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

package/skills/rabetbase/guides/backend-function.md

@@ -0,0 +1,835 @@
+# Backend Function 脚本编写规范
+
+> 目标：约束 AI 在 Lovrabet 项目中编写 Backend Function 时的行为，避免凭空编造字段、误用 SDK 返回值、写出不可维护或高风险的脚本。
+>
+> 前置阅读：`data-api-guidelines.md`
+
+## 阅读指南（按需跳转）
+
+| 需求 | 位置 |
+|------|------|
+| CLI 信封、`datasetId`、`dbtableConfig` ↔ `data.dbtable`、OpenAPI 对照 | [`references/rabetbase-dataset-detail.md`](../references/rabetbase-dataset-detail.md) |
+| 前后端数据访问、外键、性能 | [`data-api-guidelines.md`](data-api-guidelines.md) |
+| 在 BFF 中发送应用级消息通知 | 下文“消息通知扩展” |
+| HOOK/ENDPOINT 目录、注释模板、`context.client`、事务 | 下文 |
+
+## 何时使用
+
+当任务满足任一条件时，必须阅读并遵守本指南：
+
+* 编写 HOOK 脚本
+* 编写 ENDPOINT 脚本
+* 在 BFF 中调用数据集 API
+* 在 BFF 中调用自定义 SQL
+* 在 BFF 中调用应用级消息通知
+* 在 BFF 中处理事务、权限、脱敏、聚合或多表逻辑
+
+## 核心原则
+
+* 先校验数据集和字段，再写脚本
+* 所有脚本统一使用 `export default async function`
+* 前后端单条查询统一使用 `getOne({ id })`
+* BFF 中的 SQL 返回值与前端 SDK 不同，不能混用
+* 消息通知只引用当前应用中存在且未删除的 `configCode`，不接收 `appCode`、渠道地址或密钥
+* 平台自动维护字段不得手动设置
+* 发现明显性能问题时，必须先改写再继续
+* 新建与长期维护的 BFF 源文件**仅**在 **`.rabetbase/bff/<appCode>/...`**（`bff create` / `bff pull` 与 `bff status` 扫描范围）；不要写在 `src/` 等目录，详见 [`bff-creation-workflow.md`](bff-creation-workflow.md)
+* BFF 脚本只写**纯 JavaScript（ESM）**，支持到 **ES2023** 特性，不支持 TypeScript
+
+## 脚本类型
+
+| 类型 | 作用 | 路径 / 触发方式 | 查询方式 |
+|------|------|----------------|----------|
+| HOOK | 挂在标准数据接口前后执行 | Before / After | 通过数据集详情 |
+| ENDPOINT | 独立业务端点 | `POST /api/endpoint/{appCode}/{scriptName}` | `rabetbase bff list --format json`（默认） |
+| COMMON | 公共函数，供其他脚本 import 复用 | 被其他 BFF 引用 | `rabetbase bff list --format json`（type=COMMON） |
+
+写 BFF 前，先查一下公共函数列表（`rabetbase bff list --format json`），看是否有可复用的工具函数。
+
+## 平台配置地址
+
+| 类型 | 地址 |
+|------|------|
+| HOOK | `https://app.lovrabet.com/app/{appCode}/data/dataset/{datasetId}#api-list` |
+| ENDPOINT | `https://app.lovrabet.com/app/{appCode}/data/backend-function` |
+
+其中 `datasetId` 需要通过 `rabetbase dataset detail --code xxx --format json` 获取。
+
+**平台 URL / OpenAPI `get-driven-data` 与 CLI `data` 的字段对应**（含 `datasetId`、`dbtable`）：见 [`references/rabetbase-dataset-detail.md`](../references/rabetbase-dataset-detail.md)。
+
+## 本地目录约定
+
+BFF 脚本统一存放在 `.rabetbase/bff/<appCode>/` 目录下，由 CLI 同步体系管理：
+
+```text
+.rabetbase/bff/<appCode>/
+├── HOOK/
+│   └── <alias>/
+│       └── <operationType>/
+│           └── <functionNode>/
+│               └── <name>.js
+├── ENDPOINT/
+│   └── <scriptName>.js
+└── COMMON/
+    └── <scriptName>.js
+```
+
+规则：
+
+* HOOK 放在 `.rabetbase/bff/<appCode>/HOOK/<alias>/<operationType>/<functionNode>/`
+* ENDPOINT 放在 `.rabetbase/bff/<appCode>/ENDPOINT/`
+* COMMON 放在 `.rabetbase/bff/<appCode>/COMMON/`
+* 本地文件是可选的人类辅助物，平台是唯一 source of truth
+
+### HOOK 目录名优先级
+
+HOOK 的第一层子目录名（标识数据集）按以下优先级确定：
+
+1. **alias**（优先）：来自 `api.ts`（由 `rabetbase api pull` 生成）
+2. **datasetCode**（兜底）：当 `api.ts` 不可用时，直接使用 32 位数据集编码
+
+推荐始终先执行 `rabetbase api pull` 以获得可读性更好的 alias 命名。
+
+## 文件命名与函数命名
+
+| 类型 | 文件名 | 导出函数 |
+|------|--------|---------|
+| HOOK Before | `<name>.js`（位于 `HOOK/<alias>/<operationType>/before/`） | `<name>` |
+| HOOK After | `<name>.js`（位于 `HOOK/<alias>/<operationType>/after/`） | `<name>` |
+| ENDPOINT | `<scriptName>.js`（位于 `ENDPOINT/`） | `<scriptName>` |
+| COMMON | `<scriptName>.js`（位于 `COMMON/`） | `<scriptName>` |
+
+常见 `Operation`：
+
+* `filter`
+* `getOne`
+* `create`
+* `update`
+* `delete`
+* `aggregate`（仅在数据集 operation 实际返回时使用；METADATA 默认不会提供）
+
+使用 `aggregate` 时，聚合列名写在 `aggregate[].column`；`field` 只是历史兼容别名，新脚本不要使用。
+
+BFF HOOK 可以挂在 `DB_TABLE` 或 `METADATA` 数据集上；是否可挂某个 operation，以平台返回的 operation types 为准。
+
+### METADATA HOOK 脚本内部限制
+
+METADATA 数据集没有 DB_TABLE 数据源上下文，脚本中优先使用标准 SDK 操作，例如 `filter`、`getOne`、`create`、`batchCreate`、`update`、`delete`。
+
+不要在这类脚本中使用：
+
+* `context.client.customSql()` 或其他自定义 SQL 路径
+* aggregate 聚合接口
+* 直接拼接和执行 SQL
+
+如果需要复杂查询，优先组合 `filter` 的查询能力；无法满足时，考虑把数据源建模为 `DB_TABLE`，或在脚本中调用其他 `DB_TABLE` 数据集。
+
+## 强制工作流
+
+```text
+理解需求 -> 校验数据集与字段 -> 选择脚本类型 -> 生成本地脚本 -> 自检 -> status -> dry-run -> push/pull
+```
+
+### Step 1：理解需求
+
+开始写脚本前，AI 必须确认：
+
+* 这是 HOOK 还是 ENDPOINT
+* 作用于哪个数据集或接口
+* 输入参数是什么
+* 返回结构是什么
+* 是否涉及权限、脱敏、事务、外部依赖或消息通知副作用
+
+### Step 2：校验数据集、字段与关系
+
+BFF 涉及数据集读写时，必须执行 `rabetbase dataset detail --code xxx --format json`（或 `--format compress`），必要时先用 `rabetbase dataset list --format json` 定位数据集。纯消息通知 ENDPOINT 不需要为满足流程而虚构 `datasetCode`，但必须先确认当前应用、通知 `configCode`、接收对象和消息内容契约。
+
+必须确认：
+
+* 字段真实存在
+* 字段类型正确
+* 必填字段已识别：以 `data.fields[].required === true` 为准，排除平台自动维护字段
+* 枚举/选择字段已识别：写入时使用 `data.fields[].options[].value`，不要写展示用的 `label`
+* 外键或关联关系真实存在
+
+快速查看必填与枚举字段：
+
+```bash
+rabetbase dataset detail --code <datasetCode> --format compress \
+  --jq '.data.fields[] | select(.required == true or (.options | type == "array")) | {name, displayName, type, required, options}'
+```
+
+禁止行为：
+
+* 未读取数据集详情就直接写字段名
+* 凭经验猜 `user_id`、`status`、`deleted` 等通用字段
+* 把前端代码里的字段名照搬到当前 BFF
+* 把某个 Demo 或历史案例中的字段、枚举、表名当作当前任务的通用规则
+
+### Step 3：选择脚本类型
+
+使用规则：
+
+* Before：修改请求参数、补默认值、做前置校验
+* After：修改返回结果、做脱敏、补充展示字段
+* ENDPOINT：独立业务流程、事务、多表写入、复杂业务端点
+
+### Step 4：生成脚本
+
+在本地 `.rabetbase/bff/<appCode>/...` 下生成或修改完整脚本。
+
+脚本必须包含：
+
+* 顶部注释
+* `export default async function`
+* 明确的输入输出
+* 数据集映射
+* 必要的错误处理
+
+本地文件是主工作副本：
+
+* 新建时用 `rabetbase bff create`
+* 修改时直接编辑 `.rabetbase/bff/<appCode>/...`
+* 需要远端最新内容时先 `rabetbase bff pull`
+
+如果 BFF 行为与预期不符，或 `push` 显示 `unchanged` 但效果没变，先确认远端实际运行的是哪份代码：
+
+* `rabetbase bff detail --id <id> --format json`
+* 必要时再 `rabetbase bff pull --format json` 同步远端到本地
+
+先确认“远端现在是什么”，再决定是否继续改本地、查页面或查锁状态。
+
+### Step 5：自检
+
+至少检查：
+
+* 函数名匹配（用于 `scriptName` 参数）
+* 顶部注释占位符已替换
+* 单条查询是否统一使用 `getOne({ id })`
+* SQL 返回值是否按 BFF 语义处理
+* 是否误设置系统字段
+* 是否存在明显性能问题
+
+### Step 6：检查状态并预览
+
+至少执行：
+
+* `rabetbase bff status --format json`
+* `rabetbase bff push --type <type> --name <name> --dry-run --format json`
+
+确认：
+
+* 脚本进入 `added` / `modified`
+* 预览返回的 `lockKey`、`mode`、`status` 符合预期
+
+### Step 7：推送到平台
+
+确认无误后执行：
+
+* `rabetbase bff push --yes --type <type> --name <name> --format json`
+
+如果目标是同步远端到本地，则执行：
+
+* `rabetbase bff pull --format json`
+
+## 顶部注释规范
+
+顶部注释必须写清楚：
+
+* 脚本功能描述
+* 接口路径
+* 平台配置地址
+* HTTP 请求参数
+* 返回数据结构
+
+占位符必须替换为真实值，不能保留：
+
+* `{appCode}`
+* `{datasetCode}`
+* `{datasetId}`
+* `{operation}`
+* `{scriptName}`
+
+### HOOK 注释模板
+
+```javascript
+/**
+ * 脚本功能描述
+ *
+ * [接口路径] POST /api/{appCode}/{datasetCode}/{operation}
+ * [平台配置] https://app.lovrabet.com/app/{appCode}/data/dataset/{datasetId}#api-list
+ *
+ * [HTTP 请求体参数]
+ * { "field1": "字段说明" }
+ *
+ * [返回数据结构]
+ * HOOK: 返回修改后的 params
+ */
+```
+
+### ENDPOINT 注释模板
+
+```javascript
+/**
+ * 脚本功能描述
+ *
+ * [接口路径] POST /api/endpoint/{appCode}/{scriptName}
+ * [平台配置] https://app.lovrabet.com/app/{appCode}/data/backend-function
+ *
+ * [HTTP 请求体参数]
+ * { "field1": "字段说明" }
+ *
+ * [返回数据结构]
+ * ENDPOINT: 返回业务数据对象
+ */
+```
+
+## 参数与返回值
+
+| 类型 | `params` 含义 | 返回要求 |
+|------|---------------|---------|
+| Before | 请求参数 | 返回修改后的 `params` |
+| After | 响应结果，如 `tableData`、`tableColumns` | 返回修改后的 `params` |
+| ENDPOINT | HTTP 请求体 JSON | 返回业务数据对象 |
+
+`context` 常用字段：
+
+* `context.userInfo`
+* `context.appCode`
+* `context.tenantCode`
+* `context.client`
+
+## 数据集调用规范
+
+通过 `context.client.models` 调用数据集。模型键格式为固定前缀 `"dataset_"` 拼接 32 位数据集编码，编码来自 `rabetbase dataset list/detail` 返回的 `code` 字段。
+
+```javascript
+const TABLES = {
+  primary: "dataset_0123456789abcdef0123456789abcdef", // 数据集: <displayName> | 数据表: <tableName>
+  detail: "dataset_fedcba9876543210fedcba9876543210", // 数据集: <displayName> | 数据表: <tableName>
+};
+
+const models = context.client.models;
+const record = await models[TABLES.primary].getOne({ id: params.id });
+```
+
+规则：
+
+* 必须使用 `"dataset_" + 32 位数据集编码`，不要只写裸 `code`
+* 每个映射后写 `// 数据集: ... | 数据表: ...`
+* 查询单条统一使用 `getOne({ id })`
+* 列表查询优先使用 `filter()`
+* `context.client.models` 是 Proxy 对象，`Object.keys()` / `Object.entries()` 可能返回空数组；通过 `models[TABLES.xxx]` 访问即可
+
+常用方法与返回值：
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `getOne({ id })` | `object \| null` | 按主键查询单条 |
+| `filter(params)` | `{ tableData, paging, tableColumns? }` | 高级过滤查询，数据在 `tableData`，不是 `list` |
+| `aggregate(params)` | `{ tableData, paging, tableColumns? }` | DB_TABLE 单表聚合，数据在 `tableData` |
+| `create(data)` | `number` | 创建记录，返回新记录 ID，不返回完整对象 |
+| `batchCreate(rows)` | `Array<number | string>` | 批量创建同一数据集记录；ID 元素类型取决于数据集主键，顺序与输入一致 |
+| `update({ id, ...fields })` | 无业务对象 | 更新记录（id 支持数组批量，最多 1000 条） |
+| `delete({ id })` | 无业务对象 | 删除记录（id 支持数组批量，最多 1000 条） |
+
+### 批量新增与批量更新
+
+`batchCreate(rows)` 的 `rows` 必须是非空对象数组，直接传数组，不使用 `{"items":[...]}` 包装。批量数量不得超过运行时上限（默认 1000 条）。返回值是与输入顺序一致的新记录 ID 数组，元素类型取决于数据集主键：
+
+```javascript
+const createdIds = await models[TABLES.detail].batchCreate([
+  { primary_id: params.primaryId, item_code: "A" },
+  { primary_id: params.primaryId, item_code: "B" },
+]);
+
+await models[TABLES.primary].update({
+  id: [1, 2, 3],
+  status: "DONE",
+});
+```
+
+批量更新仍使用 `update({ id: [...], ...fields })`。不存在 `batchUpdate()`，也不要写成 `update([{ id: 1, ... }, { id: 2, ... }])`。示例中的字段名、ID 和枚举值都必须替换为 `dataset detail` 已确认的真实值。
+
+### aggregate 调用与选型
+
+`` context.client.models[`dataset_${datasetCode}`].aggregate(params) `` 是 BFF 的数据集 Instant API。实际脚本仍按上文的数据集映射，通过 `models[TABLES.xxx]` 访问；示例字段只用于展示参数契约，编写业务脚本前必须用 `dataset detail` 替换为真实字段：
+
+```javascript
+const aggregateResult = await models[TABLES.primary].aggregate({
+  where: { status: { $eq: "ACTIVE" } },
+  aggregate: [
+    { type: "SUM", column: "amount", alias: "totalAmount" },
+    { type: "COUNT", column: "id", alias: "recordCount", distinct: true },
+  ],
+  groupBy: ["company_id"],
+  having: { company_id: { $notNull: true } },
+  orderBy: [{ totalAmount: "desc" }],
+  currentPage: 1,
+  pageSize: 20,
+});
+
+const rows = aggregateResult.tableData;
+```
+
+聚合类型支持 `SUM`、`AVG`、`COUNT`、`MAX`、`MIN`。聚合项使用 `column` 指定真实数据集字段，可按需提供 `alias` 和 `distinct`；需要四舍五入时设置 `round: true`，`round: true` 时必须同时提供整数 `precision`。分组字段写入 `groupBy`。`having` 使用与 `where` 相同的对象结构，其中字段必须是真实数据集字段；示例使用真实分组字段 `company_id`，不要使用聚合输出别名。
+
+### 聚合别名使用边界
+
+`aggregate[].alias` 只定义聚合结果的输出字段名，不会成为新的数据集字段。当前服务端契约如下：
+
+| 位置 | 聚合别名 | 约束 |
+|------|----------|------|
+| `aggregate[].alias` | 支持 | 仅定义返回结果字段名 |
+| `select` | 不支持 | 使用真实数据集字段 |
+| `where` | 不支持 | 使用真实数据集字段 |
+| `having` | 不支持 | 使用真实数据集字段 |
+| `groupBy` | 不支持 | 使用真实数据集字段 |
+| `orderBy` | 支持 | 可以引用聚合输出别名 |
+
+需要按聚合结果过滤且 `aggregate()` 无法用真实字段表达时，使用已配置的 Custom SQL。不要在运行时静默切换到 Custom SQL，也不要动态拼接 SQL。
+
+选型规则：
+
+* 单个 `DB_TABLE` 数据集的简单聚合优先使用 `aggregate()`，不要先写 Custom SQL
+* 只有 JOIN、跨表统计、数据库特有函数或 `aggregate()` 无法表达的查询才使用已配置的 Custom SQL
+* `aggregate()` 返回值与 `filter()` 一样，从 `.tableData` 读取数据，不要按 SQL 数组返回值处理
+* `METADATA` 数据集不支持 `aggregate()` 或 Custom SQL；不要在失败后静默降级为动态 SQL
+
+正确处理 `create()` 返回值：
+
+```javascript
+const primaryId = await models[TABLES.primary].create({
+  required_field_a: params.requiredFieldA,
+});
+
+await models[TABLES.detail].create({
+  primary_id: primaryId,
+  required_field_b: params.requiredFieldB,
+});
+```
+
+不要写成：
+
+```javascript
+const primary = await models[TABLES.primary].create({ required_field_a: params.requiredFieldA });
+await models[TABLES.detail].create({ primary_id: primary.id }); // primary.id 是 undefined
+```
+
+不要再写：
+
+```javascript
+const record = await models[TABLES.primary].findOne({ id });
+```
+
+## 系统自动维护字段
+
+以下字段由平台自动维护，代码中不要手动设置：
+
+* `id`
+* `create_time`
+* `modify_time`
+* `create_by`
+* `modify_by`
+
+正确做法是只设置业务字段。
+
+## Before / After / Endpoint 规则
+
+### Before
+
+适合：
+
+* 参数校验
+* 默认值填充
+* 权限过滤
+
+规则：
+
+* 普通接口可直接修改 `params.field`
+* `filter` / `aggregate` 接口必须修改 `params.where`
+* 追加过滤条件时要保留原条件，通常用 `$and`
+
+```javascript
+export default async function beforeFilter(params, context) {
+  if (context.userInfo.role !== "admin") {
+    params.where = params.where || {};
+    const originalWhere = { ...params.where };
+    params.where = {
+      $and: [originalWhere, { created_by: { $eq: context.userInfo.id } }],
+    };
+  }
+  return params;
+}
+```
+
+### After
+
+适合：
+
+* 数据脱敏
+* 字段补充
+* 展示增强
+
+规则：
+
+* 主要操作 `params.tableData`
+* 不要破坏既有返回结构
+
+```javascript
+export default async function afterFilter(params) {
+  params.tableData?.forEach((record) => {
+    if (record.phone) {
+      record.phone = record.phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
+    }
+  });
+  return params;
+}
+```
+
+### ENDPOINT
+
+适合：
+
+* 独立业务流程
+* 多表读写
+* 事务处理
+* 需要前端通过 `client.bff.execute()` 调用的业务接口
+
+返回规则：
+
+* ENDPOINT 返回业务对象本身
+* 平台最终会包装成 `{ success, data }`
+* 前端 SDK 调用 `client.bff.execute()` 时，拿到的是业务数据，不是 `{ success, data }`
+
+## 公共函数（COMMON）
+
+### 命名建议
+
+公共函数建议统一加 `common` 前缀（如 `commonGetUserInfo`），便于与普通 ENDPOINT 区分，也方便人和 AI 识别。
+
+### 在其他 BFF 中调用公共函数
+
+通过 `context.client.bff.execute` 调用：
+
+```javascript
+const userInfo = await context.client.bff.execute({
+  scriptName: 'commonGetUserInfo',
+  params: { userId: params.userId }
+});
+```
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `scriptName` | string | 是 | 公共函数名称（与 COMMON 脚本的 scriptName 一致） |
+| `params` | object | 否 | 传递的参数，默认 `{}` |
+
+### 注意事项
+
+* `scriptName` 必须与公共函数名称精确匹配（大小写敏感）
+* 调用必须使用 `await`
+* `params` 会被深拷贝，调用方的原始对象不会被修改
+* 公共函数不可循环调用（A 调 B，B 又调 A）
+* 公共函数抛出的异常会向上传播到调用方，需在调用方做 try-catch
+* 修改公共函数的出入参会影响所有引用方；如需改动，建议新建 V2 版本逐步切换
+
+### 组合调用示例
+
+```javascript
+export default async function runBusinessFlow(params, context) {
+  const sequence = await context.client.bff.execute({
+    scriptName: 'commonGenerateSequence',
+    params: {}
+  });
+
+  const result = await context.client.bff.execute({
+    scriptName: 'commonCreateRecordsWithTransaction',
+    params: { ...params, sequence }
+  });
+
+  return result;
+}
+```
+
+## SQL 调用规则
+
+在 BFF 中使用：
+
+```javascript
+const rows = await context.client.sql.execute({
+  sqlCode: "example-read-list",
+  params,
+});
+```
+
+关键差异：
+
+* 前端 SDK：返回 `{ execSuccess, execResult }`
+* Backend Function：直接返回数组 `T[]`
+
+不要写成：
+
+```javascript
+const result = await context.client.sql.execute({ sqlCode: "xxx" });
+const rows = result.execResult;
+```
+
+## 消息通知扩展
+
+### 类型选择
+
+消息通知可以出现在以下三类脚本中：
+
+* **Before HOOK**：用于在数据集操作执行前发送明确的预通知或告警，例如高风险变更开始提醒。仅当业务接受“通知已发送但后续操作仍可能失败”，并且希望通知失败时阻止本次操作，才使用该方式。消息必须使用“即将执行”或“准备执行”语义，不得宣称操作已经成功。
+* **After HOOK**：用于数据集操作成功后的通知副作用。After HOOK 的 `params` 是业务接口响应结果，不是原始请求参数或操作前记录；仅当响应结果或固定可信规则已包含通知所需事实时才使用。`create` / `update` / `delete` 的响应若不含这些字段，不得把 `params` 当作“当前记录”，应改用能在写入前读取并暂存必要字段、在成功后发送通知的受控 ENDPOINT。
+* **ENDPOINT**：用于页面、CLI 或其他服务显式调用的独立通知流程。调用方只传经过校验的最小业务字段，不能控制渠道配置、任意收件人或完整消息。
+
+三者都使用 `context.client.extension.execute("notification", "send", params)`；`appCode` 和当前用户由 runtime 的可信脚本上下文注入，不能从 `params` 伪造。
+
+下面是 ENDPOINT 使用运行时通知扩展的完整示例：
+
+```javascript
+const CONFIG_CODE = "<confirmed-config-code>";
+const ALLOWED_AUDIENCES = [
+  { type: "ROLE", codes: ["<confirmed-role-code>"] },
+];
+
+export default async function sendOrderNotification(params, context) {
+  const orderNo =
+    typeof params?.orderNo === "string" ? params.orderNo.trim() : "";
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(orderNo)) {
+    throw new Error(
+      "orderNo must be 1-64 letters, numbers, underscores, or hyphens",
+    );
+  }
+
+  return await context.client.extension.execute("notification", "send", {
+    configCode: CONFIG_CODE,
+    audiences: ALLOWED_AUDIENCES,
+    message: {
+      title: "订单状态通知",
+      summary: "订单 " + orderNo + " 已进入待处理状态",
+      theme: "blue",
+    },
+  });
+}
+```
+
+这是 ENDPOINT 的安全调用起点：部署前必须把两个占位值替换为当前应用已确认的配置编码和角色编码；调用方只能提供经过校验的最小业务字段，不能控制 `configCode`、任意 `audiences` 或完整 `message`。Before HOOK 从已确认的请求和可信上下文派生消息，After HOOK 只能使用响应结果或固定可信规则。三者都不要改写成 `context.client.notification.send(...)`、旧 MANUAL 通知参数或脚本内 `fetch(...)`。
+
+### Before HOOK 调用方式
+
+Before HOOK 在业务接口执行前运行。通知调用必须使用 `await`；发送完成后返回原始 `params`，让后续接口继续使用原请求参数：
+
+```javascript
+const CONFIG_CODE = "<confirmed-config-code>";
+const ALLOWED_AUDIENCES = [
+  { type: "ROLE", codes: ["<confirmed-role-code>"] },
+];
+
+export default async function beforeNotifyOrderUpdate(params, context) {
+  const orderNo =
+    typeof params?.orderNo === "string" ? params.orderNo.trim() : "";
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(orderNo)) {
+    throw new Error(
+      "orderNo must be 1-64 letters, numbers, underscores, or hyphens",
+    );
+  }
+
+  await context.client.extension.execute("notification", "send", {
+    configCode: CONFIG_CODE,
+    audiences: ALLOWED_AUDIENCES,
+    message: {
+      title: "订单变更即将执行",
+      summary: "订单 " + orderNo + " 即将执行变更，请关注后续结果",
+      theme: "orange",
+    },
+  });
+
+  return params;
+}
+```
+
+Before HOOK 不得写成 `return await context.client.extension.execute(...)`。通知扩展返回的是 `{ sent, configCode, channelType, message }`；如果把它作为 Hook 返回值，runtime 会将其当作新的接口请求参数，覆盖原始 `params`。
+
+Before HOOK 的执行边界：
+
+* 通知失败会直接抛错，后续业务接口不会执行
+* 通知发送成功只表示预通知已发出；后续业务操作仍可能校验失败、执行失败或回滚
+* 消息标题和摘要必须表达“即将执行”或“准备执行”，不能表达“已完成”或“执行成功”
+* `configCode` 和允许的接收范围应固定在受控脚本中，不能由接口调用方覆盖
+
+After HOOK 通知失败或超时时，原业务操作可能已经完成，通知发送状态也可能未知；不得因此自动重试原业务请求。
+
+### 获取 configCode
+
+创建或修改通知型 BFF 前，先查询当前应用的应用级通知配置：
+
+```bash
+rabetbase notification config-list --type EMAIL --format compress
+```
+
+从 `data.configs[]` 中根据 `configName` 和 `description` 选择配置，把该项 `configCode` 固定到受控业务脚本中。查询命令只返回安全身份与描述字段，不返回 `channelConfig`、`endpointUrl` 或凭据。
+
+`configCode` 与 `channelCode` 不是同一概念：
+
+* `configCode`：应用级通知渠道配置编码，供 BFF `notification.send` 使用
+* `channelCode`：dataset 级通知通道编码，不是本扩展的入参
+
+查询为空时说明当前应用没有该类型的可用配置；查询出多个候选且无法从名称和描述判断业务目标时，向用户确认，不得自动取第一条。
+
+### 调用对象
+
+扩展调用对象只允许以下字段，多余字段会直接失败：
+
+| 字段 | 必填 | 约束 |
+|------|------|------|
+| `configCode` | 是 | 当前应用中已存在且未删除的应用级通知渠道配置编码；先用 `rabetbase notification config-list` 查询，不要猜测 |
+| `audiences` | 按渠道 | 对象数组；EMAIL 和飞书应用机器人必须至少解析出一个接收人，Webhook 机器人可以不传或传空数组 |
+| `message` | 是 | 消息对象，字段严格按下表传递 |
+
+`appCode` 和当前用户由可信脚本上下文注入。调用对象中禁止传 `appCode`、`datasetCode`、`sceneCode`、`endpointUrl`、`channelConfig`、token、secret 或其他旧通知字段。`configCode` 只能解析当前应用的配置，不能借此跨应用发送。
+
+### audiences
+
+每一项只能使用一种结构：
+
+```javascript
+[
+  { type: "USER", ids: ["user@example.com"] },
+  { type: "ROLE", codes: ["ADMIN"] },
+]
+```
+
+| `type` | 值字段 | 说明 |
+|--------|--------|------|
+| `USER` | `ids` | 非空字符串数组；具体标识必须与目标渠道的接收人类型一致，EMAIL 可使用邮箱或可解析的应用用户标识 |
+| `ROLE` | `codes` | 非空字符串数组；使用当前应用已确认的角色编码或角色标识，不要猜测 |
+
+`type` 只支持 `USER` / `ROLE`，且对象不能混入其他字段。EMAIL 和飞书应用机器人若最终没有解析出有效接收人，会在发送前失败；不要把“传了 audiences”当作“接收人已解析”。
+
+### message
+
+| 字段 | 必填 | 约束 |
+|------|------|------|
+| `title` | 是 | 非空字符串 |
+| `summary` | 是 | 非空字符串 |
+| `theme` | 否 | `blue` / `green` / `orange` / `red` / `grey` |
+| `detailMarkdown` | 否 | 字符串 |
+| `facts` | 否 | 最多 8 项，每项严格为 `{ label, value }`，两个字段都是非空字符串 |
+| `actions` | 否 | 最多 2 项，每项严格为 `{ text, url }`，两个字段都是非空字符串 |
+
+消息对象不允许额外字段，也不支持 `${...}` 模板表达式。运行时值应由 BFF 根据已校验的 `params` 直接组装，不要把模板语法交给通知扩展解析。
+
+### 返回值与副作用
+
+成功时返回：
+
+```json
+{
+  "sent": true,
+  "configCode": "<confirmed-config-code>",
+  "channelType": "EMAIL",
+  "message": "通知发送成功"
+}
+```
+
+`sent: true` 表示本次运行时通知分发成功，不表示接收人已经阅读，也不提供 exactly-once 保证。配置不存在、接收人解析为空、参数不合法或渠道调用失败会直接抛错，并保留通知错误码和消息。
+
+通知发送是外部可见副作用：
+
+* 创建/推送脚本的 dry-run 不会发送通知；只有执行 BFF 才会发送
+* 运行 smoke 前必须向用户展示当前应用、函数名、`configCode`、接收对象和消息摘要并取得确认
+* 面向多人调用的正式 ENDPOINT 必须在调用扩展前校验 `params` 的字段、类型和接收对象范围；固定业务通知优先在脚本内固定 `configCode` 和允许的接收范围，不要把任意渠道或任意收件人转发能力暴露给调用者
+* 超时或客户端未拿到结果时，发送状态可能未知；不得自动重试，避免重复通知
+* 不要在数据库事务中发送通知；先完成并提交业务写入，再执行通知调用
+* 若运行环境报告没有 `notification` 扩展，停止并确认目标 runtime 已包含该能力；不要回退到旧 MANUAL 参数或自行发 HTTP 请求
+
+## 事务规则
+
+事务使用方式：
+
+```javascript
+await context.client.db.transaction(async (tx) => {
+  const primaryId = await tx.models[TABLES.primary].create({
+    required_field_a: params.requiredFieldA,
+  });
+
+  await tx.models[TABLES.detail].create({
+    primary_id: primaryId,
+    required_field_b: params.requiredFieldB,
+  });
+
+  // tx.models 与 context.client.models 用法一致
+  // tx.sql.execute 可在同一事务中执行自定义 SQL
+  // 成功自动提交，抛错自动回滚
+});
+```
+
+必须遵守：
+
+* 外层必须 `await`
+* 回调函数必须是 `async`
+* 不要在事务中调用外部慢接口
+* 异常要向上抛出，不能吞掉
+
+## 性能约束
+
+编写 BFF 前，必须阅读 `data-api-guidelines.md` 中的性能优化部分。
+
+重点避免：
+
+* 循环查询单条
+* 循环写入
+* 嵌套循环查询
+
+性能要求：
+
+* 单次脚本数据库调用尽量控制在 `50` 次以内
+* 可批量查询时，用 `filter + $in`
+* 同一数据集批量新增优先使用 `batchCreate()`；相同字段值的批量更新优先使用 `update({ id: [...] })`
+* 只有 Instant API 无法表达的复杂写入才考虑已有且契约可信的 Custom SQL
+
+## 禁止事项
+
+* 不要使用 `findOne`
+* 不要使用 `getList()` 代替 `filter()`
+* 不要手动设置系统字段
+* 不要保留顶部注释占位符
+* 不要把前端 SQL 返回值语义套到 BFF
+* 不要在 BFF 中使用前端 SDK 独有的方法，如 `createClient`、`registerModels`
+* 不要把示例里的字段名、表名、枚举值复制到真实脚本；字段事实必须来自当前数据集详情
+* 不要忽略权限、脱敏和错误处理
+* 不要在事务里做高延迟外部调用
+* 不要在未确认 `configCode`、接收对象和消息内容时执行通知型 BFF
+* 不要把通知执行超时当作“肯定未发送”并自动重试
+
+## 自检清单
+
+* [ ] 已确认脚本类型是 Before / After / Endpoint / Common
+* [ ] 若脚本涉及数据集，已执行 `rabetbase dataset detail` 获取数据集信息
+* [ ] 若涉及数据集，字段名、类型、必填、枚举、关系已核对
+* [ ] 函数名正确（将作为 `scriptName` 参数传入）
+* [ ] 顶部注释完整且占位符已替换
+* [ ] 数据集映射使用 `"dataset_" + 32 位编码`
+* [ ] 单条查询统一使用 `getOne`
+* [ ] 列表查询使用 `filter`，并从 `.tableData` 读取结果
+* [ ] DB_TABLE 简单单表聚合优先使用 `aggregate()`，并从 `.tableData` 读取结果
+* [ ] `create()` 返回值按新记录 ID 处理，没有访问 `.id`
+* [ ] `batchCreate()` 直接接收非空对象数组，并按新记录 ID 数组处理返回值
+* [ ] 批量更新使用 `update({ id: [...] })`，没有使用不存在的 `batchUpdate()` 或记录数组参数
+* [ ] 枚举/选择字段写入 `options[].value`，不是展示 `label`
+* [ ] SQL 返回值按 BFF 语义处理
+* [ ] 未设置系统自动维护字段
+* [ ] 无明显 N+1 或循环写入问题
+* [ ] HOOK 返回 `params`，ENDPOINT 返回业务对象
+* [ ] 若脚本发送通知，只使用 `configCode` / `audiences` / `message`，且已确认接收对象和外部副作用
+
+## 相关指南
+
+* `data-api-guidelines.md`
+* `sql-creation-workflow.md`
+* `bff-creation-workflow.md`
+* `conflict-detection.md`