weaver-e10-builder 1.5.15 → 1.6.0

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

@@ -1,6 +1,6 @@
 # 浏览数据定义
 
-浏览数据定义控制浏览弹窗的默认高级搜索、可选数据范围和显示 Tab。先查询表单中哪些浏览字段可配置，再查看指定字段由数据源提供的条件与选项，最后只配置已开放的项目。不同浏览来源可能仅开放其中一部分。
+浏览数据定义包含三部分：**高级搜索**设置浏览弹窗中的搜索条件及默认值；**数据范围**限定弹窗里哪些数据可选；**浏览 Tab**设置可见页签、默认页签和顺序。先查询表单中哪些浏览字段可配置，再查看指定字段由数据源提供的条件与选项，最后只配置已开放的项目。不同浏览来源可能仅开放其中一部分。
 
 ## 操作顺序
 
@@ -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。
 
-EB 表单可从表单引擎的表单设置进入。工作流程表单的表单引擎设置页没有独立的“浏览数据定义”；它跟随所属工作流程配置，入口是「流程引擎 → 工作流管理 → 工作流程 → 高级设置 → 浏览数据定义」。先确定工作流程及其关联的表单，再传该表单 ID 和 `--workflow-id <流程ID>`。流程接口使用 `module=ebuildercard`，浏览配置的 `businessId` 是流程 ID，`formId` 是流程关联的表单 ID；同一表单若用于不同流程，应按目标流程分别读取和设置。流程表单预览不会按此配置过滤，应在流程实际使用场景核对。其他表单引擎模块按各自入口和实际开放能力配置。
+EB 表单可从表单引擎的表单设置进入。工作流程表单的表单引擎设置页没有独立的“浏览数据定义”；它跟随所属工作流程配置，入口是「流程引擎 → 工作流管理 → 工作流程 → 高级设置 → 浏览数据定义」。先确定工作流程及其关联的表单，再传该表单 ID 和 `--workflow-id <流程ID>`。配置时以流程 ID 定位所属工作流程，以关联表单 ID 定位浏览字段；同一表单若用于不同流程，应按目标流程分别读取和设置。流程表单预览不会按此配置过滤，应在流程实际使用场景核对。其他表单引擎模块按各自入口和实际开放能力配置。
 
 ## 高级搜索
 
@@ -49,9 +49,9 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 
 | 来源 | `--config` 结构 | 说明 |
 |---|---|---|
-| 人员 `hrm/resource` | `{"rules":[...],"range":"any"}`；完整报文亦可用 `itemDatas[]` | `get` 返回当下布局码表、表单字段候选、矩阵选项和现存范围。`rules[]` 按当前布局校验并转换，与已有项按范围来源合并。 |
-| 部门 `hrm/department` | `{"rules":[...]}`；完整报文亦可用 `records[]` | 已核对指定部门／分部、创建人、当前操作者、表单部门字段。 |
-| 分部 `hrm/subcompany` | `{"rules":[...]}`；完整报文亦可用 `records[]` | 已核对指定分部、创建人、当前操作者、表单分部字段。 |
+| 人员 `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 从实际候选列表取得。 |
@@ -89,11 +89,55 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 }
 ```
 
-上面展示的是 `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` **解码后的条件树**，用于说明嵌套关系；实际 `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`，并在所属工作流程的实际使用场景核对筛选效果。
+
+### 关联 EBuilder 的简便规则
+
+关联 EBuilder 字段的数据范围决定**目标表单的哪些记录可以在浏览弹窗中选择**。只需按目标表单主表字段给出一层 AND／OR 条件时，可使用 `form ebuilder-scope`；复杂嵌套条件使用上面的完整条件树。
+
+```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` 可在需要关联字段为空时填充的场景下使用，缺省关闭。配置文件是规则数组，例如：
+
+```json
+[
+  { "field": "客户状态", "operator": "eq", "value": "启用" },
+  { "field": "客户名称", "operator": "like", "value": "上海" }
+]
+```
+
+| 规则项 | 可用写法 |
+| --- | --- |
+| `operator` | `eq` 等于、`neq` 不等于、`like` 包含、`isnull` 为空、`notnull` 不为空 |
+| `value` | 文本、数字和日期填写目标值；选项类字段填写选项名或唯一的选项值 ID，由 CLI 匹配目标字段的实际选项；`isnull`、`notnull` 不填写 |
+| `valueFrom` + `valueField` | 不填固定 `value`。`currentFormField` 为“变量字段”，引用当前表单的主表字段；`targetFormField` 为“本表字段”，引用被浏览目标表单的主表字段。`valueField` 可写字段名或 ID，重名用 ID。 |
+
+例如，浏览“关联项目”时，让目标表的“关联合同”等于当前表单的“关联合同”；或者让目标表的“关联客户”等于目标表自己的“项目简介”：
+
+```json
+[
+  {"field":"关联合同","operator":"eq","valueFrom":"currentFormField","valueField":"关联合同"},
+  {"field":"关联客户","operator":"eq","valueFrom":"targetFormField","valueField":"项目简介"}
+]
+```
+
+这两种字段引用的保存结构不同。CLI 会先查字段候选，再分别生成变量字段或本表字段的配置；已有范围规则保存前用 `get` 确认，`set --rules` 会以本次规则数组重建这棵简便条件树。当前仅验证了以关联浏览字段作为筛选条件，且简便写法只支持当前表单和目标表单的主表字段。复杂嵌套条件仍使用上节的完整条件树。
+
+例如，只允许选择状态为“启用”的客户：
+
+```bash
+e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> --rules '[{"field":"客户状态","operator":"eq","value":"启用"}]'
+```
+
+设置后用 `get` 回读规则，再在设计器和实际浏览弹窗核对可选数据；`clear` 清空这些规则。简便规则只读取目标表单主表字段，不用它筛选目标明细字段。旧 `form ebuilder-filter` 修改的是字段布局中的过滤参数，不保证被浏览数据定义识别；新增数据范围使用本节命令。
 
 ### 人员范围码表与简化规则
 
-下表是已抓到的范围来源；同一 `groupTypeId` 的 `includeType`、组织维度等下级选项仍应以 `scope get` 实时返回的 `groups[].options` 为准。表单字段候选取 `formFieldCandidates`，矩阵候选取 `matrixOptions`；指定对象先用 `scope candidates` 查询。
+下表是当前可用的范围来源；同一 `groupTypeId` 的 `includeType`、组织维度等下级选项仍应以 `scope get` 实时返回的 `groups[].options` 为准。表单字段候选取 `formFieldCandidates`，矩阵候选取 `matrixOptions`；指定对象先用 `scope candidates` 查询。
 
 | `rules[].kind` | 平台组码 | 主要参数 | 适用说明 |
 |---|---:|---|---|
@@ -102,8 +146,8 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 | `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` |
+| `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`（本分部／含下级／含上级）。
@@ -117,18 +161,18 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 }
 ```
 
-矩阵规则示例结构为 `{"kind":"matrix","sourceId":"...","sourceIdCN":"...","sourceIdType":"2","targetId":"...","targetIdCN":"...","matrixRules":[{"sourceField":"矩阵来源字段ID","sourceType":"customBrowser","targetField":"表单字段ID"}]}`。来源和结果字段 ID 应从所选矩阵的候选接口读取，`matrixRules` 映射矩阵来源字段与当前表单字段；只提供矩阵 ID 无法完成此设置。
+矩阵规则示例结构为 `{"kind":"matrix","sourceId":"...","sourceIdCN":"...","sourceIdType":"2","targetId":"...","targetIdCN":"...","matrixRules":[{"sourceField":"矩阵来源字段ID","sourceType":"customBrowser","targetField":"表单字段ID"}]}`。来源和结果字段 ID 应通过 `scope matrix-options` 读取，`matrixRules` 映射矩阵来源字段与当前表单字段；只提供矩阵 ID 无法完成此设置。
 
 ### 部门、分部范围码表
 
-两者走 `browserDataScope`，浏览类型分别是 `hrm_department` 和 `hrm_subcompany`，不是人员范围的 `hrm_resource`。以下是已核对的 `rules[].type`：
+部门和分部使用各自的数据范围配置，不能套用人员范围规则。以下是当前支持的 `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`）。其它上下级关系码要以相应字段的界面候选与保存报文核对后再补，不按中文含义猜码。
+`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"}]}
@@ -145,4 +189,4 @@ e10-cli form-engine browser-definition tabs set <formId> <fieldId> --module <mod
 
 ## 支持边界
 
-命令入口与能力发现按表单引擎模块统一；底层仅适配已核对报文的浏览来源。当前已适配关联 EBuilder、人员、部门、分部、城市行政区域及自定义浏览框对应的已开放配置项。项目、关联流程等来源会在 `inspect` 中展示平台支持情况，但保存报文未经核对的子项标为 `cli=false`。工作流程路径需同时给关联表单 ID 与 `--workflow-id`；其写入效果须在流程实际使用场景验证。
+命令入口与能力发现按表单引擎模块统一；当前只支持已确认配置结构的浏览来源。当前已适配关联 EBuilder、人员、部门、分部、城市行政区域及自定义浏览框对应的已开放配置项。项目、关联流程等来源会在 `inspect` 中展示平台支持情况，但尚未支持写入的子项标为 `cli=false`。工作流程路径需同时给关联表单 ID 与 `--workflow-id`；其写入效果须在流程实际使用场景验证。