weaver-e10-builder 1.2.2 → 1.2.3

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

@@ -1,232 +1,233 @@
-# 新建 EBuilder 表单
-
-通过 `e10-cli form create` 在 EBuilder 应用中创建表单。本指南说明从需求整理、`fields.json` 编写到建后配置的完整顺序；字段参数和布局样表的详细规则按需读取专题参考。
-
-需求以已有 EB 表单、系统业务表或数据加工结果为实际数据源时，使用 [虚拟表创建与维护](guide-virtual-form.md) 的 `form virtual` 流程。
-
-## 标准创建流程
-
-1. 确认目标应用 `appId`。
-2. 确认布局类型：流式 `FLOW` 或表格式 `EXCEL`。布局类型在建表时确定。
-3. 从需求中整理字段、明细表、字段顺序和布局要求；遇到完整布局样表时，将空间结构写入 plan 的“表单布局蓝图”。
-4. 将建表时可以完成的配置写入 `fields.json`。
-5. 执行 `form create`，记录返回的 `objId` 和 `formId`。
-6. 使用 `form list-view` 查询并记录默认台账 `listId`。
-7. 按需求完成多语言、联动、校验、权限、视图和按钮等建后配置。
-8. 使用读取命令轻量核对字段、布局和默认台账。
-
-```bash
-e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW|EXCEL
-e10-cli form list-view <objId> <appId>
-e10-cli form read <objId> --app-id <appId> --out fields-created.json
-```
-
-需要同时生成台账菜单入口时，在创建命令中增加 `--menu`；建成后也可使用 `menu add-table <appId> <objId>` 添加。默认台账视图与应用菜单入口是两个资源。
-
-## 各阶段配置范围
-
-| 阶段 | 配置内容 |
-|---|---|
-| 需求与 plan | 表单名称、字段类型、顺序、明细结构、FLOW/EXCEL、布局蓝图及外围配置 |
-| `fields.json` | 字段、选项、默认值、精度、日期格式、关联、公式、明细、分组和显示属性 |
-| `form create` | 表单主体、字段、明细、布局、基础查看权限、默认台账及可选菜单 |
-| 建成后 | 字段多语言、联动、查重、进一步权限、视图名称与列、筛选、按钮及关联页签 |
-| 完成核对 | `objId`、`formId`、`listId`、字段结构和布局结果 |
-
-## 建表前整理需求
-
-### 布局类型
-
-```bash
-e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW
-e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
-```
-
-- `FLOW`：流式布局。
-- `EXCEL`：表格式布局，也是 CLI 缺省值。
-- 需求未明确且布局选择会影响结果时，建表前向用户确认。
-- 需求提供完整表格、合并单元格、分组标题、标签与字段交替排布时，按布局样表处理，详见 [表单布局规划](guide-form-layout-planning.md)。
-
-### 字段定义
-
-字段按照需求顺序写入 `fields.json`。主表字段在前，`DetailTable` 明细表放在数组末尾。
-
-```json
-[
-  {"componentKey":"Text","fieldName":"合同名称","required":true,"singleRow":true},
-  {"componentKey":"DateRange","fieldName":"合同有效期","format":"yyyy-MM-dd"},
-  {"componentKey":"Money","fieldName":"合同金额","precision":2},
-  {"componentKey":"Select","fieldName":"合同状态","fieldOptions":[{"name":"草稿"},{"name":"履行中"}]},
-  {"componentKey":"Employee","fieldName":"负责人"},
-  {"componentKey":"DetailTable","fieldName":"付款明细","formFields":[
-    {"componentKey":"Date","fieldName":"付款日期"},
-    {"componentKey":"Number","fieldName":"付款金额","precision":2}
-  ]}
-]
-```
-
-常用字段类型包括文本、数字、选项、日期、组织、关联、行政区域和其他类型。完整类型、关联码表及各类型属性见 [表单字段定义参考](ref-form-fields.md)；明细表通过表单结构配置创建。
-
-## 常用字段属性
-
-| 属性 | 作用 |
-|---|---|
-| `required:true` | 字段必填 |
-| `readOnly:true` | 禁止手工编辑 |
-| `hidden:true` | 布局中隐藏，字段仍可参与计算 |
-| `singleRow:true` | 独占一行 |
-| `group:"基本信息"` | 放入指定字段分组 |
-| `multiple:true` | 支持多选的字段设置为多选 |
-| `maxLen:500` | 文本最大长度 |
-| `precision:2` | 数字或金额小数位 |
-| `defaultValue` | 字段默认值 |
-
-### 字段分组
-
-以需求为准：只有需求明确要求字段分组时，才在 `fields.json` 中设置 `group`；需求未要求时保持不分组。
-
-```json
-[
-  {"componentKey":"Text","fieldName":"项目名称","group":"基本信息","required":true},
-  {"componentKey":"Employee","fieldName":"负责人","group":"基本信息"},
-  {"componentKey":"Number","fieldName":"项目金额","group":"财务信息","precision":2}
-]
-```
-
-同名 `group` 的字段进入同一个分组。分组内字段按字段顺序排列，需要整行展示的字段增加 `singleRow:true`。已有表单补充分组时使用：
-
-```bash
-e10-cli form group <objId> <appId> --groups '{"基本信息":["项目名称","负责人"]}'
-```
-
-### 日期区间
-
-字段本身包含开始与结束含义，如“项目周期、合同有效期、请假时间、活动时间”，优先使用 `DateRange`。明确要求两个独立字段，或开始、结束需要分别参与公式和联动时，再拆成两个日期字段。
-
-```json
-{"componentKey":"DateRange","fieldName":"项目周期","format":"yyyy-MM-dd"}
-```
-
-### 选项和多选
-
-```json
-{"componentKey":"Select","fieldName":"状态","fieldOptions":[{"name":"启用"},{"name":"停用"}]},
-{"componentKey":"Employee","fieldName":"项目成员","multiple":true}
-```
-
-`Select`、`RadioBox`、`CheckBox` 可在 `fieldOptions` 中定义选项。人员、部门、EBuilder、Browser 和 Select 等支持按字段能力设置多选。共享选项可使用 `optionTemplate`；详细结构见 [表单字段定义参考](ref-form-fields.md)。
-
-### 关联字段
-
-EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
-
-```json
-{
-  "componentKey":"EBuilder",
-  "fieldName":"关联客户",
-  "sformId":"<目标表单objId>",
-  "dataTitle":"客户名称",
-  "displayColumns":["客户名称","客户类型"]
-}
-```
-
-`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见 [表单字段定义参考](ref-form-fields.md)；关联数据过滤和范围分别见 [EBuilder 过滤](guide-ebuilder-filter.md) 与 [关联浏览数据范围](guide-ebuilder-scope.md)。
-
-### 明细表与二级明细
-
-明细字段写入 `DetailTable.formFields`。二级明细通过当前明细表关联同一主表下的另一张明细表：
-
-```json
-[
-  {"componentKey":"DetailTable","fieldName":"任务明细","formFields":[
-    {"componentKey":"Text","fieldName":"任务名称"}
-  ]},
-  {"componentKey":"DetailTable","fieldName":"工时明细","enableSubDetail":true,
-   "subDetailConfig":[{"subForm":"任务明细","subField":"任务名称"}],"formFields":[
-    {"componentKey":"Number","fieldName":"工时","precision":2}
-  ]}
-]
-```
-
-二级明细的 `defaultExpandRow` 控制默认展开行。已有表单使用 `form detail-table` 查询或调整二级明细关系。
-
-### 表单结构与布局组件
-
-主表字段直接写在 `fields.json` 根数组中；明细表使用 `DetailTable` 配置，并通过 `formFields` 维护其字段。主表与明细表字段采用相同的字段类型和属性规则。
-
-布局初始化会根据表单结构生成相应的内部组件：
-
-| 组件 | 在创建流程中的作用 |
-| --- | --- |
-| `DetailTable` | 定义明细表及其字段 |
-| `DataTable` | 在布局中承载和展示明细表 |
-| `Fold` | 承载字段分组和折叠区域 |
-| `Placeholder` | 维护布局中的占位位置 |
-| `EbuilderAppTag` | 维护 EB 应用相关的布局标签 |
-
-业务字段从字段类型码表中选择；以上结构与内部组件由明细表、分组和布局配置生成与维护。
-
-### 字段公式
-
-可在目标字段中写 `formula`，由创建流程完成公式创建和字段绑定：
-
-```json
-{"componentKey":"Number","fieldName":"项目收益","formula":"{主表.已收款}-{主表.项目费用}"}
-```
-
-公式表达式、明细汇总和函数格式见 [字段公式函数参考](guide-form-formula-functions.md)。复杂编号属于建后配置，见 [表单复杂编号](guide-form-serial-mark.md)。
-
-## 执行创建
-
-```bash
-e10-cli form create <appId> "采购合同" --fields @fields.json --layout EXCEL
-```
-
-创建流程会依次完成表单主体、字段和明细、布局初始化、字段高级属性、关联关系、选项、公式、分组、基础查看权限及默认台账配置。传入 `--menu` 时同时添加台账菜单入口。
-
-记录命令返回的：
-
-- `objId`：EB 表单业务对象 ID，多数 `form` 命令使用它。
-- `formId`：底层表单 ID，布局和部分底层接口使用它。
-- `listId`：默认台账 ID，通过 `form list-view` 查询。
-
-## 建成后配置
-
-按需求执行，未提出的配置不额外增加：
-
-| 需求 | 命令或指南 |
-|---|---|
-| 字段中英文名称 | `form field-lang set` |
-| 字段显隐、只读、必填联动 | [表单联动](guide-form-linkage.md) |
-| 字段查重 | `form validate` |
-| 表单和数据权限 | `form permission` |
-| 默认台账改名、列、筛选和分组 | [表单视图](guide-form-view.md) |
-| 表单及视图按钮 | [表单按钮](guide-form-button.md) |
-| 关联页签 | [表单关联页签](guide-form-association.md) |
-| 复杂编号 | [表单复杂编号](guide-form-serial-mark.md) |
-
-需求写成 `中文/English`（如 `项目/project`）时，先以中文名称创建字段，再设置多语言：
-
-```bash
-e10-cli form field-lang set <objId> <appId> <fieldId> --zh "项目" --en "project"
-```
-
-## 完成核对
-
-使用与本次需求直接相关的读取命令核对即可：
-
-```bash
-e10-cli form read <objId> --app-id <appId> --out fields-created.json
-e10-cli form list-view <objId> <appId>
-e10-cli form layout read <objId> <appId>
-```
-
-重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。
-
-## 专题参考
-
-- [表单字段定义参考](ref-form-fields.md)：完整字段类型、属性、关联类型和 JSON 结构。
-- [表单布局规划](guide-form-layout-planning.md)：FLOW/EXCEL、布局样表、布局蓝图及建后调整。
-- [表单复杂编号](guide-form-serial-mark.md)：编号段、流水和代字配置。
-- [字段公式函数参考](guide-form-formula-functions.md)：公式表达式和函数。
-- [表单视图](guide-form-view.md)：默认台账、视图名称和列表配置。
+# 新建 EBuilder 表单
+
+通过 `e10-cli form create` 在 EBuilder 应用中创建表单。本指南说明从需求整理、`fields.json` 编写到建后配置的完整顺序；字段参数和布局样表的详细规则按需读取专题参考。
+
+需求以已有 EB 表单、系统业务表或数据加工结果为实际数据源时，使用 [虚拟表创建与维护](guide-virtual-form.md) 的 `form virtual` 流程。
+
+## 标准创建流程
+
+1. 确认目标应用 `appId`。
+2. 确认布局类型：流式 `FLOW` 或表格式 `EXCEL`。布局类型在建表时确定。
+3. 从需求中整理字段、明细表、字段顺序和布局要求；遇到完整布局样表时，将空间结构写入 plan 的“表单布局蓝图”。
+4. 将建表时可以完成的配置写入 `fields.json`。
+5. 执行 `form create`，记录返回的 `objId` 和 `formId`。
+6. 使用 `form list-view` 查询并记录默认台账 `listId`。
+7. 按需求完成多语言、联动、校验、权限、视图和按钮等建后配置。
+8. 使用读取命令轻量核对字段、布局和默认台账。
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW|EXCEL
+e10-cli form list-view <objId> <appId>
+e10-cli form read <objId> --app-id <appId> --out fields-created.json
+```
+
+需要同时生成台账菜单入口时，在创建命令中增加 `--menu`；建成后也可使用 `menu add-table <appId> <objId>` 添加。默认台账视图与应用菜单入口是两个资源。
+
+## 各阶段配置范围
+
+| 阶段 | 配置内容 |
+|---|---|
+| 需求与 plan | 表单名称、字段类型、顺序、明细结构、FLOW/EXCEL、布局蓝图及外围配置 |
+| `fields.json` | 字段、选项、默认值、精度、日期格式、关联、公式、明细、分组和显示属性 |
+| `form create` | 表单主体、字段、明细、布局、基础查看权限、默认台账及可选菜单 |
+| 建成后 | 字段多语言、联动、查重、进一步权限、视图名称与列、筛选、按钮及关联页签 |
+| 完成核对 | `objId`、`formId`、`listId`、字段结构和布局结果 |
+
+## 建表前整理需求
+
+### 布局类型
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
+```
+
+- `FLOW`：流式布局。
+- `EXCEL`：表格式布局，也是 CLI 缺省值。
+- 需求未明确且布局选择会影响结果时，建表前向用户确认。
+- 需求提供完整表格、合并单元格、分组标题、标签与字段交替排布时，按布局样表处理，详见 [表单布局规划](guide-form-layout-planning.md)。
+
+### 字段定义
+
+字段按照需求顺序写入 `fields.json`。主表字段在前，`DetailTable` 明细表放在数组末尾。
+
+```json
+[
+  {"componentKey":"Text","fieldName":"合同名称","required":true,"singleRow":true},
+  {"componentKey":"DateRange","fieldName":"合同有效期","format":"yyyy-MM-dd"},
+  {"componentKey":"Money","fieldName":"合同金额","precision":2},
+  {"componentKey":"Select","fieldName":"合同状态","fieldOptions":[{"name":"草稿"},{"name":"履行中"}]},
+  {"componentKey":"Employee","fieldName":"负责人"},
+  {"componentKey":"DetailTable","fieldName":"付款明细","formFields":[
+    {"componentKey":"Date","fieldName":"付款日期"},
+    {"componentKey":"Number","fieldName":"付款金额","precision":2}
+  ]}
+]
+```
+
+常用字段类型包括文本、数字、选项、日期、组织、关联、行政区域和其他类型。完整类型、关联码表及各类型属性见 [表单字段定义参考](ref-form-fields.md)；明细表通过表单结构配置创建。
+
+## 常用字段属性
+
+| 属性 | 作用 |
+|---|---|
+| `required:true` | 字段必填 |
+| `readOnly:true` | 禁止手工编辑 |
+| `hidden:true` | 布局中隐藏，字段仍可参与计算 |
+| `singleRow:true` | 独占一行 |
+| `group:"基本信息"` | 放入指定字段分组 |
+| `multiple:true` | 支持多选的字段设置为多选 |
+| `maxLen:500` | 文本最大长度 |
+| `precision:2` | 数字或金额小数位 |
+| `defaultValue` | 字段默认值 |
+
+### 字段分组
+
+以需求为准：只有需求明确要求字段分组时，才在 `fields.json` 中设置 `group`；需求未要求时保持不分组。
+
+```json
+[
+  {"componentKey":"Text","fieldName":"项目名称","group":"基本信息","required":true},
+  {"componentKey":"Employee","fieldName":"负责人","group":"基本信息"},
+  {"componentKey":"Number","fieldName":"项目金额","group":"财务信息","precision":2}
+]
+```
+
+同名 `group` 的字段进入同一个分组。分组内字段按字段顺序排列，需要整行展示的字段增加 `singleRow:true`。已有表单补充分组时使用：
+
+```bash
+e10-cli form group <objId> <appId> --groups '{"基本信息":["项目名称","负责人"]}'
+```
+
+### 日期区间
+
+字段本身包含开始与结束含义，如“项目周期、合同有效期、请假时间、活动时间”，优先使用 `DateRange`。明确要求两个独立字段，或开始、结束需要分别参与公式和联动时，再拆成两个日期字段。
+
+```json
+{"componentKey":"DateRange","fieldName":"项目周期","format":"yyyy-MM-dd"}
+```
+
+### 选项和多选
+
+```json
+{"componentKey":"Select","fieldName":"状态","fieldOptions":[{"name":"启用"},{"name":"停用"}]},
+{"componentKey":"Employee","fieldName":"项目成员","multiple":true}
+```
+
+`Select`、`RadioBox`、`CheckBox` 可在 `fieldOptions` 中定义选项。人员、部门、EBuilder、Browser 和 Select 等支持按字段能力设置多选。共享选项可使用 `optionTemplate`；详细结构见 [表单字段定义参考](ref-form-fields.md)。
+
+### 关联字段
+
+EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
+
+```json
+{
+  "componentKey":"EBuilder",
+  "fieldName":"关联客户",
+  "sformId":"<目标表单objId>",
+  "dataTitle":"客户名称",
+  "displayColumns":["客户名称","客户类型"]
+}
+```
+
+`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见 [表单字段定义参考](ref-form-fields.md)；关联数据过滤和范围分别见 [EBuilder 过滤](guide-ebuilder-filter.md) 与 [关联浏览数据范围](guide-ebuilder-scope.md)。
+
+### 明细表与二级明细
+
+明细字段写入 `DetailTable.formFields`。二级明细关系配置在父明细表上，父明细每一行分别拥有对应的子明细数据：
+
+```json
+[
+  {"componentKey":"DetailTable","fieldName":"任务明细","enableSubDetail":true,
+   "subDetailConfig":[{"subForm":"工时明细","subField":"父任务标识"}],"formFields":[
+    {"componentKey":"Text","fieldName":"任务名称"}
+  ]},
+  {"componentKey":"DetailTable","fieldName":"工时明细","formFields":[
+    {"componentKey":"Text","fieldName":"父任务标识"},
+    {"componentKey":"Number","fieldName":"工时","precision":2}
+  ]}
+]
+```
+
+父级行标识缺省使用行 ID；子级行标识必须为单行文本。多父级复用、多子级和多级嵌套的规则，以及已有表单的查询、增加、删除、启停命令见 [二级明细表配置](guide-form-sub-detail.md)。
+
+### 表单结构与布局组件
+
+主表字段直接写在 `fields.json` 根数组中；明细表使用 `DetailTable` 配置，并通过 `formFields` 维护其字段。主表与明细表字段采用相同的字段类型和属性规则。
+
+布局初始化会根据表单结构生成相应的内部组件：
+
+| 组件 | 在创建流程中的作用 |
+| --- | --- |
+| `DetailTable` | 定义明细表及其字段 |
+| `DataTable` | 在布局中承载和展示明细表 |
+| `Fold` | 承载字段分组和折叠区域 |
+| `Placeholder` | 维护布局中的占位位置 |
+| `EbuilderAppTag` | 维护 EB 应用相关的布局标签 |
+
+业务字段从字段类型码表中选择；以上结构与内部组件由明细表、分组和布局配置生成与维护。
+
+### 字段公式
+
+可在目标字段中写 `formula`，由创建流程完成公式创建和字段绑定：
+
+```json
+{"componentKey":"Number","fieldName":"项目收益","formula":"{主表.已收款}-{主表.项目费用}"}
+```
+
+公式表达式、明细汇总和函数格式见 [字段公式函数参考](guide-form-formula-functions.md)。复杂编号属于建后配置，见 [表单复杂编号](guide-form-serial-mark.md)。
+
+## 执行创建
+
+```bash
+e10-cli form create <appId> "采购合同" --fields @fields.json --layout EXCEL
+```
+
+创建流程会依次完成表单主体、字段和明细、布局初始化、字段高级属性、关联关系、选项、公式、分组、基础查看权限及默认台账配置。传入 `--menu` 时同时添加台账菜单入口。
+
+记录命令返回的：
+
+- `objId`：EB 表单业务对象 ID，多数 `form` 命令使用它。
+- `formId`：底层表单 ID，布局和部分底层接口使用它。
+- `listId`：默认台账 ID，通过 `form list-view` 查询。
+
+## 建成后配置
+
+按需求执行，未提出的配置不额外增加：
+
+| 需求 | 命令或指南 |
+|---|---|
+| 字段中英文名称 | `form field-lang set` |
+| 字段显隐、只读、必填联动 | [表单联动](guide-form-linkage.md) |
+| 字段查重 | `form validate` |
+| 表单和数据权限 | `form permission` |
+| 默认台账改名、列、筛选和分组 | [表单视图](guide-form-view.md) |
+| 表单及视图按钮 | [表单按钮](guide-form-button.md) |
+| 关联页签 | [表单关联页签](guide-form-association.md) |
+| 复杂编号 | [表单复杂编号](guide-form-serial-mark.md) |
+
+需求写成 `中文/English`（如 `项目/project`）时，先以中文名称创建字段，再设置多语言：
+
+```bash
+e10-cli form field-lang set <objId> <appId> <fieldId> --zh "项目" --en "project"
+```
+
+## 完成核对
+
+使用与本次需求直接相关的读取命令核对即可：
+
+```bash
+e10-cli form read <objId> --app-id <appId> --out fields-created.json
+e10-cli form list-view <objId> <appId>
+e10-cli form layout read <objId> <appId>
+```
+
+重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。
+
+## 专题参考
+
+- [表单字段定义参考](ref-form-fields.md)：完整字段类型、属性、关联类型和 JSON 结构。
+- [表单布局规划](guide-form-layout-planning.md)：FLOW/EXCEL、布局样表、布局蓝图及建后调整。
+- [表单复杂编号](guide-form-serial-mark.md)：编号段、流水和代字配置。
+- [字段公式函数参考](guide-form-formula-functions.md)：公式表达式和函数。
+- [表单视图](guide-form-view.md)：默认台账、视图名称和列表配置。

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 步以新的父明细重新配置。

package/skill-docs/references/form/guide-list-custom-text.md

@@ -0,0 +1,52 @@
+# 列表自定义文本列
+
+表单的列表式视图（台账）里，列除了直接绑表单字段，还能加一列**自定义文本**：内容是一段富文本，
+可以写固定文字、插图，也能在文字中间**插入表单字段**（「合计：〔金额〕元」这种说明性排版）。
+
+命令是 `form nlist apply`：模板里**不给 `fieldId`、改给 `html`** 的列项，就是自定义文本列。
+
+```json
+[
+  [
+    {"fieldId": "1317534123603582976", "text": "金额", "width": 1},
+    {"html": "<p>合计：{{金额}} 元</p>", "text": "合计", "width": 1}
+  ]
+]
+```
+
+```bash
+e10-cli form nlist apply <objId> <appId> <listId> @template.json
+```
+
+## 在自定义文本里插入表单字段
+
+写 `{{字段名}}` 或 `{{fieldId}}`，CLI 查表单元数据后展开成平台的字段引用标记。
+
+上面那段 `html` 存进去的是：
+
+```html
+<p>合计：<span contenteditable="false" data-type="list" data-val="{objId.fieldId}">{表名.字段名}</span> 元</p>
+```
+
+规则：
+
+- 同一字段写几次就展开几份 —— 平台按**出现位置**逐个记引用，不去重。
+- 字段显示名在表单内重复时报错，改用 `fieldId`。
+- 字段不存在 → 报错并中止，不会把半截 HTML 写进视图。
+
+## 直接写字段引用标记
+
+已经拿到平台原样标记时，也可以把它整段写进 `html`。CLI 会校验 `data-val` 里的 fieldId 在这张
+表单里是否存在，查不到只**告警**（平台对这种引用不报错，只是静默显示不出值，所以提醒一声）。
+
+标记的形状固定为 `<span contenteditable="false" data-type="list" data-val="{objId.fieldId}">{表名.字段名}</span>`：
+**身份在 `data-val` 里的 `objId.fieldId`**，span 里的 `{表名.字段名}` 只是占位文本。
+
+## 其它
+
+- 列显示名用模板项的 `text`，缺省「自定义文本」。
+- 富文本的配色、字号、背景直接写在内联 `style` 里，与设计器编辑器一致，例如
+  `<span style="background-color:#27ae60">应收</span>`。
+- `form nlist apply` 按模板整体重建显示列与排布，PC 与移动端两个槽位一并写入；
+  当前配置用 `form nlist show <objId> <appId> <listId>` 查看。
+- ⚠ 只对列表式（NList）生效，表格式台账用 `form table-view`。