weaver-e10-builder 1.6.11 → 1.6.12

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

@@ -1,245 +1,276 @@
-# HRM 矩阵指南（条件矩阵 / 部门矩阵 / 分部矩阵）
-
-> 矩阵 = 「条件维度（行）→ 值维度（列）」的映射查询表。例如：部门 + 费用类型 → 审批人。用于流程中的矩阵对应操作者类型。
-
-## 命令参考
-
-### 矩阵管理
-
-| 命令 | 说明 |
-|------|------|
-| `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`。非 JSON 输出会标出「行随组织同步 / 行手工维护」「字段只读」 |
-| `e10-cli matrix config <id>` | 查看矩阵配置（条件字段 + 值字段） |
-| `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...>` 清空数据行再删；批量删除时只要有**一条**不可删，整批都失败 |
-
-### 矩阵数据维护
-
-| 命令 | 说明 |
-|------|------|
-| `e10-cli matrix data list <matrixId>` | 分页查询矩阵数据行。`--condition` `--value` 过滤 |
-| `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` |
-
----
-
-## 典型工作流
-
-```bash
-# 1. 创建矩阵（新建即启用；分权租户的所属机构自动取当前机构）
-e10-cli matrix create "审批人映射表" --type 2 --desc "部门→审批人"
-
-# 2. 查 ID
-e10-cli matrix list --name "审批人"
-
-# 3. 配字段（条件=部门，值=审批人）—— 直接可用，不需要先开设计器
-e10-cli matrix config-edit <matrixId> \
-  --condition '[{"type":"department","name":"所属部门"}]' \
-  --value '[{"type":"resource","name":"审批人","singleType":1}]'
-
-# 4. 启用
-e10-cli matrix enable <matrixId>
-
-# 5. 填数据
-echo '[{"<条件configId>":["<部门ID>"],"<值configId>":["<人员ID>"]}]' > rows.json
-e10-cli matrix data save <matrixId> --rows @rows.json
-
-# 6. 查数据
-e10-cli matrix data list <matrixId>
-
-# 7. 在流程中使用矩阵
-e10-cli workflow set-operator <wf> <nodeId> --type matrix \
-  --matrix-id <matrixId> --value-config-id <值configId> \
-  --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
-```
-
----
-
-## 行从哪来、字段能不能改：看 `syncType` 和 `permList`
-
-`matrix list --json` 每条记录带几个标记位。**不要拿 `sysType` 当判据** —— 它只说明是不是平台内置的，不决定能力：
-
-| 字段 | 取值 | 含义 |
-|---|---|---|
-| `type` | `0` / `1` / `2` | `0`=分部矩阵、`1`=部门矩阵、`2`=自定义矩阵 |
-| `syncType` | `1` / `0` | **行从哪来**。`1`=数据行随组织架构同步（**行不可增删，行 id 就是部门/分部 id**）；`0`=行手工维护（行 id 是平台发号的雪花） |
-| `permList` | 数组 | **含 `FIELD` 才能改字段配置**；不含就是字段只读（平台内置矩阵是这种） |
-| `sysType` | `1` / `0` | 是否平台内置。只影响名字语义，**不影响能做什么** |
-
-`matrix list` 的非 JSON 输出会直接把这两条标出来：`行随组织同步 / 行手工维护`、`字段只读`。
-
-同一租户里四个矩阵的对照，四个象限都出现过：
-
-| 矩阵 | 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`）。
-
-## 部门矩阵 / 分部矩阵：条件列是平台给的
-
-建部门矩阵（`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`。
-
-**列表的状态过滤**：`matrix list` 走管理端点 `matrix2/list`，能看到**停用的矩阵**并显示真实状态；`--name`（模糊）、`--enable-status`、`--org-id` 都是服务端过滤。
-
-## 完整配置：条件列 → 人员列 → 数据映射 → 运行时读回
-
-```bash
-# ① 建矩阵（自定义矩阵。系统矩阵是平台内置的，用 matrix list 找现成的）
-#    新建即为「启用」状态，不需要再 enable；要停用才跑 matrix disable
-#    所属机构：分权租户自动取当前机构，非分权租户用 --org-id 显式指定（不加会有"所属机构不能为空"）
-e10-cli matrix create "部门审批人" --type 2 --desc "部门→审批人"
-
-# ② 配列：条件列 + 值列。值列 type=resource 就是"人员列"；singleType 0=多选 1=单选
-e10-cli matrix config-edit <matrixId> \
-  --condition '[{"type":"department","name":"所属部门"}]' \
-  --value '[{"type":"resource","name":"审批人","singleType":1}]'
-
-# ③ 取各列 configId（数据映射的键就是它），再填数据行
-e10-cli matrix config <matrixId>            # → conditionConfigList[].id / valueConfigList[].id
-e10-cli matrix data save <matrixId> --rows @rows.json
-e10-cli matrix data list <matrixId>         # 回读数据行
-
-# ④ 启用并挂到流程节点
-e10-cli matrix enable <matrixId>
-e10-cli workflow set-operator <wf> <nodeId> --type matrix \
-  --matrix-id <matrixId> --value-config-id <值列configId> \
-  --matrix-rule "<条件列configId>:1:1:1"
-
-# ⑤ 运行时读回：确认条件列/值列是否就是流程实际在读的那一组
-e10-cli matrix config <matrixId>
-```
-
-> **矩阵类型不用手填**：`--type matrix` 的 `sourceType` / 条件列中文名由 CLI 自动读 `GET /api/bs/hrm/matrix2/config?id=<matrixId>` 解析——`conditionConfigList[].type` 是 `department` 即部门矩阵、`subcompany` 即分部矩阵。条件列不在目标矩阵里时会直接报错并列出可选列，不会静默挂错。
->
-> 排查"取不到人"时按这个顺序看：`matrix config`（列对不对）→ `matrix data list`（行有没有）→ 流程节点的矩阵规则是否引用了正确的 `条件configId`。
-
-## 字段类型枚举
-
-设计器「字段维护」里就这 **7 档**：
-
-| 中文 | API 值 |
-|------|--------|
-| 人员 | `resource` |
-| 部门 | `department` |
-| 分部 | `subcompany` |
-| 岗位 | `position` |
-| 客户 | `customer` |
-| 项目 | `project` |
-| 自定义浏览框 | `customBrowser` |
-
-## 自定义浏览框列
-
-条件列和值列都可以是**自定义浏览框**。它的读写形状**不一样**，这点最容易踩：
-
-| | 形状 |
-|---|---|
-| **写**（要发的） | `customBrowser:<浏览框富对象>` + `singleType` |
-| **读**（回来的） | `browserModule` + `browserType` + `configDetailDto{dataId,singleType}` + `showConfig` |
-
-平台**只认写的那个形状**：把读回来的三个键原样发回去，会被回「**自定义浏览框参数异常**」。所以：
-
-- **新建**一列时用浏览框**名字**指名即可，CLI 会去查回富对象：
-  ```json
-  { "type": "自定义浏览框", "name": "这里是显示名字", "browser": "测试自定义浏览框", "singleType": 0 }
-  ```
-  `browser` 也收完整对象（想直接贴 bean 就用 `customBrowser`）。名字**精确匹配**，同名多条或查不到都会报错并列候选。
-- **沿用**老列（省略 `--condition`）时，CLI 会按读回里的 `configDetailDto.dataId` **把富对象反查回来再发** —— 不需要你补；也不要手写 `browserType` / `configDetailDto`，发了会被拒。
-- `singleType`：`0` 多选 / `1` 单选（列底下那个「单选」勾选框）。自定义浏览框列默认 `0`。
-
-```bash
-e10-cli matrix config-edit <矩阵ID> \
-  --condition '[{"type":"部门","name":"所属门店"},{"type":"自定义浏览框","name":"合同","browser":"测试自定义浏览框"}]' \
-  --value '[{"type":"人员","name":"门店经理","singleType":1}]'
-```
-
-## config-edit 参数
-
-```json
-{
-  "id": "<矩阵ID>",
-  "conditionConfigList": [
-    { "id": "<现有条件列id>", "type": "department", "name": "显示名", "sort": 1 }
-  ],
-  "valueConfigList": [
-    { "id": "<现有值列id>", "type": "resource", "name": "显示名", "singleType": 1, "sort": 1 },
-    { "type": "resource", "name": "新加的列", "singleType": 0, "sort": 2 }
-  ],
-  "conditionDelList": [],
-  "valueDelList": []
-}
-```
-
-- `singleType`: 0=多选, 1=单选。值字段必传，条件字段可省（省了沿用现有的）。条件列在平台上**本身是必填的**，空着下发会被拒（「请至少维护一个条件字段」）。自定义浏览框列默认 0。
-- **自定义浏览框列**用 `"browser":"<浏览框名>"` 指名即可（CLI 查回富对象再发），详见上面「自定义浏览框列」一节。写 `browserType` / `configDetailDto` 这类**读回形状**会被平台拒。
-- **已有的列要带 `id`**（从 `matrix config` 拿）；不带 `id` 的会被当成新列去 `addField` 取号，**等于多建一列**。不带 id 但与现有列重名时 CLI 会告警。
-- **列 id 必须属于该矩阵**。传了别的矩阵的列 id，平台只回一句「系统内部错误」（NPE），CLI 会抢先报错并点名是哪一列。
-- ⚠ **保存是「按 id 合并」，不是整表替换**：没传的列**不会**被删（删列要走 `--value-del`）。所以「加一列」只传那一列就够了，不必把现有列全列一遍。
-- 保存后回读比对提交的列（在不在、名字对不对），平台回 200 但没按提交落库会直接报错。
-
-## data save 简写格式
-
-```json
-[
-  {"<条件configId>": ["<实体ID>"], "<值configId>": ["<实体ID>"]},
-  {"rowId": "<行id>", "<值configId>": ["<实体ID>"]}
-]
-```
-
-- 不带 `rowId` = 新增一行；带 `rowId`（或写作 `id`）= 改那一行。行 id 用 `matrix data list <matrixId>` 拿。
-- **改行只给要改的列就行**：平台是整行覆盖，CLI 会先读回该行、把没给的列补上再发。
-- 键不是该矩阵的列时直接报错并列出可用列，不会静默发出去。
-
-CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式；改过的行保存后会回读比对，平台回 200 但没按提交落库会直接报错。
-
+# HRM 矩阵指南（条件矩阵 / 部门矩阵 / 分部矩阵）
+
+> 矩阵 = 「条件维度（行）→ 值维度（列）」的映射查询表。例如：部门 + 费用类型 → 审批人。用于流程中的矩阵对应操作者类型。
+
+## 命令参考
+
+### 矩阵管理
+
+| 命令 | 说明 |
+|------|------|
+| `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`。非 JSON 输出会标出「行随组织同步 / 行手工维护」「字段只读」 |
+| `e10-cli matrix config <id>` | 查看矩阵配置（条件字段 + 值字段） |
+| `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...>` 清空数据行再删；批量删除时只要有**一条**不可删，整批都失败 |
+
+### 矩阵维护者
+
+矩阵维护者与矩阵数据行、流程节点操作者是不同设置。先用 `matrix maintainer options <matrixId>` 读取当前矩阵的维护者类型、权限、可维护条件码表和值列 ID；用 `matrix maintainer list <matrixId>` 查询现有条目，`get <matrixId> <维护者条目ID>` 查看已保存的表单、条件和列。`list/options` 可用 `--out <文件>` 保存完整结果。
+
+```bash
+e10-cli matrix maintainer options <matrixId>
+e10-cli matrix maintainer list <matrixId>
+e10-cli matrix maintainer get <matrixId> <维护者条目ID>
+e10-cli matrix maintainer add <matrixId> @maintainer.json
+e10-cli matrix maintainer update <matrixId> <维护者条目ID> @maintainer.json
+e10-cli matrix maintainer delete <matrixId> <维护者条目ID> [更多条目ID...]
+```
+
+`add/update` 的配置是**整条维护者规则**，不是增量补丁。`subjects` 可混合人员 `resource`、部门 `department`、分部 `subcompany`、角色 `role`、群组 `channel`、岗位 `position` 和所有人 `all`；各项使用当前环境的真实 ID，所有人的 ID 为 `0`。命令按组织浏览框回读每个具体对象，找不到就停止，不会用输入 ID 假造展示对象。可选类型仍以 `options` 的实时结果为准；界面码 `user/dept/group` 分别对应配置码 `resource/department/channel`。
+
+`type` 取 `data`（数据维护，协议值 `0`）或 `full`（完全控制，协议值 `1`）。数据维护可配置 `permissions` 中的 `add`、`delete`（新建/删除数据行）、`columns` 中的值列 ID，以及 `conditions`。这些限制不适用于完全控制，CLI 会拒绝在 `full` 中混用。**省略数据维护的权限、列或条件，表示该项提交为空**；更新前应先 `get` 并在配置文件中保留需要继续生效的项。
+
+```json
+{
+  "subjects": [{"type":"resource","id":"<人员ID>"}, {"type":"role","id":"<角色ID>"}],
+  "type": "data",
+  "permissions": ["add", "delete"],
+  "columns": ["<矩阵值列configId>"],
+  "conditions": [{"type":"department","value":"108","ids":["<部门ID>"]}]
+}
+```
+
+`conditions[].type/value` 取自当前 `options.conditions[].id/valOptionList[].id`，不要把某个矩阵的码表推广到所有矩阵。带浏览框的条件（如“指定部门/分部”）必须给 `ids`，CLI 会按当前环境回读这些 ID；其他条件不接受 `ids`。`columns` 必须属于该矩阵的值列，不能填条件列 ID。写入后 CLI 会重新读取列表与详情，核对维护者主体、类型、数据权限、条件和列；平台仅返回 HTTP/业务成功不视为验收完成。
+
+`delete` 删除的是指定矩阵中的维护者条目，可一次给出多个条目 ID；它不会删除矩阵或矩阵数据行，也不同于数据维护权限中的 `permissions: ["delete"]`。先用 `list` 取得真实条目 ID。CLI 会在提交前确认每个 ID 都属于该矩阵，调用维护者删除接口后再次列出条目，确认目标均消失且非目标条目仍存在。若回读异常，应先查询列表核实实际状态，不要盲目重试。
+
+### 矩阵数据维护
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli matrix data list <matrixId>` | 分页查询矩阵数据行。`--condition` `--value` 过滤 |
+| `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` |
+
+---
+
+## 典型工作流
+
+```bash
+# 1. 创建矩阵（新建即启用；分权租户的所属机构自动取当前机构）
+e10-cli matrix create "审批人映射表" --type 2 --desc "部门→审批人"
+
+# 2. 查 ID
+e10-cli matrix list --name "审批人"
+
+# 3. 配字段（条件=部门，值=审批人）—— 直接可用，不需要先开设计器
+e10-cli matrix config-edit <matrixId> \
+  --condition '[{"type":"department","name":"所属部门"}]' \
+  --value '[{"type":"resource","name":"审批人","singleType":1}]'
+
+# 4. 启用
+e10-cli matrix enable <matrixId>
+
+# 5. 填数据
+echo '[{"<条件configId>":["<部门ID>"],"<值configId>":["<人员ID>"]}]' > rows.json
+e10-cli matrix data save <matrixId> --rows @rows.json
+
+# 6. 查数据
+e10-cli matrix data list <matrixId>
+
+# 7. 在流程中使用矩阵
+e10-cli workflow set-operator <wf> <nodeId> --type matrix \
+  --matrix-id <matrixId> --value-config-id <值configId> \
+  --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
+```
+
+---
+
+## 行从哪来、字段能不能改：看 `syncType` 和 `permList`
+
+`matrix list --json` 每条记录带几个标记位。**不要拿 `sysType` 当判据** —— 它只说明是不是平台内置的，不决定能力：
+
+| 字段 | 取值 | 含义 |
+|---|---|---|
+| `type` | `0` / `1` / `2` | `0`=分部矩阵、`1`=部门矩阵、`2`=自定义矩阵 |
+| `syncType` | `1` / `0` | **行从哪来**。`1`=数据行随组织架构同步（**行不可增删，行 id 就是部门/分部 id**）；`0`=行手工维护（行 id 是平台发号的雪花） |
+| `permList` | 数组 | **含 `FIELD` 才能改字段配置**；不含就是字段只读（平台内置矩阵是这种） |
+| `sysType` | `1` / `0` | 是否平台内置。只影响名字语义，**不影响能做什么** |
+
+`matrix list` 的非 JSON 输出会直接把这两条标出来：`行随组织同步 / 行手工维护`、`字段只读`。
+
+同一租户里四个矩阵的对照，四个象限都出现过：
+
+| 矩阵 | 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`）。
+
+## 部门矩阵 / 分部矩阵：条件列是平台给的
+
+建部门矩阵（`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`。
+
+**列表的状态过滤**：`matrix list` 走管理端点 `matrix2/list`，能看到**停用的矩阵**并显示真实状态；`--name`（模糊）、`--enable-status`、`--org-id` 都是服务端过滤。
+
+## 完整配置：条件列 → 人员列 → 数据映射 → 运行时读回
+
+```bash
+# ① 建矩阵（自定义矩阵。系统矩阵是平台内置的，用 matrix list 找现成的）
+#    新建即为「启用」状态，不需要再 enable；要停用才跑 matrix disable
+#    所属机构：分权租户自动取当前机构，非分权租户用 --org-id 显式指定（不加会有"所属机构不能为空"）
+e10-cli matrix create "部门审批人" --type 2 --desc "部门→审批人"
+
+# ② 配列：条件列 + 值列。值列 type=resource 就是"人员列"；singleType 0=多选 1=单选
+e10-cli matrix config-edit <matrixId> \
+  --condition '[{"type":"department","name":"所属部门"}]' \
+  --value '[{"type":"resource","name":"审批人","singleType":1}]'
+
+# ③ 取各列 configId（数据映射的键就是它），再填数据行
+e10-cli matrix config <matrixId>            # → conditionConfigList[].id / valueConfigList[].id
+e10-cli matrix data save <matrixId> --rows @rows.json
+e10-cli matrix data list <matrixId>         # 回读数据行
+
+# ④ 启用并挂到流程节点
+e10-cli matrix enable <matrixId>
+e10-cli workflow set-operator <wf> <nodeId> --type matrix \
+  --matrix-id <matrixId> --value-config-id <值列configId> \
+  --matrix-rule "<条件列configId>:1:1:1"
+
+# ⑤ 运行时读回：确认条件列/值列是否就是流程实际在读的那一组
+e10-cli matrix config <matrixId>
+```
+
+> **矩阵类型不用手填**：`--type matrix` 的 `sourceType` / 条件列中文名由 CLI 自动读 `GET /api/bs/hrm/matrix2/config?id=<matrixId>` 解析——`conditionConfigList[].type` 是 `department` 即部门矩阵、`subcompany` 即分部矩阵。条件列不在目标矩阵里时会直接报错并列出可选列，不会静默挂错。
+>
+> 排查"取不到人"时按这个顺序看：`matrix config`（列对不对）→ `matrix data list`（行有没有）→ 流程节点的矩阵规则是否引用了正确的 `条件configId`。
+
+## 字段类型枚举
+
+设计器「字段维护」里就这 **7 档**：
+
+| 中文 | API 值 |
+|------|--------|
+| 人员 | `resource` |
+| 部门 | `department` |
+| 分部 | `subcompany` |
+| 岗位 | `position` |
+| 客户 | `customer` |
+| 项目 | `project` |
+| 自定义浏览框 | `customBrowser` |
+
+## 自定义浏览框列
+
+条件列和值列都可以是**自定义浏览框**。它的读写形状**不一样**，这点最容易踩：
+
+| | 形状 |
+|---|---|
+| **写**（要发的） | `customBrowser:<浏览框富对象>` + `singleType` |
+| **读**（回来的） | `browserModule` + `browserType` + `configDetailDto{dataId,singleType}` + `showConfig` |
+
+平台**只认写的那个形状**：把读回来的三个键原样发回去，会被回「**自定义浏览框参数异常**」。所以：
+
+- **新建**一列时用浏览框**名字**指名即可，CLI 会去查回富对象：
+  ```json
+  { "type": "自定义浏览框", "name": "这里是显示名字", "browser": "测试自定义浏览框", "singleType": 0 }
+  ```
+  `browser` 也收完整对象（想直接贴 bean 就用 `customBrowser`）。名字**精确匹配**，同名多条或查不到都会报错并列候选。
+- **沿用**老列（省略 `--condition`）时，CLI 会按读回里的 `configDetailDto.dataId` **把富对象反查回来再发** —— 不需要你补；也不要手写 `browserType` / `configDetailDto`，发了会被拒。
+- `singleType`：`0` 多选 / `1` 单选（列底下那个「单选」勾选框）。自定义浏览框列默认 `0`。
+
+```bash
+e10-cli matrix config-edit <矩阵ID> \
+  --condition '[{"type":"部门","name":"所属门店"},{"type":"自定义浏览框","name":"合同","browser":"测试自定义浏览框"}]' \
+  --value '[{"type":"人员","name":"门店经理","singleType":1}]'
+```
+
+## config-edit 参数
+
+```json
+{
+  "id": "<矩阵ID>",
+  "conditionConfigList": [
+    { "id": "<现有条件列id>", "type": "department", "name": "显示名", "sort": 1 }
+  ],
+  "valueConfigList": [
+    { "id": "<现有值列id>", "type": "resource", "name": "显示名", "singleType": 1, "sort": 1 },
+    { "type": "resource", "name": "新加的列", "singleType": 0, "sort": 2 }
+  ],
+  "conditionDelList": [],
+  "valueDelList": []
+}
+```
+
+- `singleType`: 0=多选, 1=单选。值字段必传，条件字段可省（省了沿用现有的）。条件列在平台上**本身是必填的**，空着下发会被拒（「请至少维护一个条件字段」）。自定义浏览框列默认 0。
+- **自定义浏览框列**用 `"browser":"<浏览框名>"` 指名即可（CLI 查回富对象再发），详见上面「自定义浏览框列」一节。写 `browserType` / `configDetailDto` 这类**读回形状**会被平台拒。
+- **已有的列要带 `id`**（从 `matrix config` 拿）；不带 `id` 的会被当成新列去 `addField` 取号，**等于多建一列**。不带 id 但与现有列重名时 CLI 会告警。
+- **列 id 必须属于该矩阵**。传了别的矩阵的列 id，平台只回一句「系统内部错误」（NPE），CLI 会抢先报错并点名是哪一列。
+- ⚠ **保存是「按 id 合并」，不是整表替换**：没传的列**不会**被删（删列要走 `--value-del`）。所以「加一列」只传那一列就够了，不必把现有列全列一遍。
+- 保存后回读比对提交的列（在不在、名字对不对），平台回 200 但没按提交落库会直接报错。
+
+## data save 简写格式
+
+```json
+[
+  {"<条件configId>": ["<实体ID>"], "<值configId>": ["<实体ID>"]},
+  {"rowId": "<行id>", "<值configId>": ["<实体ID>"]}
+]
+```
+
+- 不带 `rowId` = 新增一行；带 `rowId`（或写作 `id`）= 改那一行。行 id 用 `matrix data list <matrixId>` 拿。
+- **改行只给要改的列就行**：平台是整行覆盖，CLI 会先读回该行、把没给的列补上再发。
+- 键不是该矩阵的列时直接报错并列出可用列，不会静默发出去。
+
+CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式；改过的行保存后会回读比对，平台回 200 但没按提交落库会直接报错。
+

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

@@ -0,0 +1,77 @@
+# 角色与成员配置
+
+适用于后台管理中心的角色设置。角色功能权限、角色成员、矩阵维护者是三套不同配置；不要把 `role permission`、`role member-*` 与 `matrix maintainer` 混用。
+
+## 操作顺序
+
+先用 `role list` 确认角色 ID，`role get <roleId>` 读取基础信息；修改角色基础信息后再读一次。成员先用 `role member-list <roleId>` 找**成员条目 ID**，再用 `member-get <roleId> <memberId>` 读取完整设置。成员对象 ID（人员/部门/岗位 ID）不等于成员条目 ID，修改和删除必须传后者。功能权限先 `role permission list <roleId>`，再按返回的 `permissionSetCode` 增减。
+
+```bash
+e10-cli role list
+e10-cli role get <roleId>
+e10-cli role update <roleId> --name "新角色名" --remark "说明"
+e10-cli role update <roleId> --parent <父角色ID>
+e10-cli role permission list <roleId>
+e10-cli role permission add <roleId> <permissionSetCode>
+e10-cli role permission remove <roleId> <permissionSetCode>
+e10-cli role member-list <roleId>
+e10-cli role member-get <roleId> <memberId>
+e10-cli role member-delete <roleId> <memberId> [更多成员条目ID...]
+```
+
+`role update` 支持 `--name`、`--code`、`--remark`、`--parent`，未指定项沿用角色详情；`--parent` 只能给当前角色树中存在、且不是自身或子孙的角色 ID。`--remark ""` 清空备注。功能权限读取当前角色的权限树，`add/remove` 每次只改变一个权限集并核对选中状态，不需要、也不应手填 `menuCode` 和权限名称。禁用的权限集不能修改。
+
+## 添加成员
+
+`role add-member <roleId> [名称...] --type <类型>` 支持 `resource` 人员、`department` 部门、`subcompany` 分部、`position` 岗位、`channel` 群组；名称同名时改用 `--id <对象ID,对象ID>`。`--level` 是**角色成员级别**：`1` 总部、`2` 分部、`3` 部门，也接受中文名。`--sec-min/--sec-max` 是安全级别上下限，范围随租户而变；`--is-seclevel` 开启校验。部门/分部可给 `--department-attribute subordinate,partTimeStaff`：前者包含下级，后者包含兼职；省略表示均不启用。
+
+`--org-scope` 是成员分权范围（不同于成员级别）。新增命令支持无需指定机构的范围；“指定部门/指定分部”通过先添加成员、再用 `member-update` 设置，避免只有范围码却没有机构对象。
+
+没有具体浏览对象的“所有人”和“全部外部联系人”走另一条命令：
+
+```bash
+e10-cli role add-scope-member <roleId> --type all [--level 总部]
+e10-cli role add-scope-member <roleId> --type allExternal [--level 分部]
+```
+
+它们的类型码分别是 `all`、`allExternal`；**指定外部人员** `external` 不支持。新增后返回的成员条目 ID 可用于 `member-get`、`member-delete`。
+
+新增范围成员和批量删除会先确认成员列表完整；若平台只返回部分分页，命令会停止，不会据不完整列表判定新增或删除成功。
+
+## 修改成员：先查询，再只改所需项
+
+```bash
+e10-cli role member-update <roleId> <memberId> --department-attribute subordinate,partTimeStaff
+e10-cli role member-update <roleId> <memberId> --department-attribute ""
+e10-cli role member-update <roleId> <memberId> --level 部门 --sec-min 0 --sec-max 100
+e10-cli role member-update <roleId> <memberId> --org-scope 指定部门 --org-departments <部门ID>
+e10-cli role member-update <roleId> <memberId> --org-scope 指定分部 --org-subcompanies <分部ID> --org-attribute subordinate
+e10-cli role member-update <roleId> <memberId> --position-level 2 --position-subcompany <分部ID>
+e10-cli role member-update <roleId> <memberId> --position-level 3 --position-department <部门ID>
+e10-cli role member-update <roleId> <memberId> --expire-type DAY --expire-detail 20
+e10-cli role member-update <roleId> <memberId> --expire-type APPOINT --expire-detail 2027-01-07
+```
+
+修改会先读取该成员整条配置，保留未指定项；指定机构 ID 从组织浏览接口回读真实对象，找不到就停止。修改成员级别用 `--level`（总部/分部/部门或 1/2/3），安全级别用 `--sec-min`、`--sec-max`；是否启用校验用 `--enable-seclevel` 或 `--disable-seclevel`，两者不能同时给。上下限的可用范围以当前租户和成员表单为准，CLI 只校验数值与下限不高于上限。`--department-attribute` 只用于部门/分部成员。`--position-level` 只用于岗位成员，码表 `1` 全部、`2` 指定分部、`3` 指定部门；对应的机构 ID 分别用 `--position-subcompany`、`--position-department`，多个 ID 用逗号分隔。它与 `--level` 的成员级别无关。岗位兼职 `position_attribute` 尚无正向保存证据，暂不提供配置项。
+
+分权范围 `--org-scope` 可用中文名或协议码：
+
+| 中文名 | 协议码 |
+|---|---|
+| 全部机构 | `ALL_SCOPE` |
+| 同部门 | `ORIGINAL_DEPT_SCOPE` |
+| 同部门的下级部门 | `ORIGINAL_DEPT_SUB_SCOPE` |
+| 同部门及下级部门 | `ORIGINAL_DEPT_INCLUDE_SUB_SCOPE` |
+| 同分部 | `ORIGINAL_SUBCOMPANY_SCOPE` |
+| 同分部的下级分部 | `ORIGINAL_SUBCOMPANY_SUB_SCOPE` |
+| 同分部及下级分部 | `ORIGINAL_SUBCOMPANY_INCLUDE_SUB_SCOPE` |
+| 指定部门 | `DEPARTMENT` |
+| 指定分部 | `SUBCOMPANY` |
+
+指定部门必须有 `--org-departments`；指定分部必须有 `--org-subcompanies`；二者不能混用。两者都可选 `--org-attribute subordinate` 表示包含下级，传 `--org-attribute ""` 表示不含。其他范围不接受指定机构或该选项。
+
+有效期 `--expire-type` 的码表为：`UNLIMITED` 长期、`TEMPORARY` 临时、`DAY` 天、`WEEK` 周、`MONTH` 月、`YEAR` 年、`APPOINT` 指定日期。`DAY/WEEK/MONTH/YEAR` 须用 `--expire-detail` 给正整数，`APPOINT` 须给 `YYYY-MM-DD` 日期；`UNLIMITED/TEMPORARY` 不接受 detail。平台根据类型和 detail 计算 `expireDate`，CLI 不把旧的 `expireDate` 回传；写后核对类型与 detail。实际到期时间仍应以 `member-get` 回读的 `expireDate` 为准。
+
+## 边界
+
+角色维护者暂不支持；指定外部人员 `external` 暂不支持；岗位兼职项暂不支持。不要把 `allExternal` 理解为指定外部人员，也不要把功能权限当作菜单可见范围。删除角色成员与删除角色是不同命令，先确认 ID 所指对象。