weaver-e10-builder 1.5.1 → 1.5.3

package/skill-docs/_catalog.md

@@ -15,6 +15,7 @@
 | 字段联动、跨表带出、field-linkage、多跳带出、带出字段赋值、Text 字段取名称 | `references/form/guide-field-linkage.md` |
 | 新建表单、form create、EB 表单标准创建流程 | `references/form/guide-create-form.md` |
 | 二级明细、子明细、父级行标识、子级行标识、多级明细 | `references/form/guide-form-sub-detail.md` |
+| 物理表、多物理表、附属物理表、saveFormTable、getFormAGroupList、字段管理其他页签、字段超过100、add-physical-table、add-physical-field | `references/form/guide-form-physical-table.md` |
 | 虚拟表、虚拟表单、数据源表单、业务表展示、数据加工结果 | `references/form/guide-virtual-form.md` |
 | 字段定义、字段类型、关联字段码表、DateRange、multiple | `references/form/ref-form-fields.md` |
 | FLOW/EXCEL、布局样表、布局蓝图、字段分组、singleRow | `references/form/guide-form-layout-planning.md` |

package/skill-docs/actionflows/SKILL.md

@@ -49,12 +49,12 @@ description: "将业务需求编译为 Weaver ESB 动作流，或读取已有动
 2. 只传 `component-describe` 声明的参数；固定值与动态值根据业务需求选择，不能为了动态而动态。
 3. 语义 plan 的节点配置统一放在 `params`：`event.params`、`actions[*].params` 以及条件/循环内部节点的 `params`。`data` 仅属于平台回读/更新 DTO，不能出现在 `generate` 语义计划中；CLI 会在调用任何平台接口前拒绝该结构，并提示具体路径。
 4. 中文 plan 写入当前工作区 `.actionflow-plans/`，以 `planFile` 传给 CLI；不在 Skill 目录写临时文件。CLI 不会自动删除 plan；确认 `valid=true`、`saved=true`、`readBackVerified=true` 后才允许手工清理。
-5. 不把 `Output` 写入 `actions`。需要配置终止状态、提示或页面动作时使用顶层 `finalOutput.params`；平台内部 FormulaBean 由 CLI 生成，只有组件契约明确要求前端原对象时才传原生 DTO。
+5. 不把 `Output` 写入 `actions`。需要配置终止状态、提示或页面动作时使用顶层 `finalOutput.params`；提醒内容使用前端富文本组件对应的 `reminderContent`（`ContestSettingDTO`，动态片段放在 `formulaBeans`），不要使用旧的 `reminderMsgFormula`；平台内部 FormulaBean 由 CLI 生成，只有组件契约明确要求前端原对象时才传原生 DTO。
 5.1. 所有 CLI 生成或继续编译的 FormulaBean，只要包含 `frontId`，允许使用空串；非空时必须使用平台真实字段 ID 的纯数字字符串。`field_<数字>` 仅可在生成时规范化为 `<数字>`。禁止把字段名、paramKey 尾段、临时公式 ID 或其他包含字母/符号的值写入 `frontId`；非空值无法解析为纯数字时必须直接报错。
 6. 定时组件优先使用平台原生频率：`rate=1` 一次、`2` 按小时、`3` 按日、`4` 按周、`5` 按月，并按需提供 `cycle`、`hour`、`day`、`week`、`atWeek`、`atWeekDetail` 或 `lastWeek`；只有明确选择 `rate=6` 时才传 `cornString`。图形化频率必须提供 `startTime`。
 7. 触发器或查询组件未被需求明确限制输出字段时，不传 `queryFields`（或传空数组）：CLI 会默认全选，包含“数据ID”。如果需求明确引用某个业务字段，必须从当前租户的实时字段接口/字段选择器获取完整字段对象并保存真实 `id`，不能凭字段名、临时 ID 或只拼 `id/content`。查询节点还必须使用自身真实节点 ID 作为 `dataSource.enquiryId`，否则平台可能静默丢弃业务字段。正式回读必须确认每个声明的 `queryFields` 仍存在；缺失即生成失败，不能仅凭接口 `code=200`、`saved=true` 判定成功。e-builder 数据触发后发送消息且未显式给链接时，CLI 自动补 PC/移动端当前记录详情链接；不手写 `{formId}` / `{dataId}` 的 FormulaBean。查询结果字段动态赋值必须按手工设计器对象编译：普通业务字段使用 `FormField.<查询表单ID>.field_<真实字段ID>`，`config.paramKey` 使用 `<查询表单ID>.field_<真实字段ID>`，`config.fieldInfo.tablePrimaryKey` 为 `FormField`；系统字段按平台真实字段键（例如 `id`）保留。禁止使用 `FormData.<表单ID>[临时位置]...`，也禁止把临时公式 ID 当作 `frontId`。
 8. `ActionEbAdd` 批量新增以 `basisValue` 为明细行上下文：来源于该行的字段都用 `mapping`，编译为“依据值下级”（`switchType:"sub"`），下拉字段也同样处理。只有已核实来源/目标选项 ID 不同且语义需要转换时，才使用 `SWITCH`。关联 e-builder 字段应引用查询结果的 `数据ID`，固定格式为 `{target,kind:"query_result",source:"<EnquiryForm ref>",formId,fieldId:"id",index:0}`；`kind:"enquiry"`、`sourceId` 等旧写法会直接报错，绝不降级为空固定值。
-9. 动态赋值可使用或新建动作流变量、租户常量：已有资源必须用真实 ID；计划新建变量写顶层 `variables[]`，新建常量写 `constantDefinitions[]`，常量分组可传 `groupPk` 或 `groupName`。变量按当前 `applicationId + sceneId` 隔离，常量按分组跨动作流复用。生成时先调用真实接口创建/解析资源，再编译为变量 `type:"7"` 或常量 `type:"5"` FormulaBean；详细格式见 `references/dynamic_resources.md`。消息 `parts` 也支持 `variable`/`constant` 动态片段。
+9. 动态赋值可使用或新建动作流变量、租户常量：已有资源必须用真实 ID；计划新建变量写顶层 `variables[]`，新建常量写 `constantDefinitions[]`，常量分组可传 `groupPk` 或 `groupName`。变量按当前 `applicationId + sceneId` 隔离，常量按分组跨动作流复用。生成时先调用真实接口创建/解析资源，再编译为变量 `type:"7"` 或常量 `type:"5"` FormulaBean；详细格式见 `references/dynamic_resources.md`。消息 `SendMessage.msgTitlev/msgContentv/picLink/msgPcLink/msgMobileLink` 的 `parts` 支持 `variable`/`constant` 动态片段，并统一保存为 `ContestSettingDTO`。
 9.1. 每个参数先分为“动态公式属性”“动态人员属性”“固定平台资源属性”三类：上下文、系统变量、变量、常量、函数/公式必须保留为 FormulaBean；动态人员必须使用真实人员字段上下文或系统变量，不得把引用里的 `id` 当人员 Browser ID 查询；工作流、文档目录、按钮、规则等平台资源只有在其组件契约明确提供动态引用时才允许动态化。生成前必须记录本次组件/属性的判定，生成后按属性检查回读结果；具体映射和验证状态见 `references/dynamic_capability_matrix.md`。
 10. 自定义事件和内置 MQ 的参数必须按对应平台组件说明提供原生参数对象；`CustomTrigger.customData`、`InnerMQListener.receiveParams`、`InnerMQSend.sendParams` 不能用猜测的字段替代。若验证要求“输入参数里有字段”，必须在生成前提供至少一行真实原生参数；`tables:[]`、`tableList:[]` 或省略 `receiveParams` 只能表示无输入参数，不能作为有参数的占位。`InnerMQListener` 与 `InnerMQSend` 是动作流级互斥组件，同一计划（包括条件/循环嵌套）同时出现时，CLI 在任何平台写接口前直接报错。
 11. 根触发节点的 `event.attr.icon` 必须使用平台真实图标：`CustomTrigger` 为 `Icon-N-Triggerrul`，`InnerMQListener` 为 `Icon-built-in-mq-listening-mcolor`；组件目录里的动作图标不能覆盖根触发器图标。保存后回读必须同时检查触发器图标、已声明输入参数的数量和查询字段，不能仅凭 `valid=true` / `saved=true` 判定配置正确。
@@ -126,11 +126,11 @@ e10-cli actionflow update '@update-plan.json' --out update-result.json       #
 
 ## 触发器边界
 
-当前可生成的事件触发器：`ApproveTrigger`（流程事件）、`EventFormData`（e-builder 数据新增/更新/删除/字段变化）、`EventButton`（点击 e-builder 指定按钮）、`DateTrigger`、`TimeBatchTrigger`、`SimpleScheduler`、`CustomTrigger`（自定义事件）和 `InnerMQListener`（内置 MQ 监听）。`EventButton` 必须先用 `e10-cli actionflow form-buttons '{"tableId":"<表单ID>","appId":"<应用ID>"}'` 查询真实按钮，再以 `targetForm`、`buttonType:[{id,name,buttonLocation:"before"|"after"}]` 和可选 `triggerType` 生成；不得用 `EventFormData` 冒充按钮点击。`CustomTrigger` 和 `InnerMQListener` 的原生参数要求见 `references/components/trigger/CustomTrigger.md`、`references/components/trigger/InnerMQListener.md`。
+当前可生成的事件触发器：`ApproveTrigger`（流程事件）、`EventFormData`（e-builder 数据新增/更新/删除/字段变化）、`EventButton`（点击 e-builder 指定按钮）、`DateTrigger`、`TimeBatchTrigger`、`SimpleScheduler`、`CustomTrigger`（自定义事件）、`InnerMQListener`（内置 MQ 监听）和 `WebHookTrigger`（外部 WebHook 请求）。`EventButton` 必须先用 `e10-cli actionflow form-buttons '{"tableId":"<表单ID>","appId":"<应用ID>"}'` 查询真实按钮，再以 `targetForm`、`buttonType:[{id,name,buttonLocation:"before"|"after"}]` 和可选 `triggerType` 生成；不得用 `EventFormData` 冒充按钮点击。`CustomTrigger`、`InnerMQListener` 和 `WebHookTrigger` 的原生参数要求见 `references/components/trigger/CustomTrigger.md`、`references/components/trigger/InnerMQListener.md`、`references/components/trigger/WebHookTrigger.md`。
 
 `CustomTrigger` 的上下文动态赋值使用 `SelectParams` 作为最终上下文根。`paramKey` 只写业务路径，不写 `FormData.`、`ApprovalData.` 或 `SelectParams.` 前缀；主表字段格式为 `主表key.字段key`，明细字段格式为 `主表key.明细表key[].字段key`，主表与明细表必须沿用同一个主表 key。最终公式中的 `value`、`currentParamKey` 和 `allParamKey` 才补 `SelectParams.` 前缀，不能把明细字段写成 `FormData.明细表key[].字段key`。如果动态赋值来源于该触发器生成的 `customData`（`CustSetFormDto`），必须先在 `customData.tableList[]` 定位 `CustFormTableDto`，表维度取表对象 `id`，字段维度再从该表 `fields[]` 定位 `CustFormDetailDto` 并取字段对象 `id`，把这个 ID 设置到关联 FormulaBean.frontId；不得使用目标字段 ID、FormulaBean.id、表/字段名称或 paramKey 尾段。对应 ID 缺失时 frontId 使用空串，非空值必须为纯数字字符串。完整规则见 `references/components/trigger/CustomTrigger.md`。
 
-动作 `Http` 用于调用当前租户已配置的 HTTP/HTTPS 接口，参数要求见 `references/components/http/Http.md`；HTTPS 使用同一个 `Http` 组件，不能把协议地址当成新的组件类型。生成前会实时读取并校验“连接器 → 资源 → 接口 → 接口详情”，节点标题按“当前连接器: 当前接口”回填，图标按当前连接器目录回填；不存在、跨租户或归属不一致时拒绝生成，不信任旧环境的 E9 等名称、地址、图标或原生映射。HTTP 请求字段通过 `inputParams` 配置，必须用接口详情真实返回的 `table`/`paramKey`，CLI 写入参数行的 `formulaData`，支持统一的固定值、上下文、系统变量及函数/公式赋值；不能猜参数或直接改写 `request.tables`。动作 `InnerMQSend` 用于向平台内置 MQ 发送消息，参数要求见 `references/components/message/InnerMQSend.md`。`InnerMQListener` 和 `InnerMQSend` 不能放在同一个动作流中；该约束也适用于 `update` 修改后的完整设计。
+动作 `Http` 用于调用当前租户已配置的 HTTP/HTTPS 接口，参数要求见 `references/components/http/Http.md`；HTTPS 使用同一个 `Http` 组件，不能把协议地址当成新的组件类型。生成前会实时读取并校验“连接器 → 资源 → 接口 → 接口详情”，节点标题按“当前连接器: 当前接口”回填，图标按当前连接器目录回填；不存在、跨租户或归属不一致时拒绝生成，不信任旧环境的 E9 等名称、地址、图标或原生映射。HTTP 请求字段通过 `inputParams` 配置，必须用接口详情真实返回的 `table`/`paramKey`，CLI 写入参数行的 `formulaData`，支持统一的固定值、上下文、系统变量及函数/公式赋值；不能猜参数或直接改写 `request.tables`。动作 `serverless/Action` 用于执行二开代码，参数要求见 `references/components/serverless/ServerlessAction.md`；输入和输出必须传前端参数设计器生成的原生 ParamBean 结构。动作 `InnerMQSend` 用于向平台内置 MQ 发送消息，参数要求见 `references/components/message/InnerMQSend.md`。`InnerMQListener` 和 `InnerMQSend` 不能放在同一个动作流中；该约束也适用于 `update` 修改后的完整设计。
 
 动作 `DMLExecute` 用于执行自定义 SQL 或存储过程，参数要求见 `references/components/database/DMLExecute.md`。只支持新版数仓结构，`operateType` 固定为 `0`；数据源连接 ID 必须通过 `actionflow datasource-list` 从当前环境取得，SQL 占位符与 `fieldSet` 必须严格对应。含 DML 的生成结果还要检查 `sqlAnalysisOk=true`，因为平台 SQL 分析失败可能不会阻断保存。
 
@@ -152,6 +152,7 @@ e10-cli actionflow update '@update-plan.json' --out update-result.json       #
 | 人员 | `references/components/personnel/` |
 | 逻辑 | `references/components/logic/` |
 | HTTP/HTTPS 接口 | `references/components/http/` |
+| serverless/Action 二开代码 | `references/components/serverless/` |
 | 消息提醒 | `references/components/message/` |
 | 内置 MQ / 自定义事件 | `references/components/trigger/`、`references/components/message/` |
 | 会议、日程 | `references/components/calendar/` |

package/skill-docs/actionflows/references/components/logic/MultipleExecution.md

@@ -1,38 +1,38 @@
-# 循环（MultipleExecution）
-
-循环体通过 `actions` 提供，至少包含一个非 `Output` 动作，当前不支持循环嵌套。
-
-## 循环方式
-
-| `cycleMode` | 场景 | 必填参数 |
-| --- | --- | --- |
-| `1` | 按指定次数 | `cycleTimes` |
-| `2` | 满足条件时继续 | `condition` |
-| `3` | 按列表逐条遍历 | `detailData` |
-| `4` | 按列表分批遍历 | `batchDetailData`、`batchSizeData` |
-| `5` | 存在下一页时继续 | `pageCycleData`（平台已有变量 FormulaBean） |
-
-## 参数规则
-
-- `cycleTimes`：固定整数 `1-1000`，或实时上下文的 `context/reference`。动态引用必须使用 `getComponentContext` 返回的完整 `paramKey`；预检会保留来源字段的真实类型、所属组件和参数路径。
-- `detailData` / `batchDetailData`：只能引用真实 List/数组字段（表单明细、多选浏览框或上游动态列表）。不可用普通文本字段伪装为列表。
-- `batchSizeData`：固定整数 `2-1000`。
-- `condition`：使用 ESB `ConditionRule`，与动作流分支复用同一类规则树和 `saveCondition` 持久化；它不是 e-builder 表单动作的 `filterInput/ConditionSet`。左值可使用完整 `paramKey`、字段显示名、`paramName` 或真实字段 ID；编译器会按当前流程实时上下文回填真实 DTO。
-- `pageCycleData`：设计器会创建布尔变量并在循环体首节点写入“是否存在下一页”。当前只接受已存在的原始 `type: "7"` 变量 FormulaBean；尚未自动创建变量及赋值节点时，不生成该模式。
-
-## 示例
-
-```json
-{
-  "type": "MultipleExecution",
-  "params": {
-    "cycleMode": "3",
-    "detailData": {
-      "kind": "context",
-      "source": "event",
-      "paramKey": "<workflowId>.<arrayField>[]"
-    }
-  },
-  "actions": [{ "type": "SendMessage", "params": { "receiver": { "type": "all" }, "msgTitle": "逐条处理", "msgContent": "..." } }]
-}
-```
+# 循环（MultipleExecution）
+
+循环体通过 `actions` 提供，至少包含一个非 `Output` 动作，当前不支持循环嵌套。
+
+## 循环方式
+
+| `cycleMode` | 场景 | 必填参数 |
+| --- | --- | --- |
+| `1` | 按指定次数 | `cycleTimes` |
+| `2` | 满足条件时继续 | `condition` |
+| `3` | 按列表逐条遍历 | `detailData` |
+| `4` | 按列表分批遍历 | `batchDetailData`、`batchSizeData` |
+| `5` | 存在下一页时继续 | `pageCycleData`（平台已有变量 FormulaBean） |
+
+## 参数规则
+
+- `cycleTimes`：固定整数 `1-1000`，或实时上下文的 `context/reference`。动态引用必须使用 `getComponentContext` 返回的完整 `paramKey`；预检会保留来源字段的真实类型、所属组件和参数路径。
+- `detailData` / `batchDetailData`：只能引用真实 List/数组字段（表单明细、多选浏览框或上游动态列表）。不可用普通文本字段伪装为列表。
+- `batchSizeData`：固定整数 `2-1000`。
+- `condition`：使用 ESB `ConditionRule`，与动作流分支复用同一类规则树和 `saveCondition` 持久化；它不是 e-builder 表单动作的 `filterInput/ConditionSet`。左值可使用完整 `paramKey`、字段显示名、`paramName` 或真实字段 ID；编译器会按当前流程实时上下文回填真实 DTO。
+- `pageCycleData`：设计器会创建布尔变量并在循环体首节点写入“是否存在下一页”。当前只接受已存在的原始 `type: "7"` 变量 FormulaBean；尚未自动创建变量及赋值节点时，不生成该模式。
+
+## 示例
+
+```json
+{
+  "type": "MultipleExecution",
+  "params": {
+    "cycleMode": "3",
+    "detailData": {
+      "kind": "context",
+      "source": "event",
+      "paramKey": "<workflowId>.<arrayField>[]"
+    }
+  },
+  "actions": [{ "type": "SendMessage", "params": { "receiver": { "type": "all" }, "msgTitlev": "逐条处理", "msgContentv": "..." } }]
+}
+```

package/skill-docs/actionflows/references/components/logic/Output.md

@@ -10,7 +10,9 @@
 
 ## 不可猜测
 
-不要把 `Output` 写入 `actions`。`reminderMsgFormula` 与 `basisValue` 支持固定值、上下文、系统变量、变量、常量、查询结果和函数/公式；`jumpUrl` 在前端只允许固定文本。`fixedData`、`customOutputData` 属于平台原生高级输出结构，必须使用真实回读结构，不能猜测。
+不要把 `Output` 写入 `actions`。提醒内容必须使用前端富文本组件对应的 `ContestSettingDTO`，字段名是 `reminderContent`，不能再使用旧的 `reminderMsgFormula`。`basisValue` 仍支持固定值、上下文、系统变量、变量、常量、查询结果和函数/公式；`jumpUrl` 在前端只允许固定文本。`fixedData`、`customOutputData` 属于平台原生高级输出结构，必须使用真实回读结构，不能猜测。
+
+`reminderContent` 支持两种输入：一是前端原生对象 `{id, content, formulaBeans, langSet}`；二是 CLI 语义模板 `{parts:[{type:"text",value:"..."},{type:"context",paramKey:"..."},{type:"system_variable",key:"{date}"},{type:"variable",id:"..."},{type:"constant",id:"..."}]}`。编译器会生成 Base64 内容和 `#{paramN}` 占位符，并将每个动态片段保存为 `formulaBeans[].value`。
 
 如果自定义触发动作流需要配置终止参数，在 `finalOutput.params.customParamSetting` 中使用同一套 `CustSetFormDto` 结构，`formType` 改为 `output`，新建时 `customId` 传空字符串，`deleteTableIds` 传空数组，`appId` 由编译器注入当前动作流应用 ID，关联 ID 由后端保存方法生成。终止参数字段的映射关系必须写在 `tableList[].fields[].formulaValue`，对应后端 `CustFormDetailDto.formulaValue`；不能放在字段的 `value`、`mapping` 或其他自定义属性中。
 
@@ -22,7 +24,12 @@
     "params": {
       "outputStatus": "0",
       "reminder": "1",
-      "reminderMsgFormula": { "kind": "variable", "id": "<真实变量ID>", "name": "失败提示" },
+      "reminderContent": {
+        "parts": [
+          { "type": "text", "value": "失败：" },
+          { "type": "variable", "id": "<真实变量ID>", "name": "失败提示" }
+        ]
+      },
       "pageAction": "0"
     }
   }

package/skill-docs/actionflows/references/components/message/SendMessage.md

@@ -10,7 +10,7 @@
 
 ## 不可猜测
 
-标题和内容按需求选固定文本或 `parts` 模板；纯字符串保持固定值，只有 `parts` 模板才进入设计器的消息专用编辑器。模板会编译成“正文文本 + `#{paramN}` 占位符 + 每个占位符的独立绑定”，对应手动配置时右侧的形式。**本 Skill 生成消息标题/内容时统一使用 `parts` 模板**，不要把通用函数/公式对象直接作为消息正文输入；这只是本 Skill 的生成约定，不代表平台其他场景不能使用函数。`parts` 的动态项支持 `context`、`system_variable`、`variable`、`constant`，后两者必须按 `references/dynamic_resources.md` 使用真实资源或计划定义。需要拼接上下文时，必须拆成 `parts`，例如：
+提醒标题、提醒内容、推送图片 URL、PC 端链接和移动端链接统一使用前端 `AssignTextarea` 对应的 `ContestSettingDTO`。语义参数名分别为 `msgTitlev`、`msgContentv`、`picLink`、`msgPcLink`、`msgMobileLink`；可以传普通字符串、原生 `{id,content,formulaBeans,langSet}`，或 `parts` 模板。模板会编译成 Base64 内容、`#{paramN}` 占位符和独立 `formulaBeans`，对应手动配置时右侧的形式。**不再使用旧的 `msgTitle`、`msgContent`、`pcLink`、`mobileLink` 字段**。`parts` 的动态项支持 `context`、`system_variable`、`variable`、`constant`、`function`、`formula`、`query_result`，后两者必须按 `references/dynamic_resources.md` 使用真实资源或计划定义。需要拼接上下文时，必须拆成 `parts`，例如：
 
 ```json
 {
@@ -23,8 +23,8 @@
 }
 ```
 
-需要动态接收人时传 `receiver: {"type":"context","paramKey":"<真实人员字段paramKey>","label":"<字段名>"}`，不能把人员字段当固定人员 ID，也不能省略 `paramKey`。模板上下文只传 `paramKey` 和 `label`，由 CLI 按消息编辑器的动态片段结构编译，并绑定当前触发节点。对定时批量、按日期字段、表单数据等 e-builder 记录触发器，未显式提供链接时 CLI 自动生成 PC/移动端详情链接：`formId` 为触发表单 ID 固定值，`dataId` 为上游“数据ID”动态上下文。显式 `pcLink` / `mobileLink` 会覆盖该默认行为。
+需要动态接收人时传 `receiver: {"type":"context","paramKey":"<真实人员字段paramKey>","label":"<字段名>"}`，不能把人员字段当固定人员 ID，也不能省略 `paramKey`。模板上下文只传 `paramKey` 和 `label`，由 CLI 按消息编辑器的动态片段结构编译，并绑定当前触发节点。对定时批量、按日期字段、表单数据等 e-builder 记录触发器，未显式提供链接时 CLI 自动生成 `msgPcLink` / `msgMobileLink` 的 PC/移动端详情链接：`formId` 为触发表单 ID 固定值，`dataId` 为上游“数据ID”动态上下文。显式 `msgPcLink` / `msgMobileLink` 会覆盖该默认行为。
 
 ## 最小计划
 
-`receiver`、`msgTitle`、`msgContent`。
+`receiver`、`msgTitlev`、`msgContentv`。

package/skill-docs/actionflows/references/components/serverless/ServerlessAction.md

@@ -0,0 +1,42 @@
+# serverless/Action（`ServerlessAction`）
+
+## 何时使用
+
+用于执行平台的二开代码。`crossService=1` 时调用远程 serverless/Action 服务；`crossService=0` 时执行本地上传的 Java 类。
+
+## 参数
+
+```json
+{
+  "actions": [
+    {
+      "type": "ServerlessAction",
+      "params": {
+        "codeType": "customAction",
+        "crossService": 1,
+        "groupId": "ces",
+        "serverVersion": "1.1",
+        "request": {
+          "primaryKey": "",
+          "name": "",
+          "tableId": "<ParamMappingBean.tableId>",
+          "mappingTableId": "<ParamMappingBean.mappingTableId>",
+          "tableData": []
+        },
+        "response": {
+          "primaryKey": "",
+          "name": "",
+          "tableId": "<ParamSettingBean.tableId>",
+          "tableData": []
+        }
+      }
+    }
+  ]
+}
+```
+
+- `codeType` 当前仅支持 `customAction`。
+- `crossService=1` 时必须提供 `groupId`，`serverVersion` 按 provider/consumer 约定填写，可为空；`crossService=0` 时必须提供本地代码完整类路径 `address`。
+- `request` 必须使用前端输入参数配置生成的原生 `ParamMappingBean`；`response` 必须使用前端输出参数配置生成的原生 `ParamSettingBean`。
+- 参数行的 `id`、`parentId`、`paramKey`、`paramType`、`dataType` 和前端高级配置会被保留；缺失的参数表/字段 ID 由 CLI 补齐，不能用语义字符串替代原生结构。
+- 二开动作执行后，可以引用 `Response.entry.<字段>` 上下文；请求参数上下文使用 `Request.entry.<字段>`。

package/skill-docs/actionflows/references/components/trigger/WebHookTrigger.md

@@ -0,0 +1,89 @@
+# WebHook 请求触发（`WebHookTrigger`）
+
+`WebHookTrigger` 对应前端 `custom-webhook` 和 Java `WebHookTriggerComponent`。它接收外部 HTTP 请求，按配置的请求参数触发动作流。
+
+## 语义计划
+
+```json
+{
+  "event": {
+    "type": "WebHookTrigger",
+    "params": {
+      "requestUrl": "https://api.example.com/api/open-esb/server/webhook/trigger/order-created",
+      "request": {
+        "id": "webhook-request-1",
+        "mappingId": "webhook-mapping-1",
+        "tables": [
+          {
+            "name": "Params",
+            "primaryKey": "Params",
+            "tableId": "params-1",
+            "tableData": [
+              {
+                "id": "request-id",
+                "paramKey": "orderId",
+                "paramName": "orderId",
+                "showName": "订单 ID",
+                "paramType": "string",
+                "dataType": "attribute",
+                "required": true
+              }
+            ]
+          },
+          {
+            "name": "Header",
+            "primaryKey": "Header",
+            "tableId": "header-1",
+            "tableData": []
+          },
+          {
+            "name": "Body",
+            "primaryKey": "Body",
+            "tableId": "body-1",
+            "tableData": []
+          }
+        ]
+      },
+      "authAppIds": []
+    }
+  }
+}
+```
+
+`request` 应按设计器节点数据传入 `id`、可选 `mappingId` 和 `tables`。`tables` 的 `name` 只能是 `Params`、`Header`、`Body`；`primaryKey`、`tableId`、`customData` 等已有平台字段会原样保留，至少一个分组的 `tableData` 需要有字段，字段对象应来自前端参数设置组件。
+
+生成时推荐直接传设计器返回的完整 `requestUrl`。如果只有 `requestCode`，编译器也会生成 `/api/open-esb/server/webhook/trigger/<requestCode>` 形式的公开地址；Java 组件保存时使用最后一段作为 code。
+
+## 触发上下文
+
+Webhook 请求运行时由平台解析为三个上下文分组：`Params`、`Header`、`Body`。动作参数中的上下文引用使用完整路径，例如 `Params.orderId`、`Header.Authorization`、`Body.customer.name`；不要把它们写成 `FormData.*`。
+
+生成前 CLI 会使用当前会话调用 `openApplicationBrowser` 完成接口，并把返回的应用归一化为 `{ "id": <应用ID>, "content": "<应用名称>" }` 写入 `authAppIds`。默认使用接口返回的全部应用；如需限定范围，可在语义计划中传 `authAppNames: ["普通应用-wull"]`。认证应用为空时 Java 组件仍可保存，但请求可能无法通过开放平台认证。
+
+## 终止节点响应
+
+Webhook 触发的终止节点使用 `finalOutput.params.webhookCustomParamSetting`，对应前端 `ParamGroupMappingBean`。必须包含 `Header`、`Body`、`StatusCode` 三个分组，并至少配置一个 Header 或 Body 字段；平台原生的 `id`、`mappingId`、`primaryKey`、`mappingTableId`、`customData` 和 `tableData` 直接保留。
+
+```json
+{
+  "finalOutput": {
+    "params": {
+      "webhookCustomParamSetting": {
+        "id": "response-setting-1",
+        "mappingId": "response-mapping-1",
+        "tables": [
+          { "name": "Header", "tableData": [] },
+          { "name": "StatusCode", "tableData": [] },
+          {
+            "name": "Body",
+            "customData": "{\"dataType\":\"application/json\"}",
+            "tableData": [
+              { "id": "response-a", "paramKey": "ab", "paramName": "ab", "paramType": "string", "required": true }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```

package/skill-docs/actionflows/references/dynamic_capability_matrix.md

@@ -12,14 +12,14 @@
 | HTTP 请求参数 | `Http.inputParams.formulaData` | 固定值、上下文、系统变量、变量、常量、函数/公式 | 写入接口详情对应参数行的 FormulaBean，不改写接口参数定义 |
 | MQ 发送参数 | `InnerMQSend.queueName`、`inputParams` | 固定值、上下文、系统变量、变量、常量、查询结果、函数/公式 | 保留原生 `sendParams` 参数定义，只向命中的参数行写入 `formulaData` |
 | DML SQL 参数 | `DMLExecute.fieldSet.assign` | 固定值、上下文、系统变量、变量、常量、查询结果、函数/公式 | 按 SQL 占位符生成 FormulaBean 数组，同时保留原生 FormulaBean 兼容入口 |
-| 消息模板 | `SendMessage.title/content.parts` | 上下文、系统变量、变量、常量 | 消息正文占位符与独立绑定；接收人上下文也保留为动态人员 FormulaBean |
+| 消息模板 | `SendMessage.msgTitlev/msgContentv/picLink/msgPcLink/msgMobileLink` | 上下文、系统变量、变量、常量、函数/公式、查询结果 | 五个消息文本/链接字段统一保存为 `ContestSettingDTO`；正文占位符与独立绑定；接收人上下文仍保留为动态人员 FormulaBean |
 | 消息接收人 | `SendMessage.receiver` | 当前用户、上游人员上下文、固定人员 | 动态人员使用真实上下文 `paramKey`，固定人员使用当前租户 Browser 对象 |
 | 人员参数 | 表单数据动作、流程动作、文档动作、`HrmEmployeeUpdate`、`PersonnelOnboarding`、`AlterPersonStatus`、会议/日程中的人员属性 | 当前用户、上游人员上下文、动作流变量/常量/函数 | 不再强制走固定人员查询；动态引用保持人员 FormulaBean，固定人员仍要求真实 Browser 对象 |
 | 会议和日程运行时字段 | `MeetingCreate` 的标题/密级/人员，`ScheduleCreate` 的标题/时间/内容/其他地点/人员 | 上下文、系统变量、变量、常量、函数/公式 | 普通字段生成对应 FormulaBean；人员使用人员 FormulaBean；会议室、日程类型、关联流程等设计期资源仍保持 Browser 对象 |
 | 流程和文档运行时字段 | 流程实例 ID、标题、意见、公文正文 ID、关联数据 ID、时间、文档/附件 ID、布尔开关等 `formula_or_reference` 属性 | 固定值、上下文、系统变量、变量、常量、查询结果、函数/公式 | 统一经共享公式编译器生成 FormulaBean；固定流程定义、节点、目录 DTO 不在此列 |
 | 循环参数 | `MultipleExecution.cycleTimes`、列表/明细来源 | 上下文、变量、常量、当前循环上下文 | 按循环模式生成对应 `CycleParams`/FormulaBean |
 | 条件右值 | `Condition` | 固定值、上下文、系统变量、变量、常量、函数 | 右值保留为公式树，不把动态字段名转成固定字符串 |
-| 终止节点动态输出 | `finalOutput.params.reminderMsgFormula`、`basisValue` | 固定值、上下文、系统变量、变量、常量、查询结果、函数/公式 | 自动补充的 `Output` 节点保留高级设置，无需在 `actions` 中手写终止节点 |
+| 终止节点动态输出 | `finalOutput.params.reminderContent`、`basisValue` | 富文本 `ContestSettingDTO`；提醒内容支持文本、上下文、系统变量、变量、常量、查询结果、函数/公式 | 自动补充的 `Output` 节点保留高级设置，无需在 `actions` 中手写终止节点；旧 `reminderMsgFormula` 不再用于新生成 |
 
 ## 需要按组件协议单独判定
 

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

@@ -42,7 +42,7 @@
 | `e10-cli app read <appId>` | 查看应用**详情**（全量配置：名称/描述/简称/范围/目录/组织/发布状态）。`--json` 输出完整对象。走 `/app/info` |
 | `e10-cli app edit <appId> [--name] [--desc] [--short-name]` | 编辑应用信息（至少指定一个写参数；内部先读 `/app/info` 再合并提交） |
 | `e10-cli app delete <appId>` | 删除应用（软删除，可恢复；存在关联资源会提示先清理） |
-| `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段+Select/RadioBox/CheckBox 选项；`--out fields.json` 写 UTF-8 JSON（推荐，机器可读）。旧版 `[dir]` 参数写 memo.md，已过时 |
+| `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段+Select/RadioBox/CheckBox 选项、**并标注每个字段属于哪张物理表**（`· 物理表: 表1`，JSON 里是 `formTable` 键；多物理表见 `form physical-table list`）；`--out fields.json` 写 UTF-8 JSON（推荐，机器可读）。旧版 `[dir]` 参数写 memo.md，已过时 |
 | `e10-cli form read <objId> --app-id <appId> --out fields.json` | 读取字段含选项（Select/RadioBox/CheckBox 自动带 options）。**含明细表字段**，配动作流/联动拿明细 fieldId 用这个 |
 | `e10-cli form list <appId>` | 列出应用下的所有表单 |
 | `e10-cli form create <appId> <name> <dir> --fields @<json文件>` | 创建表单。`--fields` **必填**。支持 DetailTable(嵌套formFields)、EBuilder(sformId+dataTitle)、relateFrom(联动)。fields.json 字段可带 `"required":true`/`"readOnly":true` 直标（写进布局 comps）。**字段名与平台系统字段重名（标题/创建者/创建时间/数据ID/最后更新人/数据状态）→ 不新建物理字段、复用系统字段**，并把该字段在**布局置为可见**（platform 系统字段默认隐藏；可写 `"singleRow":true` 独占一行、`"hidden":true` 保持隐藏）。`--json` 返回 `skippedSys`。**默认不加菜单**，要入口传 `--menu`（台账菜单 VIEWPORT）；漏加 `e10-cli menu add-table <appId> <objId>` 补。**`--table-name <名>` 自定义数据库表名**（平台前缀如 `uf_` 由 CLI 自动补，传 `cs_khxx` 与 `uf_cs_khxx` 等价；字母开头、只含字母数字下划线；自定义部分受平台长度上限约束——`uf_` + 总长 30 时最多 27 位，越界直接报错不建半张表；建成后回读校验实际表名；仅物理表应用适用） |
@@ -80,6 +80,11 @@
 | `e10-cli form validate list <objId> <appId>` | 查看表单**查重规则**（字段重复校验，多字段 AND）。`add <objId> <appId> <字段名...> [--help 提示] [--remind]` 新增（缺省禁止提交 NOSUBMISSION，`--remind` 仅提醒）。**`--help` 会建成多语言标签、存的是标签 id**（平台只收 id，传文本会被拒「提示内容格式不正确」；`list` 会解回文本显示，缓存原因刚建完约 10 秒内可能仍显示 id）；`delete <objId> <appId> <ruleId>` 删除。项目名称重名/工时日期重复不允许 |
 | `e10-cli form add-detail-table <objId> <appId> <明细表名> [首字段名] [--init]` | 给**已存在的主表**加明细子表（saveSubForm 建子表 + 加首字段使其可见）。`--data-key <物理表名>`、`--first-field-type <类型>`（默认 Text）。⚠ **空子表平台会过滤掉、布局里看不见**，首字段名强烈建议传；`--init` 建完把 DetailTable 组件放进布局。后续往明细里加字段用 `form add-field --sub-form-id <subFormId>`：建表时一次性带明细用 `form create` 的 fields.json `DetailTable`+`formFields` |
 | `e10-cli form delete-detail-table <objId> <appId> <subFormId\|明细表名>` | **删除明细表**（连带表里的字段）。平台不允许删**仍被布局引用**的明细表（报「当前【X】明细表已被布局引用，不允许删除」）—— 明细表只要在表单上就必然被引用，所以多数情况要加 `--force`：先把这张表的组件（本体 + 每列的「字段本体 + 标题标签」）从布局摘掉、清掉 workbook 里的残留，再删。删除是**软删**，记录仍在但不再算数 |
+| `e10-cli form physical-table list <objId> <appId>` | 列出表单的**全部物理表**（含主表），带 `formTableId` / 显示名 / 库表名 / 表类型(`MAIN`\|`SUBSIDIARY`) / 字段数。走 `getFormAGroupList`（设计器「字段管理」那排 chip 的数据源）。**只列物理表**，明细表要用 `form detail-table list` |
+| `e10-cli form add-physical-table <objId> <appId> --name <名> --table-name <uf_xxx>` | 给**已存在的表单**加一张**附属物理表**（设计器「字段管理 → **其他**」页签，用于一个表单的字段分散到多张物理表、字段数过多时的容量兜底）。走 `saveFormTable`，`tableType=SUBSIDIARY`；输出 **`formTableId`**（后续加字段/改名/删除都要用它，忘了用 `form physical-table list` 找）。`--table-name` **必填**（平台的建议命名规则未抓到报文，不猜）。⚠ 与明细表是两根轴，别混 —— 见 `references/form/guide-form-physical-table.md` |
+| `e10-cli form add-physical-field <objId> <appId> <formTableId> <字段名> <类型> [标题]` | 往**已有的附属物理表**里加字段。机制是 `saveFormFieldNew` + jsonObj 里的 `formTableId`（**不是**批量端点）。选项与 `form add-field` 同名同义，**两者共用同一份字段构造器**。⚠ **不碰布局** —— 字段不会自动进表单布局。每次写完**回读确认**（平台对形状不认的字段会回 200 却静默不落库） |
+| `e10-cli form rename-physical-table <objId> <appId> <formTableId> --name <新名> --table-name <原表名>` | 改物理表**显示名**（同一个 `saveFormTable` 端点，带 `formTable.id` 即改名）。`--table-name` 要**原样回传** |
+| `e10-cli form delete-physical-table <objId> <appId> <formTableId...>` | 删除物理表（`deleteFormTable`，可一次删多张）。⚠ **表里的字段一并删除，不可逆**。表 id 用 `form physical-table list` 查 |
 | `e10-cli form list-search <objId> <appId> <listId> [--add <fieldId...>] [--quick <fieldId...>] [--remove <fieldId>] [--pc-only]` | 查看/配置台账**搜索条件**。`--add` 进搜索面板、`--quick` 加顶部快捷筛选（均支持多字段）、`--remove` 移除。主表字段直取 ds/fields；明细子字段自动 fallback `getFormField` 单取元数据。**自动保留移动端配置** |
 | `e10-cli form list-sort <objId> <appId> <listId> [--field <fieldId...>] [--order ASC\|DESC] [--clear] [--pc-only]` | 查看/配置台账**排序**。`--field` 支持多个（按传入顺序多级排序，`--order` 对所有字段生效）、`--clear` 清除。**自动保留移动端配置** |
 | `e10-cli form list-stats <objId> <appId> <listId> [--add <json或@文件>] [--remove <statId>] [--pc-only]` | 主表/明细顶部统计，sum/count/avg/max/min、条件及格式；明细 count 支持 `{ "type":"count", "subFormId":"..." }`。保存后回读、保护移动端；平台可能共享两端统计，输出 mobileStatistics。详见 `references/form/guide-list-stats.md` |
@@ -100,7 +105,9 @@
 | `e10-cli form layout init <objId> [--style-template <名\|id>] [--view-id <id>] [--read-only] [--required] [--disable-edit] [--single-row]` | 初始化/重建表单布局（initLayout）：**换样式模板** + 覆盖字段 readOnly/required/disableEdit/singleRow（不传这些开关则**保留字段已有设置**）。**⚠ 样式模板流式与表格式是两套**，同名不同 id，按表单实际布局类型实时查（传错套会直接报错并列出可用项；**平台对跨套 id 不报错、只会静默忽略，表现为"命令成功但样式没变"**）。缺省：流式=标准版、表格式=表格版。完整模板表见 `form/style-templates.md`。**建表时不能指定样式，只能建完再用本命令换** |
 | `e10-cli form group <objId> <appId> --groups '{"基本信息":["字段名/fieldId",...]}'` | 给**已建好的 eb 表**加字段分组（折叠容器）。建组 saveFieldGroup → 分配 updateFormFieldGroup → initLayout generateCollapse 渲染。`--groups` 可 `@文件`；`--required` 同时设分组内字段必填；同名分组复用不重复建（去重）。建表时一次性带分组用 `form create` 的 fields.json `group` 属性 |
 | `e10-cli form data add <objId> <appId> <json>` | 写入表单数据（`@` 开头为 JSON 文件路径）。JSON key 可用 fieldId 或字段名；Select/RadioBox 值填选项名（自动解析 valueKey）或 valueKey、CheckBox/SelectMultiple 用数组、TextArea 直接值、Employee/Department 用 ID。详见 `form/guide-form-data.md` |
-| `e10-cli form data list <objId> [--page <n>] [--size <n>]` | 查询表单数据。`--page` 页码（缺省1）、`--size` 每页条数（缺省1000；不传 pageInfo 平台默认卡 10） |
+| `e10-cli form data list <objId> [--page <n>] [--size <n>]` | 查询表单数据（**只含主表**）。`--page` 页码（缺省1）、`--size` 每页条数（缺省1000；不传 pageInfo 平台默认卡 10） |
+| `e10-cli form data detail <objId> <appId> <dataId> [--no-detail]` | 读一条数据详情，**默认连明细一起读**（`--no-detail` 只要主表）。要明细用这条，`list` 不返回明细。详见 `form/guide-form-data.md` |
+| `e10-cli form data update <objId> <appId> <dataId> <json> [--detail-mode cover\|append]` | 按数据 ID 修改（`@` 开头为文件路径）。只需写要改的字段；带明细表名即处理明细，缺省 `cover` **整表覆盖**，`append` 只追加 |
 | `e10-cli form data delete <objId> <dataId>` | 删除一条表单数据 |
 
 ### 表单按钮
@@ -164,7 +171,8 @@
 | `e10-cli org department edit <id> [--name] [--code] [--parent] [--disporder]` | 编辑部门：改名 / 改编号 / **移动父级** / 改排序。是「**读现状 → 改 → 写回**」：`organization/getForm?id=` 读回这个部门的**完整当前状态**（含 tenantKey / creator / datarank / createTime 等，全部原样回传，别自己造），改完再 `organization/saveForm`。⚠ 编辑报文与新建**形状不同**（认 `id`，没有 `targetId`/`formdata`/`recordId`，`advanceForm:false`），不能共用构造函数。命令会自动**回读确认**改名生效，静默失败会报错 |
 | `e10-cli org department delete <id> [--parent <父部门id>] [--subcompany <机构id>]` | 删除部门。`--parent` 是该部门的**父**（顶层部门的父就是机构 id），不传按当前机构的上下文解析。⚠ 删除是**软删**（`isDelete: true`），删完用 `getForm?id=` 仍能读出来 —— 判存在与否要看 `isDelete` 字段，别看接口有没有返回 |
 | `e10-cli org employee template [--out <路径>]` | 导出人员导入模板（xlsx）。**模板是随包发的资源**（含富文本表头和「注意事项」工作表），直接复制，不用代码重建 |
-| `e10-cli org employee import <file> [--dry-run] [--mode add\|update] [--find-by <字段>] [--review <n>]` | 从 Excel 批量导入人员。**先 `--dry-run` 预览再真导** —— 干跑到「预览」为止不落库，能看出平台解析出的列/行跟你原表对不对。⚠ 模板自带示例行，导入前删掉。细节见 `references/hrm/guide-org-employee.md` |
+| `e10-cli org employee import <file> [--dry-run] [--mode add\|update] [--find-by <字段>] [--review <n>] [--no-wait] [--wait-timeout <ms>] [--error-file <路径>] [--no-error-file]` | 从 Excel 批量导入人员。**先 `--dry-run` 预览再真导** —— 干跑到「预览」为止不落库，能看出平台解析出的列/行跟你原表对不对。⚠ 模板自带示例行，导入前删掉。导完**默认等结果**，打出 `已导入 N / 失败 M`，**有失败行时退出码非 0**；失败原因（在出错单元格的批注里）会直接打出来，失败数据默认可存成 `<源文件>.错误数据.xlsx`。⚠ **分部名写错不报错**：平台会静默新建一个同名分部再把人放进去。细节见 `references/hrm/guide-org-employee.md` |
+| `e10-cli org employee task <taskId> [--error-file <路径>]` | 查人员导入任务的结果（`getByTaskId`）。导入时用了 `--no-wait`、或等超时了，用这个补看：条数 / 失败原因 / 失败数据。⚠ **`status: 0` 不是成功**，判完成看 `callbackData` |
 
 ## 流程
 

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

@@ -48,7 +48,7 @@ e10-cli form association create <objId> <appId> "全部合同" --view <viewId> -
 
 每项含义为“目标视图字段 ← 当前来源记录字段”。支持字段 ID 或唯一显示名称，自动补全 `compType/fieldName/dataIndex` 等元数据。仅支持主表字段到主表字段的映射；明细字段及固定值筛选不在本次支持范围。
 
-上例复现样本中的配置，不代表所有关联字段都应传名称。目标 EBuilder 字段可能需要记录 ID：应按业务语义选择 `sourceField: "数据ID"` 或指定字段，并用实际记录确认筛选结果。命令不会擅自把用户提供的名称字段改成 ID。
+上例样本中的配置，不代表所有关联字段都应传名称。目标 EBuilder 字段可能需要记录 ID：应按业务语义选择 `sourceField: "数据ID"` 或指定字段，并用实际记录确认筛选结果。命令不会擅自把用户提供的名称字段改成 ID。
 
 默认启用，默认适用于 PC 和 MOBILE，默认仅显示布局。省略 `--mappings` 表示不添加关联参数；目标视图自身的筛选仍独立生效。创建检测同名页签，重复时停止，改用 `update`。
 

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

@@ -41,6 +41,36 @@ data.json 格式（`@` 开头为文件路径）。key 可用 **fieldId（长 ID
 
 > **除非用户明确要求，否则不要往表单写入任何数据。** 表单创建完成后只需确认字段正确即可，不要自动插入测试数据。
 
+## 读明细：`detail`
+
+`list` 只返回主表。要**连明细一起读**用 `detail`：
+
+```bash
+e10-cli form data detail <objId> <appId> <dataId> [--no-detail]
+```
+
+输出主表字段（按显示名）与各明细表的行。`--no-detail` 表示只要主表。
+
+## 改数据：`update`
+
+```bash
+e10-cli form data update <objId> <appId> <dataId> @patch.json [--detail-mode cover|append]
+```
+
+`@patch.json` 的写法和 `add` 一样（key 用字段名），**只需写要改的字段**。带明细表名即处理明细：
+
+```json
+{ "金额": 1200, "物料明细": [ { "物料名称": "螺丝", "数量": 100 } ] }
+```
+
+- `--detail-mode cover`（缺省）：**整表覆盖**该明细的行 —— 写几行就是几行，原来的行被替换
+- `--detail-mode append`：只追加，原有明细行保留
+
+不传明细表名时，明细原样不动。
+
+> `add` 走设计器那条保存链（`form/core/saveFormData`，**一次一条、只写主表**）；
+> `update` 与 `detail` 走表单数据 OpenAPI。
+
 ## 删数据
 
 ```bash

package/skill-docs/references/form/guide-form-layout-incremental.md

@@ -14,6 +14,12 @@
 
 明细字段也在同一个平铺数组里，靠 `config.subFormId` 归属；它的 `excel.parent` 指向明细表容器的 `nodeId`，普通字段的 `excel.parent` 是 `ROOT`。
 
+**EXCEL 布局还有第三份：网格。** `pageLayouts[].config.workbook.Sheet1.cells` 里每个组件占**一格**，靠 `style.cellType.comId` 认到自己的组件，位置也以格子自己的 `row` / `col` 为准 —— **设计器按网格渲染**。所以 EXCEL 表里「组件的 `config.excel.row` / `col`」和「格子的 `row` / `col`」是同一件事的两份副本，**改一份必须改两份**：只改组件层的话接口会回成功，但设计器里画不出来。
+
+FLOW 布局**没有** `config.workbook`（它靠 `config.flow.parent` / `nodes` 排布），这条对它不适用。
+
+> 这份同步由 CLI 负责，不用手工做。但**手工在页面上改过布局的老表**如果在 EXCEL 上有字段显示不出来，在设计器里保存一次即可 —— 设计器会按组件重算网格。
+
 ## 字段属性分两类
 
 有些属性**只存在于布局组件里，字段定义没有这个键** —— 只写字段定义等于什么都没做：接口回成功、命令也报成功，表单上一点变化都没有。
@@ -37,11 +43,20 @@
 
 **不是自己建的表不要用 `--reinit`。** 字段越多越经不起 —— 真实的一张订单主表有 131 个组件。
 
-### 什么时候加字段会中止
+### 表里还没有这个类型时：用平台给的字段模板
+
+新组件的键集（`format`、`earlyDate`、`pointSize`、`switchType` …）各类型都不一样，**按类型名拼一个出来只会猜错，而猜错不报错、只是渲染异常**。所以增量插入一向是**照同类型的现成组件整套抄**。
+
+表里没有同类型字段时，模板改从平台取：命令会调 `getFormFieldExist`，拿**平台按这个字段生成的组件模板**（`configPC`）—— 顶层样式键（按类型）与类型专有键平台都给全了，结构尾键从同作用域的现成组件借，位置和身份键由命令自己写。**全程不重建布局。**
+
+两点要知道：
+
+- 明细表字段拿不到这个接口的模板（它只返回主表与系统字段），但模板是**按类型而不是按作用域**的，此时借主表同类型的那一份。
+- 拿模板只在**真的缺**时才多打一次接口；表里已有同类型字段时，路径与从前一字不差。
 
-布局里**没有同类型的字段可参照**时，命令会中止并说明。
+### 明细表的字段是横着排的
 
-这是设计如此，不是缺陷：新组件的键集（`format`、`earlyDate`、`pointSize`、`showDimension` …）各类型都不一样，只能从同类型的现成组件整套抄过来；按类型名拼一个出来，**猜错不报错、只是渲染异常**。
+同一个「加字段」，**主表和明细表落的轴不一样**：主表是一行一个字段（新字段**往下加行**），明细表是一个字段占一列（新字段**往右加列**）。明细表还有自己的一张网格（`workbook` 的键就是 `DetailTable` 组件的 id），明细字段的格子在那张里，不在 `Sheet1`。
 
 遇到中止时，两个选择：
 

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

@@ -48,7 +48,7 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 | fieldType | 字段类型，如 `Text` / `Employee` / `Date` |
 | **`isDetail`** | **目标落在明细表里时必须为 `true`**。不传 = 主表字段 |
 
-**目标字段在明细表里，就加 `"isDetail": true`** —— 这是「主表字段控制明细列显隐」的写法，两个方向都支持（实测 `hide` / `required` 均可）：
+**目标字段在明细表里，就加 `"isDetail": true`** —— 这是「主表字段控制明细列显隐」的写法，两个方向都支持（`hide` / `required` 均可）：
 
 ```json
 {
@@ -105,7 +105,7 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 | `"effect": "formLayout"` | 只对**某个表单布局**生效（布局 id 现查） |
 | `"effect": { ... }` | 直接给 `{effectType, effectName, effectValue}`，自行指定 |
 
-⚠ **布局维度的值要的是 `multipleLayoutId`，不是 `formLayout.id`** —— 同一张表上这两个值**相邻但不同**（实测某表是 `…375` 与 `…376`）。给错了命令**不报错**，只是指向另一个布局，而且平台按这个 id 解析不出名字，回读时生效范围是个空白（`表单布局: `）。命令取的是前者，不用手填。
+⚠ **布局维度的值要的是 `multipleLayoutId`，不是 `formLayout.id`** —— 同一张表上这两个值**相邻但不同**（例如 `…375` 与 `…376`）。给错了命令**不报错**，只是指向另一个布局，而且平台按这个 id 解析不出名字，回读时生效范围是个空白（`表单布局: `）。命令取的是前者，不用手填。
 
 ### 工作流表单那条路由的维度不一样