weaver-e10-builder 1.5.16 → 1.6.4

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

@@ -1,258 +1,258 @@
-# 新建 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>` 添加。默认台账视图与应用菜单入口是两个资源。
-
-### 自定义数据库表名
-
-不指定时表名按表单名拼音首字母加随机数生成（如 `uf_xsddb_4683`）。需要固定或对齐既有命名时用 `--table-name`：
-
-```bash
-e10-cli form create <appId> "客户信息表" --fields @fields.json --table-name cs_khxx
-```
-
-- **平台前缀由 CLI 自动补**：传 `cs_khxx` 与传 `uf_cs_khxx` 结果相同（`uf_cs_khxx`）。
-- **格式约束**：字母开头，只含字母、数字、下划线。前缀之外的部分受平台长度上限约束 —— 前缀 `uf_`、总长上限 30 时，自定义部分最多 27 位。越界会直接报错，不会建成一半。
-- **建成后回读校验**：实际表名与预期不一致会报错，不静默通过。
-- 仅对**物理表**应用有效；应用未启用物理表时该选项不适用（CLI 会先查存储设置并拒绝）。
-
-## 各阶段配置范围
-
-| 阶段 | 配置内容 |
-|---|---|
-| 需求与 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)。
-
-**开关（`Switch`）自动带固定选项「开启=1 / 关闭=0」**，不需要在 `fields.json` 里写 `fieldOptions`；主表、明细表与后续 `form add-field` / `form add-physical-field` 都会自动补上。
-
-### 关联字段
-
-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)。
-
-**明细表里的 EBuilder 子字段用同一套键**：在 `DetailTable.formFields` 的字段对象里写 `sformId` / `dataTitle` / `displayColumns` 即可，建表时会一起绑定到目标表单；不写 `sformId` 会建成无关联的裸字段（命令会给出警告）。
-
-使用自定义浏览框时，在 `fields.json` 的 `Browser` / `RelateBrowser` 字段写 `"browserName":"浏览框准确名称"`；CLI 会从当前环境检索该名称并绑定。已有表单用 `form add-field ... Browser --browser-name "浏览框准确名称"`。具体字段示例见 [表单字段定义参考](ref-form-fields.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)。
-
-明细表的**描述默认是空**；需要时在 `DetailTable` 上写 `"describe":"说明文字"`，不写不会用明细名填充。
-
-### 表单结构与布局组件
-
-主表字段直接写在 `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)。
-
-## 执行创建
-
-需要还原图片或 XLSX 源样式时，可在普通创建完成后使用[源样式还原命令链](guide-form-layout-source.md)，或同时传 `--layout-source @source.json --layout-spec @spec.json --layout-artifact-out artifact.json`。该入口先验证源文件，继续使用原字段创建链，最后在高级属性、公式和分组重排结束后保存精确布局。失败保留已有 objId/formId，重试只处理该对象，不重复建表。
-
-```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>
-```
-
-重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。
-
-`fields-created.json` 里的 `fieldName` **就是字段标题** —— 与设计器「字段管理」里看到的是同一个值，想核对标题建对没有看它即可。它为空就说明标题没写进去（`form add-field` 没给标题时会回落成字段名，所以正常不会空）。
-
-## 专题参考
-
-- [表单字段定义参考](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>` 添加。默认台账视图与应用菜单入口是两个资源。
+
+### 自定义数据库表名
+
+不指定时表名按表单名拼音首字母加随机数生成（如 `uf_xsddb_4683`）。需要固定或对齐既有命名时用 `--table-name`：
+
+```bash
+e10-cli form create <appId> "客户信息表" --fields @fields.json --table-name cs_khxx
+```
+
+- **平台前缀由 CLI 自动补**：传 `cs_khxx` 与传 `uf_cs_khxx` 结果相同（`uf_cs_khxx`）。
+- **格式约束**：字母开头，只含字母、数字、下划线。前缀之外的部分受平台长度上限约束 —— 前缀 `uf_`、总长上限 30 时，自定义部分最多 27 位。越界会直接报错，不会建成一半。
+- **建成后回读校验**：实际表名与预期不一致会报错，不静默通过。
+- 仅对**物理表**应用有效；应用未启用物理表时该选项不适用（CLI 会先查存储设置并拒绝）。
+
+## 各阶段配置范围
+
+| 阶段 | 配置内容 |
+|---|---|
+| 需求与 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 缺省值。
+- 需求未明确且布局选择会影响结果时，建表前向用户确认。
+- 需求提供完整表格、合并单元格、分组标题、标签与字段交替排布时，按布局样表处理，详见 [表单布局规划](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)。
+
+**开关（`Switch`）自动带固定选项「开启=1 / 关闭=0」**，不需要在 `fields.json` 里写 `fieldOptions`；主表、明细表与后续 `form add-field` / `form add-physical-field` 都会自动补上。
+
+### 关联字段
+
+EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
+
+```json
+{
+  "componentKey":"EBuilder",
+  "fieldName":"关联客户",
+  "sformId":"<目标表单objId>",
+  "dataTitle":"客户名称",
+  "displayColumns":["客户名称","客户类型"]
+}
+```
+
+`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见[表单字段定义参考](ref-form-fields.md)；关联浏览的数据范围见[浏览数据定义](guide-browser-definition.md#数据范围)。旧布局过滤配置见[EBuilder 过滤](guide-ebuilder-filter.md)。
+
+**明细表里的 EBuilder 子字段用同一套键**：在 `DetailTable.formFields` 的字段对象里写 `sformId` / `dataTitle` / `displayColumns` 即可，建表时会一起绑定到目标表单；不写 `sformId` 会建成无关联的裸字段（命令会给出警告）。
+
+使用自定义浏览框时，在 `fields.json` 的 `Browser` / `RelateBrowser` 字段写 `"browserName":"浏览框准确名称"`；CLI 会从当前环境检索该名称并绑定。已有表单用 `form add-field ... Browser --browser-name "浏览框准确名称"`。具体字段示例见 [表单字段定义参考](ref-form-fields.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)。
+
+明细表的**描述默认是空**；需要时在 `DetailTable` 上写 `"describe":"说明文字"`，不写不会用明细名填充。
+
+### 表单结构与布局组件
+
+主表字段直接写在 `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)。
+
+## 执行创建
+
+需要还原图片或 XLSX 源样式时，可在普通创建完成后使用[源样式还原命令链](layout/source-restoration.md)，或同时传 `--layout-source @source.json --layout-spec @spec.json --layout-artifact-out artifact.json`。该入口先验证源文件，继续使用原字段创建链，最后在高级属性、公式和分组重排结束后保存精确布局。失败保留已有 objId/formId，重试只处理该对象，不重复建表。
+
+```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>
+```
+
+重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。
+
+`fields-created.json` 里的 `fieldName` **就是字段标题** —— 与设计器「字段管理」里看到的是同一个值，想核对标题建对没有看它即可。它为空就说明标题没写进去（`form add-field` 没给标题时会回落成字段名，所以正常不会空）。
+
+## 专题参考
+
+- [表单字段定义参考](ref-form-fields.md)：完整字段类型、属性、关联类型和 JSON 结构。
+- [表单布局规划](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-field-linkage.md

@@ -134,9 +134,12 @@ e10-cli form field-linkage add <appId> <objId> \
 
 ### 明细行依据（`--basis`）
 
-`明细表名=源表字段名`。决定写入明细表时按哪一列匹配/生成行。不给则取该明细表第一个赋值的源字段；当被赋值的源字段正好是依据值时，设计器里显示为「依据值本身」。
+**不给 = 依据值选「表」**：用查询结果整表作为依据，设计器里显示为源表名（如 `产品清单(uf_clm_inv_content_51)`）；每个赋值都是这张表里的一列（`type=10` + `originValue`）。写明细表通常用这个，也是设计器的默认形态。
+
+只有确实需要按某个字段匹配/合并行时，才显式写 `明细表名=源表字段名`。这时设计器里的依据值是字段；当赋值源字段正好等于依据值时，显示为「依据值本身」。
 
 ```bash
+# 字段级依据（可选，按该字段匹配行）
 --basis "明细表1=测试字段C"
 ```
 

package/skill-docs/references/form/guide-form-attachment-setting.md

@@ -0,0 +1,95 @@
+# 附件上传与关联文档设置指南
+
+表单「附件设置」页控制附件文件存在哪里、能传什么、以及由附件创建文档时落在哪个目录。设置分**通用配置**和**字段级覆盖**两层：字段级未显式覆盖的项继承通用配置。
+
+## 三层对应关系
+
+| 界面 | 通用配置 | 字段级覆盖 |
+|---|---|---|
+| 附件/图片上传目录 | `folderId` + `folderIdBrowserValue` | 同名字段；`folderSelectType` 区分固定目录 / 选项关联 |
+| 关联文档 → 新建方式设置 | `addTypeConfig.types` | `docAddTypeConfig` |
+| 关联文档 → 新建文档存储位置 | `fixedDirectory.folderValue` | `docFixedDirectoryConfig` |
+| 上传格式 | `customLimitFormat` | 同名字段 |
+| 大小限制 / 启用 / 提示语 | `attmentSizeLimit` / `enableState` / `displayTip` | 同名字段 |
+
+两个目录不要混：
+
+- **上传目录**决定附件文件存放位置；为空表示没有落点。
+- **新建文档存储位置**决定由附件创建出来的文档放在哪个知识库目录。
+- 附件"没有进文档"时，先确认**新建方式**和**新建文档存储位置**，再看上传目录；字段级覆盖成"选项关联但没有匹配目录"也会导致附件没有落点。
+
+## 读取
+
+```bash
+# 通用配置 + 字段级覆盖概要
+e10-cli form attachment-setting get <appId> <objId>
+
+# 单个附件字段的覆盖配置
+e10-cli form attachment-setting get <appId> <objId> --field <字段名或fieldId>
+```
+
+## 修改通用配置
+
+```bash
+e10-cli form attachment-setting set <appId> <objId> \
+  --upload-dir <目录ID> \
+  --doc-dir <目录ID> \
+  --doc-types html,WORD,markdown,UPLOAD \
+  --formats @doc,@image,@archive \
+  --max-size 20 \
+  --enable on --display-tip on
+```
+
+| 参数 | 说明 |
+|---|---|
+| `--upload-dir` | 附件/图片上传目录，写文档目录 ID 或唯一名称/路径；`none` 清空 |
+| `--doc-dir` | 新建文档存储位置，写法同上；`none` 清空 |
+| `--doc-types` | 新建方式，逗号分隔；`none` 清空。可选值用 `doc-types` 查询 |
+| `--formats` | 上传格式：扩展名逗号串，或预设 `@doc` / `@image` / `@video` / `@audio` / `@archive`；`none` 清空 |
+| `--max-size` | 单文件大小限制（MB），不能超过平台系统上限 |
+| `--enable` | 启用状态 `on` / `off` |
+| `--display-tip` | 是否显示提示语 `on` / `off` |
+
+只提交显式给出的项：命令先读回现有配置，合并改动后整份保存，再回读比对；未给出的项保持原值。
+
+## 修改字段级覆盖
+
+```bash
+# 固定目录
+e10-cli form attachment-setting set <appId> <objId> \
+  --field <附件字段> --upload-mode fixed --upload-dir <目录ID>
+
+# 选项关联：上传目录跟随某个单选/下拉字段
+e10-cli form attachment-setting set <appId> <objId> \
+  --field <附件字段> --upload-mode option --option-field <选项字段>
+
+# 字段级的新建方式 / 存储位置 / 上传格式
+e10-cli form attachment-setting set <appId> <objId> \
+  --field <附件字段> --doc-dir <目录ID> --doc-types WORD,markdown --formats @image
+```
+
+- `--field` 给了才是字段级覆盖；不给就是通用配置。
+- 固定目录必须同时给 `--upload-dir`；选项关联必须同时给 `--option-field`。
+- 字段级只写给出的项，未给出的项保持继承通用。
+- `--max-size` / `--enable` / `--display-tip` 当前只支持通用配置。
+
+## 查询目录与新建方式
+
+```bash
+# 列出可用文档目录（系统知识库 + 公司/私有知识库）
+e10-cli form attachment-setting folders
+e10-cli form attachment-setting folders --search 合同
+
+# 列出新建方式可选类型
+e10-cli form attachment-setting doc-types
+```
+
+`folders` 输出目录 ID、标题和类型；`--upload-dir` / `--doc-dir` 可以直接写 ID，也可以写唯一名称或路径。名称匹配到多个时命令会报错并要求改用 ID。
+
+## 注意事项
+
+1. **目录 ID 是长数字**，按字符串处理，不要转成 Number。
+2. **读回形状与写入形状不同**：读回的上传目录只在 `folderIdBrowserValue[0]` 里，写报文才带顶层 `folderId`；命令内部会补齐，不要手工拼报文。
+3. **保存顺序**：先字段级列表，再通用配置；两条都成功后再回读校验。
+4. **字段级覆盖优先于通用配置**：字段级把上传目录设成固定目录但没选具体目录，会覆盖掉通用的有效目录。
+5. 命令在保存后会逐项回读；回读不一致会直接报错，不会静默成功。