@lovrabet/rabetbase-cli 2.4.4 → 2.4.5-beta.1

package/skills/rabetbase/guides/role-permit-workflow.md

@@ -1,127 +0,0 @@
-# 用户组与权限（role / permit）工作流
-
-前置知识：已完成 `rabetbase auth` 登录，当前上下文已有 `appcode`。所有写操作默认输出 `compress`，先 `--dry-run` 再 `--yes`。
-
-## 适用范围
-
-本工作流覆盖「谁属于哪个用户组」和「某个用户组能看什么、能操作什么」两类问题：
-
-- 建组 / 改组 / 删组（`role create/update/delete`）
-- 把员工加入或移出用户组（`role user-add/user-remove`）
-- 收紧或放开某用户组的菜单可见（`permit role-menus-set`）
-- 收紧或放开某用户组的数据接口访问（`permit role-apis-set`）
-- 配置单个页面的菜单可见 / 数据操作 / 行级可见（`permit page-set`）
-
-不适用于：
-
-- 平台运营态的用户账号增删、租户成员开通（那是平台账号体系，不是应用内用户组）
-- 运行态「登录后实际能读到哪些行」的验证 —— 交给 `lovrabet data filter` 在运行态确认
-
-## 两个必须先分清的层面
-
-权限配置常被混为一谈，动手前先判断问题落在哪一层：
-
-| 层面 | 回答的问题 | 事实源 / 命令 |
-|------|-----------|--------------|
-| **成员归属** | 某个人在不在某个用户组里 | `role user-*`（`update-user-list` 全量回写） |
-| **能力授权** | 某个用户组能看哪些菜单 / 访问哪些接口 / 在某页能做什么 | `permit *`（菜单矩阵 / API 矩阵 / 单页槽位） |
-
-「小张不能看财务」通常**不是**把小张移出某个组，而是收紧他所在用户组的**能力授权**。
-
-## 角色（用户组）类型
-
-`ADMIN` / `DEV` / `USER` 为内置，`CUSTOM` 为用户创建。守卫规则：
-
-- `role update` / `role delete`：**仅 `CUSTOM`**；对 `DEV` / `ADMIN` / `USER` 会被 validation 拒绝。
-- `permit role-menus-set` / `role-apis-set`：**DEV / ADMIN 的权限矩阵不可改**，会被拒绝（内置角色按设计保持全量访问）。
-- `role user-add` / `user-remove`：成员增删对**所有角色**可用（包括把人加进 DEV）。
-
-要「限制某类人」时，正确姿势是新建或选用一个 `CUSTOM` 组，配它的能力，再把人放进去，而不是去改内置角色。
-
-## 决策树：我要解决什么问题 → 用什么命令
-
-```text
-需要改「谁在组里」？
-├─ 加人 / 移人 ──────────────→ role user-resolve（拿 userId）→ role user-add / user-remove
-├─ 新建一个用户组 ───────────→ role create
-├─ 改组名 / 备注 ────────────→ role update（仅 CUSTOM）
-└─ 删除用户组 ──────────────→ role delete（仅 CUSTOM，high-risk）
-
-需要改「某个组能看/能做什么」？
-├─ 整个组看不到某些菜单 ─────→ permit role-menus  →  role-menus-set --revoke/--grant --menus
-├─ 整个组访问不了某些数据接口 → permit role-apis-set --revoke --datasets
-└─ 针对某一个页面精细配置 ───→ permit page-get  →  page-set
-     ├─ 该页对哪些角色可见 ──→ page-set --menu-roles
-     ├─ 该页的增/改/删/详情/导出 → page-set --create-roles/--update-roles/...
-     └─ 行级「只看自己」 ─────→ page-set --row-roles SELF
-```
-
-### `role-menus-set` 与 `page-set --menu-roles` 的区别（易混）
-
-两者都影响「菜单是否可见」，但入口和粒度不同，别用错：
-
-- **`permit role-menus-set`**：以**角色**为主体，一次性设置该角色在整个 app 的菜单权限矩阵（`roleType: PAGE`），按 `resourceCode` 翻转。适合「销售组不看财务菜单」这类**按组批量**收紧。
-- **`permit page-set --menu-roles`**：以**单个菜单页面**为主体，设置「这一页对哪些角色可见」，同时还能在同一页配置数据操作和行级权限。适合「就这一个页面的权限编排」。
-
-判断口径：问题描述里主语是「某个组」→ 走 `role-menus-set`；主语是「某个页面」→ 走 `page-set`。
-
-## 通用铁律
-
-1. **先读后写**：改成员先 `role user-resolve` + `role list`；改能力先 `permit page-get` / `role-menus` 拿到真实 `resourceCode` / `menuId` / `datasetCode`，不要臆造标识。
-2. **dry-run 必做**：所有写命令先 `--dry-run` 看 `data.before` / `data.after`，确认无误再复用同参数加 `--yes`。
-3. **read-merge-write 是 CLI 内部行为**：`update-user-list` / `page/save` / `role/update` 服务端都是**全量回写**；CLI 已内部读取全量、只改目标片段、其余原样带回。你只需传要改的部分，但要理解一次写会覆盖整份对象。
-4. **防漂移**：`user-add/user-remove` 可加 `--expect-user-count <n>`，当前成员数不符即中止。
-5. **SELF 只用于行级**：`SELF` 仅允许出现在 `page-set --row-roles`（`dataPermit`）；打到菜单/操作槽位会被拒绝。`ALL` 表示所有角色。
-6. **收紧不做自动 suggest**：`role-menus-set` / `role-apis-set` 必须显式 `--menus` / `--datasets`，避免误伤；先用 `dataset list` / `menu list` 定位目标。
-7. **运行态验证要交接**：`page-set --row-roles SELF`、`role-apis-set --revoke` 只写权限配置。要验证「登录后是否只看到自己的行 / 是否读不到财务数据」，交给 `lovrabet data filter` 在运行态确认，不要把它伪装成 `rabetbase` 已验证。
-8. **读内层协议，不读顶层 envelope**：写命令的稳定字段在 `data.*`（`operation` / `selector` / `before` / `after` / `dryRun` / `backend` / `warnings`），不含合成 `protocol` key。
-
-## 常见剧本
-
-### A. 把员工加入用户组（如：把小张加入开发者）
-
-```text
-role user-resolve --name 小张   → 拿 userId（重名报错，用 --user <id> 消歧）
-role list --type DEV            → 拿目标角色 id
-role user-add --role <id> --user <userId> --dry-run → --yes
-```
-
-### B. 新建一个用户组（如：创建销售组）
-
-```text
-role create --name 销售组 --dry-run
-role create --name 销售组 --remark "华东销售" --yes   → 从 data.selector.roleId 取回填的新 id
-```
-
-> 服务端 `role/create` 返回创建后的完整角色对象，CLI 直接将 id 填入 `data.selector.roleId`，不再按名称回查。
-
-### C. 让某组看不到财务（菜单 + API 双侧收紧）
-
-```text
-dataset list                                  → 定位财务域 datasetCode
-menu list                                     → 定位财务菜单 resourceCode
-permit role-menus-set --role <salesId> --revoke --menus <财务菜单codes> --dry-run → --yes
-permit role-apis-set  --role <salesId> --revoke --datasets <财务datasetCodes> --dry-run → --yes
-```
-
-菜单不可见 + 数据接口不可访问，两侧都要收紧，否则可能菜单藏了但接口还能拉数据。
-
-### D. 某个列表页只看自己的行（如：请假列表只看自己）
-
-```text
-menu list                                     → 定位该页 menuId
-permit page-get --menu-id <id>                → 确认 dataPermit 槽位存在
-permit page-set --menu-id <id> --row-roles SELF --dry-run → --yes
-```
-
-行级 `SELF` 打在 `dataPermit`，**不要** revoke 菜单本身。
-
-## 参考
-
-- [role list / detail / create / update / delete](../references/rabetbase-role-list.md)
-- [role user-resolve](../references/rabetbase-role-user-resolve.md)
-- [role user-add / user-remove](../references/rabetbase-role-user-add.md)
-- [permit page-get / page-set](../references/rabetbase-permit-page-set.md)
-- [permit role-menus / role-menus-set](../references/rabetbase-permit-role-menus-set.md)
-- [permit role-apis-set](../references/rabetbase-permit-role-apis-set.md)
-- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-permit-page-set.md

@@ -1,69 +0,0 @@
-# rabetbase permit page-get / page-set
-
-按菜单配置页面权限：菜单可见、数据操作（create/update/delete/detail/export）、行级可见（`dataPermit` = DATA_ROW）。角色字面量支持 `SELF` / `ALL` / 角色 id / 角色名（解析自 `get-permit-list`，含特殊组）。`SELF`（行级）**只允许**用于 `--row-roles`。
-
-`page-set` 是 `high-risk-write`：服务端 `page/save` 回写完整 `IPagePermit`，CLI 读取完整快照后只改传入的槽位，其余原样回写；只能设置 `page-get` 中已存在的槽位。
-
-## 命令
-
-```bash
-rabetbase permit page-get --menu-id 55 --format compress
-rabetbase permit page-set --menu-id 55 --row-roles SELF --dry-run
-rabetbase permit page-set --menu-id 55 --row-roles SELF --yes
-rabetbase permit page-set --menu-id 55 --menu-roles ALL,销售组 --yes
-```
-
-## page-get
-
-返回 `data.page`：`menuId`、`appCode`，以及 `menuPermit` / `dataCreate` / `dataUpdate` / `dataDelete` / `dataDetail` / `dataExport` / `dataPermit` 各槽的 `{ resourceCode, roles[] }`（roles 为 `{id, roleName, roleType}`）。槽位缺失表示该页面无此权限维度。
-
-## page-set 参数
-
-| Flag | 槽位 | 允许 SELF |
-|------|------|-----------|
-| `--menu-roles` | menuPermit（目录可见） | 否 |
-| `--create-roles` | dataCreate | 否 |
-| `--update-roles` | dataUpdate | 否 |
-| `--delete-roles` | dataDelete | 否 |
-| `--detail-roles` | dataDetail | 否 |
-| `--export-roles` | dataExport | 否 |
-| `--row-roles` | dataPermit（行级可见） | 是（SELF = 只看自己） |
-
-每个值是逗号分隔的角色字面量。至少传一个槽位 flag。传入不存在的槽位会报错。
-
-## 用例 5（请假列表只看自己）
-
-行级 `SELF` 打在 `dataPermit`，**不要** revoke 菜单：
-
-```bash
-rabetbase menu list                              # 定位请假列表 menuId
-rabetbase permit page-get --menu-id <id> --format compress
-rabetbase permit page-set --menu-id <id> --row-roles SELF --dry-run
-rabetbase permit page-set --menu-id <id> --row-roles SELF --yes
-```
-
-## 输出协议
-
-```json
-{
-  "operation": "page-set",
-  "selector": { "appCode": "app-xxx", "menuId": 55, "slots": ["dataPermit"] },
-  "before": { "dataPermit": { "resourceCode": "ROW_1", "roles": [{ "id": -1, "roleName": "ALL", "roleType": "ALL" }] } },
-  "after": { "dataPermit": { "resourceCode": "ROW_1", "roles": [{ "id": 0, "roleName": "SELF", "roleType": "SELF" }] } },
-  "dryRun": true,
-  "backend": { "method": "POST", "path": "/smartapi/permit/page/save" },
-  "warnings": []
-}
-```
-
-不含合成 `protocol`。校验读 `data.after.<slot>.roles`。
-
-## 运行态验证交接
-
-`page-set --row-roles SELF` 只写入权限配置。要验证「登录后 filter 是否只返回自己的行」，交给 `lovrabet data filter` 在运行态执行验证。
-
-## 参考
-
-- [permit role-menus-set / role-apis-set](rabetbase-permit-role-menus-set.md)
-- [menu list](rabetbase-menu-list.md)
-- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-permit-role-apis-set.md

@@ -1,53 +0,0 @@
-# rabetbase permit role-apis-set
-
-按 `datasetCode` 收回角色的**数据集 API** 访问（`roleType: API`）。`high-risk-write`。一期以 `--revoke` 为主满足用例 4（销售组不能访问财务数据接口）。
-
-`datasetCode → resourceCode` 映射与当前全量 API 权限状态来自内部读取的 `get-api-list`（服务端标 `@Deprecated`，CLI 内部读、不做公开命令）。CLI 读取全量后只把指定 datasets 的 resourceCodes 置为 `0`，其余保持当前动作后全量回写。
-
-## 命令
-
-```bash
-rabetbase permit role-apis-set --role 销售组 --revoke --datasets ds_finance --dry-run
-rabetbase permit role-apis-set --role 销售组 --revoke --datasets ds_finance,ds_invoice --yes
-```
-
-## 参数
-
-| Flag | 必填 | 说明 |
-|------|------|------|
-| `--role <id\|name>` | 是 | 目标角色（DEV/ADMIN 拒绝） |
-| `--revoke` | 是 | 一期语义固定为收回；缺失会报 validation |
-| `--datasets <code,...>` | 是 | 逗号分隔 datasetCode；该角色 API 资源里不存在的 code 报错 |
-| `--appcode <code>` | 否 | 覆盖当前 app |
-
-## 输出协议
-
-```json
-{
-  "operation": "api-revoke",
-  "selector": { "appCode": "app-xxx", "roleId": 12, "roleName": "销售组", "datasetCodes": ["ds_finance"] },
-  "before": [{ "resourceCode": "API_FIN_1", "datasetCode": "ds_finance", "action": "access" }],
-  "after": [{ "resourceCode": "API_FIN_1", "datasetCode": "ds_finance", "action": "0" }],
-  "dryRun": true,
-  "backend": { "method": "POST", "path": "/smartapi/permit/role/update", "roleType": "API" },
-  "warnings": []
-}
-```
-
-不含合成 `protocol`。校验读 `data.after`（应全部为 `action: "0"`）。
-
-## 用例 4（完整：菜单 + API 双侧收紧）
-
-```bash
-rabetbase dataset list                       # 定位财务域 datasetCode
-rabetbase permit role-menus-set --role <salesId> --revoke --menus <财务菜单> --dry-run|--yes
-rabetbase permit role-apis-set  --role <salesId> --revoke --datasets <财务datasetCode> --dry-run|--yes
-```
-
-菜单不可见 + 数据接口不可访问，两侧都要收紧。真实「登录后是否读不到财务行」用 `lovrabet` 运行态验证。
-
-## 参考
-
-- [permit role-menus / role-menus-set](rabetbase-permit-role-menus-set.md)
-- [dataset list](rabetbase-dataset-list.md)
-- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-permit-role-menus-set.md

@@ -1,57 +0,0 @@
-# rabetbase permit role-menus / role-menus-set
-
-查看与设置某角色的**菜单**权限矩阵（`roleType: PAGE`）。`role-menus-set` 是 `high-risk-write`：CLI 读取角色全量菜单资源，只翻转 `--menus` 指定的 `resourceCode`，其余保持当前动作后全量回写 `permits`。
-
-**内置角色守卫**：DEV / ADMIN 的权限矩阵不可改，会被 validation 拒绝。
-
-## 命令
-
-```bash
-rabetbase permit role-menus --role 销售组 --format compress
-rabetbase permit role-menus-set --role 销售组 --revoke --menus MENU_FIN_1,MENU_FIN_2 --dry-run
-rabetbase permit role-menus-set --role 销售组 --grant --menus MENU_SALES_1 --yes
-```
-
-## role-menus（读）
-
-返回 `data.menus[]`：`resourceCode`、`resourceName`、`allowed`（是否 `access`）、`action`。用它拿到可用的 `resourceCode` 再去 set。
-
-## role-menus-set 参数
-
-| Flag | 必填 | 说明 |
-|------|------|------|
-| `--role <id\|name>` | 是 | 目标角色（DEV/ADMIN 拒绝） |
-| `--grant` / `--revoke` | 是（二选一） | 授予（`access`）或收回（`0`） |
-| `--menus <code,...>` | 是 | 逗号分隔的菜单 `resourceCode`；未知 code 报错 |
-| `--appcode <code>` | 否 | 覆盖当前 app |
-
-## 输出协议
-
-```json
-{
-  "operation": "menu-revoke",
-  "selector": { "appCode": "app-xxx", "roleId": 12, "roleName": "销售组", "resourceCodes": ["MENU_FIN_1"] },
-  "before": [{ "resourceCode": "MENU_FIN_1", "action": "access" }],
-  "after": [{ "resourceCode": "MENU_FIN_1", "action": "0" }],
-  "dryRun": true,
-  "backend": { "method": "POST", "path": "/smartapi/permit/role/update", "roleType": "PAGE" },
-  "warnings": []
-}
-```
-
-## 用例 4（菜单侧：销售组不看财务菜单）
-
-```bash
-rabetbase dataset list                      # 定位财务域
-rabetbase permit role-menus --role <salesId>
-rabetbase permit role-menus-set --role <salesId> --revoke --menus <财务菜单resourceCodes> --dry-run
-rabetbase permit role-menus-set --role <salesId> --revoke --menus <...> --yes
-```
-
-一期不做自动 suggest，必须显式 `--menus`，避免误伤非财务菜单。API 侧收紧见 [`role-apis-set`](rabetbase-permit-role-apis-set.md)。
-
-## 参考
-
-- [permit role-apis-set](rabetbase-permit-role-apis-set.md)
-- [permit page-get / page-set](rabetbase-permit-page-set.md)
-- [SKILL.md](../SKILL.md)