---
name: yida-business-rule
description: 宜搭表单业务关联规则/高级函数配置技能。用于用户明确要求在表单设置中配置业务关联规则，或使用 INSERT、UPDATE、DELETE、UPSERT 高级函数做跨表增删改。不适用于：常规推荐的集成自动化逻辑流（应使用 yida-integration），或普通字段默认值/校验公式（应使用 yida-formula）。
---

# yida-business-rule — 业务关联规则高级函数

## 适用边界

业务关联规则是宜搭表单设置里的旧式/低频跨表联动能力。用户明确提到以下意图时使用本技能：

- "业务关联规则"、"表单事件里的公式执行"
- "高级函数"、"INSERT"、"UPDATE"、"DELETE"、"UPSERT"
- "要在表单设置里配 upsert/update/delete/insert"
- 明确不想用集成自动化，而要用公式函数做跨表增删改

默认建议：

| 场景 | 使用技能 |
|------|---------|
| 常规提交后跨表联动、长期维护、节点编排 | `yida-integration` |
| 用户明确要求高级函数/业务关联规则 | **本技能** |
| 字段默认值、计算字段、自定义校验 | `yida-formula` |
| 查询/新增/更新已有表单数据记录 | `yida-data-management` |

## 配置入口

在表单设计器里进入：

```text
表单设置 → 表单事件 → 公式执行 → 添加业务关联规则
```

业务关联规则弹窗包含三个事件输入框：

| 事件 | 触发时机 |
|------|---------|
| `单据提交` | 新增记录提交成功后 |
| `单据删除` | 删除记录成功后 |
| `单据编辑` | 编辑记录提交成功后 |

点击事件输入框会打开「公式执行」编辑器。配置完成后必须依次确认：公式弹窗 → 业务关联规则弹窗 → 保存表单。

## 关键原则：必须插入令牌

业务关联公式不是普通字段公式。普通字段公式引用字段用 `#{fieldId}`；业务关联规则引用目标表、目标字段、当前表字段时，必须在公式编辑器左侧列表点击插入令牌。

不要直接手敲中文表单名或字段名。实际验证中，手敲下面这种文本会报非法标识符：

```text
UPSERT(Upsert目标,EQ(Upsert目标.键,"x"),"",Upsert目标.键,"x")
```

正确方式是在编辑器中输入函数名、括号、逗号、字符串常量，然后点击左侧字段列表插入 `Upsert目标`、`Upsert目标.键` 等令牌。最终输入框看起来可能和手敲文本相似，但内部结构不同。

## 高级函数签名

| 函数 | 格式 | 说明 |
|------|------|------|
| `INSERT` | `INSERT(目标表, 目标列1, 目标值1, 目标列2, 目标值2, ...)` | 向目标表插入新实例 |
| `UPDATE` | `UPDATE(目标表, 主条件, 子条件, 目标列1, 目标值1, ...)` | 更新目标表中满足条件的数据 |
| `UPSERT` | `UPSERT(目标表, 主条件, 子条件, 目标列1, 目标值1, ...)` | 有匹配数据则更新，无匹配数据则插入 |
| `DELETE` | `DELETE(目标表, 主条件, 子条件)` | 删除目标表中满足条件的数据 |

`子条件` 用于定位目标表某条数据下的子表单明细。不操作子表单时必须写 `""`，不能省略。

## UPSERT 模板

普通主表字段 upsert：

```text
UPSERT(目标表, EQ(目标表.业务键, 当前表业务键), "", 目标表.业务键, 当前表业务键, 目标表.目标字段, 当前表来源字段)
```

库存类示例：

```text
UPSERT(存货表, EQ(存货表.商品名, 商品名), "", 存货表.商品名, 商品名, 存货表.存货量, 存货表.存货量 + 进货量)
```

固定值探测示例：

```text
UPSERT(Upsert目标, EQ(Upsert目标.键, "_openyida_upsert_probe"), "", Upsert目标.键, "_openyida_upsert_probe", Upsert目标.备注, "configured from form settings")
```

以上示例中的表单名和字段名只是可读展示。真实配置时，所有表单和字段引用都要从左侧列表点击插入令牌。

## 条件规则

- `主条件`、`子条件` 必须由逻辑函数构造，常见为 `EQ()`、`AND()`、`OR()`。
- 除 `AND()`、`OR()` 外，逻辑函数第一个参数必须是目标表组件，例如 `EQ(存货表.商品名, 商品名)`。
- 不要把当前表字段写在 `EQ()` 第一个参数，也不要在第一个参数里嵌套其他函数。
- 更新普通组件时，`目标列` 必须是目标表普通组件。
- 更新子表单明细时，`目标列` 必须是对应明细下的组件。
- 同一个高级函数里不要同时更新普通组件和明细组件；需要拆成多条规则或多个函数。

## 浏览器配置步骤

1. 确认触发表单和目标表单都在同一应用内。
2. 用 `openyida get-schema <appType> <formUuid>` 查清目标字段和来源字段，避免点错。
3. 打开触发表单设计器，进入 `表单设置 → 表单事件 → 公式执行 → 添加业务关联规则`。
4. 点击要配置的事件输入框，例如 `单据编辑`。
5. 在公式编辑器中只手动输入函数名、括号、逗号、字符串常量。
6. 目标表、目标列、来源字段全部从左侧列表点击插入令牌。
7. 每插入一个令牌后暂停并校验公式显示，避免 CodeMirror 光标错位。
8. 点击公式弹窗「确定」。如果能回到业务关联规则弹窗，说明公式通过编辑器校验。
9. 点击业务关联规则弹窗「确定」，最后点击表单设计器「保存」并确认保存成功。

## 用量限制

| 函数 | 目标表类型 | 用量限制 |
|------|-----------|---------|
| `INSERT` | 主表 | 批量导入无条数限制，建议单次不超过 1000 条 |
| `INSERT` | 子表单插入主表 | 免费版 ≤50 条；轻享/专业/专属版 ≤500 条 |
| `UPDATE` | 主表 | 单次最多更新 100 条，超出会报错 |
| `UPDATE` | 子表单 | 免费版 ≤50 条；轻享/专业/专属版 ≤500 条 |
| `UPSERT` | 主表 | 单次最多 100 条，超出会报错 |
| `UPSERT` | 子表单 | 免费版 ≤50 条；轻享/专业/专属版 ≤500 条 |
| `DELETE` | 主表 | 单次最多删除 100 条 |
| `DELETE` | 子表单 | 轻享/专业/专属版 ≤500 条 |

## 常见错误

| 错误 | 原因 | 处理 |
|------|------|------|
| `该标识符不合法` | 手敲了表单名/字段名 | 从左侧列表点击插入令牌 |
| `Unexpected end of input` | 公式未闭合或必填参数缺失 | 检查括号、逗号、`子条件` |
| 规则未触发 | 配在错误事件或未保存表单 | 检查 `单据提交/删除/编辑` 和保存结果 |
| 更新结果过多 | 条件不够精确或超出限制 | 收紧 `主条件`，必要时改用集成自动化 |

## 参考

- 宜搭帮助中心：表单业务规则
- 宜搭帮助中心：INSERT / UPDATE / UPSERT / DELETE 业务关联公式