@agile-team/wl-skills-kit 1.2.1 → 2.1.0

package/files/.github/skills/{menu-sync → sync/menu-sync}/env/guide.md

@@ -1,83 +1,83 @@
-# env.local.json 配置说明
-
-> 该目录下的 `env.local.json` 已加入 `.gitignore`，**不会提交到远端仓库**。
-> 每位成员在本地维护自己的副本，首次使用时按本文档填写即可。
-
----
-
-## 文件结构
-
-```json
-{
-  "gatewayPath": "http://192.168.10.50:9000",
-  "parentMenuId": "1803456789012345678",
-  "sysAppNo": "QjQuXy1kbKxZyjhS5N2",
-  "token": "eyJhbGci..."
-}
-```
-
----
-
-## 字段说明
-
-| 字段 | 说明 | 示例 |
-|---|---|---|
-| `gatewayPath` | 后端网关地址，含协议和端口，**末尾不加斜杠** | `http://192.168.10.50:9000` |
-| `parentMenuId` | 目标父级目录的菜单数据库 ID（每套环境不同） | `1803456789012345678` |
-| `sysAppNo` | 应用编码（非明文，从已有菜单接口响应中获取） | `QjQuXy1kbKxZyjhS5N2` |
-| `token` | 当前登录用户的 Bearer Token，**不含 `bearer ` 前缀** | `eyJhbGci...` |
-
----
-
-## 如何获取各字段
-
-### gatewayPath
-
-询问后端同事，或查看浏览器 Network 面板中任意接口请求的 URL，取协议 + 域名/IP + 端口部分。
-
-### parentMenuId
-
-**方法 A（推荐）**：系统管理后台 → 菜单管理 → 找到目标父级目录 → 点编辑/查看 → 复制菜单 ID
-
-**方法 B（API 查询）**：
-
-```
-GET {gatewayPath}/system/menu/children?menuId=0
-```
-
-从顶级节点向下逐层查找，直到找到目标父级目录。也可以告诉 AI「帮我查一下父级菜单 ID」，AI 会自动调接口查询。
-
-### sysAppNo
-
-系统用编码后的字符串标识应用（如 `QjQuXy1kbKxZyjhS5N2`），而非明文 `produce` / `sale`。
-
-**获取方式**：浏览器 F12 → Network → 找任意菜单相关接口的响应体 → 查看已有菜单条目的 `sysAppNo` 字段值，复制即可。
-
-> ℹ️ 同一领域下所有菜单的 `sysAppNo` 相同，复制任意一个即可。
-
-### token
-
-1. 在浏览器中登录系统
-2. 按 F12 打开 DevTools → Network 面板
-3. 随便点一个接口请求
-4. 查看 Request Headers → `authorization` 字段
-5. 去掉 `bearer ` 前缀，复制剩余字符串粘贴到 `token` 字段
-
-> Token 有有效期，若创建菜单时提示鉴权失败，重新登录后刷新 token 即可。
-
----
-
-## 使用方式
-
-配置完成后，直接对 AI 说：
-
-> 「帮我创建菜单」/ 「同步菜单」/ 「补菜单」
-
-AI 会自动执行：
-1. 读取 `SYS_MENU_INFO.md`（菜单定义）
-2. 读取 `env.local.json`（环境配置）
-3. 调 `/system/menu/children` 查询父级已有子节点（去重）
-4. 逐条调 `/system/menu/save` 创建缺失菜单
-5. 输出 `created / skipped` 结果表
-
-**全程无需手动执行任何命令。**
+# env.local.json 配置说明
+
+> 该目录下的 `env.local.json` 已加入 `.gitignore`，**不会提交到远端仓库**。
+> 每位成员在本地维护自己的副本，首次使用时按本文档填写即可。
+
+---
+
+## 文件结构
+
+```json
+{
+  "gatewayPath": "http://192.168.10.50:9000",
+  "parentMenuId": "1803456789012345678",
+  "sysAppNo": "QjQuXy1kbKxZyjhS5N2",
+  "token": "eyJhbGci..."
+}
+```
+
+---
+
+## 字段说明
+
+| 字段 | 说明 | 示例 |
+|---|---|---|
+| `gatewayPath` | 后端网关地址，含协议和端口，**末尾不加斜杠** | `http://192.168.10.50:9000` |
+| `parentMenuId` | 目标父级目录的菜单数据库 ID（每套环境不同） | `1803456789012345678` |
+| `sysAppNo` | 应用编码（非明文，从已有菜单接口响应中获取） | `QjQuXy1kbKxZyjhS5N2` |
+| `token` | 当前登录用户的 Bearer Token，**不含 `bearer ` 前缀** | `eyJhbGci...` |
+
+---
+
+## 如何获取各字段
+
+### gatewayPath
+
+询问后端同事，或查看浏览器 Network 面板中任意接口请求的 URL，取协议 + 域名/IP + 端口部分。
+
+### parentMenuId
+
+**方法 A（推荐）**：系统管理后台 → 菜单管理 → 找到目标父级目录 → 点编辑/查看 → 复制菜单 ID
+
+**方法 B（API 查询）**：
+
+```
+GET {gatewayPath}/system/menu/children?menuId=0
+```
+
+从顶级节点向下逐层查找，直到找到目标父级目录。也可以告诉 AI「帮我查一下父级菜单 ID」，AI 会自动调接口查询。
+
+### sysAppNo
+
+系统用编码后的字符串标识应用（如 `QjQuXy1kbKxZyjhS5N2`），而非明文 `produce` / `sale`。
+
+**获取方式**：浏览器 F12 → Network → 找任意菜单相关接口的响应体 → 查看已有菜单条目的 `sysAppNo` 字段值，复制即可。
+
+> ℹ️ 同一领域下所有菜单的 `sysAppNo` 相同，复制任意一个即可。
+
+### token
+
+1. 在浏览器中登录系统
+2. 按 F12 打开 DevTools → Network 面板
+3. 随便点一个接口请求
+4. 查看 Request Headers → `authorization` 字段
+5. 去掉 `bearer ` 前缀，复制剩余字符串粘贴到 `token` 字段
+
+> Token 有有效期，若创建菜单时提示鉴权失败，重新登录后刷新 token 即可。
+
+---
+
+## 使用方式
+
+配置完成后，直接对 AI 说：
+
+> 「帮我创建菜单」/ 「同步菜单」/ 「补菜单」
+
+AI 会自动执行：
+1. 读取 `SYS_MENU_INFO.md`（菜单定义）
+2. 读取 `env.local.json`（环境配置）
+3. 调 `/system/menu/children` 查询父级已有子节点（去重）
+4. 逐条调 `/system/menu/save` 创建缺失菜单
+5. 输出 `created / skipped` 结果表
+
+**全程无需手动执行任何命令。**

package/files/.github/skills/sync/permission-sync/SKILL.draft.md

@@ -0,0 +1,91 @@
+---
+name: permission-sync
+description: "[PLANNED — DRAFT, not yet active] 权限同步 Skill 设计草稿。基于 reports/SYS_PERMISSION_INFO.md 基线，将页面级/按钮级权限码注册到系统权限表，并按角色分配。"
+status: planned
+---
+
+# Skill: 权限同步（permission-sync）— 草稿
+
+> ⚠️ **本文件为设计草稿（SKILL.draft.md），未启用，不参与 AI 调度。**
+
+---
+
+## 1. 设计目标
+
+新增页面后，除菜单外还需注册：
+
+- **页面访问权限**（`mmwr:customer:list`）
+- **按钮级权限**（`mmwr:customer:add` / `:edit` / `:remove` / `:approve` / `:export` ...）
+- **数据权限**（可选：客户经理只看自己的客户等）
+- **角色绑定**（哪些角色获得这些权限）
+
+---
+
+## 2. 数据流
+
+```
+本地基线                                  后端接口                              Skill 触发
+────────────────────────────────────────  ──────────────────────────────────  ────────────────
+reports/SYS_PERMISSION_INFO.md  ─fetch─→  GET  /sys/permission/listAll
+                                ←compare── POST /sys/permission/batchSave
+                                ─upload─→ POST /sys/role/assignPermissions  ─→  "同步权限"
+```
+
+---
+
+## 3. 权限码命名规范
+
+```
+{服务缩写}:{资源camelCase}:{操作}
+```
+
+| 操作     | 含义           | 示例                            |
+| -------- | -------------- | ------------------------------- |
+| list     | 查看列表       | `mmwr:customer:list`            |
+| detail   | 查看详情       | `mmwr:customer:detail`          |
+| add      | 新增           | `mmwr:customer:add`             |
+| edit     | 编辑           | `mmwr:customer:edit`            |
+| remove   | 删除           | `mmwr:customer:remove`          |
+| export   | 导出           | `mmwr:customer:export`          |
+| import   | 导入           | `mmwr:customer:import`          |
+| submit   | 提交审批       | `mmwr:customer:submit`          |
+| approve  | 审批通过       | `mmwr:customer:approve`         |
+| reject   | 审批驳回       | `mmwr:customer:reject`          |
+| {custom} | 自定义业务操作 | `mmwr:customer:convertToFormal` |
+
+---
+
+## 4. 三种工作模式
+
+| 模式       | 触发                    | 动作                                                   |
+| ---------- | ----------------------- | ------------------------------------------------------ |
+| `scan`     | "扫描权限码"            | 从 src/views/ 扫 v-permission / hasPerm 调用，输出清单 |
+| `register` | "注册权限码 / 同步权限" | 对比基线 → 创建缺失 + 更新描述                         |
+| `assign`   | "给 XX 角色分配权限"    | 选定角色 + 选定权限码 → 调 /sys/role/assignPermissions |
+
+---
+
+## 5. 安全约束
+
+- **生产环境拒绝直接 push**：检测 gatewayPath 含 prod/.com 时强制走"导出 SQL"模式
+- **角色分配二次确认**：每次 assign 必须在 Pre-flight 中列出"角色 → 新增/移除的权限"，得到用户 yes 才执行
+- **不删除权限**：永远只新增/更新，删除走人工 SQL（防误删导致大面积失权）
+- **审计**：每次 register/assign 输出 `reports/PERMISSION_SYNC_<YYYYMMDD>.md`，含完整调用日志和回滚 SQL
+
+---
+
+## 6. 与其他 Skill 联动
+
+- **page-codegen**：生成 toolbar 时根据 api.md 操作集自动加 `v-permission` 指令
+- **menu-sync**：菜单注册后提示"是否同步注册访问权限"
+- **convention-audit**：审计按钮是否都有 v-permission
+
+---
+
+## 7. 转正前的开发任务
+
+- [ ] 确认后端权限模型（RBAC / ABAC？是否分页面权限和按钮权限？）
+- [ ] 数据权限是否纳入本 Skill（建议：暂不，单独 data-permission-sync）
+- [ ] 设计 v-permission 指令的项目内实现（如 @jhlc/common-core 提供则复用）
+- [ ] 多租户场景下的权限继承策略
+- [ ] 与 SSO（嘉为蓝鲸）权限同步策略

package/files/.github/standards/01-toolchain.md

@@ -0,0 +1,57 @@
+# 01 — 工具链前置检测
+
+> **强制度**：🔴 阻断式。检测未通过 → AI 必须暂停代码生成。
+
+---
+
+## 检测目标
+
+确认项目已正确安装 `@robot-admin/git-standards`，工具链有效。
+
+## 检测项
+
+AI 在执行任何代码生成任务**之前**，必须检查以下三个特征文件是否存在于项目根目录：
+
+```
+✓ .prettierrc.js
+✓ eslint.config.ts
+✓ .husky/  （目录）
+```
+
+## 判定规则
+
+| 状态         | 处理                        |
+| ------------ | --------------------------- |
+| 三者全部存在 | ✅ 工具链就绪，继续执行任务 |
+| 缺任意一个   | ❌ 暂停任务，输出下方提示   |
+
+## 暂停提示标准格式
+
+```
+❌ 工具链检测失败：未找到 .prettierrc.js / eslint.config.ts / .husky/
+   → 请执行：npx @robot-admin/git-standards init
+   → 或联系 CHENY（工号 409322）解决
+   → ⛔ 代码生成已暂停，修复后重新触发
+```
+
+## Pre-flight 声明示例
+
+工具链就绪：
+
+```
+✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓  [全部就绪]
+```
+
+工具链缺失：
+
+```
+❌ 工具链检测：未检测到 .husky/  → 已暂停，提醒已发出
+```
+
+---
+
+## 为什么必须前置
+
+- `eslint.config.ts` 缺失 → 代码风格无法约束，AI 生成代码可能不通过 lint
+- `.prettierrc.js` 缺失 → 格式不统一，团队协作冲突
+- `.husky/` 缺失 → 提交前钩子失效，console.log / 死代码会进入仓库

package/files/.github/standards/02-code-structure.md

@@ -0,0 +1,111 @@
+# 02 — 代码结构与顺序规范
+
+> **强制度**：🔴 必遵。AI 生成代码必须严格按下列顺序输出。
+
+---
+
+## 4 文件原则（页面目录强制结构）
+
+```
+src/views/[域]/[模块]/[子模块]/[kebab-case目录]/
+├── index.vue    ← 纯模板 + 解构，不写业务逻辑
+├── data.ts      ← AbstractPageQueryHook 类 + API_CONFIG
+├── index.scss   ← 页面样式（可为空）
+└── api.md       ← 接口约定文档
+```
+
+**禁止**：把业务逻辑写在 index.vue；缺少 data.ts；缺少 api.md。
+
+## 弹窗组件归属
+
+| 场景                    | 位置                                 |
+| ----------------------- | ------------------------------------ |
+| 通用弹窗（2+ 页面复用） | `src/components/local/c_xxxModal/`   |
+| 极个性弹窗（仅单页面）  | 页面目录下 `components/xxxModal.vue` |
+
+---
+
+## index.vue 三段式（顺序固定，不可调换）
+
+```vue
+<template>
+  <!-- 纯模板 + 组件组合 -->
+</template>
+
+<script setup lang="ts">
+/* 业务逻辑全部从 data.ts 导入，按下方 9 段式 */
+</script>
+
+<style scoped lang="scss">
+@import "./index.scss";
+/* 仅允许这一行 import，全部样式写在 index.scss */
+</style>
+```
+
+---
+
+## `<script setup>` 9 段式（按需使用，用到的必须遵守此顺序）
+
+```typescript
+// ===== 1. import 语句（外部库 → 内部模块 → 类型）=====
+import { ref, computed, onMounted } from "vue";
+import { createPage } from "./data";
+
+// ===== 2. 组件宏（defineOptions / defineProps / defineEmits）=====
+defineOptions({ name: "PageName" });
+
+// ===== 3. 路由 & Store =====
+const route = useRoute();
+
+// ===== 4. createPage() 调用 + 解构（核心模式）=====
+const Page = createPage();
+const {
+  tableRef,
+  page,
+  queryParam,
+  list,
+  queryItems,
+  columns,
+  toolbars,
+  select,
+} = Page;
+
+// ===== 5. 页面补充状态（ref / reactive / computed）=====
+const loading = ref(false);
+
+// ===== 6. watch / watchEffect =====
+
+// ===== 7. 业务方法（API 调用 / 事件处理）=====
+async function handleSubmit() {}
+
+// ===== 8. 生命周期 =====
+onMounted(() => select());
+
+// ===== 9. defineExpose =====
+defineExpose({ select });
+```
+
+---
+
+## data.ts 内部顺序（强制）
+
+```typescript
+// 1. import（类型 → 基类 → API 工具 → 工具函数）
+// 2. API_CONFIG（接口路径集中声明，as const）
+// 3. createPage()（constructor → queryDef → toolbarDef → columnsDef → 业务方法）
+// 4. 页面共用辅助函数（可选，纯函数）
+```
+
+---
+
+## index.scss 顺序（建议）
+
+```scss
+// 1. 变量覆盖
+// 2. 容器级样式 (.app-page-container)
+// 3. 区域级样式 (.search-area / .table-area)
+// 4. 组件深层覆盖 (:deep(.el-table))
+// 5. 响应式 (@media)
+```
+
+> 禁止 `::v-deep` / `/deep/`，统一使用 `:deep()`。

package/files/.github/standards/03-comments.md

@@ -0,0 +1,53 @@
+# 03 — 注释规范
+
+> **强制度**：🟡 建议。
+
+---
+
+## 文件头注释
+
+由 VS Code 插件 **koroFileHeader** 自动生成，不手写。
+项目根有 `.fileheader` 配置文件。
+
+**插件缺失提示**：
+
+```
+⚠️ 未检测到 koroFileHeader 配置生效
+   → 请安装插件：VS Code 扩展商店搜索 "koroFileHeader"
+   → 或联系 CHENY（工号 409322）获取一键安装指引
+```
+
+---
+
+## 函数注释
+
+仅复杂业务逻辑需要：
+
+```typescript
+/**
+ * @description 批量提交客户档案
+ * @param ids 选中的客户 ID 列表
+ * @returns 后端响应结果
+ */
+async function batchSubmit(ids: string[]) { ... }
+```
+
+---
+
+## 行内注释
+
+- 解释「**为什么**」而非「是什么」
+- 统一使用 `//`，不使用 `/* */`
+
+```typescript
+// 后端要求 status 必须先转字符串再传（接口字段类型不一致历史遗留）
+params.status = String(params.status);
+```
+
+---
+
+## 禁止事项
+
+- ❌ 提交注释掉的死代码（直接删除，git 可追溯历史）
+- ❌ 显而易见的注释，如 `// 声明变量`、`// 调用接口`
+- ❌ TODO 不带责任人或日期，如 `// TODO: 待优化`，应写为 `// TODO(cheny, 2026-04): 接口字段后端确认中`

package/files/.github/standards/04-coding-basics.md

@@ -0,0 +1,33 @@
+# 04 — 基础编码规范
+
+> **强制度**：🔴 必遵。
+> 参考 jhat.tech 开发规范 + Robot_Admin 实践。
+
+---
+
+## 13 条核心约定
+
+1. **变量声明**：优先 `const`，必须重新赋值时用 `let`，禁止 `var`
+2. **解构赋值**：优先使用 `const { a, b } = obj`，而非 `obj.a` / `obj.b`
+3. **异步处理**：统一 `async/await`，禁止 `.then()` 链式调用
+4. **字符串引号**：统一单引号（以 `.prettierrc.js` 为准）
+5. **模板字符串**：替代字符串拼接，`` `Hello ${name}` `` 而非 `'Hello ' + name`
+6. **大括号**：所有代码块必须使用大括号包裹，即使只有一行
+7. **条件层级**：最多三层，超过三层必须抽成函数
+8. **模板表达式**：`<template>` 中只写简单表达式，复杂逻辑提取为 `computed` 或方法
+9. **对象遍历**：禁止 `for...in`，使用 `Object.keys(obj).forEach()`
+10. **undefined 判断**：使用 `typeof variable !== 'undefined'`
+11. **v-for**：必须设置 `:key`，优先用业务主键 id 而非 index
+12. **指令缩写**：统一 `:`（v-bind）、`@`（v-on）、`#`（v-slot）
+13. **this 别名**：`<script setup>` 中无 `this`；旧 Options API 中的 `this` 别名用 `self`
+
+---
+
+## 全局禁止事项
+
+- ❌ index.vue 中写业务逻辑（逻辑全在 data.ts）
+- ❌ 使用 Vuex（本项目用 Pinia）
+- ❌ `::v-deep` / `/deep/`（用 `:deep()`）
+- ❌ 直接用 axios（用 getAction/postAction，详见 13-platform-components.md）
+- ❌ 手写查询表单/工具栏/分页（用 BaseQuery/BaseToolbar/jh-pagination）
+- ❌ 每个页面重复写弹窗（优先用 `c_modal` / `c_formModal` 等局部公共组件）

package/files/.github/standards/05-logging.md

@@ -0,0 +1,38 @@
+# 05 — 日志输出规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## 开发期
+
+- 允许 `console.log` 调试，ESLint 仅给 `warn` 提示
+- AI 生成的代码**不要**包含调试用 `console.log`
+
+## 提交期
+
+- husky pre-commit 钩子自动触发 lint 检查
+- **必须清理** `console.log` / `console.warn` / `console.debug` 才能提交
+
+## 生产代码
+
+- ❌ 禁止出现 `console.log`、`console.warn`、`console.error`
+- ❌ 大量 console 输出会带来性能问题（参考 jhat.tech 规范）
+
+## 替代方案
+
+| 场景     | 替代方式                                       |
+| -------- | ---------------------------------------------- |
+| 错误监控 | 走全局错误处理器（接入 Sentry 或自研上报通道） |
+| 调试信息 | 仅在开发环境通过 `import.meta.env.DEV` 守卫    |
+| 用户提示 | 使用 `ElMessage` / `jh-message`                |
+
+```typescript
+// ✅ 允许：开发期守卫
+if (import.meta.env.DEV) {
+  console.log("[debug] payload:", payload);
+}
+
+// ❌ 禁止：生产代码无守卫的 console
+console.log("user info:", user);
+```

package/files/.github/standards/06-security.md

@@ -0,0 +1,44 @@
+# 06 — 安全规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## v-html 使用约束
+
+- ❌ 默认禁止 `v-html`
+- ✅ 仅当内容来源受控（如后端返回已消毒的富文本），且必须在使用处加注释说明来源：
+
+```vue
+<!-- v-html 安全声明：内容来自 /api/notice/detail，后端已做 XSS 过滤 -->
+<div v-html="notice.content" />
+```
+
+## Token 存储
+
+- ✅ 仅存 `sessionStorage` / `localStorage`
+- ❌ 禁止放在 URL 参数（被日志记录）
+- ❌ 禁止放在 `<meta>` 标签（HTML 静态可见）
+
+## 接口请求
+
+- ✅ 统一通过 `getAction / postAction / putAction / deleteAction` 走拦截器
+- ✅ 拦截器自动注入 token、统一处理 401 跳转
+- ❌ 禁止 `import axios from 'axios'` 直接使用
+
+## 用户输入
+
+- ✅ 通过接口参数对象传递
+- ❌ 禁止拼接到 URL 字符串
+- ❌ 禁止直接传给 SQL 语句生成函数（防 SQL 注入）
+
+## 对象遍历
+
+- ❌ 禁止 `for...in`（可能枚举原型链属性，存在安全隐患）
+- ✅ 使用 `Object.keys(obj).forEach()` / `Object.entries(obj)`
+
+## 危险 API
+
+- ❌ **禁止 `eval()`** —— 任何场景均不允许
+- ❌ 禁止 `new Function(string)` 动态执行字符串代码
+- ❌ 禁止 `setTimeout(string)` 字符串形式调用

package/files/.github/standards/07-config.md

@@ -0,0 +1,52 @@
+# 07 — 配置管理规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## 环境变量
+
+- 统一存放 `envs/.env.{mode}` 文件
+- 命名以 `VITE_` 开头（Vite 暴露给客户端的前缀）
+- 通过 `import.meta.env.VITE_XXX` 读取
+- ❌ 不硬编码环境相关值
+
+```typescript
+// ✅ 正确
+const apiBase = import.meta.env.VITE_API_URL;
+
+// ❌ 错误
+const apiBase = "http://10.0.0.5:8080/api";
+```
+
+## API 地址
+
+- ✅ 通过 `import.meta.env.VITE_API_URL` 等环境变量获取
+- ❌ 不在代码中硬编码 `http://` / `https://` 地址
+
+## 接口路径
+
+- ✅ 集中在 `data.ts` 的 `API_CONFIG` 对象中声明（`as const`）
+- ❌ 不散落在模板字符串、方法内部
+
+```typescript
+export const API_CONFIG = {
+  list: "/mmwr/customer/list",
+  save: "/mmwr/customer/save",
+  remove: "/mmwr/customer/remove",
+} as const;
+```
+
+## 敏感信息
+
+- ❌ 不提交到仓库（已纳入 `.gitignore`）
+- ✅ 团队共享走内部文档或专用密钥服务
+
+## AI 检查清单
+
+生成代码前，AI 必须确认：
+
+- [ ] 没有硬编码的 IP / 域名 / 端口
+- [ ] 所有 API 路径在 `API_CONFIG` 中声明
+- [ ] 环境变量都加了 `VITE_` 前缀
+- [ ] 没有把 token / secret / 密码以明文形式写入代码