@agile-team/wl-skills-kit 2.3.4 → 2.3.6

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

@@ -0,0 +1,93 @@
+# permission-sync · 使用示例
+
+> 给团队成员看的快速上手文档。AI 触发协议见 `SKILL.md`。
+
+---
+
+## 一句话理解
+
+**permission-sync = 角色管理 + 角色授权 + 挂动作 + 加 v-permission**
+
+整条链路覆盖"页面建好后，怎么让指定角色的人能看见、能点按钮"的全过程。
+
+---
+
+## 三种典型对话
+
+### 1. 创建角色
+
+```
+用户：创建一个测试角色，code 是 test_qa
+AI ： [触发 permission-sync]
+     [Pre-flight] 模式 = role-manage
+     调用 wls_role_query 检查 → code=test_qa 不存在
+     调用 wls_role_upsert
+     ✅ 创建成功
+```
+
+### 2. 给角色分配菜单
+
+```
+用户：给『档案普通人员』分配『客户档案』和『客户申请』两个菜单
+AI ： [触发 permission-sync]
+     [Pre-flight] 模式 = role-assign
+     ⚠️ 注意：saveRoleMenus 是全量覆盖，原有菜单会被替换
+     是否继续？(yes/no)
+用户：yes
+AI ： 调用 wls_role_assign_menus
+     ✅ 角色授权成功
+```
+
+### 3. 给页面挂动作 + 加 v-permission
+
+```
+用户：给『客户档案』页面加上 新增/编辑/删除 三个按钮
+AI ： [触发 permission-sync]
+     [Pre-flight] 模式 = action-attach
+     1. wls_action_query 查询已有动作 → 无
+     2. wls_action_upsert 创建 customer_add / customer_edit / customer_remove
+     3. 改造 src/views/customer/list/index.vue toolbar，加 v-permission
+     ✅ 完成（已写报告 reports/PERMISSION_SYNC_20260429.md）
+```
+
+---
+
+## 常见问题
+
+### Q1：角色授权时，为什么 menuIds 要传完整列表？
+
+后端 `saveRoleMenus` 是**全量覆盖**接口。你传 `[A, B]`，原先 `[A, B, C]` 就会变成 `[A, B]`，C 丢失。
+
+**正确做法**：先查角色现有菜单 → 合并新菜单 → 一起传。
+
+### Q2：v-permission 指令在哪里实现？
+
+通常由项目基座（`@jhlc/common-core` 或登录 store）注册全局指令。检查方式：
+```bash
+grep -r "v-permission\|app.directive('permission'" src/
+```
+如未找到，请联系架构组确认。
+
+### Q3：权限码用短形式还是长形式？
+
+参照项目既有用法。新项目建议短形式（`customer_add`），与平台示例数据一致。
+
+### Q4：能批量删除角色/动作吗？
+
+**不能**。permission-sync 仅新增不删除（防误删）。删除请走后端管理界面手动操作。
+
+---
+
+## 配置要点
+
+只需 `.github/skills/sync/env.local.json` 的根字段：
+
+```json
+{
+  "gatewayPath": "http://你的网关:端口",
+  "sysAppNo": "应用编码",
+  "token": "Bearer Token"
+}
+```
+
+不需要额外配置 `parentRoleId` / `parentPermissionId` 之类——所有父级 id 由 AI 在执行流程中通过查询接口动态获取。

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

@@ -1,57 +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 / 死代码会进入仓库
+# 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

@@ -1,111 +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()`。
+# 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

@@ -1,53 +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): 接口字段后端确认中`
+# 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

@@ -1,33 +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` 等局部公共组件）
+# 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` 等局部公共组件）