weaver-e10-builder 1.6.11 → 1.6.12

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

@@ -113,9 +113,8 @@
 | `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` 可选同时改描述。流程表单暂不提供 |
@@ -248,10 +247,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 +294,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 +373,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 +555,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 +600,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