@lovrabet/cli 1.2.4 → 1.2.5-beta.2

package/templates/skills/.shared/guides/07-backend-function/guide.md

@@ -0,0 +1,679 @@
+# Backend Function 脚本编写规范
+
+> **目标**：学会编写符合 lovrabet-runtime 平台规范的动态脚本，用于数据权限过滤、动态脱敏、数据增强和复杂业务逻辑。
+
+## 核心概念
+
+Backend Function 是运行在 lovrabet-runtime 平台上的动态脚本，分为两类：
+
+| 类型 | 说明 | 触发方式 |
+|------|------|----------|
+| **HOOK 脚本** | 依附于标准数据接口 | Before（前置）/ After（后置） |
+| **ENDPOINT 脚本** | 独立业务端点 | POST `/api/{appCode}/endpoint/{scriptName}` |
+
+---
+
+## 5 步强制工作流程
+
+**重要**：编写 Backend Function 脚本时，必须严格按照以下顺序执行，**禁止跳过任何步骤**。
+
+```
+需求分析 → 字段分析 → 编写脚本 → 字段验证 → 添加注释
+```
+
+### 步骤 1: 需求分析与数据集获取
+
+**目标**：理解用户需求，确定涉及的数据集。
+
+**操作**：
+1. 分解用户需求，识别关键信息：
+   - 需要操作哪个数据集？
+   - 是 Before 还是 After 脚本？
+   - 是哪个接口操作（filter、getList、create 等）？
+   - 业务逻辑是什么（权限过滤、数据脱敏、字段计算等）？
+
+2. 使用 MCP 工具获取数据集详情：
+   ```
+   使用 get_dataset_detail 获取数据集详情
+   datasetCode: <数据集代码>
+   ```
+
+**示例**：
+```
+用户需求："在用户列表查询前，非管理员只能看到自己创建的数据"
+
+分析结果：
+- 数据集：users（用户信息）
+- 脚本类型：Before
+- 接口操作：filter
+- 业务逻辑：权限过滤（根据 created_by 字段）
+```
+
+### 步骤 2: 字段详细分析与推理
+
+**目标**：深入分析数据集的字段结构，并根据业务需求推理出需要使用的字段。
+
+**操作**：
+1. 从 MCP 返回的数据集详情中，提取关键信息：
+   - `fields` - 所有字段列表
+   - 每个字段的 `name`（字段名）、`type`（类型）、`comment`（语义说明）
+   - 字段之间的关联关系（如外键）
+
+2. **根据业务需求推理所需字段**（关键步骤）：
+   - 分析业务场景，识别涉及的业务实体
+   - 推理需要读取或修改的字段
+   - 推理需要用于条件判断的字段
+   - 推理需要关联查询的字段
+
+3. 记录脚本中需要用到的字段：
+   - 字段名称（精确匹配，区分大小写）
+   - 字段类型（STRING、NUMBER、BOOLEAN 等）
+   - 字段语义（理解字段的业务含义）
+   - 使用场景（条件判断、数据修改、关联查询等）
+
+**推理示例**：
+
+**场景 1：权限过滤**
+```
+业务需求："非管理员只能查看自己创建的数据"
+
+推理过程：
+1. 需要判断用户角色 → 需要 context.userInfo.role
+2. 需要过滤创建人 → 需要 created_by 字段
+3. 需要当前用户 ID → 需要 context.userInfo.id
+
+需要的字段：
+- created_by (STRING) - 创建人 ID（用于过滤条件）
+```
+
+**场景 2：数据脱敏**
+```
+业务需求："手机号中间四位脱敏显示"
+
+推理过程：
+1. 需要处理手机号 → 需要 phone 字段
+2. 脱敏是在返回数据后处理 → After 脚本
+3. 需要遍历列表数据 → 操作 params.tableData
+
+需要的字段：
+- phone (STRING) - 手机号（用于脱敏处理）
+```
+
+**场景 3：自动填充**
+```
+业务需求："创建订单时自动填充用户信息和时间"
+
+推理过程：
+1. 需要填充用户 ID → 需要 user_id 字段
+2. 需要填充租户编码 → 需要 tenant_code 字段
+3. 需要填充创建时间 → 需要 create_time 字段
+4. 需要当前用户信息 → 需要 context.userInfo
+5. 需要当前租户信息 → 需要 context.tenantCode
+
+需要的字段：
+- user_id (STRING) - 用户 ID（自动填充）
+- tenant_code (STRING) - 租户编码（自动填充）
+- create_time (DATETIME) - 创建时间（自动填充）
+```
+
+**场景 4：关联查询增强**
+```
+业务需求："订单列表显示用户名称和等级"
+
+推理过程：
+1. 订单表有用户 ID → 需要 user_id 字段
+2. 需要查询用户表 → 需要用户数据集的 id 字段
+3. 需要获取用户名称 → 需要用户数据集的 username 字段
+4. 需要获取用户等级 → 需要用户数据集的 vip_level 字段
+5. 需要将用户信息追加到订单数据 → 需要在订单对象上添加新字段
+
+需要的字段：
+订单表：
+- user_id (STRING) - 用户 ID（用于关联查询）
+
+用户表：
+- id (STRING) - 用户 ID（关联条件）
+- username (STRING) - 用户名称（追加到订单数据）
+- vip_level (NUMBER) - VIP 等级（追加到订单数据）
+```
+
+### 步骤 3: 编写脚本
+
+**目标**：根据需求和字段分析，编写符合规范的脚本代码。
+
+**操作**：
+1. 确定脚本类型（HOOK 或 ENDPOINT）
+2. 确定接口类型（普通接口 或 filter/aggregate）
+3. 编写函数签名：`export default async function`
+4. 实现业务逻辑
+5. 确保返回 params 或业务对象
+
+**注意**：
+- 普通接口：直接设置 `params.fieldName = value`
+- filter 接口：操作 `params.ytWhere`，使用操作符语法
+- 所有数据库操作必须 `await`
+
+### 步骤 4: 字段二次验证
+
+**目标**：检查脚本中使用的所有字段，确保没有编造或用错字段。
+
+**操作**：
+1. 列出脚本中使用的所有字段名
+2. 逐一对照步骤 2 中记录的字段列表
+3. 检查：
+   - 字段名是否精确匹配（区分大小写）
+   - 字段类型是否正确使用
+   - 是否有拼写错误（如 `create_by` vs `created_by`）
+   - 是否使用了不存在的字段
+
+**常见错误**：
+- ❌ `params.createBy` - 错误：驼峰命名，应为 `created_by`
+- ❌ `params.userId` - 错误：字段不存在，应为 `user_id`
+- ❌ `params.userName` - 错误：字段不存在，应为 `user_name`
+
+### 步骤 5: 添加顶部注释
+
+**目标**：在脚本顶部添加清晰的注释，描述入参和出参格式。
+
+**格式**：
+```javascript
+/**
+ * [脚本功能描述]
+ *
+ * @param {Object} params - 入参说明
+ * @param {string} params.fieldName - 字段说明
+ * @param {Object} context - 执行上下文
+ * @returns {Object} 出参说明
+ */
+export default async function functionName(params, context) {
+  // 业务逻辑
+  return params;
+}
+```
+
+**示例**：
+```javascript
+/**
+ * 用户列表查询前置脚本 - 权限过滤
+ * 非管理员用户只能查询自己创建的数据
+ *
+ * @param {Object} params - filter 接口请求参数
+ * @param {Object} params.ytWhere - 查询条件对象
+ * @param {Object} context - 执行上下文
+ * @param {Object} context.userInfo - 当前用户信息
+ * @param {string} context.userInfo.id - 用户 ID
+ * @param {string} context.userInfo.role - 用户角色
+ * @returns {Object} 修改后的 params 对象
+ */
+export default async function beforeFilter(params, context) {
+  if (context.userInfo.role !== "admin") {
+    params.ytWhere = params.ytWhere || {};
+    const originalWhere = { ...params.ytWhere };
+    params.ytWhere = {
+      $and: [
+        originalWhere,
+        { created_by: { $eq: context.userInfo.id } }
+      ]
+    };
+  }
+  return params;
+}
+```
+
+---
+
+## 函数签名规范
+
+所有脚本必须导出一个**异步函数**，接收两个固定参数：
+
+```javascript
+export default async function functionName(params, context) {
+  // 业务逻辑
+  return params;
+}
+```
+
+**函数名格式**：`[stage][OperationName]`，例如：`beforeGetList`、`afterFilter`、`createOrder`
+
+---
+
+## 参数说明
+
+### params（业务数据）
+
+| 阶段 | params 内容 |
+|------|-------------|
+| **Before** | API 请求参数（requestBody），如查询条件、表单数据 |
+| **After** | API 返回结果（responseBody.data），通常包含 `tableData`、`tableColumns` |
+| **Endpoint** | HTTP 请求体中的 JSON 数据 |
+
+### context（执行上下文）
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `context.userInfo` | Object | 当前登录用户信息（id, username, role, tenantCode 等） |
+| `context.appCode` | String | 当前应用编码 |
+| `context.tenantCode` | String | 当前租户编码 |
+| `context.client` | Object | 数据库操作入口，提供 models 方法访问数据集 |
+
+---
+
+## 数据库操作 API
+
+通过 `context.client.models.dataset_{code}` 访问数据集（`{code}` 是 32 位数据集编码）：
+
+```javascript
+const ds = context.client.models.dataset_XXXXXXXXXX;
+```
+
+| 方法 | 说明 | 参数示例 | 返回值 |
+|------|------|----------|--------|
+| `findOne(params)` | 查询单条 | `{ id: 1 }` | Object |
+| `getList(params)` | 分页查询 | `{ page: 1, size: 20 }` | List |
+| `filter(params)` | 高级过滤 | `{ ytWhere: { age: { $eq: 18 } } }` | List |
+| `create(data)` | 创建数据 | `{ name: "John", age: 20 }` | ID |
+| `update(data)` | 更新数据 | `{ id: 1, name: "New" }` | Boolean |
+| `delete(params)` | 删除数据 | `{ id: 1 }` | Boolean |
+
+**注意**：所有数据库操作都是异步的，**必须使用 `await`**。
+
+---
+
+## 接口返回规范
+
+### filter 接口返回格式
+
+filter 接口返回的数据格式固定为：
+
+```javascript
+{
+  "tableData": [],           // 数据列表
+  "paging": {
+    "currentPage": 1,        // 当前页码
+    "totalCount": 0,         // 总记录数
+    "pageSize": 30           // 每页数量
+  },
+  "tableColumns": []         // 列定义
+}
+```
+
+### 关联查询时的数据提取
+
+**重要**：调用其他数据集的 filter 接口时，返回数据需要从 `tableData` 数组中获取。
+
+```javascript
+// ✅ 正确：从 tableData 中提取数据
+const filterResult = await context.client.models.dataset_XXXXXXXXXX.filter({
+  ytWhere: { user_id: { $in: userIds } }
+});
+const dataList = filterResult.tableData || [];
+
+// ❌ 错误：直接使用返回结果
+const dataList = await context.client.models.dataset_XXXXXXXXXX.filter({
+  ytWhere: { user_id: { $in: userIds } }
+});
+```
+
+---
+
+## 接口分类与调用规范
+
+**重要**：以下规范适用于所有 Backend Function 脚本（Before、After、ENDPOINT）中调用数据集接口时。
+
+### 接口分类
+
+lovrabet-runtime 平台的数据集接口分为两大类：
+
+| 分类 | 接口 | 特点 |
+|------|------|------|
+| **普通接口** | getList / create / update / delete / findOne | 参数直接设置字段值 |
+| **高级查询接口** | filter / aggregate | 支持复杂查询条件和操作符 |
+
+**关键区别**：
+- **普通接口**：参数中直接设置字段值，如 `{ status: "active" }`
+- **高级查询接口**：必须使用操作符语法，如 `{ ytWhere: { status: { $eq: "active" } } }`
+
+### Filter / Aggregate 接口参数
+
+| 参数 | filter | aggregate | 说明 |
+|------|:------:|:---------:|------|
+| `ytWhere` | Y | Y | 查询条件（使用操作符语法） |
+| `ytSelect` | Y | Y | 返回字段列表 |
+| `ytOrderBy` | Y | Y | 排序规则 `[{"columnName": "desc"}]` |
+| `ytHaving` | N | Y | having 条件 |
+| `ytGroupBy` | N | Y | 分组字段 |
+| `ytAggregate` | N | Y | 聚合函数 |
+| `currentPage` | Y | Y | 当前页码 |
+| `pageSize` | Y | Y | 每页数量 |
+
+### ytAggregate 聚合函数格式（仅 aggregate 接口）
+
+```javascript
+[
+  {
+    type: "SUM",           // 聚合类型：SUM / COUNT / AVG / MAX / MIN
+    field: "amount",       // 聚合字段
+    alias: "sumAmount",    // 结果别名
+    distinct: true,        // 可选：是否去重
+    round: true,           // 可选：是否四舍五入
+    precision: 2,          // 可选：小数精度
+  },
+]
+```
+
+**聚合类型说明**：
+- `SUM` - 求和
+- `COUNT` - 计数
+- `AVG` - 平均值
+- `MAX` - 最大值
+- `MIN` - 最小值
+
+**可选参数**：
+- `distinct` - 是否对字段值去重后再聚合
+- `round` - 是否对结果四舍五入
+- `precision` - 保留小数位数
+
+### ytWhere 查询操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ field: { $eq: value } }` |
+| `$ne` | 不等于 | `{ field: { $ne: value } }` |
+| `$gte` / `$gteq` | 大于等于 | `{ field: { $gte: value } }` |
+| `$lte` / `$lteq` | 小于等于 | `{ field: { $lte: value } }` |
+| `$in` | 在集合内 | `{ field: { $in: [v1, v2] } }` |
+| `$contain` | 包含（模糊匹配） | `{ field: { $contain: "keyword" } }` |
+| `$startWith` | 以...开头 | `{ field: { $startWith: "prefix" } }` |
+| `$endWith` | 以...结尾 | `{ field: { $endWith: "suffix" } }` |
+| `$and` | 且（所有条件满足） | `{ $and: [条件1, 条件2] }` |
+| `$or` | 或（任一条件满足） | `{ $or: [条件1, 条件2] }` |
+
+---
+
+## Before 脚本编写规则
+
+**关键**：**必须识别用户需求中的「操作类型」**，根据操作类型选择正确的写法！
+
+Before 脚本用于在接口执行前修改请求参数。根据接口类型不同，修改方式也不同：
+
+### 普通接口 Before
+
+直接设置字段值：
+
+```javascript
+export default async function beforeGetList(params, context) {
+  if (context.userInfo.role !== "admin") {
+    params.created_by = context.userInfo.id;
+  }
+  return params;
+}
+```
+
+**限制**：普通接口不支持操作符（如 `$gte`、`$contain`）。如需高级查询，请使用 filter 接口。
+
+### Filter / Aggregate 接口 Before
+
+对于 filter 和 aggregate 接口，Before 脚本必须操作 `params.ytWhere` 来修改查询条件。
+
+**关键规则**：
+- 必须使用操作符语法（参见"接口分类与调用规范"章节）
+- 必须保留原有的 `ytWhere` 条件，使用 `$and` 组合
+- 不能直接覆盖 `params.ytWhere`
+
+#### 示例
+
+```javascript
+export default async function beforeFilter(params, context) {
+  if (context.userInfo.role !== "admin") {
+    params.ytWhere = params.ytWhere || {};
+    const originalWhere = { ...params.ytWhere };
+    params.ytWhere = {
+      $and: [
+        originalWhere,
+        { created_by: { $eq: context.userInfo.id } }
+      ]
+    };
+  }
+  return params;
+}
+```
+
+#### 编写要点
+
+1. **必须操作 `params.ytWhere`**：不能直接 `params.fieldName = value`
+2. **必须使用操作符语法**：条件值用 `{ $eq: value }` 包裹
+3. **必须保留原有条件**：使用 `$and` 组合，不能直接覆盖
+4. **必须初始化 ytWhere**：`params.ytWhere = params.ytWhere || {}`
+
+---
+
+## After 脚本编写规则
+
+After 阶段的 params 通常包含：
+
+- `params.tableData`：数据列表（数组）
+- `params.tableColumns`：列定义（数组）
+
+### 示例：数据脱敏
+
+```javascript
+export default async function afterFilter(params, context) {
+  params.tableData?.forEach((record) => {
+    if (record.phone) {
+      record.phone = record.phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
+    }
+  });
+  return params;
+}
+```
+
+### 示例：敏感字段权限控制
+
+```javascript
+export default async function afterFilter(params, context) {
+  if (context.userInfo.role !== "admin") {
+    params.tableColumns = params.tableColumns?.filter(
+      (col) => !["salary", "bank_account"].includes(col.dataIndex)
+    );
+    params.tableData?.forEach((record) => {
+      delete record.salary;
+      delete record.bank_account;
+    });
+  }
+  return params;
+}
+```
+
+### 示例：动态追加计算字段
+
+```javascript
+export default async function afterFilter(params, context) {
+  params.tableData?.forEach((record) => {
+    record.total_amount = record.price * record.quantity;
+    record.is_vip = record.order_count > 10;
+  });
+
+  const extraColumns = [
+    { dataIndex: "total_amount", title: "总金额", type: "NUMBER" },
+    { dataIndex: "is_vip", title: "VIP客户", type: "BOOLEAN" }
+  ];
+  extraColumns.forEach((col) => params.tableColumns?.push(col));
+
+  return params;
+}
+```
+
+---
+
+## ENDPOINT 脚本编写规则
+
+独立端点脚本用于复杂的事务性业务逻辑。
+
+- **API 路径**：`POST /api/{appCode}/endpoint/{scriptName}`
+- **请求体**：JSON 对象，作为 `params` 传入
+- **返回值**：业务结果对象（不是 params）
+
+### 示例：库存校验与下单
+
+```javascript
+export default async function createOrder(params, context) {
+  // 1. 校验库存
+  const product = await context.client.models.dataset_XXXXXXXXXX.findOne({
+    id: params.productId
+  });
+
+  if (!product || product.stock < params.quantity) {
+    throw new Error(`库存不足，当前库存: ${product ? product.stock : 0}`);
+  }
+
+  // 2. 计算价格
+  const user = await context.client.models.dataset_XXXXXXXXXX.findOne({
+    id: context.userInfo.id
+  });
+  const discount = user.vip_level >= 3 ? 0.8 : 1.0;
+  const finalPrice = product.price * params.quantity * discount;
+
+  // 3. 创建订单
+  const orderId = await context.client.models.dataset_XXXXXXXXXX.create({
+    user_id: context.userInfo.id,
+    product_id: params.productId,
+    quantity: params.quantity,
+    amount: finalPrice,
+    status: "pending",
+    create_time: new Date()
+  });
+
+  // 4. 扣减库存
+  await context.client.models.dataset_XXXXXXXXXX.update({
+    id: product.id,
+    stock: product.stock - params.quantity
+  });
+
+  return {
+    success: true,
+    orderId: orderId,
+    payAmount: finalPrice,
+    discountRate: discount
+  };
+}
+```
+
+---
+
+## 文件命名与存储规范
+
+### 存储位置
+
+所有 Backend Function 脚本存放在 `src/BackendFunction/` 目录下（仅存储，不参与实际调用）。
+
+### 命名规范
+
+| 脚本类型 | 命名格式 | 示例 |
+|----------|----------|------|
+| **HOOK 脚本** | `{alias}_{operation}_{before/after}.js` | `users_filter_before.js`、`orders_create_after.js` |
+| **ENDPOINT 脚本** | `endpoint_{description}.js` | `endpoint_create_order.js` |
+
+**alias 获取方式**：从项目的 `api.ts` 文件中 `registerModels` 函数获取数据集别名。
+
+---
+
+## 代码生成输出格式
+
+生成 Backend Function 代码时，必须按以下 JSON 格式输出：
+
+```json
+{
+  "description": "功能描述（10-30字）",
+  "code": "export default async function..."
+}
+```
+
+### 代码质量要求
+
+1. **必须导出默认异步函数**：`export default async function`
+2. **必须返回结果**：函数末尾一定要 `return params`（HOOK）或业务对象（ENDPOINT）
+3. **数据库操作必须 await**：所有 `context.client.models` 调用必须使用 await
+4. **错误处理**：使用 `throw new Error("友好的错误信息")` 抛出业务异常
+5. **代码简洁**：只生成必要的逻辑，不要添加多余的注释（除了顶部的 JSDoc 注释）
+6. **性能优化**：
+   - 查询其他表数据，尽可能使用 filter 接口，**禁止使用 getList**
+   - 尽最大可能避免循环调用 findOne，而是使用 filter 的 `$in` 一次查询多条再合并
+
+### 无法实现的需求处理
+
+如果用户提出的需求在当前接口类型下无法实现，**不要乱写代码**，而是在 `description` 中告知用户原因和建议。
+
+**示例**：
+```json
+{
+  "description": "getList接口不支持大于运算，请使用filter接口",
+  "code": "// getList 接口不支持运算操作符（如 $gte），无法实现\"金额大于1000\"的查询条件。\n// 建议：请将此数据集的查询接口更换为 filter 接口，filter 支持 $gte、$lte 等操作符。\nexport default async function beforeGetList(params, context) {\n  return params;\n}"
+}
+```
+
+### 现有代码处理
+
+如果用户提供了现有代码：
+1. **理解现有代码的逻辑**：分析代码的功能和实现方式
+2. **在现有代码基础上修改或增强**：根据用户需求进行调整
+3. **保持代码风格一致**：遵循原有的命名规范和代码结构
+
+---
+
+## 注意事项
+
+### 必须遵守
+
+1. **必须返回结果**：函数末尾一定要 `return params`（HOOK）或业务对象（ENDPOINT）
+2. **必须 await 数据库操作**：所有 `context.client.models` 调用必须使用 await
+3. **必须使用 filter 查询其他表**：禁止使用 getList，尽量避免循环调用 findOne，改用 filter 的 `$in` 批量查询
+
+### 禁止事项
+
+1. **禁止递归调用接口本身**：Before 和 After 脚本不能调用当前数据集的接口本身，防止死循环
+2. **禁止网络请求**：Backend Function 不支持任何网络请求（HTTP、WebSocket 等）
+3. **禁止遗漏 await**：否则无法获取数据库结果
+4. **禁止直接覆盖 ytWhere**：必须用 `$and` 组合原有条件
+
+### 限制
+
+- 单次脚本执行的数据库调用次数限制：**50 次**（超出会抛出异常）
+- 不支持网络请求：无法调用外部 API 或发起 HTTP 请求
+
+### 错误处理
+
+使用 `throw new Error("友好的错误信息")` 抛出业务异常，系统会捕获并返回给前端（状态码 500）。
+
+---
+
+## 快速对照表
+
+### 普通接口 vs Filter 接口
+
+| 场景 | 普通接口（getList 等） | Filter 接口 |
+|------|------------------------|-------------|
+| 权限过滤 | `params.created_by = userId` | `params.ytWhere = { $and: [..., { created_by: { $eq: userId } }] }` |
+| 支持操作符 | 不支持 | 支持 `$eq`、`$gte`、`$contain` 等 |
+| 复杂条件 | 不支持 | 支持 `$and`、`$or` 组合 |
+
+### Before vs After
+
+| 阶段 | params 内容 | 典型用途 |
+|------|-------------|----------|
+| **Before** | 请求参数 | 权限过滤、参数校验、自动填充 |
+| **After** | 响应数据 | 数据脱敏、字段计算、敏感列隐藏 |
+
+---
+
+## 自检清单
+
+编写 Backend Function 时，检查：
+
+- [ ] 函数签名正确：`export default async function`
+- [ ] 返回了 params 或业务对象
+- [ ] 数据库操作使用了 await
+- [ ] Filter 接口使用了 ytWhere 和操作符
+- [ ] 保留了原有 ytWhere 条件（使用 $and 组合）
+- [ ] 没有递归调用数据集本身
+- [ ] 查询其他表使用 filter 而非 getList
+- [ ] 错误信息对用户友好