init

2026-09-27 10:15:49 +08:00
commit 368e80f6bf
418 changed files with 45822 additions and 0 deletions
--- a/.codex/skills/frontend-crud-coding/SKILL.md
+++ b/.codex/skills/frontend-crud-coding/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: frontend-crud-coding
+description: 在 plus-ui 前端项目中按真实 Vue 3 + TypeScript + Element Plus + oxlint/oxfmt 代码风格生成或修改页面、API、types、hooks 接入和样式壳。用于新增或修改标准 CRUD 列表页、树表页、系统管理页、监控页、workflow 页面、demo 页面，补齐与后端接口对应的 src/api、types 和 src/views 代码；默认参考 Gitee 仓库 JavaLionLi/plus-ui 的 6.X-Vue 分支，触发后应先读取适用 references，再阅读目标模块真实代码和项目内 gen 代码生成模板。
+---
+
+# 前端编码规范
+
+先对齐当前前端项目里的真实实现，再参考项目内 `gen` 目录下的代码生成模板。不要只套通用 Vue 模板，也不要把 generator 模板原样复制进来而忽略当前项目已经演进出的 hooks、页面壳、类型入口和下载方式。
+
+## 项目基线
+
+- 基线仓库：`https://gitee.com/JavaLionLi/plus-ui`
+- 默认分支：`6.X-Vue`
+- 远端引用必须同时标记仓库、分支和文件路径，例如 `https://gitee.com/JavaLionLi/plus-ui/blob/6.X-Vue/gen/index.vue.ftl` 或 `branch=6.X-Vue, path=gen/index.vue.ftl`。
+- 不要在 skill、reference 或 agent 文档中写本机绝对路径；本地文件读取以运行时工作目录为准。
+- 如果用户指定其他分支，先按用户分支读取同一仓库的对应文件，并在结果中说明使用的分支。
+
+## 执行流程
+
+1. 判断任务类型：新增标准 CRUD、树表、已有页面增强、复杂业务页、只补 API/types。
+2. 按“文档读取规则”读取必要 reference，不一次性展开所有资料。
+3. 阅读目标目录下最近似的真实代码：
+   - 标准单表优先看 `src/views/demo/demo/index.vue`、`src/api/demo/demo/*`。
+   - 树表优先看 `src/views/demo/tree/index.vue`、`src/views/workflow/category/index.vue`。
+   - 系统复杂页优先看 `src/views/system/user/index.vue`、`system/role`、`system/post`、`system/config`。
+   - workflow 业务页优先看 `src/views/workflow/*` 同类页面。
+4. 新增标准页面前，对照项目内模板确认基础骨架：
+   - API 模板：`gen/api.ts.ftl`
+   - types 模板：`gen/types.ts.ftl`
+   - 标准单表页模板：`gen/index.vue.ftl`
+   - 树表页模板：`gen/index-tree.vue.ftl`
+5. 新增代码时通常同步维护 `src/api/<module>/<business>/index.ts`、`types.ts`、`src/views/<module>/<business>/index.vue`。
+6. 增强已有页面时只做增量修改，保留原页面的树筛选、导入导出、列显隐、权限、字典、弹窗和路由跳转能力。
+7. 修改完成后按影响范围运行验证：优先 `pnpm exec vue-tsc --noEmit`，改动页面或导入时再跑 `pnpm lint`，大范围变更再跑 `pnpm build`。
+
+## 文档读取规则
+
+- 前端 API、types、页面、hooks、样式和验证规则，先读 [references/frontend.md](references/frontend.md)。
+- 不确定任务边界、需要标准用例或提问方式时，再读 [references/examples.md](references/examples.md)。
+- reference 只约束实现方式和自检范围；发生冲突时，以当前模块真实代码和实际调用点为准。
+
+## 优先级规则
+
+发生冲突时按下面顺序决策：
+
+1. 目标目录下最近似页面、API、types 的真实实现。
+2. 当前项目公共 hooks、组件、工具和样式约定。
+3. 项目内 `gen` 代码生成模板。
+4. 通用 Vue 3 / Element Plus 习惯。
+
+也就是说：
+
+- 同模块已有页面怎么写，优先怎么写。
+- 没有现成页面时，使用项目内 `gen` 模板作为骨架，再改成当前项目风格。
+- 复杂模块不能为了“标准 CRUD”退化成裸模板页。
+
+## 仓库通用规则
+
+- 遵循 [`.editorconfig`](../../../.editorconfig)：UTF-8、LF、2 空格缩进；Markdown 例外。
+- 当前仓库没有 `.prettierrc`，格式脚本是 `pnpm run fmt` 调用 `oxfmt .`，lint 脚本是 `pnpm lint` 调用 `oxlint src`。
+- 页面优先使用 `<script setup name="Xxx" lang="ts">`。
+- API 返回类型优先从 `@/utils/api-types` 引入 `AxiosPromise`，分页结果从 `@/api/types` 引入 `PageResult`。
+- 请求统一通过 `@/utils/request`，导出下载使用 `import { download as requestDownload } from '@/utils/request';`。
+- 标准列表页优先复用 `useLoading`、`useSearchToggle`、`useSearchReset`、`useTableSelection`、`useFormDialog`、`useDateRangeQuery`。
+- 页面壳优先使用 `p-2 app-container <module>-<business>-page`、`search-panel`、`toolbar-shell`、`data-table`、`right-toolbar`、`pagination`。
+- 新页面不要无故引入另一套状态管理、请求封装、样式体系或权限写法。
+
+## 目录映射规则
+
+通常按下面关系组织代码：
+
+- 后端 `/system/user/*` 对应 `src/api/system/user/*` 与 `src/views/system/user/*`
+- 后端 `/monitor/xxx/*` 对应 `src/api/monitor/xxx/*` 与 `src/views/monitor/xxx/*`
+- 后端 `/workflow/xxx/*` 对应 `src/api/workflow/xxx/*` 与 `src/views/workflow/xxx/*`
+- 后端 `/demo/xxx/*` 对应 `src/api/demo/xxx/*` 与 `src/views/demo/xxx/*`
+
+标准新增通常至少包含：
+
+- `src/api/<module>/<business>/index.ts`
+- `src/api/<module>/<business>/types.ts`
+- `src/views/<module>/<business>/index.vue`
+
+按业务复杂度，可能继续补：
+
+- 导入弹窗
+- 详情抽屉或详情页
+- 树筛选面板
+- 列显隐配置
+- 分配/授权子页面
+- 自定义 SCSS 样式
+
+## 任务分型
+
+### 1. 标准单表 CRUD
+
+以 `gen/index.vue.ftl`、`gen/api.ts.ftl`、`gen/types.ts.ftl` 和 `src/views/demo/demo/index.vue` 为主要起点，补齐列表、搜索、分页、新增、编辑、删除、导出、权限、类型和验证。
+
+### 2. 树表 CRUD
+
+以 `src/views/demo/tree/index.vue`、`src/views/workflow/category/index.vue` 为主要起点。列表接口通常返回数组而不是 `PageResult`，页面使用 `handleTree`、`useTreeTableExpand`，`Query` 通常不继承 `PageQuery`。
+
+### 3. 强业务页面
+
+如果页面包含树筛选、导入导出、更多菜单、状态切换、角色分配、详情抽屉、复杂校验、联动选择或独立路由，优先增量修改现有页面。不要重写成简单 CRUD。
+
+### 4. 工作流页面
+
+workflow 目录优先参考 `src/views/workflow/*`。流程定义、流程实例、任务列表、请假申请等页面通常有业务按钮、弹窗和路由跳转，不要硬套 system 模块。
+
+### 5. 只补 API 和 types
+
+只维护 `src/api/<module>/<business>/index.ts` 与 `types.ts`，但仍要与后端路由、返回结构、当前模块导入方式和类型入口一致。
+
+## 输出要求
+
+使用本 skill 时，默认期望产出应满足：
+
+- 类型完整，不把页面逻辑大量写成 `any`。
+- API 路径、函数名、权限标识与后端接口保持一致。
+- 标准页查询、重置、分页、弹窗、提交、删除、导出流程闭环完整。
+- 复杂页面保留原有交互能力和业务约束。
+- 代码体现当前项目 hooks、页面壳和下载方式，而不是 `gen` 模板裸输出。
+- 交付前说明运行过的验证命令；如果无法验证，说明原因。
+
+## 快速检查清单
+
+- `AxiosPromise` 是否来自 `@/utils/api-types`。
+- `PageResult` 是否来自 `@/api/types`。
+- API `params` 和 `data` 是否与后端方法一致。
+- 日期范围是否通过 `useDateRangeQuery` 或附近页面现有方式处理。
+- 列表 loading 是否通过 `useLoading` 或原页面方式维护。
+- 弹窗是否通过 `useFormDialog` 或原页面方式维护。
+- 多选状态是否通过 `useTableSelection` 或原页面方式维护。
+- 权限指令是否保持同文件一致，默认使用当前项目主流 `v-hasPermi`。
+- 导出是否使用 `requestDownload('<module>/<business>/export', { ...queryParams.value }, '<name>_<time>.xlsx')`。
+- 页面壳是否保留 `search-panel`、`table-panel`、`toolbar-shell`、`data-table`、`right-toolbar`、`pagination`。
+
+## 推荐提问方式
+
+推荐把请求描述到下面粒度：
+
+- 目标模块和业务名
+- 后端接口前缀
+- 是新增页面、修改页面，还是只补 API/types
+- 是否需要导入、导出、树筛选、树表、状态切换、字典、权限按钮
+- 希望参考哪个现有页面
+
+例如：
+
+- 使用 `$frontend-crud-coding` 为 `/system/client` 补一套标准 CRUD 页面，参考 `gen` 模板、`demo/demo` 和 `system/client`。
+- 使用 `$frontend-crud-coding` 修改 `workflow/category` 列表页，增加导出按钮和状态筛选，保持当前 workflow 风格。
--- a/.codex/skills/frontend-crud-coding/agents/openai.yaml
+++ b/.codex/skills/frontend-crud-coding/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+  display_name: "前端编码"
+  short_description: "按 plus-ui 6.X-Vue 真实代码和 gen 模板编写前端 CRUD"
+  default_prompt: "使用 $frontend-crud-coding 先读取适用 reference，再按 plus-ui Gitee 仓库 6.X-Vue 分支的真实页面、hooks、API/types 约定和项目内 gen 模板实现前端修改。"
+
+policy:
+  allow_implicit_invocation: true
--- a/.codex/skills/frontend-crud-coding/references/examples.md
+++ b/.codex/skills/frontend-crud-coding/references/examples.md
@@ -0,0 +1,126 @@
+# 使用案例
+
+## 案例 1：新增标准 CRUD 页面
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 为 system/client 补一套前端 CRUD 页面。
+后端接口已经有 /system/client/list、/system/client/{id}、POST /system/client、PUT /system/client、DELETE /system/client/{ids}。
+请参考 plus-ui Gitee 仓库 6.X-Vue 分支的项目内 gen 模板、src/views/demo/demo/index.vue 和现有 system/client 风格实现。
+```
+
+### 期望执行方式
+
+- 先看 `src/api/system/client/*` 和 `src/views/system/client/index.vue` 是否已存在。
+- 再看 `src/views/demo/demo/index.vue` 的标准 hooks 版 CRUD 骨架。
+- 对照项目内 `gen/api.ts.ftl`、`gen/types.ts.ftl`、`gen/index.vue.ftl`。
+- 生成或修改 `api/index.ts`、`types.ts`、`views/.../index.vue`。
+- 使用 `AxiosPromise` from `@/utils/api-types`、`PageResult` from `@/api/types`、`useLoading`、`useFormDialog`、`useSearchReset`、`useTableSelection`。
+
+## 案例 2：新增树表页面
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 为 demo/tree2 新增树表 CRUD，接口返回数组，字段包含 id、parentId、name、orderNum。
+参考 src/views/demo/tree/index.vue 和 workflow/category。
+```
+
+### 期望执行方式
+
+- 优先判断这是树表，不生成分页 `PageResult` 页面。
+- API 列表返回 `AxiosPromise<Tree2VO[]>`。
+- `Query` 不继承 `PageQuery`。
+- 页面使用 `handleTree`、`row-key`、`tree-props`、`useTreeTableExpand`、`el-tree-select`。
+- 新增子节点时从当前行带入 `parentId`。
+
+## 案例 3：修改已有复杂列表页
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 修改 system/user 页面：
+1. 新增一个创建时间快捷筛选
+2. 导出按钮保留在更多菜单中
+3. 保持现有树筛选、导入、列显隐、详情抽屉和角色分配不变
+```
+
+### 期望执行方式
+
+- 判断这是“已有复杂页面增强”，不是重新生成 CRUD。
+- 优先阅读 `src/views/system/user/index.vue`。
+- 保留 `TreePanel`、导入弹窗、`right-toolbar` 列显隐、`UserViewDrawer`、角色分配路由、权限控制。
+- 只增量修改搜索和查询参数处理。
+
+## 案例 4：修改 workflow 页面
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 为 workflow/category 增加状态筛选和导出按钮，保持 workflow 模块自己的树表风格。
+```
+
+### 期望执行方式
+
+- 优先看 `src/views/workflow/category/index.vue` 和 `src/api/workflow/category/*`。
+- 判断是否需要后端新增导出接口；前端导出路径保持 `workflow/category/export`。
+- 不迁移 system/user 的用户专属逻辑。
+- 保留树表、`useTreeTableExpand`、`handleTree` 和分类弹窗逻辑。
+
+## 案例 5：只补 API 和 types
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 为 monitor/cache 补全前端 API 和 types，页面先不改。
+```
+
+### 期望执行方式
+
+- 只维护 `src/api/monitor/cache/index.ts` 和 `src/api/monitor/cache/types.ts`。
+- 仍然检查同目录 monitor API 的 `export function` / `export const` 风格。
+- 返回类型使用 `AxiosPromise` from `@/utils/api-types`。
+- 不创建页面，不改路由。
+
+## 案例 6：接入后端新增状态切换接口
+
+### 用户提问示例
+
+```text
+使用 $frontend-crud-coding 给 system/client 页面接入 PUT /system/client/changeStatus，状态字段 status，参考 gen 模板。
+```
+
+### 期望执行方式
+
+- API 增加 `changeClientStatus(id, status)`。
+- types 确认 `status` 类型是 string、number 还是 boolean。
+- 表格列用 `el-switch`，active/inactive 值跟后端字段类型一致。
+- 切换失败时回滚原状态。
+- 权限使用 `system:client:edit` 或后端实际权限。
+
+## 推荐的高质量任务描述
+
+```text
+使用 $frontend-crud-coding 在当前前端项目中新增 `/system/notice` 列表页增强：
+1. 保留现有页面
+2. 新增状态筛选和导出
+3. API 路径沿用后端接口
+4. 参考 system/config 的工具栏与导出交互
+5. 参考 plus-ui Gitee 仓库 6.X-Vue 分支的 gen 模板补齐缺失 types
+```
+
+## 不推荐的任务描述
+
+```text
+帮我写个后台页面
+```
+
+更好的写法至少补充：
+
+- 模块名
+- 业务名
+- 后端接口前缀
+- 是新增还是修改
+- 是否需要分页、导出、树表、字典、权限
+- 想参考哪个现有页面
--- a/.codex/skills/frontend-crud-coding/references/frontend.md
+++ b/.codex/skills/frontend-crud-coding/references/frontend.md
@@ -0,0 +1,156 @@
+# 前端约定
+
+## 优先参考的代码来源
+
+- 默认远端基线：`https://gitee.com/JavaLionLi/plus-ui`，分支 `6.X-Vue`。引用远端文件时必须同时写明 `branch=6.X-Vue` 和仓库内路径。
+- 当前目标目录下最近似页面、API、types。
+- 标准单表：`src/views/demo/demo/index.vue`、`src/api/demo/demo/index.ts`、`src/api/demo/demo/types.ts`。
+- 树表：`src/views/demo/tree/index.vue`、`src/views/workflow/category/index.vue`。
+- 复杂系统页：`src/views/system/user/index.vue`、`src/views/system/role/index.vue`、`src/views/system/post/index.vue`、`src/views/system/config/index.vue`。
+- workflow 页：`src/views/workflow/*`、`src/api/workflow/*`。
+- 监控页：`src/views/monitor/*`、`src/api/monitor/*`。
+- 公共 hooks：`src/hooks/async/useLoading.ts`、`src/hooks/dialog/*`、`src/hooks/form/*`、`src/hooks/table/*`、`src/hooks/tree/*`。
+- 项目内 generator 模板：
+  `gen/api.ts.ftl`
+  `gen/types.ts.ftl`
+  `gen/index.vue.ftl`
+  `gen/index-tree.vue.ftl`
+
+## 基础栈与格式
+
+- 技术栈是 Vue 3 + TypeScript + Element Plus + Vite + Pinia。
+- 包管理按仓库现状使用 pnpm。
+- `.editorconfig` 要求 UTF-8、LF、2 空格缩进。
+- 当前仓库没有 `.prettierrc`；格式化使用 `pnpm run fmt`，lint 使用 `pnpm lint`。
+- 不要在一个页面里混入与仓库不一致的格式和写法。
+- 不要把本机绝对路径写进 skill 输出或参考文档；跨环境参考统一使用 Gitee 仓库 URL、分支和仓库内相对路径。
+
+## API 文件规则
+
+- 标准 API 文件放在 `src/api/<module>/<business>/index.ts`，同目录维护 `types.ts`。
+- import 顺序优先跟随附近文件，标准生成页常见形式：
+  `import type { XxxForm, XxxQuery, XxxVO } from '@/api/<module>/<business>/types';`
+  `import type { PageResult } from '@/api/types';`
+  `import type { AxiosPromise } from '@/utils/api-types';`
+  `import request from '@/utils/request';`
+- 不要从 `axios` 引入 `AxiosPromise`。
+- 列表分页接口通常返回 `AxiosPromise<PageResult<XxxVO>>`。
+- 树表列表接口通常返回 `AxiosPromise<XxxVO[]>`。
+- 详情接口返回 `AxiosPromise<XxxVO>`；复杂详情返回单独的 `InfoVO`。
+- 标准函数命名：
+  `listXxx` -> `GET /<module>/<business>/list`
+  `getXxx` -> `GET /<module>/<business>/{id}`
+  `addXxx` -> `POST /<module>/<business>`
+  `updateXxx` -> `PUT /<module>/<business>`
+  `delXxx` -> `DELETE /<module>/<business>/{id or ids}`
+  `changeXxxStatus` -> `PUT /<module>/<business>/changeStatus`
+- query string 用 `params`，请求体用 `data`。
+- 加密、防重复提交等 headers 直接写在请求配置里，例如用户重置密码中的 `isEncrypt`、`repeatSubmit`。
+- 当前仓库有些 API 使用 `export const`，有些使用 `export function`；新增标准 CRUD 优先跟随 `gen/api.ts.ftl` 和相邻模块。
+- 只有相邻模块已有 `export default { ... }` 聚合时才新增默认导出。
+
+## 类型文件规则
+
+- 标准类型定义 `VO`、`Form`、`Query`，必要时补 `InfoVO`、`TreeVO`、`ResetPwdForm` 等扩展类型。
+- `Form` 通常继承 `BaseEntity`。
+- 非树表 `Query` 通常继承 `PageQuery`。
+- 树表 `Query` 通常不继承 `PageQuery`。
+- ID 字段通常使用 `string | number`，批量删除参数使用 `string | number | Array<string | number>`。
+- Java 数值类型映射为 `number`，Boolean 映射为 `boolean`，日期/文本默认 `string`。
+- 日期范围查询保留 `params?: any`，不要因为它看起来宽松就删掉。
+- 列表对象、表单对象、查询对象职责分开；字段不一致时不要强行复用一个接口。
+- 能明确写出类型时不要用 `any`；组件库、字典或历史接口确实无法收窄时再保留。
+
+## Vue 页面结构规则
+
+- 页面优先使用 `<script setup name="Xxx" lang="ts">`。
+- 标准根节点使用 `class="p-2 app-container <module>-<business>-page"`；已有页面是特殊布局时保持原样。
+- 标准列表页结构：
+  搜索卡片 `search-panel`
+  表格卡片 `table-panel`
+  工具栏 `toolbar-shell`
+  表格 `data-table`
+  `right-toolbar`
+  `pagination`
+  新增/编辑 `el-dialog`
+- 搜索区通过 `useSearchToggle` 控制 `showSearch`，头部点击切换。
+- 列表 loading 通过 `useLoading(true)` 和 `withLoading`。
+- 选择状态通过 `useTableSelection<XxxVO>(item => item.id)` 返回 `ids`、`single`、`multiple`、`handleSelectionChange`。
+- 表单弹窗优先使用 `useFormDialog({ form, formRef, initialFormData })`，返回 `dialog`、`resetForm`、`openDialog`、`showDialog`、`closeDialog`。
+- 仅需要简单弹窗状态或一个页面多个弹窗时使用 `useDialogState`。
+- 日期范围查询优先使用 `useDateRangeQuery()`；带后端参数名时使用 `useDateRangeQuery('CreateTime')` 等相邻页面模式。
+- 查询和表单状态通常放在 `reactive<PageData<Form, Query>>({ form, queryParams, rules })`，再 `toRefs(data)`。
+
+## 页面行为规则
+
+- `getList` 负责设置 loading、调用列表接口、回填列表和 `total`。
+- `handleQuery` 先把 `queryParams.value.pageNum = 1`，再调用 `getList()`；树表无分页时只调用 `getList()`。
+- `resetQuery` 使用 `useSearchReset`，分页页传 `pageNumKey: 'pageNum'`，需要时传 `pageSizeKey` 和 `resetExtras`。
+- `handleAdd` 使用 `openDialog('添加xxx')`；如果有树/联动选项，打开前后按现有页面加载选项。
+- `handleUpdate` 先 `reset()`，再按行或 `ids.value[0]` 查详情，`Object.assign(form.value, res.data)`，最后 `showDialog('修改xxx')`。
+- `submitForm` 表单校验通过后设置 `buttonLoading`，根据主键判断新增或修改，成功后 `modal.msgSuccess('操作成功')`、关闭弹窗、刷新列表。
+- `handleDelete` 使用 `modal.confirm(...)` 二次确认，再调用删除接口，成功提示并刷新。
+- `handleExport` 使用 `requestDownload('<module>/<business>/export', { ...queryParams.value }, '<business>_<timestamp>.xlsx')`。
+- 状态切换失败时要把 switch 值回滚，参考 generator 模板和现有 `system/user`、`system/role`。
+- 导入上传使用 `globalHeaders()`、`import.meta.env.VITE_APP_BASE_API`、`ElUpload`，优先参考 `system/user` 或流程定义页面。
+
+## 字典、权限与公共工具
+
+- 字典使用 `useDict`：
+  `const { sys_normal_disable } = toRefs<any>(useDict('sys_normal_disable'));`
+- 新增代码默认使用当前项目主流 `v-hasPermi`。
+- 如果正在修改的文件已经混用或使用 `v-has-permi`，保持同文件现状，不为统一写法而重排无关代码。
+- `el-dropdown-item` 延迟加载导致权限指令不可靠时，使用 `v-if="checkPermi([...])"`，参考 `system/user`。
+- 常用工具：
+  `modal` from `@/plugins/modal`
+  `download as requestDownload` from `@/utils/request`
+  `useDict` from `@/utils/dict`
+  `checkPermi` from `@/utils/permission`
+  `handleTree`、`parseStrEmpty` from `@/utils/ruoyi`
+
+## 组件与样式规则
+
+- 优先复用公共组件：`right-toolbar`、`pagination`、`DictTag` / `dict-tag`、`ImageUpload` / `image-upload`、`ImagePreview` / `image-preview`、`FileUpload` / `file-upload`、`Editor` / `editor`、`TreePanel`。
+- 标准页面尽量使用已有页面壳类，不堆大量内联样式。
+- 复杂页面需要 scoped SCSS 时优先复用：
+  `@use '@/assets/styles/components/page-shell' as pageShell;`
+  再按现有 mixin 使用。
+- 不要为了单页需求修改全局组件样式。
+- 类名保持模块语义：`system-client-page`、`workflow-category-page`、`demo-demo-page`。
+
+## 树表规则
+
+- 树表列表接口通常返回数组，页面通过 `handleTree<T>(res.data, 'id', 'parentId')` 组树。
+- 使用 `row-key`、`:tree-props="{ children: 'children', hasChildren: 'hasChildren' }"`。
+- 展开/折叠使用 `useTreeTableExpand`。
+- 表单中上级节点使用 `el-tree-select`。
+- 新增子节点时从当前行回填 `parentId`。
+- 删除确认文案优先使用业务名称，而不是批量 ID 文案。
+
+## 与 gen 模板的关系
+
+- `gen` 是 plus-ui 前端项目内的生成模板；默认远端位置是 `https://gitee.com/JavaLionLi/plus-ui/tree/6.X-Vue/gen`，分支必须标记为 `6.X-Vue`。
+- 本地仓库存在对应文件时优先读本地 `gen`，但不要把本地绝对路径写入 skill 或交付内容。
+- 新增标准单表页面时读取 `gen/index.vue.ftl`、`gen/api.ts.ftl`、`gen/types.ts.ftl`。
+- 新增树表页面时读取 `gen/index-tree.vue.ftl`、`gen/api.ts.ftl`、`gen/types.ts.ftl`。
+- `gen` 模板是标准骨架，不是最终答案；落地时仍要对照目标模块真实页面和公共 hooks。
+- 当前前端项目已经把生成页升级为 hooks 版：`useLoading`、`useFormDialog`、`useSearchReset`、`useTableSelection`、`useDateRangeQuery`。
+- 新增标准 CRUD 时，先从 `gen` 确认字段、权限、导出、状态切换、排序、日期范围等，再落成当前项目的实际页面壳。
+- 修改已有页面时，不要把现有强业务逻辑替换回 `gen` 的简化逻辑。
+
+## 验证规则
+
+- 只改文档或 skill：运行 skill 基础校验即可。
+- 改前端 TS/Vue/API/types：优先运行 `pnpm exec vue-tsc --noEmit`。
+- 改页面模板、import、权限或较多文件：再运行 `pnpm lint`。
+- 改公共 hooks、组件、构建相关或大范围页面：再运行 `pnpm build`。
+- 如果验证因为环境、依赖或权限失败，交付时说明失败命令和原因。
+
+## 避免事项
+
+- 不要从 `axios` 引入 `AxiosPromise`。
+- 不要绕开 `request` 或 `requestDownload` 自造请求/下载封装。
+- 不要跳过 `types.ts`，把类型全写在页面里。
+- 不要删除日期范围 `params`、权限指令、导出、导入、树筛选、列显隐等现有能力。
+- 不要为了“更整洁”重写复杂页面的大块业务逻辑。
+- 不要在新增标准页里使用与仓库不一致的 UI 壳或状态管理方式。