weaver-e10-builder 1.6.10 → 1.6.12

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
 

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

@@ -0,0 +1,285 @@
+# 浏览数据范围
+
+先按[浏览数据定义](guide-browser-definition.md#操作顺序)确认配置归属：独立 EB 表单与关联工作流程的表单分别保存记录，流程中的高级搜索、数据范围和浏览 Tab 均须在流程高级设置中配置。本文只说明数据范围本身。
+
+## 命令与浏览来源
+
+```bash
+e10-cli form-engine browser-definition scope get <formId> <fieldId> --module <module> [--app-id <appId>]
+e10-cli form-engine browser-definition scope clear <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
+e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <module> [--app-id <appId>] --tree @tree.json [--source-obj-id <当前表单objId>]
+```
+
+`scope set` 的 `--config` 写平台原始完整配置；关联 EBuilder、自定义浏览框可用 `--tree @tree.json` 按实时条件布局编译混合嵌套规则。旧 `--rules @rules.json [--logic and|or] [--fill-null]` 仅用于关联 EBuilder 的单层规则。三者互斥；引用当前表单字段时额外传 `--source-obj-id <源表单objId>`。`clear` 当前仅适用于关联 EBuilder 字段；其他浏览来源不要套用空条件树，应按该来源的记录结构处理。
+
+### 关联浏览范围的共同配置逻辑
+
+关联 EBuilder 与自定义浏览框都要先读 `scope get` 的 `conditionLayout`：**左侧字段**来自被浏览的目标数据，其 `conditionType[]` 是该字段当前开放的界面操作符，`disabled:true` 不可选；不同字段、不同浏览来源可以不同。再确定**右侧取值来源**：手动输入固定值、当前表单的变量字段、被浏览目标数据的本表字段；空值操作符不需要右侧值。右侧候选还受左侧字段类型与组件限制，不能把三种来源当成任何字段都必备的选项。当前接口未统一返回完整的“字段 × 操作符 × 右侧来源”矩阵，因此 CLI 的结构化 `--tree` 只编译已知保存结构，其余组合保留 `--config` 原始配置方式，且须先核对该组合的真实保存结构。
+
+`--tree` 的组节点是 `{"logic":"and|or","children":[...]}`，可任意嵌套；叶节点是 `{"field":"左侧字段名或ID","operator":"conditionType中的界面码",...}`。手动输入给 `"valueFrom":"manual","value":"固定值"`；变量字段给 `"valueFrom":"currentFormField","valueField":"当前表单字段名或ID"` 并传 `--source-obj-id`；本表字段给 `"valueFrom":"targetFormField","valueField":"目标数据字段名或ID"`。重名时使用 ID。编译器逐条按左侧字段布局检查操作符，将界面码转换为保存码，再生成 `scopeInfoRender`。例如：
+
+```json
+{"logic":"or","children":[
+  {"field":"名称","operator":"eq","valueFrom":"manual","value":"样例"},
+  {"logic":"and","children":[
+    {"field":"名称","operator":"notEq","valueFrom":"currentFormField","valueField":"申请名称"},
+    {"field":"名称","operator":"isNull"}
+  ]}
+]}
+```
+
+目前 `--tree` 已覆盖文本字段的 `eq/notEq` 手动输入、关联 EBuilder 左侧字段的 `eq/notEq/in/notIn` 手动输入、日期字段的 `between` 两日期区间、文本或关联 EBuilder 左侧字段的 `eq/notEq/in/notIn` **同类字段引用**（仍以该字段实际开放的操作符为限），以及 `isNull/isNotNull`。其中日期区间输入 `"value":["YYYY-MM-DD","YYYY-MM-DD"]`，保存为 `func:"range"`；关联 EBuilder 手动输入四种操作符的 `selectValue` **均为单个** `manualInput` 对象，`value/customValue` 相同且 `customBrowserValue:[]`。其他固定值类型、浏览字段的固定记录选择、跨类型字段引用、`inC/notInC` 等取值结构未纳入结构化编译，需用 `--config` 和已核对的原始保存结构。`--tree` 的拒绝提示表示缺少该组合的编译依据，不表示平台不支持。写入后按下文验收口径回读。
+
+### 保存与验收口径
+
+日常配置按实际需求选择来源与条件，保存后用 `scope get` 回读，核对记录归属、字段 ID、保存码、右侧取值、条件组层级及记录 ID；结构一致即可报告“配置已保存并回读”。**不要把回读表述为浏览弹窗筛选效果已验证，也不把抓到筛选结果接口或逐次页面检查设为日常配置的必经步骤。** 首次使用尚未核实的字段／取值组合、修改高风险复杂规则或出现结果异常时，再用已知应出现／不应出现的记录在实际浏览弹窗做针对性检查。
+
+数据范围按浏览来源选择适配器：
+
+| 来源 | `--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-engine browser-definition scope set --rules` 提供按字段名编译的简便方式；操作符码表见下文“浏览范围条件码表”。 |
+| 自定义浏览框 `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-engine browser-definition scope set --rules` | 可使用固定值、目标字段选项、当前表单字段或目标表单字段作条件值 |
+| `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-engine browser-definition scope get <formId> <fieldId> --module ebuilderform --app-id <appId>
+e10-cli form-engine browser-definition scope set <formId> <fieldId> --module ebuilderform --app-id <appId> --rules @scope-rules.json --logic and
+e10-cli form-engine browser-definition scope clear <formId> <fieldId> --module ebuilderform --app-id <appId>
+```
+
+`formId` 是当前表单的版本 ID（不是 objId）；`appId` 是应用 ID；`fieldId` 是该关联字段的 ID。规则中的 `field` 指目标表单主表字段，可填字段名或 ID，重名时用 ID。`--logic and|or` 控制所有规则的关系，缺省为 `and`。`--fill-null` 可在需要关联字段为空时填充的场景下使用，缺省关闭。使用 `valueFrom:"currentFormField"` 时须额外传 `--source-obj-id <当前表单objId>`，用于读取来源字段候选；流程场景也可用同一套 `--rules`，改传 `--module workflow --workflow-id <流程ID>`。
+
+> `--rules` 与 `--config` 都遵循总指南的配置归属。表单绑定工作流程后，流程实际读取流程高级设置记录；务必传 `--module workflow --workflow-id <流程ID>`，不要误写 `--module ebuilderform`。
+
+规则文件是 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":"项目简介"` | 选择“本表字段”：左侧和右侧均来自被浏览的目标表单主表字段，逐条目标记录内部比较 |
+
+选项类字段（Select/Radio/CheckBox）的固定 `value` 可填选项名或唯一值 ID；CLI 读取目标字段选项，将其转换为平台保存的选项 ID 与显示名。名称不存在或重名时应改用唯一 ID，不要猜测码表。
+
+字段引用时不填固定 `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` 回读；按上文验收口径区分保存状态与运行效果。
+
+若规则引用当前表单字段，命令应同时指定来源表单对象 ID；例如 `scope set <formId> <fieldId> --module workflow --workflow-id <流程ID> --source-obj-id <源表单objId> --rules @scope-rules.json`。`--source-obj-id` 只用于解析变量字段，不改变范围记录的归属；归属始终由 `--module` 与 `--workflow-id` 决定。
+
+只允许选择状态为“启用”的客户时，也可直接传规则数组：
+
+```bash
+e10-cli form-engine browser-definition scope set <formId> <fieldId> --module ebuilderform --app-id <appId> --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` / `neq` | 固定值或字段引用；字段引用时 `selectValue` 是对象 |
+| 包含（文本） | `like` / `notLike` | 固定值或字段引用 |
+| 包含（浏览/部门） | `inC` / `notInC` | 字段选项或字段引用；这是“包含”，不是“属于” |
+| 属于 / 不属于（本表字段/变量字段） | `aggregate` / `unaggregate` | `type:"custombyhander"`；`selectValue` 是数组 `[{"id":"tableFields" 或 "varFileds","content":"本表字段" 或 "变量字段","type":"SELECTION_CUSTOM"}]`；`value` 填被引用字段名；本表字段 ID 在 `customValue`，变量字段对象在 `customBrowserValue[]` |
+| 为空 / 不为空 | 保存树用 `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` 换成 `变量字段`，同时将 `customValue` 置空、来源字段放入 `customBrowserValue[]`；不能只替换选择器。条件布局没有列出的操作符不要凭字面猜测，先读 `conditionLayout` 或抓一次设计器保存报文。
+
+### 自定义浏览框
+
+先用 `inspect` 找出目标字段及其 `bcw/customBrowser_*` 来源，再用 `describe` 或 `scope get` 读取当前配置和 `conditionLayout`。候选布局按当前浏览框动态返回，每个字段提供 `id/text/type/compType/conditionType` 等信息。`conditionType[].id` 是**界面选项码**，`scopeInfoRender.datas[].conditions.func` 是**保存码**；不能把前者原样写入后者。对关联 EBuilder 类型的目标字段，六种常用选项对应如下：
+
+自定义浏览框与关联 EBuilder 浏览字段的数据范围采用同一种**完整条件树配置方式**：已知组合可用 `scope set --tree @tree.json` 编译，或用 `--config @scope.json` 直接写 `records[].scopeInfoRender`。三件事分别决定一条条件：左侧选择被浏览数据的字段；该字段的 `conditionLayout` 限定可用操作符；右侧选择固定值、变量字段（当前表单字段）或本表字段（被浏览目标表的字段）。操作符不是取值来源的分类，同一来源可能搭配不同操作符；为空／不为空不需要右侧值。自定义浏览框不支持旧 `--rules` 单层输入，但支持 `--tree` 的混合嵌套条件。
+
+| 右侧取值来源 | 值来自哪里 | 配置时要区分的内容 |
+|---|---|---|
+| 固定值／手动输入 | 配置时给定的常量或目标字段选项 | 按该字段类型及所选操作符填写值；不要写成字段引用 |
+| 变量字段 | 打开浏览框的当前表单字段 | 来源字段属于当前表单；已知字段引用使用 `customBrowserValue[]`，不把字段 ID 放在 `customValue` |
+| 本表字段 | 被浏览目标表中的另一个字段 | 来源字段属于目标表；`customValue` 放目标字段 ID，`customBrowserValue:[]` |
+
+三种来源是可选的取值方式，不代表每个字段／操作符组合都开放全部来源。固定值依字段类型选择手动输入或候选项；用该字段同类条件的保存结构填写 `conditions.value/customValue/selectValue`，不写 `varFileds` 或 `tableFields`。变量字段与本表字段的明确结构见下文。需要嵌套时，沿用上文[复杂规则：完整条件树](#复杂规则完整条件树)的组节点：`datas` 可含条件与子组，各组以 `relationship=1` 表示 AND、`0` 表示 OR，`parentNode` 指向直接父组。例如 `A OR (B AND C)`，A/B/C 各自独立选择字段、操作符和取值来源。将整棵树序列化为 `scopeInfoRender` 字符串，写入后按上文验收口径回读。
+
+| 界面文案 | `conditionType[].id` | 保存树 `conditions.func` | 右侧取值 |
+|---|---|---|---|
+| 属于 | `in` | `aggregate` | 字段引用时 `selectValue` 为数组 |
+| 不属于 | `notIn` | `unaggregate` | 字段引用时 `selectValue` 为数组 |
+| 等于 | `eq` | `eq` | 字段引用时 `selectValue` 为对象 |
+| 不等于 | `notEq` | `neq` | 字段引用时 `selectValue` 为对象 |
+| 为空 | `isNull` | `empty` | 无右侧字段引用 |
+| 不为空 | `isNotNull` | `nempty` | 无右侧字段引用 |
+
+对已知的**变量字段**保存结构，`selectValue` 的数组或对象形状由**操作符**决定：`aggregate/unaggregate` 使用 `selectValue:[{"id":"varFileds","content":"变量字段","type":"SELECTION_CUSTOM"}]`；`eq/neq` 使用 `selectValue:{"id":"varFileds","content":"变量字段","type":"SELECTION_CUSTOM"}`。这不表示操作符只支持变量字段；固定值或本表字段应使用其自身的取值来源标识和值结构，不能沿用 `varFileds`。
+
+引用当前表单字段时，目标字段与来源字段要分开放置：条件节点的 `id/fieldName` 是被浏览目标表单的字段；`conditions.value` 为来源字段显示名，`conditions.customValue` 为 `""`，`conditions.customBrowserValue` 是来源字段对象数组，例如 `[{"id":"<当前表单字段ID>","name":"所属项目","content":"所属项目","location":"主表"}]`。`customBrowserValue` 在上述“属于”和“等于”的字段引用保存结构中**都是数组**；不要误以为“等于”会把它改成对象，也不要把来源字段 ID 塞进 `customValue`。`empty/nempty` 无需 `selectValue/customBrowserValue`，已见保存结构为 `value/customValue` 填“为空”或“不为空”。
+
+引用**本表字段**时，条件节点仍指被浏览目标表的左侧字段；`conditions.value` 是右侧目标字段显示名，`conditions.customValue` 是右侧目标字段的 `field_<字段ID>`（系统字段按候选 ID），`conditions.customBrowserValue` 为 `[]`。`selectValue` 的来源项改为 `{"id":"tableFields","content":"本表字段","type":"SELECTION_CUSTOM"}`；“属于／不属于”包一层数组，“等于／不等于”直接用对象。变量字段则用 `varFileds` 来源项及上段的 `customBrowserValue[]`。这两种字段引用都要按左侧字段的实际可用操作符选择，右侧字段须从对应表单的候选字段读取，不凭显示名猜 ID。
+
+关联 EBuilder 左侧字段的**手动输入固定值**可与“等于／不等于／属于／不属于”搭配，前提是该字段的 `conditionLayout` 开放相应操作符。四者都用 `selectValue:{"id":"manualInput","content":"手动输入","type":"SELECTION_CUSTOM"}` **对象**，`conditions.type="custombyhander"`，`value` 与 `customValue` 均为输入文本，`customBrowserValue:[]`；即使操作符保存为 `aggregate/unaggregate`，手动输入也**不使用数组**。数组只见于这两种操作符的字段引用来源，不能按操作符单独决定形状。这与选择浏览弹窗中的某一条固定记录不同，不能据此推出固定记录的保存结构。日期字段“介于”采用 `conditions.func="range"`、`conditions.value=["起始日期","结束日期"]`，不使用字段引用的 `selectValue`。
+
+`scopeInfoRender` 使用平台的完整条件树 JSON 字符串，组节点的 `datas` 可嵌套 AND／OR 条件。日期区间在候选操作符中记作 `between`，已见保存条件采用 `conditions.func="range"` 且 `value` 为两个日期值。以上映射只适用于当前字段布局实际开放的选项；其他字段类型或操作符继续按该浏览框的布局和对应保存结构判断，不能把关联 EBuilder 浏览来源的取值结构直接套用。高级搜索同样先读该浏览框返回的 `layout.items`，再构造 `commonLines/commonCells/lines/cells/searchValue`。Tab 是否可配以 `inspect` 的 `tabs.platform` 为准。
+
+CLI 对自定义浏览框按左侧字段的实时 `conditionType[]` 校验保存码，并对关联 EBuilder 目标字段的变量／本表字段引用校验 `selectValue` 形状及字段位置；它也递归检查嵌套组。`--tree` 输入界面码并自动转换；原始 `--config` 须自行填**保存码**，不能把 `in/notIn/notEq/isNull/isNotNull` 等界面码直接放入 `conditions.func`。保存后按上文验收口径回读；异常时才检查运行效果。
+
+### 人员范围码表与简化规则
+
+下表是当前可用的范围来源；同一 `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"}]}
+```

package/skill-docs/references/form/guide-create-form.md

@@ -145,7 +145,7 @@ EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
 }
 ```
 
-`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见[表单字段定义参考](ref-form-fields.md)；关联浏览的数据范围见[浏览数据定义](guide-browser-definition.md#数据范围)。旧布局过滤配置见[EBuilder 过滤](guide-ebuilder-filter.md)。
+`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见[表单字段定义参考](ref-form-fields.md)；关联浏览先按[浏览数据定义](guide-browser-definition.md)确定配置归属，再读[浏览数据范围](guide-browser-scope.md)。旧布局过滤配置见[EBuilder 过滤](guide-ebuilder-filter.md)。
 
 **明细表里的 EBuilder 子字段用同一套键**：在 `DetailTable.formFields` 的字段对象里写 `sformId` / `dataTitle` / `displayColumns` 即可，建表时会一起绑定到目标表单；不写 `sformId` 会建成无关联的裸字段（命令会给出警告）。