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

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

@@ -0,0 +1,173 @@
+# SQL 工作流规则
+
+前置知识：`data-api-guidelines.md`
+
+## 核心原则
+
+平台是唯一 source of truth。团队长期维护 SQL 时，优先使用 **本地同步工作流**：`sql create / pull / status / push / delete` + `.rabetbase/sql.lock.json`。
+
+## 工作流
+
+```
+确认需求 → [按需]查现有 SQL → 校验字段 → 拉/落本地（pull/new）→ 编辑本地文件 → [建议]validate → status → push/delete → detail/exec 验证
+```
+
+### 1. 确认需求
+写 SQL 前必须明确：查询目标、字段、筛选条件、排序分页、是否 JOIN、新建还是修改。缺失则先问用户。
+
+### 2. 查现有 SQL（按需）
+* 新建 → 可跳过
+* 修改已有 → 执行 `rabetbase sql list --format json` 找到目标，确认 `sqlCode`
+* 不确定 → 查一下
+
+命中同名或同语义 SQL 时，停下问用户：沿用还是另建。
+
+### 3. 校验字段
+执行 `rabetbase dataset detail --code <数据集编码> --format json` 确认表名、字段名、字段类型。禁止凭经验猜。
+
+### 4. 先把 SQL 拉/落到同步目录
+
+#### 修改已有 SQL
+
+先执行：
+
+```bash
+rabetbase sql pull --sqlcode <sqlCode> --format json
+```
+
+把平台最新内容同步到本地。
+
+#### 新建 SQL
+
+先执行：
+
+```bash
+rabetbase sql create --name <sqlName> --db-id <dbId> --mode sql --format json
+```
+
+或 MyBatis XML：
+
+```bash
+rabetbase sql create --name <sqlName> --db-id <dbId> --mode mybatisXml --format json
+```
+
+`sql create` 会先在远端创建 SQL，再生成本地文件并写入 `.rabetbase/sql.lock.json`。
+
+### 5. 编辑本地 SQL（规范路径）
+
+长期维护的文件路径统一为：
+
+```text
+.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml
+```
+
+不要默认把长期源文件放在 `queries/`、`src/` 等目录；长期维护统一使用同步目录。
+
+CLI 会自动维护 `@lovrabet` 头注释，例如：
+
+```sql
+-- @lovrabet.sqlCode: 2305f915-dd48cd4c
+-- @lovrabet.sqlName: getUserList
+-- @lovrabet.dbId: 10001
+-- @lovrabet.dbName: sample_db
+-- @lovrabet.mode: sql
+-- @lovrabet.syncedAt: 2026-04-11T06:47:24.325Z
+
+select * from users
+```
+
+可以保留并编辑这段头注释；`sql push` 上传时会自动剥离，不会把本地元信息写回平台正文。
+
+### 6. 验证（建议）
+执行 `rabetbase sql validate --file <sql文件路径> --format json` 传入 SQL 文件。未通过则修正后重新验证。
+
+### 7. 查看同步状态
+
+执行：
+
+```bash
+rabetbase sql status --format json
+```
+
+必要时补充：
+
+```bash
+rabetbase sql status --remote --format json
+```
+
+状态含义：
+
+* `added`：本地文件存在，但 lock 未跟踪
+* `modified`：本地文件 hash、路径或文件名（`sqlName`）变化
+* `missing`：lock 有记录，但本地文件缺失
+* `unchanged`：本地与 lock 一致
+* `remoteOnly`：只有 `--remote` 时检查远端孤儿项
+
+### 8. 推送到平台
+
+先预览：
+
+```bash
+rabetbase sql push --sqlcode <sqlCode> --dry-run --format json
+```
+
+确认无误后正式执行：
+
+```bash
+rabetbase sql push --sqlcode <sqlCode> --yes --format json
+```
+
+补充规则：
+
+* 仅文件名变化时，`sql push` 会把新的文件名视作新的 `sqlName` 并回写远端
+* 文件移动到新的数据库目录时，`sql push` 会尝试按目录名重新绑定 `dbId`
+* 若提示 `missing remote version`，先执行 `sql pull` 刷新 lock 中的 `version`
+
+### 9. 测试
+
+推送成功后执行：
+
+```bash
+rabetbase sql detail --sqlcode <sqlCode> --format json
+rabetbase sql exec --sqlcode <sqlCode> --format json
+```
+
+失败则修正 → validate → status → push → detail/exec。
+
+### 10. 删除工作流
+
+先预览：
+
+```bash
+rabetbase sql delete --sqlcode <sqlCode> --dry-run --format json
+```
+
+确认无误后：
+
+```bash
+rabetbase sql delete --sqlcode <sqlCode> --yes --format json
+```
+
+成功后会删除远端记录，并把本地文件移动到 `.rabetbase/sql-trash/`。
+
+## 非 SELECT 语句
+
+DELETE / DDL（DROP / ALTER / CREATE / TRUNCATE）属高风险，不建议进入同步主路径。
+将 SQL 写入本地草稿文件，告知用户手动在平台操作。
+草稿路径可放在同步目录旁的 `.draft.sql`，例如：
+
+```text
+.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.draft.sql
+```
+
+## 冲突处理
+
+* `sql pull` 提示 `local differs from remote` → 说明本地与远端已漂移；先和用户确认是否 `--force`
+* `sql push` 失败 → 明确告诉用户是哪一条 `sqlCode` 失败、为什么失败，不要粉饰为已同步
+
+## SQL 调用差异
+
+| 场景 | 前端 SDK | BFF (context.client) |
+|------|---------|---------------------|
+| 返回值 | `{ execSuccess, execResult }` | 直接返回数组 |
+| 调用 | `client.sql.execute({ sqlCode, params })` | `context.client.sql.execute({ sqlCode, params })` |

package/skills/rabetbase/guides/sql-mybatis.md

@@ -0,0 +1,126 @@
+# SQL CLI 命令与 MyBatis 语法指南
+
+> 目标：指导 AI 如何正确使用 CLI 命令来完成 SQL 的查询、本地同步、验证、推送与测试，并提供平台支持的 MyBatis 动态 SQL 语法参考。
+>
+> 前置阅读：`sql-creation-workflow.md`（整体流程）、`data-api-guidelines.md`（字段约束）
+
+## 何时使用
+
+当任务满足任一条件时，必须阅读并遵守本指南：
+
+* 需要使用 CLI 命令处理自定义 SQL
+* 编写需要动态条件的复杂 SQL（如可选参数、范围过滤）
+* SQL 验证报错，需要排查语法或字段问题
+
+## CLI 命令调用规范
+
+在执行 `sql-creation-workflow.md` 规定的流程时，AI 必须严格按以下方式使用 CLI 命令。
+
+### 1. `rabetbase sql list --format json`
+* **用途**：创建或修改前，搜索同名或相似语义的 SQL。
+* **动作**：若发现相似项，必须与开发者确认是否复用或另起新名，避免冗余创建。
+
+### 2. `rabetbase dataset detail --code xxx --format json`
+* **用途**：写 SQL 前获取表结构，**绝对禁止凭空编造表名或字段名**。
+* **提取项**：
+  * 真实表名：`basic.tableName`
+  * 真实字段列表：`fields` 下的 `code`、`type`、`required`
+  * 数据库 ID：`basic.database.dbId`（`sql create` 时需要）
+
+### 3. `rabetbase sql pull --sqlcode xxx` / `rabetbase sql create --name ... --db-id ... --mode ...`
+* **用途**：把 SQL 先落到本地同步目录，再编辑。
+* **动作**：
+  * 修改已有 SQL → 先 `sql pull --sqlcode <sqlCode>`
+  * 新建 SQL → 先 `sql create --name <sqlName> --db-id <dbId> --mode sql|mybatisXml`
+* **目录**：长期维护的文件统一放在 `.rabetbase/sql/<appCode>/<dbName|db-<id>>/<sqlCode>_<sqlName>.sql|xml`
+
+### 4. `rabetbase sql validate --file xxx --format json`
+* **用途**：推送前的建议卡点。
+* **动作**：如果 `valid: false`，必须根据 `errors` 提示修改 SQL 内容，然后重新执行此命令，直到通过。
+
+### 5. `rabetbase sql status --format json`
+* **用途**：确认当前本地文件是否被识别为 `modified` / `added` / `missing` / `unchanged`。
+* **动作**：若状态与预期不符，先解释原因再继续，不要跳过状态检查直接推送。
+
+### 6. `rabetbase sql push --sqlcode xxx --dry-run|--yes --format json`
+* **用途**：将同步目录中的本地文件上传到平台。
+* **动作**：
+  * 先 `--dry-run` 看预览
+  * 再 `--yes` 正式执行
+* **补充**：
+  * 文件名变化会驱动远端 `sqlName` 更新
+  * 文件移动到新的数据库目录时，会尝试按目录重绑 `dbId`
+  * 如果提示 `missing remote version`，先执行 `sql pull`
+
+### 7. `rabetbase sql exec --sqlcode xxx --format json`
+* **用途**：推送成功后的功能测试。
+* **动作**：测试失败（如语法错、数据不符合预期）时，必须在本地文件中修改 SQL -> 重新 validate -> 重新 status -> 重新 push -> 重新 execute，形成闭环。
+
+
+---
+
+## 📚 MyBatis 动态 SQL 语法参考（核心）
+
+平台支持 MyBatis 语法。在自定义 SQL 中处理动态参数时，必须遵守以下规范。
+
+### 简单参数 vs 动态参数
+
+| 类型 | 语法 | `jdbcType` | 适用场景 |
+|---|---|---|---|
+| **简单参数** | `#{param}` | ❌ 不加 | 必定传入的固定条件 |
+| **动态参数** | `#{param, jdbcType=TYPE}` | ✅ 必须加 | `<if>` 标签内的可选条件 |
+
+### 动态 SQL 示例（推荐）
+
+```sql
+SELECT id, name, status_code 
+FROM company
+<where>
+    <if test="statusCode != null and statusCode != ''">
+        AND status_code = #{statusCode, jdbcType=VARCHAR}
+    </if>
+    <if test="name != null and name != ''">
+        AND name LIKE CONCAT('%', #{name, jdbcType=VARCHAR}, '%')
+    </if>
+    <if test="startDate != null">
+        AND created_at &gt;= #{startDate, jdbcType=DATE}
+    </if>
+</where>
+ORDER BY id DESC
+```
+
+### 常用标签说明
+
+* `<where>`：自动处理内部的 `AND` / `OR` 前缀，当内部没有条件成立时，整个 `WHERE` 关键字也不会出现。
+* `<if test="条件">`：用于判空。注意：字符串应同时判断 `!= null` 和 `!= ''`，数字/布尔只需判断 `!= null`。
+* `<foreach>`：常用于 `IN` 语句的数组遍历。
+
+### `jdbcType` 对照表
+
+在 `<if>` 标签内使用参数时，必须带上对应的 `jdbcType`：
+
+| 数据类型 | `jdbcType` |
+|---|---|
+| 字符串 | `VARCHAR` |
+| 整数 | `INTEGER` |
+| 小数 | `DECIMAL` |
+| 日期 | `DATE` |
+| 时间戳 | `TIMESTAMP` |
+
+### XML 转义规则
+
+由于 SQL 内容会被解析为 XML，符号需要正确转义：
+
+* **SQL 文本中**：必须转义！
+  * 大于号 `>` 写作 `&gt;`
+  * 小于号 `<` 写作 `&lt;`
+  * 示例：`AND created_at &gt;= #{startDate, jdbcType=DATE}`
+* **`<if test="...">` 属性内**：不需要转义！
+  * 示例：`<if test="amount > 100">`
+
+## 禁止事项
+
+* ❌ 禁止在未执行 `rabetbase sql validate` 通过前，直接执行 `rabetbase sql push`
+* ❌ 禁止在 `<if>` 标签的参数绑定中漏写 `jdbcType`
+* ❌ 禁止在简单固定参数（不在标签内）里加 `jdbcType`
+* ❌ 禁止把 `<` 或 `>` 直接写在 SQL 正文中（必须用 `&lt;` / `&gt;`）

package/skills/rabetbase/guides/troubleshooting.md

@@ -0,0 +1,67 @@
+# AI 故障诊断手册 (Troubleshooting)
+
+> 目标：当执行代码报错，或用户向 AI 抛出"报错日志 / 没数据 / 查不到"时，约束 AI 的第一排查反应，避免顺着错误方向盲目改代码。
+> 
+> 前置阅读：`data-api-guidelines.md`
+
+## 何时使用
+
+当遇到以下情况时，AI 必须进入本指南定义的诊断模式：
+* 用户说"查询没有结果"、"空数组"
+* 控制台报错"参数格式不正确"、"字段不存在"、"表不存在"
+* 用户说"BFF 返回结构不对"、"SQL 报错"
+* CLI 命令执行失败，提示"Dataset not found"
+
+---
+
+## 诊断肌肉记忆（强制）
+
+### 1. 听到"查不到数据"、"空数组"
+**AI 的第一反应**：检查是否漏写了操作符。
+
+* ❌ 错误排查方向：怀疑数据库没连上、怀疑数据集配错
+* ✅ **强制动作**：检查 `where` 对象里是否直接写了值（如 `status: "active"`）。必须补上操作符（如 `status: { $eq: "active" }`）。
+
+### 2. 听到"参数格式不正确"
+**AI 的第一反应**：检查分页、排序、字段选择的参数名是否写成了老旧格式。
+
+* ❌ 错误排查方向：怀疑后端 API 坏了
+* ✅ **强制动作**：
+  * 检查是否误用了 `fields`，必须改为 `select`
+  * 检查是否误用了 `sort`，必须改为 `orderBy`
+  * 检查是否误用了 `page` / `limit`，必须改为 `currentPage` / `pageSize`
+
+### 3. 听到"SQL 报错：表不存在/字段不存在"
+**AI 的第一反应**：立刻执行 `rabetbase dataset detail --code xxx --format json` 核对 Schema。
+
+* ❌ 错误排查方向：按自己的猜测随便换一个字段名重试
+* ✅ **强制动作**：
+  1. 执行 `rabetbase dataset detail --code xxx --format json` 获取真实数据集信息
+  2. 提取 `basic.tableName` 作为表名
+  3. 逐一核查报错字段是否存在于 `fields` 列表中，注意大小写
+  4. 确认无误后再重新生成 SQL 并通过 `rabetbase sql validate --file xxx --format json` 验证
+
+### 4. 听到"BFF 查不到数据 / 字段是 undefined"
+**AI 的第一反应**：检查 BFF 中的 API 调用方式和 SQL 结果提取。
+
+* ❌ 错误排查方向：给 BFF 增加前端 SDK 包装结构
+* ✅ **强制动作**：
+  * 检查单条查询是否误用了 `findOne`，必须改为 `getOne`
+  * 检查 SQL 执行是否用了 `result.execResult`，在 BFF 中，`context.client.sql.execute` **直接返回数组**，没有 `execResult` 这一层
+
+### 5. 听到"CLI 报错 / Dataset not found"
+**AI 的第一反应**：检查基础连通性，指导用户确认环境。
+
+* ❌ 错误排查方向：建议用户重装各种库
+* ✅ **强制动作**：
+  * 建议用户检查 `.lovrabetrc`（或其他配置）中的 `appcode` 是否正确
+  * 建议用户在终端执行 `rabetbase auth` 检查是否未登录或 Cookie 过期
+  * 帮用户执行 `rabetbase dataset list --format json` 确认该环境到底有哪些可用数据集
+
+---
+
+## 核心原则
+
+* **不要猜**：只要涉及"不存在"、"不匹配"，第一步永远是通过 CLI 命令（如 `rabetbase dataset detail`）拉取最新真实数据。
+* **不要盲试**：在没有分析出具体根因前，不要试图通过微调参数名盲目重试。
+* **分清端环境**：报错若是发生在前/后端交互边界，第一时间弄清是前端 SDK 的事，还是 BFF 脚本里的事，两者的返回值和对象结构不同。

package/skills/rabetbase/guides/typescript-sdk.md

@@ -0,0 +1,227 @@
+# SDK 编码规则与 API 约束
+
+> 目标：约束 AI 在前端与 Node 环境中生成 Lovrabet SDK 代码时的用法，杜绝凭借通用经验瞎猜 API 结构。
+>
+> 适用范围：前端 / Node 环境中通过 `@lovrabet/sdk` 初始化后的 `client` 调用。
+> BFF 脚本中的 `context.client` 由平台注入，API 子集与前端 SDK 有差异；编写 BFF 时以 `backend-function.md` 为准。
+
+## 何时使用
+
+当任务涉及以下动作时，必须阅读并遵守本指南：
+* 初始化 Lovrabet Client
+* 编写模型/数据集的查询与写入代码
+* 在前端或中台服务中执行自定义 SQL
+* 在前端调用 Backend Function (BFF)
+* 处理 API 返回的错误或业务异常
+
+不要把本指南里的 `createClient`、`registerModels` 等前端 / Node SDK 初始化能力套用到 BFF。BFF 内只使用平台注入的 `context.client`。
+
+## 初始化规则
+
+必须使用 `createClient` 命名导出，禁止使用 `new LovrabetClient()`：
+
+```typescript
+import { createClient } from "@lovrabet/sdk";
+
+const client = createClient({
+  appCode: "your-app-code",
+  accessKey: process.env.RABETBASE_ACCESS_KEY, // 仅在服务端使用
+  models: [
+    { tableName: "users", datasetCode: "39f758e7b38c476b8bb3996771a601a1", alias: "users" }
+  ],
+});
+```
+
+## 1. 模型查询 (Filter API)
+
+这是操作模型（表）的**最高优** API。
+
+### 强制参数名称
+绝不允许用错以下参数名：
+* ❌ `fields` -> ✅ `select`
+* ❌ `sort` -> ✅ `orderBy`
+* ❌ `page` / `limit` -> ✅ `currentPage` / `pageSize`
+
+### 强制操作符
+`where` 条件中**禁止直接写值**，必须使用操作符：
+* ❌ `where: { status: 'active' }`
+* ✅ `where: { status: { $eq: 'active' } }`
+
+支持的操作符：`$eq`, `$ne`, `$gte`, `$lte`, `$gt`, `$lt`, `$contain`, `$startWith`, `$endWith`, `$in`。
+
+逻辑组合：
+```typescript
+where: {
+  $and: [
+    { age: { $gte: 18 } },
+    { $or: [{ status: { $eq: "pending" } }, { status: { $eq: "processing" } }] }
+  ]
+}
+```
+
+### 多表关联（自动 JOIN）
+* 仅支持 1:1 或 N:1
+* 关联字段引用必须使用**表名**（如 `profile.username`），不能用 datasetCode。
+* 只有提前通过 CLI 命令分析出有外键关联的，才能这么写。
+
+```typescript
+// 示例：查询文章及其关联的作者信息
+const result = await client.models.article.filter({
+  select: ["id", "title", "profile.username"],
+  where: { "profile.is_signed": { $eq: true } }
+});
+```
+
+### 写入与删除操作（SDK >= 1.2.0）
+
+从 SDK v1.2.0 开始，update 和 delete 支持对象模式（推荐，与 BFF 一致）和兼容模式两种写法，单次最多 **1000 条**记录。
+
+#### 更新（Update）
+
+**接口**：
+```typescript
+client.models.dataset_[code].update({
+  id: number | string | (number | string)[]; [key: string]: any
+})
+```
+
+**示例**：
+```typescript
+// 单条更新
+await client.models.customer.update({ id: 1001, status: 'active' });
+
+// 批量更新
+await client.models.customer.update({
+  id: [1, 2, 3, 4, 5],
+  status: 'active',
+  updateTime: new Date().toISOString()
+});
+```
+
+**注意事项**：
+- 单次最多更新 **1000 条**
+- 原子操作：要么全部成功，要么全部失败
+- 不能批量修改主键字段
+- 不能将必填字段设置为空值
+
+#### 删除（Delete）
+
+**接口**：
+```typescript
+client.models.dataset_[code].delete({ id: number | string | (number | string)[] })
+```
+
+**示例**：
+```typescript
+// 单条删除
+await client.models.customer.delete({ id: 1001 });
+
+// 批量删除
+const inactiveUsers = await client.models.customer.filter({
+  where: { lastLoginTime: { $lt: '2026-01-01' } },
+  select: ['id']
+});
+
+await client.models.customer.delete({
+  id: inactiveUsers.map(u => u.id)
+});
+```
+
+**注意事项**：
+- 单次最多删除 **1000 条**
+- 删除操作不可逆，建议先备份
+- 如果有外键约束，需要先删除关联数据
+
+#### 分批处理超过 1000 条的数据
+
+当数据量超过 1000 时，需要手动分批：
+
+```typescript
+async function updateInBatches(ids: number[], batchSize = 1000) {
+  for (let i = 0; i < ids.length; i += batchSize) {
+    const batch = ids.slice(i, i + batchSize);
+    await client.models.customer.update({ id: batch, status: 'processed' });
+    console.log(`已处理 ${i + batch.length} / ${ids.length}`);
+  }
+}
+```
+
+### 别名模式（Alias Pattern）
+
+如果在前端 / Node SDK 中使用 `registerModels` 定义了别名，批量操作同样支持。此能力不适用于 BFF 的 `context.client`。
+
+```typescript
+// 注册别名
+client.registerModels({
+  primary: 'dataset_abc123',
+  detail: 'dataset_def456'
+});
+
+// 使用别名批量操作
+await client.models.primary.update({ id: [1, 2, 3], status: 'active' });
+```
+
+## 2. 自定义 SQL (SQL API)
+
+### 强制返回值处理
+SDK 中的 SQL API 返回的是**业务数据层**，包含 `execSuccess` 和 `execResult`：
+* **必须**判断 `execSuccess`，不能直接读结果。
+* 这与 BFF 环境中直接返回数组（不带 execResult）有本质区别，**不要混用**。
+
+```typescript
+// ✅ 前端/Node SDK 调用 SQL：
+const data = await client.sql.execute<MyRowType>({
+  sqlCode: "fc8e7777-06e3847d",
+  params: { userId: "123" },
+});
+
+if (data.execSuccess && data.execResult) {
+  console.log(data.execResult); // T[]
+} else {
+  console.error("业务级SQL执行失败");
+}
+```
+
+## 3. 前端 / Node 调用 Backend Function (BFF API)
+
+### 强制返回值处理
+调用 BFF 返回的直接是你在脚本中 `return` 的业务数据对象。
+* 这里**没有** `execSuccess` 或 `execResult`。
+
+```typescript
+// ✅ 调用 BFF
+const dashboard = await client.bff.execute<DashboardData>({
+  scriptName: "getUserDashboard",
+  params: { userId: "123" },
+});
+
+// 直接使用业务数据
+console.log(dashboard.userCount);
+```
+
+## 异常处理底线
+
+所有通过 `client` 发起的网络调用都可能抛出 HTTP 级别的错误，AI 必须养成使用 `try...catch` 包裹代码的习惯，并识别 `LovrabetError`。
+
+```typescript
+import { LovrabetError } from "@lovrabet/sdk";
+
+try {
+  const result = await client.models.users.getOne({ id });
+} catch (error) {
+  if (error instanceof LovrabetError) {
+    console.error("HTTP/框架级错误:", error.message, error.code);
+  } else {
+    console.error("其他运行时错误:", error);
+  }
+}
+```
+
+## AI 自检清单
+每次生成 SDK 相关代码时，AI 应隐式自问：
+* [ ] 是否把 `select` 写成了 `fields`？
+* [ ] 是否把 `orderBy` 写成了 `sort`？
+* [ ] `where` 对象里是否老老实实带了 `$eq` 等操作符？
+* [ ] 处理 SQL 的返回值时，判断了 `execSuccess` 吗？
+* [ ] 处理 BFF 的返回值时，是不是直接使用了业务数据？
+* [ ] 加入了 `try...catch` 块防止整个应用崩溃吗？