@lovrabet/rabetbase-cli 2.5.3-beta.1 → 2.5.3-beta.2

package/skills/rabetbase/references/rabetbase-flow-resources.md

@@ -0,0 +1,83 @@
+# 流程定义资源发现
+
+FlowConfig 中的真实标识必须来自 CLI 查询，不得由 Agent 猜测。
+
+## 映射
+
+| FlowConfig 字段 | 发现命令 | 选中值 |
+|---|---|---|
+| 外层 `datasetCode` | `dataset list`、`dataset detail` | Dataset `code` |
+| 外层 `pageId` | `menu list` | 与目标页面对应的 `pageId` |
+| `flowJson.startPageId` | `page custom-list`、`page custom-detail` | 自定义页面 `pageId` |
+| `APPROVAL.pageId` | `page custom-list`、`page custom-detail` | 自定义页面 `pageId` |
+| `APPROVAL.assignee.userIds` | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `APPROVAL.assignee.roleId` | `flow runtime-role-list` | 运行态角色 `id` |
+| 角色成员核对 | `flow runtime-role-user-list` | 运行态只读成员清单 |
+| `transferCandidates.userIds` | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `APPROVAL.cc.recipientUserIds` / `END.cc.recipientUserIds` | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `SCRIPT.scriptName` | `bff list --type ENDPOINT` | Endpoint `functionName` |
+| `APPROVAL.timeout.scriptName` | `bff list --type ENDPOINT` | Endpoint `functionName` |
+| `NOTIFICATION.config.configCode` | `notification config-list --all` | `configs[].configCode` |
+| `NOTIFICATION.config.recipients[].value`（固定 USER） | `flow runtime-user-search` | 运行态 `users[].userId` |
+| `NOTIFICATION.config.recipients[].value`（固定 ROLE） | `flow runtime-role-list` | 运行态角色 `id` |
+
+`startPageId` 和节点 `pageId` 只选择自定义页面事实，不使用菜单名称、URL 或编辑器地址代替数值 `pageId`。占位符形式的通知收件人来自运行态变量，不需要资源查询；固定 EMAIL 收件人由用户明确提供，不推断邮箱地址。
+
+## 搜索运行态应用用户
+
+```bash
+rabetbase flow runtime-user-search --keyword <text> [--page <n>] [--page-size <n>] --format compress
+```
+
+- 只查询当前运行态应用已关联的用户，对 userId、nickname、username、displayName、email 做不区分大小写的包含匹配。
+- 输出 `scope: "runtime"`、安全字段 `userId`、`username`、`nickname`、`displayName`、`email`、`status` 和分页信息。
+- 不输出手机号、访问密钥或无关身份字段。
+- 多个候选时必须由用户确认；不要默认取第一项。
+
+不要用 `role`、`app members-list` 或 `tenant members-list` 的人员结果填写审批 FlowConfig。
+
+## 查询运行态角色
+
+```bash
+rabetbase flow runtime-role-list [--keyword <role-name>] [--page <n>] [--page-size <n>] --format compress
+```
+
+- 查询当前应用运行态 `env=RUNTIME` 角色，`--keyword` 由服务端按角色名模糊过滤。
+- 输出 `scope: "runtime"`、角色 `id/name/type`、备注和人数/权限数安全摘要，不输出权限矩阵。
+- `APPROVAL.assignee.roleId` 只能使用这里返回的运行态角色 ID；不要使用 `role list/detail` 的配置端角色 ID。
+
+## 查看运行态角色成员
+
+```bash
+rabetbase flow runtime-role-user-list --role <role-id-or-name> [--page <n>] [--page-size <n>] --format compress
+```
+
+- 在当前应用运行态角色成员分组中按 ID 或精确名称解析角色。
+- 角色名称不唯一时要求改用角色 ID。
+- 输出 `scope: "runtime"`；只读，不修改成员关系。
+
+## 查询通知配置
+
+```bash
+rabetbase notification config-list --all --format compress
+rabetbase notification config-list --type EMAIL --format compress
+```
+
+- `--all` 查询 `EMAIL`、`FEISHU`、`DINGTALK`、`WECOM`、`WEBHOOK` 的安全摘要。
+- `--all` 与 `--type` 互斥；未指定时继续默认查询 `EMAIL`。
+- 只使用同一条记录的 `configCode`，不要用渠道名、URL、dataset code 或凭据代替。
+
+## 查询脚本
+
+```bash
+rabetbase bff list --type ENDPOINT --name <keyword> --format compress
+```
+
+只把确认后的 Endpoint `functionName` 写入 `SCRIPT.scriptName` 或 `APPROVAL.timeout.scriptName`。COMMON、HOOK 或展示名称不能替代 Endpoint 函数名。
+
+## 确认规则
+
+- 无候选：返回 `NEEDS_USER_CONFIRMATION` 并请求更精确关键词。
+- 多候选：展示稳定 ID、名称和必要上下文，请用户选择。
+- 唯一候选：可以推荐，但身份、角色、脚本和通知配置仍需用户确认。
+- 当前 DSL 无法表达需求：返回 `NEEDS_DSL_EXTENSION`，不要伪造配置。

package/skills/rabetbase/references/rabetbase-flow-runtime-boundary.md

@@ -0,0 +1,25 @@
+# 流程定义设计态与运行态边界
+
+`rabetbase flow` 管理 SmartCode 中的表单审批流与独立工作流定义；运行态待办和任务办理不属于本仓 CLI。
+
+## rabetbase 负责
+
+- 查询、导出和校验 FlowConfig。
+- 创建或更新设计态流程定义。
+- 发布流程定义。
+- 通过 dataset、menu、BFF、notification 命令发现设计资源；通过 `flow runtime-user-search/runtime-role-list/runtime-role-user-list` 只读发现审批所需的运行态人员和角色。
+
+## Runtime CLI 负责
+
+- 查询当前用户待办和任务详情。
+- 审批、拒绝和转交已有运行态任务。
+- 验证流程实例、业务状态和任务权限。
+
+`rabetbase` 只调用已核实的运行态人员/角色只读接口来生成 FlowConfig，不查询或办理任务。需要办理待办时，显式交接到 Runtime CLI 仓库及其公开 Skill。
+
+## 完成口径
+
+- `flow validate` 成功只表示本地结构和已实现的拓扑规则通过。
+- `flow create/update` 成功只表示服务端保存了设计态定义。
+- `flow publish` 是同步服务端操作；只有成功响应才表示发布完成，dry-run 不表示发布成功。
+- Runtime 最终行为仍需在 Runtime 环境中验证，不能用设计态查询代替。

package/skills/rabetbase/references/rabetbase-instant-api-policy.md

@@ -12,29 +12,114 @@
 
 `init`、`pull`、`validate` 和 `publish` 只使用该路径，不提供 `--file`。目标应用来自当前工作区、`--app <name>` 或 `--appcode <code>`。策略不存入 `.rabetbase.json` 或运行态 app-config。
 
-`version` 固定为字符串 `"1"`，表示 JSON 结构版本。`revision` 是服务端发布历史版本，首次发布为 1，后续发布和回滚递增；两者含义不同。
+`version` 是 JSON 结构版本：`"1"` 保持精确匹配兼容，`"2"` 支持通配选择和排除项；新版 CLI 的 `init` 默认创建版本 2。`revision` 是服务端发布历史版本，首次发布为 1，后续发布和回滚递增；两者含义不同。
 
 ## 配置结构
 
+### 先取得真实 Dataset 选择器
+
+策略匹配的是平台 Dataset，不是前端 SDK 的变量名。编辑前按下面顺序取得当前应用的事实：
+
+```bash
+# 更新当前应用的本地模型事实；多应用项目显式选择目标
+rabetbase api pull --appcode <appCode> --yes --format compress
+
+# 对将被规则覆盖的 Dataset 确认真实 code、字段和支持的操作
+rabetbase dataset detail --appcode <appCode> --code <datasetCode> --format compress
+```
+
+`api pull` 生成的模型条目包含 `datasetCode`、可选 `tableName` 和 SDK `alias`。规则中优先只写这个 `datasetCode`；**不能**写 `alias`。例如模型中的 `alias: "brand"` 只是 SDK 调用名，不是策略选择器。只有无法取得 code 的兼容场景才使用 `tableName`；若两者同时填写，服务端要求它们解析为同一个 Dataset。
+
+认证不可用、`api pull` 失败或模型文件明显过期时，停止配置并先恢复认证；不要根据业务名称、SDK alias 或旧截图猜测 `datasetCode`。
+
+### Dataset 选择器规则
+
+| 场景 | 合法写法 | 约束 |
+| --- | --- | --- |
+| v1/v2 的精确 Dataset | `{ "datasetCode": "<real-dataset-code>" }` | 首选；code 来自当前应用的 `api pull` 或 `dataset detail` |
+| v1/v2 的精确物理表 | `{ "tableName": "<real-table-name>" }` | 可用作兼容选择器；不能填 SDK alias |
+| v1/v2 双字段精确选择 | `{ "datasetCode": "…", "tableName": "…" }` | 两值必须解析为同一个 Dataset；已知 code 时不要冗余填写 tableName |
+| 仅 v2 的全部 Dataset | `{ "datasetCode": "*" }` | `datasets` 的唯一元素；不能附带 `tableName`，也不能与精确选择器混用 |
+
+`{ "tableName": "*" }` 在任何版本都不支持。版本 1 只接受上面的精确选择器，不能使用 Dataset/API 通配或 `excludes`。
+
+### 顶层字段
+
+| 字段 | 必填 | 取值 / 约束 | 作用 |
+| --- | --- | --- | --- |
+| `version` | 是 | `"1"` 或 `"2"`；新文件使用 `"2"` | JSON 结构版本，不是服务端发布 revision |
+| `appCode` | 是 | 必须等于当前命令解析出的应用 | 防止跨应用误发布 |
+| `defaults.instantApi` | 是 | `"allow"` 或 `"deny"` | 没有任何规则命中时的最终动作；不能是 `"route"` |
+| `rules` | 否 | 规则数组；缺省或空数组表示全部使用默认动作 | 对特定 Dataset + API 组合覆盖默认动作 |
+
+### 规则字段
+
+| 字段 | 必填 | 取值 / 约束 |
+| --- | --- | --- |
+| `name` | 是 | 稳定、可读的规则标识，方便审阅和版本回溯 |
+| `description` | 否 | 说明规则的业务目的和影响范围 |
+| `datasets` | 是 | 非空数组；每项优先仅 `{ "datasetCode": "<real-dataset-code>" }` |
+| `apis` | 是 | 非空数组，每项是独立 API 名；不能把多个 API 拼为一个逗号字符串 |
+| `action` | 是 | `"allow"`、`"deny"` 或 `"route"` |
+| `backendFunction` | 条件必填 | 仅 `action: "route"` 时填写；必须是同一应用的普通 `ENDPOINT`，不能是 Personal Backend Function |
+| `excludes` | 仅 v2 可用 | 从本规则的 Dataset × API 匹配集合中扣除的数组；每项都要有 `datasets` 和 `apis`，且不得超出父规则范围 |
+
+支持的 API 名称为：`getSelectOptions`、`getList`、`excelExport`、`filter`、`aggregate`、`getOne`、`getOneOrigin`、`create`、`batchCreate`、`update`、`delete`。
+
+规则数组**没有优先级**。服务端会先按每条规则的 Dataset × API 组合（扣除 `excludes` 后）计算覆盖范围；仍有重叠就校验失败，而不是“后一条覆盖前一条”。未被任何规则覆盖的组合回退到 `defaults.instantApi`。
+
+### 精确匹配示例
+
+下面的 `<real-dataset-code>` 必须替换为刚由 `api pull` 得到的 code，不能替换成 alias 或展示名称：
+
+```json
+{
+  "version": "2",
+  "appCode": "app-example",
+  "defaults": { "instantApi": "allow" },
+  "rules": [
+    {
+      "name": "deny-sensitive-export",
+      "description": "禁止敏感数据集通过 Instant API 导出",
+      "datasets": [{ "datasetCode": "<real-dataset-code>" }],
+      "apis": ["excelExport"],
+      "action": "deny"
+    }
+  ]
+}
+```
+
+这是默认放行下的最小收紧方式：仅该 Dataset 的 `excelExport` 被禁止，其他组合继续由默认动作处理。
+
+### 版本 2 通配与排除示例
+
 ```json
 {
-  "version": "1",
+  "version": "2",
   "appCode": "app-example",
   "defaults": {
     "instantApi": "allow"
   },
   "rules": [
     {
-      "name": "route-student-filter",
-      "description": "学生筛选交给业务 Backend Function",
-      "datasets": [
+      "name": "route-all-except-student-create",
+      "description": "除学生新增外，全部数据集操作交给统一 Backend Function",
+      "datasets": [{"datasetCode": "*"}],
+      "apis": ["*"],
+      "excludes": [
         {
-          "datasetCode": "student23"
+          "datasets": [{"datasetCode": "student23"}],
+          "apis": ["create"]
         }
       ],
-      "apis": ["filter"],
       "action": "route",
-      "backendFunction": "filterStudents"
+      "backendFunction": "unifiedGateway"
+    },
+    {
+      "name": "allow-student-create",
+      "datasets": [{"datasetCode": "student23"}],
+      "apis": ["create"],
+      "action": "allow"
     }
   ]
 }
@@ -43,8 +128,13 @@
 - `defaults.instantApi` 只允许 `allow` 或 `deny`，不能是 `route`。
 - `rules[].action` 允许 `allow`、`deny`、`route`。
 - `route` 必须填写 `backendFunction`；其他 action 禁止填写。
-- `datasets[]` 至少填写 `datasetCode` 或 `tableName`；建议优先使用稳定的 `datasetCode`。两者同时填写时必须指向同一 Dataset。
-- 同一个 `datasetCode + api` 只能命中一条规则；重复覆盖会校验失败。
+- `datasets[]` 至少填写 `datasetCode` 或 `tableName`；已知 code 时只填写稳定的 `datasetCode`。两者同时填写时必须指向同一 Dataset。
+- 版本 1 只支持精确匹配，不允许 `*` 或 `excludes`。
+- 版本 2 的全部数据集写为 `datasets: [{"datasetCode":"*"}]`。通配项必须是数组唯一元素且不能包含 `tableName`；不支持 `tableName: "*"`。
+- 版本 2 的全部 API 写为 `apis: ["*"]`，`"*"` 必须是数组唯一元素。
+- `excludes[]` 每项包含 `datasets` 和 `apis`，表示从父规则中扣除两者笛卡尔积；排除范围不能超出父规则。
+- 被排除的组合可以由后续其他规则处理；没有其他规则时执行 `defaults.instantApi`。
+- 排除后仍重复的 `datasetCode + api` 会校验失败，规则数组顺序不表示优先级。
 - `apis` 的每个元素是一个独立值。`["filter,create"]` 或包含中文逗号的 `["filter，create"]` 都不是两个 API。
 - 支持的 API：`getSelectOptions`、`getList`、`excelExport`、`filter`、`aggregate`、`getOne`、`getOneOrigin`、`create`、`batchCreate`、`update`、`delete`。
 
@@ -70,7 +160,7 @@ rabetbase instant-api-policy publish --expected-revision 0 --change-summary "ini
 rabetbase instant-api-policy publish --expected-revision 0 --change-summary "initial policy" --yes --format compress
 ```
 
-`init --default-action deny` 可以创建默认禁止草稿。`init` 和 `pull` 遇到不同的既有文件时停止；只有 `--force --yes` 可以替换。
+`init --default-action deny` 可以创建版本 2 的默认禁止草稿。`init` 和 `pull` 遇到不同的既有文件时停止；只有 `--force --yes` 可以替换。已有版本 1 文件仍可继续校验和发布。
 
 `validate` 调用服务端完整校验，返回 `configHash` 和 `normalizedConfig`，但不发布、不生成 revision。Dataset、API、规则重叠以及 Backend Function 合法性以该结果为准。
 
@@ -90,3 +180,5 @@ rabetbase instant-api-policy rollback --revision 2 --expected-revision 5 --chang
 回滚不会把 revision 倒退，也不会覆盖历史。例如当前 revision 为 5，恢复 revision 2 后会生成新的 revision 6。
 
 发布和回滚最多提交一次。CLI 随后读取当前策略，要求 configHash 匹配且 revision 推进。响应丢失但回读可以证明结果时返回 verified；证据不足时停止并提示执行 `current`，不得自动重提。Runtime 最迟约 30 秒感知新策略。
+
+数据集通配项按应用当前有效数据集展开；应用新增数据集后，会在 Runtime 策略缓存刷新时自动进入通配规则范围。

package/skills/rabetbase/references/rabetbase-notification-config-list.md

@@ -7,6 +7,7 @@
 ```bash
 rabetbase notification config-list --format compress
 rabetbase notification config-list --type EMAIL --format compress
+rabetbase notification config-list --all --format compress
 rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format json
 ```
 
@@ -20,6 +21,8 @@ rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format jso
 
 类型值使用大写。
 
+`--all` 会分别查询 `EMAIL`、`FEISHU`、`DINGTALK`、`WECOM`、`WEBHOOK`，合并为同一份安全摘要。`--all` 与 `--type` 互斥；不传二者时继续保持默认 `EMAIL` 行为。
+
 ## 输出
 
 ```json
@@ -45,6 +48,20 @@ rabetbase notification config-list --type EMAIL --appcode app-xxxxx --format jso
 }
 ```
 
+`--all` 输出使用 `data.channelTypes` 代替单个 `data.channelType`，`configs` 为五种类型结果的合并列表：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "appCode": "app-xxxxx",
+    "channelTypes": ["EMAIL", "FEISHU", "DINGTALK", "WECOM", "WEBHOOK"],
+    "count": 2,
+    "configs": []
+  }
+}
+```
+
 CLI 只输出用于选择配置的安全字段，不输出：
 
 * `channelConfig`

package/skills/rabetbase.manifest.json

@@ -2,10 +2,11 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.3-beta.1",
-  "skillVersion": "2.5.3-beta.1",
+  "packageVersion": "2.5.3-beta.2",
+  "skillVersion": "2.5.3-beta.2",
   "files": [
     "SKILL.md",
+    "guides/approval-flow-development-workflow.md",
     "guides/backend-function.md",
     "guides/best-practices.md",
     "guides/bff-creation-workflow.md",
@@ -22,6 +23,7 @@
     "guides/sql-mybatis.md",
     "guides/troubleshooting.md",
     "guides/typescript-sdk.md",
+    "knowledge/approval-flow/config-json-schema.md",
     "knowledge/components.md",
     "knowledge/custom-page/generation-standards.md",
     "knowledge/custom-page/page-templates.md",
@@ -46,6 +48,7 @@
     "references/rabetbase-bff-delete.md",
     "references/rabetbase-bff-detail.md",
     "references/rabetbase-bff-list.md",
+    "references/rabetbase-bff-logs.md",
     "references/rabetbase-bff-pull.md",
     "references/rabetbase-bff-push.md",
     "references/rabetbase-bff-save.md",
@@ -85,6 +88,9 @@
     "references/rabetbase-deployment-sync-all.md",
     "references/rabetbase-doctor.md",
     "references/rabetbase-file.md",
+    "references/rabetbase-flow-commands.md",
+    "references/rabetbase-flow-resources.md",
+    "references/rabetbase-flow-runtime-boundary.md",
     "references/rabetbase-init.md",
     "references/rabetbase-instant-api-policy.md",
     "references/rabetbase-issue-report.md",
@@ -140,5 +146,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "737d15dee0512e879514bb4ab5e657b2e817656ba483dd285f5fbfe59adabc05"
+  "digest": "bdb1237d11f707a54a1a189d00c313b8cf7f4ac4f41e9ec7d2aec7e187edbaa9"
 }