worsoft-frontend-codegen-local-mcp 0.1.64 → 0.1.66

package/assets/templates/master_child_jump/api.tpl

@@ -1,48 +1,7 @@
-// 请求工具
-import request from '/@/utils/request';
+// 通用 CRUD 接口工厂
+import { createCrudApi } from '/@/api/common/crudFactory';
+{{API_REQUEST_IMPORT}}
 
-// 查询分页列表
-export function fetchList(query?: object) {
-  return request({
-    url: '/{{API_PATH}}/page',
-    method: 'get',
-    params: query,
-  });
-}
-
-// 新增数据
-export function addObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}/save',
-    method: 'post',
-    data: obj,
-  });
-}
-
-// 查询详情数据
-export function getObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}/getById',
-    method: 'get',
-    params: obj,
-  });
-}
-
-// 删除数据
-export function delObjs(ids?: object) {
-  return request({
-    url: '/{{API_PATH}}/removeByIds',
-    method: 'post',
-    data: ids,
-  });
-}
-
-// 更新数据
-export function putObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}/updateById',
-    method: 'post',
-    data: obj,
-  });
-}
+// {{FEATURE_TITLE}} 通用列表、新增、详情、删除、更新接口
+export const { fetchList, addObj, getObj, delObjs, putObj } = createCrudApi('/{{API_PATH}}');
 {{EXTRA_API_FUNCTIONS}}

package/assets/templates/master_child_jump/form.tpl

@@ -1,9 +1,13 @@
 <template>
+  <!-- 页面布局：{{FEATURE_TITLE}}主子表表单页 -->
   <div class="layout-padding-auto layout-padding-view">
+    <!-- 表单卡片：承载标题、操作按钮、主表字段和子表明细 -->
     <el-card shadow="never" class="w100">
       <template #header>
+        <!-- 表单页头：根据新增、编辑、详情模式展示标题和按钮 -->
         <div style="display: flex; justify-content: space-between; align-items: center;">
           <span style="font-size: 16px; font-weight: bold;">{{ form.{{PK_ATTR}} ? (detail ? t('common.viewBtn') : t('common.editBtn')) : t('common.addBtn') }}</span>
+          <!-- 编辑模式操作按钮：保存、流转、提交、取消 -->
           <div v-if="!detail">
             <el-button @click="onSubmit('save')" :disabled="loading" icon="document">{{ commonActionLabel('save') }}</el-button>
             <el-button @click="onSubmit('flow')" :disabled="loading" plain type="success" icon="position">{{ commonActionLabel('flow') }}</el-button>
@@ -11,15 +15,19 @@
             <el-divider direction="vertical" />
             <el-button @click="handleBack" icon="close">{{ t('common.cancelButtonText') }}</el-button>
           </div>
+          <!-- 详情模式操作按钮：返回列表页 -->
           <div v-else>
             <el-button @click="handleBack" icon="back">{{ commonActionLabel('back') }}</el-button>
           </div>
         </div>
       </template>
+      <!-- 主子表表单：按 PRD 表单显隐和顺序渲染字段 -->
       <el-form ref="dataFormRef" :model="form" :rules="dataRules" :disabled="detail" v-loading="loading">
+        <!-- 主表字段区：字段级注释由 MCP 根据字段名称生成 -->
         <el-row :gutter="24">
 {{FORM_FIELDS}}
         </el-row>
+        <!-- 子表明细区：按 children 配置渲染多个子表 -->
         <el-row :gutter="24">
 {{CHILD_SECTIONS}}
         </el-row>

package/assets/templates/master_child_jump/index.tpl

@@ -1,7 +1,9 @@
 <!-- 功能名称：{{FEATURE_TITLE}} -->
 <template>
+  <!-- 页面布局：{{FEATURE_TITLE}}列表页 -->
   <div class="layout-padding">
     <div class="layout-padding-auto layout-padding-view flex h-full flex-col">
+      <!-- 列表工具栏：搜索、新增、导入、批量删除、导出、刷新 -->
       <SchemaListToolbar
         v-bind="toolbarProps"
         @update:keyword="state.queryForm.smartVal = $event"
@@ -15,6 +17,7 @@
         @refresh="handleToolbarRefresh"
       />
 
+      <!-- 列表表格：展示{{FEATURE_TITLE}}列表数据、分页、排序和行操作 -->
       <SchemaListTable
         v-bind="tableProps"
         row-id-key="{{PK_ATTR}}"
@@ -23,16 +26,23 @@
         @size-change="handleTableSizeChange"
         @current-change="handleTableCurrentChange"
       >
+        <!-- 行操作按钮：查看、编辑、提交、流转、删除 -->
         <template #actions="{ row }">
+          <!-- 查看{{FEATURE_TITLE}}详情 -->
           <el-button text type="primary" icon="view" v-auth="'{{PERMISSION_PREFIX}}_view'" @click="handleDetail(row.{{PK_ATTR}})">{{ t('common.viewBtn') }}</el-button>
+          <!-- 编辑{{FEATURE_TITLE}}：业务单据编辑态控制按需生效 -->
           <el-button{{BUSINESS_EDIT_IF}} icon="edit-pen" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_edit'" @click="handleEdit(row.{{PK_ATTR}})">{{ t('common.editBtn') }}</el-button>
+          <!-- 提交{{FEATURE_TITLE}} -->
           <el-button text type="primary" icon="check" @click="handleQuickAction(row, 'submit')">{{ commonActionLabel('submit') }}</el-button>
+          <!-- 流转{{FEATURE_TITLE}} -->
           <el-button text type="success" icon="position" @click="handleQuickAction(row, 'flow')">{{ commonActionLabel('flow') }}</el-button>
+          <!-- 删除{{FEATURE_TITLE}} -->
           <el-button icon="delete" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_del'" @click="handleDelete([row.{{PK_ATTR}}])">{{ t('common.delBtn') }}</el-button>
         </template>
       </SchemaListTable>
     </div>
 
+    <!-- Excel 导入组件：导入{{FEATURE_TITLE}}列表数据 -->
     <upload-excel ref="excelUploadRef" :title="t('common.importBtn')" url="/{{API_PATH}}/import" temp-url="/admin/sys-file/local/file/{{FUNCTION_NAME}}.xlsx" @refreshDataList="getDataList" />
   </div>
 </template>

package/assets/templates/master_child_jump/menu.sql.tpl

@@ -5,6 +5,10 @@
 insert into sys_menu (menu_id, parent_id, path, permission, menu_type, icon, del_flag, create_time, sort_order, update_time, name, tenant_id)
 values ({{MENU_BASE_ID}}, '-1', '/{{MENU_ROUTE_PATH}}/index', '', '0', 'icon-bangzhushouji', '0', null, '8', null, '{{TABLE_COMMENT}}管理', 1);
 
+-- Form route SQL for jump-based pages. Hidden from sidebar, used by list page add/edit/view navigation.
+insert into sys_menu (menu_id, parent_id, path, permission, menu_type, icon, visible, del_flag, create_time, sort_order, update_time, name, tenant_id)
+values ({{MENU_BASE_ID_PLUS_6}}, {{MENU_BASE_ID}}, '/{{MENU_ROUTE_PATH}}/form', '', '0', 'icon-biaodan', '0', '0', null, '9', null, '{{TABLE_COMMENT}}表单', 1);
+
 insert into sys_menu (menu_id, parent_id, permission, menu_type, path, icon, del_flag, create_time, sort_order, update_time, name, tenant_id)
 values ({{MENU_BASE_ID_PLUS_1}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_view', '1', null, '1', '0', null, '0', null, '{{TABLE_COMMENT}}查看', 1);
 
@@ -18,4 +22,4 @@ insert into sys_menu (menu_id, parent_id, permission, menu_type, path, icon, del
 values ({{MENU_BASE_ID_PLUS_4}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_del', '1', null, '1', '0', null, '3', null, '{{TABLE_COMMENT}}删除', 1);
 
 insert into sys_menu (menu_id, parent_id, permission, menu_type, path, icon, del_flag, create_time, sort_order, update_time, name, tenant_id)
-values ({{MENU_BASE_ID_PLUS_5}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_export', '1', null, '1', '0', null, '4', null, '导入导出', 1);
+values ({{MENU_BASE_ID_PLUS_5}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_export', '1', null, '1', '0', null, '4', null, '导入导出', 1);

package/assets/templates/single_table_dialog/api.tpl

@@ -1,50 +1,9 @@
-// 请求工具
-import request from '/@/utils/request';
+// 通用 CRUD 接口工厂
+import { createCrudApi } from '/@/api/common/crudFactory';
+{{API_REQUEST_IMPORT}}
 
-// 查询分页列表
-export function fetchList(query?: object) {
-  return request({
-    url: '/{{API_PATH}}/page',
-    method: 'get',
-    params: query,
-  });
-}
-
-// 新增数据
-export function addObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}',
-    method: 'post',
-    data: obj,
-  });
-}
-
-// 查询详情数据
-export function getObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}/details',
-    method: 'get',
-    params: obj,
-  });
-}
-
-// 删除数据
-export function delObjs(ids?: object) {
-  return request({
-    url: '/{{API_PATH}}',
-    method: 'delete',
-    data: ids,
-  });
-}
-
-// 更新数据
-export function putObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}',
-    method: 'put',
-    data: obj,
-  });
-}
+// {{FEATURE_TITLE}} 通用列表、新增、详情、删除、更新接口
+export const { fetchList, addObj, getObj, delObjs, putObj } = createCrudApi('/{{API_PATH}}');
 
 {{DICT_API_FUNCTIONS}}
 {{EXTRA_API_FUNCTIONS}}

package/assets/templates/single_table_dialog/form.tpl

@@ -1,10 +1,14 @@
 <template>
+  <!-- 表单弹窗：新增或编辑{{FEATURE_TITLE}}数据 -->
   <el-dialog v-model="visible" :title="form.{{PK_ATTR}} ? t('common.editBtn') : t('common.addBtn')" :close-on-click-modal="false" draggable>
+    <!-- 弹窗表单：按 PRD 表单显隐和顺序渲染字段 -->
     <el-form ref="dataFormRef" :model="form" :rules="dataRules" label-width="100px" v-loading="loading">
+      <!-- 主表字段区：字段级注释由 MCP 根据字段名称生成 -->
       <el-row :gutter="24">
 {{FORM_FIELDS}}
       </el-row>
     </el-form>
+    <!-- 弹窗底部操作按钮：取消和确认提交 -->
     <template #footer>
       <span class="dialog-footer">
         <el-button @click="visible = false">{{ t('common.cancelButtonText') }}</el-button>

package/assets/templates/single_table_dialog/index.tpl

@@ -1,7 +1,9 @@
 <!-- 功能名称：{{FEATURE_TITLE}} -->
 <template>
+  <!-- 页面布局：{{FEATURE_TITLE}}列表页 -->
   <div class="layout-padding">
     <div class="layout-padding-auto layout-padding-view flex h-full flex-col">
+      <!-- 列表工具栏：搜索、新增、导入、批量删除、导出、刷新 -->
       <SchemaListToolbar
         v-bind="toolbarProps"
         @update:keyword="state.queryForm.smartVal = $event"
@@ -15,6 +17,7 @@
         @refresh="handleToolbarRefresh"
       />
 
+      <!-- 列表表格：展示{{FEATURE_TITLE}}列表数据、分页、排序和行操作 -->
       <SchemaListTable
         v-bind="tableProps"
         row-id-key="{{PK_ATTR}}"
@@ -24,13 +27,16 @@
         @size-change="handleTableSizeChange"
         @current-change="handleTableCurrentChange"
       >
+        <!-- 行操作按钮：编辑、删除、启用、禁用 -->
         <template #actions="{ row }">
 {{LIST_ACTIONS}}
         </template>
       </SchemaListTable>
     </div>
 
+    <!-- 表单弹窗组件：新增和编辑{{FEATURE_TITLE}}数据 -->
     <form-dialog ref="formDialogRef" @refresh="getDataList(false)" />
+    <!-- Excel 导入组件：导入{{FEATURE_TITLE}}列表数据 -->
     <upload-excel ref="excelUploadRef" :title="t('common.importBtn')" url="/{{API_PATH}}/import" temp-url="/admin/sys-file/local/file/{{FUNCTION_NAME}}.xlsx" @refreshDataList="getDataList" />
   </div>
 </template>

package/assets/templates/single_table_jump/api.tpl

@@ -1,48 +1,7 @@
-// 请求工具
-import request from '/@/utils/request';
+// 通用 CRUD 接口工厂
+import { createCrudApi } from '/@/api/common/crudFactory';
+{{API_REQUEST_IMPORT}}
 
-// 查询分页列表
-export function fetchList(query?: object) {
-  return request({
-    url: '/{{API_PATH}}/page',
-    method: 'get',
-    params: query,
-  });
-}
-
-// 新增数据
-export function addObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}',
-    method: 'post',
-    data: obj,
-  });
-}
-
-// 查询详情数据
-export function getObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}/details',
-    method: 'get',
-    params: obj,
-  });
-}
-
-// 删除数据
-export function delObjs(ids?: object) {
-  return request({
-    url: '/{{API_PATH}}',
-    method: 'delete',
-    data: ids,
-  });
-}
-
-// 更新数据
-export function putObj(obj?: object) {
-  return request({
-    url: '/{{API_PATH}}',
-    method: 'put',
-    data: obj,
-  });
-}
+// {{FEATURE_TITLE}} 通用列表、新增、详情、删除、更新接口
+export const { fetchList, addObj, getObj, delObjs, putObj } = createCrudApi('/{{API_PATH}}');
 {{EXTRA_API_FUNCTIONS}}

package/assets/templates/single_table_jump/form.tpl

@@ -1,9 +1,13 @@
 <template>
+  <!-- 页面布局：{{FEATURE_TITLE}}表单页 -->
   <div class="layout-padding-auto layout-padding-view">
+    <!-- 表单卡片：承载标题、操作按钮和主表字段 -->
     <el-card shadow="never" class="w100">
       <template #header>
+        <!-- 表单页头：根据新增、编辑、详情模式展示标题和按钮 -->
         <div style="display: flex; justify-content: space-between; align-items: center;">
           <span style="font-size: 16px; font-weight: bold;">{{ form.{{PK_ATTR}} ? (detail ? t('common.viewBtn') : t('common.editBtn')) : t('common.addBtn') }}</span>
+          <!-- 编辑模式操作按钮：保存、流转、提交、取消 -->
           <div v-if="!detail">
             <el-button @click="onSubmit('save')" :disabled="loading" icon="document">{{ commonActionLabel('save') }}</el-button>
             <el-button @click="onSubmit('flow')" :disabled="loading" plain type="success" icon="position">{{ commonActionLabel('flow') }}</el-button>
@@ -11,12 +15,15 @@
             <el-divider direction="vertical" />
             <el-button @click="handleBack" icon="close">{{ t('common.cancelButtonText') }}</el-button>
           </div>
+          <!-- 详情模式操作按钮：返回列表页 -->
           <div v-else>
             <el-button @click="handleBack" icon="back">{{ commonActionLabel('back') }}</el-button>
           </div>
         </div>
       </template>
+      <!-- 主表表单：按 PRD 表单显隐和顺序渲染字段 -->
       <el-form ref="dataFormRef" :model="form" :rules="dataRules" :disabled="detail" v-loading="loading">
+        <!-- 主表字段区：字段级注释由 MCP 根据字段名称生成 -->
         <el-row :gutter="24">
 {{FORM_FIELDS}}
         </el-row>

package/assets/templates/single_table_jump/index.tpl

@@ -1,7 +1,9 @@
 <!-- 功能名称：{{FEATURE_TITLE}} -->
 <template>
+  <!-- 页面布局：{{FEATURE_TITLE}}列表页 -->
   <div class="layout-padding">
     <div class="layout-padding-auto layout-padding-view flex h-full flex-col">
+      <!-- 列表工具栏：搜索、新增、导入、批量删除、导出、刷新 -->
       <SchemaListToolbar
         v-bind="toolbarProps"
         @update:keyword="state.queryForm.smartVal = $event"
@@ -15,6 +17,7 @@
         @refresh="handleToolbarRefresh"
       />
 
+      <!-- 列表表格：展示{{FEATURE_TITLE}}列表数据、分页、排序和行操作 -->
       <SchemaListTable
         v-bind="tableProps"
         row-id-key="{{PK_ATTR}}"
@@ -24,14 +27,19 @@
         @size-change="handleTableSizeChange"
         @current-change="handleTableCurrentChange"
       >
+        <!-- 行操作按钮：查看、编辑、删除 -->
         <template #actions="{ row }">
+          <!-- 查看{{FEATURE_TITLE}}详情 -->
           <el-button text type="primary" icon="view" v-auth="'{{PERMISSION_PREFIX}}_view'" @click="handleDetail(row.{{PK_ATTR}})">{{ t('common.viewBtn') }}</el-button>
+          <!-- 编辑{{FEATURE_TITLE}}：业务单据编辑态控制按需生效 -->
           <el-button{{BUSINESS_EDIT_IF}} icon="edit-pen" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_edit'" @click="handleEdit(row.{{PK_ATTR}})">{{ t('common.editBtn') }}</el-button>
+          <!-- 删除{{FEATURE_TITLE}} -->
           <el-button icon="delete" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_del'" @click="handleDelete([row.{{PK_ATTR}}])">{{ t('common.delBtn') }}</el-button>
         </template>
       </SchemaListTable>
     </div>
 
+    <!-- Excel 导入组件：导入{{FEATURE_TITLE}}列表数据 -->
     <upload-excel ref="excelUploadRef" :title="t('common.importBtn')" url="/{{API_PATH}}/import" temp-url="/admin/sys-file/local/file/{{FUNCTION_NAME}}.xlsx" @refreshDataList="getDataList" />
   </div>
 </template>

package/assets/templates/single_table_jump/menu.sql.tpl

@@ -5,6 +5,10 @@
 insert into sys_menu (menu_id, parent_id, path, permission, menu_type, icon, del_flag, create_time, sort_order, update_time, name, tenant_id)
 values ({{MENU_BASE_ID}}, '-1', '/{{MENU_ROUTE_PATH}}/index', '', '0', 'icon-bangzhushouji', '0', null, '8', null, '{{TABLE_COMMENT}}管理', 1);
 
+-- Form route SQL for jump-based pages. Hidden from sidebar, used by list page add/edit/view navigation.
+insert into sys_menu (menu_id, parent_id, path, permission, menu_type, icon, visible, del_flag, create_time, sort_order, update_time, name, tenant_id)
+values ({{MENU_BASE_ID_PLUS_6}}, {{MENU_BASE_ID}}, '/{{MENU_ROUTE_PATH}}/form', '', '0', 'icon-biaodan', '0', '0', null, '9', null, '{{TABLE_COMMENT}}表单', 1);
+
 insert into sys_menu (menu_id, parent_id, permission, menu_type, path, icon, del_flag, create_time, sort_order, update_time, name, tenant_id)
 values ({{MENU_BASE_ID_PLUS_1}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_view', '1', null, '1', '0', null, '0', null, '{{TABLE_COMMENT}}查看', 1);
 
@@ -18,4 +22,4 @@ insert into sys_menu (menu_id, parent_id, permission, menu_type, path, icon, del
 values ({{MENU_BASE_ID_PLUS_4}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_del', '1', null, '1', '0', null, '3', null, '{{TABLE_COMMENT}}删除', 1);
 
 insert into sys_menu (menu_id, parent_id, permission, menu_type, path, icon, del_flag, create_time, sort_order, update_time, name, tenant_id)
-values ({{MENU_BASE_ID_PLUS_5}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_export', '1', null, '1', '0', null, '4', null, '导入导出', 1);
+values ({{MENU_BASE_ID_PLUS_5}}, {{MENU_BASE_ID}}, '{{PERMISSION_PREFIX}}_export', '1', null, '1', '0', null, '4', null, '导入导出', 1);

package/mcp_server.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 const path = require('path');
 
 const SERVER_NAME = 'worsoft-codegen-local';
-const SERVER_VERSION = '0.1.64';
+const SERVER_VERSION = '0.1.66';
 const PROTOCOL_VERSION = '2024-11-05';
 const TOOL_NAME = 'worsoft_codegen_local_generate_frontend';
 const STYLE_CATALOG_PATH = path.join(__dirname, 'assets', 'style-catalog.json');
@@ -146,10 +146,65 @@ export function createCrudSchema(
   }
 
   return buildSchema(masterOrDefinition as Record<string, FieldMeta>, children);
-}
-`;
-
-const TOOL_SCHEMA = {
+}
+`;
+
+const DEFAULT_CRUD_FACTORY_TEMPLATE = `import request from '/@/utils/request';
+
+export interface CrudApiPathOverrides {
+  page?: string;
+  save?: string;
+  detail?: string;
+  remove?: string;
+  update?: string;
+}
+
+const joinApiPath = (baseUrl: string, suffix: string) => {
+  const normalizedBase = String(baseUrl || '').replace(/\\/+$/, '');
+  const normalizedSuffix = String(suffix || '').replace(/^\\/+/, '');
+  return normalizedSuffix ? \`\${normalizedBase}/\${normalizedSuffix}\` : normalizedBase;
+};
+
+// 生成标准业务功能 CRUD 接口：分页、新增、详情、删除、更新。
+export const createCrudApi = (baseUrl: string, overrides: CrudApiPathOverrides = {}) => ({
+  fetchList: (query?: object) =>
+    request({
+      url: overrides.page || joinApiPath(baseUrl, 'page'),
+      method: 'get',
+      params: query,
+    }),
+
+  addObj: (obj?: object) =>
+    request({
+      url: overrides.save || joinApiPath(baseUrl, 'save'),
+      method: 'post',
+      data: obj,
+    }),
+
+  getObj: (obj?: object) =>
+    request({
+      url: overrides.detail || joinApiPath(baseUrl, 'getById'),
+      method: 'get',
+      params: obj,
+    }),
+
+  delObjs: (ids?: object) =>
+    request({
+      url: overrides.remove || joinApiPath(baseUrl, 'removeByIds'),
+      method: 'post',
+      data: ids,
+    }),
+
+  putObj: (obj?: object) =>
+    request({
+      url: overrides.update || joinApiPath(baseUrl, 'updateById'),
+      method: 'post',
+      data: obj,
+    }),
+});
+`;
+
+const TOOL_SCHEMA = {
   type: 'object',
   properties: {
     featureTitle: { type: 'string', description: 'Feature title from pre-parsed structured metadata.' },
@@ -340,11 +395,11 @@ const TOOL_SCHEMA = {
     },
     writeToDisk: { type: 'boolean', default: true, description: 'Whether to write generated files.' },
     overwrite: { type: 'boolean', default: true, description: 'Whether to overwrite existing files. If false, existing files are skipped.' },
-    writeSupportFiles: {
-      type: 'boolean',
-      default: true,
-      description: 'Whether to write project support files such as src/enums/dict-registry.ts and src/utils/crudSchema.ts.'
-    },
+    writeSupportFiles: {
+      type: 'boolean',
+      default: true,
+      description: 'Whether to write project support files such as src/enums/dict-registry.ts, src/utils/crudSchema.ts and src/api/common/crudFactory.ts.'
+    },
     mergeI18nZh: {
       type: 'boolean',
       default: true,
@@ -835,7 +890,7 @@ function prepareDictRegistry(frontendPath, dictTypes) {
   };
 }
 
-function ensureCrudSchemaSupportFile(frontendPath) {
+function ensureCrudSchemaSupportFile(frontendPath) {
   const schemaPath = path.join(frontendPath, 'src', 'utils', 'crudSchema.ts');
   const exists = fs.existsSync(schemaPath);
   const currentContent = exists ? readUtf8File(schemaPath) : '';
@@ -852,12 +907,27 @@ function ensureCrudSchemaSupportFile(frontendPath) {
     exists,
     isCompatible: hasCoreShape && supportsLabelKey,
     needsWrite: !exists || shouldUpgradeLegacy,
-  };
-}
-
-function ensureDirectory(filePath) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-}
+  };
+}
+
+function ensureCrudFactorySupportFile(frontendPath) {
+  const factoryPath = path.join(frontendPath, 'src', 'api', 'common', 'crudFactory.ts');
+  const exists = fs.existsSync(factoryPath);
+  const currentContent = exists ? readUtf8File(factoryPath) : '';
+  const isCompatible = !exists || currentContent.includes('export const createCrudApi');
+
+  return {
+    path: factoryPath,
+    content: DEFAULT_CRUD_FACTORY_TEMPLATE,
+    exists,
+    isCompatible,
+    needsWrite: !exists,
+  };
+}
+
+function ensureDirectory(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
 
 function writeSupportFile(filePath, content) {
   ensureDirectory(filePath);
@@ -880,30 +950,52 @@ function prepareSharedSupport(frontendPath, dictTypes, writeSupportFiles) {
   const normalizedDictTypes = [...new Set((dictTypes || []).filter(Boolean))];
   const dictRegistry = writeSupportFiles ? prepareDictRegistry(frontendPath, normalizedDictTypes) : buildVirtualDictRegistry(normalizedDictTypes);
   const crudSchemaPath = path.join(frontendPath, 'src', 'utils', 'crudSchema.ts');
-  const crudSchema = writeSupportFiles
-    ? ensureCrudSchemaSupportFile(frontendPath)
-    : {
-        path: crudSchemaPath,
+  const crudSchema = writeSupportFiles
+    ? ensureCrudSchemaSupportFile(frontendPath)
+    : {
+        path: crudSchemaPath,
         content: DEFAULT_CRUD_SCHEMA_TEMPLATE,
         exists: fs.existsSync(crudSchemaPath),
         isCompatible: true,
-        needsWrite: false,
-        writeEnabled: false,
-      };
-  return {
-    dictRegistry,
-    crudSchema,
-    writeEnabled: Boolean(writeSupportFiles),
-  };
-}
+        needsWrite: false,
+        writeEnabled: false,
+      };
+  const crudFactoryPath = path.join(frontendPath, 'src', 'api', 'common', 'crudFactory.ts');
+  const crudFactory = writeSupportFiles
+    ? ensureCrudFactorySupportFile(frontendPath)
+    : {
+        path: crudFactoryPath,
+        content: DEFAULT_CRUD_FACTORY_TEMPLATE,
+        exists: fs.existsSync(crudFactoryPath),
+        isCompatible: true,
+        needsWrite: false,
+        writeEnabled: false,
+      };
+  return {
+    dictRegistry,
+    crudSchema,
+    crudFactory,
+    writeEnabled: Boolean(writeSupportFiles),
+  };
+}
 
 function maybeWriteSharedSupport(sharedSupport, writeToDisk) {
   if (!writeToDisk || !sharedSupport.writeEnabled) return;
 
-  if (sharedSupport.crudSchema.needsWrite) {
-    writeSupportFile(sharedSupport.crudSchema.path, sharedSupport.crudSchema.content);
-  }
-
+  if (sharedSupport.crudSchema.needsWrite) {
+    writeSupportFile(sharedSupport.crudSchema.path, sharedSupport.crudSchema.content);
+  }
+
+  if (sharedSupport.crudFactory.needsWrite) {
+    if (!sharedSupport.crudFactory.isCompatible) {
+      throw new Error(
+        'Detected an existing src/api/common/crudFactory.ts that MCP could not merge safely. ' +
+          'Please align the createCrudApi export manually before enabling writeSupportFiles.'
+      );
+    }
+    writeSupportFile(sharedSupport.crudFactory.path, sharedSupport.crudFactory.content);
+  }
+
   if (sharedSupport.dictRegistry.needsWrite) {
     if (!sharedSupport.dictRegistry.isCompatible) {
       throw new Error(
@@ -918,11 +1010,11 @@ function maybeWriteSharedSupport(sharedSupport, writeToDisk) {
 function buildSupportNote(sharedSupport, localeZhSupport) {
   const notes = [];
 
-  if (!sharedSupport.writeEnabled) {
-    notes.push(
-      'Shared support file writing is disabled. Generated code still references src/utils/crudSchema.ts and may reference src/enums/dict-registry.ts, so those helpers must already exist in the target project.'
-    );
-  }
+  if (!sharedSupport.writeEnabled) {
+    notes.push(
+      'Shared support file writing is disabled. Generated code still references src/utils/crudSchema.ts, src/api/common/crudFactory.ts and may reference src/enums/dict-registry.ts, so those helpers must already exist in the target project.'
+    );
+  }
 
   if (sharedSupport.crudSchema.exists && !sharedSupport.crudSchema.isCompatible) {
     notes.push(
@@ -931,6 +1023,13 @@ function buildSupportNote(sharedSupport, localeZhSupport) {
     );
   }
 
+  if (sharedSupport.crudFactory.exists && !sharedSupport.crudFactory.isCompatible) {
+    notes.push(
+      'Detected an existing src/api/common/crudFactory.ts that does not export createCrudApi. ' +
+        'MCP preserved the existing file and did not overwrite it. Generated API modules now depend on that file being manually aligned.'
+    );
+  }
+
   if (sharedSupport.dictRegistry.exists && !sharedSupport.dictRegistry.isCompatible) {
     notes.push(
       'Detected an existing src/enums/dict-registry.ts that MCP could not merge safely. ' +
@@ -1956,10 +2055,12 @@ function renderChildSection(childModel, childCount) {
 
   return [
     '          <el-col :span="24" class="mb20">',
+    `            <!-- 子表区域：${sanitizeHtmlComment(childModel.comment || childModel.tableName)} -->`,
     `            <div class="mb10" style="font-weight: 600;">{{ childSectionTitle('${childModel.listName}') }}</div>`,
+    '            <!-- 子表编辑表格：支持新增行、删除行和行内字段编辑 -->',
     `            <sc-form-table v-model="form.${childModel.listName}" :addTemplate="childTemp${childModel.className}" @delete="(obj) => ${deleteExpression}" :placeholder="t('common.noData')">`,
     childModel.visibleFields.map((field) => renderChildTableColumn(field, childModel.listName)).join('\n'),
-    '            </sc-form-table>',
+    '            </sc-form-table>',
     '          </el-col>',
   ].join('\n');
 }
@@ -2504,14 +2605,18 @@ function renderMultiLevelFormVue(model, moduleModel) {
   ].join('\n');
   const rules = renderFormRulesV2(moduleModel.visibleFields);
   return `<template>
-  <el-dialog v-model="visible" :title="form.${moduleModel.pk.attrName} ? t('common.editBtn') : t('common.addBtn')" :close-on-click-modal="false" draggable>
-    <el-form ref="dataFormRef" :model="form" :rules="dataRules" label-width="100px" v-loading="loading">
-      <el-row :gutter="24">
-${moduleModel.visibleFields.map(renderMultiLevelFormField).join('\n')}
-      </el-row>
-    </el-form>
-    <template #footer>
-      <span class="dialog-footer">
+  <!-- 表单弹窗：新增或编辑${sanitizeHtmlComment(moduleModel.comment || moduleModel.tableName)}数据 -->
+  <el-dialog v-model="visible" :title="form.${moduleModel.pk.attrName} ? t('common.editBtn') : t('common.addBtn')" :close-on-click-modal="false" draggable>
+    <!-- 弹窗表单：按 PRD 表单显隐和顺序渲染字段 -->
+    <el-form ref="dataFormRef" :model="form" :rules="dataRules" label-width="100px" v-loading="loading">
+      <!-- 字典字段区：字段级注释由 MCP 根据字段名称生成 -->
+      <el-row :gutter="24">
+${moduleModel.visibleFields.map(renderMultiLevelFormField).join('\n')}
+      </el-row>
+    </el-form>
+    <!-- 弹窗底部操作按钮：取消和确认提交 -->
+    <template #footer>
+      <span class="dialog-footer">
         <el-button @click="visible = false">{{ t('common.cancelButtonText') }}</el-button>
         <el-button type="primary" @click="onSubmit" :disabled="loading">{{ t('common.confirmButtonText') }}</el-button>
       </span>
@@ -2642,11 +2747,14 @@ ${moduleModel.visibleFields.map(renderMultiLevelFormField).join('\n')}
 function renderMultiLevelSchemaListSlot(levelVarName, activeKeyVarName, activeModuleVarName) {
   return [
     `        <div class="multi-level-slot" v-if="${levelVarName}">`,
+    '          <!-- 多层字典页签：切换当前层级下的字典模块 -->',
     '          <el-tabs class="multi-level-tabs" v-if="' + `${levelVarName}.moduleKeys.length > 1` + `" v-model="${activeKeyVarName}">`,
     `            <el-tab-pane v-for="moduleKey in ${levelVarName}.moduleKeys" :key="moduleKey" :label="resolveModuleTitle(moduleConfigs[moduleKey])" :name="moduleKey" />`,
     '          </el-tabs>',
+    '          <!-- 多层字典列表面板：承载当前层级的工具栏和表格 -->',
     '          <div class="multi-level-panel" v-if="' + `${activeModuleVarName}` + `">`,
     '            <div class="layout-padding-auto layout-padding-view flex h-full flex-col">',
+    '              <!-- 当前层级工具栏：搜索、新增和重置 -->',
     `              <SchemaListToolbar`,
     `                v-bind="getPanelToolbarProps(${activeModuleVarName}.key)"`,
     `                @update:keyword="handlePanelKeywordChange(${activeModuleVarName}.key, $event)"`,
@@ -2654,16 +2762,22 @@ function renderMultiLevelSchemaListSlot(levelVarName, activeKeyVarName, activeMo
     `                @query="handlePanelQuery(${activeModuleVarName}.key)"`,
     `                @reset="handlePanelReset(${activeModuleVarName}.key)"`,
     `              />`,
+    '              <!-- 当前层级表格：展示字典数据、分页和行操作 -->',
     `              <SchemaListTable`,
     `                v-bind="getPanelTableProps(${activeModuleVarName}.key)"`,
     `                @row-current-change="handlePanelCurrentChange(${activeModuleVarName}.key, $event.row)"`,
     `                @current-change="handleCurrentPageChange(${activeModuleVarName}.key, $event.current)"`,
     `                @size-change="handlePageSizeChange(${activeModuleVarName}.key, $event.size)"`,
     `              >`,
+    '                <!-- 行操作按钮：编辑、删除、启用、禁用 -->',
     `                <template #actions="{ row }">`,
+    '                  <!-- 编辑当前字典数据 -->',
     `                  <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'edit', row)" icon="edit-pen" text type="primary" @click="openEdit(${activeModuleVarName}.key, row)">{{ t('common.editBtn') }}</el-button>`,
+    '                  <!-- 删除当前字典数据 -->',
     `                  <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'delete', row)" icon="delete" text type="primary" @click="handleDelete(${activeModuleVarName}.key, row)">{{ t('common.delBtn') }}</el-button>`,
+    '                  <!-- 启用当前字典数据 -->',
     `                  <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'enable', row)" icon="circle-check" text type="primary" @click="handleEnable(${activeModuleVarName}.key, row)">闁告凹鍨抽弫?/el-button>`,
+    '                  <!-- 禁用当前字典数据 -->',
     `                  <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'disable', row)" icon="remove" text type="primary" @click="handleDisable(${activeModuleVarName}.key, row)">缂佸倷鑳堕弫?/el-button>`,
     `                </template>`,
     `              </SchemaListTable>`,
@@ -2676,14 +2790,18 @@ function renderMultiLevelSchemaListSlot(levelVarName, activeKeyVarName, activeMo
 function renderMultiLevelLevelSlot(levelVarName, activeKeyVarName, activeModuleVarName) {
   return [
     `        <div class="multi-level-slot" v-if="${levelVarName}">`,
+    '          <!-- 多层字典页签：切换当前层级下的字典模块 -->',
     '          <el-tabs class="multi-level-tabs" v-if="' + `${levelVarName}.moduleKeys.length > 1` + `" v-model="${activeKeyVarName}">`,
     `            <el-tab-pane v-for="moduleKey in ${levelVarName}.moduleKeys" :key="moduleKey" :label="resolveModuleTitle(moduleConfigs[moduleKey])" :name="moduleKey" />`,
     '          </el-tabs>',
+    '          <!-- 多层字典列表面板：承载当前层级的新增按钮、表格和分页 -->',
     '          <div class="multi-level-panel" v-if="' + `${activeModuleVarName}` + `">`,
     '            <div class="layout-padding-auto layout-padding-view flex h-full flex-col">',
+    '              <!-- 当前层级新增按钮：受父级状态约束控制 -->',
     '              <div class="mb8" style="width: 100%">',
     `                <el-button icon="folder-add" type="primary" class="ml10" :disabled="isAddDisabled(${activeModuleVarName}.key)" @click="openCreate(${activeModuleVarName}.key)">{{ t('common.addBtn') }}</el-button>`,
     '              </div>',
+    '              <!-- 当前层级表格：展示字典数据并处理行选中联动 -->',
     '              <el-table',
     `                :data="moduleStateMap[${activeModuleVarName}.key].dataList"`,
     `                v-loading="moduleStateMap[${activeModuleVarName}.key].loading"`,
@@ -2692,7 +2810,9 @@ function renderMultiLevelLevelSlot(levelVarName, activeKeyVarName, activeModuleV
     '                highlight-current-row',
     `                @current-change="handlePanelCurrentChange(${activeModuleVarName}.key, $event)"`,
     '              >',
+    '                <!-- 序号列 -->',
     `                <el-table-column type="index" :label="t('common.serial')" width="60" />`,
+    '                <!-- 字典业务字段列 -->',
     `                <el-table-column`,
     `                  v-for="column in getListFields(${activeModuleVarName}.key)"`,
     '                  :key="column.key"',
@@ -2706,15 +2826,21 @@ function renderMultiLevelLevelSlot(levelVarName, activeKeyVarName, activeModuleV
     '                    <span v-else>{{ scope.row[column.key] }}</span>',
     '                  </template>',
     '                </el-table-column>',
+    '                <!-- 行操作按钮：编辑、删除、启用、禁用 -->',
     `                <el-table-column :label="t('common.action')" width="260">`,
     '                  <template #default="{ row }">',
+    '                    <!-- 编辑当前字典数据 -->',
     `                    <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'edit', row)" icon="edit-pen" text type="primary" @click="openEdit(${activeModuleVarName}.key, row)">{{ t('common.editBtn') }}</el-button>`,
+    '                    <!-- 删除当前字典数据 -->',
     `                    <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'delete', row)" icon="delete" text type="primary" @click="handleDelete(${activeModuleVarName}.key, row)">{{ t('common.delBtn') }}</el-button>`,
+    '                    <!-- 启用当前字典数据 -->',
     `                    <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'enable', row)" icon="circle-check" text type="primary" @click="handleEnable(${activeModuleVarName}.key, row)">{{ t('common.actions.enable') }}</el-button>`,
+    '                    <!-- 禁用当前字典数据 -->',
     `                    <el-button v-if="showModuleAction(${activeModuleVarName}.key, 'disable', row)" icon="remove" text type="primary" @click="handleDisable(${activeModuleVarName}.key, row)">{{ t('common.actions.disable') }}</el-button>`,
     '                  </template>',
     '                </el-table-column>',
     '              </el-table>',
+    '              <!-- 当前层级分页组件 -->',
     '              <div class="mt-2.5 flex shrink-0 justify-end">',
     '                <pagination',
     `                  :current-page="moduleStateMap[${activeModuleVarName}.key].currentPage"`,
@@ -2766,24 +2892,31 @@ function renderMultiLevelIndexVue(model) {
 
   return `<!-- 功能名称：${sanitizeHtmlComment(model.featureTitle)} -->
 <template>
+  <!-- 页面布局：${sanitizeHtmlComment(model.featureTitle)}多层字典列表页 -->
   <div class="layout-padding">
+    <!-- 多层字典主布局：左侧一级字典，右侧二级和三级字典联动 -->
     <div class="multi-level-dict-layout">
-      <div class="multi-level-left">
+      <!-- 一级字典区域 -->
+      <div class="multi-level-left">
 ${renderMultiLevelSchemaListSlot('level1Config', 'activeLevel1Key', 'activeLevel1Module')}
-      </div>
-      <div class="multi-level-right">
-        <div class="multi-level-right-top">
+      </div>
+      <!-- 二级和三级字典区域 -->
+      <div class="multi-level-right">
+        <!-- 二级字典区域 -->
+        <div class="multi-level-right-top">
 ${level2 ? renderMultiLevelSchemaListSlot('level2Config', 'activeLevel2Key', 'activeLevel2Module') : ''}
-        </div>
-        <div v-if="level3Config" class="multi-level-right-bottom">
+        </div>
+        <!-- 三级字典区域 -->
+        <div v-if="level3Config" class="multi-level-right-bottom">
 ${level3 ? renderMultiLevelSchemaListSlot('level3Config', 'activeLevel3Key', 'activeLevel3Module') : ''}
-        </div>
-      </div>
-    </div>
-
-${formComponents}
-  </div>
-</template>
+        </div>
+      </div>
+    </div>
+
+    <!-- 多层字典表单弹窗：按模块异步挂载 -->
+${formComponents}
+  </div>
+</template>
 
   <script setup lang="ts" name="system${model.className}">
   // 通用消息与确认弹窗
@@ -3055,11 +3188,15 @@ function renderSingleTableDialogActions(model, permissionPrefix) {
   const pkAttr = model.pk.attrName;
   const isDictWithStatus = model.pageType === 'dict' && model.statusField;
   const lines = [
+    `          <!-- 编辑${sanitizeHtmlComment(model.featureTitle)} -->`,
     `          <el-button${isDictWithStatus ? ` v-if="showDictAction('edit', row)"` : ''} icon="edit-pen" text type="primary" v-auth="'${permissionPrefix}_edit'" @click="formDialogRef.openDialog(row.${pkAttr})">{{ t('common.editBtn') }}</el-button>`,
+    `          <!-- 删除${sanitizeHtmlComment(model.featureTitle)} -->`,
     `          <el-button${isDictWithStatus ? ` v-if="showDictAction('delete', row)"` : ''} icon="delete" text type="primary" v-auth="'${permissionPrefix}_del'" @click="handleDelete([row.${pkAttr}])">{{ t('common.delBtn') }}</el-button>`,
   ];
   if (isDictWithStatus) {
+    lines.push(`          <!-- 启用${sanitizeHtmlComment(model.featureTitle)} -->`);
     lines.push(`          <el-button v-if="showDictAction('enable', row)" icon="circle-check" text type="primary" @click="handleEnable(row.${pkAttr})">{{ t('common.actions.enable') }}</el-button>`);
+    lines.push(`          <!-- 禁用${sanitizeHtmlComment(model.featureTitle)} -->`);
     lines.push(`          <el-button v-if="showDictAction('disable', row)" icon="remove" text type="primary" @click="handleDisable(row.${pkAttr})">{{ t('common.actions.disable') }}</el-button>`);
   }
   return lines.join('\n');
@@ -3188,6 +3325,38 @@ function renderExtraApiFunctions(model) {
     .join('\n');
 }
 
+function renderApiRequestImport(model) {
+  const hasExtraApis = Array.isArray(model.extraApis) && model.extraApis.length > 0;
+  const hasDictStatusApis = model.pageType === 'dict' && !!model.statusField;
+  return hasExtraApis || hasDictStatusApis ? "import request from '/@/utils/request';" : '';
+}
+
+function renderExtraApiFunctionsV2(model) {
+  if (!Array.isArray(model.extraApis) || !model.extraApis.length) return '';
+  return model.extraApis
+    .map((api) => {
+      const requestField = api.requestType === 'data' ? 'data' : 'params';
+      const lines = ['', `// 额外接口：${sanitizeComment(api.description)}`];
+      if (api.usedBy) {
+        lines.push(`// 使用场景：${sanitizeComment(api.usedBy)}`);
+      }
+      if (api.source) {
+        lines.push(`// 来源说明：${sanitizeComment(api.source)}`);
+      }
+      lines.push(
+        `export function ${api.functionName}(payload?: any) {`,
+        '  return request({',
+        `    url: '${api.url}',`,
+        `    method: '${api.method}',`,
+        `    ${requestField}: payload,`,
+        '  });',
+        '}'
+      );
+      return lines.join('\n');
+    })
+    .join('\n');
+}
+
 function buildReplacements(model, sharedSupport) {
   const menuBaseId = Date.now();
   const apiModulePath = model.targetApiModule || `${model.moduleName}/${model.functionName}`;
@@ -3218,16 +3387,18 @@ function buildReplacements(model, sharedSupport) {
     BUSINESS_STATUS_IMPORTS: renderBusinessStatusImports(model),
     BUSINESS_EDIT_IF: hasBusinessBillStateEditControl(model) ? ' v-if="showEditAction(row)"' : '',
     BUSINESS_STATUS_HELPERS: renderBusinessStatusHelpers(model),
-    EXTRA_API_FUNCTIONS: renderExtraApiFunctions(model),
+    API_REQUEST_IMPORT: renderApiRequestImport(model),
+    EXTRA_API_FUNCTIONS: renderExtraApiFunctionsV2(model),
     CUSTOM_QUERY_FIELDS_EXPR: model.pageType === 'dict' ? '[]' : 'queryableDictOptions.value',
     SHOW_RIGHT_TOOLS: model.pageType === 'dict' ? 'false' : 'true',
     MENU_BASE_ID: menuBaseId,
     MENU_BASE_ID_PLUS_1: menuBaseId + 1,
     MENU_BASE_ID_PLUS_2: menuBaseId + 2,
-    MENU_BASE_ID_PLUS_3: menuBaseId + 3,
-      MENU_BASE_ID_PLUS_4: menuBaseId + 4,
-      MENU_BASE_ID_PLUS_5: menuBaseId + 5,
-      GENERATED_AT: new Date().toISOString(),
+    MENU_BASE_ID_PLUS_3: menuBaseId + 3,
+      MENU_BASE_ID_PLUS_4: menuBaseId + 4,
+      MENU_BASE_ID_PLUS_5: menuBaseId + 5,
+      MENU_BASE_ID_PLUS_6: menuBaseId + 6,
+      GENERATED_AT: new Date().toISOString(),
       FORM_FIELDS: model.visibleFields.map(renderFormFieldV2).join('\n'),
       TABLE_COLUMNS: model.gridFields.map((field) => renderTableColumn(field, dictRegistryRefs)).join('\n'),
       FORM_DEFAULTS: renderFormDefaults(model),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worsoft-frontend-codegen-local-mcp",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "description": "Worsoft frontend local-template code generation MCP server.",
   "license": "UNLICENSED",
   "author": "worsoft <sw@worsoft.vip>",