weaver-e10-builder 1.2.5 → 1.5.2

package/skill-docs/references/form/guide-form-physical-table.md

@@ -0,0 +1,146 @@
+# 多物理表（一个表单的字段分散到多张物理表）
+
+设计器里「表单 → 字段管理」有三个页签：**主表 | 明细表 | 其他**。本文说的是**「其他」** —— 同一个表单的字段分散在多张**物理表**上。
+
+## 什么时候用
+
+**字段数过多时的容量兜底**（单表字段超过 100 个左右）。正常表单用不到，属于偶尔一用的结构级能力。业务上要「一行对多行」请用**明细表**，那是另一回事（见 `guide-form-sub-detail.md`）。
+
+## ⚠ 和「明细表」是两根轴，别混
+
+| | 明细表 | **物理表（本文）** |
+|---|---|---|
+| 建表命令 | `form add-detail-table` | **`form add-physical-table`** |
+| 加字段命令 | `form add-field --sub-form-id` | **`form add-physical-field`** |
+| 建表端点 | `saveSubForm` | **`saveFormTable`** |
+| 标志 | `isSubForm: true` | **`isSubForm: false`** |
+| `tableType` | `MAIN` | **`SUBSIDIARY`** |
+| 布局里 | `DetailTable` 组件 | 无（不自动进布局，见下） |
+| 语义 | 一对多业务建模 | 一个表单自己的字段拆到多张表 |
+
+## 命令
+
+```shell
+# 1) 列出表单的全部物理表（含主表）—— 忘掉 formTableId 时就用它
+e10-cli form physical-table list <objId> <appId>
+
+# 2) 建一张附属物理表 —— 输出 formTableId，后面都要用它
+e10-cli form add-physical-table <objId> <appId> \
+  --name 物理表A \
+  --table-name uf_ryxxb_6_1
+
+# 3) 往那张表里加字段（任意类型，能力同 form add-field）
+e10-cli form add-physical-field <objId> <appId> <formTableId> <字段名> <类型> [标题] [选项]
+
+# 4) 改名
+e10-cli form rename-physical-table <objId> <appId> <formTableId> \
+  --name 新名字 --table-name uf_ryxxb_6_1
+
+# 5) 删除（可一次删多张；表里的字段一并删除，不可逆）
+e10-cli form delete-physical-table <objId> <appId> <formTableId...>
+```
+
+`add-physical-field` 的选项与 `form add-field` 同名同义（`--precision` / `--format` / `--default` / `--data-key` / `--column-name` / `--multiple` / `--option-template` / `--browser-type` / `--sform-id` …）—— 两者**共用同一份字段构造器**，所以字段形状是同一套，不存在「这个命令能建那个命令不能建」的差异。
+
+| 参数 | 说明 |
+|---|---|
+| `--name <名>` | 物理表**显示名**，设计器里那排 chip 上的字 |
+| `--table-name <名>` | **数据库表名**（如 `uf_ryxxb_6_1`）。⚠ 平台的建议命名规则未抓到报文，**必填**；改名时也要原样回传 |
+
+## 表 id 从哪来
+
+建表输出里就带着：
+
+```
+物理表已建: 物理表A  formTableId=1323895867900731392  tableName=uf_ryxxb_6_1
+```
+
+事后想找回，用 `form physical-table list`（走 `getFormAGroupList`，就是设计器那排 chip 的数据源）：
+
+```
+$ e10-cli form physical-table list 1323898521989193728 1323897873591762945
+表单 1323898521989193728 共 3 张物理表:
+  多物理表测试表单  [主表]  formTableId=1323898521989193731  库表=uf_dwlbcsbd_5766  字段2
+  表1  [附属]  formTableId=1323898595055067136  库表=uf_dwlbcs_t1  字段3
+  表2  [附属]  formTableId=1323898612300947456  库表=uf_dwlbcs_t2  字段3
+```
+
+⚠ 注意这只列**物理表**。`form detail-table list`（走 `querySubForms`）是另一回事，只列**明细表**。
+
+字段**归属**也随时可读：`form read <objId> --app-id <appId>` 每个字段后面会带 `· 物理表: 表1`。
+
+> 读 `getFormAGroupList` 时别碰那条记录里的 `id` 键 —— 它是 **formId**，`formTableId` 才是表 id。这个子系统里 `id` 反复是这个陷阱。
+
+## ⚠ `add-physical-field` **不碰布局**
+
+字段建在这张物理表上，但**不会自动进表单布局**——它是否需要在布局里出现、怎么放，尚未抓到报文。别默认它已经挂在表单上了；要不要进布局请在设计器里确认。
+
+（`form add-field` 会做布局插入，是因为它落在主表/明细表这些**本来就在布局里**的落点上。）
+
+## 报文契约
+
+### 建表 / 改名 —— 同一个端点，带不带 `id` 决定是哪种
+
+```
+POST /api/ebuilder/form/form/field/manage/saveFormTable?apid=<appId>
+header ebbusinessid: <formId>
+```
+
+```json
+{"module":"ebuilderform",
+ "formTable":{"id":"<表id：改名时带，新建时不带>",
+              "name":"物理表A",
+              "tableName":"uf_ryxxb_6_1",
+              "tableType":"SUBSIDIARY",
+              "form":{"id":"<formId>"},
+              "otherProperties":"{}"},
+ "customParam":{"appId":"...","objId":"..."}}
+```
+
+响应：`{"code":200,"status":true,"data":{"formTableId":"..."}}` —— 新表的 id 在 `data.formTableId`。
+
+### 加字段 —— **不是**批量端点
+
+```
+POST /api/ebuilder/form/form/field/manage/saveFormFieldNew
+body {"formId":...,"module":"ebuilderform","jsonObj":"{... 带 \"formTableId\":\"<表id>\" ...}"}
+```
+
+字段落点由 **jsonObj 里的 `formTableId`** 决定。这条与「建表时连字段一起建」的 `batch/save/formField` + `formTableList` **不是同一条路**。
+
+### 删表
+
+```
+POST /api/ebuilder/form/form/field/manage/deleteFormTable?apid=<appId>
+body {"module":"ebuilderform","formId":"<formId>","ids":["<表id>"],"customParam":{...}}
+```
+
+### 列表（`form physical-table list`）
+
+```
+POST /api/ebuilder/form/form/field/manage/getFormAGroupList?apid=<appId>
+body {"module":"ebuilderform","formId":"<formId>","customParam":{...}}
+```
+
+响应 `data.formList[]` 每条：`name`（显示名）/ `tableName` / `tableType`（`MAIN` | `SUBSIDIARY`）/ `formTableId` / `systemTable` / `dataCount`；
+另外 `data.groupList[]` 是字段分组。**主表也在 `formList` 里**（`tableType: MAIN`）。
+
+⚠ 记录里的 `id` 键是 **formId**，不是表 id。
+
+## 踩过的两条坑（都别再走）
+
+**1. 不能把已有字段搬到另一张表。** 试过把字段的 `formTableId` 改成新表再整份写回，平台明确拒绝：
+
+```
+【备注】此字段不属于当前物理表，不能更改位置
+```
+
+所以**别指望「字段超 100 之后把老字段挪走」**——至少这条路径不行。能做的只有：**一开始就把新字段建到新表上**。这也解释了设计器的真实用法：先建附属表，后续新增的字段直接落在它上面。
+
+**2. 平台会对形状不认的字段回 `200` 但静默不落库。** 在 `batch/save/formField` 那条路上，`DateTime` / `Percent` / `Attachment` / `Browser` 四种就是这样——接口回成功，字段根本没建出来。所以 `add-physical-field` **每次写完都回读确认**，「接口回 200」不等于「建上了」。带配置的类型（如 Select 的选项）建完再用对应命令补。
+
+## 注意事项
+
+1. **删除不可逆**，表里的字段一并删除。执行前先确认表 id。
+2. **`--table-name` 必填**。设计器用的是 `uf_<表单名拼音>_<n>_<m>` 这类命名，但规则没抓到报文，CLI 不替你猜 —— 重名/非法由平台报错（`此表的数据库表名称与数据库现有表存在冲突`）。
+3. **建完的空表照样存在**于「其他」页签里；要清掉用 `delete-physical-table`。

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`。它与“关联浏览”中选择分部数据源是两种字段配置。
+
 ### 关联类型
 
 以下为原生关联对象码表。需求明确指向这些业务对象时，直接使用对应类型。

package/skill-docs/references/hrm/guide-matrix.md

@@ -1,4 +1,4 @@
-# HRM 条件矩阵指南
+# HRM 矩阵指南（条件矩阵 / 部门矩阵 / 分部矩阵）
 
 > 矩阵 = 「条件维度（行）→ 值维度（列）」的映射查询表。例如：部门 + 费用类型 → 审批人。用于流程中的矩阵对应操作者类型。
 
@@ -10,9 +10,9 @@
 |------|------|
 | `e10-cli matrix create <name>` | 新建矩阵。`--type 0=分部/1=部门/2=自定义` `--desc` `--org-id` |
 | `e10-cli matrix update <id>` | 更新矩阵。`--name` `--desc` `--type` |
-| `e10-cli matrix list` | 查询矩阵列表。`--name` `--enable-status` `--org-id` |
+| `e10-cli matrix list` | 查询矩阵列表。`--name` `--enable-status` `--org-id`。非 JSON 输出会标出「行随组织同步 / 行手工维护」「字段只读」 |
 | `e10-cli matrix config <id>` | 查看矩阵配置（条件字段 + 值字段） |
-| `e10-cli matrix config-edit <id>` | 编辑配置。`--condition` `--value` 或 `--config` 一次性提交 |
+| `e10-cli matrix config-edit <id>` | 编辑配置。`--value`（配合可选 `--condition`）或 `--config` 一次性提交。**`--condition` 可省略**，省略则沿用现有条件列 |
 | `e10-cli matrix enable <id>` | 启用矩阵 |
 | `e10-cli matrix disable <id>` | 停用矩阵 |
 | `e10-cli matrix delete <ids...>` | 删除矩阵。**矩阵里有数据行时平台会拒绝删除**（报"存在不能删除的矩阵"且不指出是哪个）——先 `matrix data delete <id> <rowIds...>` 清空数据行再删；批量删除时只要有**一条**不可删，整批都失败 |
@@ -22,7 +22,7 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli matrix data list <matrixId>` | 分页查询矩阵数据行。`--condition` `--value` 过滤 |
-| `e10-cli matrix data save <matrixId> --rows @file` | 保存数据行（新增/修改）。简写: `[{"字段configId":["实体ID"]}]` |
+| `e10-cli matrix data save <matrixId> --rows @file` | 保存数据行（新增/修改）。简写: `[{rowId?, "字段configId":["实体ID"]}]` —— 带 `rowId` 为改该行，不带为新增 |
 | `e10-cli matrix data delete <matrixId> <ids...>` | 删除数据行 |
 | `e10-cli matrix data template <matrixId>` | 下载导入模板（Excel） |
 | `e10-cli matrix data import <matrixId> <file>` | 从 Excel 导入。`--mode add/cover` |
@@ -59,22 +59,75 @@ e10-cli workflow set-operator <wf> <nodeId> --type matrix \
   --matrix-rule "<条件configId>:1:1:1"
 ```
 
+部门矩阵少一步 —— 条件列是平台建矩阵时自动给的，只配值列：
+
+```bash
+# 1. 建（--sync-depart = 界面上那个「从组织架构中同步部门」；行随组织同步，不可增删）
+e10-cli matrix create "部门负责人" --type 1 --sync-depart --desc "部门→负责人"
+
+# 2. 只配值列，--condition 省略（CLI 会沿用平台建好的「部门」条件列）
+e10-cli matrix config-edit <matrixId> \
+  --value '[{"type":"resource","name":"部门负责人","singleType":0}]'
+
+# 3. 看行 —— 同步型矩阵的行是组织架构带来的，行 id 就是部门 id
+e10-cli matrix data list <matrixId>
+
+# 4. 给某一行填值（带 rowId 才是改那一行，不带就是新增一行）
+echo '[{"rowId":"<部门id>","<值configId>":["<人员ID>"]}]' > rows.json
+e10-cli matrix data save <matrixId> --rows @rows.json
+```
+
 ---
 
-## 系统矩阵 vs 自定义矩阵
+## 行从哪来、字段能不能改：看 `syncType` 和 `permList`
 
-`matrix list --json` 每条记录带三个标记位，决定这个矩阵能改什么：
+`matrix list --json` 每条记录带几个标记位。**不要拿 `sysType` 当判据** —— 它只说明是不是平台内置的，不决定能力：
 
 | 字段 | 取值 | 含义 |
 |---|---|---|
 | `type` | `0` / `1` / `2` | `0`=分部矩阵、`1`=部门矩阵、`2`=自定义矩阵 |
-| `sysType` | `1` / `0` | `1`=系统矩阵（平台内置的组织维度矩阵），`0`=非系统 |
-| `syncType` | `1` / `0` | `1`=数据行随系统组织同步，`0`=手工维护 |
+| `syncType` | `1` / `0` | **行从哪来**。`1`=数据行随组织架构同步（**行不可增删，行 id 就是部门/分部 id**）；`0`=行手工维护（行 id 是平台发号的雪花） |
+| `permList` | 数组 | **含 `FIELD` 才能改字段配置**；不含就是字段只读（平台内置矩阵是这种） |
+| `sysType` | `1` / `0` | 是否平台内置。只影响名字语义，**不影响能做什么** |
+
+`matrix list` 的非 JSON 输出会直接把这两条标出来：`行随组织同步 / 行手工维护`、`字段只读`。
 
-- **系统矩阵**（`sysType=1`，即 type 0/1 的分部/部门矩阵）：条件列由平台内置的组织维度决定（分部 / 部门），建好后不自行增删条件列；`syncType=1` 时数据行随系统组织同步，不需要 `matrix data save` 手工填（典型：`部门矩阵` —— 条件列=部门、值列为空、描述"同步系统部门信息"）。
-- **自定义矩阵**（`sysType=0`，`type=2`）：条件列与值列都自由配置，数据行手工维护，可带 `belongOrgId` 归属机构。
+同一租户里四个矩阵的对照，四个象限都出现过：
+
+| 矩阵 | type | sysType | syncType | permList 有 `FIELD` | 结果 |
+|---|---|---|---|---|---|
+| 平台内置的部门矩阵 | 1 | 1 | 1 | 否 | 行随组织同步、字段只读 |
+| 部门负责人矩阵 | 1 | 0 | 0 | 是 | 行手工维护、字段可改 |
+| 自建并勾了「同步部门」 | 1 | 0 | 1 | 是 | 行随组织同步、字段可改 |
+| 自建未勾同步 | 1 | 0 | 0 | 是 | 行手工维护、字段可改 |
+
+> **`type` 与 `syncType` 互相独立**：`type=1` 的部门矩阵既可以是同步的、也可以是手工维护的；创建时用 `--sync-depart` / `--sync-subcompany` 决定，事后也能用 `matrix update --sync-depart` 改。
+>
+> 不管哪种，**在流程里的用法完全一样**（都是 `workflow set-operator --type matrix`）。
 
-> 两者**在流程里的用法完全一样**（都是 `workflow set-operator --type matrix`），差别只在"条件列从哪来 / 数据谁来填"。
+## 部门矩阵 / 分部矩阵：条件列是平台给的
+
+建部门矩阵（`matrix create <name> --type 1 --sync-depart`）时，平台会**自动把条件列建好**：
+
+```json
+"conditionConfigList": [
+  { "id": "<矩阵id + 1>", "name": "部门", "type": "department", "singleType": 1 }
+],
+"valueConfigList": []          ← 这才是你要配的
+```
+
+所以配列时**只给值列就行**，`--condition` 省略掉：
+
+```bash
+e10-cli matrix config-edit <matrixId> \
+  --value '[{"type":"resource","name":"部门负责人","singleType":0}]'
+```
+
+CLI 会把现有条件列原样带上（会打印一行 `ℹ 未指定条件列，已沿用现有的: 部门`）。
+
+> **别手写条件列。** 写一个不带 `id` 的 `{"type":"department","name":"部门"}` 进去，CLI 会当成新列去 `addField` 取号，结果矩阵里多出一条一模一样的「部门」列。
+>
+> 可用类型用 `GET /api/bs/hrm/matrix2/config/typeList?id=<matrixId>&matrixType=<0|1|2>` 查：部门矩阵返回 `conditionTypeList:[department]` / `valueTypeList:[resource]`。
 
 **所属机构与分权**：矩阵强制校验"所属机构"，而落到哪个字段由**分权状态**决定——分权开启时平台读 `belong_org_id`（归属机构），关闭时读 `targetId`。CLI 建矩阵前会自动查 `check-detach` 判断并选对字段，分权租户还会直接用返回的当前机构兜底，所以 `matrix create` 通常不用手写机构；只有"非分权租户"或"归属机构与目标机构必须不同"时才需要 `--org-id` / `--target-id`。
 
@@ -130,25 +183,35 @@ e10-cli matrix config <matrixId>
 {
   "id": "<矩阵ID>",
   "conditionConfigList": [
-    { "type": "department", "name": "显示名", "sort": 1 }
+    { "id": "<现有条件列id>", "type": "department", "name": "显示名", "sort": 1 }
   ],
   "valueConfigList": [
-    { "type": "resource", "name": "显示名", "singleType": 1, "sort": 1 }
+    { "id": "<现有值列id>", "type": "resource", "name": "显示名", "singleType": 1, "sort": 1 },
+    { "type": "resource", "name": "新加的列", "singleType": 0, "sort": 2 }
   ],
   "conditionDelList": [],
   "valueDelList": []
 }
 ```
 
-> `singleType`: 0=多选, 1=单选。条件字段不传，值字段必传。
+- `singleType`: 0=多选, 1=单选。值字段必传，条件字段可省（省了沿用现有的）。条件列在平台上**本身是必填的**，空着下发会被拒（「请至少维护一个条件字段」）。
+- **已有的列要带 `id`**（从 `matrix config` 拿）；不带 `id` 的会被当成新列去 `addField` 取号，**等于多建一列**。不带 id 但与现有列重名时 CLI 会告警。
+- **列 id 必须属于该矩阵**。传了别的矩阵的列 id，平台只回一句「系统内部错误」（NPE），CLI 会抢先报错并点名是哪一列。
+- ⚠ **保存是「按 id 合并」，不是整表替换**：没传的列**不会**被删（删列要走 `--value-del`）。所以「加一列」只传那一列就够了，不必把现有列全列一遍。
+- 保存后回读比对提交的列（在不在、名字对不对），平台回 200 但没按提交落库会直接报错。
 
 ## data save 简写格式
 
 ```json
 [
-  {"<条件configId>": ["<实体ID>"], "<值configId>": ["<实体ID>"]}
+  {"<条件configId>": ["<实体ID>"], "<值configId>": ["<实体ID>"]},
+  {"rowId": "<行id>", "<值configId>": ["<实体ID>"]}
 ]
 ```
 
-CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式。
+- 不带 `rowId` = 新增一行；带 `rowId`（或写作 `id`）= 改那一行。行 id 用 `matrix data list <matrixId>` 拿。
+- **改行只给要改的列就行**：平台是整行覆盖，CLI 会先读回该行、把没给的列补上再发。
+- 键不是该矩阵的列时直接报错并列出可用列，不会静默发出去。
+
+CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式；改过的行保存后会回读比对，平台回 200 但没按提交落库会直接报错。