worsoft-frontend-codegen-local-mcp 0.1.29 → 0.1.33

package/MVP_DESIGN.md

@@ -4,40 +4,43 @@
 
 Build a local MCP plugin that generates frontend files from:
 
-- API-first structured metadata
-- local template assets
-- style-based template selection
+- structured feature metadata
+- local runtime templates
+- style-based rendering rules
 
-without depending on the Worsoft backend generation API
+without depending on the Worsoft backend generation API.
 
 ## Current Supported Flow
 
-1. Caller-side skill reads API doc and requirement doc
-2. Caller-side skill builds structured metadata
+1. Upstream caller parses PRD, API docs, or any other source
+2. Upstream caller builds structured JSON metadata
 3. MCP receives:
    - main table metadata
    - child table metadata
    - explicit `payloadField`
+   - explicit `levels[]`
    - field arrays
 4. MCP loads style metadata from `assets/style-catalog.json`
-5. MCP resolves shared template selection for the requested `style`
-6. MCP builds a normalized runtime model
-7. MCP maps structured fields into frontend field types
-8. MCP renders runtime templates
-9. MCP returns a render manifest
-10. MCP optionally writes files
+5. MCP builds a normalized runtime model
+6. MCP maps structured fields into frontend field types
+7. MCP renders runtime templates
+8. MCP returns a render manifest
+9. MCP optionally writes files
+10. MCP optionally writes support files and optionally merges `zh-cn.ts`
 
 ## Declared Styles
 
 - `single_table_jump`
 - `single_table_dialog`
 - `master_child_jump`
+- `multi_level_dict`
 
 ## Runtime-Implemented Styles
 
 - `single_table_jump`
 - `single_table_dialog`
 - `master_child_jump`
+- `multi_level_dict`
 
 ## Metadata Model
 
@@ -76,22 +79,36 @@ without depending on the Worsoft backend generation API
 }
 ```
 
-## Master-Child Contract
+## Contracts
 
-When `style=master_child_jump`:
+### master_child_jump
 
 - MCP never infers child relations
 - caller must always pass explicit `children[]`
 - `payloadField` is the only child list truth
 
+### multi_level_dict
+
+- MCP never infers level hierarchy
+- caller must always pass explicit `levels[]`
+- non-root modules must provide `queryParentField`
+
+### side effects
+
+- `writeSupportFiles=true` keeps project helper writes enabled
+- `writeSupportFiles=false` turns MCP into a render-only generator for support files
+- `mergeI18nZh=true` keeps existing Chinese locale merge behavior
+- `mergeI18nZh=false` makes zh-cn output source-of-truth from current metadata only
+
 ## Risks
 
-- Quality now depends on caller-side extraction from API doc and requirement doc
-- If API doc omits structure or dict codes, caller-side skill must stop and report the gap
-- Query/list/form metadata inference still contains heuristics for widths and control defaults
+- Quality depends on upstream structured metadata quality
+- If upstream metadata omits structure or dict codes, caller must stop and report the gap
+- Query/list/form metadata normalization still contains heuristics for widths and default controls
 
 ## Next Steps
 
-1. Continue hardening API-first extraction rules on caller-side skills
+1. Keep the MCP contract source-agnostic and JSON-only
 2. Expand structured validation for field completeness
-3. Keep template behavior aligned with API-first contract
+3. Keep render behavior aligned with the structured metadata contract
+4. Continue reducing project-specific side effects so MCP focuses on validate, render, and optional write

package/README.md

@@ -1,10 +1,10 @@
 # Worsoft Frontend Codegen Local MCP
 
-This MCP generates Worsoft frontend files from API-first structured metadata.
+This MCP generates Worsoft frontend files from structured JSON metadata.
 
 ## Scope
 
-- API-first structured input
+- structured JSON input
 - style-based template selection
 - local template rendering
 - single-table runtime generation
@@ -20,10 +20,13 @@ This MCP generates Worsoft frontend files from API-first structured metadata.
 - `style`
 - `fields`
 - `children`
+- `levels`
 - `frontendPath`
 - `moduleName`
 - `writeToDisk`
 - `overwrite`
+- `writeSupportFiles`
+- `mergeI18nZh`
 
 ## Recommended MCP Arguments
 
@@ -88,6 +91,7 @@ PowerShell:
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario single
+powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario single_dialog
 powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario master
 powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario multi
 ```
@@ -96,8 +100,9 @@ Node:
 
 ```bash
 node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario single
+node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario single_dialog
 node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario master
-node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario multi
+node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario dict_multi
 ```
 
 Optional overrides:
@@ -110,6 +115,17 @@ Optional overrides:
 - `--frontend-path`
 - `--write-to-disk`
 
+## Side-Effect Controls
+
+- `writeSupportFiles=true`:
+  MCP may write `src/enums/dict-registry.ts` and `src/utils/crudSchema.ts`
+- `writeSupportFiles=false`:
+  MCP does not write support files. Generated code still expects those helpers to already exist in the target project
+- `mergeI18nZh=true`:
+  MCP reads an existing `zh-cn.ts` and merges missing keys
+- `mergeI18nZh=false`:
+  MCP renders `zh-cn.ts` from current metadata only and does not parse the existing file
+
 ## Master-Child Contract
 
 For `master_child_jump`, MCP does not infer relations.
@@ -125,6 +141,21 @@ The caller must provide explicit `children[]`, and each child must include:
 
 If these fields are missing, MCP returns a structured validation error.
 
+## Multi-Level Dictionary Contract
+
+For `multi_level_dict`, MCP does not infer hierarchy.
+
+The caller must provide explicit `levels[]`. Each level must include:
+
+- `levelIndex`
+- `modules`
+
+Each module must include:
+
+- `tableName`
+- `apiPath`
+- `fields`
+
 ## Current Outputs
 
 - `src/views/<module>/<function>/index.vue`
@@ -144,13 +175,14 @@ Declared styles:
 - `single_table_jump`
 - `single_table_dialog`
 - `master_child_jump`
+- `multi_level_dict`
 
 ## Notes
 
-- Shared Worsoft template references live under `../template`
 - Plugin-local runtime assets live under `assets/templates`
-- API-first means MCP no longer reads Markdown design docs or SQL design docs
-- Caller-side skills are responsible for turning API doc + requirement doc into structured arguments
+- MCP does not parse PRD, API, Markdown, or SQL design documents
+- Upstream caller-side skills are responsible for turning documents into structured JSON metadata
+- Support-file writes and zh-cn merge behavior can be controlled through `writeSupportFiles` and `mergeI18nZh`
 - Menu SQL is emitted to `frontendPath/menu/`
 
 ## IDE Guide

package/assets/templates/master_child_jump/index.tpl

@@ -1,56 +1,35 @@
 <template>
   <div class="layout-padding">
-    <!-- 功能名称：{{FEATURE_TITLE}} -->
-    <div class="layout-padding-auto layout-padding-view flex-column" style="display: flex; flex-direction: column; height: 100%;">
-      <div class="mb8" style="width: 100%; flex-shrink: 0;">
-        <el-button icon="folder-add" type="primary" class="ml10"  @click="handleCreate">{{ t('common.addBtn') }}</el-button>
-        <el-button plain icon="upload-filled" type="primary" class="ml10"  @click="excelUploadRef.show()">{{ t('common.importBtn') }}</el-button>
-        <el-button plain :disabled="multiple" icon="Delete" type="primary"  @click="handleDelete(selectObjs)">{{ t('common.delBtn') }}</el-button>
-        <right-toolbar :export="'{{PERMISSION_PREFIX}}_export'" @exportExcel="exportExcel" class="ml10 mr20" style="float: right;" />
-      </div>
-
-      <div style="flex: 1; overflow: hidden; display: flex; flex-direction: column;">
-        <el-table
-          :data="state.dataList"
-          v-loading="state.loading"
-          border
-          height="100%"
-          style="width: 100%;"
-          :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="t('common.serial')" width="60" />
-        <el-table-column
-          v-for="column in visibleTableColumns"
-          :key="column.prop"
-          :prop="column.prop"
-          :label="resolveLabel(column.labelKey, column.fallbackLabel)"
-          :min-width="column.width"
-          show-overflow-tooltip
-        >
-          <template #default="scope">
-            <dict-tag v-if="column.dictType" :options="getDictOptions(column.dictType)" :value="scope.row[column.prop]" />
-            <span v-else>{{ scope.row[column.prop] }}</span>
-          </template>
-        </el-table-column>
-        <el-table-column :label="t('common.action')" width="380" fixed="right">
-          <template #default="scope">
-            <el-button text type="primary" icon="view" v-auth="'{{PERMISSION_PREFIX}}_view'" @click="handleDetail(scope.row.id)">{{ t('common.viewBtn') }}</el-button>
-            <el-button icon="edit-pen" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_edit'" @click="handleEdit(scope.row.id)">{{ t('common.editBtn') }}</el-button>
-            <el-button text type="primary" icon="check" @click="handleQuickAction(scope.row, 'submit')">{{ commonActionLabel('submit') }}</el-button>
-            <el-button text type="success" icon="position" @click="handleQuickAction(scope.row, 'flow')">{{ commonActionLabel('flow') }}</el-button>
-            <el-button icon="delete" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_del'" @click="handleDelete([scope.row.id])">{{ t('common.delBtn') }}</el-button>
-          </template>
-        </el-table-column>
-        </el-table>
-      </div>
-
-      <div style="flex-shrink: 0; margin-top: 10px; display: flex; justify-content: flex-end;">
-        <pagination @size-change="sizeChangeHandle" @current-change="currentChangeHandle" v-bind="state.pagination" />
-      </div>
+    <div class="layout-padding-auto layout-padding-view flex h-full flex-col">
+      <SchemaListToolbar
+        v-bind="toolbarProps"
+        @update:keyword="state.queryForm.smartVal = $event"
+        @add="handleToolbarAdd"
+        @import="handleToolbarImport"
+        @delete="handleToolbarDelete"
+        @query="handleToolbarQuery"
+        @reset="handleToolbarReset"
+        @custom-query-confirm="handleToolbarCustomQueryConfirm"
+        @export="handleToolbarExport"
+        @refresh="handleToolbarRefresh"
+      />
+
+      <SchemaListTable
+        v-bind="tableProps"
+        row-id-key="{{PK_ATTR}}"
+        @selection-change="handleTableSelectionChange"
+        @sort-change="handleTableSortChange"
+        @size-change="handleTableSizeChange"
+        @current-change="handleTableCurrentChange"
+      >
+        <template #actions="{ row }">
+          <el-button text type="primary" icon="view" v-auth="'{{PERMISSION_PREFIX}}_view'" @click="handleDetail(row.{{PK_ATTR}})">{{ t('common.viewBtn') }}</el-button>
+          <el-button icon="edit-pen" text type="primary" v-auth="'{{PERMISSION_PREFIX}}_edit'" @click="handleEdit(row.{{PK_ATTR}})">{{ t('common.editBtn') }}</el-button>
+          <el-button text type="primary" icon="check" @click="handleQuickAction(row, 'submit')">{{ commonActionLabel('submit') }}</el-button>
+          <el-button text type="success" icon="position" @click="handleQuickAction(row, 'flow')">{{ commonActionLabel('flow') }}</el-button>
+          <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>
 
     <upload-excel ref="excelUploadRef" :title="t('common.importBtn')" url="/{{API_PATH}}/import" temp-url="/admin/sys-file/local/file/{{FUNCTION_NAME}}.xlsx" @refreshDataList="getDataList" />
@@ -58,52 +37,83 @@
 </template>
 
 <script setup lang="ts" name="system{{CLASS_NAME}}">
-import { BasicTableProps, useTable } from '/@/hooks/table';
 import { fetchList, delObjs } from '/@/api/{{API_MODULE_PATH}}';
 import { useMessage, useMessageBox } from '/@/hooks/message';
 import { useDict } from '/@/hooks/dict';
 import { useCrudPageMeta } from '/@/hooks/useCrudPageMeta';
+import { useSchemaListQuery } from '/@/hooks/useSchemaListQuery';
+import SchemaListToolbar from '/@/components/schema-list/SchemaListToolbar.vue';
+import SchemaListTable from '/@/components/schema-list/SchemaListTable.vue';
 import { useI18n } from 'vue-i18n';
-import { allDictTypes, dataMasterEntity } from './options';
+import { allDictTypes, crudSchema, dataMasterEntity } from './options';
 
 const dictRefs = useDict(...allDictTypes);
 const { t } = useI18n();
 const router = useRouter();
 
 const excelUploadRef = ref();
-const selectObjs = ref([]) as any;
+const selectObjs = ref<string[]>([]);
 const multiple = ref(true);
 
-// 列表页基础状态，由 useTable 统一接管分页、排序和数据加载
-const state: BasicTableProps = reactive<BasicTableProps>({
-  queryForm: {},
+const { state, getDataList, currentChangeHandle, sizeChangeHandle, sortChangeHandle, tableStyle, exportExcel: runExportExcel, resetQueryForm } = useSchemaListQuery({
+  schema: crudSchema,
   pageList: fetchList,
+  exportUrl: '/{{API_PATH}}/export',
+  exportFileName: '{{FUNCTION_NAME}}.xlsx',
 });
 
-// 页面字段、双语和字典相关的公共能力统一从 hook 中获取
-const { resolveLabel, getDictOptions, commonActionLabel, visibleTableColumns } = useCrudPageMeta(dataMasterEntity, dictRefs);
-
-const { getDataList, currentChangeHandle, sizeChangeHandle, sortChangeHandle, downBlobFile, tableStyle } = useTable(state);
+const { resolveLabel, getDictOptions, commonActionLabel, visibleTableColumns, searchKeywordTooltip, queryableDictFields } = useCrudPageMeta(dataMasterEntity, dictRefs);
+
+const queryableDictOptions = computed(() =>
+  queryableDictFields.value.map((field) => ({
+    ...field,
+    options: getDictOptions(field.dictType),
+  }))
+);
+
+const tableColumns = computed(() =>
+  visibleTableColumns.value.map((column) => ({
+    prop: column.prop,
+    label: resolveLabel(column.labelKey, column.fallbackLabel),
+    width: column.width,
+    dictType: column.dictType,
+    options: column.dictType ? getDictOptions(column.dictType) : [],
+  }))
+);
+
+const toolbarProps = computed(() => ({
+  keyword: state.queryForm.smartVal,
+  searchPlaceholder: searchKeywordTooltip.value,
+  queryModel: state.queryForm,
+  customQueryFields: queryableDictOptions.value,
+  selectedIds: selectObjs.value,
+  deleteDisabled: multiple.value,
+  exportPermission: '{{PERMISSION_PREFIX}}_export',
+}));
+
+const tableProps = computed(() => ({
+  data: state.dataList,
+  loading: !!state.loading,
+  columns: tableColumns.value,
+  pagination: state.pagination,
+  tableStyle,
+}));
 
 const getFormPath = () => '/{{VIEW_MODULE_PATH}}/form';
 
-// 进入新增页
 const handleCreate = () => {
   router.push({ path: getFormPath(), query: { tagsViewName: t('common.addBtn') } });
 };
 
-// 进入详情页
 const handleDetail = (id: string) => {
   router.push({ path: getFormPath(), query: { id, detail: '1', tagsViewName: t('common.viewBtn') } });
 };
 
-// 进入编辑页
 const handleEdit = (id: string) => {
   router.push({ path: getFormPath(), query: { id, tagsViewName: t('common.editBtn') } });
 };
 
-// 快捷提交和流转共用一套确认和成功提示
-const handleQuickAction = async (row: any, actionType: string) => {
+const handleQuickAction = async (_row: any, actionType: string) => {
   const actionName = commonActionLabel(actionType);
   try {
     await useMessageBox().confirm(t('common.messages.quickActionConfirm', { action: actionName }));
@@ -113,21 +123,32 @@ const handleQuickAction = async (row: any, actionType: string) => {
         : t('common.messages.quickFlowSuccess')
     );
     getDataList();
-  } catch {}
+  } catch {
+    return;
+  }
 };
 
-// 导出当前查询结果
 const exportExcel = () => {
-  downBlobFile('/{{API_PATH}}/export', { ...state.queryForm, ids: selectObjs.value }, '{{FUNCTION_NAME}}.xlsx');
+  runExportExcel(selectObjs.value);
 };
 
-// 维护当前表格勾选项
-const selectionChangeHandle = (objs: { id: string }[]) => {
-  selectObjs.value = objs.map((item) => item.id);
-  multiple.value = !objs.length;
+const handleQueryFilterConfirm = (values: Record<string, any>) => {
+  queryableDictFields.value.forEach((field) => {
+    const nextValue = values[field.prop];
+    if (Array.isArray(nextValue) && nextValue.length) {
+      state.queryForm[field.prop] = nextValue;
+      return;
+    }
+    delete state.queryForm[field.prop];
+  });
+  getDataList();
+};
+
+const resetQuery = () => {
+  resetQueryForm();
+  getDataList();
 };
 
-// 删除前先进行二次确认
 const handleDelete = async (ids: string[]) => {
   try {
     await useMessageBox().confirm(t('common.delConfirmText'));
@@ -143,4 +164,53 @@ const handleDelete = async (ids: string[]) => {
     useMessage().error(err.msg || t('common.delBtn'));
   }
 };
+
+const handleToolbarAdd = () => {
+  handleCreate();
+};
+
+const handleToolbarImport = () => {
+  excelUploadRef.value?.show();
+};
+
+const handleToolbarDelete = () => {
+  handleDelete(selectObjs.value);
+};
+
+const handleToolbarQuery = () => {
+  getDataList();
+};
+
+const handleToolbarReset = () => {
+  resetQuery();
+};
+
+const handleToolbarCustomQueryConfirm = (payload: { values: Record<string, any> }) => {
+  handleQueryFilterConfirm(payload.values);
+};
+
+const handleToolbarExport = () => {
+  exportExcel();
+};
+
+const handleToolbarRefresh = () => {
+  getDataList();
+};
+
+const handleTableSelectionChange = (payload: { ids: Array<string | number> }) => {
+  selectObjs.value = payload.ids.map((id) => String(id));
+  multiple.value = !payload.ids.length;
+};
+
+const handleTableSortChange = (payload: { raw: any }) => {
+  sortChangeHandle(payload.raw);
+};
+
+const handleTableSizeChange = (payload: { size: number }) => {
+  sizeChangeHandle(payload.size);
+};
+
+const handleTableCurrentChange = (payload: { current: number }) => {
+  currentChangeHandle(payload.current);
+};
 </script>

package/assets/templates/master_child_jump/options.tpl

@@ -18,6 +18,7 @@ const definition: CrudSchemaDefinition = {
 // 将页面声明转换成 index/form 统一消费的 schema 结果
 const schema = createCrudSchema(definition);
 
+export const crudSchema = schema;
 // 主表字段配置，供列表页和表单页使用
 export const dataMasterEntity = schema.master;
 // 子表字段配置，供主子表区块读取