weaver-e10-builder 1.5.12 → 1.5.13

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

@@ -2,27 +2,69 @@
 
 ## 概述
 
-字段联动（FormDataLinkage）：表单字段变化时，按条件查询**另一张表**，把查到的值**赋给本表字段**（主表或明细表）。
+本指南汇总字段值的带出与赋值：关联 EBuilder 字段直接带出、HRM 属性带出，以及跨表查询赋值（`FormDataLinkage`）。先按来源选择配置方式，再看对应命令。
 
-背后是一条 ESB FieldLinkage 动作流（触发 + EnquiryForm 查询 + Output 赋值），CLI 自动完成建 ESB app + saveDesign + 绑定联动记录。
+其中 `FormDataLinkage` 可按触发字段值查询另一张表，把结果赋给本表主表或明细字段；背后由 ESB FieldLinkage 动作流执行，CLI 自动完成创建和绑定。支持两种方式：快捷配置（`--condition` / `--assign`，任意条件、多查询字段与多赋值）和旧单跳/多跳（`--source-form` / `--query-field` / `--hops`，固定按数据 ID 过滤）。
 
-支持两种配置方式：
+## 选择带出方式
 
-- **快捷配置**（`--condition` / `--assign`）：任意条件 + 多查询字段 + 多赋值，对应设计器里的「快捷配置」页
-- **旧单跳/多跳**（`--source-form` / `--query-field` / `--hops`）：固定按「数据ID = 触发字段值」过滤，多跳用于把 ID 换成名称
-
-## 三种联动对比
+| 需求 | 配置方式 | 命令或入口 |
+|---|---|---|
+| 关联 EBuilder 记录后直接复制该记录的一个字段 | 字段级 `ffRelateField` | 建表时 `relateFrom`；建表后 `form edit-field --relate-from` |
+| 人员或部门字段变化后带出 HRM 属性 | 字段级 `ffRelateField` | `form relate` |
+| 按条件查询另一张表，单跳或多跳赋值 | `FormDataLinkage`，由 ESB 动作流实现 | `form field-linkage`（快捷配置或旧单跳/多跳） |
 
-| | 属性联动（显隐） | 关联表带出（form relate） | **字段联动（field-linkage）** |
-|---|---|---|---|
-| 命令 | `form linkage add` | `form relate` | `form field-linkage add` |
-| 接口 | viewlinkage | ffRelateField module:hrm | saveFormDataLinkage + saveDesign（ESB） |
-| 作用 | 改字段显示属性（hide/show/required） | 换 Employee/Department→带 HRM 属性 | **查任意表→带出任意字段赋值** |
-| 源 | 表单字段值条件 | Employee/Department（HRM 源） | 任意字段→任意表查询 |
-| 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表，ESB 动作流） |
+这些都改变字段**值**。按条件改变隐藏、只读、必填等**显示属性**，使用 `form linkage`，见 [显示属性联动指南](guide-form-linkage.md)。
 
 > 本文讲的是**跨表**带出。本表字段之间用公式互相计算赋值的是**函数联动**（eb 表 `form formula-linkage`、流程表单 `wf-form formula-linkage`），见 `guide-formula-linkage.md` —— 两者 `linkageType` 不同（`excel` vs `template`），`form field-linkage list/delete` 看不到也删不掉函数联动。
 
+## 关联 EBuilder 字段直接带出（`ffRelateField`）
+
+当 EBuilder 关联字段选中某条记录后，自动将该记录的一个字段值复制到当前字段。例如：选客户后带出联系人；选合同后带出合同金额。
+
+### 建表时配置
+
+`form create --fields` 里用 `relateFrom` 定义，CLI 在创建字段后配置 `ffRelateField`：
+
+```json
+{ "componentKey": "Text", "fieldName": "联系人",
+  "relateFrom": { "ebuilderField": "关联客户", "sourceFieldId": "1296220571782152194" } }
+```
+
+### 建表后补配
+
+```bash
+e10-cli form edit-field <objId> <appId> <fieldId> \
+  --relate-from <EBuilder字段名> \
+  --relate-from-source <目标表单源字段fieldId>
+```
+
+`sourceFieldId` 和 `--relate-from-source` 必须是关联目标表单中源字段的数字 `fieldId`，不能写字段名。先用 `form read <目标表objId> --app-id <appId>` 查实际 ID。`--relate-from` 是本表单中的 EBuilder 关联字段名。
+
+## HRM 属性带出（`form relate`）
+
+本表单的人员或部门字段变化后，自动向目标字段填入 HRM 属性。源字段必须是 Employee 或 Department 类型。Employee 源的 `ffRelateField` 带 `module:"hrm"`，Department 源不带。
+
+```bash
+# 申请人（Employee）变化 → 向申请人工号填入邮箱
+e10-cli form relate <appId> <objId> 申请人工号 --from 申请人 --key email
+
+# 所属部门（Department）变化 → 向申请人工号填入部门编号
+e10-cli form relate <appId> <objId> 申请人工号 --from 所属部门 --key code
+```
+
+| 参数 | 说明 |
+|---|---|
+| `<targetField>` | 被填充的目标字段，名称或 `fieldId` |
+| `--from <field>` | 表单中的源字段，必须是 Employee 或 Department 类型 |
+| `--key <key>` | 带出的 HRM 属性；默认 Employee=`department`、Department=`name`；不传 `--title` 时自动取属性中文名 |
+
+`--key` 从平台 `listBusinessField` 清单校验。Employee 属性包括 `username` 姓名、`email` 邮箱、`superior` 上级、`mobile` 手机、`jobNum` 工号、`hiredate` 入职时间、`department` 部门、`position` 岗位、`grade` 职级、`allSuperiors` 所有上级等。Department 属性包括 `name` 部门名称、`code` 部门编号、`parent` 上级部门、`fullname` 部门全称、`department.coadjutant` 协办人、`deptEmployee` 部门人员。
+
+目标字段类型与带出属性不匹配时，命令只提示警告、不阻止；例如 `deptEmployee` 通常应填入 Employee 字段。
+
+## 跨表查询赋值（`FormDataLinkage`）
+
 ## CLI 命令
 
 ```bash