weaver-e10-builder 1.1.9 → 1.2.3

package/skill-docs/references/ebuilder-designer/guide-designer.md

@@ -2,7 +2,7 @@
 
 > 本文件为 `SKILL.md` 的子模块，在用户于 Ebuilder 设计器中读/改/存页面布局时加载。覆盖：页面元信息（info）、布局树（layout）、保存（save）、锁定/解锁（lock）、主题（theme）、栅格位置（position）、加组件（comp-add，factory 模板自带打包）。
 >
-> **契约来源**：本指南全部字段、参数、取值枚举来自 ebuilder-designer 的 7 个 HTTP 接口规约（layout/page-info、layout/list、layout/save、layout/lock、layout/refTheme、page/version/list、page/version/revert）。凡接口未给出、须运行时 inspect 真实页面才能确定的具体取值（组件 config 子字段集、取值枚举、header 抓包集等），一律标 **「需 inspect 真实页面查原始值」**，不凭空构造——盲造组件 config 会触发 ERR-007/008 崩页。
+> **契约来源**：本指南全部字段、参数、取值枚举来自 ebuilder-designer 的 7 个 HTTP 接口规约（layout/page-info、layout/list、layout/save、layout/lock、layout/refTheme、page/version/list、page/version/revert）。凡接口未给出、须运行时 inspect 真实页面才能确定的具体取值（组件 config 子字段集、取值枚举、header 样本集等），一律标 **「需 inspect 真实页面查原始值」**，不凭空构造——盲造组件 config 会触发 ERR-007/008 崩页。
 >
 > 本 skill 自包含分发，不依赖任何本机文件；"inspect 真实页面"指用户对自己的页面运行 `designer layout <pageId> --json` 查看实际数据，是运行时操作。
 
@@ -188,7 +188,7 @@
 >
 > **坑**：Body 直接传压缩后的数字串（`Content-Type: application/json`），**不要**再用 `JSON.stringify()` 包裹；保存前若 `isLock=1` 须先 unlock。
 >
-> **⚠️ 需 inspect 真实页面/抓包**：接口文档 §4.4 仅明示 `ebbusinessid` 请求头（=pageId）+ Cookie（`ETEAMSID`/`LOGIN_TYPE`/`langType`）。真实浏览器调用还带 `referer`、`timezoneoffset` 等头——**完整 header 集需抓包确认，本骨架只列文档明示项**。CLI 已封装常用头，手调原始接口时按需补。
+> **⚠️ 需 inspect 真实页面**：接口文档 §4.4 仅明示 `ebbusinessid` 请求头（=pageId）+ Cookie（`ETEAMSID`/`LOGIN_TYPE`/`langType`）。真实浏览器调用还带 `referer`、`timezoneoffset` 等头——**完整 header 集需样本确认，本骨架只列文档明示项**。CLI 已封装常用头，手调原始接口时按需补。
 
 ### 返回与内部流程
 
@@ -211,7 +211,7 @@
 
 ## designer theme — 设置主题
 
-**接口契约**：POST `/api/bs/ebuilder/designer/layout/refTheme`，**Query 参数** `themeId`（Long 必填）、`pageId`（Long 必填）、`terminalType`（`PC`/`MOBILE`，默认 `PC`；契约只列 themeId+pageId，CLI 抓包发现带 terminalType），请求头 `ETEAMSID`，需 EDIT 权限。
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/refTheme`，**Query 参数** `themeId`（Long 必填）、`pageId`（Long 必填）、`terminalType`（`PC`/`MOBILE`，默认 `PC`；契约只列 themeId+pageId，CLI 样本发现带 terminalType），请求头 `ETEAMSID`，需 EDIT 权限。
 
 **返回**：`{ themeCss, styleConfig, themeId, themeVersion, refTheme, defTheme, refStyles[] }`。
 
@@ -284,4 +284,4 @@ e10-cli designer unlock <pageId>
 
 > **关键**：save 入参直接取自 `/list` 导出值，只改 `comps`；元数据不动。组件具体 config 取值需 inspect 真实页面，不凭空造。
 
-> **⚠️ 收尾必做显式 save + unlock（否则"布局未保存"）**：`comp-add`/`position`/各组件 setter（chart dataset-set/measure-add 等）虽各自**封装 `/layout/save` 自动存盘**，但全部改完后**必须再跑一次显式 `designer save <pageId> --layouts @<fresh-layout.json>` + `designer unlock <pageId>`**（fresh layout 用 `designer layout <pageId> --terminal all --json` 现导）。否则页面留 `isLock=true`（浏览器开了设计器会自动上锁）或 draft 标志未清，**设计器/预览打开会弹"布局未保存"提示**（实测：未 unlock 的页 `isLock=true`，预览必弹）。`designer unlock` 是软锁释放，多人协作场景防并发；单人编辑也必须收尾 unlock 清态。`publish-menu` 前务必先 save+unlock。
+> **⚠️ 收尾必做显式 save + unlock（否则"布局未保存"）**：`comp-add`/`position`/各组件 setter（chart dataset-set/measure-add 等）虽各自**封装 `/layout/save` 自动存盘**，但全部改完后**必须再跑一次显式 `designer save <pageId> --layouts @<fresh-layout.json>` + `designer unlock <pageId>`**（fresh layout 用 `designer layout <pageId> --terminal all --json` 现导）。否则页面留 `isLock=true`（浏览器开了设计器会自动上锁）或 draft 标志未清，**设计器/预览打开会弹"布局未保存"提示**（验证：未 unlock 的页 `isLock=true`，预览必弹）。`designer unlock` 是软锁释放，多人协作场景防并发；单人编辑也必须收尾 unlock 清态。`publish-menu` 前务必先 save+unlock。

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

@@ -2,6 +2,8 @@
 
 通过 `e10-cli form create` 在 EBuilder 应用中创建表单。本指南说明从需求整理、`fields.json` 编写到建后配置的完整顺序；字段参数和布局样表的详细规则按需读取专题参考。
 
+需求以已有 EB 表单、系统业务表或数据加工结果为实际数据源时，使用 [虚拟表创建与维护](guide-virtual-form.md) 的 `form virtual` 流程。
+
 ## 标准创建流程
 
 1. 确认目标应用 `appId`。
@@ -63,7 +65,7 @@ e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
 ]
 ```
 
-常用类型包括 `Text`、`TextArea`、`Number`、`Money`、`Date`、`DateTime`、`DateRange`、`Select`、`Employee`、`Department`、`FileComponent`、`EBuilder`、`Browser`、`Flow` 和 `DetailTable`。完整类型、关联码表及各类型属性见 [表单字段定义参考](ref-form-fields.md)。
+常用字段类型包括文本、数字、选项、日期、组织、关联、行政区域和其他类型。完整类型、关联码表及各类型属性见 [表单字段定义参考](ref-form-fields.md)；明细表通过表单结构配置创建。
 
 ## 常用字段属性
 
@@ -132,21 +134,38 @@ EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
 
 ### 明细表与二级明细
 
-明细字段写入 `DetailTable.formFields`。二级明细通过当前明细表关联同一主表下的另一张明细表：
+明细字段写入 `DetailTable.formFields`。二级明细关系配置在父明细表上，父明细每一行分别拥有对应的子明细数据：
 
 ```json
 [
-  {"componentKey":"DetailTable","fieldName":"任务明细","formFields":[
+  {"componentKey":"DetailTable","fieldName":"任务明细","enableSubDetail":true,
+   "subDetailConfig":[{"subForm":"工时明细","subField":"父任务标识"}],"formFields":[
     {"componentKey":"Text","fieldName":"任务名称"}
   ]},
-  {"componentKey":"DetailTable","fieldName":"工时明细","enableSubDetail":true,
-   "subDetailConfig":[{"subForm":"任务明细","subField":"任务名称"}],"formFields":[
+  {"componentKey":"DetailTable","fieldName":"工时明细","formFields":[
+    {"componentKey":"Text","fieldName":"父任务标识"},
     {"componentKey":"Number","fieldName":"工时","precision":2}
   ]}
 ]
 ```
 
-已有表单使用 `form detail-table` 查询或调整二级明细关系。
+父级行标识缺省使用行 ID；子级行标识必须为单行文本。多父级复用、多子级和多级嵌套的规则，以及已有表单的查询、增加、删除、启停命令见 [二级明细表配置](guide-form-sub-detail.md)。
+
+### 表单结构与布局组件
+
+主表字段直接写在 `fields.json` 根数组中；明细表使用 `DetailTable` 配置，并通过 `formFields` 维护其字段。主表与明细表字段采用相同的字段类型和属性规则。
+
+布局初始化会根据表单结构生成相应的内部组件：
+
+| 组件 | 在创建流程中的作用 |
+| --- | --- |
+| `DetailTable` | 定义明细表及其字段 |
+| `DataTable` | 在布局中承载和展示明细表 |
+| `Fold` | 承载字段分组和折叠区域 |
+| `Placeholder` | 维护布局中的占位位置 |
+| `EbuilderAppTag` | 维护 EB 应用相关的布局标签 |
+
+业务字段从字段类型码表中选择；以上结构与内部组件由明细表、分组和布局配置生成与维护。
 
 ### 字段公式
 

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-formula-functions.md

@@ -1,7 +1,17 @@
 # 字段函数公式大全（平台 funcList）
 
 > 来源：平台公式函数目录，共 **219 个函数**，11 类。写 `fields.json` 的 `formula` 或 `form formula set --expression` 时查这里。
-> 引用字段语法：`{主表.字段名}`；**日期差用 `DAYS(开始,结束)`**（相减不生效）。
+> 引用字段语法：`{主表.字段名}` / `{明细表名.字段名}`；**日期差用 `DAYS(开始,结束)`**（相减不生效）。
+>
+> **两种写法都收**：设计器的公式编辑器里显示和输入的是方括号 `[字段名]`，平台存储的是花括号
+> `{主表.字段名}`。CLI 两者都认，**从编辑器里复制原文直接传即可**，会先归一化成花括号再下发。
+> 不必自己把 `[通知]` 改写成 `{主表.通知}`。
+>
+> ⚠️ 注意区分：**函数签名里的 `[...]` 表示「可选参数」**（如 `CONCAT(文本1, 文本2, [文本3, …])`），
+> 而表达式里写在字段位置上的 `[字段名]` 才是字段引用。别把签名里的方括号当成引用照抄。
+>
+> 返回类型不填时按目标字段类型推断（数字/金额→Number，日期/时间→Date，其余→String）。
+> **纯常量公式**（不含任何字段引用）平台允许，会带一条提示正常保存。
 > 完整原始数据含参数说明/示例结果：`senba6/公式表.json`。
 
 ## 函数速查矩阵

package/skill-docs/references/form/guide-form-sub-detail.md

@@ -0,0 +1,82 @@
+# 二级明细表配置
+
+二级明细表配置在父明细表上。父明细的每一行分别拥有一组子明细数据；新增子明细数据时，平台把对应父行的行标识自动写入子级行标识字段，用于维持归属关系。
+
+## 结构规则
+
+- 一个父明细可以关联多个子明细。
+- 同一个子明细可以被多个父明细复用。
+- 明细关系可以继续向下嵌套，例如 A → B → C。
+- 当前明细不能选择自身、直属父级或任一祖先作为子明细。通过候选列表选择目标即可。
+- 调换父子方向时，先删除原关系，再重新查询新父明细的候选列表并建立反向关系。例如将 `A → B` 改为 `B → A`，依次执行：删除 `A → B`、查询 B 的候选列表、新增 `B → A`。
+- 父级行标识支持行 ID、单行文本 `Text`、单选框 `RadioBox`、下拉单选框 `Select`，没有明确要求时使用行 ID。
+- 子级行标识必须使用单行文本 `Text`。
+
+## 创建时配置
+
+先定义全部明细表，再把 `enableSubDetail` 和 `subDetailConfig` 写在父明细表上：
+
+```json
+[
+  {
+    "componentKey": "DetailTable",
+    "fieldName": "任务明细",
+    "enableSubDetail": true,
+    "defaultExpandRow": true,
+    "subDetailConfig": [
+      {"subForm": "工时明细", "subField": "父任务标识"}
+    ],
+    "formFields": [
+      {"componentKey": "Text", "fieldName": "任务名称"}
+    ]
+  },
+  {
+    "componentKey": "DetailTable",
+    "fieldName": "工时明细",
+    "formFields": [
+      {"componentKey": "Text", "fieldName": "父任务标识"},
+      {"componentKey": "Number", "fieldName": "工时", "precision": 2}
+    ]
+  }
+]
+```
+
+缺省父级行标识为 `rowId`。需要使用父明细字段时，在关系中增加 `parentField`，可传字段名或字段 ID：
+
+```json
+{"subForm":"工时明细","subField":"父任务标识","parentField":"任务编码"}
+```
+
+## 已有表单维护
+
+先查询父明细当前可选的子明细，再配置关系：
+
+```shell
+e10-cli form detail-table sub-detail candidates <objId> <appId> <父明细>
+e10-cli form detail-table sub-detail add <objId> <appId> <父明细> --target <子明细> --target-field <子级文本标识>
+```
+
+常用命令：
+
+| 操作 | 命令 |
+| --- | --- |
+| 查询全部明细表 | `form detail-table list <objId> <appId>` |
+| 查询某父明细当前配置 | `form detail-table read <objId> <appId> <父明细>` |
+| 查询可选子明细 | `form detail-table sub-detail candidates <objId> <appId> <父明细>` |
+| 增加或更新一条关系 | `form detail-table sub-detail add ... --target <子明细> --target-field <子级标识> [--parent-field <父级标识>]` |
+| 完整替换关系 | `form detail-table sub-detail set ... --target <子明细> --target-field <子级标识> [--parent-field <父级标识>]` |
+| 删除一条关系 | `form detail-table sub-detail remove ... --target <子明细>` |
+| 启用或停用 | `form detail-table sub-detail enable\|disable ...` |
+| 清空全部关系 | `form detail-table sub-detail clear ...` |
+
+`add` 保留父明细已有的其他子明细关系；`set` 完整替换父明细的关系配置。删除最后一条关系后，二级明细功能随之关闭。`disable` 仅停用并保留关系，后续可用 `enable` 恢复。
+
+## 执行顺序
+
+1. 创建父、子明细表及字段。
+2. 确认子明细存在可用的 `Text` 行标识字段。
+3. 使用 `candidates` 查询当前父明细可选目标。
+4. 使用 `add` 或 `set` 保存关系；未指定父级字段时使用 `rowId`。
+5. 使用 `read` 回读父明细的 `enableSubDetail`、`defaultExpandRow` 和 `subDetailConfig`。
+
+关系方向发生变化时，先对原父明细执行 `remove`，再按第 3～5 步以新的父明细重新配置。