weaver-e10-builder 1.6.11 → 1.6.13

package/skill-docs/references/common/guide-plan-template.md

@@ -12,7 +12,7 @@
 ## 搭建计划
 
 > `[ ]` 为未完成；写入且按该项风险完成必要核验后，才改 `[x]` 并填写真实 ID 或结果。尚待后续资源的项保留 `[ ]` 并写明依赖。
-> 来源可用需求文档章节、表格或图片标题。已有资源先只读盘点，记明复用/修改/新建及实际 ID。
+> 来源可用需求文档章节、表格或图片标题。已有资源先只读盘点，按[资源复用判定](map.md#资源复用判定默认新建)决定复用或新建，记明理由、差异及实际 ID；**默认新建**。
 
 ### 0. 环境与范围
 - 目标环境/profile：<名称与地址>；所属机构：<名称/ID>；主应用：<名称/ID>
@@ -60,11 +60,14 @@
 | 菜单/页面 <名称> | 新建/复用 | <来源、入口及目标> | 视图/流程/页面 | 待回填 ID |
 
 > 角色和矩阵先用 `role list`、`matrix list` 只读盘点同名资源及归属、成员或数据行，记录候选 ID，并与用户逐项确认复用还是新建。复用但需补成员或数据行的，在对应功能批次单独列项；没有矩阵需求则不创建。
+>
+> 表单、应用等资源按[资源复用判定](map.md#资源复用判定默认新建)处理，默认新建。复用须在本表“决策与归属”写理由，并补需求项→现有字段/配置的映射；只允许新增字段，不改已有字段的名称、类型、选项、默认值和显示属性。需改存量结构、有数据或引用关系不明时新建。参考现有资源的命名和语义不构成复用，不得继承其 ID 与配置。
 
 #### 1.1 表单字段与布局蓝图（每张表单各一份）
 
 ##### 表单：<名称>；资源决策：<新建/复用>；objId/formId：<待回填>；来源：<章节>
 - 布局：FLOW/EXCEL；已有表单改造时记录现有布局及保留要求。
+- 复用映射：复用已有表单时逐项写需求字段→现有字段（复用/新增/改不了）；“改不了”保持未完成并标“待确认”，不静默绕过。
 - 字段清单：逐字段写主表/明细表、名称、componentKey、选项、默认值、长度/精度、关联目标、公式及明确的必填/只读/隐藏/独占一行/分组。字段名含中英文时分别记录。
 - 明细表：<名称、字段、层级>；二级明细逐条记录父明细→子明细、父子行标识及默认展开要求。
 - 虚拟表：<来源类别与资源ID、稳定主键、来源字段→展示类型映射>。

package/skill-docs/references/common/map.md

@@ -4,7 +4,7 @@
 
 ## 使用方法与状态
 
-1. 逐段阅读正文、表格和图片，将每条业务要求映射到资源与配置项，记录原文来源、所属应用/表单/视图/流程、前置依赖及可观察结果。已有资源先只读盘点，再决定复用、修改或新建。
+1. 逐段阅读正文、表格和图片，将每条业务要求映射到资源与配置项，记录原文来源、所属应用/表单/视图/流程、前置依赖及可观察结果。已有资源先只读盘点，再按[资源复用判定](#资源复用判定默认新建)决定复用或新建；**默认新建**，复用须写出理由与差异。
 2. 需求含完整布局样表时，按[布局规划](../form/layout/planning.md)保留标题、分组、同排、空白与字段顺序，并同时写入字段清单和布局蓝图。每张表单创建前确认 FLOW 或 EXCEL。
 3. 规划状态区分：**待业务确认**（语义或取值有歧义）、**待环境核查**（资源、权限或环境行为未证实）、**需其他方式补充**（现有 CLI 只能完成一部分）、**已确认无法实现**（核实无可行路径）。只有最后一种写入 plan 的“无法实现的项”，原需求项保持未完成。
 4. 按资源依赖组织 plan；关键配置写明读回点和最小业务验收点。接口保存、配置读回与页面实际生效是不同层次，按风险选择必要的检查。
@@ -45,6 +45,30 @@
 | ESB 系统接口 | 从接口文档创建对外接口定义 | 写系统池、接口清单和文档来源 | 区分接口定义与动作流 HTTP 调用；验收创建结果 | [接口导入](../esb-interface/guide-import.md) |
 | 组织数据 | 维护部门、人员等基础数据 | 写机构归属、人员来源和导入范围 | 批量导入先预检；验收数据和归属 | [组织](../hrm/guide-org-employee.md) |
 
+### 资源复用判定（默认新建）
+
+新建是完整写入，改存量受已有字段、数据和引用约束。规划时先按本节判定；结论写入 plan 的资源清单。
+
+**只有同时满足以下条件才复用**：
+
+1. 需求明确要求复用该资源；或现有对象与需求是同一业务对象，现有字段集覆盖需求的业务含义。
+2. 差异只有**新增字段**：不改已有字段的名称、类型、选项、默认值和显示属性，也不删除字段。
+3. 已有数据、既有布局和其他资源对它的引用都不受本次改动影响；不确定时先只读核对，不按“应该没问题”处理。
+
+**出现任一情况改新建**：
+
+- 字段名、类型、选项或结构与需求不一致，且必须改动；
+- 需要删除或合并已有字段；
+- 已有数据且本次要改结构；
+- 仅名称相似或用途相近，不能确认是同一业务对象；
+- 无法核对其归属、数据量和被引用关系。
+
+**复用必须写清**：复用理由、需求项→现有字段/配置的映射、无法改动的项及处理方式。无法改动的项保持未完成并标“待确认”，不得静默绕过、改用近似配置或改需求冒充完成。
+
+**应用层复用**（已有应用、底座应用）：额外评估菜单、权限、既有表单/流程/动作流是否引用该应用，以及新资源与既有资源是否相互耦合；写不出复用理由时新建应用。
+
+**参考不等于复用**：为对齐命名、字段语义或交互而阅读现有资源时，不得继承其 ID、布局和配置；此类情况一律按新建处理。
+
 ## 二、功能配置地图：资源建成后还要做什么
 
 下表用于识别应写入 plan 的配置，不表示每个项目都要启用。具体取值和命令由专题指南确定。
@@ -60,7 +84,7 @@
 | 布局样表 | 从完整表格提取空间排布 | 写 FLOW/EXCEL、标题、行列、同排、空白和合并 | 字段清单与布局蓝图同时保留；验收实际位置 | [布局规划](../form/layout/planning.md) |
 | 字段分组 | 将业务字段归入折叠分段 | 写分组名称、顺序及成员字段 | 需求明确时配置；验收字段归属 | [布局规划](../form/layout/planning.md) |
 | 关联字段 | 选择客户、合同、流程等原生业务对象 | 写字段子类、目标对象、单/多选 | 关联对象与通用浏览来源分别选型；验收选择范围 | [字段码表](../form/ref-form-fields.md) |
-| 浏览数据定义 | 限定浏览可选数据、默认搜索及弹窗 Tab | 先查可配置字段，再查各字段开放的配置项与候选值 | 按浏览来源适配；验收实际可选数据、搜索与 Tab | [浏览数据定义](../form/guide-browser-definition.md) |
+| 浏览数据定义 | 限定浏览可选数据、默认搜索及弹窗 Tab | 先查配置归属和可配置字段，再按来源读取候选项 | 验收实际可选数据、搜索与 Tab | [浏览数据定义](../form/guide-browser-definition.md)、[数据范围](../form/guide-browser-scope.md) |
 | 二级明细 | 父级每行挂载子级明细记录 | 主/子明细表；写父子行标识与层级 | 子表归属需按行核对 | [二级明细](../form/guide-form-sub-detail.md) |
 | 字段公式 | 根据其他字段计算目标值 | 写表达式、目标字段和精度 | 验收公式读回与样例计算 | [公式](../form/guide-form-formula-functions.md) |
 | 函数联动 | 字段变动或载入时赋值计算 | 写触发字段、目标字段、事件和表达式 | 与静态字段公式分开；验收触发结果 | [函数联动](../form/guide-formula-linkage.md) |
@@ -135,7 +159,7 @@
 
 ## 四、常见依赖与计划顺序
 
-这些是依赖关系，不替代 [计划模板](guide-plan-template.md)的三段执行规则。已有且符合要求的资源可复用，按真实 ID 解除依赖。
+这些是依赖关系，不替代 [计划模板](guide-plan-template.md)的三段执行规则。只有通过[资源复用判定](#资源复用判定默认新建)的资源才复用，并按真实 ID 解除依赖。
 
 ```text
 环境/机构 → 主应用与角色 → 表单/字段/明细 → 布局与默认台账 → 视图/权限/按钮
@@ -154,7 +178,7 @@
 |---|---|
 | 业务含义不清 | 写出不同解释会改变的字段、权限或路由，提出具体确认问题 |
 | 文档内容冲突 | 标出原文位置和受影响配置，待用户确认后定稿 |
-| 资源新建/复用不明 | 只读盘点同名资源、归属和 ID；不能唯一确定时标“待环境核查”或请用户选择 |
+| 资源新建/复用不明 | 默认新建：只读盘点同名资源、归属和 ID 后按[资源复用判定](#资源复用判定默认新建)核对；不能唯一确定或需改存量结构时新建，并向用户说明取舍 |
 | 布局或字段来源缺失 | 确认 FLOW/EXCEL、样表结构、目标字段和关联来源；保留可确认内容 |
 | 环境能力尚未核实 | 列最小查询/验证动作，保持“待环境核查”，不直接判为无法实现 |
 | 仅能部分配置 | 分别列可完成部分与需页面/其他系统补充部分，注明责任和验收方式 |

package/skill-docs/references/common/ref-cli-commands.md

@@ -108,14 +108,17 @@
 | `e10-cli form permission archive <list\|add\|remove\|card> <objId> <appId> --workflow <workflowId>` | **流程归档权限**（归档后数据对谁可见/可改/可删，**按流程各一套**，与共享权限不同）。`add --target <general/creator/field/matrix>`：`general` 通用对象配 `--org-type`+`--org-id`；`creator` 创建人相关配 `--creator-related 0~7`；`field` 字段相关配 `--field <字段id或名>`（`--sub-form-id` 支持明细字段，未收录的字段类型需 `--org-type field_xxx` 显式指定）；`matrix` 矩阵相关配 `--matrix`（真矩阵）或 `--eb-form`（e-Builder 表单）+ `--matrix-value`（e-Builder 表单按名取它自己的人员字段/创建者，人员字段 valueType=resource），另可加**矩阵条件**（e-Builder 表单的条件列自动取该表单主表字段） `--matrix-condition '<json>'`（可重复 / `@文件` 给数组；右值三选一 `value` 固定值 / `field` 引本表单字段 / `fieldRef` 直给字段描述符）+ `--matrix-condition-relation and\|or`。权限码 `5/view` 归档查看、`6/edit` 归档编辑、`7/delete` 归档删除（**归档查看是系统默认必选，界面不可取消；`--rights` 没传 view 会自动并入**）；归档附件另算 `501/view`、`502/download`、`503/edit`（**不是**共享权限的 401/402；**归档附件查看 501 同属系统必选，不给 `--file-rights` 也会带上**）。保存后按 ID 回读逐项核对；`card <workflowId> <appId> [--set 0\|1]` 读写归档卡片开关。详见 `form/guide-form-archive-permission.md` |
 | `e10-cli form permission <list\|add\|remove\|rebuild> <objId> <appId>` | 权限通用管理及兼容入口。新建权限与数据权限分开；旧 `add --right-type` 保留兼容。`list` 查看全部分类；`remove --right-id <id[,id...]>` 删除一条或多条权限；添加后提示 `isShowRebuild=2` 时执行 `rebuild` |
 | `e10-cli form list-view <objId> <appId>` | 查看台账/数据列表（获取 viewId 用于菜单配置） |
-| `e10-cli form list-columns <objId> <appId> <listId> [--add <fieldId...>] [--remove <fieldId...>] [--set @columns.json] [--terminal pc/mobile] [--pc-only]` | 查看/批量设置台账显示列。增量追加、移除或整组指定顺序/列宽/格式；整组模式与增删互斥。支持主表和明细子字段，保留已有列未指定属性、事件及数据主键；一次保存并回读核对目标列和另一终端。详见 `references/form/guide-list-columns.md` |
+| `e10-cli form list-columns <objId> <appId> <listId> [--add <fieldId...>] [--remove <fieldId...>] [--set @columns.json] [--terminal pc/mobile] [--pc-only]` | 查看/批量设置台账显示列。增量追加、移除或整组指定顺序/列宽/格式；整组模式与增删互斥。支持主表和明细子字段，保留已有列未指定属性、事件及数据主键；一次保存并回读核对目标列和另一终端。**只作用于表格式 `tableField`**：列表式/卡片视图（NList）会直接报错并指向 `form nlist`。详见 `references/form/guide-list-columns.md` |
+| `e10-cli form list-columns attr show\|set <objId> <appId> <listId> --field <fieldId> [--align left\|center\|right] [--fixed on\|off] [--width N] [--width-unit px\|%] [--editable 0\|1] [--rich-editor on\|off] [--show-name <名>] [--conversion '<json>'] [--terminal pc/mobile]` | 列属性层（`getListFields`/`saveListFields`）：对齐、冻结、列宽、显示名、可编辑、富文本、显示转换。只改目标列，另一端与其它列原样回传，保存后回读目标列断言 |
+| `e10-cli form list-filter sql get\|set <objId> <appId> <listId> [--sql @sql.json] [--base-sql <sql>] [--dialect "mysql=<sql>"] [--dataset-id <id>]` | **SQL 条件**（`filter.type=sql_where`）：SQL 正文写进独立的 `sqlfragments` 数据集，视图只记数据集 ID。`sql.json` 键：`base` + `mysql/oracle/sqlserver/pg/dm/kingbase/st/oceanbase`（对应平台 `mysqlSql/oracleSql/sqlserverSql/pgSql/dmSql/kingBaseSql/stSql/oceanbaseMysql`）。主表别名 `t1`、明细 `d1`、`{参数}` 为运行时占位；保存后回读视图条件与数据集正文。`--dataset-id` 只切绑定不新建；`--ignore-empty on|off` 写「变量值为空时不参与过滤」（`filterIsNull`：on→false，off→true）。详见 `form/guide-form-view.md` |
+| `e10-cli form list-filter http get\|set <objId> <appId> <listId> --url <url> [--method GET\|POST] [--param name=value] [--header name=value] [--form name=value] [--payload '<json>'] [--ignore-empty on\|off]` | **自定义接口条件**（`filter.type=http`）：URL + 方法 + Params/Headers/Body(form-data 或 JSON)。落库 `data.{method,contentType,url,urlParams[],headers[],formData[],payload}`，`rootStr="自定义接口"`，PC/移动端同写；保存后回读 URL 与方法。详见 `form/guide-form-view.md` |
+| `e10-cli form list-config get\|set <objId> <appId> <listId> [--head-merge on\|off] [--hide-checkbox on\|off] [--page-size N] [--set-top 1\|0] [--set-top-type <s>] [--set-top-rule '<json>'] [--batch-edit-value on\|off] [--batch-add-fields '<json>'] [--batch-edit-fields '<json>'] [--can-delete on\|off] [--terminal pc/mobile] [--pc-only]` | 视图基础开关（`getNListConfig` 顶层键）：表头合并、隐藏 check 框、分页条数、数据置顶、批量、允许删除。只改点名键、其余原样回写，保存后只回读被改的键；`get` 额外展示操作按钮摘要（只读，本版不写 `buttonConfig`）。`headMerge`/`setTop` 的 UI 文案与极性待真机核对 |
 | `e10-cli form list-unit <objId> <appId> <listId> <fieldId> <后缀> [--prefix <前缀>] [--clear] [--pc-only]` | 设置台账列显示**单位**（后缀/前缀）。平台无字段级单位属性，靠列表列配置 `showTrans.ruleConfig.suffix/prefix` 实现。如 `form list-unit ... <fieldId> "（元）"` 让列显示单位；`--clear` 清除 |
 | `e10-cli form list-format <objId> <appId> <listId> <fieldId> [--thousandths] [--no-thousandths] [--decimal <n>] [--clear] [--pc-only]` | 查看/设置台账列**千分位/小数位**（Number/Money 列）。不加参数显示当前；`--thousandths` 开千分位（列 `format:"THOUSANDS"`）、`--no-thousandths` 关、`--decimal <n>` 小数位数（`decimalLength`）、`--clear` 清除恢复默认。与 `list-unit`（单位，走 `showTrans`）是两套不同机制。**自动保留移动端配置** |
 | `e10-cli form list-click <objId> <appId> <listId> <fieldId> [--target <formObjId>] [--open-mode <模式>] [--win-size <尺寸>] [--clear] [--pc-only]` | 设置台账列**点击跳转**。`--open-mode` 支持当前页面/新窗口/弹出窗口/右侧滑出/右侧推出；`--win-size` 仅用于滑出/推出，具体数值按需求填写：百分比使用 `%`（0～100），像素使用 `px`，两种单位不可混用。缺省 `800px` |
 | `e10-cli form ebuilder-columns <objId> <appId> <fieldId> [字段名/ID...] [--clear]` | 设置 EBuilder 关联字段的**浏览显示列**（存在字段配置 `ffDisplayColumns:{id,name}[]`）。**缺省查看**：列出当前显示列 + 目标表单全部**业务字段候选**（系统字段已自动过滤，不设显示列时浏览走平台默认列会带系统字段）；**传目标表业务字段名/ID 设置**，系统字段会被拦截提示"系统字段不能设为显示列"；`--clear` 清空。关联浏览显示哪些字段（只留业务字段） |
-| `e10-cli form ebuilder-scope <get\|set\|clear> <objId> <appId> <fieldId>` | **浏览数据定义 → 数据范围设置**（关联浏览字段，限定被关联数据须满足条件才可选，如关联客户只选"客户状态=启用"的）。走 `browserDataScope` 接口（独立于字段布局）。`set --rules '[{"field":"客户状态","operator":"eq","value":"启用"}]'`（选项类 value 用选项名，CLI 自动解析 valueKey）；`--logic and/or` 多规则关系；`--fill-null` 关联字段为空时填充；`get` 读已设条件；`clear` 清空。**这是关联浏览筛选的正解**，旧 `ebuilder-filter` 走 layout/save 不被设计器识别 |
 | `e10-cli form-engine browser-definition inspect\|describe <formId> [<fieldId>] --module ebuilderform\|workflow\|biaoge [--app-id <appId>] [--workflow-id <id>]` | 先列出表单内可配置的浏览字段、各字段高级搜索／范围／Tab 的平台支持和 CLI 适配状态；再查询指定字段的候选项与当前配置。EB 表单须提供 `--app-id`。**表单绑定工作流程时，浏览数据定义必须在流程的「高级设置 → 浏览数据定义」配置；表单级记录与流程记录是两套数据，流程只读自己的记录，表单上的同名字段配置对流程等于无效，不是被流程配置覆盖。** CLI 用关联表单 formId 加 `--module workflow --workflow-id <流程ID>`。详见 `form/guide-browser-definition.md` |
-| `e10-cli form-engine browser-definition search\|scope\|tabs get\|set <formId> <fieldId> --module ...` | 按字段已开放的能力分别配置高级搜索、数据范围和浏览 Tab；`get` 先读候选结构与现值，`set` 写入并回读。不同浏览来源走不同适配器，未适配项明确拒绝。**流程场景必须带 `--module workflow --workflow-id <流程ID>`；`form ebuilder-scope` 的表单级配置不会写入流程高级设置，也不会在流程中生效。** 详见 `form/guide-browser-definition.md` |
+| `e10-cli form-engine browser-definition search\|scope\|tabs get\|set <formId> <fieldId> --module ...` | 按字段已开放的能力分别配置高级搜索、数据范围和浏览 Tab；`get` 先读候选结构与现值，`set` 写入并回读。关联 EBuilder／自定义浏览框的 `scope set --tree` 按左侧字段实时操作符编译已知的混合嵌套条件；`--config` 写平台原始完整树，旧 `--rules` 仅关联 EBuilder 单层条件；`scope clear` 目前仅适用于关联 EBuilder。不同浏览来源走不同适配器，未适配项明确拒绝。**流程场景必须带 `--module workflow --workflow-id <流程ID>`。** 先读 `form/guide-browser-definition.md` 判断归属，再读 `form/guide-browser-scope.md` 配数据范围 |
 | `e10-cli form validate list <objId> <appId>` | 查看表单**查重规则**（字段重复校验，多字段 AND）。`add <objId> <appId> <字段名...> [--help 提示] [--remind]` 新增（缺省禁止提交 NOSUBMISSION，`--remind` 仅提醒）。**`--help` 会建成多语言标签、存的是标签 id**（平台只收 id，传文本会被拒「提示内容格式不正确」；`list` 会解回文本显示，缓存原因刚建完约 10 秒内可能仍显示 id）；`update <objId> <appId> <ruleId> [--fields <名...>] [--help <文本>] [--remind\|--no-remind]` **修改**（只改传入项，其余保持；**checkFields 是整组替换**，命令内部会把完整字段一起回传，不会丢字段；`--help` 支持 `#[字段名]#` 插入变量，自动转成平台片段 `<a>#[字段id]#</a>`，也支持 `@文件`）；`delete <objId> <appId> <ruleId>` 删除。项目名称重名/工时日期重复不允许 |
 | `e10-cli form add-detail-table <objId> <appId> <明细表名> [首字段名] [--no-place] [--init]` | 给**已存在的主表**加明细子表（saveSubForm 建子表 + 加首字段使其可见），**默认增量放进现有布局**（复制临时布局取平台生成的容器组件，原布局不重建）。`--data-key <物理表名>`、`--first-field-type <类型>`（默认 Text）、`--first-field-data-key <编码>`（首字段字段编码，缺省取首字段名拼音首字母，与 `add-field` 一致）。⚠ **空子表平台会过滤掉、布局里看不见**，首字段名强烈建议传；`--no-place` 只建表不排布局；`--init` 改用整表重建（会换样式模板并重排已有位置）。后续往明细里加字段用 `form add-field --sub-form-id <subFormId>`：建表时一次性带明细用 `form create` 的 fields.json `DetailTable`+`formFields`。详见 `references/form/layout/incremental.md` |
 | `e10-cli form rename-detail-table <objId> <appId> <subFormId\|明细表名> <新名称> [--describe <描述>]` | **修改明细表名称**（同步子表标题、字段引用名与布局 DetailTable 标题）。按 subFormId 或当前名称定位；保存后回读子表标题与布局标题。当前名称与旧值同名、明细表重名、读不到物理表记录 id 或回读不一致会报错；`--describe` 可选同时改描述。流程表单暂不提供 |
@@ -136,10 +139,11 @@
 | `e10-cli form list-permission <objId> <appId> <listId> [--add-all] [--add-user <userId> --name <name>] [--add-role <roleId> [--name <name>]] [--add-matrix <矩阵id> --name <name>] [--share-level <n>] [--seclevel <min>-<max>] [--add-raw '<json>'] [--remove <id>] [--remove-all] [--clear]` | 查看/配置**台账视图权限**（谁能查看这个台账）。`--add-all` 所有人（自动把空 dataid 与 0 视为同一主体，避免重复）、`--add-user` 人员、`--add-role` 角色、`--add-matrix` 矩阵（同 `form permission archive` 的矩阵条件参数：`--matrix-condition` / `--matrix-condition-relation` / `--matrix-condition-comp-type` / `--matrix-condition-raw`）。`--remove <id>` 删除指定权限；`--remove-all` 删除全部“所有人”，与 `--add-all` 同用可清理重复后只保留一条；`--clear` 清空全部。保存走 `list/permission/save` 全量覆盖并回读。另支持共享级别和安全级别范围 |
 | `e10-cli form list-search-group <objId> <appId> <listId> [--add <字段名或fieldId>] [--add-custom <名称>] [--custom @配置.json] [--archive on\|off] [--position 0\|1] [--display 平铺\|下拉] [--show-archive on\|off] [--option-order default\|field] [--no-show-count] [--count-update] [--only-with-data] [--date-granularity <列表>] [--default-group <粒度> --default-value <起,止>] [--options <列表>] [--default-options <列表>] [--remove <fieldId>] [--clear] [--pc-only]` | 查看/配置**分类搜索**（台账顶部/下拉的分类筛选）。`--add` 收**字段名或 fieldId**，已在里面则按本次参数**重建那条**（改配置走它）—— 本次没给的选项一律回到缺省，所以只改一项时要把想留着的一起给全。支持四类：**选项类**(Select/RadioBox/CheckBox)、**浏览框类**(Ebuilder/Browser/Employee/Department)、**日期类**(DateComponent)、**系统字段**(创建者/数据ID 这类)。`--position` **0=顶部(缺省)/1=左侧(下拉样式)**（平台枚举 Top="0"、Left/DropDown="1"）；`--display` 是「显示方式」：`平铺` 写 `tabStyle="tab"`、`下拉` 写 `"select"`（缺省下拉）；`--show-archive on|off` 控制「显示封存的选项」`showArchiveOption`（缺省 on）。`--add-custom <名称>` 添加**自定义分类**（`componentKey=GroupCustom`）：id 由前端生成 18 位数字、`fieldId=GroupCustom_<id>`（平台没有创建接口），分类值 `listGroupSets` 初始为空、之后在设计器里配置；同名分类再执行即更新（保留原 id），可用 `--remove <名称|id|fieldId>` 删除；`--option-order` 浏览框的选项排序（default 默认排序 / field 按字段属性设置）；`--no-show-count` 关掉统计数字，`--count-update` 让统计数字**随搜索结果更新**（选项/浏览框/日期可用，缺省只在进入台账时统计一次）；`--only-with-data` **仅显示有数据的选项**（**只有**选项/浏览框类有这个键，日期与系统字段用不了；这个键**勾上才出现**，不勾整个键都没有）；`--date-granularity` 日期粒度（全年/半年/季度/月，缺省全要）；`--options` / `--default-options` 控制选项类**哪些选项出现 / 哪些默认选中**。日期类的**默认值**用 `--default-group <粒度>` + `--default-value "起,止"`（两个**必须一起给**；平台存的是一条 `{value,group}` 的默认值，并把它对应的粒度标成默认勾上）。**仅主表字段，不支持明细（产品边界，传明细报错）**。走 saveNListConfig `config.searchConditions.groupFilters`（视图级明文） |
 | `e10-cli form nlist apply <objId> <appId> <listId> <template>` | 配置**列表式视图**（台账）的显示列：模板是二维数组（行 → 列），列项可绑表单字段（`fieldId`）或做**自定义文本**列（不给 `fieldId`、给 `html`，里面用 `{{字段名}}` 插入表单字段）。自动读移动端槽位一并写入。`show` 查看当前配置。⚠ 仅对列表式(NList)生效，表格式用 `form table-view`。详见 `form/guide-list-custom-text.md` |
+| `e10-cli form nlist add-field\|remove-field <objId> <appId> <listId> <fieldId...> [--form-id <id>]` | **增量**改列表式/卡片视图显示字段：追加的字段各占一行，移除时同时清 `listField` 与 `cardLayout.grid`；已有布局原样保留（不重建模板）。隐藏主键 `id=5` 恒保留。PC 与移动端一次提交，两端回读 |
 | `e10-cli form view list <objId> <appId> [--with-comps]` | 列出表单全部视图。`--with-comps` 额外拉每个视图布局 comps 数、标出空视图（NList 数据视图会显示「读取失败」，正常） |
-| `e10-cli form view rename <objId> <appId> <viewId> <新名称>` | 修改视图名称并回读。**表单视图与台账各走一条接口**（台账走 `viewlist/buttonEvent` 的编辑动作，其余视图走 `layout/rename`），命令按类型自动选。保留原视图 ID 和配置。需求名称与默认名称不一致时统一用此命令，不新建重复视图 |
-| `e10-cli form view delete <objId> <appId> <viewId>` | 删除视图（表单视图 / 台账 / 看板等，按类型自动选接口）。⚠ **不可逆、无回收站**。先回读定位目标，删完**再回读确认确实没了**才算成功 |
-| `e10-cli form view create <objId> <appId> <视图名> [--type formView\|kanbanView\|calendarView\|mindMapView\|multiView] [--terminal PC\|MOBILE] [--layout-type FLOW\|EXCEL] [--detail <明细名>] [--sub-form-id <明细subFormId>]` | 给**已有表单**添加视图。`formView` 创建后是空布局，需续跑 `form view populate` 填字段；`kanbanView`/`calendarView`/`mindMapView`/`multiView` 建视图实体。**multiView 数据维度**：缺省主表；明细表维度用 `--detail <明细名>`（按名解析）或 `--sub-form-id <明细subFormId>`（直传），传值即明细维度（`subFormMain:true`）。**台账(NList)视图**用 `form table-view create`，不在此命令 |
+| `e10-cli form view rename <objId> <appId> <viewId> <新名称>` | 修改视图名称并回读。**表单视图与台账各走一条接口**（台账与卡片视图走 `viewlist/buttonEvent` 的编辑动作，报文 `viewType` 分别为 `nListView`/`cardView`；其余视图走 `layout/rename`），命令按类型自动选。保留原视图 ID 和配置。需求名称与默认名称不一致时统一用此命令，不新建重复视图 |
+| `e10-cli form view delete <objId> <appId> <viewId>` | 删除视图（表单视图 / 台账 / **卡片视图** / 看板等，按类型自动选接口；台账与卡片视图走 `viewlist/buttonEvent`）。⚠ **不可逆、无回收站**。先回读定位目标，删完**再回读确认确实没了**才算成功 |
+| `e10-cli form view create <objId> <appId> <视图名> [--type formView\|cardView\|kanbanView\|calendarView\|mindMapView\|multiView] [--terminal PC\|MOBILE] [--layout-type FLOW\|EXCEL] [--detail <明细名>] [--sub-form-id <明细subFormId>]` | 给**已有表单**添加视图。`formView` 创建后是空布局，需续跑 `form view populate` 填字段；`cardView` 走精简 body（不带 layoutType），创建后必须在 `cardView.detail` 回读到，否则报错提示抓 createView 报文；`kanbanView`/`calendarView`/`mindMapView`/`multiView` 建视图实体。**multiView 数据维度**：缺省主表；明细表维度用 `--detail <明细名>`（按名解析）或 `--sub-form-id <明细subFormId>`（直传），传值即明细维度（`subFormMain:true`）。**台账(NList)视图**用 `form table-view create`，不在此命令 |
 | `e10-cli form view populate <objId> <appId> <viewId>` | 把已有字段按布局类型填入 formView。视图为空则整份填；**视图已有字段时只补缺**——只补视图里还没有的字段，已有组件的排版与属性一个不动（重跑幂等）。表单新增字段后要让它出现在某个视图里，也走这条 |
 | `e10-cli form message list <appId> [--obj-id <objId>] [--keyword <kw>] [--page-size <n>] [--page-index <n>]` | 列出**消息提醒**（表单数据变动时提醒人）。不传 `--obj-id` 列出整个应用的；传了**在本地按表单收口**（平台那条过滤参数不生效）。详见 `references/form/guide-form-message.md` |
 | `e10-cli form message get <appId> <triggerId> [--obj-id <objId>]` | 查看单条消息提醒，含**推送渠道**与提醒对象。渠道不在列表与详情返回里，命令额外读一次补上 |
@@ -248,10 +252,20 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli role list` | 列出所有角色（树形结构，含层级关系） |
+| `e10-cli role get <roleId>` | 读取角色基础信息；完整设置与码表见 `references/hrm/guide-role.md` |
+| `e10-cli role update <roleId> [--name …] [--code …] [--remark …] [--parent <id>]` | 局部修改角色基础信息，保留未指定项，保存后回读；父角色必须存在且不可形成循环 |
 | `e10-cli role create <name>` | 创建角色，`--parent <id>` 指定父角色，`--code` 编码，`--remark` 备注 |
 | `e10-cli role delete <ids...>` | 删除角色（可多个） |
+| `e10-cli role permission list <roleId>` | 查询当前角色功能权限集的编码、名称、选中与禁用状态；权限项来自平台权限树，不使用固定码表 |
+| `e10-cli role permission add\|remove <roleId> <permissionSetCode>` | 按权限集编码授予/移除一项功能权限；先从权限树确认目标，再用增量 `addList/removeList` 保存并回读选中状态，不覆盖其他权限 |
 | `e10-cli role add-member <roleId> [<名字...>] [--id <id,id>] [--type <类型>]` | 添加角色成员。**两条入口二选一**：给**名字**（可多个，各自独立搜索）或给 **`--id`**（逗号分隔，直接指定对象）。同名多条时用 `--id` —— 名字入口**精确同名优先**，同名多条、或多条命中却没有同名项，一律**报错不取首条**（取首条会静默加错人），报错里会列出候选及其 id。两条入口**最终走同一个构造器**，平台收到的东西完全一致（`--id` 不是"只发个 id"，而是先按 id 把对象读回来）。`--type` 取 `resource`(人员，缺省) / `department`(部门) / `subcompany`(分部) / `position`(岗位) / `channel`(**群组**) —— 这几项正是平台 `objectTypeFilter` 白名单里**可以逐个选**的对象，白名单另三项 `all`/`external`/`allExternal` 不是逐个选的对象，本命令不支持。五类走**同一个保存端点**，靠 `objType` 选各自数组（`obj_resource` / `obj_department` / `obj_subcompany` / `obj_position` / `obj_channel`）。`--sec-min/--sec-max`、`--is-seclevel` 覆盖安全级别（**这两个值随租户配置变**，缺省 `0`/`100` + false）；`--department-attribute subordinate,partTimeStaff` 给部门/分部指定是否含下级 / 含兼职。**`--level` 设「成员级别」**（总部 / 分部 / 部门，缺省**总部**；本次添加的成员共用同一档）；**`--org-scope` 设「分权范围」**（成员能维护哪些机构，缺省全部机构；可选 同部门 / 同部门的下级部门 / 同部门及下级部门 / 同分部 / 同分部的下级分部 / 同分部及下级分部）。`role member-list` 的输出会带 `级别=` / `范围=` 便于核对。**增量追加**，不会冲掉已有成员。⚠ `--id` 里**有不存在的 id 会直接报错**（平台对取不到的 id 是静默丢弃的，不核对就会"报成功但少加了一个"）|
 | `e10-cli role member-list <roleId>` | 列出角色成员（人员 / 部门 / 分部 / 岗位 / 群组，含成员级别与分权范围） |
+| `e10-cli role add-scope-member <roleId> --type all\|allExternal [--level 总部\|分部\|部门]` | 添加“所有人”或“全部外部联系人”成员；指定外部人员不支持 |
+| `e10-cli role member-get <roleId> <memberId>` | 读取一条成员的完整配置；修改已有成员前先查成员行 ID 和当前字段 |
+| `e10-cli role member-update <roleId> <memberId> [选项]` | 保留未指定项；支持岗位级别及指定机构、部门/分部的下级与兼职、分权范围及指定机构、有效期；具体参数组合与码表见 `references/hrm/guide-role.md` |
+| `e10-cli role member-delete <roleId> <memberIds...>` | 按成员条目 ID 删除并回读列表；不同于删除角色 |
+
+角色功能权限的 `permissionSetCode` 必须先用 `role permission list` 从当前角色权限树查询；`add/remove` 只提交一项增量变更。岗位的 `position_level` 是**岗位成员内的岗位级别**，与角色成员的 `obj_level`（总部/分部/部门）不是同一设置；岗位指定部门的接口键名实际为 `position_level_partment`。部门/分部成员的下级、兼职选项使用 `department_attribute`。角色维护者、指定外部人员及岗位兼职暂不支持；“全部外部联系人”另见 `add-scope-member`。完整方法见 `references/hrm/guide-role.md`。
 | `e10-cli org department create <name> [--code <编号>] [--parent <父部门id>] [--subcompany <分部id>]` | 新建部门。**两步**：`organization/getForm?flag=department` 取保存模板（含平台**现生成**的 targetId）→ `organization/saveForm` 落组织树（扁平报文，背后的表单记录平台会自己补）。`--parent` 不传即顶层部门，挂在当前用户的分部下（分部自动解析，可用 `--subcompany` 覆盖）。⚠ 模板里 `parent` 是数组、`subcompany` 是对象数组，命令内部转成 id 字符串 —— **别拿模板直接发** |
 | `e10-cli org department list [--name <关键词>] [--page <n>] [--page-size <n>]` | 列出部门（不传 `--name` 就是全部），带分页与总数。**用来拿 id 给别的命令当入参**（例如 `role add-member --id`）。走 `browser/data/department` —— ⚠ **这个端点的本相是「列表」不是「搜索」**：空搜索即返回全部并带 `current` / `total` 分页，`--name` 只是在它上面加一层名字过滤。输出第二列是全路径（如「营销部 / 前端逻辑编排 / 维森集团」），层级直接看得到 |
 | `e10-cli org subcompany create <name> --parent <上级分部id> [--code <编号>]` | 新建**分部**（机构；部门挂在它下面）。与建部门**同一套接口、同一个报文**，只差 `getForm` 的 `flag` 与报文的 `type`。⚠ **必须给 `--parent`**（分部总得挂在某个分部下）。⚠ 「上级部门」与「所属分部」**至少填一个**，两者各填其中一半：建**部门**填「所属分部」、建**分部**填「上级分部」 |
@@ -285,7 +299,6 @@
 | `e10-cli wf-form add-field <formId> <名> Browser <标题> --browser-type <源>` | **浏览按钮必须指定浏览数据源**，否则平台报「程序异常」。源可选 `workflow`(缺省=工作流) / `hrcontract` / `role` / `archive` / `form`；用 `form` 时再配 `--browser-form-source business\|ebuilder`。落到平台是 `type=RelateBrowser` + `browserType:{module,name,id,type}` |
 | `e10-cli wf-form add-field <formId> <名> Browser <标题> --browser-name "CLM-合同类型"` | **按名字指定浏览数据源**，含自定义浏览框（`customBrowser_xxx`，没有固定 id 必须现查）。名字**精确匹配**，查不到会停下并列候选，不用近似项顶替。优先于 `--browser-type`。批量 `add-fields` 直接在 JSON 里写 `browserType:{...}` 对象 |
 | `e10-cli wf-form add-fields <formId> @fields.json [--no-init]` | **批量加字段**：JSON 数组每项 `{name,type,title?,subFormId?,multiple?,precision?,percent?,default?,format?,singleRow?,defaultCurrent?}`；加完**自动跑一次 layout init 重新布局**（`--no-init` 跳过）。字段多时比逐条 `add-field` 省事 |
-| `e10-cli wf-form ebuilder-scope <formId> <ebuilder字段Id> --rule "目标表字段:操作:值" [--sform-id <objId>] [--workflow-id <wfId>]` | 给流程表单的**关联浏览字段**设数据范围（如关联客户只选「客户状态=启用」的）。操作用 `eq`/`neq`/`like`/`isnull`/`notnull`；Select 值填**选项名**。对应 eb 表的 `form ebuilder-scope` |
 | `e10-cli wf-form edit-field <formId> <fieldId> [--title <标题>] [--multiple|--single]` | 编辑已有字段（read-modify-write）。`--multiple`/`--single`：Employee/Department/SubCompany/Browser 切 isSingle，Select↔SelectMultiple。必填为布局级用 `wf-form layout init --required` |
 | `e10-cli wf-form delete-field <formId> <fieldId...> [--force]` | 删除流程表单字段（可批量）。**仍被布局引用的字段平台拒删**；`--force` 让 CLI 先从布局摘掉这些字段的组件（含它的标题标签）再删。eb 表侧对应 `form delete-field` |
 | `e10-cli wf-form formula set <formId> --expression "DAYS({主表.开始时间},{主表.结束时间})" --target <fieldId>` | 给流程表单字段绑定计算公式。`{主表.字段}`/`{明细表名.字段}` 引用（getConfig 解析）→ `/api/excel/formula/save`(module=workflow) → ffExpress 绑字段 + saveSourceForm。`--name`/`--return-type`/**`--formula-id <id>`（原地更新已有公式，不新建）**。另：`formula get <id>` / `list <formId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错不报错只是算不对，见 `references/form/guide-form-formula-functions.md` |
@@ -365,6 +378,7 @@
 | `e10-cli workflow node field-permission get <wf> <nodeId>` | 查看节点字段权限（各字段 显示/隐藏）。表单字段在节点上可见与否 |
 | `e10-cli workflow node field-permission set <wf> <nodeId> [--hide/--show/--readonly/--editable/--disable-manual-edit/--required/--no-required <字段...>] [--enable]` | 设置节点字段权限，字段可用名称或 ID、可多个；已设权限则更新、未设则新建。**界面约束自动收口**：`--editable`（编辑）会同时勾选「显示」；`--disable-manual-edit`（禁止手动编辑）需要编辑，会自动勾选「编辑」与「显示」；`--readonly` 会清除「禁止手动编辑」。`--enable` 保存前先打勾「允许修改流程表单内容」 |
 | `e10-cli workflow node sign <wf> <nodeId>` | 全部签字意见设置；旧必填参数保留，`--data JSON/@文件` 局部修改签批签名、隐藏输入框/区域、显示类型/范围、反馈；`--schema` 字段定义，`--options` 查询完整候选。先读后改并回读 |
+| `e10-cli workflow node batch <wf> --spec <json\|@file> [--only fp,reject,sign] [--apply]` | **一张表批量设置多个节点**：默认预演，`--apply` 落库，全部写完统一回读。`nodes[]` 每条可写 `nodes`（名称或 ID，可为数组，一组配置覆盖多个节点）、`enable-modify-form`、`field-permission`、`reject`、`sign`。字段权限用三态 `hidden` / `readonly` / `editable` / `required`，或 `{access, required, disableEdit}`；`hidden` 自动带只读，从根上避开「隐藏 + 可编辑」落不了地。`reject` 键名与 `node-reject set` 一致；`sign` 用 `allRequired` / `noneRequired` / `select` / `data`（与 `node sign` 的 flags 一致）。⚠ `allRequired` / `noneRequired` **只接受 `true`**：「全部不必填」用 `noneRequired: true`，写 `allRequired: false` 会直接报错，不会静默忽略。字段名在主表与明细表重复时（例如两处「备注」）必须写字段 ID，写名称会直接报歧义并列出候选 ID；节点重名需改用 ID；同一节点出现两次直接拒绝。`enable-modify-form` 的当前值从 `displayLayoutForm.data.allowModify` 读取，会参与预演差异与落库回读。已达标时零写入，可重复执行。退出码：0 全部一致 / 2 仅告警 / 1 有错误或回读不一致 |
 | `e10-cli workflow node empty-handle get <wf> <nodeId>` | 查看节点**流程异常处理**（无可处理人时怎么办） |
 | `e10-cli workflow node empty-handle set <wf> <nodeId> --handle-way <1-5>` | 设置节点流程异常处理：1=指定人员(`--person 名称/ID`) / 2=用户指定 / 3=发起人 / 4=自动流转下一节点 / 5=提交指定节点(`--assign-node <节点ID>`)；`--off` 关闭；`--sync` 同步所有节点 |
 | `e10-cli workflow setting title <wf>` | 流程标题规则（发起后标题按规则生成，如"发起人-提交日期-客户名称"→真实数据）。缺省列出可用变量（发起人/部门/日期/表单字段）；`--rule "发起人\|提交日期\|客户名称"` 竖线分隔字段名设置；`--sep <分隔符>` 默认 `-`；`--disable` 关闭自动生成（标题回退流程名+系统默认）。占位符 `$code$`，平台发起时替换为真实值 |
@@ -546,7 +560,7 @@ e10-cli report cleanup --app-id <id> [--prefix __build_] [--apply]
 
 # 校验 / 体检 / 修复（fix 默认只预演，--apply 才落库）
 e10-cli report validate base|condition|format|transform|href|gridline|blank|style ...
-e10-cli report verify bind|all|meta|condition|format|blank|gridline|contract|limit <reportId> [--app-id <id>]
+e10-cli report verify bind|all|meta|condition|format|blank|gridline|contract|limit|drill <reportId> [--app-id <id>]
 e10-cli report fix table-name <reportId> [--apply]       # 补 tableName
 e10-cli report fix freeze <reportId> [--anchor x,y] [--apply]
 e10-cli report fix echo <reportId> --app-id <id>
@@ -591,6 +605,7 @@ e10-cli report py preagg --report-id <id> [--app-id <id>]
 | `e10-cli matrix enable <id>` / `disable <id>` | 启用 / 停用（停用后数据只读） |
 | `e10-cli matrix update <id>` / `delete <ids...>` | 更新基本信息（名称/描述/同步方式）/ 删除（级联删配置、数据、维护者） |
 | `e10-cli matrix data` | 矩阵数据维护（映射行）。`data save` 简写为 `[{rowId?, "<列configId>": ["<实体ID>"]}]`：**带 `rowId` 改那一行、不带为新增**（行 id 用 `data list` 拿；同步型矩阵的行 id 就是部门 id）。改行只给要改的列即可，CLI 自动补全其余列并回读比对 |
+| `e10-cli matrix maintainer options\|list\|get\|add\|update\|delete` | 矩阵维护者配置：先查当前矩阵可用主体、维护类型、数据权限、条件码表和值列，再用 JSON 配置新增或完整更新；`delete <matrixId> <条目ID> [更多条目ID...]` 删除指定维护者。写入或删除后按条目回读核对。详见 `references/hrm/guide-matrix.md` |
 
 > 行从哪来（`syncType`）、字段能不能改（`permList` 里有没有 `FIELD`）、以及「条件列 → 人员列 → 数据映射 → 运行时读回」的完整步骤见 `references/hrm/guide-matrix.md`。
 

package/skill-docs/references/form/guide-browser-definition.md

@@ -16,7 +16,7 @@ e10-cli form-engine browser-definition describe <formId> <fieldId> --module work
 
 `inspect` 对每个字段分别输出 `search/scope/tabs` 的 `platform`（平台是否开放）、`cli`（CLI 是否有该数据源适配）和 `configured`（已配置标记）。`describe` 返回字段原始元数据、支持项的当前配置及候选条件／范围／Tab。只在 `platform=true, cli=true` 时执行对应写入；`platform=true, cli=false` 表示数据源允许设置，但该浏览来源的保存结构尚未纳入 CLI。字段名重名时使用字段 ID。
 
-**表单绑定工作流程时，浏览数据定义必须配置在该工作流程的“高级设置 → 浏览数据定义”上；在表单设置里配置的同名字段范围不会生效。** 这是两套独立记录：流程场景用 `businessId = workflowId`、`businessModule/module = ebuildercard`，`formId` 只是关联表单的 formId；表单场景才用 `businessId = formId`、`module = ebuilderform`。流程高级设置读不到表单级配置，`form ebuilder-scope` 也不能代替流程配置。
+**表单绑定工作流程时，高级搜索、数据范围、浏览 Tab 都必须配置在该工作流程的“高级设置 → 浏览数据定义”上；仅在表单引擎的表单设置里配置同名字段，不会对流程生效。** 这是两套独立记录：流程场景用 `businessId = workflowId`、`businessModule/module = ebuildercard`，`formId` 只是关联表单的 formId；表单场景才用 `businessId = formId`、`module = ebuilderform`。流程高级设置读不到表单级配置。
 
 这不是“流程配置覆盖表单配置”的优先级关系，而是**流程只读属于自己的流程记录**：表单级记录即使存在也不会被流程读取，因此对流程等于无效。只有同一表单在**不经过流程**的独立表单场景中使用时，表单级配置才按表单场景生效。
 
@@ -50,224 +50,7 @@ e10-cli form-engine browser-definition search set <formId> <fieldId> --module <m
 
 ## 数据范围
 
-```bash
-e10-cli form-engine browser-definition scope get <formId> <fieldId> --module <module> [--app-id <appId>]
-e10-cli form-engine browser-definition scope candidates <formId> <fieldId> --module <module> [--app-id <appId>] --kind resource|department|subcompany --keyword <名称>
-e10-cli form-engine browser-definition scope matrix-options <formId> <fieldId> --module <module> [--app-id <appId>] --matrix-id <矩阵ID>
-e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <module> [--app-id <appId>] --config @scope.json
-```
-
-数据范围按浏览来源选择适配器：
-
-| 来源 | `--config` 结构 | 说明 |
-|---|---|---|
-| 人员 `hrm/resource` | `{"rules":[...],"range":"any"}`；完整配置亦可用 `itemDatas[]` | `get` 返回当下布局码表、表单字段候选、矩阵选项和现存范围。`rules[]` 按当前布局校验并转换，与已有项按范围来源合并。 |
-| 部门 `hrm/department` | `{"rules":[...]}`；完整配置亦可用 `records[]` | 已核对指定部门／分部、创建人、当前操作者、表单部门字段。 |
-| 分部 `hrm/subcompany` | `{"rules":[...]}`；完整配置亦可用 `records[]` | 已核对指定分部、创建人、当前操作者、表单分部字段。 |
-| 关联 EBuilder `ebuilder/form/ebuilder` | `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"..."}]}` | `scopeInfoRender` 为条件树 JSON 字符串；已有 `form ebuilder-scope` 提供按字段名编译的简便方式；操作符码表见下文“浏览范围条件码表”。 |
-| 自定义浏览框 `bcw/customBrowser_*` | `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"..."}]}` | `scope get` 返回该浏览框自己的 `conditionLayout`，从其中选择字段与操作符，按完整条件树写入；字段和操作符在保存前校验。 |
-| 行政区域 `bcw/city` | `{"records":[{"scopeType":"normal_country","scopeInfo":"国家ID","scopeInfoRender":"{...}","type":"normal"}]}` | 例：指定国家为中国；国家 ID 从实际候选列表取得。 |
-
-`records` 是完整范围记录，按 `get` 回读的 ID 更新既有项。人员范围与流程操作者的选项概念相近，但并非全量相同，必须以 `describe` 返回的可选布局为准。加入多项范围时，其可选数据取并集；未设置范围时不应把它误判为“空范围”。
-
-### 关联 EBuilder：先选配置方式
-
-关联 EBuilder 的数据范围决定**目标表单的哪些记录可以在浏览弹窗中选择**。先按规则复杂度选择命令：
-
-| 需求 | 配置方式 | 适用范围 |
-| --- | --- | --- |
-| 按目标表单字段设置一层“且／或”条件 | `form ebuilder-scope get/set/clear` | 可使用固定值、目标字段选项、当前表单字段或目标表单字段作条件值 |
-| `A OR (B AND C)` 等混合嵌套条件 | `form-engine browser-definition scope get/set` | 读取候选布局后编写完整条件树 |
-
-先区分两张表单：**当前表单**是用户正在填写、包含关联 EBuilder 字段的源表单；**目标表单**是该关联字段打开浏览弹窗后列出记录的 EBuilder 表单。每条条件的左侧 `field` 始终选择**目标表单字段**，右侧取值来源决定比较方式：
-
-| 右侧取值方式 | 左侧 `field` | 右侧字段 | 适用场景 |
-| --- | --- | --- | --- |
-| 固定值 `value` | 目标表单字段 | 手工输入的值或目标字段的选项 | 只允许选择状态为“启用”的目标记录 |
-| 变量字段 `valueFrom: "currentFormField"` | 目标表单字段 | 当前表单字段 `valueField` | 只允许选择“所属项目”等于当前申请“相关项目”的任务；当前表单字段值作为筛选变量 |
-| 本表字段 `valueFrom: "targetFormField"` | 目标表单字段 | 同一目标表单的另一个字段 `valueField` | 在每条目标记录内部比较两个字段；不引用当前表单的值 |
-
-“本表字段”的“本表”指**被浏览的目标表单**。如果需求写着“关联任务只能选当前所选项目的任务”，右侧应选**变量字段**，不能选本表字段。空值判断 `isnull`、`notnull` 没有右侧取值。旧 `form ebuilder-filter` 修改的是字段布局中的过滤参数，不保证被浏览数据定义识别；设置浏览弹窗可选记录使用本节的数据范围命令。
-
-#### 常用规则：查询、设置与清空
-
-```bash
-e10-cli form ebuilder-scope get <源objId> <appId> <EBuilder字段fieldId>
-e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> --rules @scope-rules.json --logic and
-e10-cli form ebuilder-scope clear <源objId> <appId> <EBuilder字段fieldId>
-```
-
-`源objId` 是包含关联字段的表单对象 ID；`appId` 是应用 ID；`fieldId` 是该关联字段的 ID。规则中的 `field` 指目标表单主表字段，可填字段名或 ID，重名时用 ID。`--logic and|or` 控制所有规则的关系，缺省为 `and`。`--fill-null` 可在需要关联字段为空时填充的场景下使用，缺省关闭。
-
-> `form ebuilder-scope` 只写 **EB 表单级**记录（`module=ebuilderform`）。表单绑定工作流程后，流程实际读取的是流程高级设置记录；此时必须改用 `form-engine browser-definition ... --module workflow --workflow-id <流程ID>`，表单级配置不会生效。
-
-规则文件是 JSON 数组。操作符与条件取值写法如下：
-
-例如，同时按客户状态和名称设置固定值条件：
-
-```json
-[
-  { "field": "客户状态", "operator": "eq", "value": "启用" },
-  { "field": "客户名称", "operator": "like", "value": "上海" }
-]
-```
-
-| 项目 | 写法 | 含义与限制 |
-| --- | --- | --- |
-| `operator` | `eq`、`neq`、`like`、`isnull`、`notnull`；字段引用可用 `aggregate`、`unaggregate` | 等于、不等于、包含、为空、不为空；`aggregate`/`unaggregate` 为平台保存树里的“属于/不属于” |
-| 固定值 | `"value":"上海"` | 文本、数字、日期填目标值；选项类字段可填选项名或唯一选项值 ID，CLI 按实际选项匹配 |
-| 当前表单字段 | `"valueFrom":"currentFormField","valueField":"相关项目"` | 选择“变量字段”：左侧仍是目标表单字段，右侧引用源表单主表字段的当前值 |
-| 目标表单字段 | `"valueFrom":"targetFormField","valueField":"项目简介"` | 选择“本表字段”：左侧和右侧均来自被浏览的目标表单主表字段，逐条目标记录内部比较 |
-
-字段引用时不填固定 `value`；`valueField` 可填字段名或 ID，重名时用 ID。CLI 先查询字段候选，再分别生成变量字段或本表字段的配置。目前字段引用只验证了**条件左侧为关联浏览字段**的情况；简便规则只读取源表单和目标表单的主表字段，不用于目标明细字段。用 `aggregate`/`unaggregate` 时，CLI 会按平台结构把 `selectValue` 写成数组；左侧不是关联浏览字段（例如部门字段）时简便命令会拒绝，改用下面的完整条件树。
-
-例如，浏览“关联项目”时，让目标表的“关联合同”等于当前表单的“关联合同”；再让目标表的“关联客户”等于目标表自己的“项目简介”：
-
-```json
-[
-  {"field":"关联合同","operator":"eq","valueFrom":"currentFormField","valueField":"关联合同"},
-  {"field":"关联客户","operator":"eq","valueFrom":"targetFormField","valueField":"项目简介"}
-]
-```
-
-例如，浏览“关联任务”时，只允许选择“所属项目”等于当前申请的“相关项目”、且“任务状态”不为“已完成”的任务，`scope-rules.json` 可写为：
-
-```json
-[
-  {"field":"所属项目","operator":"eq","valueFrom":"currentFormField","valueField":"相关项目"},
-  {"field":"任务状态","operator":"neq","value":"已完成"}
-]
-```
-
-此例须先确认“所属项目”是关联浏览字段、“任务状态”的选项中确有“已完成”，再用 `--logic and` 写入。选项名称或值 ID 均由 CLI 对照目标字段的实际选项。另一个字段引用例子是 `{"field":"关联客户","operator":"eq","valueFrom":"targetFormField","valueField":"项目简介"}`，表示目标表单内两个字段相比较。
-
-`set --rules` 会按本次数组重建整组简便规则，修改前先 `get` 并保留仍需生效的条件。写入后再次 `get` 回读，并在实际表单的浏览弹窗核对可选记录。字段引用已验证写入与回读；随当前表单字段值变化的实时筛选效果仍须在实际场景核对。
-
-只允许选择状态为“启用”的客户时，也可直接传规则数组：
-
-```bash
-e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> --rules '[{"field":"客户状态","operator":"eq","value":"启用"}]'
-```
-
-#### 复杂规则：完整条件树
-
-关联 EBuilder 使用 `scopeType=scopeSql` 的条件树。需要 `A OR (B AND C)` 等混合逻辑时，使用 `form-engine browser-definition scope get/set` 读写完整 `records[].scopeInfoRender`。先用 `scope get` 读取原配置和候选布局，按目标表实际字段、字段类型与可选操作符调整条件树，再保存并回读。
-
-条件树中的 `datas` 可以同时包含字段条件和子条件组；组的 `relationship` 为 `1`（AND／所有条件）或 `0`（OR／任一条件）。每个组有唯一 `key`，子项的 `parentNode` 指向直接父组的 `key`。例如 `A OR (B AND C)` 的结构是：
-
-```json
-{
-  "key": "root", "relationship": "0", "isParent": true, "parentNode": "",
-  "isNewFilter": true, "version": 1, "showFilterIsNull": false,
-  "datas": [
-    { "key": "a", "parentNode": "root", "isParent": false, "type": "condition",
-      "id": "name", "fieldName": "name", "fieldType": "String", "compType": "Text", "text": "标题",
-      "conditions": { "func": "eq", "value": "A", "selectValue": { "id": "manualInput", "content": "手动输入", "type": "SELECTION_CUSTOM" }, "customValue": "A", "customBrowserValue": [] } },
-    { "key": "group-bc", "parentNode": "root", "relationship": "1", "isParent": true,
-      "datas": [
-        { "key": "b", "parentNode": "group-bc", "isParent": false, "type": "condition",
-          "id": "name", "fieldName": "name", "fieldType": "String", "compType": "Text", "text": "标题",
-          "conditions": { "func": "eq", "value": "B", "selectValue": { "id": "manualInput", "content": "手动输入", "type": "SELECTION_CUSTOM" }, "customValue": "B", "customBrowserValue": [] } },
-        { "key": "c", "parentNode": "group-bc", "isParent": false, "type": "condition",
-          "id": "name", "fieldName": "name", "fieldType": "String", "compType": "Text", "text": "标题",
-          "conditions": { "func": "eq", "value": "C", "selectValue": { "id": "manualInput", "content": "手动输入", "type": "SELECTION_CUSTOM" }, "customValue": "C", "customBrowserValue": [] } }
-      ] }
-  ]
-}
-```
-
-上面展示的是 `scopeInfoRender` **解码后的条件树**，用于说明嵌套关系；实际 `scope.json` 须把整棵树序列化为 JSON 字符串，放入 `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"<序列化后的条件树>"}]}`。字段 `id/fieldName/fieldType/compType`、`conditions` 的操作符和值结构要按目标字段和 `scope get` 返回的同类条件填写；选项、表单字段、变量字段等值的配置形状与示例的手动文本值不同。更新已有规则时保留其记录 ID（CLI 在未给 ID 时也会按 `scopeType` 查找并沿用已有 ID）。保存后再次 `scope get`，核对树层级、每层 `relationship`、字段和值及记录 ID。工作流程场景还须传 `--workflow-id`，并在所属工作流程的实际使用场景核对筛选效果。
-
-#### 浏览范围条件码表（`scopeInfoRender`）
-
-平台 `getScopeConditionLayout/ebuilder` 返回的字段操作符与保存树里的 `conditions.func` 对应如下。`scope get` / `describe` 现在会返回 EBuilder 的 `conditionLayout`，以目标字段实际返回的 `conditionType` 为准：
-
-| 场景 | `conditions.func` | 值结构 |
-|---|---|---|
-| 等于 / 不等于 | `eq` / `notEq` | 固定值或字段引用；字段引用时 `selectValue` 是对象 |
-| 包含（文本） | `like` / `notLike` | 固定值或字段引用 |
-| 包含（浏览/部门） | `inC` / `notInC` | 字段选项或字段引用；这是“包含”，不是“属于” |
-| 属于 / 不属于（本表字段/变量字段） | `aggregate` / `unaggregate` | `type:"custombyhander"`；`selectValue` 是数组 `[{"id":"tableFields" 或 "varFileds","content":"本表字段" 或 "变量字段","type":"SELECTION_CUSTOM"}]`；`customValue:"field_<被引用字段ID>"`；`value` 填被引用字段名 |
-| 为空 / 不为空 | 保存树用 `empty` / `nempty`；条件布局用 `isNull` / `isNotNull` | 无右侧值 |
-| 介于 | `between` | 日期起止值 |
-
-**关键区别**：`inC` 是“包含”，用于浏览/部门字段的集合包含；本表字段/变量字段比较的“属于/不属于”是 **`aggregate`/`unaggregate`**，并且 `selectValue` 必须是数组，不能沿用 `eq` 的对象形状。
-
-例如“所属部门 属于 经办部门”的条件节点：
-
-```json
-{
-  "id": "field_<左字段ID>",
-  "fieldName": "field_<左字段ID>",
-  "fieldType": "String",
-  "text": "所属部门",
-  "compType": "Department",
-  "type": "condition",
-  "conditions": {
-    "func": "aggregate",
-    "value": "经办部门",
-    "type": "custombyhander",
-    "text": "",
-    "selectValue": [
-      { "id": "tableFields", "content": "本表字段", "type": "SELECTION_CUSTOM" }
-    ],
-    "customValue": "field_<右字段ID>",
-    "customBrowserValue": []
-  },
-  "config": { "name": "所属部门", "title": "所属部门" },
-  "subTableId": "",
-  "key": "<节点key>"
-}
-```
-
-变量字段把 `selectValue[0].id` 换成 `varFileds`、`content` 换成 `变量字段`；其余保持不变。条件布局没有列出的操作符不要凭字面猜测，先读 `conditionLayout` 或抓一次设计器保存报文。
-
-### 自定义浏览框
-
-先用 `inspect` 找出目标字段及其 `bcw/customBrowser_*` 来源，再用 `describe` 或 `scope get` 读取当前配置和 `conditionLayout`。候选布局按当前浏览框动态返回，每个字段提供 `id/text/type/compType/conditionType` 等信息；条件树叶节点的字段 ID 与操作符须来自这份布局。`scopeInfoRender` 使用平台的完整条件树 JSON 字符串，组节点的 `datas` 可嵌套 AND／OR 条件。日期区间在候选操作符中记作 `between`，已见保存条件采用 `conditions.func="range"` 且 `value` 为两个日期值；其他操作符和值结构按该字段实际候选及现有配置填写。高级搜索同样先读该浏览框返回的 `layout.items`，再构造 `commonLines/commonCells/lines/cells/searchValue`。Tab 是否可配以 `inspect` 的 `tabs.platform` 为准。
-
-### 人员范围码表与简化规则
-
-下表是当前可用的范围来源；同一 `groupTypeId` 的 `includeType`、组织维度等下级选项仍应以 `scope get` 实时返回的 `groups[].options` 为准。表单字段候选取 `formFieldCandidates`，矩阵候选取 `matrixOptions`；指定对象先用 `scope candidates` 查询。
-
-| `rules[].kind` | 平台组码 | 主要参数 | 适用说明 |
-|---|---:|---|---|
-| `person` | 101 | `target` 为候选人员对象 | 指定人员 |
-| `everyone` | 110 | 无 | 所有人 |
-| `creator` | 114 | `includeType`、`virtualId` | 数据创建人及其组织关系 |
-| `operator` | 121 | `includeType`、`virtualId` | 当前操作者及其组织关系 |
-| `field` + `fieldType=resource` | 201 | `field`、`includeType` | 按表单人员字段值取范围 |
-| `field` + `fieldType=department` | 202 | `field`、`includeType` | 按表单部门字段值取范围；本部门使用 `1` |
-| `field` + `fieldType=subcompany` | 203 | `field`、`includeType` | 按表单分部字段值取范围；本分部使用 `4` |
-| `matrix` | 401 | `sourceId/sourceIdType/targetId/matrixRules` 等 | 先选择矩阵并读取 `getMaTrixItems` 返回的来源、结果字段及映射项 |
-
-布局中还可出现指定部门 `102`、指定分部 `103`、指定角色 `104`、指定岗位 `105` 等组。它们的组织维度、包含上下级和安全级别选项因当前字段与数据源而异；先从 `get` 读取，未纳入简化规则的结构可使用完整 `itemDatas[]`，不能照搬流程操作者的全量码表。指定部门的已见关系码为 `1/2/3`（本部门／含下级／含上级），指定分部为 `4/5/6`（本分部／含下级／含上级）。
-
-```json
-{
-  "rules": [
-    {"kind":"field","fieldType":"department","field":"报销部门","includeType":"1"},
-    {"kind":"operator","includeType":"12"}
-  ]
-}
-```
-
-矩阵规则示例结构为 `{"kind":"matrix","sourceId":"...","sourceIdCN":"...","sourceIdType":"2","targetId":"...","targetIdCN":"...","matrixRules":[{"sourceField":"矩阵来源字段ID","sourceType":"customBrowser","targetField":"表单字段ID"}]}`。来源和结果字段 ID 应通过 `scope matrix-options` 读取，`matrixRules` 映射矩阵来源字段与当前表单字段；只提供矩阵 ID 无法完成此设置。
-
-### 部门、分部范围码表
-
-部门和分部使用各自的数据范围配置，不能套用人员范围规则。以下是当前支持的 `rules[].type`：
-
-| 来源字段 | 可用 `type` | 已核对的关系码／值 |
-|---|---|---|
-| 部门 | `targetDepartment`、`targetSubcompany`、`creator`、`operator`、`department` | 指定部门 `ownDepartment`；指定分部 `ownOrSubcompany`；创建人 `subcompanyAsCreator`；操作者 `subcompanyAsOperator`；表单部门 `ownDepartment` |
-| 分部 | `targetSubcompany`、`creator`、`operator`、`subCompany` | 指定分部 `ownOrSubcompany`；创建人 `subcompanyAsCreator`；操作者 `OPERATOR_SUP_SUBCOMPANY`；表单分部 `ownSubcompany` |
-
-`targetDepartment/targetSubcompany` 的 `target` 使用 `scope candidates` 返回的完整候选对象；`department/subCompany` 的 `field` 使用本表字段名或 ID。`creator/operator` 可给 `virtualId`（未给取已核对的行政组织 `1`）。其它上下级关系码须先读取相应字段的候选项，不按中文含义猜码。
-
-```json
-{"rules":[{"type":"targetDepartment","target":{"id":"部门ID","name":"技术部","content":"技术部"},"mode":"ownDepartment"},{"type":"department","field":"报销部门","mode":"ownDepartment"}]}
-```
+数据范围限制浏览弹窗中的可选记录。配置前先按本指南确定表单级或流程级归属，再阅读[浏览数据范围](guide-browser-scope.md)：其中按浏览来源分别说明命令、码表、条件树、人员／组织范围及验证方法。
 
 ## 浏览 Tab