npm - weaver-e10-builder - Versions diffs - 1.6.16 → 1.7.1 - Mend

weaver-e10-builder 1.6.16 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2055) hide show

package/skill-docs/references/form/guide-formula-linkage.md CHANGED Viewed

@@ -1,324 +1,324 @@
-# 函数联动（本表字段间的公式赋值）指南
-## 概述
-函数联动：在**本表单内部**，当某个字段变化（或表单载入）时，用一张**公式**算出结果，赋值给本表的另一个字段。
-例：`数量` 或 `单价` 变化时 → `销售金额 = 数量 × 单价`。
-设计器里的位置是字段属性面板的「函数联动」，要配四件事：**在哪生效**（生效维度）、**什么时候触发**（触发时机，**可以挂多个**）、**谁触发**（触发字段）、**赋值给谁 + 怎么算**（目标字段 + 函数体）。
-> **不跨表。** 要查另一张表把值带回来，那是 `form field-linkage`（跨表带出），见 `guide-field-linkage.md`。
-## 四套联动对比
-| | 属性联动（显隐） | 关联表带出 | **字段联动（跨表带出）** | **函数联动（本表赋值）** |
-|---|---|---|---|---|
-| 命令 | `form linkage add` | `form relate` | `form field-linkage add` | `form formula-linkage add` |
-| 取值靠 | — | HRM 源 | ESB 动作流（查另一张表） | **一张公式** |
-| `linkageType` | （另一套存储） | — | `template` | `excel` |
-| 做的事 | 改字段显示属性 | 换 Employee/Department→带 HRM 属性 | 查任意表→带出字段赋值 | **本表字段→算→赋给本表字段** |
-| 跨表 | 否 | 否 | **是** | 否 |
-四者可以叠加：同一个字段既可以有显隐联动，也可以被函数联动赋值。
-## 赋值式：公式长什么样
-落库的 `expressSql` 是一条**赋值式**，左边是目标字段、右边是函数体：
-```
-{主表.销售金额}=VALUE({主表.数量})*VALUE({主表.单价})
-```
-CLI 的 `--expression` **只给右边**就行，左边的 `{主表.<目标>}=` 会自动拼上。
-从设计器里整段复制也行 —— 如果表达式里已经有赋值式，CLI 会校验它的左侧与 `--target` 是否指向同一字段：一致就沿用，不一致就**报错中止**（不会偷偷改目标）。
-> ⚠ **一个等号是赋值，两个等号才是比较 —— 两个层次别写反。**
-> - **顶层**那个 `=` 是「赋给谁」：`{主表.销售金额}=…`。**一个等号**。
-> - **函数体内部**做判断要用 `==`：`IF({主表.状态}=="已完成", 1, 0)`。**两个等号**。
->
-> 函数体里写成单个 `=` 不报错，只是按赋值语义走、算出来不对。另：**函数名必须大写**（自定义 JS 脚本函数除外）、**跨表粘贴的公式要把 `{主表.X}`/`{明细表.X}` 逐个换成本表字段**、**选项型控件要比就得引用选项本身**（`{主表.性别}=={主表.性别.男}`，写成 `=='男'` 恒不成立）—— 合看 `guide-form-formula-functions.md` 的「写公式前先记住这几条」。
-### 字段引用的两种写法
-| 写法 | 场景 |
-|---|---|
-| `{主表.字段名}` / `{明细表名.字段名}` | 平台存储格式，整段复制来的就是这种 |
-| `[字段名]` / `[表名.字段名]` | 设计器编辑器里的显示格式 |
-两种都收，保存前统一归一化成花括号再下发（原样发方括号会静默失效，见 `guide-form-formula-functions.md`）。
-**函数体里不要出现裸方括号** —— 解析器把任何 `[...]` 都当字段引用，`SUBSTR("a[1]",…)` 这种会被当成找不到的字段。
-## 模块字段（系统字段）
-`{主表.主表数据id}`、`{主表.当前日期}`、`{主表.操作者部门}` 这类是**系统模块字段**，可以出现在公式右边，也能当触发字段，但**不能作为赋值目标**。
-原因很直白：平台在公式的 `extendParam.unSupportTargets` 里把这 21 个字段列成了「不可赋值」，而 CLI 就用这份清单做判据 —— 传了模块字段当 `--target` 会当场报错，不会建出一条平台不认的规则。
-两种写法都能用：
-```
-{主表.主表数据id}      ← 裸标签，平台存储格式
-[formDataId]          ← 语义键，等价；归一化后仍写成裸标签
-```
-`form formula-linkage columns` 会把两桶分开列：业务字段（可作目标）+ 系统模块字段（不可作目标）。
-## CLI 命令
-```bash
-# 看有哪些事件可选（值改变时 / 载入时 / 创建数据时 …）
-e10-cli form formula-linkage events <appId> <objId>
-# 看有哪些字段可用（业务字段 / 系统模块字段分两桶）
-e10-cli form formula-linkage columns <appId> <objId>
-e10-cli form formula-linkage columns <appId> <objId> --keyword 金额
-# 列出/回读（read 带公式表达式与参数）
-e10-cli form formula-linkage list <appId> <objId>
-e10-cli form formula-linkage read <appId> <objId> <linkageId>
-# 新增
-e10-cli form formula-linkage add <appId> <objId> \
-  --event changeField \
-  --trigger 数量 --trigger 单价 \
-  --target 销售金额 \
-  --expression "VALUE({主表.数量})*VALUE({主表.单价})"
-# 改联动（只传要改的；--event/--trigger 不传就沿用现有的）
-e10-cli form formula-linkage update <appId> <objId> <linkageId> --trigger 产品类别
-e10-cli form formula-linkage update <appId> <objId> <linkageId> --state off
-e10-cli form formula-linkage update <appId> <objId> <linkageId> --name "重算金额"
-# 关掉「联动出的值继续触发联动」
-e10-cli form formula-linkage update <appId> <objId> <linkageId> --fission off
-# 改公式正文（目标不变）
-e10-cli form formula-linkage update <appId> <objId> <linkageId> \
-  --expression "VALUE({主表.数量})*VALUE({主表.单价})*2"
-# 连赋值目标一起改
-e10-cli form formula-linkage update <appId> <objId> <linkageId> \
-  --target 含税金额 --expression "VALUE({主表.数量})*VALUE({主表.单价})"
-# 只改目标（沿用原公式右侧）
-e10-cli form formula-linkage update <appId> <objId> <linkageId> --target 含税金额
-# 删除（批量）
-e10-cli form formula-linkage delete <appId> <objId> <linkageId...>
-```
-### 改公式（`--expression` / `--target`）
-**联动和公式是两条记录**：联动里只存 `sourceExcel.excelId`，真正被写入的赋值式在公式记录里。所以：
-- 只改触发时机 / 名称 / 启停 → 不碰公式，`updateFormDataLinkage` 就够了；
-- 改表达式或赋值目标 → 走 `--expression` / `--target`，命令读回联动引用的 `excelId`、按新表达式重建参数表，再用 `formulaId` **原地更新那张公式**（`excelId` 不变），不会删掉联动重建。
-两种写法都能改：
-- `--expression` 只给右侧函数体，或直接贴整段赋值式（左侧与最终目标不一致会报错，不会静默改目标）；含引号/换行时用 `@文件路径`。
-- `--target` 单独给时，沿用原公式右侧，只换左侧目标；与 `--expression` 一起给时按新目标拼左侧。
-> `delete` 删除的是**联动记录**，把规则从表单上摘掉。公式记录是另一条记录，本命令不发单独的公式删除请求。
-### add 的参数
-| 参数 | 说明 |
-|---|---|
-| `--target <字段>` | **赋值目标**，被写入的字段。只能是业务字段 |
-| `--expression <函数体>` | 公式右侧。含引号/换行时可用 `@文件路径` |
-| `--event <事件...>` | **触发时机，可给多个**（一条联动能挂多个）。每个可自带触发字段：写 `事件名或 type`，或 `类型:字段,字段`。默认 `changeField`（值改变时） |
-| `--trigger <字段...>` | 触发字段，可多个。作用于**没有自带字段**的字段级事件；表单级 / 流程级事件不用给 |
-| `--effect <维度>` | 生效维度：`form`（默认，当前表单）/ `formLayout`（表单布局）/ `workFlow`（当前工作流）/ `includeNode`（选择节点，另需 `--node`）。后两者必给 `--workflow-id` |
-| `--name <名>` | 联动名。默认 `<公式名> - 公式_<时间戳>` |
-| `--formula-name <名>` | 公式名，默认取表单名 |
-| `--formula-id <id>` | 复用/更新已有公式，不新建 |
-| `--fission on\|off` | **联动出的值继续触发联动**，默认 `on`。关掉后，本规则算出的值不再作为其他联动的触发来源（落库 `linkageExt.fissionState`：on=1 / off=0） |
-### 联动出的值继续触发联动（`--fission`）
-函数联动与字段联动共用同一个开关，存在 `linkageExt.fissionState`：
-```bash
-# 新建时关掉
-e10-cli form formula-linkage add <appId> <objId> ... --fission off
-# 改已有规则
-e10-cli form formula-linkage update <appId> <objId> <linkageId> --fission off
-```
-`on`（缺省）表示这条规则赋值后产生的字段变化还会继续驱动其他联动；`off` 表示到此为止，避免多条规则相互触发形成循环。`list` / `read` 会显示当前状态。
-### 生效维度（`--effect`）
-| 维度 | `--effect` | 生效范围 |
-|---|---|---|
-| 当前表单（默认） | 不传 或 `form` | 该表单的**所有布局**，以及所有关联了该表单的工作流 |
-| 表单布局 | `formLayout` | **只对选定的那一个布局** |
-```bash
-# 只在这个布局上生效
-e10-cli form formula-linkage add <appId> <objId> --effect formLayout \
-  --event changeField --trigger 数量 --target 销售金额 \
-  --expression "VALUE({主表.数量})"
-```
-> ⚠ 布局 id 取的是 `getFormLayout` 返回的 **`multipleLayoutId`**，不是 `formLayout.id` —— 同一张表上这两个值相邻但不同（如 `…375` / `…376`），**发错不报错，只是指向另一个布局**，回读时生效范围会是个空白。CLI 走的是与显隐联动同一套解析（`resolveEffect`），不用手填 id。
-### 触发事件
-| 分组 | 事件 | type | 要触发字段 |
-|---|---|---|---|
-| 字段 | 值改变时 / 获取输入焦点时 / 失去输入焦点时 / 鼠标单击时 / 鼠标双击时 | `changeField` / `onfocus` / `onblur` / `onclick` / `ondbclick` | 要 |
-| 表单 | 载入时 / 载入时(可编辑) / 载入时(新建) / 创建数据时 / 窗口滚动时 | `onLoadForm` / `onLoadFormEdit` / `onLoadFormCreate` / `createData` / `onscroll` | 不要 |
-| 流程 | 提交/批准时 / 转发时 / 保存时 / 退回时 / 转办时 / 意见征询时 / 传阅时 | `EVENT_SUBMIT_OR_AGREE` / `EVENT_FORWARD` / `EVENT_SAVE_DATA` / `EVENT_REJECT` / `EVENT_TURNTODO` / `EVENT_REMARKADVICE` / `EVENT_CIRCULATE` | 不要 |
-⚠ **「流程」那一组默认列不出来**：`form formula-linkage events` 不给 `--effect` 时只列前两组 10 个，加 `--effect workFlow --workflow-id <流程id>` 才列得出 17 个。用了流程事件就要把生效维度也设成「当前工作流 / 选择节点」——两者的关系不是可选的；换个维度又沿用旧事件时 CLI 会直接报错拦下。
-### 一条联动挂多个触发时机
-「触发时机」**不是单选**：设计器里勾几个，`monitorActions` 就存几条。
-```bash
-# 7 个流程时机一起挂（都不需要触发字段）
-e10-cli form formula-linkage add <appId> <objId> --effect workFlow --workflow-id <wf> \
-  --event EVENT_SUBMIT_OR_AGREE EVENT_FORWARD EVENT_SAVE_DATA \
-  --target 登记时间 --expression '{主表.当前日期}'
-# 各配各的触发字段：值改变时看「数量、单价」，鼠标单击时看「按钮」
-e10-cli form formula-linkage add <appId> <objId> \
-  --event changeField:数量,单价 onclick:按钮 \
-  --target 销售金额 --expression "VALUE({主表.数量})*VALUE({主表.单价})"
-# 老写法照旧：--trigger 给所有「没自带字段」的字段级事件
-e10-cli form formula-linkage add <appId> <objId> \
-  --event changeField onclick --trigger 数量 \
-  --target 销售金额 --expression "VALUE({主表.数量})"
-```
-## 示例
-### 金额 = 数量 × 单价（两个触发字段）
-```bash
-e10-cli form formula-linkage add <appId> <objId> \
-  --event changeField --trigger 数量 --trigger 单价 \
-  --target 销售金额 \
-  --expression "VALUE({主表.数量})*VALUE({主表.单价})"
-```
-### 编号 = 数据ID + 订单号（引用系统模块字段）
-```bash
-e10-cli form formula-linkage add <appId> <objId> \
-  --event onLoadFormCreate \
-  --target 订单编号 \
-  --expression 'CONCAT({主表.主表数据id},{主表.订单编号})'
-```
-### 载入时赋当前日期（表单级事件，不给 --trigger）
-```bash
-e10-cli form formula-linkage add <appId> <objId> \
-  --event onLoadForm --target 登记日期 --expression '{主表.当前日期}'
-```
-## 注意事项
-> 公式**语言本身**的硬规则（函数名必须大写 / 比较用 `==` / 赋值用 `=` / 跨表粘贴要换字段变量）在 `guide-form-formula-functions.md` 的「写公式前先记住这四条」，写表达式前先过一遍 —— 这几条写错**不报错**，只是算不对。
-1. **目标只能是业务字段**。系统模块字段（`主表数据id`/`当前日期`/`操作者部门` 等 21 个）不能作 `--target`，但可以出现在公式右边、也可以当触发字段。
-2. **一个触发时机 × 一个触发字段 = 一条触发动作**。多个触发字段 → N 条 `actionType` 相同的动作；多个触发时机 → 多条 `actionType` 各异的动作。平台侧就是这张表，不是一条里挂 N 个字段 —— CLI 已按这个形状下发。**`update` 不给 `--event`/`--trigger` 时原样沿用现有的触发时机**，不会只留第一条。
-3. **触发字段与目标不能搞反**。`--trigger` 是「谁变了」，`--target` 是「谁被写」。写反了规则会反向生效，回读时表达式左边能看到真实目标。
-4. **字段名有歧义会报错**，不会默认取第一条。两张明细表里各有一个「编号」时，写 `编号` 会列出两个候选，改用字段 id 或 `明细表名.编号`。
-5. **业务字段与模块字段同名时**（如业务字段叫「标题」、模块字段 `name` 的标签也叫「标题」），按裸标签写会报歧义，用字段 id 或完整列名 `主表.标题` 区分。
-6. **生效范围四种**：缺省「当前表单」（所有布局 + 所有关联该表单的工作流）、`--effect formLayout`（只对某个布局生效）、`--effect workFlow`（当前工作流，需 `--workflow-id`）、`--effect includeNode`（选择节点，需 `--workflow-id` + `--node`）。布局 id 由 CLI 现查（见上「生效维度」）。`update` 不传 `--effect` 会沿用现有维度 —— 但**在「表单/布局」与「工作流/节点」之间换维度时必须同时给 `--event`**，否则会存出一条事件与维度对不上的坏规则。
-7. **改了公式不会同步 `inFields`/`outFields`**。平台的数据源上带这两组字段（公式用到的来源字段 / 被赋值的字段），它们反映的是**建这条联动时**的公式；后来改公式它们不跟着变。这不影响运行，但别拿它当「当前公式用了哪些字段」的依据 —— 用 `form formula-linkage read` 看表达式。
-8. **`form field-linkage` 看不见这类联动**。两者 `linkageType` 不同（`excel` vs `template`），各查各的。`form field-linkage list` 末尾会提示「另有 N 条函数联动」；`form field-linkage delete` 传函数联动的 id 会直接报错指路，不会静默删 0 条。
-9. **`--event` 里 `类型:字段,字段` 的分隔符只认半角 `:` 与 `,`**（全角「：」「，」不作分隔）。字段名里真含半角逗号时会被切坏 —— 那种字段改用 `--trigger`（空格分隔），或直接写字段 id。
-## 流程表单上的函数联动（`wf-form formula-linkage`）
-流程表单也支持函数联动，是**同一能力的另一条路由**。命令面与 eb 表逐字对齐，只有位置参数和多出来的选项不同：
-```bash
-wf-form formula-linkage list   <formId> --workflow-id <id>
-wf-form formula-linkage read   <formId> --workflow-id <id> <linkageId>
-wf-form formula-linkage events <formId> --workflow-id <id>
-wf-form formula-linkage columns<formId> --workflow-id <id>
-wf-form formula-linkage add    <formId> --workflow-id <id> --target <字段> --expression <函数体> [...]
-wf-form formula-linkage update <formId> --workflow-id <id> <linkageId> [...]
-wf-form formula-linkage delete <formId> --workflow-id <id> <linkageIds...>
-```
-`--workflow-id` 一个旗标管两件事：**`refId`**（这条联动挂在流程上）+「当前工作流 / 选择节点」两个维度的取值来源。不给就按 `formId` 兜底（查不到时先补上它）。流程 ID 用 `workflow search --name <流程名>` 拿。
-### 两条路由的差异
-| | eb 表 `form formula-linkage` | **流程表单 `wf-form formula-linkage`** |
-|---|---|---|
-| 位置参数 | `<appId> <objId>` | **`<formId>`** + `--workflow-id` |
-| 联动端点 | `/api/ebuilder/form/form/linkage` | `/api/ebuilder/flow/form/linkage`（**不带 `?apid=`**） |
-| `module` | `ebuilderform` | **`ebuildercard`** |
-| 定位入参 | `customParam: {appId, objId}`（读、存都发） | **顶层 `refId` = workflowId**；`customParam: {scene:'workflow'}` **只在读的时候发，保存报文里没有这个键** |
-| 公式参数里的 `appId` | 有 | **没有这个键** |
-| 不可作赋值目标的系统字段 | 21 项 | **30 项**（模块字段桶是 32 —— 差的两个见下） |
-| 触发事件 | 默认 10 个（字段组 5 + 表单组 5）；生效维度给 `workFlow`/`includeNode` 时取流程那套 = **17 个** | **恒 17 个**（这条路由一直取流程那套） |
-| 生效维度 | 四种：当前表单 / 表单布局 / 当前工作流 / 选择节点（后两者需 `--workflow-id`） | 同样四种 |
-### 多出来的「流程」触发事件
-除了字段组的 5 个与表单组的 5 个，还有 7 个流程级事件（都不需要 `--trigger`）：
-> ⚠ 这 7 个**不是流程表单专属**：eb 表选了「当前工作流 / 选择节点」维度时一样能用（设计器就这么配、也存得下）。差别只在**取清单**：eb 路由默认只给前两组 10 个，要给流程事件得加 `--effect workFlow --workflow-id <流程id>` 让它去取流程那套。
-```
-EVENT_SUBMIT_OR_AGREE  提交/批准时      EVENT_REJECT        退回时
-EVENT_FORWARD          转发时          EVENT_TURNTODO      转办时
-EVENT_SAVE_DATA        保存时          EVENT_REMARKADVICE  意见征询时
-                                      EVENT_CIRCULATE     传阅时
-```
-### 生效维度的四种取值
-```bash
---effect form          # 默认。当前表单
---effect formLayout    # 表单布局（--layout-id 可指定，不传取默认布局）
---effect workFlow      # 当前工作流，必须给 --workflow-id
---effect includeNode   # 选择节点，必须给 --workflow-id 与 --node
-```
-「选择节点」的 `--node` 可以给节点 id 或节点名。「当前工作流」的选项名是 `流程名【V活动版本号】`，版本号取活动版本 —— 与设计器发出的形状一致。
-四种取值 eb 表也有（1.5.11 起），命令面同名同义。另外：`fdEffect.effectModule` **跟生效维度走、不跟路由走** —— 「当前工作流 / 选择节点」两个维度归卡片模块（`ebuildercard`），即便这条联动挂在 eb 表上（`linkageModule` 仍是 `ebuilderform`）。
-### 系统字段里有两个**可以**当赋值目标
-流程表单的模块字段桶有 32 项，但平台标「不可赋值」的只有 30 项，差的是：
-```
-REQ_REQUEST_NAME   流程标题
-REQUEST_LEVEL      紧急程度
-```
-这两个**可以**作 `--target`。`columns` 命令会按「可作 / 不可作赋值目标」分桶列出，别拿「是不是系统字段」去判断。
-### 流程表单这条路由读不出字段时
-`wf-form` 的多数命令靠 `getFormLayout` + `getConfig` 读字段，但**部分流程表单上 `getFormLayout` 会直接 500**（`Form.isPhysicalTable()` 上 NPE）。函数联动**不受影响** —— 它的字段清单直接取 `findFormDrivingColumns`（这条路由自己给的），没走 `getConfig`。所以 `wf-form read` 读不出来的表单，`wf-form formula-linkage columns` 照样能列出字段。
-## 常见报错
-| 报错 | 原因 | 怎么办 |
-|---|---|---|
-| 系统模块字段「X」不能作为赋值目标 | `--target` 写了模块字段 | 换成业务字段；模块字段只能出现在公式右边 |
-| 「X」在…上匹配到 N 个字段 | 字段名有歧义 | 用字段 id（`form formula-linkage columns` 里）
-| 表达式里写的是一个赋值式，它的左侧是「A」，与 --target「B」不一致 | 粘贴的赋值式目标与 `--target` 不符 | 改 `--target`，或只给右侧函数体 |
-| 事件「载入时」是表单级/流程级的，不需要触发字段，--trigger 已忽略 | 表单级 / 流程级事件给了触发字段 | 无害提示；去掉字段即可 |
-| 事件「值改变时」需要指定触发字段 | 字段级事件没给触发字段 | 补 `--trigger`，或写成 `--event changeField:<字段,字段>` |
-| 未知事件「EVENT_FORWARD」，可用: …（只列 10 个） | 想在 eb 表上用流程级事件，但没换维度 | 加 `--effect workFlow --workflow-id <流程id>` 再试 |
-| 生效维度在「当前表单/表单布局」与「当前工作流/选择节点」之间切换时，必须同时用 --event 指定… | `update` 换了维度却沿用旧事件 | 一起给 `--event`（新的维度下可用的事件） |
-| 平台回读的表达式与提交不一致 | 归一化猜错了写法 | 以平台为准；把 `read` 的结果记下来反馈 |
+# 函数联动（本表字段间的公式赋值）指南
+## 概述
+函数联动：在**本表单内部**，当某个字段变化（或表单载入）时，用一张**公式**算出结果，赋值给本表的另一个字段。
+例：`数量` 或 `单价` 变化时 → `销售金额 = 数量 × 单价`。
+设计器里的位置是字段属性面板的「函数联动」，要配四件事：**在哪生效**（生效维度）、**什么时候触发**（触发时机，**可以挂多个**）、**谁触发**（触发字段）、**赋值给谁 + 怎么算**（目标字段 + 函数体）。
+> **不跨表。** 要查另一张表把值带回来，那是 `form field-linkage`（跨表带出），见 `guide-field-linkage.md`。
+## 四套联动对比
+| | 属性联动（显隐） | 关联表带出 | **字段联动（跨表带出）** | **函数联动（本表赋值）** |
+|---|---|---|---|---|
+| 命令 | `form linkage add` | `form relate` | `form field-linkage add` | `form formula-linkage add` |
+| 取值靠 | — | HRM 源 | ESB 动作流（查另一张表） | **一张公式** |
+| `linkageType` | （另一套存储） | — | `template` | `excel` |
+| 做的事 | 改字段显示属性 | 换 Employee/Department→带 HRM 属性 | 查任意表→带出字段赋值 | **本表字段→算→赋给本表字段** |
+| 跨表 | 否 | 否 | **是** | 否 |
+四者可以叠加：同一个字段既可以有显隐联动，也可以被函数联动赋值。
+## 赋值式：公式长什么样
+落库的 `expressSql` 是一条**赋值式**，左边是目标字段、右边是函数体：
+```
+{主表.销售金额}=VALUE({主表.数量})*VALUE({主表.单价})
+```
+CLI 的 `--expression` **只给右边**就行，左边的 `{主表.<目标>}=` 会自动拼上。
+从设计器里整段复制也行 —— 如果表达式里已经有赋值式，CLI 会校验它的左侧与 `--target` 是否指向同一字段：一致就沿用，不一致就**报错中止**（不会偷偷改目标）。
+> ⚠ **一个等号是赋值，两个等号才是比较 —— 两个层次别写反。**
+> - **顶层**那个 `=` 是「赋给谁」：`{主表.销售金额}=…`。**一个等号**。
+> - **函数体内部**做判断要用 `==`：`IF({主表.状态}=="已完成", 1, 0)`。**两个等号**。
+>
+> 函数体里写成单个 `=` 不报错，只是按赋值语义走、算出来不对。另：**函数名必须大写**（自定义 JS 脚本函数除外）、**跨表粘贴的公式要把 `{主表.X}`/`{明细表.X}` 逐个换成本表字段**、**选项型控件要比就得引用选项本身**（`{主表.性别}=={主表.性别.男}`，写成 `=='男'` 恒不成立）—— 合看 `guide-form-formula-functions.md` 的「写公式前先记住这几条」。
+### 字段引用的两种写法
+| 写法 | 场景 |
+|---|---|
+| `{主表.字段名}` / `{明细表名.字段名}` | 平台存储格式，整段复制来的就是这种 |
+| `[字段名]` / `[表名.字段名]` | 设计器编辑器里的显示格式 |
+两种都收，保存前统一归一化成花括号再下发（原样发方括号会静默失效，见 `guide-form-formula-functions.md`）。
+**函数体里不要出现裸方括号** —— 解析器把任何 `[...]` 都当字段引用，`SUBSTR("a[1]",…)` 这种会被当成找不到的字段。
+## 模块字段（系统字段）
+`{主表.主表数据id}`、`{主表.当前日期}`、`{主表.操作者部门}` 这类是**系统模块字段**，可以出现在公式右边，也能当触发字段，但**不能作为赋值目标**。
+原因很直白：平台在公式的 `extendParam.unSupportTargets` 里把这 21 个字段列成了「不可赋值」，而 CLI 就用这份清单做判据 —— 传了模块字段当 `--target` 会当场报错，不会建出一条平台不认的规则。
+两种写法都能用：
+```
+{主表.主表数据id}      ← 裸标签，平台存储格式
+[formDataId]          ← 语义键，等价；归一化后仍写成裸标签
+```
+`form formula-linkage columns` 会把两桶分开列：业务字段（可作目标）+ 系统模块字段（不可作目标）。
+## CLI 命令
+```bash
+# 看有哪些事件可选（值改变时 / 载入时 / 创建数据时 …）
+e10-cli form formula-linkage events <appId> <objId>
+# 看有哪些字段可用（业务字段 / 系统模块字段分两桶）
+e10-cli form formula-linkage columns <appId> <objId>
+e10-cli form formula-linkage columns <appId> <objId> --keyword 金额
+# 列出/回读（read 带公式表达式与参数）
+e10-cli form formula-linkage list <appId> <objId>
+e10-cli form formula-linkage read <appId> <objId> <linkageId>
+# 新增
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField \
+  --trigger 数量 --trigger 单价 \
+  --target 销售金额 \
+  --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+# 改联动（只传要改的；--event/--trigger 不传就沿用现有的）
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --trigger 产品类别
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --state off
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --name "重算金额"
+# 关掉「联动出的值继续触发联动」
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --fission off
+# 改公式正文（目标不变）
+e10-cli form formula-linkage update <appId> <objId> <linkageId> \
+  --expression "VALUE({主表.数量})*VALUE({主表.单价})*2"
+# 连赋值目标一起改
+e10-cli form formula-linkage update <appId> <objId> <linkageId> \
+  --target 含税金额 --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+# 只改目标（沿用原公式右侧）
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --target 含税金额
+# 删除（批量）
+e10-cli form formula-linkage delete <appId> <objId> <linkageId...>
+```
+### 改公式（`--expression` / `--target`）
+**联动和公式是两条记录**：联动里只存 `sourceExcel.excelId`，真正被写入的赋值式在公式记录里。所以：
+- 只改触发时机 / 名称 / 启停 → 不碰公式，`updateFormDataLinkage` 就够了；
+- 改表达式或赋值目标 → 走 `--expression` / `--target`，命令读回联动引用的 `excelId`、按新表达式重建参数表，再用 `formulaId` **原地更新那张公式**（`excelId` 不变），不会删掉联动重建。
+两种写法都能改：
+- `--expression` 只给右侧函数体，或直接贴整段赋值式（左侧与最终目标不一致会报错，不会静默改目标）；含引号/换行时用 `@文件路径`。
+- `--target` 单独给时，沿用原公式右侧，只换左侧目标；与 `--expression` 一起给时按新目标拼左侧。
+> `delete` 删除的是**联动记录**，把规则从表单上摘掉。公式记录是另一条记录，本命令不发单独的公式删除请求。
+### add 的参数
+| 参数 | 说明 |
+|---|---|
+| `--target <字段>` | **赋值目标**，被写入的字段。只能是业务字段 |
+| `--expression <函数体>` | 公式右侧。含引号/换行时可用 `@文件路径` |
+| `--event <事件...>` | **触发时机，可给多个**（一条联动能挂多个）。每个可自带触发字段：写 `事件名或 type`，或 `类型:字段,字段`。默认 `changeField`（值改变时） |
+| `--trigger <字段...>` | 触发字段，可多个。作用于**没有自带字段**的字段级事件；表单级 / 流程级事件不用给 |
+| `--effect <维度>` | 生效维度：`form`（默认，当前表单）/ `formLayout`（表单布局）/ `workFlow`（当前工作流）/ `includeNode`（选择节点，另需 `--node`）。后两者必给 `--workflow-id` |
+| `--name <名>` | 联动名。默认 `<公式名> - 公式_<时间戳>` |
+| `--formula-name <名>` | 公式名，默认取表单名 |
+| `--formula-id <id>` | 复用/更新已有公式，不新建 |
+| `--fission on\|off` | **联动出的值继续触发联动**，默认 `on`。关掉后，本规则算出的值不再作为其他联动的触发来源（落库 `linkageExt.fissionState`：on=1 / off=0） |
+### 联动出的值继续触发联动（`--fission`）
+函数联动与字段联动共用同一个开关，存在 `linkageExt.fissionState`：
+```bash
+# 新建时关掉
+e10-cli form formula-linkage add <appId> <objId> ... --fission off
+# 改已有规则
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --fission off
+```
+`on`（缺省）表示这条规则赋值后产生的字段变化还会继续驱动其他联动；`off` 表示到此为止，避免多条规则相互触发形成循环。`list` / `read` 会显示当前状态。
+### 生效维度（`--effect`）
+| 维度 | `--effect` | 生效范围 |
+|---|---|---|
+| 当前表单（默认） | 不传 或 `form` | 该表单的**所有布局**，以及所有关联了该表单的工作流 |
+| 表单布局 | `formLayout` | **只对选定的那一个布局** |
+```bash
+# 只在这个布局上生效
+e10-cli form formula-linkage add <appId> <objId> --effect formLayout \
+  --event changeField --trigger 数量 --target 销售金额 \
+  --expression "VALUE({主表.数量})"
+```
+> ⚠ 布局 id 取的是 `getFormLayout` 返回的 **`multipleLayoutId`**，不是 `formLayout.id` —— 同一张表上这两个值相邻但不同（如 `…375` / `…376`），**发错不报错，只是指向另一个布局**，回读时生效范围会是个空白。CLI 走的是与显隐联动同一套解析（`resolveEffect`），不用手填 id。
+### 触发事件
+| 分组 | 事件 | type | 要触发字段 |
+|---|---|---|---|
+| 字段 | 值改变时 / 获取输入焦点时 / 失去输入焦点时 / 鼠标单击时 / 鼠标双击时 | `changeField` / `onfocus` / `onblur` / `onclick` / `ondbclick` | 要 |
+| 表单 | 载入时 / 载入时(可编辑) / 载入时(新建) / 创建数据时 / 窗口滚动时 | `onLoadForm` / `onLoadFormEdit` / `onLoadFormCreate` / `createData` / `onscroll` | 不要 |
+| 流程 | 提交/批准时 / 转发时 / 保存时 / 退回时 / 转办时 / 意见征询时 / 传阅时 | `EVENT_SUBMIT_OR_AGREE` / `EVENT_FORWARD` / `EVENT_SAVE_DATA` / `EVENT_REJECT` / `EVENT_TURNTODO` / `EVENT_REMARKADVICE` / `EVENT_CIRCULATE` | 不要 |
+⚠ **「流程」那一组默认列不出来**：`form formula-linkage events` 不给 `--effect` 时只列前两组 10 个，加 `--effect workFlow --workflow-id <流程id>` 才列得出 17 个。用了流程事件就要把生效维度也设成「当前工作流 / 选择节点」——两者的关系不是可选的；换个维度又沿用旧事件时 CLI 会直接报错拦下。
+### 一条联动挂多个触发时机
+「触发时机」**不是单选**：设计器里勾几个，`monitorActions` 就存几条。
+```bash
+# 7 个流程时机一起挂（都不需要触发字段）
+e10-cli form formula-linkage add <appId> <objId> --effect workFlow --workflow-id <wf> \
+  --event EVENT_SUBMIT_OR_AGREE EVENT_FORWARD EVENT_SAVE_DATA \
+  --target 登记时间 --expression '{主表.当前日期}'
+# 各配各的触发字段：值改变时看「数量、单价」，鼠标单击时看「按钮」
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField:数量,单价 onclick:按钮 \
+  --target 销售金额 --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+# 老写法照旧：--trigger 给所有「没自带字段」的字段级事件
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField onclick --trigger 数量 \
+  --target 销售金额 --expression "VALUE({主表.数量})"
+```
+## 示例
+### 金额 = 数量 × 单价（两个触发字段）
+```bash
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField --trigger 数量 --trigger 单价 \
+  --target 销售金额 \
+  --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+```
+### 编号 = 数据ID + 订单号（引用系统模块字段）
+```bash
+e10-cli form formula-linkage add <appId> <objId> \
+  --event onLoadFormCreate \
+  --target 订单编号 \
+  --expression 'CONCAT({主表.主表数据id},{主表.订单编号})'
+```
+### 载入时赋当前日期（表单级事件，不给 --trigger）
+```bash
+e10-cli form formula-linkage add <appId> <objId> \
+  --event onLoadForm --target 登记日期 --expression '{主表.当前日期}'
+```
+## 注意事项
+> 公式**语言本身**的硬规则（函数名必须大写 / 比较用 `==` / 赋值用 `=` / 跨表粘贴要换字段变量）在 `guide-form-formula-functions.md` 的「写公式前先记住这四条」，写表达式前先过一遍 —— 这几条写错**不报错**，只是算不对。
+1. **目标只能是业务字段**。系统模块字段（`主表数据id`/`当前日期`/`操作者部门` 等 21 个）不能作 `--target`，但可以出现在公式右边、也可以当触发字段。
+2. **一个触发时机 × 一个触发字段 = 一条触发动作**。多个触发字段 → N 条 `actionType` 相同的动作；多个触发时机 → 多条 `actionType` 各异的动作。平台侧就是这张表，不是一条里挂 N 个字段 —— CLI 已按这个形状下发。**`update` 不给 `--event`/`--trigger` 时原样沿用现有的触发时机**，不会只留第一条。
+3. **触发字段与目标不能搞反**。`--trigger` 是「谁变了」，`--target` 是「谁被写」。写反了规则会反向生效，回读时表达式左边能看到真实目标。
+4. **字段名有歧义会报错**，不会默认取第一条。两张明细表里各有一个「编号」时，写 `编号` 会列出两个候选，改用字段 id 或 `明细表名.编号`。
+5. **业务字段与模块字段同名时**（如业务字段叫「标题」、模块字段 `name` 的标签也叫「标题」），按裸标签写会报歧义，用字段 id 或完整列名 `主表.标题` 区分。
+6. **生效范围四种**：缺省「当前表单」（所有布局 + 所有关联该表单的工作流）、`--effect formLayout`（只对某个布局生效）、`--effect workFlow`（当前工作流，需 `--workflow-id`）、`--effect includeNode`（选择节点，需 `--workflow-id` + `--node`）。布局 id 由 CLI 现查（见上「生效维度」）。`update` 不传 `--effect` 会沿用现有维度 —— 但**在「表单/布局」与「工作流/节点」之间换维度时必须同时给 `--event`**，否则会存出一条事件与维度对不上的坏规则。
+7. **改了公式不会同步 `inFields`/`outFields`**。平台的数据源上带这两组字段（公式用到的来源字段 / 被赋值的字段），它们反映的是**建这条联动时**的公式；后来改公式它们不跟着变。这不影响运行，但别拿它当「当前公式用了哪些字段」的依据 —— 用 `form formula-linkage read` 看表达式。
+8. **`form field-linkage` 看不见这类联动**。两者 `linkageType` 不同（`excel` vs `template`），各查各的。`form field-linkage list` 末尾会提示「另有 N 条函数联动」；`form field-linkage delete` 传函数联动的 id 会直接报错指路，不会静默删 0 条。
+9. **`--event` 里 `类型:字段,字段` 的分隔符只认半角 `:` 与 `,`**（全角「：」「，」不作分隔）。字段名里真含半角逗号时会被切坏 —— 那种字段改用 `--trigger`（空格分隔），或直接写字段 id。
+## 流程表单上的函数联动（`wf-form formula-linkage`）
+流程表单也支持函数联动，是**同一能力的另一条路由**。命令面与 eb 表逐字对齐，只有位置参数和多出来的选项不同：
+```bash
+wf-form formula-linkage list   <formId> --workflow-id <id>
+wf-form formula-linkage read   <formId> --workflow-id <id> <linkageId>
+wf-form formula-linkage events <formId> --workflow-id <id>
+wf-form formula-linkage columns<formId> --workflow-id <id>
+wf-form formula-linkage add    <formId> --workflow-id <id> --target <字段> --expression <函数体> [...]
+wf-form formula-linkage update <formId> --workflow-id <id> <linkageId> [...]
+wf-form formula-linkage delete <formId> --workflow-id <id> <linkageIds...>
+```
+`--workflow-id` 一个旗标管两件事：**`refId`**（这条联动挂在流程上）+「当前工作流 / 选择节点」两个维度的取值来源。不给就按 `formId` 兜底（查不到时先补上它）。流程 ID 用 `workflow search --name <流程名>` 拿。
+### 两条路由的差异
+| | eb 表 `form formula-linkage` | **流程表单 `wf-form formula-linkage`** |
+|---|---|---|
+| 位置参数 | `<appId> <objId>` | **`<formId>`** + `--workflow-id` |
+| 联动端点 | `/api/ebuilder/form/form/linkage` | `/api/ebuilder/flow/form/linkage`（**不带 `?apid=`**） |
+| `module` | `ebuilderform` | **`ebuildercard`** |
+| 定位入参 | `customParam: {appId, objId}`（读、存都发） | **顶层 `refId` = workflowId**；`customParam: {scene:'workflow'}` **只在读的时候发，保存报文里没有这个键** |
+| 公式参数里的 `appId` | 有 | **没有这个键** |
+| 不可作赋值目标的系统字段 | 21 项 | **30 项**（模块字段桶是 32 —— 差的两个见下） |
+| 触发事件 | 默认 10 个（字段组 5 + 表单组 5）；生效维度给 `workFlow`/`includeNode` 时取流程那套 = **17 个** | **恒 17 个**（这条路由一直取流程那套） |
+| 生效维度 | 四种：当前表单 / 表单布局 / 当前工作流 / 选择节点（后两者需 `--workflow-id`） | 同样四种 |
+### 多出来的「流程」触发事件
+除了字段组的 5 个与表单组的 5 个，还有 7 个流程级事件（都不需要 `--trigger`）：
+> ⚠ 这 7 个**不是流程表单专属**：eb 表选了「当前工作流 / 选择节点」维度时一样能用（设计器就这么配、也存得下）。差别只在**取清单**：eb 路由默认只给前两组 10 个，要给流程事件得加 `--effect workFlow --workflow-id <流程id>` 让它去取流程那套。
+```
+EVENT_SUBMIT_OR_AGREE  提交/批准时      EVENT_REJECT        退回时
+EVENT_FORWARD          转发时          EVENT_TURNTODO      转办时
+EVENT_SAVE_DATA        保存时          EVENT_REMARKADVICE  意见征询时
+                                      EVENT_CIRCULATE     传阅时
+```
+### 生效维度的四种取值
+```bash
+--effect form          # 默认。当前表单
+--effect formLayout    # 表单布局（--layout-id 可指定，不传取默认布局）
+--effect workFlow      # 当前工作流，必须给 --workflow-id
+--effect includeNode   # 选择节点，必须给 --workflow-id 与 --node
+```
+「选择节点」的 `--node` 可以给节点 id 或节点名。「当前工作流」的选项名是 `流程名【V活动版本号】`，版本号取活动版本 —— 与设计器发出的形状一致。
+四种取值 eb 表也有（1.5.11 起），命令面同名同义。另外：`fdEffect.effectModule` **跟生效维度走、不跟路由走** —— 「当前工作流 / 选择节点」两个维度归卡片模块（`ebuildercard`），即便这条联动挂在 eb 表上（`linkageModule` 仍是 `ebuilderform`）。
+### 系统字段里有两个**可以**当赋值目标
+流程表单的模块字段桶有 32 项，但平台标「不可赋值」的只有 30 项，差的是：
+```
+REQ_REQUEST_NAME   流程标题
+REQUEST_LEVEL      紧急程度
+```
+这两个**可以**作 `--target`。`columns` 命令会按「可作 / 不可作赋值目标」分桶列出，别拿「是不是系统字段」去判断。
+### 流程表单这条路由读不出字段时
+`wf-form` 的多数命令靠 `getFormLayout` + `getConfig` 读字段，但**部分流程表单上 `getFormLayout` 会直接 500**（`Form.isPhysicalTable()` 上 NPE）。函数联动**不受影响** —— 它的字段清单直接取 `findFormDrivingColumns`（这条路由自己给的），没走 `getConfig`。所以 `wf-form read` 读不出来的表单，`wf-form formula-linkage columns` 照样能列出字段。
+## 常见报错
+| 报错 | 原因 | 怎么办 |
+|---|---|---|
+| 系统模块字段「X」不能作为赋值目标 | `--target` 写了模块字段 | 换成业务字段；模块字段只能出现在公式右边 |
+| 「X」在…上匹配到 N 个字段 | 字段名有歧义 | 用字段 id（`form formula-linkage columns` 里）
+| 表达式里写的是一个赋值式，它的左侧是「A」，与 --target「B」不一致 | 粘贴的赋值式目标与 `--target` 不符 | 改 `--target`，或只给右侧函数体 |
+| 事件「载入时」是表单级/流程级的，不需要触发字段，--trigger 已忽略 | 表单级 / 流程级事件给了触发字段 | 无害提示；去掉字段即可 |
+| 事件「值改变时」需要指定触发字段 | 字段级事件没给触发字段 | 补 `--trigger`，或写成 `--event changeField:<字段,字段>` |
+| 未知事件「EVENT_FORWARD」，可用: …（只列 10 个） | 想在 eb 表上用流程级事件，但没换维度 | 加 `--effect workFlow --workflow-id <流程id>` 再试 |
+| 生效维度在「当前表单/表单布局」与「当前工作流/选择节点」之间切换时，必须同时用 --event 指定… | `update` 换了维度却沿用旧事件 | 一起给 `--event`（新的维度下可用的事件） |
+| 平台回读的表达式与提交不一致 | 归一化猜错了写法 | 以平台为准；把 `read` 的结果记下来反馈 |