weaver-e10-builder 1.7.1 → 1.7.2

package/skill-docs/actionflows/references/components/ebuilder/ActionEbDelete.md

@@ -1,80 +1,80 @@
-# 删除表单数据（`ActionEbDelete`）
-
-## 何时使用
-
-按筛选条件删除 e-builder 表单数据；还原已删除数据使用 `ActionEbRecover`。
-删除组件只允许“按条件删除”，CLI 不生成无条件删除节点。
-
-## 先查询
-
-查询目标表单、目标表的数据源字段和操作人。前端 `ActionEbDelete` 使用
-`dataSource + ConditionSet`，后端保存字段为 `filterInput`；CLI 计划层使用
-`filterCondition`，由编译器转换为 `filterInput`。
-
-## 不可猜测
-
-筛选条件必须引用目标表真实字段；不能把名称或非本次上下文的字段键写入条件。
-
-## 最小计划
-
-`targetForm`、`person`、`filterCondition`。`nullOpflag` 可选，默认 `false`，对应前端“传空值时执行”开关。
-
-## filterCondition 格式
-
-**以 `references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，也不能省略或传空 `filterCondition`。
-
-条件左值必须来自目标表的 `/api/ebuilder/common/ds/fields` 实时字段接口，不能凭名称、旧缓存或 `getEbField` 结果拼接。右值支持固定值、系统值、上下文、变量和函数等条件规则中定义的类型。
-
-## 计划示例
-
-```json
-{
-  "type": "ActionEbDelete",
-  "params": {
-    "targetForm": {
-      "groupId": "<业务应用ID>",
-      "id": "<表单ID>",
-      "name": "<表单名称>"
-    },
-    "person": { "type": "role" },
-    "filterCondition": {
-      "field": { "id": "<实时字段ID>", "label": "状态" },
-      "operator": "eq",
-      "right": { "type": "fixed", "value": "D02", "label": "闲置" }
-    },
-    "nullOpflag": false
-  }
-}
-```
-
-## 与前端/后端 DTO 的对应关系
-
-前端 `ActionEbDelete` 提交的关键字段如下，CLI 不要求计划直接写这些平台字段：
-
-```json
-{
-  "type": "ActionEbDelete",
-  "targetForm": {
-    "groupId": "<业务应用ID>",
-    "id": "<表单ID>",
-    "text": "<表单名称>",
-    "type": "FORM"
-  },
-  "tableType": [{ "id": "<表单ID>", "name": "<表单名称>" }],
-  "appType": [{ "id": "<业务应用ID>", "name": "<应用名称>" }],
-  "person": "<操作人公式>",
-  "filterInput": {
-    "isNewFilter": true,
-    "isParent": true,
-    "relationship": "1",
-    "datas": ["<由 filterCondition 编译的条件项>"],
-    "parentNode": "",
-    "key": "<编译时生成>"
-  },
-  "nullOpflag": false
-}
-```
-
-`filterInput.datas[].conditions.esbAssign.wId` 必须指向当前删除组件节点，不能指向触发器节点。
-
-当条件左字段是「关联流程」Workflow 时，必须由 Skill 根据实时字段元数据和 `workflowPath.formIds` 反查真实流程表单对象；编译后的左值使用原始数字 `fieldName`、`fieldType:"String"`、顶层 `sformId` 和 `formInfo.formId/layoutId`，不得套用普通业务字段的 `field_` 前缀或把目标表单版本 ID写成 `sformId`。
+# 删除表单数据（`ActionEbDelete`）
+
+## 何时使用
+
+按筛选条件删除 e-builder 表单数据；还原已删除数据使用 `ActionEbRecover`。
+删除组件只允许“按条件删除”，CLI 不生成无条件删除节点。
+
+## 先查询
+
+查询目标表单、目标表的数据源字段和操作人。前端 `ActionEbDelete` 使用
+`dataSource + ConditionSet`，后端保存字段为 `filterInput`；CLI 计划层使用
+`filterCondition`，由编译器转换为 `filterInput`。
+
+## 不可猜测
+
+筛选条件必须引用目标表真实字段；不能把名称或非本次上下文的字段键写入条件。
+
+## 最小计划
+
+`targetForm`、`person`、`filterCondition`。`nullOpflag` 可选，默认 `false`，对应前端“传空值时执行”开关。
+
+## filterCondition 格式
+
+**以 `references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，也不能省略或传空 `filterCondition`。
+
+条件左值必须来自目标表的 `/api/ebuilder/common/ds/fields` 实时字段接口，不能凭名称、旧缓存或 `getEbField` 结果拼接。右值支持固定值、系统值、上下文、变量和函数等条件规则中定义的类型。
+
+## 计划示例
+
+```json
+{
+  "type": "ActionEbDelete",
+  "params": {
+    "targetForm": {
+      "groupId": "<业务应用ID>",
+      "id": "<表单ID>",
+      "name": "<表单名称>"
+    },
+    "person": { "type": "role" },
+    "filterCondition": {
+      "field": { "id": "<实时字段ID>", "label": "状态" },
+      "operator": "eq",
+      "right": { "type": "fixed", "value": "D02", "label": "闲置" }
+    },
+    "nullOpflag": false
+  }
+}
+```
+
+## 与前端/后端 DTO 的对应关系
+
+前端 `ActionEbDelete` 提交的关键字段如下，CLI 不要求计划直接写这些平台字段：
+
+```json
+{
+  "type": "ActionEbDelete",
+  "targetForm": {
+    "groupId": "<业务应用ID>",
+    "id": "<表单ID>",
+    "text": "<表单名称>",
+    "type": "FORM"
+  },
+  "tableType": [{ "id": "<表单ID>", "name": "<表单名称>" }],
+  "appType": [{ "id": "<业务应用ID>", "name": "<应用名称>" }],
+  "person": "<操作人公式>",
+  "filterInput": {
+    "isNewFilter": true,
+    "isParent": true,
+    "relationship": "1",
+    "datas": ["<由 filterCondition 编译的条件项>"],
+    "parentNode": "",
+    "key": "<编译时生成>"
+  },
+  "nullOpflag": false
+}
+```
+
+`filterInput.datas[].conditions.esbAssign.wId` 必须指向当前删除组件节点，不能指向触发器节点。
+
+当条件左字段是「关联流程」Workflow 时，必须由 Skill 根据实时字段元数据和 `workflowPath.formIds` 反查真实流程表单对象；编译后的左值使用原始数字 `fieldName`、`fieldType:"String"`、顶层 `sformId` 和 `formInfo.formId/layoutId`，不得自行拼接字段前缀或把目标表单版本 ID写成 `sformId`。

package/skill-docs/actionflows/references/components/ebuilder/ActionEbUpdate.md

@@ -1,75 +1,75 @@
-# 更新表单数据（`ActionEbUpdate`）
-
-## 何时使用
-
-更新 e-builder 数据；若需要在匹配条件不满足时新增数据，可开启 `needAdd`；删除数据使用 `ActionEbDelete`。
-
-## 先查询
-
-查询目标表单及字段；按条件更新还要确认条件左字段和本次触发器上下文。
-
-## 不可猜测
-
-`id`、`updateData`、`fieldUpdate` 三种定位方式互不替代。`basisValue` 只用于真实上游明细依据值。
-
-更新赋值可以使用固定值、上下文、动作流变量、租户常量或函数/公式；变量必须属于当前动作流场景，常量必须是当前租户真实常量 ID。新建资源和名称引用见 `references/dynamic_resources.md`。
-
-## 最小计划
-
-`targetForm`、`person`、更新赋值，以及与 `opType` 对应的定位参数。
-
-## 三种更新模式
-
-- `opType:"updateData"`：必须配置 `filterCondition`，仅按条件更新；不支持 `basisValue`，也不能同时配置 `updateId` 或 `updateFieldCondition`。
-- `opType:"id"`：必须配置 `updateId`。不填写 `basisValue` 时按数据 ID 更新单条数据；填写真实上游明细依据值后，按依据值批量更新。
-- `opType:"fieldUpdate"`：必须配置 `updateFieldCondition` 和 `updatePolicy`。不填写 `basisValue` 时按字段匹配更新单条数据；填写真实上游明细依据值后，按依据值批量更新。
-
-`basisValue` 只是 `id` 和 `fieldUpdate` 的批量开关，不能用于条件筛选更新。CLI 会在编译前校验这些组合，避免把一个模式的定位参数静默带入另一个模式。
-
-### 条件不满足时插入
-
-`needAdd` 对应平台参数 `EbuilderActionDTO.needAdd`，默认 `false`。设为 `true` 时启用“条件不满足时插入”：匹配到目标记录时更新，未匹配到时新增。需要“存在则更新、否则新增”时应设置 `needAdd: true`，不需要另行组合新增组件。
-
-内置 MQ 监听来源同样可使用 `opType:"fieldUpdate"` 配合 `needAdd:true`；匹配字段不能同时作为主表更新赋值目标。主表 `updates` 和明细 `detail` 可以配置在同一节点。
-
-当 `id` 或 `fieldUpdate` 配置了 `basisValue` 时，如果 `updateId` 或 `updateFieldCondition.updateField[].assign` 的来源字段 `paramKey` 明确位于该依据值下级（例如依据值为 `100.12345[]`，来源字段为 `100.12345[].67890`），CLI 会按前端“依据值下级”协议编译为 `type:"10"`、`config.switchType:"sub"`。只有路径明确以该依据值加 `.` 开头时才会转换；不相关的明细字段仍按普通动态上下文编译，不凭路径形状猜测依据关系。`basisValue` 和来源字段都应使用前置上下文接口返回的真实字段元数据。
-
-### 明细表策略
-
-更新组件的 `ActionEbDlg` 会为每张明细表单独保存策略。`detail` 每项至少包含 `detailTableId`，可使用以下结构：
-
-```json
-{
-  "detailTableId": "<目标明细表ID>",
-  "operateType": "update",
-  "basisValue": {"paramKey": "<来源明细paramKey>[]", "label": "<来源明细表>"},
-  "updateType": "fields",
-  "updateFieldCondition": {
-    "updateField": [
-      {"fieldKey": "<匹配字段ID>", "assign": {"kind": "context", "paramKey": "<来源字段>"}}
-    ]
-  },
-  "updatePolicy": "ALL",
-  "mapping": {"<来源字段>": "<目标明细字段ID>"},
-  "constants": {"<目标明细字段ID>": "<固定值>"},
-  "formula": {},
-  "deleteFields": []
-}
-```
-
-`operateType` 与前端枚举一致：`default`、`add`、`update`、`updateAdd`、`cover`、`delete`。
-
-- `add`/`cover`：用于按依据值新增或覆盖明细；有字段赋值时需要 `basisValue`。
-- `update`/`updateAdd`：必须有 `basisValue` 和至少一个字段赋值；`updateType` 只能是 `fields` 或 `rowId`。`fields` 必须提供 `updateFieldCondition.updateField`，`rowId` 必须提供 `rowId`。
-- `delete`：`updateType` 可为 `fields`、`rowId` 或 `deleteAll`。前两者需要 `basisValue` 和对应条件，`deleteAll` 不需要依据值且不配置字段赋值。
-- `updatePolicy` 仅用于 `update`/`updateAdd`，可选 `ALL`、`FIRST`、`LAST`、`ZERO`、`EXCEPTION`。
-
-当 `operateType` 为 `update` 或 `updateAdd` 且 `updateType` 为 `fields` 时，`updateFieldCondition.updateField[].fieldKey` 是专门用于匹配的条件字段，不能同时出现在 `mapping`、`constants` 或 `formula` 的目标字段中。编译后的 `EsbDetailForm.data` 与 `EsbDetailForm.updateFieldCondition` 对同一字段只能保留一份；主表的 `updateFieldCondition` 与 `setting.main` 也遵循同样规则。按 `rowId` 更新时不能再配置 `updateFieldCondition`。
-
-`rowId` 使用动态赋值对象，例如 `{"kind":"context","paramKey":"<来源明细ID>","label":"明细数据ID"}`；CLI 会将它包装为后端 `EsbDetailForm.rowId` 的 `FieldValue`。`deleteFields` 仍表示清除字段配置，不表示删除明细行；删除明细行必须使用 `operateType:"delete"`。
-
-## filterCondition 格式（opType=updateData 定位条件）
-
-**以 `references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，否则编译报「左侧字段 id 不在目标表单实时字段列表中」。
-
-当条件左字段是「关联流程」Workflow 时，必须由 Skill 根据实时字段元数据和 `workflowPath.formIds` 反查真实流程表单对象；编译后的左值使用原始数字 `fieldName`、`fieldType:"String"`、顶层 `sformId` 和 `formInfo.formId/layoutId`，不得套用普通业务字段的 `field_` 前缀或把目标表单版本 ID写成 `sformId`。
+# 更新表单数据（`ActionEbUpdate`）
+
+## 何时使用
+
+更新 e-builder 数据；若需要在匹配条件不满足时新增数据，可开启 `needAdd`；删除数据使用 `ActionEbDelete`。
+
+## 先查询
+
+查询目标表单及字段；按条件更新还要确认条件左字段和本次触发器上下文。
+
+## 不可猜测
+
+`id`、`updateData`、`fieldUpdate` 三种定位方式互不替代。`basisValue` 只用于真实上游明细依据值。
+
+更新赋值可以使用固定值、上下文、动作流变量、租户常量或函数/公式；变量必须属于当前动作流场景，常量必须是当前租户真实常量 ID。新建资源和名称引用见 `references/dynamic_resources.md`。
+
+## 最小计划
+
+`targetForm`、`person`、更新赋值，以及与 `opType` 对应的定位参数。
+
+## 三种更新模式
+
+- `opType:"updateData"`：必须配置 `filterCondition`，仅按条件更新；不支持 `basisValue`，也不能同时配置 `updateId` 或 `updateFieldCondition`。
+- `opType:"id"`：必须配置 `updateId`。不填写 `basisValue` 时按数据 ID 更新单条数据；填写真实上游明细依据值后，按依据值批量更新。
+- `opType:"fieldUpdate"`：必须配置 `updateFieldCondition` 和 `updatePolicy`。不填写 `basisValue` 时按字段匹配更新单条数据；填写真实上游明细依据值后，按依据值批量更新。
+
+`basisValue` 只是 `id` 和 `fieldUpdate` 的批量开关，不能用于条件筛选更新。CLI 会在编译前校验这些组合，避免把一个模式的定位参数静默带入另一个模式。
+
+### 条件不满足时插入
+
+`needAdd` 对应平台参数 `EbuilderActionDTO.needAdd`，默认 `false`。设为 `true` 时启用“条件不满足时插入”：匹配到目标记录时更新，未匹配到时新增。需要“存在则更新、否则新增”时应设置 `needAdd: true`，不需要另行组合新增组件。
+
+内置 MQ 监听来源同样可使用 `opType:"fieldUpdate"` 配合 `needAdd:true`；匹配字段不能同时作为主表更新赋值目标。主表 `updates` 和明细 `detail` 可以配置在同一节点。
+
+当 `id` 或 `fieldUpdate` 配置了 `basisValue` 时，如果 `updateId` 或 `updateFieldCondition.updateField[].assign` 的来源字段 `paramKey` 明确位于该依据值下级（例如依据值为 `100.12345[]`，来源字段为 `100.12345[].67890`），CLI 会按前端“依据值下级”协议编译为 `type:"10"`、`config.switchType:"sub"`。只有路径明确以该依据值加 `.` 开头时才会转换；不相关的明细字段仍按普通动态上下文编译，不凭路径形状猜测依据关系。`basisValue` 和来源字段都应使用前置上下文接口返回的真实字段元数据。
+
+### 明细表策略
+
+更新组件的 `ActionEbDlg` 会为每张明细表单独保存策略。`detail` 每项至少包含 `detailTableId`，可使用以下结构：
+
+```json
+{
+  "detailTableId": "<目标明细表ID>",
+  "operateType": "update",
+  "basisValue": {"paramKey": "<来源明细paramKey>[]", "label": "<来源明细表>"},
+  "updateType": "fields",
+  "updateFieldCondition": {
+    "updateField": [
+      {"fieldKey": "<匹配字段ID>", "assign": {"kind": "context", "paramKey": "<来源字段>"}}
+    ]
+  },
+  "updatePolicy": "ALL",
+  "mapping": {"<来源字段>": "<目标明细字段ID>"},
+  "constants": {"<目标明细字段ID>": "<固定值>"},
+  "formula": {},
+  "deleteFields": []
+}
+```
+
+`operateType` 与前端枚举一致：`default`、`add`、`update`、`updateAdd`、`cover`、`delete`。
+
+- `add`/`cover`：用于按依据值新增或覆盖明细；有字段赋值时需要 `basisValue`。
+- `update`/`updateAdd`：必须有 `basisValue` 和至少一个字段赋值；`updateType` 只能是 `fields` 或 `rowId`。`fields` 必须提供 `updateFieldCondition.updateField`，`rowId` 必须提供 `rowId`。
+- `delete`：`updateType` 可为 `fields`、`rowId` 或 `deleteAll`。前两者需要 `basisValue` 和对应条件，`deleteAll` 不需要依据值且不配置字段赋值。
+- `updatePolicy` 仅用于 `update`/`updateAdd`，可选 `ALL`、`FIRST`、`LAST`、`ZERO`、`EXCEPTION`。
+
+当 `operateType` 为 `update` 或 `updateAdd` 且 `updateType` 为 `fields` 时，`updateFieldCondition.updateField[].fieldKey` 是专门用于匹配的条件字段，不能同时出现在 `mapping`、`constants` 或 `formula` 的目标字段中。编译后的 `EsbDetailForm.data` 与 `EsbDetailForm.updateFieldCondition` 对同一字段只能保留一份；主表的 `updateFieldCondition` 与 `setting.main` 也遵循同样规则。按 `rowId` 更新时不能再配置 `updateFieldCondition`。
+
+`rowId` 使用动态赋值对象，例如 `{"kind":"context","paramKey":"<来源明细ID>","label":"明细数据ID"}`；CLI 会将它包装为后端 `EsbDetailForm.rowId` 的 `FieldValue`。`deleteFields` 仍表示清除字段配置，不表示删除明细行；删除明细行必须使用 `operateType:"delete"`。
+
+## filterCondition 格式（opType=updateData 定位条件）
+
+**以 `references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，否则编译报「左侧字段 id 不在目标表单实时字段列表中」。
+
+当条件左字段是「关联流程」Workflow 时，必须由 Skill 根据实时字段元数据和 `workflowPath.formIds` 反查真实流程表单对象；编译后的左值使用原始数字 `fieldName`、`fieldType:"String"`、顶层 `sformId` 和 `formInfo.formId/layoutId`，不得自行拼接字段前缀或把目标表单版本 ID写成 `sformId`。

package/skill-docs/actionflows/references/components/ebuilder/EnquiryForm.md

@@ -1,111 +1,113 @@
-# 查询表单数据（`EnquiryForm`）
-
-## 何时使用
-
-查询 e-builder 表单列表或分组统计；按单条 ID 读取使用 `EbGetDataById`。
-
-## 先查询
-
-查询数据源、全部字段、筛选字段、输出字段和查询操作人。
-
-`actionflow data-source-condition-fields '{"dataSource":{...}}'` 查询条件左值；`filter.field.id` 使用其中的 `id`。`name` 唯一时可兼容输入，重名必须使用 id。`queryFields` 的 id 来自 `showDataSourceFields`，下游引用使用 `component-context-fields` 的 paramKey；不要把临时上下文 id 当条件字段 id。CLI 输出的条件 `fieldName` 取真实字段 `name`。
-
-## 不可猜测
-
-筛选、排序、分组和输出字段都必须来自当前数据源；统计结果应作为后续节点上下文使用。
-
-## 最小计划
-
-`dataSource`、`person`；按 `opType` 补充查询字段，必须提供 `filter` 或 `conditionFormula`。未给出条件时应向用户确认具体筛选条件；即使需要查询全部数据，也不能臆造中性条件，应先确认并使用 `ds/fields` 返回的真实字段及支持的运算符。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选实时可选字段。
-
-业务模块数据源使用 `dataSourceKind:"business_module"`，可用平台实时分类名 `groupName` 或分类 ID `groupId` 缩小范围（例如 HRM）；未指定时逐分类查找，存在多个候选时须明确选择。字段查询沿用选中数据源返回的服务组。
-
-## 动态分页和条件
-
-- `formPageNo`、`formPageSize` 支持固定值、上下文、系统变量、变量、常量和函数/公式。
-- 需要由上游计算整段查询条件时使用 `conditionFormula`；它会写为 `conditionType:"assign"`，此时不得同时传 `filter`。
-- 普通业务筛选继续使用 `filter`，两种条件模式不能混用。
-
-## 分组/汇总查询
-
-`opType:"groupFields"` 是原生“分组/汇总”能力，不需要规则集或外部计算组件：
-
-- `groupFields` 是分组维度：`[{"field":"<真实字段id>"}]`；没有分组维度时传空数组。
-- `groupMessage` 是汇总值：`[{"field":"<真实字段id>","aggregator":"SUM"}]`。
-- 可用聚合方式：`SUM`、`MIN`、`AVG`、`MAX`、`COUNT`、`DISTINCTCOUNT`。其中 `SUM`/`AVG` 只用于数值字段。
-- 汇总输出字段名由平台固定为 `s_sum_<字段id>`、`s_min_<字段id>`、`s_avg_<字段id>`、`s_max_<字段id>`、`s_count_<字段id>`、`s_distinctcount_<字段id>`；后续节点引用它时使用 `kind:"query_result"`、`fieldId:"s_sum_<字段id>"`、`source:"<查询动作ref>"`、`index:0`。
-
-示例：汇总“收款金额”并让后续节点取第一条汇总结果：
-
-```json
-{
-  "type": "EnquiryForm",
-  "ref": "收款汇总",
-  "params": {
-    "dataSource": {"groupId":"<应用id>","id":"<合同收款表id>","text":"合同收款表"},
-    "person": {"type":"role"},
-    "opType": "groupFields",
-    "filter": {"field":{"id":"<关联项目字段id>","label":"关联项目"},"operator":"eq","right":{"kind":"context","paramKey":"<当前表单>.关联项目"}},
-    "groupFields": [],
-    "groupMessage": [{"field":"<收款金额字段id>","aggregator":"SUM"}]
-  }
-}
-```
-
-## 批量新增主表字段引用查询结果（2026-08-27 真机钉死）
-
-**结论：当需求确实需要反查时，EnquiryForm 查询结果可以赋给 `batchInsert` 主表字段（标量），但只限"单值反查"场景**。它不是任何表单新增动作的默认前置节点。手动创建成功样本：`references/examples/enquiry-form-batch-insert-scene2.json`（ApproveTrigger → EnquiryForm → ActionEbAdd(batchInsert) → Output）。样例中的 `opText` 是历史平台序列化快照，不是生成模板；生成时只依据语义 plan 和实时字段元数据，尤其不要复制其中 Workflow 左值的旧 `field_`/`Workflow` 组合。
-
-关键结构（与旧结论不同，已修正）：
-
-1. **EnquiryForm 节点（首动作）**：
-   - 此历史样本的 `dataSource.type` 是 `LOGIC`；生成时必须使用当前 Browser 返回的真实 `type/sourceType`，不能据样本推断。查询服务组是 `weaver-ebuilder-form-service`。
-   - `queryFields[].id = "id"`（简写，不是 `{表id}[].id`）；`fieldGroup = { name: 表名, id: 表id }`
-   - 筛选：`filterInput.datas[].conditions.value` 用流程上下文 type=3（`ApprovalData.{wfId}.requestId`）
-   - 首动作 **不需要 sources**（undefined），ActionEbAdd 的 sources 指向 EnquiryForm 节点 wId
-
-2. **主表字段引用查询结果（项目名称 5453）**：
-   - assign：`type=3`，`value = "FormData.{查询表id}[{positionId}].id"`（**数组下标用 positionId 而非 `[]`**）
-   - `config.comType = "EnquiryForm"`、`config.comId = EnquiryForm 节点 id`、`config.paramKey = "{查询表id}[].id"`（paramKey 保持 `[]` 数组标记）
-   - **childs 必须带固定值取下标**：`[{ type: "1", value: "0", position: "{positionId}" }]`（value=0 取第一条）
-   - `frontId` = 查询结果字段的真实 `fieldId`（不能使用公式对象临时 id）；前端用它定位查询节点输出字段，否则会回显为“数据源查询（已删除）”并标红。
-
-3. 其余明细字段仍用依据值下级 type=10 直连（paramKey `{wfId}.{明细表id}[].{子字段id}`，source=event 节点 id）。
-
-4. 挂接注意：EnquiryForm 作为**流程首动作**保存成功，首动作不要补 sources。数据源类型以当前接口实际返回为准。
-
-计划中引用该结果时，必须显式写 `kind:"query_result"`，不能把它写成普通流程字段。例如：
-
-```json
-{
-  "mapping": {
-    "<查询表单id>[].id": {
-      "target": "<目标字段id>",
-      "kind": "query_result",
-      "source": "<EnquiryForm动作ref>",
-      "formId": "<查询表单id>",
-      "fieldId": "id",
-      "label": "数据ID",
-      "index": 0
-    }
-  }
-}
-```
-
-其中查询动作需显式声明例如 `{"type":"EnquiryForm","ref":"项目查询","params":{...}}`，后续写 `source:"项目查询"`。编译器会将该语义 `ref` 替换为实际节点 ID，并生成保存所需的 `childs` 下标公式；禁止使用或猜测平台节点 ID。
-
-## 关键边界：只支持"单值反查"，不支持"逐行明细反查"（2026-08-27 用户确认）
-
-**适用条件（场景2 成立的唯一前提）**：EnquiryForm 的筛选条件用的是**流程级唯一值**（如 `关联流程 eq requestId`），业务上一个流程只对应一条查询结果 → 取第一条（childs value=0）就是唯一那条，赋值主表字段正确。
-
-**禁止场景（多条结果）**：如果筛选条件用的是**明细行 id/明细字段**（如"按任务编号反查"），查询结果会有多条，且**数据源返回结果的顺序与流程明细表的行顺序不保证一致**（第 1 行明细对应的结果可能排在返回结果第 5 行）。此时：
-- 无法用"取第一条"对应到正确的明细行；
-- 无法把查询结果作为依据值（basisValue）传给下方组件——明细字段值仍需以**流程明细表本身作为依据值**（type=10 直连）；
-- **转化规则必须逐行做明细字段转化，多条结果做不到 → 该场景明确拒绝，不硬凑 EnquiryForm**。
-
-一句话决策：**EnquiryForm 反查只能给"与明细行无关的全局单值"（主表字段，按流程级唯一条件查）；凡需"按每行明细反查对应值"的，直接拒绝并告知用户**。
-
-## 曾经的错误结论（已推翻，勿沿用）
-
-- ~~EnquiryForm 输出是列表数组不能赋主表标量~~ → 实际通过 childs 固定值取下标（value=0 第一条）实现（仅限单值反查）。
-- ~~批量新增场景不要用 EnquiryForm 反查~~ → 单值反查是标准做法，见上；逐行反查仍不可行。
+# 查询表单数据（`EnquiryForm`）
+
+## 何时使用
+
+查询 e-builder 表单列表或分组统计；按单条 ID 读取使用 `EbGetDataById`。
+
+## 先查询
+
+查询数据源、全部字段、筛选字段、输出字段和查询操作人。
+
+`actionflow data-source-condition-fields '{"dataSource":{...}}'` 查询条件左值；`filter.field.id` 使用其中的 `id`。`name` 唯一时可兼容输入，重名必须使用 id。`queryFields` 的 id 来自 `showDataSourceFields`，下游引用使用 `component-context-fields` 的 paramKey；不要把临时上下文 id 当条件字段 id。CLI 输出的条件 `fieldName` 取真实字段 `name`。
+
+## 不可猜测
+
+筛选、排序、分组和输出字段都必须来自当前数据源；统计结果应作为后续节点上下文使用。
+
+## 最小计划
+
+`dataSource`、`person`；按 `opType` 补充查询字段，必须提供 `filter` 或 `conditionFormula`。未给出条件时应向用户确认具体筛选条件；即使需要查询全部数据，也不能臆造中性条件，应先确认并使用 `ds/fields` 返回的真实字段及支持的运算符。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选实时可选字段。
+
+业务模块数据源使用 `dataSourceKind:"business_module"`，可用平台实时分类名 `groupName` 或分类 ID `groupId` 缩小范围（例如 HRM）；未指定时逐分类查找，存在多个候选时须明确选择。字段查询沿用选中数据源返回的服务组。
+
+`countFlag`（返回总数）和 `parseMark`（返回关联字段的显示名称）默认开启；需求明确关闭时可分别传 `false`。下游引用总数时，应在该配置下查询 `getComponentContext` 并使用接口返回的真实字段；CLI 不补造 `response.count`。
+
+## 动态分页和条件
+
+- `formPageNo`、`formPageSize` 支持固定值、上下文、系统变量、变量、常量和函数/公式。
+- 需要由上游计算整段查询条件时使用 `conditionFormula`；它会写为 `conditionType:"assign"`，此时不得同时传 `filter`。
+- 普通业务筛选继续使用 `filter`，两种条件模式不能混用。
+
+## 分组/汇总查询
+
+`opType:"groupFields"` 是原生“分组/汇总”能力，不需要规则集或外部计算组件：
+
+- `groupFields` 是分组维度：`[{"field":"<真实字段id>"}]`；没有分组维度时传空数组。
+- `groupMessage` 是汇总值：`[{"field":"<真实字段id>","aggregator":"SUM"}]`。
+- 可用聚合方式：`SUM`、`MIN`、`AVG`、`MAX`、`COUNT`、`DISTINCTCOUNT`。其中 `SUM`/`AVG` 只用于数值字段。
+- 汇总输出字段名由平台固定为 `s_sum_<字段id>`、`s_min_<字段id>`、`s_avg_<字段id>`、`s_max_<字段id>`、`s_count_<字段id>`、`s_distinctcount_<字段id>`；后续节点引用它时使用 `kind:"query_result"`、`fieldId:"s_sum_<字段id>"`、`source:"<查询动作ref>"`、`index:0`。
+
+示例：汇总“收款金额”并让后续节点取第一条汇总结果：
+
+```json
+{
+  "type": "EnquiryForm",
+  "ref": "收款汇总",
+  "params": {
+    "dataSource": {"groupId":"<应用id>","id":"<合同收款表id>","text":"合同收款表"},
+    "person": {"type":"role"},
+    "opType": "groupFields",
+    "filter": {"field":{"id":"<关联项目字段id>","label":"关联项目"},"operator":"eq","right":{"kind":"context","paramKey":"<当前表单>.关联项目"}},
+    "groupFields": [],
+    "groupMessage": [{"field":"<收款金额字段id>","aggregator":"SUM"}]
+  }
+}
+```
+
+## 批量新增主表字段引用查询结果（2026-08-27 真机钉死）
+
+**结论：当需求确实需要反查时，EnquiryForm 查询结果可以赋给 `batchInsert` 主表字段（标量），但只限"单值反查"场景**。它不是任何表单新增动作的默认前置节点。手动创建成功样本：`references/examples/enquiry-form-batch-insert-scene2.json`（ApproveTrigger → EnquiryForm → ActionEbAdd(batchInsert) → Output）。样例中的 `opText` 是历史平台序列化快照，不是生成模板；生成时只依据语义 plan 和实时字段元数据，尤其不要复制其中 Workflow 左值的旧 `field_`/`Workflow` 组合。
+
+关键结构（与旧结论不同，已修正）：
+
+1. **EnquiryForm 节点（首动作）**：
+   - 此历史样本的 `dataSource.type` 是 `LOGIC`；生成时必须使用当前 Browser 返回的真实 `type/sourceType`，不能据样本推断。查询服务组是 `weaver-ebuilder-form-service`。
+   - `queryFields[].id = "id"`（简写，不是 `{表id}[].id`）；`fieldGroup = { name: 表名, id: 表id }`
+   - 筛选：`filterInput.datas[].conditions.value` 用流程上下文 type=3（`ApprovalData.{wfId}.requestId`）
+   - 首动作 **不需要 sources**（undefined），ActionEbAdd 的 sources 指向 EnquiryForm 节点 wId
+
+2. **主表字段引用查询结果（项目名称 5453）**：
+   - assign：`type=3`，`value = "FormData.{查询表id}[{positionId}].id"`（**数组下标用 positionId 而非 `[]`**）
+   - `config.comType = "EnquiryForm"`、`config.comId = EnquiryForm 节点 id`、`config.paramKey = "{查询表id}[].id"`（paramKey 保持 `[]` 数组标记）
+   - **childs 必须带固定值取下标**：`[{ type: "1", value: "0", position: "{positionId}" }]`（value=0 取第一条）
+   - `frontId` = 查询结果字段的真实 `fieldId`（不能使用公式对象临时 id）；前端用它定位查询节点输出字段，否则会回显为“数据源查询（已删除）”并标红。
+
+3. 其余明细字段仍用依据值下级 type=10 直连（paramKey `{wfId}.{明细表id}[].{子字段id}`，source=event 节点 id）。
+
+4. 挂接注意：EnquiryForm 作为**流程首动作**保存成功，首动作不要补 sources。数据源类型以当前接口实际返回为准。
+
+计划中引用该结果时，必须显式写 `kind:"query_result"`，不能把它写成普通流程字段。例如：
+
+```json
+{
+  "mapping": {
+    "<查询表单id>[].id": {
+      "target": "<目标字段id>",
+      "kind": "query_result",
+      "source": "<EnquiryForm动作ref>",
+      "formId": "<查询表单id>",
+      "fieldId": "id",
+      "label": "数据ID",
+      "index": 0
+    }
+  }
+}
+```
+
+其中查询动作需显式声明例如 `{"type":"EnquiryForm","ref":"项目查询","params":{...}}`，后续写 `source:"项目查询"`。编译器会将该语义 `ref` 替换为实际节点 ID，并生成保存所需的 `childs` 下标公式；禁止使用或猜测平台节点 ID。
+
+## 关键边界：只支持"单值反查"，不支持"逐行明细反查"（2026-08-27 用户确认）
+
+**适用条件（场景2 成立的唯一前提）**：EnquiryForm 的筛选条件用的是**流程级唯一值**（如 `关联流程 eq requestId`），业务上一个流程只对应一条查询结果 → 取第一条（childs value=0）就是唯一那条，赋值主表字段正确。
+
+**禁止场景（多条结果）**：如果筛选条件用的是**明细行 id/明细字段**（如"按任务编号反查"），查询结果会有多条，且**数据源返回结果的顺序与流程明细表的行顺序不保证一致**（第 1 行明细对应的结果可能排在返回结果第 5 行）。此时：
+- 无法用"取第一条"对应到正确的明细行；
+- 无法把查询结果作为依据值（basisValue）传给下方组件——明细字段值仍需以**流程明细表本身作为依据值**（type=10 直连）；
+- **转化规则必须逐行做明细字段转化，多条结果做不到 → 该场景明确拒绝，不硬凑 EnquiryForm**。
+
+一句话决策：**EnquiryForm 反查只能给"与明细行无关的全局单值"（主表字段，按流程级唯一条件查）；凡需"按每行明细反查对应值"的，直接拒绝并告知用户**。
+
+## 曾经的错误结论（已推翻，勿沿用）
+
+- ~~EnquiryForm 输出是列表数组不能赋主表标量~~ → 实际通过 childs 固定值取下标（value=0 第一条）实现（仅限单值反查）。
+- ~~批量新增场景不要用 EnquiryForm 反查~~ → 单值反查是标准做法，见上；逐行反查仍不可行。