update 内置代码生成模板优化skill

2026-06-03 15:20:07 +08:00
parent 7eccb9b8c1
commit bbf508e123
12 changed files with 1194 additions and 34 deletions
@@ -1,11 +1,11 @@
 ---
 name: frontend-crud-coding
-description: 在当前 plus-ui-react 前端项目中按真实 React + TypeScript + Umi Max + Ant Design ProComponents + oxlint/oxfmt 代码风格生成或修改页面、API、types、hooks 接入和样式。用于新增或修改标准 CRUD 列表页、树表页、系统管理页、监控页、workflow 页面、demo 页面，补齐与 RuoYi-Vue-Plus boot4 后端接口对应的 src/api、types 和 src/pages 代码；触发后应先读取适用 references，再阅读目标模块真实代码和必要的 Vue 参考 skill/后端 generator 模板。
+description: 在当前 plus-ui-react 前端项目中按真实 React + TypeScript + Umi Max + Ant Design ProComponents + oxlint/oxfmt 代码风格生成或修改页面、API、types、hooks 接入、样式和项目内置 gen/*.vm 代码生成模板。用于新增或修改标准 CRUD 列表页、树表页、系统管理页、监控页、workflow 页面、demo 页面，补齐与 RuoYi-Vue-Plus boot4 后端接口对应的 src/api、types 和 src/pages 代码，或维护 gen/api.ts.vm、gen/types.ts.vm、gen/index.vue.vm、gen/index-tree.vue.vm；触发后应先读取适用 references，再阅读目标模块真实代码和项目内置 gen 模板。
 ---

 # 前端编码规范

-先对齐当前 React 项目里的真实实现，再参考 Vue 版本 skill 和关联后端工程的代码生成器模板。不要直接套 Vue 3、Element Plus、AxiosPromise 或 `src/views` 规则；要落成当前仓库的 `src/pages`、`src/api`、ProTable、ModalForm、权限和导出方式。
+先对齐当前 React 项目里的真实实现，再参考项目内置 `gen/` 代码生成模板。Vue 版本 skill 和关联后端工程的代码生成器模板只用于理解字段、权限、任务分型和迁移意图。不要直接套 Vue 3、Element Plus、AxiosPromise 或 `src/views` 规则；要落成当前仓库的 `src/pages`、`src/api`、ProTable、ModalForm、权限、导出和公共工具方式。

 ## 执行流程

@@ -16,11 +16,12 @@ description: 在当前 plus-ui-react 前端项目中按真实 React + TypeScript
   - 树表优先看 `src/pages/demo/tree/index.tsx`、`src/pages/workflow/category/index.tsx`。
   - 系统复杂页优先看 `src/pages/system/user/index.tsx`、`system/role`、`system/post`、`system/config`。
   - workflow 业务页优先看 `src/pages/workflow/*` 与 `src/api/workflow/*` 同类页面。
-4. 需要从 Vue 版本迁移经验时，参考 `D:\git-sources\Plus相关\plus-ui-new\.codex\skills\frontend-crud-coding` 和 `.claude\agents`，只吸收任务分型、增量修改和自检原则。
-5. 新增标准页面前，可以对照后端工程 `D:\git-sources\Plus相关\RuoYi-Vue-Plus-boot4\ruoyi-modules\ruoyi-gen\src\main\resources\vm` 确认接口、字段、权限和导出能力，但输出必须改成 React 项目风格。
-6. 新增代码时通常同步维护 `src/api/<module>/<business>/index.ts`、`types.ts`、`src/pages/<module>/<business>/index.tsx`。
-7. 增强已有页面时只做增量修改，保留原页面的树筛选、导入导出、列显隐、权限、字典、弹窗、抽屉和路由跳转能力。
-8. 修改完成后按影响范围运行验证：优先 `pnpm exec tsc --noEmit` 或 `pnpm lint`；大范围页面、公共组件、构建配置变更再跑 `pnpm build`。
+4. 新增或维护代码生成能力时，优先阅读当前仓库 `gen/api.ts.vm`、`gen/types.ts.vm`、`gen/index.vue.vm`、`gen/index-tree.vue.vm`。这些是 React 版内置生成模板，即使文件名保留 `.vue.vm`，内容也应是当前项目 React/TSX 风格。
+5. 需要从 Vue 版本迁移经验时，参考 `D:\git-sources\Plus相关\plus-ui-new\.codex\skills\frontend-crud-coding` 和 `.claude\agents`，只吸收任务分型、增量修改和自检原则。
+6. 新增标准页面前，可以对照后端工程 `D:\git-sources\Plus相关\RuoYi-Vue-Plus-boot4\ruoyi-modules\ruoyi-gen\src\main\resources\vm` 确认字段、权限和导出能力，但输出和 `gen/` 模板必须保持 React 项目风格。
+7. 新增代码时通常同步维护 `src/api/<module>/<business>/index.ts`、`types.ts`、`src/pages/<module>/<business>/index.tsx`；如果是生成模板优化，同步维护 `gen/` 对应 `.vm`。
+8. 增强已有页面时只做增量修改，保留原页面的树筛选、导入导出、列显隐、权限、字典、弹窗、抽屉和路由跳转能力。
+9. 修改完成后按影响范围运行验证：优先 `pnpm exec tsc --noEmit` 或 `pnpm lint`；大范围页面、公共组件、构建配置变更再跑 `pnpm build`。

 ## 文档读取规则

@@ -34,9 +35,10 @@ description: 在当前 plus-ui-react 前端项目中按真实 React + TypeScript

 1. 目标目录下最近似页面、API、types 的真实实现。
 2. 当前项目公共 hooks、组件、工具、样式和请求封装约定。
-3. Vue 参考项目 `.codex` / `.claude` 中的任务分型和工作流。
-4. 关联后端工程 generator 模板。
-5. 通用 React / Ant Design ProComponents 习惯。
+3. 当前项目内置 `gen/*.vm` React 代码生成模板。
+4. Vue 参考项目 `.codex` / `.claude` 中的任务分型和工作流。
+5. 关联后端工程 generator 模板。
+6. 通用 React / Ant Design ProComponents 习惯。

 也就是说：

@@ -54,6 +56,7 @@ description: 在当前 plus-ui-react 前端项目中按真实 React + TypeScript
 - 请求统一通过 `src/api/request.ts`，API 返回类型使用 `Promise<R<T>>`，不要从 `axios` 或 Vue 项目引入 `AxiosPromise`。
 - 分页结果使用 `PageResult<T>` from `@/api/types`，接口外层使用 `R<T>` from `@/api/types`。
 - 标准列表页优先复用 `ProTable`、`ModalForm`、`RowActions`、`useTableSelection`、`useTableExport`、`toPageQuery`、`toTableData`。
+- 查询、字典、树表、loading、重置和确认弹窗优先复用 `useDateRangeQuery`、`dictOptions`、`useTreeTableExpand`、`useLoading`、`useSearchReset`、`confirmAction`/`confirmTitleSafe`。
 - 权限用 `const userInfo = useUserStore(state => state.userInfo)` 和 `hasPermi(userInfo, ['module:business:action'])` 计算布尔值。
 - 新页面不要无故引入另一套状态管理、请求封装、表格封装、样式体系或权限写法。

@@ -89,7 +92,7 @@ description: 在当前 plus-ui-react 前端项目中按真实 React + TypeScript

 ### 2. 树表 CRUD

-以 `src/pages/demo/tree/index.tsx`、`src/pages/workflow/category/index.tsx` 为主要起点。列表接口通常返回数组，不使用分页 `PageResult`；页面使用 `handleTree`、`expandedRowKeys`、`ProFormTreeSelect`。
+以 `src/pages/demo/tree/index.tsx`、`src/pages/workflow/category/index.tsx` 为主要起点。列表接口通常返回数组，不使用分页 `PageResult`；页面使用 `handleTree`、`useTreeTableExpand`、`ProFormTreeSelect`。

 ### 3. 强业务页面

@@ -103,6 +106,17 @@ workflow 目录优先参考 `src/pages/workflow/*`。流程定义、流程实例

 只维护 `src/api/<module>/<business>/index.ts` 与 `types.ts`，但仍要与后端路由、返回结构、当前模块导入方式和类型入口一致。

+### 6. 维护 React 生成模板
+
+模板只放在当前仓库 `gen/` 下，除非用户明确要求写入 boot4 后端工程。维护时保持 Velocity 变量和文件名不变：
+
+- `gen/api.ts.vm`
+- `gen/types.ts.vm`
+- `gen/index.vue.vm`
+- `gen/index-tree.vue.vm`
+
+模板内容必须生成当前 React 项目代码，并优先使用已有公共工具：`useDateRangeQuery`、`dictOptions`、`useTreeTableExpand`、`useTableSelection`、`useTableExport`、`confirmAction`、`toPageQuery`、`toTableData`、`handleTree`、`formatDateTimeFields`、`toDayjsFields`。不要把 Vue 模板、Element Plus 组件或 `src/views` 路径写入这些模板。
+
 ## 输出要求

 使用本 skill 时，默认期望产出应满足：
@@ -112,6 +126,7 @@ workflow 目录优先参考 `src/pages/workflow/*`。流程定义、流程实例
 - 标准页查询、重置、分页、弹窗、提交、删除、导出流程闭环完整。
 - 复杂页面保留原有交互能力和业务约束。
 - 代码体现当前项目 hooks、页面壳和下载方式，而不是 Vue 版本或 generator 裸输出。
+- 生成模板变更要同步反映当前项目公共 hooks/工具，避免生成的新页面重复手写日期范围、字典 options、树展开、loading、搜索重置和确认框逻辑。
 - 交付前说明运行过的验证命令；如果无法验证，说明原因。

 ## 快速检查清单
@@ -124,8 +139,12 @@ workflow 目录优先参考 `src/pages/workflow/*`。流程定义、流程实例
 - 多选是否通过 `useTableSelection<T>(row => row.id)`。
 - 行操作是否优先使用 `RowActions` 和 Ant Design 图标。
 - 权限是否通过 `useUserStore` + `hasPermi` 计算，不要写 Vue 指令。
- 日期范围是否通过 `formatDateTimeRange` + `addDateRange` 或附近页面现有方式处理。
- 树表是否使用 `handleTree`、`pagination={false}`、`expandedRowKeys`、`ProFormTreeSelect`。
+- 日期范围是否通过 `useDateRangeQuery` 或 `addDateRange` 相关工具处理。
+- 字典 options 是否通过 `dictOptions`。
+- 树表是否使用 `handleTree`、`pagination={false}`、`useTreeTableExpand`、`ProFormTreeSelect`。
+- loading 是否优先使用 `useLoading`，搜索重置是否优先使用 `useSearchReset`。
+- 需要 Promise 式确认时是否使用 `confirmAction` 或 `confirmTitleSafe`。
+- 代码生成模板是否仍输出 React TSX 项目风格。

 ## 推荐提问方式

@@ -1,7 +1,7 @@
 interface:
  display_name: "前端编码"
-  short_description: "按 plus-ui-react 真实代码编写 React CRUD"
-  default_prompt: "使用 $frontend-crud-coding 先读取适用 reference，再按 plus-ui-react 真实页面、API/types、ProTable、ModalForm、权限和导出约定实现前端修改。"
+  short_description: "按 plus-ui-react 真实代码和 gen 模板编写 React CRUD"
+  default_prompt: "使用 $frontend-crud-coding 先读取适用 reference，再按 plus-ui-react 真实页面、项目内置 gen 模板、API/types、ProTable、ModalForm、权限、导出和公共工具约定实现前端修改。"

 policy:
  allow_implicit_invocation: true
@@ -14,9 +14,10 @@

 - 先看 `src/api/system/client/*` 和 `src/pages/system/client/index.tsx` 是否已存在。
 - 再看 `src/pages/demo/demo/index.tsx` 的标准 React CRUD 骨架。
- 必要时对照 boot4 generator 模板确认字段、权限和接口。
+- 新增标准生成能力时优先对照当前仓库 `gen/index.vue.vm`、`gen/api.ts.vm`、`gen/types.ts.vm`；boot4 generator 只用于核对字段、权限和接口。
 - 生成或修改 `api/index.ts`、`types.ts`、`pages/.../index.tsx`。
 - 使用 `request<R<PageResult<T>>>`、`ProTable`、`ModalForm`、`RowActions`、`useTableSelection`、`useTableExport`。
+- 日期范围、字典 options、确认框、loading 等优先使用 `useDateRangeQuery`、`dictOptions`、`confirmAction`、`useLoading` 等项目工具。

 ## 案例 2：新增树表页面

@@ -32,9 +33,25 @@
 - 判断这是树表，不生成分页 `PageResult` 页面。
 - API 列表返回 `R<Tree2VO[]>`。
 - `Query` 不继承 `PageQuery`。
- 页面使用 `handleTree`、`pagination={false}`、`expandedRowKeys`、`ProFormTreeSelect`。
+- 页面使用 `handleTree`、`pagination={false}`、`useTreeTableExpand`、`ProFormTreeSelect`。
 - 新增子节点时从当前行带入 `parentId`。

+## 案例 2.1：优化 React 代码生成模板
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 优化当前项目 gen 目录下的 React 代码生成模板，让生成页面继续使用新加的工具。
+```
+
+### 期望执行方式
+
+- 读取 `gen/api.ts.vm`、`gen/types.ts.vm`、`gen/index.vue.vm`、`gen/index-tree.vue.vm`。
+- 保持 Velocity 变量、宏和文件名不变。
+- 普通表模板继续使用 `useTableSelection`、`useTableExport`、`useDateRangeQuery`、`dictOptions`、`confirmAction`。
+- 树表模板继续使用 `handleTree`、`filterTree`、`useTreeTableExpand`、`dictOptions`。
+- 输出仍是 React TSX 项目代码，不写 Vue `src/views`、Element Plus 或 `AxiosPromise`。
+
 ## 案例 3：修改已有复杂列表页

 ### 用户提问示例
@@ -66,7 +83,7 @@
 - 优先看 `src/pages/workflow/category/index.tsx` 和 `src/api/workflow/category/*`。
 - 判断是否需要后端新增导出接口；前端导出路径保持 `/workflow/category/export`。
 - 不迁移 system/user 的用户专属逻辑。
- 保留树表、`expandedRowKeys`、`handleTree` 和分类弹窗逻辑。
+- 保留树表、`useTreeTableExpand`、`handleTree` 和分类弹窗逻辑。

 ## 案例 5：只补 API 和 types

@@ -107,7 +124,7 @@
 2. 新增状态筛选和导出
 3. API 路径沿用后端接口
 4. 参考 system/config 的工具栏与导出交互
-5. 参考 boot4 generator 模板补齐缺失 types
+5. 参考当前项目 gen 模板和 boot4 generator 字段补齐缺失 types
 ```

 ## 不推荐的任务描述
@@ -3,14 +3,15 @@
 ## 优先参考的代码来源

 - 当前目标目录下最近似页面、API、types。
+- 当前仓库内置 React 生成模板：`gen/api.ts.vm`、`gen/types.ts.vm`、`gen/index.vue.vm`、`gen/index-tree.vue.vm`。
 - 标准单表：`src/pages/demo/demo/index.tsx`、`src/api/demo/demo/index.ts`、`src/api/demo/demo/types.ts`。
 - 树表：`src/pages/demo/tree/index.tsx`、`src/pages/workflow/category/index.tsx`。
 - 复杂系统页：`src/pages/system/user/index.tsx`、`src/pages/system/role/index.tsx`、`src/pages/system/post/index.tsx`、`src/pages/system/config/index.tsx`。
 - workflow 页：`src/pages/workflow/*`、`src/api/workflow/*`。
 - 监控页：`src/pages/monitor/*`、`src/api/monitor/*`。
- 公共 hooks：`src/hooks/useTableSelection.ts`、`src/hooks/useTableExport.ts`、`src/hooks/useDict.ts`。
+- 公共 hooks：`src/hooks/useTableSelection.ts`、`src/hooks/useTableExport.ts`、`src/hooks/useDict.ts`、`src/hooks/useDateRangeQuery.ts`、`src/hooks/useTreeTableExpand.ts`、`src/hooks/useLoading.ts`、`src/hooks/useSearchReset.ts`。
 - 公共组件：`src/components/common/RowActions.tsx`、`TreePanel.tsx`、`RightToolbar.tsx`、`DictTag.tsx`、上传/预览组件。
- 工具函数：`src/utils/ruoyi.ts`、`src/utils/permission.ts`、`src/utils/download.ts`。
+- 工具函数：`src/utils/ruoyi.ts`、`src/utils/permission.ts`、`src/utils/download.ts`、`src/utils/dict.ts`、`src/utils/modal.ts`。

 ## 基础栈与格式

@@ -82,13 +83,14 @@
 - `remove` 或 `handleDelete` 支持行删除和批量删除，成功后 `message.success('删除成功')`、`clearSelection()`、`reloadAndRest` 或 `reload`。
 - 批量按钮通常用 `Popconfirm`，行操作确认优先放在 `RowActions` 的 `confirm`。
 - 状态切换失败时要回滚或刷新，参考 `src/pages/system/user/index.tsx`。
- 日期范围查询使用 `formatDateTimeRange` 和 `addDateRange`，参考 `system/user`。
+- 日期范围查询优先使用 `useDateRangeQuery`，底层通过 `addDateRange` 写入 `params.beginXxx/endXxx`。
+- 字典 options 优先使用 `dictOptions(dicts.xxx)`。
 - 导入上传参考 `system/user/components/UserImportModal.tsx` 或流程定义导入弹窗，保留 `globalHeaders()` 和 `appEnv.baseApi` 相关方式。

 ## 字典、权限与公共工具

 - 字典使用 `const dicts = useDict('sys_normal_disable', 'sys_user_gender')`。
- 字典 options 可按 `system/user` 中的 `dictOptions` 函数映射为 `{ label, value }`。
+- 字典 options 使用 `dictOptions` from `@/utils/dict` 映射为 `{ label, value }`。
 - 权限使用：
  `const userInfo = useUserStore(state => state.userInfo);`
  `const canAdd = hasPermi(userInfo, ['system:user:add']);`
@@ -96,6 +98,8 @@
 - 常用工具：
  `hasPermi` from `@/utils/permission`
  `handleTree`、`parseStrEmpty`、`toPageQuery`、`toTableData`、`addDateRange`、`formatDateTimeRange` from `@/utils/ruoyi`
+  `dictOptions` from `@/utils/dict`
+  `confirmAction`、`confirmTitleSafe` from `@/utils/modal`
  `download` via `useTableExport`

 ## 组件与样式规则
@@ -104,6 +108,9 @@
 - 树筛选优先复用 `TreePanel`，参考 `system/user`。
 - 导出优先复用 `useTableExport`。
 - 多选优先复用 `useTableSelection`。
+- 异步 loading 优先复用 `useLoading`，不要重复手写 `setLoading(true)` + `finally setLoading(false)`。
+- ProTable 重置后还要清空额外筛选状态时，优先复用 `useSearchReset`。
+- Promise 式确认框优先复用 `confirmAction` 或 `confirmTitleSafe`。
 - 标准页面尽量使用 `PageContainer`、`ProTable`、ProComponents 页面壳，不堆大量内联样式。
 - 需要自定义布局时先查 `src/assets/styles` 是否已有 `.tree-table-page`、`.table-panel`、`.page-surface` 等类。
 - 不要为了单页需求修改全局组件样式。
@@ -112,22 +119,25 @@

 - 树表列表接口通常返回数组，页面通过 `handleTree<T>(res.data || [], 'id', 'parentId')` 组树。
 - `ProTable` 使用 `pagination={false}`。
- 使用 `expandedRowKeys` 和 `onExpandedRowsChange` 控制展开。
+- 使用 `useTreeTableExpand` 控制 `expandedRowKeys`、`onExpandedRowsChange`、`syncExpandedRows`、`toggleExpandAll`。
 - 展开/折叠按钮参考 `demo/tree` 和 `workflow/category`，用 `SortAscendingOutlined`。
 - 表单中上级节点使用 `ProFormTreeSelect`。
 - 新增子节点时从当前行回填 `parentId`。
 - 删除确认文案优先使用业务名称，而不是批量 ID 文案。

-## 与 Vue 参考项目和生成器模板的关系
+## 与 gen 模板、Vue 参考项目和后端生成器的关系

+- 当前仓库 `gen/*.vm` 是 React 版内置代码生成模板，是维护生成能力时的第一参考。
+- `gen/index.vue.vm`、`gen/index-tree.vue.vm` 文件名为兼容后端 generator 保持不变，但内容必须生成 React TSX 页面。
+- 修改公共 hooks/工具后，如果它们能简化标准生成页，要同步评估 `gen/*.vm` 是否需要更新。
 - Vue skill 和 `.claude/agents` 提供的是任务分型、优先级、增量修改、自检方式，不是 React 实现模板。
- generator 模板可用于确认字段、权限、导出、状态切换、排序、日期范围等，但不是最终答案。
+- boot4 后端 generator 模板可用于确认字段、权限、导出、状态切换、排序、日期范围等，但不是最终答案。
 - 当前 React 项目的核心骨架是 `ProTable`、`ModalForm`、`RowActions`、`useTableSelection`、`useTableExport`。
 - 修改已有页面时，不要把现有强业务逻辑替换回 generator 的简化逻辑。

 ## 验证规则

- 只改文档或 skill：运行 skill 基础校验。
+- 只改文档、skill 或 `gen/*.vm` 模板：至少运行 skill 基础校验或 `git diff --check`；如果模板改动依赖项目工具，优先再跑 `pnpm lint`。
 - 改前端 TS/TSX/API/types：优先运行 `pnpm exec tsc --noEmit` 或 `pnpm lint`。
 - 改页面、import、权限或较多文件：运行 `pnpm lint`。
 - 改公共 hooks、组件、构建相关或大范围页面：再运行 `pnpm build`。