weaver-e10-builder 1.2.3 → 1.5.1

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/menu/system-menus.md

@@ -61,3 +61,15 @@
 ```
 
 > **只有包含工作流的应用**才能挂载工作流系统页面。表单台账会自动挂入菜单，无需手动操作。
+
+---
+
+## 菜单是一棵树
+
+应用菜单不止一层：顶层之外还有 `children` 嵌套（例如平台自带的「设置 → 个人设置 → 个人菜单设置」、系统设置下的「基本信息 / 菜单设置」）。
+
+- `menu list <appId>` **递归展开**整棵树，输出带缩进；末尾会注明含多少个嵌套菜单。**这份列表就是全量**，在它里面找不到某个菜单，才能下结论说「该应用没有这个菜单」。
+- `menu rename <appId> <菜单ID或名称> <新名>` 按 ID 或名称定位，**嵌套里的菜单一样能改**。同名多条时命令会报歧义并列出候选 ID，不会替你挑一条。
+- 改名的命令会**重建写报文**再回读比对：名称变了、且「页面绑定 / 菜单 URL / 可见范围」等字段一个都没动，才算成功。改名只动名字，不会顺带改掉已有的筛选条件或页签配置。
+
+**平台系统菜单（回收站、设置及其子项）不能改名** —— 它们由平台维护、指向内置页面，改名没有语义，命令会直接拒绝。

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 记录
 

package/skill-docs/references/workflow/guide-workflow-odoc-setting.md

@@ -0,0 +1,248 @@
+# 公文设置指南
+
+## 使用范围
+
+本指南用于配置原生公文流程的专属设置。先从 [公文流程指南](guide-workflow-odoc.md) 完成流程、表单、节点和出口，再按本指南配置正文、模板、痕迹、编号、附件区、归档和智能助手等内容。
+
+所有环境读取与配置均使用 `e10-cli`：
+
+```bash
+e10-cli workflow odoc setting get <workflowId>
+e10-cli workflow odoc setting set <workflowId> --config @odoc-setting.json
+```
+
+`setting get` 返回当前环境实际提供的设置分组、当前值、候选字段和候选控件。配置前先读取，按需求选择设置项；配置后再次读取核对。
+
+## 已验证的通用规则
+
+- `setting set` 先读取当前完整配置，只合并本次指定项，再整包保存；未指定的设置保持原值。
+- 保存后自动回读比对，配置是否生效以回读结果为准。
+- 字段选择值保存为字段 ID；显式字段参数支持字段名称或字段 ID。
+- 节点参数支持节点名称或节点 ID。节点名称在同一流程内重复时，命令停止并返回候选节点 ID，不自动选择。
+- `--open-text-select 2` 时使用 `--open-text-node` 指定一个或多个节点；`--edit-text-node` 同样支持多个节点。
+- `--ai-abstract`、`--ai-format` 属于公文助手子能力，启用时同时配置 `--ai-odoc 1`。
+- `odocNumber`、`odocAttachArea` 保持嵌套对象；`signNode` 以 `signNodeList` 保存；其他普通分组字段平铺到保存报文顶层。
+- 已配置的节点清单读回为 `{name,id}` 数组，保存时转换为节点 ID 串；重复修改设置时同样按此形状保存。签章节点数组保持对象结构。
+
+## 配置方式
+
+公文设置有三种使用方式：
+
+- **显式参数**：常用字段、节点和开关直接使用命令参数。
+- **结构化配置**：其余已明确结构的设置写入 `--config @文件`。
+- **专用配置**：目录、模板、字段映射等需要选择业务对象的设置，先查询候选资源，再按对应章节配置。
+
+配置文件可使用业务分组包装，CLI 会将普通分组字段合并到完整保存报文：
+
+当前可用的配置包装名称为 `basic`、`text`、`files`、`nodes`、`signature`、`archive`、`ai`；`number` 映射为 `odocNumber`，`attachmentArea` 映射为 `odocAttachArea`。也可以直接在配置对象顶层填写平台配置键。
+
+```json
+{
+  "basic": {
+    "officialType": "1",
+    "requestTitleField": "字段ID",
+    "documentTitleField": "-102",
+    "openTextDefaultSelect": "2",
+    "openTextDefaultNode": ["节点ID"],
+    "editTextNode": ["节点ID"],
+    "editorReadOnly": true,
+    "previewDefault": true
+  }
+}
+```
+
+字段选择值使用字段 ID；节点选择可在显式参数中使用名称或 ID，在 JSON 中使用节点 ID。开关在 JSON 中使用布尔值或 `0/1`，CLI 保存时转换为平台要求的形状。
+
+## 配置分组总览
+
+| 平台分组 | settingKey | 包含内容 |
+|---|---|---|
+| 基础设置 | `base` | 公文类型、标题、正文字段、目录、正文节点和预览 |
+| 常用功能 | `common` | 新建正文、上传格式、正文版本、流程草稿、签字意见分组 |
+| 正文显示设置 | `textDisplay` | 表单内显示、分栏、位置、比例、应用节点和重新上传 |
+| 痕迹设置 | `trace` | 留痕、审阅、隐藏痕迹、清稿节点 |
+| 其他设置 | `other` | 附件转换、打印下载、标题同步、客户端插件和保存提醒 |
+| 模板设置 | `template` | 套红模板、编辑模板、打印模板 |
+| 排版设置 | `format` | 排版模板 |
+| 签章节点设置 | `signNode` | 节点签章、启用与必填 |
+| 正文动作设置 | `docAction` | 正文动作规则 |
+| 公文字段设置 | `fieldSetting` | 公文字段配置 |
+| 内部交换设置 | `innerExchangeSetting` | 内部交换配置 |
+| 公文编号设置 | `odocNumber` | 文号字段、类型、出口和编辑节点 |
+| 附件区设置 | `odocAttachArea` | 展开方式、字段、比例、节点和角标 |
+| 文种变更设置 | `odocTypeChangeSettings` | 文种变更规则 |
+| 公文环节映射设置 | `processRelativeSetting` | 公文环节映射 |
+| 在线签批设置 | `wellSignSettings` | 在线签批配置 |
+| 公文元数据设置 | `metaDataSettings` | 公文元数据 |
+| 归档管理设置 | `Archive` | 预归档节点、触发方式、表单和字段映射 |
+| 智能助手 | `OdocAi` | 公文助手、事务公文、智能排版和默认格式 |
+
+## 基础设置
+
+| 设置项 | 配置键 | 值与依赖 | 当前 CLI 配置方式 |
+|---|---|---|---|
+| 公文类型 | `officialType` | `1` 发文、`2` 收文、`3` 签报 | **CLI 已支持**：`--official-type 1|2|3` 或 JSON |
+| 流程标题 | `requestTitleField` | 单行或多行文本字段 | **CLI 已支持**：`--request-title-field <字段名或ID>` |
+| 正文字段 | `flowDocField` | 单选文档浏览框，候选项以 `setting get` 为准 | **CLI 部分支持**：JSON 写字段 ID，尚未实测非空字段 |
+| 正文标题 | `documentTitleField` | 单行或多行文本字段；`-102` 表示流程名称（系统） | **CLI 已支持**：JSON 写字段 ID 或 `-102` |
+| 默认存放目录 | `defaultCat` | 文档目录 | **CLI 未支持**：待补充目录查询和非空保存结构 |
+| 目录区分字段 | `flowDocCatField` | 表单选择字段 | **CLI 已支持**：JSON 写字段 ID |
+| 文档属性设置 | `docPropSettings` | 正文文档属性与流程表单字段的映射 | **CLI 未支持**：待补充映射结构 |
+| 默认打开正文的节点 | `openTextDefaultSelect`、`openTextDefaultNode` | `1` 全部；`2` 选择节点 | **CLI 已支持**：`--open-text-select` 配合 `--open-text-node` |
+| 可编辑正文的节点 | `editTextNode` | 一个或多个流程节点 | **CLI 已支持**：`--edit-text-node <节点名或ID...>` |
+| 编辑时使用预览插件 | `editorReadOnly` | 开关 | **CLI 已支持**：JSON 写布尔值 |
+| 默认预览正文 | `previewDefault` | 开关 | **CLI 已支持**：JSON 写布尔值 |
+
+完整示例：
+
+```json
+{
+  "basic": {
+    "officialType": "1",
+    "requestTitleField": "公文标题字段ID",
+    "flowDocField": "正文浏览框字段ID",
+    "documentTitleField": "-102",
+    "flowDocCatField": "目录区分字段ID",
+    "openTextDefaultSelect": "2",
+    "openTextDefaultNode": ["发起节点ID", "审批节点ID"],
+    "editTextNode": ["发起节点ID"],
+    "editorReadOnly": true,
+    "previewDefault": true
+  }
+}
+```
+
+## 常用功能
+
+| 设置项 | 配置键 | CLI 支持情况 |
+|---|---|---|
+| 只能新建正文 | `newTextNodes` | **CLI 已支持**：JSON |
+| 允许上传 WORD | `uploadWORD` | **CLI 已支持**：`--upload-word` |
+| 允许上传 PDF | `uploadPDF` | **CLI 已支持**：`--upload-pdf` |
+| 允许上传 OFD | `uploadOFD` | **CLI 已支持**：`--upload-ofd` |
+| 保留正文版本 | `saveTempFile` | **CLI 已支持**：JSON |
+| 存为流程草稿 | `isWorkflowDraft` | **CLI 已支持**：JSON |
+| 签字意见分组 | `signGroupMould` | **CLI 部分支持**：可写分组 ID，未提供名称查询 |
+
+上传格式可直接使用 `--upload-word`、`--upload-pdf`、`--upload-ofd`。其余普通开关写入 JSON；签字意见分组按候选分组 ID 配置。
+
+## 正文显示设置
+
+- `isTextInForm`：正文内容显示在流程表单。**CLI 已支持**：`--text-in-form`。
+- `editTextInForm`：允许在表单中直接编辑正文。**CLI 已支持**：JSON。
+- `showTextNewColumn`：正文分栏显示。**CLI 已支持**：JSON。
+- `columnPosition`：正文位置，`1` 左侧、`2` 右侧。**CLI 已支持**：`--column-position`。
+- `textColumnSize`：正文栏占比。**CLI 部分支持**：JSON 可写；启用附件区后实测可能保留原值，须以回读为准。
+- `openTextInFormSelect`、`openTextInFormNode`：正文显示应用节点，`1` 全部、`2` 选择。**CLI 已支持**：JSON 写节点 ID。
+- `showAttributeTab`：正文页面显示文档属性页签。**CLI 已支持**：JSON。
+- `reupload`：发起节点允许重新上传。**CLI 未支持**：实测写入后仍为关闭。
+- `reUploadSelect`、`reUploadNode`：允许重新上传正文的节点。**CLI 已支持**：JSON 写节点 ID。
+- `canChangeEditMould`：发起节点允许更换编辑模板。**CLI 已支持**：JSON。
+
+## 痕迹设置
+
+- `isCompellentMark`：必须保留痕迹。**CLI 已支持**：JSON。
+- `isCancelCheck`：取消审阅。**CLI 已支持**：JSON。
+- `isHideTraces`：编辑正文时默认隐藏痕迹。**CLI 已支持**：JSON。
+- `cleanCopyNodesSelect`、`cleanCopyNodes`：清稿节点，`1` 全部、`2` 选择。**CLI 已支持**：JSON 写节点 ID。
+- `isAutoCleanCopy`：清稿节点保存正文时自动清稿。**CLI 已支持**：JSON。
+
+## 其他设置
+
+- `extFileToDoc`：流程附件转为正文附件。**CLI 已支持**：JSON。
+- `extFileToDocSelect`：选择转为正文附件的字段。**CLI 部分支持**：可写字段 ID，待实测字段选择结构。
+- `keepExtFile`：保留流程附件。**CLI 已支持**：JSON。
+- `defaultDocType`：默认文档类型。**CLI 部分支持**：可写类型值，待补充码表。
+- `printNodeSelect`：打印正文节点。**CLI 部分支持**：可写节点 ID，待补充完整选择结构。
+- `downloadSelect`：正文下载权限。**CLI 部分支持**：可写配置值，待补充完整码表。
+- `syncTitleNodes`：同步正文标题的节点。**CLI 已支持**：JSON 写节点 ID。
+- `useClientNodes`：使用客户端插件的节点。**CLI 已支持**：JSON 写节点 ID。
+- `openSignatureSeal`：启用签名印章。**CLI 已支持**：JSON。
+- `savedBackForm`：保存正文返回表单。**CLI 已支持**：JSON。
+- `savedRemind`：离开正文提醒保存。**CLI 已支持**：JSON。
+- `isTextInFormMobile`：移动端正文附件显示在表单。**CLI 已支持**：JSON。
+- `openAfterSavingMerge`：手动合并文档时自动保存正文。**CLI 已支持**：JSON。
+
+## 模板、排版与签章
+
+- 模板设置：`officialTemplate` 套红模板、`editTemplate` 编辑模板、`printTemplate` 打印模板。**CLI 未支持**。
+- 排版设置：`composingTemplate`。**CLI 未支持**。
+- 签章节点设置：保存为 `signNodeList`，每项包含节点及启用、必填状态。**CLI 部分支持**：JSON 对象数组已实际保存并读回；命令的回读比较可能误报不一致。
+- 正文动作设置：`textActionSetting`。**CLI 未支持**。
+
+模板和排版配置先查询可用模板，再按模板 ID、适用节点及条件配置。签章节点对象数组中的开关由 CLI 转换为平台要求的 `"1"/`"0"`。
+
+## 公文字段与交换
+
+以下设置使用各自的结构化配置：
+
+- `officialFieldSetting`：公文字段设置。**CLI 未支持**。
+- `innerExchangeSetting`：内部交换设置。**CLI 未支持**。
+- `odocTypeChangeSettings`：文种变更设置。**CLI 未支持**。
+- `processRelativeSetting`：公文环节映射。**CLI 未支持**。
+- `wellSignSettings`：在线签批。**CLI 未支持**。
+- `metaDataSettings`：公文元数据。**CLI 未支持**。
+
+逐项补充时记录选择资源的查询方式、保存结构、字段码表及回读结构。
+
+## 公文编号
+
+`odocNumber` 作为完整嵌套对象保存：
+
+- `openOdocNumber`：启用公文文号。**CLI 已支持**：`number` JSON。
+- `odocNumberField`：文号字段。**CLI 部分支持**：可写字段 ID。
+- `numberTypeField`：文号类型字段。**CLI 部分支持**：可写字段 ID。
+- `odocNumberSelect`：`1` 全部、`2` 选择。**CLI 已支持**：`number` JSON。
+- `odocNumberType`：可用文号类型。**CLI 部分支持**：可写类型 ID，未提供名称查询。
+- `odocNumberLink`：生成文号出口。**CLI 部分支持**：可写出口 ID，未提供名称查询。
+- `editNumberNode`：文号可编辑节点。**CLI 已支持**：`number` JSON 写节点 ID。
+
+## 附件区
+
+`odocAttachArea` 作为完整嵌套对象保存。可使用 `--attach-area 1|0` 控制总开关，其余配置写入 `attachmentArea`：
+
+- `attachDefaultOpen`：默认展开。**CLI 已支持**：`attachmentArea` JSON。
+- `attachOpenDirection`：`1` 左侧、`2` 右侧。**CLI 已支持**：`attachmentArea` JSON。
+- `attachOpenNodeSelect`、`attachOpenNode`：默认展开节点。**CLI 已支持**：JSON 写节点 ID。
+- `attachProportion`：附件区占比。**CLI 已支持**：JSON 写百分比数值。
+- `odocProportion`：正文栏占比。**CLI 部分支持**：JSON 可写；启用附件区后实测可能保留原值，须以回读为准。
+- `allowAddFile`：允许上传新附件或添加新文档。**CLI 已支持**：JSON。
+- `attachSelect`、`attachField`：附件区展示字段。**CLI 部分支持**：选择范围可写，字段结构待补充。
+- `subscriptOpen`：启用角标。**CLI 已支持**：JSON。
+- `subscriptStyle`：`1` 数字、`2` 红点。**CLI 已支持**：JSON。
+- `subscriptScope`：`1` 附件数量、`2` 文档数量、`3` 正文数量。**CLI 已支持**：JSON。
+
+## 归档管理
+
+- `archivesNodeOpen`：启用预归档。**CLI 已支持**：JSON；使用 `--archive-node` 时自动开启。
+- `archivesNode`：预归档节点。**CLI 已支持**：`--archive-node <节点名或ID>`。
+- `archivesNodeSelect`：`1` 到达节点、`2` 离开节点。**CLI 已支持**：JSON。
+- `archivesFormSettings`：归档表单设置。**CLI 未支持**。
+- `archivesFormFieldSettings`：归档表单字段映射。**CLI 未支持**。
+
+## 智能助手
+
+- `showAiOdoc`：启用公文助手。**CLI 已支持**：`--ai-odoc`。
+- `showOfficialDoc`：启用事务公文。**CLI 已支持**：JSON。
+- `openAiAbstract`：智能摘要。**CLI 已支持**：`--ai-abstract`。
+- `aiAbstractField`：摘要写入字段。**CLI 部分支持**：JSON 可写字段 ID；实测环境无可选字段，尚未验证非空写入。
+- `openAiFormat`：智能排版。**CLI 已支持**：`--ai-format`。
+- `autoAiFormat`：生成正文后自动排版。**CLI 已支持**：JSON。
+- `defaultFormatTemplate`：默认排版格式。**CLI 部分支持**：可写模板 ID，未提供名称查询。
+
+配置摘要或排版能力时同时开启 `showAiOdoc`。
+
+## 保存形状
+
+CLI 读取完整设置后合并指定修改，再按平台保存形状提交：
+
+| 数据 | 配置输入 | 保存形状 |
+|---|---|---|
+| 开关 | 布尔或 `0/1` | `"1"/`"0"` |
+| ID 清单 | 字符串数组 | 逗号分隔字符串 |
+| 节点清单 | 节点 ID 数组 | 逗号分隔节点 ID |
+| 签章节点 | 对象数组 | 对象数组，内部开关转换为字符串 |
+| 公文编号 | `number` | `odocNumber` 嵌套对象 |
+| 附件区 | `attachmentArea` | `odocAttachArea` 嵌套对象 |
+
+`setting set` 保存后自动回读比对。配置结果以回读值为准。