@agile-team/wl-skills-kit 2.5.2 → 2.7.0

package/files/.github/skills/core/business-doc-extract/templates/module-index.md

@@ -0,0 +1,67 @@
+<!--
+模板：docs/business/0X-xxx/index.md（模块全景）
+使用：business-doc-extract Skill 在 module 模式下生成或刷新。
+约束：仅放“模块定位 + 子功能清单 + 页面/API 索引 + 模块链路摘要”。
+     详细需求 / 字段 / 字典放在 requirement.md / field.md / dictionary.md。
+-->
+
+# {{ModuleName}}
+
+> **代码目录**：`src/views/{{module-path}}`
+> **文档目录**：`docs/business/0X-{{module-kebab}}/`
+> **最近更新**：{{UpdatedAt}}
+
+---
+
+## 1. 模块定位
+
+{{ModulePositioning}}
+
+---
+
+## 2. 子功能清单
+
+| 功能 | 说明 | 状态 |
+|---|---|---|
+| {{Feature1}} | {{Desc1}} | {{Status1}} |
+| {{Feature2}} | {{Desc2}} | {{Status2}} |
+
+---
+
+## 3. 页面与 API 索引
+
+> 详细接口契约位于页面目录的 `api.md`，本表只做导航。
+
+| 页面 | 代码目录 | API 契约 | 实现状态 |
+|---|---|---|---|
+| {{Page1Name}} | `src/views/{{page1-path}}` | [`api.md`](../../../src/views/{{page1-path}}/api.md) | {{Status1}} |
+| {{Page2Name}} | `src/views/{{page2-path}}` | [`api.md`](../../../src/views/{{page2-path}}/api.md) | {{Status2}} |
+
+---
+
+## 4. 模块链路摘要
+
+```mermaid
+flowchart TD
+  A[{{Step1}}] --> B[{{Step2}}]
+  B --> C[{{Step3}}]
+```
+
+> 完整业务流程详见 [`requirement.md`](./requirement.md)。
+
+---
+
+## 5. 关联模块
+
+| 模块 | 关系 |
+|---|---|
+| {{RelatedModule}} | {{Relation}} |
+
+---
+
+## 6. 模块导航
+
+- 需求理解：[`requirement.md`](./requirement.md)
+- 字典枚举：[`dictionary.md`](./dictionary.md)
+- 字段清单：[`field.md`](./field.md)
+- 全局待确认：[`../open-questions.md`](../open-questions.md)

package/files/.github/skills/core/business-doc-extract/templates/module-requirement.md

@@ -0,0 +1,101 @@
+<!--
+模板：docs/business/0X-xxx/requirement.md（模块需求理解）
+使用：business-doc-extract Skill 在 module / incremental 模式下生成或更新。
+约束：流程图、页面清单、模块待确认事项都放在本文件，不再单独建 flow.md / pages.md / open-questions.md。
+     全局 open-questions.md 由 Skill 汇总，不在本文件维护汇总表。
+-->
+
+# {{ModuleName}}：需求理解
+
+---
+
+## 1. 需求来源
+
+| 来源类型 | 路径或说明 |
+|---|---|
+| 原型 | {{PrototypePath}} |
+| 详设 | {{SpecPath}} |
+| 现有代码 | `src/views/{{module-path}}` |
+| 后端字段实体 | {{EntityPath}} |
+| 字典资料 | {{DictPath}} |
+
+---
+
+## 2. 业务目标
+
+{{BusinessGoal}}
+
+---
+
+## 3. 角色与权限
+
+| 角色 | 可操作内容 | 备注 |
+|---|---|---|
+| {{Role1}} | {{Operation1}} | {{Note1}} |
+| {{Role2}} | {{Operation2}} | {{Note2}} |
+
+---
+
+## 4. 功能范围
+
+| 功能 | 说明 | 是否本期 | 备注 |
+|---|---|---|---|
+| {{Feature1}} | {{Desc1}} | 是 / 否 | {{Note1}} |
+
+---
+
+## 5. 核心业务流程
+
+```mermaid
+flowchart TD
+  A[{{Step1}}] --> B[{{Step2}}]
+  B --> C[{{Step3}}]
+```
+
+> 多个流程时按子标题拆分，例如 `5.1 主流程`、`5.2 异常流程`。
+
+---
+
+## 6. 页面清单
+
+| 页面 | 原型 / 详设来源 | 代码路径 | 实现状态 | 备注 |
+|---|---|---|---|---|
+| {{Page1}} | {{Source1}} | `src/views/{{page1-path}}` | {{Status1}} | {{Note1}} |
+| {{Page2}} | {{Source2}} | `src/views/{{page2-path}}` | {{Status2}} | {{Note2}} |
+
+> 详细接口契约见对应页面目录下的 `api.md`。
+
+---
+
+## 7. 业务规则
+
+| 规则 | 说明 |
+|---|---|
+| {{Rule1}} | {{Desc1}} |
+| {{Rule2}} | {{Desc2}} |
+
+---
+
+## 8. 异常规则
+
+| 场景 | 处理方式 |
+|---|---|
+| {{Exception1}} | {{Handling1}} |
+
+---
+
+## 9. 模块待确认事项
+
+> 仅维护本模块的待确认事项；全局视图见 `docs/business/open-questions.md`。
+
+| 编号 | 问题 | 影响 | 建议确认人 | 优先级 | 状态 |
+|---|---|---|---|---|---|
+| Q-{{Module}}-001 | {{Question}} | {{Impact}} | 产品 / 后端 / 前端 | 高 / 中 / 低 | 待确认 |
+
+---
+
+## 10. 变更记录
+
+| 日期 | 摘要 | 操作人 |
+|---|---|---|
+| {{Date}} | {{Summary}} | {{Operator}} |

package/files/.github/skills/ops/code-fix/USAGE.md

@@ -0,0 +1,131 @@
+# 使用指南：code-fix（受控自动修复）
+
+> **谁读这个文档**：团队成员（前端 / 接手老项目时）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+`convention-audit` 跑完会生成 `reports/规范审查报告.md`，里面列出 N 条偏差，按 🔴/🟡/🟢 分级。如果手动一条一条改，效率很低；但**全量交给 AI 自动改**又会引入隐性破坏。
+
+`code-fix` 的定位是：**只修 🟡 / 🟢 级偏差，且每条都要 diff 预览 + 用户确认**。
+
+---
+
+## 何时使用
+
+- `convention-audit` 报告里堆积了大量 🟡 / 🟢 偏差（如缺 `:scoped` / 缺 `cid` / 缺导入顺序等）
+- 接手老项目，想批量整改 ESLint 之外的项目内规范
+- PR 评审前快速把"低风险偏差"清干净，让 reviewer 只看业务逻辑
+
+**不适用场景**：
+
+- 🔴 严重偏差（结构错误 / 用错组件 / 接口契约不符等）→ 用 `page-codegen` 重新生成或人工重写
+- 业务逻辑变更 → code-fix 不参与；这是 PR 的活
+- 没跑过 `convention-audit` → 必须先有报告，code-fix 不会自己扫代码
+
+---
+
+## 触发关键词
+
+`自动修复` / `整改偏差` / `修复报告` / `规范整改` / `code fix`
+
+---
+
+## 前置条件
+
+1. 项目根有 `reports/规范审查报告.md`（来自 `convention-audit` 的最新一次输出）
+2. 报告里 issue 项明确（含 issueId / 文件路径 / 行号 / 偏差类型）
+
+---
+
+## 标准对话示例
+
+```
+你：把规范审查报告里 🟡 级的偏差都修一下
+AI：[Pre-flight]
+    步骤 1：读取 reports/规范审查报告.md，识别到：
+       - 🔴 严重 3 项（不修）
+       - 🟡 中 12 项（可修）
+       - 🟢 低 8 项（可修）
+    步骤 2：本次修复目标：12 + 8 = 20 项
+    步骤 3：分组展示前 5 项 diff：
+
+       [issue-001] src/views/sale/order/index.vue:24
+       - <style lang="scss">
+       + <style lang="scss" scoped>
+
+       [issue-002] src/views/sale/order/index.vue:80
+       - <BaseTable :columns="columns" />
+       + <BaseTable :cid="ORDER_CID" :columns="columns" />
+
+       ... (再展示 3 项)
+
+    [需你确认] 这 5 项 yes 后继续看后续 15 项？逐组 yes/no？
+你：yes，全部一起改了吧
+AI：执行第 1 组（5 项）写入 → 标记报告条目为 ✅ 已修复 → 显示下一组
+    ...
+```
+
+---
+
+## 输出物
+
+1. **修改后的源文件**（每条 issue 命中的文件被精准 patch）
+2. **报告条目状态更新**：`reports/规范审查报告.md` 中对应 issueId 标记为 ✅ 已修复 + 时间戳
+3. **修复摘要**（可选）：`reports/CODE_FIX_<YYYYMMDD>.md` —— 本次共修复 N 项，按文件聚合
+
+---
+
+## 受控原则（严格执行）
+
+| 原则 | 说明 |
+|---|---|
+| **不修 🔴** | 严重偏差必须人工或 page-codegen 处理，code-fix 不介入 |
+| **不破坏功能** | 只改报告点名的行，不顺手"重构"周边代码 |
+| **不批量盲改** | 每个文件都先 diff 预览，禁止跳过用户确认 |
+| **不生成新逻辑** | 只修偏差，不做功能补全（那是 page-codegen 的职责） |
+| **范围明确** | 若用户引导修改业务逻辑，必须拒绝并说明原因 |
+
+---
+
+## 常见踩坑
+
+| 现象 | 原因 | 解法 |
+|---|---|---|
+| diff 看着对，但 lint 又报新错 | 修复策略与项目 ESLint 配置不一致 | 先跑 `npm run lint` 看新报错；调整 SKILL 里的 rule-based 策略 |
+| 报告里 issueId 被改回去了 | code-fix 修完后又有人手工改回旧写法 | PR 评审环节加"不要逆向修改"约束 |
+| AI 想"顺手优化"周边逻辑 | 模型主动性过强 | 在指令里加"严格按 issueId 修复，不做其他改动" |
+| 两次 code-fix 的 diff 不一致 | 中间 convention-audit 没重跑 | code-fix 之前必须先 audit，保证报告是最新快照 |
+
+---
+
+## 团队协作流程
+
+```
+[每次 PR 之前]
+1. wl-skills validate-page <修改过的页面>      # 单页快速校验
+2. convention-audit                             # 生成最新偏差报告
+3. code-fix                                      # 修 🟡/🟢
+4. 再跑一次 convention-audit                     # 复扫确认 🟡/🟢 → 0
+5. PR 提交（reviewer 只看 🔴 处理 + 业务逻辑）
+```
+
+> 复扫这一步**必做**：避免 code-fix 改完之后又引入新偏差。
+
+---
+
+## FAQ
+
+**Q：能跳过用户确认直接全部改吗？**
+A：**不允许**。code-fix 的核心定位就是"受控"，跳过确认会变成黑盒整改。要全自动请用 ESLint --fix。
+
+**Q：和 ESLint --fix 有什么区别？**
+A：ESLint 修语法/格式（自动化没风险），code-fix 修**项目内规范**（如 cid/operations/`:scoped`/导入顺序/AGGrid 写法 等 ESLint 不覆盖的规则）。两者互补，建议先 ESLint 再 code-fix。
+
+**Q：code-fix 改完会不会破坏 mock-first？**
+A：不会。code-fix 只动报告点名的行，mock-first 相关字段（`API_CONFIG.useMock` 等）不在受控修复范围。
+
+**Q：和 page-codegen 重新生成有什么区别？**
+A：`page-codegen` 是"重写整个页面骨架"，适合 🔴 级整页结构错误；`code-fix` 是"按 issue 精准修",  适合 🟡/🟢 级零碎偏差。两者互补，混用即可。

package/files/.github/skills/sync/dict-sync/USAGE.md

@@ -0,0 +1,122 @@
+# 使用指南：dict-sync（字典同步）
+
+> **谁读这个文档**：团队成员（前端 + 后端联调时）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+业务页面里 `data.ts` 引用的字典（`logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"`）需要在低代码平台 **数据字典模块** 中真实存在，否则下拉项为空、表头标签为空。
+
+`dict-sync` 负责：
+
+1. 拉取**线上字典模块及字典项**到 `reports/SYS_DICT_INFO.md`（团队基线）
+2. 对比 `data.ts` 引用的字典码 vs 线上字典，**列出缺失字典码**
+3. 调用字典模块/字典项保存接口（或生成对照报告供后端建数据）
+
+---
+
+## 何时使用
+
+- 业务页面下拉/状态列空白，怀疑字典码没建
+- 一次性从原型/详设里抽取出 N 个新字典，需批量同步
+- 同步线上字典基线（DEV / UAT / PROD 拉齐）
+- `convention-audit` 报告里出现 "字典码不存在" 类偏差
+
+---
+
+## 触发关键词
+
+`同步字典` / `创建字典` / `刷新字典基线` / `字典对比` / `字典审计`
+
+---
+
+## 前置条件
+
+`.github/skills/sync/env.local.json`（已 gitignore，每个开发者本地填自己的 token）：
+
+```json
+{
+  "gatewayPath": "http://192.168.10.50:9000",
+  "sysAppNo": "QjQuXy1kbKxZyjhS5N2",
+  "token": "eyJhbGci...",
+  "dict": {
+    "moduleId": "7C909G0U2F8HI7E305LV0135LSJ3UBIO"
+  }
+}
+```
+
+`dict.moduleId` 获取方式：低代码平台 → 数据字典 → 新增一条 → DevTools Network → 抓 `moduleId` 字段。
+
+> **向下兼容**：`env.local.json` 不存在时回落到旧路径 `skills/sync/menu-sync/env/env.local.json`。
+
+---
+
+## 标准对话示例
+
+```
+你：把 src/views/produce/aiflow/ 里所有页面用到的字典同步一下
+AI：[Pre-flight]
+    步骤 1：扫描 data.ts，提取 logicValue 形成字典码集合（共 12 个）
+    步骤 2：调用 wls_dict_query 拉线上字典模块（已有 8 个，缺 4 个）
+    步骤 3：建议新增字典模块 + 字典项：
+       - APPLY_STATUS（申请状态：待审核/审核中/已通过/已驳回）
+       - CUSTOMER_TYPE（客户类型：临时/正式/合作/战略）
+       - ...
+    [需你确认]
+    - 排序 sortPriority 自动从 1 递增？yes/no
+    - 字典名 strName 我直接用截图里的中文，对吗？yes/no
+```
+
+---
+
+## 输出物
+
+1. **基线文件**：`reports/SYS_DICT_INFO.md` —— 当前所有线上字典模块 + 字典项的本地基线
+2. **同步报告**（可选）：`reports/DICT_SYNC_<YYYYMMDD>.md` —— 本次新增了哪些字典/字典项
+3. **缺失对照**：报告附 "未在线上找到的字典码" 列表，便于后端预先建数据
+
+---
+
+## 与 business-doc-extract 的关系
+
+| 维度 | `business-doc-extract` | `dict-sync` |
+|---|---|---|
+| 职责 | 业务理解 / 设计意图 | 线上事实 / 数据落地 |
+| 输出 | `docs/business/0X-xx/dictionary.md`（人读） | 后端字典表（系统读） |
+| 时机 | 项目/模块沉淀阶段 | 联调前 / 上线前 |
+
+两者**互不替代**：业务文档说的是"应该有什么字典"，dict-sync 解决"线上有没有"。建议顺序：`business-doc-extract` 整理出 dictionary.md 草案 → 评审 → `dict-sync` 落地。
+
+---
+
+## 常见踩坑
+
+| 现象 | 原因 | 解法 |
+|---|---|---|
+| 下拉空白但接口返回正常 | 字典码大小写不一致 | 字典码全部 UPPER_SNAKE_CASE，data.ts 与后端对齐 |
+| 401/403 报错 | env.local.json 的 token 过期 | 重新登录系统，从 Network 抓 Authorization 替换 |
+| 模块新增成功但取不到 id | 接口异步延迟 | dict-sync 已自动 re-query，无需手动处理 |
+| 字典项重复创建 | 没读基线就 push | 先跑 `wls_dict_query` 取线上数据 → 对比 → 增量 push |
+
+---
+
+## 团队协作流程
+
+1. **每周一**由 lead 跑一次 `刷新字典基线`，更新 `reports/SYS_DICT_INFO.md`
+2. 业务页面 PR 提交前自查 "我加的字典码是否进了基线"
+3. 上线前再 sync 一次到生产环境（切换 env 文件中的 gatewayPath）
+
+---
+
+## FAQ
+
+**Q：业务字典 vs 系统字典 vs 状态枚举怎么区分？**
+A：状态枚举（如 `APPLY_STATUS`）走系统字典；业务高频可枚举字段（如 `CUSTOMER_TYPE`）走系统字典；纯文本备注、复杂联动数据不走字典。
+
+**Q：能不能让 AI 直接根据 data.ts 自动建字典？**
+A：可以，但 **建议人工确认 strName**。AI 从字段中文猜出来的字典名往往不够标准，PR 评审难。先生成对照报告，人工 review 后再 push。
+
+**Q：和 menu-sync / permission-sync 关系？**
+A：菜单是入口，字典是值域，权限是访问控制。三者独立但配合。建议顺序：`menu-sync` → `permission-sync` → `dict-sync`。