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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/files/.github/skills/sync/permission-sync/SKILL.md +39 -20
  3. package/files/.github/skills/sync/permission-sync/USAGE.md +22 -8
  4. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.3.7] - 2026-04-29
4
+
5
+ ### 🔐 permission-sync 闭环完善（数据驱动权限）
6
+
7
+ - **修正权限落地方式**：`action-attach` 模式改为在 `data.ts` 的 `ActionButtonDesc` 上加 `permission: []` 字段，而非错误的 `v-permission` 指令（`BaseToolbar` 内部已做权限拦截）
8
+ - **简化角色授权备份说明**：平台侧已防重复分配；AI 内部做"查旧 menuIds + 合并"，不再建议额外备份
9
+ - **联动说明更新**：`page-codegen` 预留 `permission: []` 占位；`convention-audit` 改为审计 `data.ts` 按钮是否有非空 `permission` 字段
10
+ - `USAGE.md` 补充"为什么不用 v-permission 指令"说明 + Q2 权限码写法示例
11
+
3
12
  ## [2.3.6] - 2026-04-29
4
13
 
5
14
  ### 🔐 permission-sync Skill 正式激活
package/files/.github/skills/sync/permission-sync/SKILL.md CHANGED
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: permission-sync
3
- description: "Use when: managing roles, authorizing menus to roles, attaching action buttons (type=A) to page menus, or wiring v-permission directives in Vue code. Triggers on: 创建角色, 角色管理, 角色授权, 给角色分配菜单, 挂动作, 添加动作按钮, 同步权限, 权限码注册, role assign, permission sync."
3
+ description: "Use when: managing roles, authorizing menus to roles, attaching action buttons (type=A) to page menus, or wiring permission field in data.ts toolbar config. Triggers on: 创建角色, 角色管理, 角色授权, 给角色分配菜单, 挂动作, 添加动作按钮, 同步权限, 权限码注册, role assign, permission sync."
4
4
  ---
5
5
 
6
6
  # Skill: 权限同步（permission-sync）
7
7
 
8
- 将系统的**角色 → 菜单授权 → 动作按钮 → 业务代码 v-permission**串成一条链路，覆盖从权限注册到代码落地的全流程。
8
+ 将系统的**角色 → 菜单授权 → 动作按钮 → `data.ts` 权限码字段**串成一条链路，覆盖从权限注册到代码落地的全流程。
9
9
 
10
10
  > **与 menu-sync / dict-sync 的关系**：完全对称，统一从 `.github/skills/sync/env.local.json` 读取配置。`menu-sync` 负责页面菜单（type=M/C），`permission-sync` 负责其上的角色与动作（type=A）。
11
11
 
@@ -29,11 +29,11 @@ description: "Use when: managing roles, authorizing menus to roles, attaching ac
29
29
 
30
30
  ## 三种工作模式
31
31
 
32
- | 模式 | 触发关键词 | 动作 |
33
- | ---------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
34
- | `role-manage` | 创建角色 / 角色管理 / 列出角色 | 查询/新增角色（按 `code` 去重，幂等） |
35
- | `role-assign` | 角色授权 / 给 XX 角色分配菜单 | 查询全量可授权菜单 → 选定 menuIds → 调用 `saveRoleMenus` 批量分配 |
36
- | `action-attach` | 挂动作 / 给页面加按钮 / 注册权限码 | 在指定页面菜单下批量新增 type=A 动作（按 `permission` 去重）+ 在代码加 v-permission |
32
+ | 模式 | 触发关键词 | 动作 |
33
+ | ---------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
34
+ | `role-manage` | 创建角色 / 角色管理 / 列出角色 | 查询/新增角色（按 `code` 去重，幂等） |
35
+ | `role-assign` | 角色授权 / 给 XX 角色分配菜单 | 查询全量可授权菜单 → 选定 menuIds → 调用 `saveRoleMenus` 批量分配 |
36
+ | `action-attach` | 挂动作 / 给页面加按钮 / 注册权限码 | 注册 type=A 动作到后端 + 在 `data.ts` 对应按钮的 `ActionButtonDesc` 加 `permission` 字段，形成完整闭环 |
37
37
 
38
38
  ---
39
39
 
@@ -141,18 +141,37 @@ permission-sync 通过 6 个 MCP 工具完成所有操作（无需手动 fetch
141
141
  }
142
142
  ```
143
143
 
144
- #### 3.2 在 Vue 代码中加 v-permission 指令
144
+ #### 3.2 在 `data.ts` 中给对应按钮加 `permission` 字段
145
145
 
146
- 注册动作后，AI 自动改造对应页面的 toolbar/操作列，加上 `v-permission`：
146
+ 本项目使用 `@jhlc/common-core` 的 `ActionButtonDesc` 类型，`BaseToolbar` 内部根据 `permission` 字段做权限拦截——**这是数据驱动方式，无需修改模板，无需 `v-permission` 指令**。
147
147
 
148
- ```vue
149
- <el-button v-permission="'customer_add'" @click="onAdd">新增</el-button>
150
- <el-button v-permission="'customer_edit'" @click="onEdit">编辑</el-button>
151
- <el-button v-permission="'customer_remove'" @click="onRemove">删除</el-button>
152
- <el-button v-permission="'customer_export'" @click="onExport">导出</el-button>
148
+ 由于 page-codegen 保证 `data.ts` 结构一致，toolbar 按钮配置始终在 `data.ts` 内。注册动作后，AI 找到对应按钮对象，添加 `permission` 数组字段：
149
+
150
+ ```ts
151
+ // data.ts — 工具栏按钮配置（ActionButtonDesc[]）
152
+ {
153
+ name: 'add',
154
+ label: '新增',
155
+ type: 'primary',
156
+ permission: ['customer_add'], // ← 新增此字段
157
+ onClick: () => modalRef.value?.open()
158
+ },
159
+ {
160
+ name: 'edit',
161
+ label: '编辑',
162
+ permission: ['customer_edit'], // ← 新增此字段
163
+ onClick: (row: any) => modalRef.value?.edit(row.id)
164
+ },
165
+ {
166
+ name: 'remove',
167
+ label: '删除',
168
+ type: 'danger',
169
+ permission: ['customer_remove'], // ← 新增此字段
170
+ onClick: (row: any) => handleRemove(row.id)
171
+ },
153
172
  ```
154
173
 
155
- > `v-permission` 指令通常由项目基座（如 `@jhlc/common-core` 或登录鉴权模块）注册。若项目未注册，AI 应在 Pre-flight 提示用户"未检测到 v-permission 指令实现，仅完成服务端注册，代码侧指令请由架构组补全"。
174
+ `permission` 值与 §3.1 中注册到后端的动作 `permission` 字段**完全一致**，直接复制使用。`BaseToolbar` 内部读取当前用户权限列表（由登录态注入），自动控制按钮显示/隐藏——无需任何额外处理。
156
175
 
157
176
  ---
158
177
 
@@ -182,9 +201,9 @@ permission-sync 通过 6 个 MCP 工具完成所有操作（无需手动 fetch
182
201
  ## 5. 安全约束（强制）
183
202
 
184
203
  - ✅ **生产环境拒绝直接 push**：`gatewayPath` 含 `prod` / `.com` 时切换为"导出 SQL/JSON"模式，不直接调接口
185
- - ✅ **角色分配二次确认**：`role-assign` 模式下，必须在 Pre-flight 中列出"角色 → 完整菜单清单"得到用户 yes 才执行
204
+ - ✅ **角色分配全量覆盖处理**：`role-assign` 模式下，AI 内部自动"查旧 menuIds + 合并新增"再调用，防止漏带原有菜单。平台侧已防重复分配，无需额外备份机制
186
205
  - ✅ **仅新增不删除**：所有 upsert 工具按唯一键去重跳过；删除走人工 SQL（防误删导致大面积失权）
187
- - ✅ **审计报告**：每次执行后，在 `reports/PERMISSION_SYNC_<YYYYMMDD>.md` 追加日志（角色/动作变更、调用接口、响应、回滚提示）
206
+ - ✅ **审计报告**：每次执行后，在 `reports/PERMISSION_SYNC_<YYYYMMDD>.md` 追加日志（角色/动作变更、接口调用、data.ts 修改行位置）
188
207
 
189
208
  ---
190
209
 
@@ -210,10 +229,10 @@ Authorization: Bearer <token>
210
229
 
211
230
  ## 7. 与其他 Skill 联动
212
231
 
213
- - **page-codegen**：生成 toolbar 时根据 `api.md` 的操作集自动加 `v-permission` 指令（在动作 upsert 完成后）
232
+ - **page-codegen**：生成 toolbar 按钮时，若 api.md 中声明了操作集，在 `data.ts` 的 `ActionButtonDesc` 中预留 `permission: []`（空数组占位），等待 permission-sync 后续填入真实权限码
214
233
  - **menu-sync**：菜单注册成功后，AI 应主动询问"是否给该页面挂动作？" → 触发 action-attach
215
- - **convention-audit**：审计页面 toolbar 是否所有按钮都有 `v-permission`（缺失视为偏差）
216
- - **prototype-scan**：扫描原型时识别按钮 → 写入 `reports/SYS_PERMISSION_INFO.md` 基线
234
+ - **convention-audit**：审计 `data.ts` 工具栏按钮是否都设置了非空的 `permission` 字段（字段缺失或为 `[]` 视为偏差）
235
+ - **prototype-scan**：扫描原型时识别按钮操作 → 写入 `reports/SYS_PERMISSION_INFO.md` 基线
217
236
 
218
237
  ---
219
238
 
package/files/.github/skills/sync/permission-sync/USAGE.md CHANGED
@@ -38,18 +38,24 @@ AI ： 调用 wls_role_assign_menus
38
38
  ✅ 角色授权成功
39
39
  ```
40
40
 
41
- ### 3. 给页面挂动作 + 加 v-permission
41
+ ### 3. 给页面挂动作 + 加权限字段（数据驱动，无需改模板）
42
42
 
43
43
  ```
44
44
  用户：给『客户档案』页面加上 新增/编辑/删除 三个按钮
45
45
  AI ： [触发 permission-sync]
46
46
  [Pre-flight] 模式 = action-attach
47
47
  1. wls_action_query 查询已有动作 → 无
48
- 2. wls_action_upsert 创建 customer_add / customer_edit / customer_remove
49
- 3. 改造 src/views/customer/list/index.vue toolbar，加 v-permission
48
+ 2. wls_action_upsert 注册到后端：customer_add / customer_edit / customer_remove
49
+ 3. 在 src/views/customer/list/data.ts 找到工具栏按钮配置，
50
+ 给每个对应按钮的 ActionButtonDesc 添加 permission 字段：
51
+ { name: 'add', label: '新增', permission: ['customer_add'], ... }
50
52
  ✅ 完成（已写报告 reports/PERMISSION_SYNC_20260429.md）
51
53
  ```
52
54
 
55
+ > **为什么不用 v-permission 指令？**
56
+ > 本项目 `BaseToolbar` 内部读取 `ActionButtonDesc.permission` 字段做权限控制，
57
+ > 只需在 `data.ts` 的按钮配置对象里加字段，不需要改 `.vue` 模板，也不依赖全局指令注册。
58
+
53
59
  ---
54
60
 
55
61
  ## 常见问题
@@ -60,13 +66,21 @@ AI ： [触发 permission-sync]
60
66
 
61
67
  **正确做法**：先查角色现有菜单 → 合并新菜单 → 一起传。
62
68
 
63
- ### Q2：v-permission 指令在哪里实现？
69
+ ### Q2：权限码写在 `data.ts` 哪里？不需要改模板吗？
70
+
71
+ 对，**不需要改模板（`.vue` 文件）**。`BaseToolbar` 从 `ActionButtonDesc` 的 `permission` 字段读取权限码，在渲染时内部做拦截，标准结构如下：
64
72
 
65
- 通常由项目基座（`@jhlc/common-core` 或登录 store）注册全局指令。检查方式：
66
- ```bash
67
- grep -r "v-permission\|app.directive('permission'" src/
73
+ ```ts
74
+ // data.ts
75
+ {
76
+ name: 'edit',
77
+ label: '编辑',
78
+ permission: ['qmmcProcessCodeMain_update'], // ← 就加这一行
79
+ onClick: (row: any) => modalRef.value?.edit(row.id)
80
+ }
68
81
  ```
69
- 如未找到，请联系架构组确认。
82
+
83
+ `permission` 是数组，支持多权限码 OR 逻辑（有其中任意一个权限码即显示按钮）。
70
84
 
71
85
  ### Q3：权限码用短形式还是长形式？
72
86
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agile-team/wl-skills-kit",
3
- "version": "2.3.6",
3
+ "version": "2.3.7",
4
4
  "description": "AI Skill 模板包 — 一键导入 AI 指令 + 组件文档 + 通用组件 + 领域样例，覆盖 Copilot/Cursor/Windsurf/Kiro 等主流 AI 编辑器",
5
5
  "main": "./bin/wl-skills.js",
6
6
  "bin": {