weaver-e10-builder 1.2.5 → 1.5.1

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 但没按提交落库会直接报错。
 

package/skill-docs/references/hrm/guide-org-employee.md

@@ -0,0 +1,56 @@
+# 组织架构 — 人员录入（Excel 批量导入）
+
+> **平台自己解析 Excel，CLI 只负责把文件送上去、把解析结果取回来** —— CLI 不解析单元格，
+> 也不想解析：字段映射、必填校验、主子表展开全在平台侧，CLI 自己解一遍只会跟平台不一致。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli org employee template [--out <路径>]` | 导出人员导入模板（xlsx）。默认输出到当前目录的 `人员导入模板.xlsx` |
+| `e10-cli org employee import <file>` | 从 Excel 导入人员。`--dry-run` 只预览不导入；`--mode add\|update`（默认 `add`）；`--find-by <字段>`（更新时按哪个字段认人，默认 `username`）；`--review <n>` 预览行数（默认 100） |
+
+## ⚠ 先 `--dry-run`，再真导
+
+批量写组织数据是**外部可见且不好撤销**的操作。导入前先干跑一次：
+
+```bash
+e10-cli org employee import 人员.xlsx --dry-run
+```
+
+干跑会打出**平台解析出来的**工作表名、列数、行数和前几行内容 —— 拿它跟你的原表对一遍，
+确认列没串、行数对得上（尤其是**模板自带的示例行要删掉**），再去掉 `--dry-run` 真导。
+
+`--dry-run` 停在「预览」这一步，**这一步之前不会往组织里写任何东西**。
+
+## 链路（七步，每步产出喂给下一步）
+
+| | 端点 | 产出 |
+|---|---|---|
+| ⓪ | `POST /api/bs/hrm/emp/edit/importParam` | `bizId` + moduleName / functionName / handlerName / serviceName / dataType |
+| ① | `POST /api/file/preUploadCheck`（multipart） | 预上传 id |
+| ② | `POST /api/file/module/upload`（multipart） | `fileId` |
+| ③ | `POST /api/ebatch/checkFilePassword` | — |
+| ④ | `POST /api/ebatch/uploadFileId` | `taskId` |
+| ⑤ | `POST /api/ebatch/getExcelData` | 预览行（**不落库**） |
+| ⑥ | `POST /api/ebatch/importExcelData` | 真正执行 |
+
+- **⓪ 把 ④ 要的元数据全给了** —— moduleName / functionName / handlerName / serviceName / dataType
+  都不是 CLI 硬编码的，`bizId` 更是每次调用现生成。
+- **①② 的 multipart 字段逐字相同**，② 只多 `preUploadId` 与 `uploadType=common`。
+- ⑤⑥ 的参数全在 **query string**，body 为空。
+
+## 几个坑
+
+- **取 id 的层级三步三样**：① 在 `data.uploadModuleDto.fileid`、② 在 `data.fileid`（**小写 d**）、
+  ④ 在 `data.data.taskId`（多一层）。照着别的接口的写法套会静默取到空。
+- **⑤ 的参数是 `rerviewNum`** —— 平台把 review 拼错了，别"顺手改正"成 `reviewNum`。
+- **`weaTable[0].total` 是 `-1`**，不能拿来当行数；行数看 `data` 数组长度。
+- **`rerviewNum` 只是一次取多少行**，预览到的未必是全部 —— 行数刚好等于上限时命令会提示。
+- **模板里的示例行**（`user001`~`user008`）是平台放的演示数据，**导入前务必删掉**，否则会被当成真人建进去。
+- **`importType` 在 ④ 的报文里出现两次**：顶层是空串、真正生效的在 `uploadSet.customObj` 里。
+
+## 环境差异
+
+`emp/edit/importParam` 是判定「这个环境能不能导入人员」的探针 —— 返回里没有 `bizId` / `functionName`
+就说明该环境不支持，命令会直接报错，不会带着半截参数往下走。

package/skill-docs/references/workflow/guide-workflow-auth-resp.md

@@ -4,15 +4,15 @@
 
 ## 一、选择方式
 
-- 需要独立维护、供多个流程复用：先创建独立权责表，再由流程引用并映射变量。
-- 只服务于当前流程，且表单已经确定：创建权责表方式流程时选择新建权责表，条件直接引用表单字段。
-- 需要插入另一张权责表的审批路径中：创建中间片段型权责表，首尾位置使用审批等中间节点类型，再由宿主权责表按分支引用。
+- **默认选择随流程新建权责表**：创建权责表方式流程时使用 `--new-table`，条件直接引用当前流程表单字段。这条路径配置更直接，不需要额外维护变量映射，适用于一般权责表流程。
+- 只有权责规则需要被多个流程复用时，才先创建独立权责表，再使用 `--reuse-table` 引用并映射变量。
+- 需要多重嵌套权责表时，独立创建可复用的中间片段型权责表，首尾位置使用审批、确认等中间节点类型，再由宿主权责表按分支引用。
 - 普通顺序、分支流程继续使用流程图方式；只有需求明确要求权责表时才使用本指南。
 
 ## 二、独立权责表搭建顺序
 
 1. `workflow auth-resp create` 创建权责表并记录 `authRespId`。
-2. `workflow auth-resp variable add` 创建条件需要的变量；条件只能引用已创建变量。变量还必须在某个分支条件里**真正被引用**，否则复用该权责表建流程时它不会进变量映射列表（见 §五）。
+2. 条件可以直接使用系统字段；需要表达业务表单字段时，先用 `workflow auth-resp variable add` 创建变量。变量必须在某个分支条件里被引用，复用到流程后再映射为实际表单字段（见 §五）。
 3. 建立发起、结束设置和多个中间审批节点。中间节点统一作为列创建，操作者规则沿用工作流节点操作者规则。
 4. 为每个有效分支填写分支场景说明并创建条件。
 5. 每个分支从已有中间节点中选择自己的路径，通过顺序号表达串行或并行。
@@ -46,18 +46,8 @@ e10-cli workflow auth-resp configure <authRespId> --config @auth-resp.json
       "scenario": "合同金额不超过5万元",
       "condition": {
         "relation": "AND",
-        "childrens": [
-          {
-            "selectType": "4",
-            "formField": [{ "id": "-自定义稳定ID", "name": "合同金额", "fieldType": "NumberComponent", "variable": true, "varFirstType": "wf_number" }],
-            "NumberCompareOptionLeft": "4",
-            "NumberValueOptionLeft": "1",
-            "NumberTextValueLeft1": 50000,
-            "elementValue1Id": "",
-            "elementValue2Id": "",
-            "expressionBaseId": "",
-            "dataValueId": ""
-          }
+        "rules": [
+          { "source": "form", "field": "合同金额", "operator": "小于等于", "value": 50000 }
         ]
       },
       "path": [
@@ -69,13 +59,28 @@ e10-cli workflow auth-resp configure <authRespId> --config @auth-resp.json
 }
 ```
 
-流程内新建权责表时，`workflowId` 写真实流程 ID，条件 `formField` 使用该流程实际表单字段；独立权责表使用 `workflowId=-99999999`，条件引用 `variables` 中的变量。操作者类型直接支持 `all`、`user`、`initiator`；其他已有操作者类型使用 `raw` 并提供平台 `itemDatas`，结构与普通流程操作者一致。
+流程内新建权责表时，`workflowId` 写真实流程 ID，`source=form` 直接解析当前流程表单字段；独立权责表使用 `workflowId=-99999999`，`source=form` 会解析为 `variables` 中的同名变量。系统字段统一使用 `source=system`。复杂条件也可直接提供平台原始 `childrens`。操作者类型直接支持 `all`、`user`、`initiator`；其他已有操作者类型使用 `raw` 并提供平台 `itemDatas`，结构与普通流程操作者一致。
+
+条件字段查询：
+
+```bash
+e10-cli workflow auth-resp condition-fields <authRespId> --source-id <分支sourceId> --workflow-id <流程ID|-99999999>
+```
+
+| 业务来源 | 随流程新建权责表 | 独立或复用权责表 |
+|---|---|---|
+| 系统字段 `system` | 直接选择并保存 | 直接选择并保存 |
+| 表单字段 `form` | 直接选择当前流程实际表单字段 | 选择权责表变量作为表单字段的抽象 |
+| 变量 `variable` | 一般不需要 | 创建后用于条件，复用流程时映射到实际表单字段 |
+
+因此两种搭建方式都可以配置系统字段和表单字段条件；区别是独立权责表尚未绑定具体表单，配置时以变量表示表单字段，并在流程引用该权责表后完成变量映射。
 
 `usage=workflow` 表示完整流转，首尾默认使用发起和结束节点。`usage=fragment` 表示供其他权责表路径引用的中间片段，`start.type` 与 `end.type` 均配置为 `approve`、`confirm` 等中间节点类型；首尾位置不能使用 `start` 或 `end`。
 
 ```bash
 e10-cli workflow auth-resp create "合同分级审批权责表"
 e10-cli workflow auth-resp variable add <authRespId> "合同金额" wf_number
+e10-cli workflow auth-resp variable add <authRespId> "出行人" wf_browser --second-type wf_sub_company --detail
 e10-cli workflow auth-resp variable list <authRespId>
 e10-cli workflow auth-resp read <authRespId> --base-id <baseId> > design.json
 e10-cli workflow auth-resp save-design <authRespId> --config @design.json
@@ -91,6 +96,25 @@ e10-cli workflow auth-resp save-design <authRespId> --config @design.json
 | `wf_browser` | 浏览 | `--second-type` |
 | `wf_browser_relate` | 关联浏览 | `--relate-browser @browser.json` |
 
+变量既可以属于主表，也可以通过 `--detail` 创建为明细变量。明细变量用于表达未来流程表单中的某个明细字段，分支条件必须同时指定行量词：
+
+```json
+{
+  "condition": {
+    "relation": "AND",
+    "rules": [
+      { "source": "form", "field": "出行人", "operator": "等于", "value": [{ "id": "分部ID", "name": "泛微西安" }], "detail": "any" },
+      { "source": "form", "field": "出行人", "operator": "不为空", "detail": "all" }
+    ]
+  }
+}
+```
+
+- `detail: "any"`：任一行满足该条件，保存为 `detailOption=1`。
+- `detail: "all"`：所有行满足该条件，保存为 `detailOption=2`。
+- 字符串规则也可在末尾写 `:任一` 或 `:所有`。
+- 独立权责表中的 `source=form` 会按变量解析；明细变量被分支条件引用后，复用到流程时映射至类型匹配的实际明细字段。
+
 ## 三、表格设计结构
 
 `read` 返回的设计以 `columns` 和 `rows` 为核心：
@@ -103,7 +127,7 @@ e10-cli workflow auth-resp save-design <authRespId> --config @design.json
 
 每个有效分支必须有非空 `eventColumn` 和 `conditionKey`。界面用于继续录入的空白占位行不进入 CLI 保存数据。
 
-操作者和条件的业务规则与普通工作流一致，具体语法读取 [流程指南](guide-workflow.md) 和 [流程条件指南](guide-workflow-condition.md)。权责表条件的上下文标识由权责表命令负责，不把独立权责表变量当作表单字段创建。
+操作者和条件的业务规则与普通工作流一致，具体语法读取 [流程指南](guide-workflow.md) 和 [流程条件指南](guide-workflow-condition.md)。权责表命令自动补充 `belongScene=3`、权责表 ID、分支 ID 等上下文；独立权责表使用变量表达未来需要映射的表单字段。
 
 ## 四、在分支中引用权责表
 
@@ -141,7 +165,9 @@ e10-cli workflow auth-resp reference remove <宿主sourceId> <被引用sourceId>
 
 权责表是流程的搭建方式，流程表单来源仍按原生工作流程规则选择：自建流程表单、绑定已有流程表单或绑定 EB 表单。基础表单参数写入 `base.json`，其字段与 `workflow create-workflow` 的创建结构一致。
 
-### 随流程新建权责表
+一般需求默认使用“随流程新建权责表”；仅在需求明确要求复用已有权责规则，或需要以独立中间型权责表组成多重嵌套结构时，使用“复用已有权责表”。
+
+### 默认：随流程新建权责表
 
 ```bash
 e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --new-table "合同审批权责表"
@@ -149,7 +175,7 @@ e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --
 
 服务端在创建流程时生成并返回 `workflowId`、`formId` 和 `newAuthRespId`。这种方式已确定实际表单，分支条件直接选择表单字段，不做变量映射；发起和结束位置直接设置操作者。
 
-### 复用已有权责表
+### 按需：复用已有权责表
 
 ```bash
 e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --reuse-table <authRespId> --mappings @mappings.json
@@ -163,7 +189,7 @@ e10-cli workflow auth-resp-flow mapping-read <workflowId>
 e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
 ```
 
-复用模式把独立权责表变量映射为当前流程表单字段。先用 `mapping-read` 取得平台返回的变量项和可用字段结构，在对应项补全 `fieldBrowser` 后整体保存；变量类型必须与表单字段匹配。
+复用模式把独立权责表变量映射为当前流程表单字段。先用 `mapping-read` 取得平台返回的变量项和可用字段结构，在对应项补全 `fieldBrowser` 后整体保存；变量类型必须与表单字段匹配，明细变量必须选择实际表单的明细字段。
 
 > **前置条件：只有「已被分支条件引用」的变量才会出现在映射列表里。**
 >
@@ -191,7 +217,7 @@ e10-cli workflow auth-resp-flow mapping-read <workflowId>
 e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
 ```
 
-映射项保留变量的 `varId`、`varName`、`varType` 和筛选参数，在 `fieldBrowser` 中写入实际字段；变量类型、主表或明细位置应与字段匹配。流程内新建权责表并直接使用表单字段时无需变量映射。
+映射项保留变量的 `varId`、`varName`、`varType`、主表/明细位置和筛选参数，在 `fieldBrowser` 中写入实际字段；主表变量映射主表字段，明细变量映射明细字段，且变量类型与字段类型保持匹配。条件中的“任一行/所有行”属于权责表条件本身，映射后继续生效。流程内新建权责表并直接使用表单字段时无需变量映射。
 
 ## 七、Plan 记录