weaver-e10-builder 1.2.3 → 1.5.1

package/skill-docs/references/form/guide-field-linkage.md

@@ -17,6 +17,8 @@
 | 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表多跳，ESB 动作流） |
 | 关系 | — | — | **字段联动是关联表带出的进阶版** |
 
+> 本文讲的是**跨表**带出。本表字段之间用公式互相计算赋值的是**函数联动**（eb 表 `form formula-linkage`、流程表单 `wf-form formula-linkage`），见 `guide-formula-linkage.md` —— 两者 `linkageType` 不同（`excel` vs `template`），`form field-linkage list/delete` 看不到也删不掉函数联动。
+
 ## 何时用多跳
 
 **Text 字段赋值必须用名称（多跳），不能直接赋 ID。**

package/skill-docs/references/form/guide-form-formula-functions.md

@@ -14,6 +14,42 @@
 > **纯常量公式**（不含任何字段引用）平台允许，会带一条提示正常保存。
 > 完整原始数据含参数说明/示例结果：`senba6/公式表.json`。
 
+## ⚠️ 写公式前先记住这几条
+
+这四条是**平台侧的语言规则**，写错**不报错**，只是算不对或整段失效 —— 出问题很难往回找。
+
+**1. 函数名称必须大写。** `CONCAT(...)` / `VALUE(...)` / `IF(...)` / `SUM(...)`，小写平台不认。
+> **例外：自定义 JS 脚本函数保持原样大小写** —— `default()`、`replaceAll()`、`countRelate()`、`getAddHrmIds()` 这些（见「自定义JS脚本函数」一类）是用户脚本注册的，名字怎么写就怎么用，**别跟着一起改成大写**。
+
+**2. 逻辑比较用 `==`（两个等号），不是 `=`（一个等号）。**
+
+```
+✅ IF({主表.状态}=="已完成", 1, 0)
+❌ IF({主表.状态}="已完成", 1, 0)      ← 单个等号是赋值语义，不是比较
+```
+
+**3. 给字段赋值用 `=`（一个等号），它只出现在整条公式的最左边。**
+
+```
+{主表.销售金额}=VALUE({主表.数量})*VALUE({主表.单价})
+└──── 赋值，一个等号 ────┘└──── 函数体内部，比较用两个等号 ────┘
+```
+
+顶层那个 `=` 与函数体里的 `==` 是**两个层次**的东西，别因为看见 `=` 就写成 `==`，也别在函数体里把比较写成 `=`。函数联动的赋值式与 CLI 的关系见 `guide-formula-linkage.md`。
+
+**4. 跨表复制粘贴公式，必须把非本表的字段变量换掉。** 从别的表单复制来的公式里，`{主表.X}` / `{明细表.X}` 指的是**原来那张表**的字段。粘到当前表必须逐个替换成本表字段 —— 平台按名字找字段，找不到、或者找到同名但语义不同的字段，**都不会拦住你**，只会静默算出不对的结果。
+
+**5. 选项型控件（Select / RadioBox / CheckBox）要比的值，得引用「选项本身」，不能拿字符串比。**
+
+```
+✅ IF({主表.性别}=={主表.性别.男}, 65, 60)     ← 三段式：表.字段.选项
+❌ IF({主表.性别}=='男', 65, 60)               ← 恒不成立
+```
+
+选项在库里存的是 **valueKey**（一串 id），不是选项名，所以拿 `'男'` 去比**永远不相等**；而平台**照收、不报错、回 200** —— 写完看着全绿，结果永远不对，是最难查的一类错。`e10-cli` 解析到「选项型字段 与字符串字面量 做 `==`/`!=`」会**出声警告**并给出正确写法，但**不会替你改**（表达式合不合法最终由平台定）。
+
+⚠ 选项引用必须写**完整三段**。`[性别.男]` 只有两段，会被当成「明细表 `性别` 里的字段 `男`」—— 两段的方括号写法是既有的「明细表.字段名」，两者撞车，不给它开后门。
+
 ## 函数速查矩阵
 
 | 分类 | 函数（中文名） |

package/skill-docs/references/form/guide-form-layout-incremental.md

@@ -0,0 +1,75 @@
+# 给已有表单改布局
+
+给已经建好的表单加字段、改字段的显示属性时读这篇。**不是自己建的表尤其要读**：改错了别人的版式，对方要一个个调回来。
+
+## 布局是两套数据
+
+| | 存在哪 | 一条是什么 |
+|---|---|---|
+| **字段定义** | 字段管理接口 | 一个字段一条（`fieldId` / `type` / `componentKey` / `title` / `dataKey` / `columnName` …） |
+| **布局组件** | 表单布局接口的 `pageLayouts[].comps` | **平铺一维数组**，每个字段占**两个**：一个标签组件、一个值组件 |
+
+**判断「这个组件属于哪个字段」只能看 `config.associatedId`。**
+标签组件的 `config.fieldId` 是布局自己另生成的一个 id，与字段定义没有对应关系 —— 拿它去找字段会找不到。
+
+明细字段也在同一个平铺数组里，靠 `config.subFormId` 归属；它的 `excel.parent` 指向明细表容器的 `nodeId`，普通字段的 `excel.parent` 是 `ROOT`。
+
+## 字段属性分两类
+
+有些属性**只存在于布局组件里，字段定义没有这个键** —— 只写字段定义等于什么都没做：接口回成功、命令也报成功，表单上一点变化都没有。
+
+| 只存在于布局组件 | 字段定义里也有 |
+|---|---|
+| `required`（必填）、`readOnly`、`singleRow`（独占一行）、`display`、`isHideTitle`、`excel`（位置）、`layout` | `title`、`dataKey`、`columnName`、`maxLen`、`componentKey`、`type`、`format` … |
+
+必填是个典型：一张真实表 53 条字段记录里，**没有一条**带 `required`。设必填就是改布局组件。
+
+## 加字段：默认增量，别动不动重建
+
+`e10-cli form add-field` 默认**只往布局里加这一个字段**，不动其它组件、不动样式模板、不动位置。
+
+`--reinit` 才是整表重建，它会：
+
+- 把样式模板换成工具默认的那一个；
+- 按字段顺序**重算所有位置**（手工调过的行列全没了）；
+- 把标签组件**全部换成新 id**；
+- 布局层的自定义（合并格、列宽、配色）一并丢失。
+
+**不是自己建的表不要用 `--reinit`。** 字段越多越经不起 —— 真实的一张订单主表有 131 个组件。
+
+### 什么时候加字段会中止
+
+布局里**没有同类型的字段可参照**时，命令会中止并说明。
+
+这是设计如此，不是缺陷：新组件的键集（`format`、`earlyDate`、`pointSize`、`showDimension` …）各类型都不一样，只能从同类型的现成组件整套抄过来；按类型名拼一个出来，**猜错不报错、只是渲染异常**。
+
+遇到中止时，两个选择：
+
+1. 先在设计器里手工加一个同类型字段（它就成了可参照的样板），再重跑命令；
+2. 确认这张表是自己建的、不在乎版式被重排 → 显式加 `--reinit`。
+
+## 哪些 id 可以自己生成，哪些必须由平台发号
+
+这一条最容易踩：**编一个 id 不会报错**，而是在之后某个看不出来的环节静默失效。
+
+| 位置 | 能否自己生成 | 说明 |
+|---|---|---|
+| 布局组件的 `id` | ✅ | 布局内唯一即可，形如 32 位十六进制串 |
+| 布局组件的 `excel.nodeId` | ✅ | 布局内唯一即可，短随机串 |
+| 标签组件的 `config.fieldId` | ✅ | 只在布局内有意义，与字段定义无关 |
+| **`labelObj.title` / `titleLabelId`** | ❌ **必须平台发号** | 见下 |
+
+### 为什么标题的 id 必须平台发号
+
+平台把**字段标题存的是标签 id，不是文本本身**。这个 id 要调多语言标签接口（`i18n/multilangLabel/saveLabel`）由平台分配。
+
+自己拼一个（比如拿时间戳凑）的后果：接口**照样回成功**，之后任何要显示这个标题的地方都取不到文字 —— 字段名变成空的，看着就像这个字段不存在。
+
+判断一个标签 id 是否有效：用 `-1` 去查标签，拿到的是一行空值（模板行）。**查一个不存在的标签，返回的结果与查 `-1` 完全一致** —— 所以「查得回来」不等于「标签存在」，要看有没有值。
+
+现成命令：`e10-cli form field-lang set <objId> <appId> <fieldId> --zh <中文> --en <英文>` 会建标签并回写字段，写完还能回读校验。`form add-field` 建字段时也会自动建标签。
+
+## 相关
+
+- 建表时的布局规划见 [EB 表单布局规划](guide-form-layout-planning.md)。
+- 字段类型与属性码表见 [表单字段定义参考](ref-form-fields.md)。

package/skill-docs/references/form/guide-form-layout-planning.md

@@ -62,7 +62,7 @@
 
 ```bash
 e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
-e10-cli form layout read <objId> <appId>
+e10-cli form layout read <objId>
 ```
 
 创建后需要调整局部位置或显示属性时，使用 `form layout` 下的移动、只读和必填设置命令；具体参数通过 `form layout --help` 查询。

package/skill-docs/references/form/guide-form-linkage.md

@@ -29,7 +29,8 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
           "fieldId": "目标字段ID",
           "name": "字段名称",
           "dataKey": "字段编码",
-          "fieldType": "Employee"
+          "fieldType": "Employee",
+          "isDetail": false
         }
       ]
     }
@@ -37,6 +38,30 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 }
 ```
 
+### actions[].fields[]（联动目标字段）
+
+| 键 | 说明 |
+|------|------|
+| fieldId | 目标字段的 fieldId（从 `form read --app-id` 获取） |
+| name | 字段名（显示用） |
+| dataKey | 字段编码；`form read` 不返回它，**留空即可**（用 fieldId 代替可行） |
+| fieldType | 字段类型，如 `Text` / `Employee` / `Date` |
+| **`isDetail`** | **目标落在明细表里时必须为 `true`**。不传 = 主表字段 |
+
+**目标字段在明细表里，就加 `"isDetail": true`** —— 这是「主表字段控制明细列显隐」的写法，两个方向都支持（实测 `hide` / `required` 均可）：
+
+```json
+{
+  "conditions": [{ "fieldId": "<主表字段ID>", "operator": "EQUAL", "value": "Y" }],
+  "actions": [{
+    "prop": "hide",
+    "fields": [{ "fieldId": "<明细列ID>", "name": "明细列A", "dataKey": "", "fieldType": "Text", "isDetail": true }]
+  }]
+}
+```
+
+**怎么认出明细字段**：`form read` 的输出里，明细字段会标注所属明细表 —— 带 `明细表: xxx` 那些就是，照它填 `isDetail: true`。
+
 ### conditions（触发条件）
 
 多个条件之间是 **AND** 关系（全部满足才触发）。
@@ -44,10 +69,68 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 | 字段 | 说明 |
 |------|------|
 | fieldId | 触发字段的 fieldId（从 `form read --app-id` 获取） |
-| operator | 比较符：`EQUAL`（等于）、`NOT_EQUAL`（不等于）、`CONTAIN`（包含）、`NOT_CONTAIN`（不包含） |
-| value | 普通字段的比较值（文本/数字） |
+| operator | 比较符，见下表 |
+| value | 普通字段的比较值（文本/数字）。**「为空 / 不为空」不要给** |
 | options | Select/RadioBox 字段的选项，格式：`[{"optionId": "选项ID", "content": "选项名"}]` |
 
+比较符：
+
+| 写法 | 含义 | 备注 |
+|------|------|------|
+| `EQUAL` / `NOT_EQUAL` | 等于 / 不等于 | |
+| `CONTAIN` / `NOT_CONTAIN` | 包含 / 不包含 | |
+| `GREATER` / `LESS` / `GREATER_EQUAL` / `LESS_EQUAL` | 大于 / 小于 / 大于等于 / 小于等于 | |
+| **`NULL`** | **为空** | 也可以写 `EMPTY` / `IS_NULL`，命令会归一成平台码 |
+| **`NOT_NULL`** | **不为空** | 也可以写 `NOT_EMPTY` / `IS_NOT_NULL` |
+
+**「为空」的算子写错，报错会指向完全无关的地方。** 平台不认 `EMPTY` 这类写法时不会说「算子不合法」，而是在写库时抛一句 `mybatis PersistenceException / Error updating database` —— 容易让人误判成字段配置问题（真实发生过：被当成「目标字段 `dataKey` 为空导致 NOT NULL」去查，而 `dataKey` 留空本身是没问题的）。用 `NULL` / `NOT_NULL`，或者写 `EMPTY` 交给命令归一。
+
+### 多个条件之间：任一 / 全部
+
+界面上的「满足以下**任一**条件」= `OR`，「满足以下**全部**条件」= `AND`。在 config 顶层写 `detailType`：
+
+```json
+{ "detailType": "OR", "conditions": [ ... ], "actions": [ ... ] }
+```
+
+**不写这个键时由平台取自己的默认值** —— 设计器每次都显式发，所以缺省行为没有依据，命令不替平台决定。多条件时建议明确写。
+
+## 生效维度（生效范围）
+
+联动可以只对**某一种展示形态**生效。在 config 里用 `effect` 指定：
+
+| 写法 | 含义 |
+|------|------|
+| 不写 | **当前表单**（最常见） |
+| `"effect": "formLayout"` | 只对**某个表单布局**生效（布局 id 现查） |
+| `"effect": { ... }` | 直接给 `{effectType, effectName, effectValue}`，自行指定 |
+
+⚠ **布局维度的值要的是 `multipleLayoutId`，不是 `formLayout.id`** —— 同一张表上这两个值**相邻但不同**（实测某表是 `…375` 与 `…376`）。给错了命令**不报错**，只是指向另一个布局，而且平台按这个 id 解析不出名字，回读时生效范围是个空白（`表单布局: `）。命令取的是前者，不用手填。
+
+### 工作流表单那条路由的维度不一样
+
+上面的表是 **eb 表**（`form linkage add`）的。**原生工作流程表单**（`wf-form linkage`）提供的是另外四种，写法也不同：
+
+| 界面上的维度 | `effect` 写什么 | 取值 | 额外参数 |
+|---|---|---|---|
+| 当前表单 | 不写（缺省） | 表单 formId | — |
+| **表单布局** | `"formLayout"` | **布局 id**（默认布局；可用 `"layoutId"` 指定别的） | — |
+| **当前工作流** | `"workFlow"` | **流程 ID** | `--workflow-id` |
+| **选择节点** | `"includeNode"` | **节点 ID** | `--workflow-id` + `"nodeId"`（可写节点名） |
+
+```bash
+e10-cli wf-form linkage <formId> "规则名" --workflow-id <流程ID> --config @cfg.json
+```
+
+```json
+{ "effect": "workFlow",  "conditions": [ ... ], "actions": [ ... ] }
+{ "effect": "includeNode", "nodeId": "1级审批", "conditions": [ ... ], "actions": [ ... ] }
+```
+
+**这条路由的 `refId` 始终是流程 ID**，是「这条联动挂在哪个流程上」，**不是**选项的取值 —— 给「选择节点」时选项取值是节点 ID，两者不同，别照着取值抄。流程表单 formId 与流程 ID 不是一回事，用 `workflow info <流程ID>` 可以反查。
+
+选项的显示名里那个 `【V1】` 是**平台按活动版本自己加的**，写节点名进去它会补成「节点名【V1】」。
+
 ### actions（联动效果）
 
 | 属性 | prop 值 | 效果 |
@@ -121,12 +204,13 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 
 ## 注意事项
 
-1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段；明细表触发字段只能修改本行字段
+1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段；明细表触发字段只能修改本行字段。
+   目标落在明细表里时，`actions[].fields[]` 那个条目**必须带 `isDetail: true`**；不带的话这个目标会被当作主表字段提交
 2. **表格布局限制**：通过隐藏行/列/单元格自定义属性隐藏的字段，无法通过联动显示出来
 3. **明细表字段列隐藏**：需在明细表第一行配置操作按钮元素
 4. **多规则冲突**：避免同一个触发字段或同一个目标字段出现在多个规则里
 5. **默认属性**：字段的默认显示属性为设计器中设置的"读写属性"或"字段权限"
-6. **目标字段 dataKey**：config 里目标字段需要 `dataKey`，但 `form read` 不返回这个字段——用 `fieldId` 代替可行（`dataKey` 留空或用 `fieldId` 均可）
+6. **目标字段 dataKey**：`form read` 不返回它，**留空即可** —— 平台按 `fieldId` 定位，`dataKey` 空着能正常建规则（已对照验证）。填上真值也行，但别为了凑它去猜；它**不是**某些报错的原因。
 7. **Select 选项 ID**：必须用 `form read --app-id` 返回的真实 `valueKey`（自动生成的长 ID，如 `1294601918674214939`），不能用建表单时给的短 `valueKey`（如 `"GQ"` / `"5"`）
 
 ---

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

@@ -0,0 +1,250 @@
+# 函数联动（本表字段间的公式赋值）指南
+
+## 概述
+
+函数联动：在**本表单内部**，当某个字段变化（或表单载入）时，用一张**公式**算出结果，赋值给本表的另一个字段。
+
+例：`数量` 或 `单价` 变化时 → `销售金额 = 数量 × 单价`。
+
+设计器里的位置是字段属性面板的「函数联动」，要配四件事：**在哪生效**（当前表单 / 某个布局）、**什么时候触发**（事件）、**谁触发**（触发字段）、**赋值给谁 + 怎么算**（目标字段 + 函数体）。
+
+> **不跨表。** 要查另一张表把值带回来，那是 `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 delete <appId> <objId> <linkageId...>
+```
+
+### add 的参数
+
+| 参数 | 说明 |
+|---|---|
+| `--target <字段>` | **赋值目标**，被写入的字段。只能是业务字段 |
+| `--expression <函数体>` | 公式右侧。含引号/换行时可用 `@文件路径` |
+| `--event <事件>` | 触发事件，默认 `changeField`（值改变时）。可传 `type` 或中文名 |
+| `--trigger <字段...>` | 触发字段，可多个。字段级事件必填；表单级事件（如「载入时」）不用给 |
+| `--effect <维度>` | 生效维度：`form`（默认，当前表单）/ `formLayout`（表单布局） |
+| `--name <名>` | 联动名。默认 `<公式名> - 公式_<时间戳>` |
+| `--formula-name <名>` | 公式名，默认取表单名 |
+| `--formula-id <id>` | 复用/更新已有公式，不新建 |
+
+### 生效维度（`--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` | 不要 |
+
+## 示例
+
+### 金额 = 数量 × 单价（两个触发字段）
+
+```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. **一个触发字段一条触发动作**。`--trigger` 传多个时，平台侧是 N 条动作记录，不是一条里挂 N 个字段 —— CLI 已按这个形状下发。
+3. **触发字段与目标不能搞反**。`--trigger` 是「谁变了」，`--target` 是「谁被写」。写反了规则会反向生效，回读时表达式左边能看到真实目标。
+4. **字段名有歧义会报错**，不会默认取第一条。两张明细表里各有一个「编号」时，写 `编号` 会列出两个候选，改用字段 id 或 `明细表名.编号`。
+5. **业务字段与模块字段同名时**（如业务字段叫「标题」、模块字段 `name` 的标签也叫「标题」），按裸标签写会报歧义，用字段 id 或完整列名 `主表.标题` 区分。
+6. **生效范围两种**：缺省「当前表单」（所有布局 + 所有关联该表单的工作流），`--effect formLayout` 则只对某个布局生效。布局 id 由 CLI 现查（见上「生效维度」）。`update` 不传 `--effect` 会沿用现有维度。
+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 条。
+
+## 流程表单上的函数联动（`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） | **17 个**（多一组「流程」事件） |
+| 生效维度 | 当前表单 / 表单布局 | 当前表单 / 表单布局 / **当前工作流 / 选择节点** |
+
+### 多出来的「流程」触发事件
+
+除了字段组的 5 个与表单组的 5 个，流程表单还多 7 个流程级事件（都不需要 `--trigger`）：
+
+```
+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活动版本号】`，版本号取活动版本 —— 与设计器发出的形状一致。
+
+### 系统字段里有两个**可以**当赋值目标
+
+流程表单的模块字段桶有 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`（CLI 会忽略并提示） |
+| 事件「值改变时」需要指定触发字段 | 字段级事件没给 `--trigger` | 补 `--trigger` |
+| 平台回读的表达式与提交不一致 | 归一化猜错了写法 | 以平台为准；把 `read` 的结果记下来反馈 |

package/skill-docs/references/form/ref-form-fields.md

@@ -8,6 +8,8 @@
 {
   "componentKey": "Text",
   "fieldName": "项目名称",
+  "dataKey": "xmmc",
+  "columnName": "xmmc",
   "required": true,
   "readOnly": false,
   "hidden": false,
@@ -21,6 +23,7 @@
 | --- | --- |
 | `componentKey` | 字段类型标识 |
 | `fieldName` | 字段名称 |
+| `dataKey` / `columnName` | 字段编码 / 数据库列名。**两者是两个独立的东西**，可分别指定；都不写则同为字段名拼音首字母，只写 `dataKey` 时列名跟随。建后由 `add-field --data-key/--column-name`、`edit-field --column-name` 调整 |
 | `required` / `readOnly` / `hidden` | 必填、只读、隐藏 |
 | `singleRow` | 独占一行 |
 | `group` | 所属分组 |
@@ -73,8 +76,11 @@
 | --- | --- | --- |
 | 人员选择 | `Employee` | `multiple` |
 | 部门选择 | `Department` | `multiple` |
+| 分部选择 | `SubCompany` | `multiple`（默认单选）；平台读回的组件名为 `Subcompany` |
 | 共享人 | `Sharer` | 共享范围设置 |
 
+创建“分部选择”字段使用原生组织类型 `SubCompany`，例如 `form add-field <objId> <appId> 所属分部 SubCompany`；多选时加 `--multiple`。它与“关联浏览”中选择分部数据源是两种字段配置。
+
 ### 关联类型
 
 以下为原生关联对象码表。需求明确指向这些业务对象时，直接使用对应类型。