@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

package/skills/rabetbase/guides/menu-anomaly-manual-cleanup.md

@@ -0,0 +1,137 @@
+# 菜单异常审计与安全修复
+
+用于重复 `path`、根级菜单重名、疑似菜单同步重复创建等场景。默认通过 `menu list` 审计；CLI 只按精确 ID 生成可审阅计划，页面菜单或目录树必须完整暴露影响后再执行。
+
+## 执行原则
+
+- 菜单事实只从 `rabetbase menu list --verbose` 获取。
+- 不绕过 `rabetbase menu list --verbose` 读取菜单配置。
+- 删除只能使用精确菜单 ID，不得根据 label/path 自动猜测目标。
+- 单删允许 `resources=[]` 的空 folder 或任意非 folder 叶子菜单；非空 folder 必须显式 `--recursive`。
+- 页面菜单删除会触发平台既有 Page/PageSchema 级联；同一 pageId 被计划外菜单引用时必须阻断。
+- 删除先用 `--id` 和 `--plan-out` 生成计划，确认后只使用 `--plan <file> --yes` 执行；层级调整仍交由平台处理。
+
+## 平台入口
+
+先按当前 `rabetbase` 环境计算 `<appBaseUrl>`：
+
+```text
+production https://app.lovrabet.com/app/<appCode>
+daily      https://daily.lovrabet.com/web-app/app/<appCode>
+```
+
+总入口：
+
+```text
+<appBaseUrl>/pages
+```
+
+精细入口：
+
+```text
+<appBaseUrl>/pages/<menuCode>
+```
+
+当菜单 `path` 可作为页面标识使用时，可生成：
+
+```text
+<appBaseUrl>/pages/<encodeURIComponent(menu.path)>
+```
+
+重复 `path` 场景下，多条异常菜单的精细入口可能相同；这只能帮助用户快速进入页面配置，不能替代按 `id / parentId / label` 做删除确认。
+
+## 审计步骤
+
+1. 读取菜单事实：
+
+```bash
+rabetbase menu list --appcode <appCode> --verbose --format json
+```
+
+`menu list` 返回 DFS 扁平数组，并直接提供 `childrenIds`、`childrenCount`、`pageId` 和 `pageType`。
+
+2. 按规则分类异常：
+
+必须修复：
+- 非空 `path` 重复。
+- `parentId` 指向不存在的菜单。
+- 菜单树出现循环引用。
+- 同一父级下重复关键业务菜单。
+
+需要人工确认：
+- 根级 `label` 重复。
+- `visible=false` 但仍有 `path` 或 `resources`。
+- 多个菜单共享同一 `pageId`。
+- `procode` 菜单缺少 resources，但同组重复菜单存在 resources。
+
+不默认视为异常：
+- 空 `path` 的 folder。
+- 不同父级下的同名 `label`。
+- folder 没有 resources。
+
+3. 输出修复清单：
+
+```text
+平台总入口: <appBaseUrl>/pages
+精细入口: <appBaseUrl>/pages/<menuCode>
+
+异常类型: duplicate_path
+path: <path>
+建议保留:
+- id: <id>, label: <label>, parentId: <parentId>, resources: <count>
+建议删除:
+- id: <id>, label: <label>, type: <type>, parentId: <parentId>, childrenCount: <count>, pageId: <pageId|null>, resources: <count>
+停止条件:
+- 平台无法确认该 id
+- 目标不是空 folder、非 folder 叶子或已完整计划的 folder 子树
+- pageId 被计划外菜单引用
+- folder resources 不为空
+- 平台显示与清单不一致
+```
+
+4. 对确认后的精确目标先预演。空 folder 或非 folder 叶子使用单目标计划：
+
+```bash
+rabetbase menu delete \
+  --appcode <appCode> \
+  --id <menuId> \
+  --expect-parent-id <id|root> \
+  --expect-path '<path>' \
+  --expected-children-count 0 \
+  --dry-run \
+  --plan-out ./menu-delete-<menuId>.plan.json \
+  --format compress
+```
+
+非空 folder 使用递归计划，并完整审阅 `targets`、`deleteOrder`、`cascade.pages` 和 `warnings`：
+
+```bash
+rabetbase menu delete \
+  --appcode <appCode> \
+  --id <folderId> \
+  --recursive \
+  --dry-run \
+  --plan-out ./menu-tree-delete-<folderId>.plan.json \
+  --format compress
+```
+
+确认 dry-run 的 `before`、`snapshotHash`、完整目标集合和叶子优先顺序后，在 30 分钟内执行：
+
+```bash
+rabetbase menu delete \
+  --plan <reviewed-plan-file> \
+  --yes \
+  --format compress
+```
+
+计划绑定 `appCode`、菜单快照、完整目标事实和删除顺序；任一事实漂移、计划缺项、时间字段异常或计划过期都应重新生成计划。发生部分失败时以 `remainingIds` 为事实重新生成计划，不复用旧计划。需要管理 folder 的 label 或 sort 时使用 `group-update`；调整归属仍转平台处理，并在完成后用 `menu list` 回查。
+
+5. 再读取菜单事实并复查：
+
+```bash
+rabetbase menu list --appcode <appCode> --verbose --format json
+```
+
+复查至少确认重复 `path` 清零、目标保留菜单仍存在、resources 符合预期。
+
+CLI 返回 blocker 时不要绕过；把清单交给用户核实计划外引用或平台事实，处理后仍用 `menu list` 回查。

package/skills/rabetbase/guides/page-development-workflow.md

@@ -0,0 +1,187 @@
+# 智能列表页（Smart List Page，page）工作流
+
+前置知识：已完成 `rabetbase auth` 登录，当前上下文已有 `appcode`，并已理解 `knowledge/page-schema/` 是 PageSchema 组件知识，不是 `rabetbase page` 命令说明。
+
+## 适用范围
+
+本工作流只适用于 **智能列表页（Smart List Page，DOV2 `smart_page`）** 路径：
+
+- 基于数据集首次生成智能列表页
+- 数据集字段变更后同步已有智能列表页
+- 将智能列表页 schema 拉到本地进行 IDE 修改，再推回平台
+
+不适用于：
+
+- 平台 WebCode 页面
+- 本地主子应用开发（使用 `rabetbase project`）
+- 只凭“数据集缺页”就批量生成所有页面的场景
+
+评论、附件、历史记录等子资源，默认不优先作为独立主页面；若业务目标不是标准智能列表页（Smart List Page），先停下来确认是否还应继续走 `page` 工作流。
+
+## 核心原则
+
+1. 智能列表页是“标准后台”方案，不是所有数据集的默认答案。
+2. 平台是页面权威来源；本地 schema 开发也必须通过 `pull -> IDE 编辑 -> push` 闭环。
+3. 新编排与自动化链路统一按 async-first 契约编排：任务状态查询与页面事实查询分离。
+4. 生产环境先做 `--dry-run`，确认目标、页面组和风险后再执行真实写操作。
+
+## 工作流
+
+```text
+确认业务目标 → 校验数据集与关联页 → 判断 generate-start 还是 sync → [按需]pull → IDE 编辑 → push --dry-run → push
+```
+
+### 1. 确认业务目标
+
+先确认这次目标是不是智能列表页最擅长的事情：
+
+- 列表 / 新建 / 编辑 / 详情型智能列表页（Smart List Page）
+- 标准管理后台
+- 单数据集或轻度关联数据集
+
+如果目标是工作台、看板、时间轴、复杂协作视图，说明它不属于本地 `rabetbase page` 工作流；本地研发工程师应改走 `rabetbase project` 主子应用开发路径。
+
+### 2. 校验数据集与关联页
+
+执行以下命令拿事实，不要凭经验判断：
+
+```bash
+rabetbase dataset detail --code <datasetCode> --format json
+rabetbase dataset relations --datasetcode <datasetCode> --format json
+```
+
+重点确认：
+
+- 数据集是否存在
+- 字段名、字段类型、关联关系是否符合预期
+- `relatedPages` 中是否已有未删除智能列表页
+
+### 3. 判断用 `generate-start / sync`
+
+规则如下：
+
+- **没有未删除关联页**
+  - 用 [`page generate-start`](../references/rabetbase-page-generate-start.md)
+- **已有未删除关联页** → 用 [`page sync`](../references/rabetbase-page-sync.md)
+
+推荐先做预演（`generate-start` 默认就是预演，必须显式 `--apply` 才提交）：
+
+```bash
+rabetbase page standard-page-status --datasetcode <datasetCode> --format json
+rabetbase page generate-start --datasetcode <datasetCode> --format json
+rabetbase page sync --datasetcode <datasetCode> --dry-run --format json
+```
+
+不要在已有页面时继续强行 `generate-start --apply`，也不要在完全没页时直接 `sync`。
+
+真实提交生成后，保存返回的 `taskId`、`operationId` 和 `clientOperationId`，优先直接执行返回的 `query.command`，用同一任务标识查询：
+
+```bash
+rabetbase page generate-start --datasetcode <datasetCode> --apply --format json
+rabetbase page generate-status --datasetcode <datasetCode> --task-id <taskId> --format json
+```
+
+`taskId` 是首选查询标识；只有旧响应没有 taskId 时才回退 `operationId`，两者都丢失时再用 `clientOperationId`。三种标识必须且只能传一个。查询超时、未知状态或网络失败时继续查询原任务，不重新提交生成。成功终态后，从 `standardPageStatus.pageSets[]` 读取页面事实和 `versionTag`；存在多个完整组、残留页或冲突时交给用户确认，不猜测页面组。
+
+### 4. 拉取页面 schema 到本地
+
+需要本地开发 formal schema 时，执行 [`page pull`](../references/rabetbase-page-pull.md)：
+
+```bash
+rabetbase page pull --id <pageId> --format json
+rabetbase page pull --datasetcode <datasetCode> --format json
+rabetbase page pull --datasetcode <datasetCode> --version-tag <versionTag> --format json
+```
+
+规则：
+
+- `--id` 用于单页
+- `--datasetcode` / `--alias` 用于按数据集批量
+- 同一命令里 `--id` 与 `--datasetcode` / `--alias` 互斥
+- 生成链路优先使用 `page generate-status` 的 `standardPageStatus.pageSets[].versionTag`
+- 批量模式下若同一数据集存在多组页面且 `versionTag` 不唯一，必须由用户确认后显式传 `--version-tag`
+
+本地文件位置：
+
+- 页面文件：`.rabetbase/page/<appCode>/<pageId>-<TYPE>.json`
+- lock 文件：`.rabetbase/page.lock.json`
+
+### 5. 在 IDE 中修改 schema
+
+本地修改时遵循两条底线：
+
+1. 先 `pull` 建立基线，不要手工从零伪造页面文件
+2. 如需理解 PageSchema 组件语义，再按需查看 `knowledge/page-schema/`；那是组件知识，不是 CLI 命令 reference
+
+### 6. 推送前先做 `push --dry-run`
+
+真实推送前，先执行 [`page push`](../references/rabetbase-page-push.md) 的预演：
+
+```bash
+rabetbase page push --id <pageId> --dry-run --format json
+rabetbase page push --datasetcode <datasetCode> --version-tag <tag> --dry-run --format json
+```
+
+预演阶段重点看：
+
+- 本地是否存在基线
+- 远端页面版本是否已变化
+- 批量模式下目标页面组是否正确
+
+若命令提示先重新 `pull`，不要盲推覆盖。
+
+### 7. 推送回平台
+
+确认无误后再执行真实推送：
+
+```bash
+rabetbase page push --id <pageId> --format json
+rabetbase page push --datasetcode <datasetCode> --version-tag <tag> --format json
+```
+
+推送成功后，CLI 会自动回拉远端 canonical schema 覆盖本地文件和 lock。这个行为是预期的，不要把它当作“本地改动丢失”；它的目的是让本地重新回到平台权威状态。
+
+## 常见分支
+
+### A. 首次补齐智能列表页
+
+```text
+dataset detail → standard-page-status → page generate-start（默认预览） → page generate-start --apply → 保存 taskId → page generate-status → 从 standardPageStatus.pageSets[] 选择 versionTag
+```
+
+适用于：
+
+- 主业务对象还没有任何智能列表页
+- 目标是快速补齐标准智能列表页（Smart List Page）
+
+### B. 字段变更后同步已有智能列表页
+
+```text
+dataset detail → page sync --dry-run → page sync
+```
+
+适用于：
+
+- 数据集字段已变化
+- 关联智能列表页已经存在
+
+### C. 本地 schema 开发
+
+```text
+page pull → IDE 编辑 → page push --dry-run → page push
+```
+
+适用于：
+
+- 智能列表页已经生成
+- 需要在 formal schema 层做本地定制
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase-page-generate-start.md](../references/rabetbase-page-generate-start.md)
+- [rabetbase-page-generate-status.md](../references/rabetbase-page-generate-status.md)
+- [rabetbase-standard-page-status.md](../references/rabetbase-standard-page-status.md)
+- [rabetbase-page-sync.md](../references/rabetbase-page-sync.md)
+- [rabetbase-page-pull.md](../references/rabetbase-page-pull.md)
+- [rabetbase-page-push.md](../references/rabetbase-page-push.md)

package/skills/rabetbase/guides/react-custom-page-workflow.md

@@ -0,0 +1,184 @@
+# React 自定义页面工作流
+
+本指南说明如何使用 `rabetbase` 创建、修改和发布 React 自定义页面。页面内容由完整 JSX、样式和多语言文件组成。
+
+## 适用范围
+
+适用于以下目标：
+
+- 新建或修改 React 自定义页面、看板、门户、落地页或复杂交互页面
+
+## 前置上下文
+
+- 创建页面前确认 `appCode`；修改页面前确认 `pageId`
+- 确认页面目标，以及影响实现的布局、交互、数据和样式约束
+- 无法确定新建页面或目标页面时，先向用户确认
+
+## 编排规则
+
+### 新建页面
+
+1. 先阅读 [`rabetbase-page-react-create.md`](../references/rabetbase-page-react-create.md)
+2. 可选传入完整 `--page-content`；省略时 CLI 生成默认文件。先执行 `page react-create --dry-run`，确认页面名称、父菜单和最终页面文件
+3. 经用户确认后创建页面，记录 `data.after.pageId`。新页面默认尚未发布
+4. 执行 `page react-detail --id <pageId>`，以 `data.codeContent` 中的完整页面文件为修改基线
+5. 需要定制初始文件时，再按“更新页面”流程保存完整页面文件
+
+创建页面会同时创建菜单入口。不得额外调用菜单创建命令重复创建入口。
+
+### 查找或修改已有页面
+
+1. 未知页面 ID 时，先阅读 [`rabetbase-page-react-list.md`](../references/rabetbase-page-react-list.md)，执行 `page react-list --appcode <appCode>`
+2. 根据 `data.pages[].pageId` 与 `label` 与用户确认目标页面；`data.pages[].pageUrl` 用于查看最新保存内容，`data.pages[].editPageUrl` 用于打开页面编辑器
+3. 阅读 [`rabetbase-page-react-detail.md`](../references/rabetbase-page-react-detail.md)，执行 `page react-detail --id <pageId>`
+4. 只在返回的最新 `data.codeContent` 基础上编辑，不得根据旧缓存或猜测覆盖文件
+
+### 更新页面
+
+1. 阅读 [`rabetbase-page-react-update.md`](../references/rabetbase-page-react-update.md)
+2. 将新增、修改和保留的所有文件整理为完整 `page-content` JSON
+3. 先执行 `page react-update --dry-run` 审阅完整页面文件
+4. 经用户确认后执行更新
+5. 再执行 `page react-detail --id <pageId>`，确认 `codeContent` 已包含预期文件和内容
+6. 已发布页面更新后，最新保存内容需要再次发布，用户访问的已发布页面才能看到本次修改
+
+`page react-update` 会完整保存页面文件：未提交的文件会被删除。不得仅提交本次修改的单个文件，也不得为删除文件再调用不存在的独立删除命令。
+
+当前 CLI 没有逐文件新增、编辑或删除命令。将本地文件操作整理为完整 `codeContent` 后再调用 `react-update`；每次更新都会创建一个新的保存版本，`react-detail` 默认读取最新页面内容。
+
+### 发布页面
+
+1. 先执行 `page react-detail --id <pageId>`，确认当前 `data.status`
+2. 当前状态为 `FORMAL` 时，表示当前保存内容已发布，不执行 `page react-publish`，直接查看已发布页面或继续后续流程
+3. 当前状态不是 `FORMAL` 时，读取 [`rabetbase-page-react-publish.md`](../references/rabetbase-page-react-publish.md)，再执行 `page react-publish --dry-run`
+4. 发布会影响用户实际访问的页面，必须取得用户明确确认后再执行
+5. 从 `data.after.status` 确认 `FORMAL`，表示内容已发布
+
+`data.pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`data.editPageUrl` 用于打开页面编辑器；`page react-publish` 成功返回的 `data.runtimePageUrl` 用于查看已发布内容。不要将三者混用。
+
+## 页面生命周期
+
+React 页面有“未发布”和“已发布”两种状态。未发布的修改可通过 `pageUrl` 或编辑器查看，已发布页面只展示最近一次发布的内容。
+
+```text
+page react-create
+  → 未发布
+  → 生成或更新完整页面文件
+  → 未发布
+  → page react-publish
+  → 已发布（FORMAL）→ 可通过 runtimePageUrl 查看已发布内容
+  → page react-update
+  → 未发布（已发布页面仍显示上一次发布内容）
+  → page react-publish
+  → 已发布（FORMAL）→ 已发布页面展示最新发布内容
+```
+
+| 阶段 | `pageUrl` 或编辑器可见内容 | 已发布页面可见内容 | 下一步 |
+| --- | --- | --- | --- |
+| 创建后 | 初始页面文件，尚未发布 | 无新发布内容 | 读取详情并生成或更新内容 |
+| 更新后、未发布 | 最新保存内容，尚未发布 | 最近一次已发布内容 | 完成自检并发布 |
+| 发布后 | 当前已发布版本，状态为 `FORMAL` | 本次已发布内容 | 通过 `runtimePageUrl` 查看或继续修改 |
+| 已发布后再次更新 | 最新保存内容，尚未发布 | 更新前的已发布内容 | 再次发布后才切换已发布页面内容 |
+
+`page react-detail` 用于确认最新保存内容，`page react-publish` 用于发布当前保存内容。不要仅因 `react-update` 成功就认为已发布页面已经更新。
+
+`react-detail` 返回 `FORMAL` 时，表示当前保存内容已经发布。没有新的修改时，跳过重复发布，继续查看已发布页面或后续流程。
+
+### 地址语义
+
+| 操作结果 | 输出字段 | 用途 |
+| --- | --- | --- |
+| 创建/保存成功 | `pageUrl`、`editPageUrl` | `pageUrl` 查看最新保存内容，`editPageUrl` 打开页面编辑器 |
+| 发布成功 | `runtimePageUrl` | 查看最近一次已发布内容 |
+| 页面查询 | `pageUrl`、`editPageUrl` | 快速打开最新保存内容或页面编辑器 |
+
+## 数据与服务契约
+
+### 选型
+
+- 单个数据集的常规查询和写入，使用数据集模型能力
+- 页面需要组合多个数据集的数据时，考虑使用自定义 SQL
+- 数据需要个性化处理、复杂业务编排或调用外部服务时，考虑使用 BFF
+
+页面需要读取或写入数据集时，先按以下顺序确认事实：
+
+1. `rabetbase dataset list --appcode <appCode>` 查找可用数据集
+2. `rabetbase dataset detail --code <datasetCode>` 确认字段、类型和必填约束
+3. `rabetbase dataset operations --code <datasetCode>` 确认可用操作及其输入
+4. 需要生成调用示例时，阅读 [`rabetbase-codegen-sdk.md`](../references/rabetbase-codegen-sdk.md)，使用 `rabetbase codegen sdk`
+
+页面需要调用自定义 SQL 或 BFF 时，先通过当前 CLI 获取目标资源事实：
+
+1. SQL：执行 `rabetbase sql list`，再执行 `rabetbase sql detail --sqlcode <sqlCode>` 确认目标 SQL
+2. BFF：执行 `rabetbase bff list`，再执行 `rabetbase bff detail --id <id>` 确认目标脚本
+3. 按 `@lovrabet/sdk` 的使用规范实现 `client.sql` 或 `client.bff` 调用，不得根据 CLI 返回结构猜测页面调用参数或返回值
+4. 页面使用自定义 SQL 前，使用代表性参数执行 `rabetbase sql exec --sqlcode <sqlCode> --params <json> --format json`，确认执行没有报错并检查实际数据结构
+5. `sql exec` 仅用于确认 SQL 可执行及返回数据结构。页面代码按 `@lovrabet/sdk` 的使用规范处理 `client.sql` 的返回值，不使用 CLI 输出字段 `data.rows`
+
+当前 CLI 没有按单个数据集返回页面数据访问说明的专用命令。在页面中使用 `client` 前，必须以数据集、SQL 或 BFF 的事实，以及对应的 `@lovrabet/sdk` 使用规范为依据；无法确认的字段、接口路径和响应结构不得猜测。
+
+## 页面开发参考
+
+编写页面内容前，先阅读 [`generation-standards.md`](../knowledge/react-page/generation-standards.md)。
+
+- 选择、组合或新增 UI 组件时，按需阅读 [`components.md`](../knowledge/react-page/components.md)
+- 调用页面上下文、国际化、路由或数据客户端时，按需阅读 `generation-standards.md` 中的“页面上下文内置能力”
+- 未登记的组件、方法、参数和返回结构不得猜测，先补充确认后的规范再复用
+
+## 页面文件与代码约束
+
+默认文件结构：
+
+```text
+src/app/index.jsx
+src/app/index.css
+src/locales/index.js
+src/components/*.jsx
+```
+
+代码遵循以下约束：
+
+- 仅导入 [`generation-standards.md`](../knowledge/react-page/generation-standards.md)“依赖白名单”中的包及其子路径
+- 使用页面上下文时，从 `@/context/app-context` 导入 `useSdkClient`、`useI18n`、`useNavigate`、`useLocation`
+- 数据读取或写入前，先确认数据集及 SDK 用法；接口或字段无法从现有事实确认时，不得猜测请求协议
+- 所有用户可见文案通过 `$i18n.t("key")` 获取，并在 `src/locales/index.js` 提供有效翻译
+- 路由跳转使用 `navigate`，读取地址信息使用 `location`；关联页面优先使用 `navigate("/pagecode", { onePage: true })`
+- CSS 使用 Ant Design CSS 变量，不写死颜色或其他样式常量
+- 不新增白名单外依赖，不使用 `window.location`
+
+未传 `--page-content` 时，`react-create` 生成基础 JSX、样式和词包。首次自定义时，将初始文案和样式一并调整为上述约束后再发布，不把初始化模板视为最终页面实现。
+
+## 页面内容自检
+
+在首次提交或每次更新完整 `codeContent` 前，按以下顺序自检：
+
+1. 先用 `page react-detail --id <pageId>` 读取最新页面文件，避免覆盖其他尚未发布的修改
+2. 确认提交内容包含全部需要保留的文件，入口、样式、词包和组件之间的导入路径一致
+3. 对照 [`generation-standards.md`](../knowledge/react-page/generation-standards.md) 检查依赖白名单、国际化、路由、样式和数据契约
+4. 使用组件或内置方法时，分别对照 `components.md` 和 `generation-standards.md` 中的“页面上下文内置能力”，确认不存在未登记的属性、方法或返回结构假设
+5. 先完成“页面生成规范”中的静态自检，再执行 `page react-update --dry-run`。CLI 会阻止缺少 React 源码或存在基础 JS/JSX/TS/TSX 语法错误的内容，但不推断变量引用、模块导出、数据契约或运行时行为
+6. 更新后再次执行 `page react-detail --id <pageId>`，确认最新保存的 `codeContent` 与提交内容一致
+7. 需要让用户查看已发布页面时，先检查最新 `data.status`。状态为 `FORMAL` 时跳过发布；否则执行 `page react-publish --dry-run`、取得确认后发布，并确认 `data.after.status` 为 `FORMAL` 和 `data.runtimePageUrl` 已返回
+
+当前 CLI 不提供已发布页面截图或自动浏览器预览。发布成功后，使用返回的 `data.runtimePageUrl` 打开已发布页面进行人工预览。
+
+## 最小验证闭环
+
+```text
+新建：react-create --dry-run → react-create → react-detail → [按需] react-update --dry-run → react-update → react-detail → [尚未发布（status 非 FORMAL）且经确认] react-publish --dry-run → react-publish
+
+修改：react-list（按需）→ react-detail → react-update --dry-run → react-update → react-detail → [尚未发布（status 非 FORMAL）且经确认] react-publish --dry-run → react-publish
+```
+
+CLI 当前不提供本地预览或独立删除命令。
+
+## 参考
+
+- [`rabetbase-page-react-create.md`](../references/rabetbase-page-react-create.md)
+- [`rabetbase-page-react-list.md`](../references/rabetbase-page-react-list.md)
+- [`rabetbase-page-react-detail.md`](../references/rabetbase-page-react-detail.md)
+- [`rabetbase-page-react-update.md`](../references/rabetbase-page-react-update.md)
+- [`rabetbase-page-react-publish.md`](../references/rabetbase-page-react-publish.md)
+- [`generation-standards.md`](../knowledge/react-page/generation-standards.md)
+- [`components.md`](../knowledge/react-page/components.md)
+- [`rabetbase-codegen-sdk.md`](../references/rabetbase-codegen-sdk.md)

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

@@ -0,0 +1,127 @@
+# 用户组与权限（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)