weaver-e10-builder 1.2.5 → 1.5.2

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

@@ -0,0 +1,124 @@
+# 组织架构 — 人员录入（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） |
+| `e10-cli org employee task <taskId>` | 查某个导入任务的结果（没等、或等超时了，用这个补看） |
+
+导入默认**等结果**：打完 `已导入 N 条 / 失败 M 条` 才结束，**有失败行时退出码非 0**，脚本可以直接判。
+
+| 选项 | 说明 |
+|---|---|
+| `--no-wait` | 提交后立刻返回。⚠ 不等就等于不校验 —— **「已提交」不代表导入成功**，要自己再用 `task` 查 |
+| `--wait-timeout <ms>` | 等结果的超时（默认 60000）。超时不编成功，如实报「仍在处理中」并给 taskId |
+| `--error-file <路径>` | 失败数据的保存路径。默认与源文件同目录、同名 + `.错误数据.xlsx` |
+| `--no-error-file` | 不保存失败数据文件（原因仍会打出来） |
+
+## ⚠ 先 `--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` | 真正执行 |
+| ⑦ | `POST /api/ebatch/getByTaskId` | **导入结果**：条数 / 失败原因 / 错误文件 |
+
+- **⓪ 把 ④ 要的元数据全给了** —— moduleName / functionName / handlerName / serviceName / dataType
+  都不是 CLI 硬编码的，`bizId` 更是每次调用现生成。
+- **①② 的 multipart 字段逐字相同**，② 只多 `preUploadId` 与 `uploadType=common`。
+- ⑤⑥⑦ 的参数全在 **query string**，body 为空。
+
+## 导入结果（⑥ 只是「提交了」，结论在 ⑦）
+
+**⑥ 的响应体只有一个 `true`** —— 条数、失败原因、错误文件**全都不在里面**。只发 ⑥ 就报成功，
+会让**整批失败也显示成「导入已提交」**，所以命令发完 ⑥ 会去轮询 ⑦。
+
+```json
+{"status": -1,
+ "msg": "存在错误数据，下载错误文件查看",
+ "callbackData": "{\"msg\":\"导入失败\",\"errorFileId\":\"...\",\"module\":\"hrm\",\"successCount\":0,\"errorCount\":\"1\"}"}
+```
+
+- **`callbackData` 是一个 JSON 字符串**，要二次解析 —— 条数和错误文件 id 都在里面。
+- ⚠ **`successCount` 是数字、`errorCount` 是字符串**（`1` / `"0"`），同一段 JSON 里类型不一致，两边都得转一遍。
+- ⚠ **`status: 0` 不是「成功」** —— 它是个**中途值**：同一个任务先读到 `status: 0` + `msg: 成功`、
+  `callbackData` 还是空的，几秒后才落成 `-1` + 失败 1 条。**判完成的依据是 `callbackData` 能不能解出来，不是 `status`**；
+  按 `status` 收工就会把失败读成成功。
+- `status: -1` = 存在错误数据，可以直接当终态（命令也这么处理）。
+
+### 失败原因在**单元格批注**里，不在任何一列
+
+导出的失败数据文件里**只有出错的那几行，没有「原因」列** —— 用表格软件打开看值，看不出为什么失败。
+原因挂在**出错单元格的批注（Excel comment）**上，形态是：
+
+| 单元格 | 值 | 批注 |
+|---|---|---|
+| A2 | 人员A | **姓名 重复** |
+
+所以 `import` / `task` 会把批注读出来直接打给你：
+
+```
+导入结果: 人员A.xlsx
+  已导入     0 条
+  失败       1 条
+  平台说明   存在错误数据，下载错误文件查看
+  失败原因
+    第 2 行 · 姓名（人员A）: 姓名 重复
+  失败数据   1323916251655815168 → 人员A.错误数据.xlsx
+```
+
+### 失败数据怎么下来的
+
+```
+GET /api/file/remotedownload/<fileId>/token/true?authModule=ebatch
+  → 302 → 对象存储的签名地址（文件真身在这边，文件名也在这一步给）
+```
+
+下载按**两步**取：先带鉴权拿到 302，再**不带任何鉴权头**去对象存储取字节 ——
+会话凭证不跟着跳转发到第三方域名上。
+
+## 几个坑
+
+- **取 id 的层级三步三样**：① 在 `data.preUploadId`（**有的环境**是 `data.uploadModuleDto.fileid`）、
+  ② 在 `data.fileid`（**小写 d**）、④ 在 `data.data.taskId`（多一层）。照着别的接口的写法套会静默取到空。
+- **① 的返回形状随环境变**：有的环境 `preUploadCheck` 只回 `data.preUploadId`
+  （`data` 下就 `preUploadId` / `uploadType` / `permissionType` 三个键，**没有** `uploadModuleDto`）。
+  两种写法语义相同，命令都认；一个都没有才报错。只认其中一种的话，那条环境整条导入链**第①步就断**。
+- **⑤ 的参数是 `rerviewNum`** —— 平台把 review 拼错了，别"顺手改正"成 `reviewNum`。
+- **`weaTable[0].total` 是 `-1`**，不能拿来当行数；行数看 `data` 数组长度。
+- **`rerviewNum` 只是一次取多少行**，预览到的未必是全部 —— 行数刚好等于上限时命令会提示。
+- **⚠⚠ 分部名写错不会报错 —— 平台会静默新建一个分部，把人放进去。**
+  「分部（必填）」填一个机构里不存在的名字（例如把「泛微北京」写成「泛微北金」），导入**照样回成功**，
+  然后机构里会多出一个同名分部（父级 = 操作者所在组织），人落在里面。**没有报错、没有警告**，
+  `--dry-run` 的预览也看不出来 —— 预览只是把单元格原样回显，**不做任何校验**。
+  所以：**分部名必须是机构里已有的名字**，导之前自己核一遍 —— 一次手误就是一条脏组织数据 + 一个错位的人。
+- **模板里的示例行**（`user001`~`user008`）是平台放的演示数据，**导入前务必删掉**，否则会被当成真人建进去。
+- **`importType` 在 ④ 的报文里出现两次**：顶层是空串、真正生效的在 `uploadSet.customObj` 里。
+
+## 环境差异
+
+`emp/edit/importParam` 是判定「这个环境能不能导入人员」的探针 —— 返回里没有 `bizId` / `functionName`
+就说明该环境不支持，命令会直接报错，不会带着半截参数往下走。

package/skill-docs/references/report/cell-config-echo-guide.md

@@ -28,7 +28,7 @@
 **指纹示例**：`formatterType[0] + '|' + formatter + '|' + font + '|' + backColor`
 相同指纹 → 直接复用已通过的 style 对象引用（或深拷贝），**不再**走 JSON 样例确认。
 
-## 二、数字格式目录（工具栏回显金标准）
+## 二、数字格式目录（工具栏回显参照）
 
 > 来源：设计器静态资源 `main.js` 中格式下拉 `g()` 目录。`￥` 为全角 `U+FFE5`（JSON 中写 `\uFFE5`）。
 

package/skill-docs/references/report/dataset-query-filter-guide.md

@@ -1,7 +1,7 @@
 # 数据集筛选（queryInfoSave）API 写入规范
 
 > **适用场景**：设计器左侧「数据集 → 筛选条件」、行级数据权限、整表预过滤。 
-> **金标准报表**：`1304979556231593985`（EBU 经营数据统计） 
+> **参考报表**：`1304979556231593985`（EBU 经营数据统计） 
 > **代码实现**：`本地工作目录` → `build_*_dataset_query_filter()` / `ensure_*_dataset_filter()` 
 > **执行**：`python 本地工作目录`
 
@@ -160,7 +160,7 @@ def _build_compare_form_field(origin_field):
 
 ---
 
-## 七、EBU 金标准示例
+## 七、EBU 参考示例
 
 报表 `1304979556231593985`
 
@@ -186,7 +186,7 @@ rootStr：`( 负责人姓名 等于 '{lastname}' ) AND ( 创建者 等于 '{user
 
 rootStr：`(( 核算机构 不等于合同种类 ) 或 ( 创建时间 开头包含 '{thisyear}' ))`
 
-### 7.3 历史验证过的其他写法（按需）
+### 7.3 其他可用写法（按需）
 
 | 场景 | func | value |
 |------|------|-------|

package/skill-docs/references/report/date-range-query-reference.md

@@ -1,6 +1,6 @@
 # 日期区间查询条件选项参考（已验证样例）
 
-> **金标准来源**：报表 `1304979556231593985`（EBU 经营数据统计）· 查询条件「入职时间」 
+> **来源**：报表 `1304979556231593985`（EBU 经营数据统计）· 查询条件「入职时间」 
 > **完整规范**：`query-condition-api-guide.md`（条件字段形态、系统参数默认值、验证清单） 
 > **filterParam 快照**：`outputs/join_date_filterparam.json`（运行 `本地工作目录` 可重新导出） 
 > **代码实现**：`本地工作目录` → `_default_date_filter_param()`
@@ -97,6 +97,6 @@
 | 文件 | 用途 |
 |------|------|
 | `query-condition-api-guide.md` | 查询条件总规范 |
-| `outputs/join_date_filterparam.json` | filterParam 金标准 |
+| `outputs/join_date_filterparam.json` | filterParam 参考样本 |
 | `本地工作目录` | 生成/修复 |
 | `本地工作目录` | 扫描导出 |

package/skill-docs/references/report/query-condition-api-guide.md

@@ -1,7 +1,7 @@
 # 查询条件 API 写入规范
 
 > **适用场景**：通过 `saveQueryItem` / `saveQueryConfig` API 或脚本添加、修复报表查询条件。
-> **金标准报表**：`1304979556231593985`（EBU 经营数据统计）
+> **参考报表**：`1304979556231593985`（EBU 经营数据统计）
 > **代码实现**：`本地工作目录` → `ensure_query_conditions()`；执行 `python 本地工作目录`
 > **核心规则**：数据集合选取后，**选择类型未特别指定 SQL 时，一律默认为「条件字段」**。
 
@@ -43,7 +43,7 @@
 
 ## 二、条件字段标准形态（saveQueryItem）
 
-设计器 save 后回读的金标准结构：
+设计器 save 后回读的基准结构：
 
 | 字段 | 条件字段正确值 |
 |------|----------------|
@@ -118,7 +118,7 @@ await saveQueryItem({ reportId, queryItems: '{}' }); // conditions 缺失 → 50
 
 ### 2.1 显示方式（强制 · 不可不选）
 
-> **✅ 终局定案（2026-09-11 · 以「设计器手工配置的真实条件」为金标准反推）**
+> **✅ 终局定案（2026-09-11 · 以「设计器手工配置的真实条件」为基准反推）**
 >
 > 条件级「显示方式」的正确落库值是 **JSON 数组字符串**：
 >
@@ -278,7 +278,7 @@ Content-Disposition: form-data; name="queryItems"
 | 条件级与报表级是两个独立字段，互不影响 | ❌ 错。`updateQueryType` 用 `queryType` **批量覆盖所有条件**（§2.1.3 真正根因） |
 | `updateQueryType` 只改报表级「高级搜索显示形式」 | ❌ 错。它会把入参写进每条条件 → 长码一键摧毁全表回显 |
 
-**旧结论怎么来的 / 为什么错**：早期用 JS 合成事件点击条件 tag，实际点到了**左侧字段面板**的「显示方式」（那是字段属性，非条件显示方式），读取勾选态得到假信号；且未把「人工配置的条件」作为金标准对照。**修复方式**：改用 **CDP `Input.dispatchMouseEvent` 真实鼠标事件**点条件 tag，读「编辑查询条件」弹窗，并以人工条件为参照。
+**旧结论怎么来的 / 为什么错**：早期用 JS 合成事件点击条件 tag，实际点到了**左侧字段面板**的「显示方式」（那是字段属性，非条件显示方式），读取勾选态得到假信号；且未把「人工配置的条件」作为基准对照。**修复方式**：改用 **CDP `Input.dispatchMouseEvent` 真实鼠标事件**点条件 tag，读「编辑查询条件」弹窗，并以人工条件为参照。
 
 **真正根因的发现路径**：给 `save` 加「落库后回读自检」时，发现**刚写入的数组被回读成长码** → 隔离实验证明只有 `saveQueryItem` 时数组完好，一旦再调 `updateQueryType` 即被批量覆盖 → 穷举入参证明 `updateQueryType` 是「全表条件 `queryType` 批量写」。**AI 自检回读是抓到它的关键手段**，务必保留。
 
@@ -297,7 +297,7 @@ e10-cli report query fix-echo <reportId> --app-id <appId>   # 长码/空值 →
 e10-cli report query verify <reportId> --app-id <appId> --fix # 体检 Q1~Q10 + 幂等修复
 ```
 
-**设计器真实保存形态（金标准，从 `saveQueryItem` 实际请求）**
+**设计器真实保存形态（基准，从 `saveQueryItem` 实际请求）**
 
 ```json
 {
@@ -339,7 +339,7 @@ e10-cli report query verify <reportId> --app-id <appId> --fix # 体检 Q1~Q10 +
 | 唯一功能读点 | `SheetServiceImpl`：取**第一条**高级搜索条件的 `advancedSearchType`，`=='openCondition'` → `isOpenCondition=true` |
 | 页面效果 | `isOpenCondition=true` → 报表页查询区**展开铺开**（「展开条件」）；否则 → **默认样式**（右上角搜索图标，点击才展开） |
 | 设计器入口 | 报表级「查询设置」弹窗的 **高级搜索显示形式：默认样式 / 展开条件** |
-| 人工条件（金标准） | **该键不存在**（`undefined`），平台不主动写 |
+| 人工条件（基准） | **该键不存在**（`undefined`），平台不主动写 |
 
 **硬规则**
 
@@ -438,7 +438,7 @@ e10-cli report fix query-default --report-id <id> --app-id <appId> --all --show-
 
 > **事故**：同报表查询条件「销售部门」绑定字段 `originFieldType=Department`，但设计器关联类型显示为空/默认**人员**。**定案根因：`browserType` 写成了简写 `[{"id":"HrmDepartmentComInfo"}]`，缺少 `name`/`type` 等字段 → 前端无法解析显示名 → 退回默认「人员」标签页。**
 
-**设计器真实形态（金标准）**：`browserType` 是 **全字段富对象数组**，关键字段 `name`（显示名）、`type`（`department`/`employee`）、`module`、`groupId`、`tenantKey`、`dataId`、`labelId`、`id`。**`browserTypeStr` 才是落库判据**（服务端存 `[{"id":"HrmDepartmentComInfo"}]` 形式的字符串）。
+**设计器真实形态（基准）**：`browserType` 是 **全字段富对象数组**，关键字段 `name`（显示名）、`type`（`department`/`employee`）、`module`、`groupId`、`tenantKey`、`dataId`、`labelId`、`id`。**`browserTypeStr` 才是落库判据**（服务端存 `[{"id":"HrmDepartmentComInfo"}]` 形式的字符串）。
 
 | 字段 `originFieldType` | `displayType` | `browserTypeStr`（落库） | 设计器关联类型 |
 |------------------------|---------------|--------------------------|----------------|
@@ -490,7 +490,7 @@ queryType 以 "[" 开头 → 数组 → UI 勾选正常 ✅
 queryType 是其它字符串 → 退化 → UI 不勾选 ❌（改写为 '["advance"]'）
 ```
 
-> 复现路径存档：前端 bundle 经 CDP `Debugger.getScriptSource` 导出至 `本地工作目录`
+> 来源：前端 bundle 经 CDP `Debugger.getScriptSource` 导出至 `本地工作目录`
 > （`route_DatasetList.js` 179879B / `route_ReportDesigner.js` 702877B / `lib.js` 661658B）；
 > UI 回显用 `_q_real2.py`（CDP `Input.dispatchMouseEvent` 真实鼠标点击条件 tag + 读「编辑查询条件」弹窗 checkbox）。
 
@@ -579,7 +579,7 @@ POST /api/bs/edc/report/saveQueryItem (multipart: reportId + queryItems 单对
 | 3 | `conditions` | **非 null 数组**，至少 1 个 `{dataSetId, fieldId, relation}` |
 | 4 | Header | `ebBusinessId` = 报表所属 **appId**；`eteamsid` + Cookie |
 | 5 | 多条条件 | **多次** POST，每次一条；不要一次塞数组 |
-| 6 | 对照金标准 | 先 `getQueryItem` 拉已有报表一条，改 `text`/`fieldId` 再 save |
+| 6 | 对照基准 | 先 `getQueryItem` 拉已有报表一条，改 `text`/`fieldId` 再 save |
 
 **不要**：为排 500 去开浏览器扫页（浪费）；先按上表自检。仍 500 时看响应 `msg` 是否权限/报表不存在，再问用户。
 
@@ -803,7 +803,7 @@ function inferQueryDisplay(text, fieldMeta) {
 
 ## 七、数据集筛选（设计器左侧 · 行级权限）
 
-> **完整规范已独立成文**：`dataset-query-filter-guide.md`（func 对照、字段对比、日期 format、AND/OR、EBU 金标准、验证清单）。
+> **完整规范已独立成文**：`dataset-query-filter-guide.md`（func 对照、字段对比、日期 format、AND/OR、EBU 参考样本、验证清单）。
 > 本节仅保留与高级搜索的边界说明。
 
 **与高级搜索不同**：设计器左侧数据集右键「筛选条件」走 **`queryInfoSave` / `queryInfoGet`**（`conditionData` + `otherData`），**不是** `saveQueryItem`。
@@ -886,5 +886,5 @@ function inferQueryDisplay(text, fieldMeta) {
 | `report-building-guide.md` §6 | 设计器操作步骤 |
 | `report-config-schema.md` §五 | Schema 摘要 |
 | `SKILL.md` §6.3–§6.4 | Agent 步骤入口 |
-| `outputs/join_date_filterparam.json` | filterParam 金标准 |
+| `outputs/join_date_filterparam.json` | filterParam 参考样本 |
 | `本地工作目录` | 生成/修复实现 |

package/skill-docs/references/report/report-designer-feature-map.md

@@ -488,7 +488,7 @@ pageNo=1&pageSize=10&dateRange=["",""]&sheetId=<reportId>&versionName=&creators=
 | `designKey` | 设计器会话 UUID |
 | `pageSetting` | JSON 数组，含 `split`（分页/分栏）、`scrollPage` 等 |
 
-### 11.4 复现实际请求
+### 11.4 对照实际请求
 
 ```bash
 cd 本地工作目录

package/skill-docs/references/report/report-permission-guide.md

@@ -75,7 +75,7 @@ flowchart TB
 | 外部联系人 | `external` | `obj_id_external` | `external` | `7` | 外部人 ID | 须 browser 查真实 ID |
 | 所有外部人 | `allExternal` | （无） | `allExternal` | `12` | `0` | 无对象选择框 |
 
-> **targetType 金标准**（`edc_report_ph_report_view` 的 `org_config.typeEnum`，weaver-edcreportd SQL）：
+> **targetType 判断依据**（`edc_report_ph_report_view` 的 `org_config.typeEnum`，weaver-edcreportd SQL）：
 > 人员 `1|17` · 部门 `2|3|4|…` · 分部 `5|6|7|…` · **角色 `10`** · **群组(channel) `14|1411`** · 岗位 `12|13|…` · 外部 `110` · 所有人 `11`
 > 写入前务必 `table/list/new` 回读；**禁止**把角色写成 `targetType:3`、群组写成 `targetType:5`（会分别落库为部门/分部）。
 > **安全级别**：通用项均可带 `seclevel: {"min": -999, "max": 999}`（UI「安全级别」列）。
@@ -272,7 +272,7 @@ Content-Type: application/json
 ]
 ```
 
-> **矩阵字段 JSON 结构**因「矩阵表 vs e-Builder 表单」及租户配置而异，**必须以设计器 Network 实际请求为金标准**；Skill 禁止臆造 `matrixConditionData` / `matrixValueRelation` 内部键名。
+> **矩阵字段 JSON 结构**因「矩阵表 vs e-Builder 表单」及租户配置而异，**必须以设计器 Network 实际请求为准**；Skill 禁止臆造 `matrixConditionData` / `matrixValueRelation` 内部键名。
 
 ---
 

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