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

package/skills/rabetbase/guides/best-practices.md

@@ -0,0 +1,137 @@
+# Lovrabet 开发质量规范与最佳实践
+
+> 目标：约束 AI 在编写代码、SQL 和 BFF 时的安全边界、命名风格和防御性编程习惯，避免生成高风险或难以维护的产物。
+>
+> 适用场景：编写或审查代码生成逻辑、SQL 和 BFF 脚本时。
+
+## 需求落地标准工作流
+
+当遇到一个新业务需求时，AI **必须**按以下漏斗模型进行思考与技术选型，严禁一上来就直接写页面或堆砌复杂的自定义 SQL/BFF：
+
+### Step 1：模型与关系推演
+- **强制动作**：使用 CLI 命令（`rabetbase dataset list --format json`、`rabetbase dataset list --name "xxx" --format json`、`rabetbase dataset detail --code <数据集编码> --format json`）找出所有相关的业务模型。
+- **list 与 detail**：`dataset list` 只返回精简列表（便于扫目录）；**字段、操作、关联、库表摘要**等一律以 `dataset detail` 为准——该命令默认即为完整结构化 JSON，**无需** `--verbose`。
+- **分析深度**：必须分析数据集里的字段含义、系统字段、字段格式、数据规范以及多表之间的关联关系（主外键）。
+- **目的**：绝不凭空捏造结构，确保后续的所有代码设计都基于平台真实的 Schema。
+
+### Step 2：接口选型（唯一权威见 SKILL.md）
+
+技术与实现方式优先级 **以 [SKILL.md](../SKILL.md) 的「接口选型优先级」「Agent 快速执行顺序」为准**；勿在此重复整段漏斗。
+
+本文件仅补充执行习惯：
+
+- **SQL**：写前先 `sql list` 查复用；统计类 SQL 主动对齐历史口径，**不一致时告知开发者**。长期维护的源文件落在 **`.rabetbase/sql/<appCode>/<dbName|db-<id>>/`**（与 `sql create` / `sql pull` / `sql push` / `sql status` 约定一致）。
+- **BFF**：写前先 `bff list` 防重复；若逻辑可复用，**建议**抽公共函数或 service 层。脚本**仅**在 **`.rabetbase/bff/<appCode>/...`** 下维护（见 `bff create`）。
+
+### Step 3：前端页面呈现
+- 只有在后端的模型和接口选型彻底理清、确认可用之后，**最后一步**才是编写前端 React 页面。
+- 确保将规划好的接口数据合理、高效地绑定到页面组件上。
+
+## 命名规范
+
+AI 必须使用有业务语义的规范命名，严禁使用诸如 `test`、`temp`、`query1` 等无意义名称。
+
+### 动态值生成 JavaScript / TypeScript 标识符
+
+- 外部动态值不得未经处理直接用于 JavaScript / TypeScript 标识符。
+- 生成名称必须合法、确定且不存在歧义；无法安全生成时应明确失败。
+- 已发布的公开名称应保持兼容，变更时按破坏性变更处理。
+- 生成文件不应手工修补，应修正规则或输入后重新生成。
+
+### SQL 查询命名
+**推荐格式**: `[模块]-[功能]-[类型]`（小写，连字符分隔）
+
+```markdown
+✅ 好的命名：
+- customer-active-list      # 客户-活跃列表
+- order-payment-summary     # 订单-支付汇总
+- product-inventory-query   # 产品-库存查询
+
+❌ 禁止的命名：
+- query1, query2            # 无意义的序号
+- test, temp                # 临时性名称
+- abc, xyz                  # 无含义缩写
+- 数据查询                   # 不要使用中文作为 code/name 标识
+```
+
+### BFF 脚本命名
+**推荐格式**: `[动词]-[模块]-[功能]`（小写或驼峰视环境而定，通常连字符风格为佳）
+
+```markdown
+✅ 好的命名：
+- get-customer-list
+- update-order-status
+- validate-user-permission
+
+❌ 禁止的命名：
+- api1, handler2
+- do-something
+- test-api
+```
+
+## 安全与高危操作边界
+
+当用户要求执行高危操作时，AI **必须主动拦截并要求二次确认**，并在生成代码时增加安全防护。
+
+### SQL 高危操作识别
+
+🔴 **高危特征**：
+* 包含 `DELETE`、`TRUNCATE`、`DROP`
+* 修改核心业务表（如订单、支付、库存）
+* **无 `LIMIT` 或无 `WHERE` 限制的 `UPDATE`**
+
+✅ **防御动作**：
+* 如果用户给出了不带 `LIMIT` 或全局匹配的 `UPDATE`，AI 必须主动补充约束条件或提示风险。
+* 高危 DDL/DML 不应通过 CLI 自动保存到平台，必须建议用户保存在本地 `.rabetbase/sql/` 同步目录或 `.draft.sql` 草稿中进行 review。
+
+### BFF 高危操作识别
+
+🔴 **高危特征**：
+* 参数未加任何验证直接传入 `delete` 或 `update` 方法
+* 未做权限校验直接暴露数据
+
+✅ **防御动作**：
+AI 编写 BFF 代码时，必须养成防御性编程习惯，默认加上参数校验和错误捕获：
+
+```javascript
+// ❌ 高危：无验证，直接透传
+export default async function(params: any) {
+  return await client.models.customer.delete({ id: params.id });
+}
+
+// ✅ 安全：带验证和异常处理
+export default async function(params: any, context: any) {
+  if (!params.id) {
+    return { success: false, error: '无效的 ID' };
+  }
+  
+  // 必须捕获异常，不要让内部堆栈直接抛给前端
+  try {
+    return await context.client.models.customer.delete({ id: params.id });
+  } catch (err) {
+    return { success: false, error: '删除失败' };
+  }
+}
+```
+
+## 描述与版本标记
+
+在通过 CLI 命令保存资源（如 SQL、BFF）时，应善用 `description` 字段。AI 应在描述中主动加入语义化的标签和版本说明。
+
+**可用标记**：
+* `#生产使用` - 生产环境关键资源
+* `#测试中` - 仍在联调阶段
+* `#待废弃` - 计划移除的旧资源
+
+**示例**：
+```markdown
+查询活跃客户列表 #生产使用 
+
+用途：客户管理主页面展示
+变更记录：
+- 2024-03-20: 增加状态筛选
+```
+
+## 冲突处理底线
+
+硬性规则见 [SKILL.md](../SKILL.md)「冲突处理」；分支表、响应结构与沟通要求见 [`conflict-detection.md`](conflict-detection.md)。**禁止**捏造 `forceUpdate`、代用户强制覆盖；`blocked` 时引导平台操作或另存为新名称。

package/skills/rabetbase/guides/bff-creation-workflow.md

@@ -0,0 +1,148 @@
+# BFF 工作流规则
+
+前置知识：`backend-function.md`、`data-api-guidelines.md`
+
+## 核心原则
+
+平台是唯一 source of truth。修改已有脚本时，从平台拉取最新内容。
+
+## 工作流
+
+```
+速查公共函数 → 确认需求 → 校验字段 → [按需]查平台 → 编写本地脚本 → 自检 → status → dry-run → push/pull → [按需]运行态 smoke
+```
+
+### 0. 速查公共函数
+执行 `rabetbase bff list --type COMMON --format json` 查看已有公共函数。如有可复用的工具函数，先用 `rabetbase bff detail --id <id> --format json` 确认入参、返回值和副作用，避免按名称猜测。
+
+### 1. 确认需求
+写码前必须明确：类型（ENDPOINT/HOOK/COMMON）、函数名、入参、返回结构，以及是否涉及数据集或消息通知。缺失则先问用户。通知型 BFF 还必须确认当前应用已有的 `configCode`、接收对象、标题/摘要和是否允许执行真实发送；不能用示例编码代替真实配置。
+
+### 2. 校验依赖事实
+BFF 涉及数据集时，执行 `rabetbase dataset detail --code <数据集编码> --format json`（或 `compress`）确认字段名、类型、必填字段、枚举值、关联关系。禁止凭经验猜字段名，禁止把 Demo 或历史案例里的字段、表名、枚举值复制到当前脚本。
+
+不读写数据集的纯消息通知 ENDPOINT 可以不依赖数据集；业务明确要求在数据集操作执行前发送预通知或告警时使用 Before HOOK；作为数据集操作成功后副作用的通知，只有响应结果已包含通知所需字段时才使用 After HOOK。三者都必须按 [`backend-function.md`](backend-function.md) 的“消息通知扩展”核对 `configCode`、`audiences` 和 `message`。先执行以下只读命令获取当前应用的 EMAIL 配置：
+
+```bash
+rabetbase notification config-list --type EMAIL --format compress
+```
+
+从 `data.configs[]` 按 `configName` / `description` 选择配置，并使用同一项的 `configCode`。命令不会输出 `channelConfig`、`endpointUrl` 或通知凭据。没有结果或存在多个候选且业务目标不明确时，停下向用户确认；不得猜测。不要把 dataset 级通知通道的 `channelCode` 当成 BFF 所需的应用级 `configCode`。
+
+BFF HOOK 可挂载 `DB_TABLE` 或 `METADATA` 数据集，具体 operation 以平台返回为准。`METADATA` 数据集不支持 SQL / aggregate 路径；脚本中应使用 `` context.client.models[`dataset_${datasetCode}`] `` 的标准操作能力。
+
+常用字段投影：
+
+```bash
+rabetbase dataset detail --code <数据集编码> --format compress \
+  --jq '.data.fields[] | {name, displayName, type, required, options}'
+```
+
+写入前必须确认：
+* 业务必填字段：`data.fields[].required === true`，平台自动维护字段除外
+* 枚举/选择字段：写入 `options[].value`，不要写展示用 `label`
+* 外键字段：从 `data.relations[]` 或 `dataset relations` 确认真实关系
+
+### 3. 查平台（按需）
+* 新建 → 跳过
+* 修改已有 → 执行 `rabetbase bff list --format json`（ENDPOINT 或 COMMON） + `rabetbase bff detail --id <id> --format json` 取 `id` 和最新内容
+* 不确定 → 查一下
+
+命中同名脚本时，停下问用户：修改还是另起新名。
+
+### 4. 编写脚本（规范路径）
+新建脚本应使用 **`rabetbase bff create`**，在 **`.rabetbase/bff/<appCode>/...`** 下生成脚手架后再编辑（路径与 `bff status` / `bff push` 一致）。**不要**在 `src/` 或仓库任意目录手写 BFF 再期望被 CLI 识别。
+已有脚本仅在上述 BFF 树内修改；与 `backend-function.md` 中的目录约定一致。
+
+通知需要在数据集 `create` / `update` / `delete` 执行前明确预告，并且通知失败应阻止本次操作时，选择 Before HOOK；通知由数据集操作成功触发，且响应结果已包含通知所需字段时，选择 After HOOK；响应结果不包含通知所需字段时，选择能在写入前读取并暂存必要字段、在成功后发送通知的受控 `ENDPOINT`。三者都使用 `await context.client.extension.execute("notification", "send", ...)`，并由 runtime 注入可信 `appCode` 和当前用户；不要把 `appCode`、渠道地址或密钥作为外部参数透传。
+
+### 5. 自检
+* 方法名正确
+* 单条查询用 `getOne`
+* BFF 模型键使用 `"dataset_" + 32 位数据集 code`
+* METADATA 数据集的 BFF / HOOK 不走 SQL 或 aggregate；只使用平台返回的标准数据操作
+* `filter()` 结果从 `.tableData` 读取，不是 `.list`
+* `create()` 返回新记录 ID，不是完整对象；不要访问 `created.id`
+* `batchCreate()` 返回新记录 ID 数组；入参直接使用非空对象数组，不使用 `{"items":[...]}` 包装
+* 批量更新使用 `update({ id: [...] })`；不存在 `batchUpdate()`，也不传记录数组
+* 枚举/选择字段写入 `options[].value`，不是展示 `label`
+* BFF 中 `sql.execute` 返回数组，不是 `{ execSuccess, execResult }`
+* 没有在 BFF 中使用前端 SDK 初始化能力，如 `createClient`、`registerModels`
+* 参数校验、错误处理、脱敏
+* 通知型 BFF 只传 `configCode` / `audiences` / `message`，并且没有 `${...}` 模板表达式、旧 MANUAL 参数或渠道密钥
+* 通知型 ENDPOINT 限制调用者可传的字段、`configCode` 和接收对象范围，不形成任意通知转发器
+* 通知型 Before HOOK 使用“即将执行”或“准备执行”的消息语义，`await` 发送后返回原始 `params`；不直接返回通知扩展结果，并明确接受“通知已发送但后续业务仍可能失败”
+* 通知型 After HOOK 只使用业务接口响应结果或固定可信规则派生接收对象与消息；若通知失败或超时，按业务操作可能已完成、通知状态未知处理，不得自动重试原业务请求
+
+### 6. 检查本地状态
+执行 `rabetbase bff status --format json`：
+* 确认新增脚本进入 `added`
+* 确认修改脚本进入 `modified`
+* 若状态异常，先不要推送
+
+### 7. 预览推送
+执行 `rabetbase bff push --type <type> --name <name> --dry-run --format json`：
+* 查看本次是 `create` 还是 `update`
+* 检查目标 `lockKey`、`filePath` 和预期状态
+* dry-run 不会上传远端，也不会改 lock
+
+### 8. 推送到平台
+执行 `rabetbase bff push --yes --type <type> --name <name> --format json`：
+* 成功项进入 `uploaded`
+* 未变更项进入 `skipped: unchanged`
+* 失败项进入 `failed`
+
+### 9. 运行态 smoke（按需）
+`rabetbase bff push` 只证明脚本配置已同步到平台管理侧。若本轮需求要求确认最终运行效果，应显式进入运行验证，例如在已安装并配置运行 CLI 的环境中执行：
+
+```bash
+lovrabet bff exec --appcode <appCode> --name <functionName> --params '<json>' --format compress
+```
+
+边界：
+* 通知型 BFF 的 smoke 会真实发送外部消息；必须通过已确认上下文或显式 `--appcode` 锁定同一 app，执行前向用户展示 app、函数名、`configCode`、接收对象和消息摘要并取得明确确认
+* `lovrabet bff detail` 只确认运行契约和版本，不返回脚本源码；通知参数必须来自本地已审查脚本或明确业务契约，不能按函数名猜
+* 通知执行超时或客户端未拿到结果时，先按“状态未知”处理；不得自动重试，避免重复发送
+* `lovrabet` CLI 不可用、未配置或无权限时，明确记录“运行态 smoke 未执行”，不要把它写成 `rabetbase` 验证已通过
+* 管理态已同步但运行态仍返回旧版本时，优先按传播延迟 / 缓存延迟处理：等待后重试；必要时再对目标脚本执行一次精确 `bff push --force --type <type> --name <name>`
+* 多次重试仍旧版本时，记录平台运行态缓存风险并上报；不要通过修改 Skill、配置文件或另建脚本来掩盖
+
+### 10. 本地文件
+脚本内容直接保存在本地文件中，纳入 Git 管理。路径遵循 `.rabetbase/bff/<appCode>/` 目录约定（详见 `backend-function.md`）：
+* ENDPOINT → `.rabetbase/bff/<appCode>/ENDPOINT/<name>.js`
+* HOOK → `.rabetbase/bff/<appCode>/HOOK/<alias>/<operationType>/<functionNode>/<name>.js`
+* COMMON → `.rabetbase/bff/<appCode>/COMMON/<name>.js`
+
+## 冲突处理
+
+若返回 `failed`：
+* 告知用户失败的 `lockKey` 和错误原因
+* 不要假装成功
+* 已成功推送的其他脚本不会自动回滚
+
+## 本地文件
+
+正常流程：先在本地创建/修改，再通过 `push` 同步远端，路径同 Step 10（`.rabetbase/bff/<appCode>/` 下）。
+例外场景：
+* 用户主动要求"同步平台最新到本地" → 从平台拉取 → 覆盖本地（`bff pull`）
+* 用户要求删除脚本 → `bff delete --yes --target ...`
+
+修改已有脚本时，从平台拉取最新内容。
+
+## 修改已有脚本
+
+`rabetbase bff list --format json` → `rabetbase bff detail --id <id> --format json` 拉最新内容 → 如需覆盖本地则 `bff pull` → 修改本地文件 → `bff status` → `bff push --yes`
+
+## BFF 语义差异
+
+| 场景 | 前端 SDK | BFF (context.client) |
+|------|---------|---------------------|
+| SQL 返回值 | `{ execSuccess, execResult }` | 直接返回数组 |
+| 模型键 | 可通过初始化/生成代码使用 alias | 使用 `"dataset_" + 32 位数据集 code` |
+| `filter()` 返回 | `tableData` 为列表数据 | `tableData` 为列表数据，不是 `list` |
+| `create()` 返回 | 以 SDK 文档/类型为准 | 新记录 ID，不是完整对象 |
+| `batchCreate()` 返回 | 以 SDK 文档/类型为准 | 新记录 ID 数组；直接传非空对象数组 |
+| 批量更新 | 以 SDK 文档/类型为准 | `update({ id: [...] })`；不存在 `batchUpdate()` |
+| SDK 初始化能力 | `createClient` / `registerModels` | 不可用；`context.client` 由平台注入 |
+| 前端调 BFF | `client.bff.execute({ scriptName, params })` 返回业务数据 | — |
+| 发送应用级通知 | — | `context.client.extension.execute("notification", "send", { configCode, audiences, message })` |

package/skills/rabetbase/guides/conflict-detection.md

@@ -0,0 +1,119 @@
+# 冲突检测与未完成写入处理
+
+**文档版本**: v4.0
+**适用于**: SQL / BFF 资源的远端写入与同步
+
+> **与 SKILL.md 的关系**：[SKILL.md](../SKILL.md) 只保留硬性规则；本文件负责解释什么叫“远端未写入成功”，以及 AI 应该如何沟通。
+
+---
+
+## 当前主工作流
+
+当前推荐路径：
+
+- **SQL**
+  - 新建：`rabetbase sql create`
+  - 修改：编辑 `.rabetbase/sql/...` 下的同步文件后执行 `rabetbase sql push`
+  - 删除：`rabetbase sql delete`
+- **BFF**
+  - 新建本地脚手架：`rabetbase bff create`
+  - 推送远端：`rabetbase bff push`
+  - 删除远端：`rabetbase bff delete`
+
+## 什么时候算“没有写入成功”
+
+只要 CLI 返回结果表明**远端没有完成创建 / 更新 / 删除 / 同步**，就必须按失败处理。常见信号包括：
+
+- `blocked: true`
+- `action: "blocked"`
+- `success: false`
+- `ok: false`
+- 返回 message 明确表示冲突、被平台拦截、校验失败、未同步
+- 非零退出且错误原因发生在远端写入前后
+
+**核心原则**：
+
+- 本地文件已生成，不等于远端已保存
+- `--dry-run` 预览成功，不等于远端已执行
+- 命令执行失败时，不能用“已处理”“已保存”这类表述蒙混过去
+
+---
+
+## AI 的沟通义务
+
+只要远端未写入成功，回复里必须同时做到：
+
+1. **明确状态**
+   - 直接说“未保存到平台”“未完成远端同步”“只完成了本地生成/预览”。
+2. **说明原因**
+   - 引用返回里的 `message`、`error.message`、`blocked`、或关键上下文。
+3. **给出下一步**
+   - 去平台处理
+   - 修改本地内容后重试
+   - 先 `--dry-run`
+   - 回到 `create + 本地编辑 + push` 主路径
+
+---
+
+## 典型分支
+
+| 场景 | 是否算远端成功 | AI 应怎么说 |
+|------|----------------|-------------|
+| `sql create --dry-run` 成功 | 否 | 说明只是预览，尚未创建远端 SQL |
+| `bff create` 成功 | 否 | 说明本地脚手架已生成，尚未推送远端 |
+| `sql push --yes` 成功 | 是 | 告知已同步远端，可附带 sqlCode / 路径 |
+| `bff push --yes` 成功 | 是 | 告知已推送远端，可附带 lockKey / 名称 |
+| `blocked: true` / `action: blocked` | 否 | 明确说平台未保存，提示手动处理或联系相关人 |
+| 校验失败 / validation error | 否 | 说明未写入远端，先修内容或参数 |
+## blocked 场景
+
+当返回 `blocked: true` 或语义等价的“平台冲突 / 非本人资源 / 平台限制”时：
+
+- 必须明确说：**这次没有写入到 Lovrabet 平台**
+- 可以建议：去平台手动处理、联系上次提交人、或先保留本地草稿
+- 禁止：重试绕过、换参数偷偷再试、把失败包装成成功
+
+建议话术：
+
+```text
+这次没有同步到 Lovrabet 平台。平台返回了冲突/阻断提示：<message>。
+如果需要继续修改，请先到平台处理冲突，或联系上次提交人；本地内容可以先保留。
+```
+
+---
+
+## 响应示例
+
+### 仅预览成功
+
+```json
+{
+  "ok": true,
+  "dryRun": true,
+  "data": {
+    "method": "POST"
+  }
+}
+```
+
+解释：**预览成功，不等于远端已执行**。
+
+### 冲突/阻断
+
+```json
+{
+  "ok": false,
+  "blocked": true,
+  "message": "Resource was blocked by platform"
+}
+```
+
+解释：**远端未写入成功，必须明确告知用户**。
+
+---
+
+## 相关文档
+
+- **SQL 工作流**: `sql-creation-workflow.md`
+- **BFF 工作流**: `bff-creation-workflow.md`
+- **最佳实践**: `best-practices.md`