refactor: enhance API documentation and improve form component structure for better readability and maintainability

common/api.ts

@@ -1,9 +1,11 @@
 import request from "/@/utils/request"
 
+// ========== 基础CRUD接口 ==========
+
 /**
- * 根据分页查询参数获取列表数据。
- * @param {Object} [query] - 查询参数。
- * @returns {Promise} 请求的 Promise 分页对象。
+ * 分页查询列表数据
+ * @param query - 查询参数对象
+ * @returns Promise<分页数据>
  */
 export function fetchList(query?: Object) {
   return request({
@@ -14,9 +16,9 @@ export function fetchList(query?: Object) {
 }
 
 /**
- * 添加一个新对象。
- * @param {Object} [obj] - 要添加的对象。
- * @returns {Promise} 请求的 Promise 对象 （true/false）。
+ * 新增数据
+ * @param obj - 要新增的数据对象
+ * @returns Promise<boolean> - 操作结果
  */
 export function addObj(obj?: Object) {
   return request({
@@ -27,9 +29,9 @@ export function addObj(obj?: Object) {
 }
 
 /**
- * 根据查询参数获取对象详情。
- * @param {Object} [obj] - 查询参数。
- * @returns {Promise} 请求的 Promise 对象数组。
+ * 获取详情数据
+ * @param obj - 查询参数对象（包含ID等）
+ * @returns Promise<数据详情>
  */
 export function getObj(obj?: Object) {
   return request({
@@ -40,9 +42,9 @@ export function getObj(obj?: Object) {
 }
 
 /**
- * 根据 ID 删除对象。
- * @param {Object} [ids] - 要删除的对象 ID。
- * @returns {Promise} 请求的 Promise 对象。
+ * 批量删除数据
+ * @param ids - 要删除的ID数组
+ * @returns Promise<操作结果>
  */
 export function delObjs(ids?: Object) {
   return request({
@@ -53,9 +55,9 @@ export function delObjs(ids?: Object) {
 }
 
 /**
- * 更新一个已存在的对象。
- * @param {Object} [obj] - 要更新的对象。
- * @returns {Promise} 请求的 Promise 对象。
+ * 更新数据
+ * @param obj - 要更新的数据对象
+ * @returns Promise<操作结果>
  */
 export function putObj(obj?: Object) {
   return request({
@@ -65,15 +67,18 @@ export function putObj(obj?: Object) {
   })
 }
 
+// ========== 工具函数 ==========
+
 /**
- * 验证某个字段的值是否已经存在。
- * @param {Object} rule - 验证规则对象。
- * @param {*} value - 要验证的值。
- * @param {Function} callback - 验证完成后的回调函数。
- * @param {boolean} isEdit - 当前操作是否为编辑。
+ * 验证字段值唯一性
+ * @param rule - 验证规则对象
+ * @param value - 要验证的值
+ * @param callback - 验证回调函数
+ * @param isEdit - 是否为编辑模式
  * 
- * 示例用法：
- * 字段名: [
+ * @example
+ * // 在表单验证规则中使用
+ * fieldName: [
  *   {
  *     validator: (rule, value, callback) => {
  *       validateExist(rule, value, callback, form.${pk.attrName} !== '');
@@ -83,10 +88,12 @@ export function putObj(obj?: Object) {
  * ]
  */
 export function validateExist(rule: any, value: any, callback: any, isEdit: boolean) {
+  // 编辑模式下跳过验证
   if (isEdit) {
     return callback();
   }
 
+  // 查询是否存在相同值
   getObj({ [rule.field]: value }).then((response) => {
     const result = response.data;
     if (result !== null && result.length > 0) {
@@ -97,13 +104,14 @@ export function validateExist(rule: any, value: any, callback: any, isEdit: bool
   });
 }
 
-
 #if($ChildClassName)
+// ========== 子表相关接口 ==========
+
 /**
-* 删除子对象。
-* @param {Object} [ids] - 要删除的子对象 ID。
-* @returns {Promise} 请求的 Promise 对象。
-*/
+ * 删除子表数据
+ * @param ids - 要删除的子表数据ID数组
+ * @returns Promise<操作结果>
+ */
 export function delChildObj(ids?: Object) {
   return request({
     url: '/${moduleName}/${functionName}/child',

common/i18n中文模板.ts

@@ -1,11 +1,17 @@
+/**
+ * ${tableComment}模块 - 中文语言包
+ */
 export default {
    ${functionName}: {
+        // 基础文本
         index: '#',
         import${className}Tip: '导入${tableComment}',
 #foreach($field in $fieldList)
+        // 字段名称
         ${field.attrName}: '#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end',
 #end
 #foreach($field in $fieldList)
+        // 输入提示
         input$str.pascalCase(${field.attrName})Tip: '请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end',
 #end
     }

common/i18n英文模板.ts

@@ -1,12 +1,18 @@
+/**
+ * ${tableComment} Module - English Language Pack
+ */
 export default {
    ${functionName}: {
+        // Basic Text
         index: '#',
-        import${className}Tip: 'import ${ClassName}',
+        import${className}Tip: 'Import ${ClassName}',
 #foreach($field in $fieldList)
+        // Field Names
         ${field.attrName}: '${field.attrName}',
 #end
 #foreach($field in $fieldList)
-        input$str.pascalCase(${field.attrName})Tip: 'input ${field.attrName}',
+        // Input Tips
+        input$str.pascalCase(${field.attrName})Tip: 'Please input ${field.attrName}',
 #end
     }
 }

multiple/主子表单.vue

@@ -216,14 +216,17 @@ const dataRules = ref({
 
 // ========== 6. 方法定义 ==========
 // 获取主子表详情数据
-const get${ClassName}Data = (id: string) => {
-  loading.value = true;
-  getObj({ ${pk.attrName}: id }).then((res: any) => {
-    // 将获取的数据赋值给表单
-    Object.assign(form, res.data[0]);
-  }).finally(() => {
+const get${ClassName}Data = async (id: string) => {
+  try {
+    loading.value = true;
+    const { data } = await getObj({ ${pk.attrName}: id });
+    // 直接将第一条数据赋值给表单
+    Object.assign(form, data[0]);
+  } catch (error) {
+    useMessage().error('获取数据失败');
+  } finally {
     loading.value = false;
-  });
+  }
 };
 
 // 打开抽屉方法

multiple/主子表格.vue

@@ -6,38 +6,60 @@
         <el-form :model="state.queryForm" ref="queryRef" :inline="true" @keyup.enter="getDataList">
 #foreach($field in $queryList)
 #if($field.queryFormType == 'select')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}">
-            <el-select v-model="state.queryForm.${field.attrName}" placeholder="请选择#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end">
-       #if($field.fieldDict)
-              <el-option :label="item.label" :value="item.value" v-for="(item, index) in ${field.fieldDict}" :key="index"></el-option>
-         #else
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-select v-model="state.queryForm.${field.attrName}" placeholder="请选择#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end">
+#if($field.fieldDict)
+              <el-option 
+                :label="item.label" 
+                :value="item.value" 
+                v-for="(item, index) in ${field.fieldDict}" 
+                :key="index">
+              </el-option>
+#else
               <el-option label="请选择">0</el-option>
-         #end
+#end
             </el-select>
-      </el-form-item>
+          </el-form-item>
 #elseif($field.queryFormType == 'date')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}">
-      <el-date-picker type="date" placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" v-model="state.queryForm.${field.attrName}"></el-date-picker>
-      </el-form-item>
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-date-picker 
+              type="date" 
+              placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+              v-model="state.queryForm.${field.attrName}">
+            </el-date-picker>
+          </el-form-item>
 #elseif($field.queryFormType == 'datetime')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}" >
-            <el-date-picker type="datetime" placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" v-model="state.queryForm.${field.attrName}"></el-date-picker>
-      </el-form-item>
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-date-picker 
+              type="datetime" 
+              placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+              v-model="state.queryForm.${field.attrName}">
+            </el-date-picker>
+          </el-form-item>
 #elseif($field.formType == 'radio')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}">
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
             <el-radio-group v-model="state.queryForm.${field.attrName}">
-      #if($field.fieldDict)
-            <el-radio :label="item.value" v-for="(item, index) in ${field.fieldDict}" border :key="index">{{ item.label }}</el-radio>
-       #else
-            <el-radio label="${field.fieldComment}" border>${field.fieldComment}</el-radio>
-       #end
+#if($field.fieldDict)
+              <el-radio 
+                :label="item.value" 
+                v-for="(item, index) in ${field.fieldDict}" 
+                border 
+                :key="index">
+                {{ item.label }}
+              </el-radio>
+#else
+              <el-radio label="${field.fieldComment}" border>${field.fieldComment}</el-radio>
+#end
             </el-radio-group>
-     </el-form-item>
+          </el-form-item>
 #else
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}" >
-        <el-input placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" v-model="state.queryForm.${field.attrName}"
-          style="max-width: 180px" />
-      </el-form-item>
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-input 
+              placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+              v-model="state.queryForm.${field.attrName}"
+              style="max-width: 180px" 
+            />
+          </el-form-item>
 #end
 #end
           <el-form-item>
@@ -51,54 +73,100 @@
 #end
       <el-row>
         <div class="mb8" style="width: 100%">
-          <el-button icon="folder-add" type="primary" class="ml10" @click="formDialogRef.openDialog()"
+          <el-button 
+            icon="folder-add" 
+            type="primary" 
+            class="ml10" 
+            @click="formDialogRef.openDialog()"
             v-auth="'${moduleName}_${functionName}_add'">
-            新 增
+            新增
           </el-button>
-          <el-button plain :disabled="multiple" icon="Delete" type="primary"
-            v-auth="'${moduleName}_${functionName}_del'" @click="handleDelete(selectObjs)">
+          <el-button 
+            plain 
+            :disabled="multiple" 
+            icon="Delete" 
+            type="primary"
+            v-auth="'${moduleName}_${functionName}_del'" 
+            @click="handleDelete(selectObjs)">
             删除
           </el-button>
-          <right-toolbar v-model:showSearch="showSearch" :export="'${moduleName}_${functionName}_export'"
-                @exportExcel="exportExcel" class="ml10 mr20" style="float: right;"
-            @queryTable="getDataList"></right-toolbar>
+          <right-toolbar 
+            v-model:showSearch="showSearch" 
+            :export="'${moduleName}_${functionName}_export'"
+            @exportExcel="exportExcel" 
+            class="ml10 mr20" 
+            style="float: right;"
+            @queryTable="getDataList">
+          </right-toolbar>
         </div>
       </el-row>
-      <el-table :data="state.dataList" v-loading="state.loading" border 
-        :cell-style="tableStyle.cellStyle" :header-cell-style="tableStyle.headerCellStyle"
-        @selection-change="selectionChangeHandle" @sort-change="sortChangeHandle">
+      <el-table 
+        :data="state.dataList" 
+        v-loading="state.loading" 
+        border 
+        :cell-style="tableStyle.cellStyle" 
+        :header-cell-style="tableStyle.headerCellStyle"
+        @selection-change="selectionChangeHandle" 
+        @sort-change="sortChangeHandle">
         <el-table-column type="selection" width="40" align="center" />
         <el-table-column type="index" label="#" width="40" />
-      #foreach($field in $gridList)
-        #if($field.fieldDict)
-          <el-table-column prop="${field.attrName}" label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" show-overflow-tooltip>
-      <template #default="scope">
-                <dict-tag :options="$field.fieldDict" :value="scope.row.${field.attrName}"></dict-tag>
-            </template>
-          </el-table-column>
-        #else
-          <el-table-column prop="${field.attrName}" label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" #if(${field.gridSort} == '1')sortable="custom"#end show-overflow-tooltip/>
-        #end
-     #end
+#foreach($field in $gridList)
+#if($field.fieldDict)
+        <el-table-column prop="${field.attrName}" label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" show-overflow-tooltip>
+          <template #default="scope">
+            <dict-tag :options="$field.fieldDict" :value="scope.row.${field.attrName}"></dict-tag>
+          </template>
+        </el-table-column>
+#else
+        <el-table-column 
+          prop="${field.attrName}" 
+          label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+#if(${field.gridSort} == '1')
+          sortable="custom" 
+#end
+          show-overflow-tooltip
+        />
+#end
+#end
         <el-table-column label="操作" width="200">
           <template #default="scope">
-          #if($ChildClassName)
-            <el-button text type="primary" icon="view" v-auth="'sys_role_edit'" @click="formDialogRef.openDialog(scope.row.${pk.attrName}, true)">
+#if($ChildClassName)
+            <el-button 
+              text 
+              type="primary" 
+              icon="view" 
+              v-auth="'${moduleName}_${functionName}_view'" 
+              @click="formDialogRef.openDialog(scope.row.${pk.attrName}, true)">
               详情
             </el-button>
-          #end
-            <el-button icon="edit-pen" text type="primary" v-auth="'${moduleName}_${functionName}_edit'"
-              @click="formDialogRef.openDialog(scope.row.${pk.attrName})">编辑</el-button>
-            <el-button icon="delete" text type="primary" v-auth="'${moduleName}_${functionName}_del'" @click="handleDelete([scope.row.${pk.attrName}])">
+#end
+            <el-button 
+              icon="edit-pen" 
+              text 
+              type="primary" 
+              v-auth="'${moduleName}_${functionName}_edit'"
+              @click="formDialogRef.openDialog(scope.row.${pk.attrName})">
+              编辑
+            </el-button>
+            <el-button 
+              icon="delete" 
+              text 
+              type="primary" 
+              v-auth="'${moduleName}_${functionName}_del'" 
+              @click="handleDelete([scope.row.${pk.attrName}])">
               删除
             </el-button>
           </template>
         </el-table-column>
       </el-table>
-      <pagination @size-change="sizeChangeHandle" @current-change="currentChangeHandle" v-bind="state.pagination" />
+      <pagination 
+        @size-change="sizeChangeHandle" 
+        @current-change="currentChangeHandle" 
+        v-bind="state.pagination" 
+      />
     </div>
 
-    <!-- 编辑、新增  -->
+    <!-- 编辑、新增 -->
     <form-dialog ref="formDialogRef" @refresh="getDataList(false)" />
   </div>
 </template>
@@ -108,40 +176,41 @@ import { BasicTableProps, useTable } from "/@/hooks/table";
 import { fetchList, delObjs } from "/@/api/${moduleName}/${functionName}";
 import { useMessage, useMessageBox } from "/@/hooks/message";
 import { useDict } from '/@/hooks/dict';
+
 // 引入组件
 const FormDialog = defineAsyncComponent(() => import('./form.vue'));
 
 // 定义查询字典
 #set($fieldDict=[])
 #foreach($field in $queryList)
-  #if($field.fieldDict)
-    #set($void=$fieldDict.add($field.fieldDict))
-  #end
+#if($field.fieldDict)
+#set($void=$fieldDict.add($field.fieldDict))
+#end
 #end
-
 #foreach($field in $gridList)
-  #if($field.fieldDict)
-    #set($void=$fieldDict.add($field.fieldDict))
-  #end
+#if($field.fieldDict)
+#set($void=$fieldDict.add($field.fieldDict))
+#end
 #end
 #if($fieldDict)
-const { $dict.format($fieldDict) } = useDict($dict.quotation($fieldDict))
+const { $dict.format($fieldDict) } = useDict($dict.quotation($fieldDict));
 #end
+
 // 定义变量内容
-const formDialogRef = ref()
+const formDialogRef = ref();
 // 搜索变量
-const queryRef = ref()
-const showSearch = ref(true)
+const queryRef = ref();
+const showSearch = ref(true);
 // 多选变量
-const selectObjs = ref([]) as any
-const multiple = ref(true)
+const selectObjs = ref([]) as any;
+const multiple = ref(true);
 
 const state: BasicTableProps = reactive<BasicTableProps>({
   queryForm: {},
   pageList: fetchList
-})
+});
 
-//  table hook
+// table hook
 const {
   getDataList,
   currentChangeHandle,
@@ -149,21 +218,21 @@ const {
   sortChangeHandle,
   downBlobFile,
   tableStyle
-} = useTable(state)
+} = useTable(state);
 
 // 清空搜索条件
 const resetQuery = () => {
   // 清空搜索条件
-  queryRef.value?.resetFields()
+  queryRef.value?.resetFields();
   // 清空多选
-  selectObjs.value = []
-  getDataList()
-}
+  selectObjs.value = [];
+  getDataList();
+};
 
 // 导出excel
 const exportExcel = () => {
-  downBlobFile('/${moduleName}/${functionName}/export', Object.assign(state.queryForm, { ids: selectObjs }), '${functionName}.xlsx')
-}
+  downBlobFile('/${moduleName}/${functionName}/export', Object.assign(state.queryForm, { ids: selectObjs }), '${functionName}.xlsx');
+};
 
 // 多选事件
 const selectionChangeHandle = (objs: { $pk.attrName: string }[]) => {

single/表单.vue

@@ -181,14 +181,17 @@ const dataRules = ref({
 
 // ========== 6. 方法定义 ==========
 // 获取详情数据
-const get${ClassName}Data = (id: string) => {
-  loading.value = true;
-  getObj({ ${pk.attrName}: id }).then((res: any) => {
-    // 将获取的数据赋值给表单
-    Object.assign(form, res.data[0]);
-  }).finally(() => {
+const get${ClassName}Data = async (id: string) => {
+  try {
+    loading.value = true;
+    const { data } = await getObj({ ${pk.attrName}: id });
+    // 直接将第一条数据赋值给表单
+    Object.assign(form, data[0]);
+  } catch (error) {
+    useMessage().error('获取数据失败');
+  } finally {
     loading.value = false;
-  });
+  }
 };
 
 // 打开弹窗方法

single/表格.vue

@@ -2,183 +2,290 @@
   <div class="layout-padding">
     <div class="layout-padding-auto layout-padding-view">
 #if($queryList)
+      <!-- 查询表单区域 -->
       <el-row v-show="showSearch">
         <el-form :model="state.queryForm" ref="queryRef" :inline="true" @keyup.enter="getDataList">
 #foreach($field in $queryList)
 #if($field.queryFormType == 'select')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}">
-            <el-select v-model="state.queryForm.${field.attrName}" placeholder="请选择#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end">
-       #if($field.fieldDict)
-              <el-option :label="item.label" :value="item.value" v-for="(item, index) in ${field.fieldDict}" :key="index"></el-option>
-         #else
-              <el-option label="请选择">0</el-option>
-         #end
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-select v-model="state.queryForm.${field.attrName}" placeholder="请选择#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end">
+#if($field.fieldDict)
+              <el-option 
+                :label="item.label" 
+                :value="item.value" 
+                v-for="(item, index) in ${field.fieldDict}" 
+                :key="index"
+              />
+#else
+              <el-option label="请选择" value="0" />
+#end
             </el-select>
-      </el-form-item>
+          </el-form-item>
 #elseif($field.queryFormType == 'date')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}">
-      <el-date-picker type="date" placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" v-model="state.queryForm.${field.attrName}"></el-date-picker>
-      </el-form-item>
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-date-picker 
+              type="date" 
+              placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+              v-model="state.queryForm.${field.attrName}"
+            />
+          </el-form-item>
 #elseif($field.queryFormType == 'datetime')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}" >
-            <el-date-picker type="datetime" placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" v-model="state.queryForm.${field.attrName}"></el-date-picker>
-      </el-form-item>
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-date-picker 
+              type="datetime" 
+              placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+              v-model="state.queryForm.${field.attrName}"
+            />
+          </el-form-item>
 #elseif($field.formType == 'radio')
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}">
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
             <el-radio-group v-model="state.queryForm.${field.attrName}">
-     #if($field.fieldDict)
-             <el-radio :label="item.value" v-for="(item, index) in ${field.fieldDict}" border :key="index">{{ item.label }}
-            </el-radio>
-       #else
-           <el-radio label="${field.fieldComment}" border>${field.fieldComment}</el-radio>
-       #end
+#if($field.fieldDict)
+              <el-radio 
+                :label="item.value" 
+                v-for="(item, index) in ${field.fieldDict}" 
+                border 
+                :key="index"
+              >
+                {{ item.label }}
+              </el-radio>
+#else
+              <el-radio label="${field.fieldComment}" border>
+                ${field.fieldComment}
+              </el-radio>
+#end
             </el-radio-group>
-     </el-form-item>
+          </el-form-item>
 #else
-      <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" prop="${field.attrName}" >
-        <el-input placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" v-model="state.queryForm.${field.attrName}" />
-      </el-form-item>
+          <el-form-item label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" prop="${field.attrName}">
+            <el-input 
+              placeholder="请输入#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+              v-model="state.queryForm.${field.attrName}" 
+            />
+          </el-form-item>
 #end
 #end
           <el-form-item>
             <el-button icon="search" type="primary" @click="getDataList">
-              查 询
+              查询
             </el-button>
-            <el-button icon="Refresh" @click="resetQuery">重 置</el-button>
+            <el-button icon="Refresh" @click="resetQuery">重置</el-button>
           </el-form-item>
         </el-form>
       </el-row>
 #end
+
+      <!-- 操作按钮区域 -->
       <el-row>
         <div class="mb8" style="width: 100%">
-          <el-button icon="folder-add" type="primary" class="ml10" @click="formDialogRef.openDialog()"
-            v-auth="'${moduleName}_${functionName}_add'">
-            新 增
+          <el-button 
+            icon="folder-add" 
+            type="primary" 
+            class="ml10" 
+            @click="formDialogRef.openDialog()"
+            v-auth="'${moduleName}_${functionName}_add'"
+          >
+            新增
           </el-button>
-          <el-button plain icon="upload-filled" type="primary" class="ml10" @click="excelUploadRef.show()" v-auth="'sys_user_add'">
-						导 入
-					</el-button>
-          <el-button plain :disabled="multiple" icon="Delete" type="primary"
-            v-auth="'${moduleName}_${functionName}_del'" @click="handleDelete(selectObjs)">
-            删 除
+          <el-button 
+            plain 
+            icon="upload-filled" 
+            type="primary" 
+            class="ml10" 
+            @click="excelUploadRef.show()" 
+            v-auth="'${moduleName}_${functionName}_add'"
+          >
+            导入
           </el-button>
-          <right-toolbar v-model:showSearch="showSearch" :export="'${moduleName}_${functionName}_export'"
-                @exportExcel="exportExcel" class="ml10 mr20" style="float: right;"
-            @queryTable="getDataList"></right-toolbar>
+          <el-button 
+            plain 
+            :disabled="multiple" 
+            icon="Delete" 
+            type="primary"
+            v-auth="'${moduleName}_${functionName}_del'" 
+            @click="handleDelete(selectObjs)"
+          >
+            删除
+          </el-button>
+          <right-toolbar 
+            v-model:showSearch="showSearch" 
+            :export="'${moduleName}_${functionName}_export'"
+            @exportExcel="exportExcel" 
+            class="ml10 mr20" 
+            style="float: right;"
+            @queryTable="getDataList"
+          />
         </div>
       </el-row>
-      <el-table :data="state.dataList" v-loading="state.loading" border 
-        :cell-style="tableStyle.cellStyle" :header-cell-style="tableStyle.headerCellStyle"
-				@selection-change="selectionChangHandle"
-        @sort-change="sortChangeHandle">
+
+      <!-- 数据表格区域 -->
+      <el-table 
+        :data="state.dataList" 
+        v-loading="state.loading" 
+        border 
+        :cell-style="tableStyle.cellStyle" 
+        :header-cell-style="tableStyle.headerCellStyle"
+        @selection-change="selectionChangHandle"
+        @sort-change="sortChangeHandle"
+      >
         <el-table-column type="selection" width="40" align="center" />
         <el-table-column type="index" label="#" width="40" />
-      #foreach($field in $gridList)
-        #if($field.fieldDict)
-          <el-table-column prop="${field.attrName}" label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" show-overflow-tooltip>
-      <template #default="scope">
-                <dict-tag :options="$field.fieldDict" :value="scope.row.${field.attrName}"></dict-tag>
-            </template>
-          </el-table-column>
-        #else
-          <el-table-column prop="${field.attrName}" label="#if(${field.fieldComment})${field.fieldComment}#else ${field.attrName}#end" #if(${field.gridSort} == '1')sortable="custom"#end show-overflow-tooltip/>
-        #end
-     #end
+#foreach($field in $gridList)
+#if($field.fieldDict)
+        <el-table-column prop="${field.attrName}" label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" show-overflow-tooltip>
+          <template #default="scope">
+            <dict-tag :options="$field.fieldDict" :value="scope.row.${field.attrName}" />
+          </template>
+        </el-table-column>
+#else
+        <el-table-column 
+          prop="${field.attrName}" 
+          label="#if(${field.fieldComment})${field.fieldComment}#else${field.attrName}#end" 
+#if(${field.gridSort} == '1')
+          sortable="custom" 
+#end
+          show-overflow-tooltip
+        />
+#end
+#end
         <el-table-column label="操作" width="150">
           <template #default="scope">
-            <el-button icon="edit-pen" text type="primary" v-auth="'${moduleName}_${functionName}_edit'"
-              @click="formDialogRef.openDialog(scope.row.${pk.attrName})">编辑</el-button>
-            <el-button icon="delete" text type="primary" v-auth="'${moduleName}_${functionName}_del'" @click="handleDelete([scope.row.${pk.attrName}])">删除</el-button>
+            <el-button 
+              icon="edit-pen" 
+              text 
+              type="primary" 
+              v-auth="'${moduleName}_${functionName}_edit'"
+              @click="formDialogRef.openDialog(scope.row.${pk.attrName})"
+            >
+              编辑
+            </el-button>
+            <el-button 
+              icon="delete" 
+              text 
+              type="primary" 
+              v-auth="'${moduleName}_${functionName}_del'" 
+              @click="handleDelete([scope.row.${pk.attrName}])"
+            >
+              删除
+            </el-button>
           </template>
         </el-table-column>
       </el-table>
-      <pagination @size-change="sizeChangeHandle" @current-change="currentChangeHandle" v-bind="state.pagination" />
+
+      <!-- 分页组件 -->
+      <pagination 
+        @size-change="sizeChangeHandle" 
+        @current-change="currentChangeHandle" 
+        v-bind="state.pagination" 
+      />
     </div>
 
-    <!-- 编辑、新增  -->
+    <!-- 编辑、新增弹窗 -->
     <form-dialog ref="formDialogRef" @refresh="getDataList(false)" />
 
-    <!-- 导入excel (需要在 upms-biz/resources/file 下维护模板) -->
+    <!-- 导入excel弹窗 (需要在 upms-biz/resources/file 下维护模板) -->
     <upload-excel
-			ref="excelUploadRef"
-			title="导入"
-			url="/${moduleName}/${functionName}/import"
+      ref="excelUploadRef"
+      title="导入"
+      url="/${moduleName}/${functionName}/import"
       temp-url="/admin/sys-file/local/file/${functionName}.xlsx"
-			@refreshDataList="getDataList"
-		/>
+      @refreshDataList="getDataList"
+    />
   </div>
 </template>
 
 <script setup lang="ts" name="system${ClassName}">
+// ========== 导入声明 ==========
 import { BasicTableProps, useTable } from "/@/hooks/table";
 import { fetchList, delObjs } from "/@/api/${moduleName}/${functionName}";
 import { useMessage, useMessageBox } from "/@/hooks/message";
 import { useDict } from '/@/hooks/dict';
 
-// 引入组件
+// ========== 组件声明 ==========
+// 异步加载表单弹窗组件
 const FormDialog = defineAsyncComponent(() => import('./form.vue'));
-// 定义查询字典
+
+// ========== 字典数据 ==========
 #set($fieldDict=[])
 #foreach($field in $queryList)
-  #if($field.fieldDict)
-    #set($void=$fieldDict.add($field.fieldDict))
-  #end
+#if($field.fieldDict)
+#set($void=$fieldDict.add($field.fieldDict))
+#end
 #end
-
 #foreach($field in $gridList)
-  #if($field.fieldDict)
-    #set($void=$fieldDict.add($field.fieldDict))
-  #end
+#if($field.fieldDict)
+#set($void=$fieldDict.add($field.fieldDict))
+#end
 #end
 #if($fieldDict)
-const { $dict.format($fieldDict) } = useDict($dict.quotation($fieldDict))
+// 加载字典数据
+const { $dict.format($fieldDict) } = useDict($dict.quotation($fieldDict));
 #end
-// 定义变量内容
-const formDialogRef = ref()
-const excelUploadRef = ref();
-// 搜索变量
-const queryRef = ref()
-const showSearch = ref(true)
-// 多选变量
-const selectObjs = ref([]) as any
-const multiple = ref(true)
 
+// ========== 组件引用 ==========
+const formDialogRef = ref();          // 表单弹窗引用
+const excelUploadRef = ref();         // Excel上传弹窗引用
+const queryRef = ref();               // 查询表单引用
+
+// ========== 响应式数据 ==========
+const showSearch = ref(true);         // 是否显示搜索区域
+const selectObjs = ref([]) as any;    // 表格多选数据
+const multiple = ref(true);           // 是否多选
+
+// ========== 表格状态 ==========
 const state: BasicTableProps = reactive<BasicTableProps>({
-  queryForm: {},
-  pageList: fetchList
-})
+  queryForm: {},    // 查询参数
+  pageList: fetchList // 分页查询方法
+});
 
-//  table hook
+// ========== Hook引用 ==========
+// 表格相关Hook
 const {
   getDataList,
   currentChangeHandle,
   sizeChangeHandle,
   sortChangeHandle,
   downBlobFile,
-	tableStyle
-} = useTable(state)
+  tableStyle
+} = useTable(state);
 
-// 清空搜索条件
+// ========== 方法定义 ==========
+/**
+ * 重置查询条件
+ */
 const resetQuery = () => {
   // 清空搜索条件
-  queryRef.value?.resetFields()
+  queryRef.value?.resetFields();
   // 清空多选
-  selectObjs.value = []
-  getDataList()
-}
+  selectObjs.value = [];
+  // 重新查询
+  getDataList();
+};
 
-// 导出excel
+/**
+ * 导出Excel文件
+ */
 const exportExcel = () => {
-  downBlobFile('/${moduleName}/${functionName}/export', Object.assign(state.queryForm, { ids: selectObjs }), '${functionName}.xlsx')
-}
+  downBlobFile(
+    '/${moduleName}/${functionName}/export',
+    Object.assign(state.queryForm, { ids: selectObjs }),
+    '${functionName}.xlsx'
+  );
+};
 
-// 多选事件
+/**
+ * 表格多选事件处理
+ * @param objs 选中的数据行
+ */
 const selectionChangHandle = (objs: { $pk.attrName: string }[]) => {
   selectObjs.value = objs.map(({ $pk.attrName }) => $pk.attrName);
   multiple.value = !objs.length;
 };
 
-// 删除操作
+/**
+ * 删除数据处理
+ * @param ids 要删除的数据ID数组
+ */
 const handleDelete = async (ids: string[]) => {
   try {
     await useMessageBox().confirm('此操作将永久删除');