weaver-e10-builder 1.1.5 → 1.1.7

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

@@ -1,464 +1,214 @@
-# 新建 Ebuilder 表单
+# 新建 EBuilder 表单
 
-通过 `e10-cli form create` 创建表单。
+通过 `e10-cli form create` 在 EBuilder 应用中创建表单。本指南说明从需求整理、`fields.json` 编写到建后配置的完整顺序；字段参数和布局样表的详细规则按需读取专题参考。
 
-建表自带默认台账；方案要求同一表单的普通列表时，查询 `form list-view <objId> <appId>` 并复用，名称略有差异也不另建。默认保留名称，记录实际 listId，详见[视图指南](guide-form-view.md)。
+## 标准创建流程
 
-> **重要**：字段定义一次性写全（含选项、默认值等）。不要先建空表再逐个 `add-field` —— add-field 只用于罕见补救。
-
-## 基本用法
-
-```bash
-e10-cli form create {应用ID} "表单名" --fields @fields.json
-# 默认不加菜单；要入口传 --menu（台账菜单 VIEWPORT，指向数据列表页）。漏加可用 `e10-cli menu add-table <appId> <objId>` 补
-```
-
-不传 `--fields` 时使用默认字段：名称(Text)、数量(Number)、日期(Date)、状态(Select)。
-
-### 布局类型（流式/表格式）
+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 {应用ID} "表单名" --fields @fields.json --layout FLOW   # 流式
-e10-cli form create {应用ID} "表单名" --fields @fields.json --layout EXCEL  # 表格（缺省）
+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
 ```
 
-| 要点 | 说明 |
-|------|------|
-| **布局类型建表时定死** | 平台建表后不可切换（流式↔表格式），只能创建时选。`--layout` 写在建表请求里（`layoutType` + `isAdvance:false`） |
-| **流式模板** | FLOW 用特殊模板 `820000000000000001`（非通用版本 id，跨环境一致）；CLI 自动配 |
-| 缺省 | 不传 `--layout` 时缺省 `EXCEL`（表格，行为不变） |
-
-> **⚠ 建表前必须和用户确认布局类型**：表单要**流式(FLOW)** 还是**表格式(EXCEL)**——平台建表后不可切换，只能创建时定死。需求文档/截图没明确表态时，不要默认 EXCEL 直接建，先向用户问清。流程表单同理（`workflow create-workflow --layout FLOW|EXCEL`）。
-
-### 从需求文档识别完整布局样表
-
-识别发生在读取需求文档之后、编写 `plan.md` 之前。先完成字段定义识别，再扫描布局章节；不要等到创建表单时才回头猜布局。
-
-出现下列任一特征时，将表格作为“布局样表”候选，而不是普通字段清单：
-
-- 上下文出现“表格式布局”“Excel样式”“按照如下布局构建”等说明；
-- 单元格包含 `[字段名]`，或呈现“标签｜字段｜标签｜字段”的交替结构；
-- 存在独占行的表单标题、分组标题、有意义的空白单元格或同一行多个字段；
-- 表格描述字段摆放位置，而不是“字段名称/字段类型/字段说明”的重复记录。
-
-逐行识别单元格角色：表单标题、分组标题、字段标签、字段控件、空白占位。字段控件后的必填、只读、金额大写等归字段显示属性；条件式必填/隐藏归显隐联动；字段比较归校验；公式归字段公式。空白单元格和同排关系属于布局信息，不能丢弃。
+需要同时生成台账菜单入口时，在创建命令中增加 `--menu`；建成后也可使用 `menu add-table <appId> <objId>` 添加。默认台账视图与应用菜单入口是两个资源。
 
-优先读取 `e10-cli docx read` 生成的 Markdown 表格。只有 Markdown 不能确定合并单元格或跨列范围时，才查看原 DOCX 对应页面或表格结构；不能确定时在 plan 标“待确认”，不得自行猜测。
+## 各阶段配置范围
 
-识别结果必须双份落入 plan：
-
-1. “字段定义”保存字段类型和可直接创建的字段属性；
-2. 紧随其后的“表单布局蓝图”逐行保存标题、分组、字段同排关系、顺序、空白占位、跨列信息及原文说明。
-
-`group`、`singleRow` 和字段数组顺序只是字段级布局提示，不能替代完整布局蓝图。生成 plan 后做一次轻量核对：原样表每个 `[字段]` 均同时出现在字段定义和布局蓝图中，且同排关系、分组顺序和原文属性没有遗漏。
+| 阶段 | 配置内容 |
+|---|---|
+| 需求与 plan | 表单名称、字段类型、顺序、明细结构、FLOW/EXCEL、布局蓝图及外围配置 |
+| `fields.json` | 字段、选项、默认值、精度、日期格式、关联、公式、明细、分组和显示属性 |
+| `form create` | 表单主体、字段、明细、布局、基础查看权限、默认台账及可选菜单 |
+| 建成后 | 字段多语言、联动、查重、进一步权限、视图名称与列、筛选、按钮及关联页签 |
+| 完成核对 | `objId`、`formId`、`listId`、字段结构和布局结果 |
 
-“表单布局蓝图”只负责完整保存需求并指导后续执行，不作为单独的人工审核项，也不增加额外确认步骤。CLI 不直接消费该表格，也不需要额外生成 `.layout-plans/*.layout.json`。进入执行阶段后，根据蓝图把字段顺序、`group`、`singleRow`、`required`、`readOnly` 等可创建信息写入 `fields.json`，使用 `form create --fields @fields.json --layout EXCEL` 一次创建并初始化；公式、联动和校验仍走各自命令。创建结果与蓝图有局部位置差异时，再按实际布局使用 `form layout read/move/set-read-only/set-required` 等现有能力处理，不预设固定转换文件，也不修改已经可用的 EXCEL 初始化逻辑。
+## 建表前整理需求
 
-## 自定义字段
+### 布局类型
 
 ```bash
-e10-cli form create {应用ID} "表单名" --fields @fields.json
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
 ```
 
-字段 JSON 格式（保存在 `fields.json` 中）：
+- `FLOW`：流式布局。
+- `EXCEL`：表格式布局，也是 CLI 缺省值。
+- 需求未明确且布局选择会影响结果时，建表前向用户确认。
+- 需求提供完整表格、合并单元格、分组标题、标签与字段交替排布时，按布局样表处理，详见 [表单布局规划](guide-form-layout-planning.md)。
+
+### 字段定义
+
+字段按照需求顺序写入 `fields.json`。主表字段在前，`DetailTable` 明细表放在数组末尾。
 
 ```json
 [
-  {"componentKey": "Text", "fieldName": "客户名称"},
-  {"componentKey": "Phone", "fieldName": "联系电话"},
-  {"componentKey": "Mobile", "fieldName": "手机号码"},
-  {"componentKey": "IDCard", "fieldName": "身份证号"},
-  {"componentKey": "Employee", "fieldName": "负责人"},
-  {"componentKey": "Department", "fieldName": "所属部门"},
-  {"componentKey": "Date", "fieldName": "签订日期"},
-  {"componentKey": "Money", "fieldName": "合同金额"},
-  {"componentKey": "Select", "fieldName": "客户等级", "fieldOptions": [{"name":"A级"},{"name":"B级"}]}
+  {"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}
+  ]}
 ]
 ```
 
-> **明细表（DetailTable）放最下面**：主表字段在前、明细表放数组末尾。布局/铺列按数组顺序处理，明细在前会打乱主表字段排布。
-> ```json
-> [
->   {"componentKey":"Text","fieldName":"合同名称"},
->   {"componentKey":"Money","fieldName":"合同金额"},
->   {"componentKey":"DetailTable","fieldName":"付款明细","formFields":[
->     {"componentKey":"Text","fieldName":"付款条件"},
->     {"componentKey":"Number","fieldName":"付款金额","precision":2}
->   ]}
-> ]
-> ```
+常用类型包括 `Text`、`TextArea`、`Number`、`Money`、`Date`、`DateTime`、`DateRange`、`Select`、`Employee`、`Department`、`FileComponent`、`EBuilder`、`Browser`、`Flow` 和 `DetailTable`。完整类型、关联码表及各类型属性见 [表单字段定义参考](ref-form-fields.md)。
 
-> **`valueKey` 可选但必须是数字**：Select/RadioBox/CheckBox 的 `fieldOptions` 只需写 `name`，`valueKey` 由 CLI 自动生成（雪花号）。也可手动指定**数字** valueKey（如 `"valueKey":"100"`，推荐用业务语义编码，数据记录与下游引用存的就是它）；**非数字会被 CLI 直接报错拒绝**（平台规范+下游条件/公式按数字处理）。
+## 常用字段属性
 
-**选项预设模板**（Select 专有）：多个表单共用一套下拉选项时，用 `optionTemplate` 引用模板而不是内联 `fieldOptions`。模板先建（`e10-cli form option-template create <名称> --options @<json>`），fields.json 里写名称（或模板 ID）：
-
-```json
-{"componentKey":"Select","fieldName":"优先级","optionTemplate":"优先级模板"}
-```
+| 属性 | 作用 |
+|---|---|
+| `required:true` | 字段必填 |
+| `readOnly:true` | 禁止手工编辑 |
+| `hidden:true` | 布局中隐藏，字段仍可参与计算 |
+| `singleRow:true` | 独占一行 |
+| `group:"基本信息"` | 放入指定字段分组 |
+| `multiple:true` | 支持多选的字段设置为多选 |
+| `maxLen:500` | 文本最大长度 |
+| `precision:2` | 数字或金额小数位 |
+| `defaultValue` | 字段默认值 |
 
-- 选项不落字段上（`options:[]`），平台渲染时按模板拉取；**模板改选项，所有引用字段跟着变**
-- 与 `fieldOptions` 互斥：同字段两个都写时 `optionTemplate` 被忽略（模板引用只在无内联选项时绑定）
-- 数据记录存模板选项的 valueKey（`fieldOptionId`），与内联选项一致；`form data add` 直接填选项名或 valueKey
-- 模板管理：`list`（`--system` 看内置）/ `read` / `copy` / `delete`；已有字段补绑用 `form add-field` 加不了——对已有 Select 改绑模板需在字段管理页面操作
+### 字段分组
 
-**字段读写属性**：`required` 必填 / `readOnly` 只读 / `hidden` 隐藏（字段不展示但保留参与计算，如运算/派生字段）：
-```json
-{"componentKey":"Number","fieldName":"请假时长(小时)","readOnly":true,"hidden":true},
-{"componentKey":"FileComponent","fieldName":"证明材料","required":true}
-```
-> `hidden:true` → 布局属性"显示"取消（show:false）；`readOnly` → 布局"禁止手工编辑"；`required` → 布局"必填"。这些是**布局属性**（优先级：字段在布局中的设置 > 字段管理中字段设置 > 模块默认），建表时一次配好，勿依赖平台默认值。
+以需求为准：只有需求明确要求字段分组时，才在 `fields.json` 中设置 `group`；需求未要求时保持不分组。
 
-**独占一行**：字段写 `"singleRow":true` → 该字段整行显示（对齐平台布局 singleRow 属性），其余字段仍两列：
-```json
-{"componentKey":"Text","fieldName":"项目名称","singleRow":true},
-{"componentKey":"TextArea","fieldName":"项目描述","singleRow":true},
-{"componentKey":"Text","fieldName":"负责人"}
-```
-> 不加 `singleRow` 的普通字段两列排布。明细表 / 落单字段（奇数最后一个）本来就独占一行。add-field 加字段可用 `--single-row`。
->
-> **规划阶段就该判断，勿默认全两列**：长文本/备注/项目描述/地址/富文本/长说明 → 默认 `singleRow:true`（两列挤一起难看）；标题类（项目名称、合同名称）也常独占。AI 常漏标 singleRow，建表前过一遍字段语义。
-
-**字段分组**（按表单结构判断，**勿默认全平铺**）：6+ 字段、或字段有明显逻辑分段（基本信息/合同信息/系统设置/付款信息…）→ 按 `group` 名分组，建表时自动生成折叠容器，字段收进对应分组。用户没明确要求时，按字段语义自然分组（别每张表都加，也别 3 字段小表加）。建表时 fields.json 一并写 `group`，勿留到建后用 `form group` 补（那是对齐补救手段）。
 ```json
 [
-  {"componentKey":"Text","fieldName":"客户名称","group":"基本信息"},
-  {"componentKey":"Phone","fieldName":"联系电话","group":"基本信息"},
-  {"componentKey":"Select","fieldName":"客户状态","group":"基本信息","fieldOptions":[{"name":"潜在"},{"name":"正式"}]},
-  {"componentKey":"Date","fieldName":"签订日期"},
-  {"componentKey":"TextArea","fieldName":"备注"}
+  {"componentKey":"Text","fieldName":"项目名称","group":"基本信息","required":true},
+  {"componentKey":"Employee","fieldName":"负责人","group":"基本信息"},
+  {"componentKey":"Number","fieldName":"项目金额","group":"财务信息","precision":2}
 ]
 ```
-> 不写 `group` 的字段归「未分组」平铺在分组之后。分组内字段**默认两列**（一行两个），要独占一行写 `"singleRow":true`。明细表不参与分组（独立区块）。EXCEL/FLOW 布局都按 singleRow 控制两列/整行（对齐浏览器 initLayout payload）。
-
-
-**Number/Money 精度**：用 `precision` 指定小数位数（缺省 Number=0 整数、Money=2）：
-```json
-{"componentKey":"Number","fieldName":"单价","precision":2},
-{"componentKey":"Money","fieldName":"金额"}
-```
-> 不设 precision 时 Number 建出来是整数（pointSize=0）、Money 是 2 位小数。主表/明细子字段都支持。
-> **Number 与 Money 是两种类型**：Number=纯数字（默认无千分位/大写），Money=金额（千分位默认开）。字段名叫"金额"不代表必须用 Money 类型——类型由方案数据语义定，名称只是展示文本。
-
-**Number/Money 千分位与大写**（按需开启，**由字段类型决定默认，与字段名无关**）：
-`"delimiter":true` 开千分位（**Number 默认关、Money 默认开**，`"delimiter":false` 关 Money 的）；`"capital":true` 开大写金额显示（`isCapital` + `capitalFormat onlyUpperCase`）：
-```json
-{"componentKey":"Number","fieldName":"费用金额","precision":2},
-{"componentKey":"Money","fieldName":"费用金额"}
-```
-> - **类型决定默认，不是字段名**：上面两个字段**同名**"费用金额"，但前者是 Number（千分位/大写关）、后者是 Money（千分位默认开）。判断看 `componentKey`，不看字段名。
-> - **千分位/大写是 opt-in**：只在方案文档**明确要求**"显示千分位/金额大写"时才加 `delimiter`/`capital`，不要因字段名含"金额/费用/收款"就自动套用。
-> - **Number 类型的金额语义字段缺省就是裸数字**：`{"componentKey":"Number","fieldName":"项目费用","precision":2}` —— 不带 delimiter/capital，这是正确写法。
-> - add-field 用 `--delimiter` / `--no-delimiter` / `--capital`。
 
-**Number 百分比显示**：`"percent":true` → `numberType=percentage`（缺省 pointSize=1，可再配 `precision`）：
-```json
-{"componentKey":"Number","fieldName":"付款比例","percent":true,"precision":1}
-```
-> ⚠️ **百分比字段的公式要 ×100**：平台百分比字段是「数值直接拼 %」（不自动 ×100）。如 付款比例=付款金额/项目金额，10000/20000=0.5，会显示「**0.5%**」而非 50%。公式必须 ×100：
-> ```json
-> {"componentKey":"Number","fieldName":"付款比例","percent":true,"precision":1,"formula":"{付款信息.付款金额}/{主表.项目金额}*100"}
-> ```
-> 这样 0.5×100=50 → 显示「50%」。累加校验「比例累加=100%」也基于百分比数（50+50=100），不是比值。
+同名 `group` 的字段进入同一个分组。分组内字段按字段顺序排列，需要整行展示的字段增加 `singleRow:true`。已有表单补充分组时使用：
 
-**Number/Money 默认值**：`"defaultValue":1000` → 存 `content` + `isDefault:true`（如 工时单价默认 1000 元）：
-```json
-{"componentKey":"Number","fieldName":"工时单价","defaultValue":1000}
+```bash
+e10-cli form group <objId> <appId> --groups '{"基本信息":["项目名称","负责人"]}'
 ```
-> 平台机制：设默认值必须连 `isDelimiter/stepMode/step/isCapital` 一起发，否则默认值不落库（CLI 已处理）。
-> 单位没有独立字段属性 —— 显示单位直接写在字段名里，如 `"fieldName":"工时数量（天）"`。
-> **台账列单位显示**（绕法）：平台字段无单位属性，但台账列可配显示后缀，用 `form list-unit <objId> <appId> <listId> <fieldId> "（元）"` 设置（走列表列配置 `showTrans.ruleConfig.suffix`，极简结构平台即接受）。
 
-## 支持的字段类型
+### 日期区间
 
-| componentKey | 说明 |
-|---|---|
-| Text | 文本 |
-| TextArea | 多行文本 |
-| Email | 邮箱 |
-| Phone | 电话 |
-| Mobile | 手机 |
-| IDCard | 身份证号 |
-| Number | 数字（千分位/大写默认关，按需开；precision 缺省 0 整数） |
-| Money | 金额（千分位默认开，大写按需开；precision 缺省 2） |
-| Date | 日期（默认精度**年月日**，format `yyyy-MM-dd`；要带时间用 `"format"` 覆盖） |
-| DateTime | 日期-时间（`Date` 的别名，默认带 时:分，format `yyyy-MM-dd HH:mm` 不含秒） |
-| Employee | 人员选择 |
-| Department | 部门选择 |
-| FileComponent | 附件上传（**注意是 FileComponent 不是 File**） |
-| Select | 下拉选择 |
-| RadioBox | 单选按钮 |
-| CheckBox | 多选按钮 |
-| EInvoice | 电子发票（创建后无需额外配置，平台自动处理） |
-| AudioRecord | 语音（极简字段，无特殊配置。注意不是 FileComponent 附件） |
-| VideoRecord | 视频（极简字段，无特殊配置） |
-| DetailTable | 明细表 |
-| DateRange | 日期区间 |
-| Time | 时间 |
-| EBuilder | 关联 EB 表单（见下节） |
-| Flow | **浏览-流程**（关联流程，如"数据来源"来自项目立项流程；`--sform-id` 为目标流程绑定的表单 objId，点击自动跳流程）。**form create 的 fields.json 直接写 `"sformId":"<流程表单objId>"` 即可**（建表后 CLI 自动绑 sformId/relateExt，与 EBuilder 同机制）；add-field 用 `--sform-id`。⚠ sformId 必须是**流程绑定的表单 objId**（不是 workflowId），即"仅允许关联某流程"=Flow 字段 + sformId 指向该流程的表单 |
-
-正常情况下，人相关的 都是用Employee
-Time 的格式固定为 HH:mm:ss 如 17:00:00
-> **人员/部门默认值**：默认**不配默认值**（没写就没有）。要默认当前用户/部门写 `"defaultValue": true`（建表时自动配 `defaultExtend`）。
-> **Date/DateTime 精度与默认值**：默认**不填默认值**。要带时间用 `"format"` 覆盖精度（如 `"format":"yyyy-MM-dd HH:mm"`、`yyyy-MM-dd HH:mm:ss`）；要配动态当天默认值写 `"defaultValue": true`（建表时自动配 `defaultExtend`）。add-field 加字段用 `--format` 覆盖精度。
-> ```json
-> {"componentKey":"Date","fieldName":"签订日期"},
-> {"componentKey":"Date","fieldName":"精确到秒","format":"yyyy-MM-dd HH:mm:ss"},
-> {"componentKey":"Date","fieldName":"默认今天","defaultValue":true}
-> ```
->
-> **日期限制**：A 字段**最早不得早于** B 字段写 `"minField":"B字段名"`，**最晚不得晚于**写 `"maxField":"B字段名"`（对齐平台 `min/max.dateField`，自动解析 B 的 fieldId）。**子表字段同样支持**，可指向主表字段或同子表字段。add-field 用 `--min-field` / `--max-field`。
-> ```json
-> {"componentKey":"Date","fieldName":"计划开始日期"},
-> {"componentKey":"Date","fieldName":"计划结束日期","minField":"计划开始日期"},
-> {"componentKey":"Date","fieldName":"完成日期","maxField":"计划结束日期"},
-> {"componentKey":"DetailTable","fieldName":"行程明细","formFields":[
->   {"componentKey":"Date","fieldName":"明细开始日期","minField":"计划开始日期"},
->   {"componentKey":"Date","fieldName":"明细结束日期","minField":"明细开始日期"}
-> ]}
-> ```
-
-**多选**：人员(Employee)/部门(Department)/关联ebuilder(EBuilder)/浏览(Browser)/下拉(Select) 默认单选，要选多个加 `"multiple": true`：
-```json
-{"componentKey":"Employee","fieldName":"参与人员","multiple":true},
-{"componentKey":"Department","fieldName":"会签部门","multiple":true},
-{"componentKey":"EBuilder","fieldName":"关联客户","sformId":"<目标表单objId>","dataTitle":"name","multiple":true},
-{"componentKey":"Select","fieldName":"标签","multiple":true,"fieldOptions":[{"name":"A"},{"name":"B"}]}
-```
-> 不写 `multiple` 即单选。多选 EBuilder 选中多条记录，字段存数组值。**下拉 Select 多选 = 独立类型 `SelectMultiple`**（CLI 自动转，非 Select+开关）。
+字段本身包含开始与结束含义，如“项目周期、合同有效期、请假时间、活动时间”，优先使用 `DateRange`。明确要求两个独立字段，或开始、结束需要分别参与公式和联动时，再拆成两个日期字段。
 
-**文本最大长度**：Text 缺省 100、TextArea 缺省 4000，用 `"maxLen"` 覆盖（主表 + 明细子字段都支持）：
 ```json
-{"componentKey":"Text","fieldName":"备注","maxLen":500},
-{"componentKey":"TextArea","fieldName":"详情","maxLen":8000}
+{"componentKey":"DateRange","fieldName":"项目周期","format":"yyyy-MM-dd"}
 ```
-> add-field 用 `--max-len <n>`。
-
-## EBuilder 关联字段
 
-关联其他表单记录（下拉选择/搜索），选中后展示目标表单的某个字段值。
+### 选项和多选
 
 ```json
-{
-  "componentKey": "EBuilder",
-  "fieldName": "关联客户",
-  "sformId": "1296220571782152199",
-  "dataTitle": "客户名称"
-}
+{"componentKey":"Select","fieldName":"状态","fieldOptions":[{"name":"启用"},{"name":"停用"}]},
+{"componentKey":"Employee","fieldName":"项目成员","multiple":true}
 ```
 
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `sformId` | 是 | **目标表单的 objId**（不是 appId/formId） |
-| `dataTitle` | 是 | 目标表单中用于显示的字段名，选中记录后展示该字段值。传 `"name"`（或不写）默认取目标表**字段名含"名称"**的字段（如 客户名称/类型名称），无则取第一个业务字段 |
-| `displayColumns` | 否 | **关联浏览弹窗显示列**（字段名列表）。缺省自动用目标表业务字段**最多 5 个**（去系统字段），建好即生效；要指定用这个 |
-
-> **关联浏览弹窗显示列默认自动配好**：`form create` 建表和 `form add-field` 加 EBuilder 字段时都自动写入 `ffDisplayColumns` = 目标表**业务字段前 5 个**（排除创建者/创建时间/数据ID等系统字段），浏览弹窗直接生效。`fields.json` 里显式写 `displayColumns` 指定列不受 5 个限制。事后想改可用 `e10-cli form ebuilder-columns <objId> <appId> <fieldId> <列...>` 或 `--clear` 清空。
+`Select`、`RadioBox`、`CheckBox` 可在 `fieldOptions` 中定义选项。人员、部门、EBuilder、Browser 和 Select 等支持按字段能力设置多选。共享选项可使用 `optionTemplate`；详细结构见 [表单字段定义参考](ref-form-fields.md)。
 
-### EBuilder + 值带出（relateFrom）
+### 关联字段
 
-选关联记录后自动带出其他字段值（如选客户→带出联系人/地址）：
+EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
 
 ```json
 {
-  "componentKey": "Text",
-  "fieldName": "联系人",
-  "relateFrom": { "ebuilderField": "关联客户", "sourceFieldId": "1296220571782152194" }
+  "componentKey":"EBuilder",
+  "fieldName":"关联客户",
+  "sformId":"<目标表单objId>",
+  "dataTitle":"客户名称",
+  "displayColumns":["客户名称","客户类型"]
 }
 ```
 
-- `ebuilderField`：本表单中的 EBuilder 字段名
-- `sourceFieldId`：目标表单中要复制值的字段 **fieldId（数字 ID）**。⚠️ **不能传字段名**，用 `form read --app-id` 获取
+`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见 [表单字段定义参考](ref-form-fields.md)；关联数据过滤和范围分别见 [EBuilder 过滤](guide-ebuilder-filter.md) 与 [关联浏览数据范围](guide-ebuilder-scope.md)。
 
-创建后补配值带出：`e10-cli form edit-field ... --relate-from <EBuilder字段名> --relate-from-source <源字段fieldId>`
-> ⚠️ `--relate-from-source` 必须传字段的**数字 fieldId**，不能传字段名。
+### 明细表与二级明细
 
-## Select/RadioBox/CheckBox 带选项
-
-```json
-{
-  "componentKey": "Select",
-  "fieldName": "客户等级",
-  "fieldOptions": [
-    {"name": "A级"},
-    {"name": "B级"},
-    {"name": "C级"}
-  ]
-}
-```
-
-## 明细表 DetailTable
-
-明细表包含嵌套子字段，子字段写在其 `formFields` 数组内：
-
-```json
-{
-  "componentKey": "DetailTable",
-  "fieldName": "订单明细",
-  "formFields": [
-    {"componentKey": "Text", "fieldName": "商品名称"},
-    {"componentKey": "Number", "fieldName": "数量"},
-    {"componentKey": "Number", "fieldName": "单价"},
-    {"componentKey": "Date", "fieldName": "交付日期"}
-  ]
-}
-```
-
-### 二级明细表
-
-二级明细不是在明细表内再创建一张表，而是让当前明细表关联同一主表下的另一张明细表。`subForm` 和 `subField` 均可写名称；CLI 会解析为 ID、校验不能关联自身，并在保存后回读确认。
+明细字段写入 `DetailTable.formFields`。二级明细通过当前明细表关联同一主表下的另一张明细表：
 
 ```json
 [
-  {"componentKey":"DetailTable","fieldName":"明细表2","formFields":[
-    {"componentKey":"Text","fieldName":"名称"}
+  {"componentKey":"DetailTable","fieldName":"任务明细","formFields":[
+    {"componentKey":"Text","fieldName":"任务名称"}
   ]},
-  {"componentKey":"DetailTable","fieldName":"明细表3","enableSubDetail":true,"defaultExpandRow":true,
-   "subDetailConfig":[{"subForm":"明细表2","subField":"名称"}],"formFields":[
-    {"componentKey":"Text","fieldName":"说明"}
+  {"componentKey":"DetailTable","fieldName":"工时明细","enableSubDetail":true,
+   "subDetailConfig":[{"subForm":"任务明细","subField":"任务名称"}],"formFields":[
+    {"componentKey":"Number","fieldName":"工时","precision":2}
   ]}
 ]
 ```
 
-平台实测默认配置为 `parentMark=rowId`、`displayMode=inside`、`filterType=single`；通常不必显式填写。已有表单可用 `form detail-table sub-detail set` 配置，用 `disable` 暂停但保留关系，用 `clear` 清除关系。
+已有表单使用 `form detail-table` 查询或调整二级明细关系。
 
-子字段也支持带选项的类型。
+### 字段公式
 
-## 复杂编号（年份编号）：serial-mark
+可在目标字段中写 `formula`，由创建流程完成公式创建和字段绑定：
 
-编号（如 `XM-2026-001`、`YF-2026-0001`）走**复杂编号**机制：在任意文本字段上配编码段，`form serial-mark set --segments` 用 JSON 数组组合任意规则，**数组顺序即编号拼接顺序**，一条命令配完（含代字），重跑全量替换不累积。
-
-### 配置：`set --segments`
-
-```bash
-e10-cli form serial-mark set <objId> <appId> <字段ID> --segments @segments.json
-# 也支持内联 JSON：--segments '[{"type":"fixed","value":"XM-"},{"type":"serial","digits":4}]'
-```
-
-segments.json 示例（生成如 `YF-2026-0001`，按年单独流水）：
 ```json
-[
-  {"type":"field","fieldId":"<选择框字段ID>","shortName":{"研发":"YF","实施":"SS","运维":"YW","咨询":"ZX"}},
-  {"type":"fixed","value":"-"},
-  {"type":"year","format":"four","alone":true},
-  {"type":"serial","digits":4,"zero":true}
-]
+{"componentKey":"Number","fieldName":"项目收益","formula":"{主表.已收款}-{主表.项目费用}"}
 ```
 
-### 段类型参考（任意组合，数组顺序决定拼接顺序）
-
-| type | 含义 | 属性 | 平台 markFieldType |
-|------|------|------|-------------------|
-| `fixed` | 固定内容 | `value`（文本，如 `"XM-"`/`"-"`） | FIX_CONTEXT |
-| `year` | 年份 | `format`：`four`(四位 2026,缺省)/`two`(两位 26)；`alone`：true 按年单独流水(缺省 true) | DATE_YEAR |
-| `serial` | 流水号 | `digits`（位数，如 4→0001）；`zero`：true 补零(缺省)/false 不补零；`alone`：true 机构单独流水 | SERIAL_NUMBER |
-| `field` | 表单字段值 | `fieldId`（取值字段）；`alone`：true 机构单独流水；`shortName`：inline 代字映射（选项名→简称，见下） | FORM_FIELD |
-| `system` | 系统字段 | `systemField`：`creator`(创建人)/`creator-dept`(创建人所属部门,自动部门代字)；`alone` | SYSTEM_FIELD |
-| `date` | 日期 | `format`：`yyyy`/`yyyyMM`/`yyyyMMdd`；`source`：`current`(当前)/`<字段ID>`；`alone` | DATE |
-
-> - **任意规则直接组合**：把规则拆成段，按拼接顺序写入数组即可。如 `项目类型-年份-4位流水` = field + fixed("-") + year + serial
-> - **代字自动**：field 段 markExtend=103（选项值取简称）、system creator-dept markExtend=101（部门取代字），无需手填
-> - **inline 代字**：field 段带 `shortName` 自动配置代字映射，无需再跑 short-name
-> - **按年单独流水**：year 段 `alone:true`（DATE_YEAR seqAlone，流水号每年重新计数）
-> - **全量替换**：重跑时旧段进 delDefIds 清除，markDefId 复用，绑定/代字不丢失
-> - 段对象来自 `getMarkFieldAddData` 预生成；markDefId 来自 `saveSingleMarkDef`；已有绑定时复用持久化 markDef（getMarkContext 优先用绑定记录的 targetId）
-
-### 增量调整（可选）
-
-`set` 是全量重建；需在已有编号上追加/微调单段用 `add-segment`，单独查/改代字用 `short-name`：
+公式表达式、明细汇总和函数格式见 [字段公式函数参考](guide-form-formula-functions.md)。复杂编号属于建后配置，见 [表单复杂编号](guide-form-serial-mark.md)。
 
-```bash
-e10-cli form serial-mark add-segment <objId> <appId> <绑定字段ID> --type field --field-id <取值字段ID> [--position 0]
-e10-cli form serial-mark add-segment <objId> <appId> <绑定字段ID> --type system --system-field creator-dept
-e10-cli form serial-mark short-name list <objId> <appId> <选择框字段ID>
-e10-cli form serial-mark short-name set <objId> <appId> <选择框字段ID> --map '{"研发":"YF","实施":"SS"}'
-```
-add-segment 段类型与 set 一致（fixed/year/serial/field/system/date），`--position` 插入位置（缺省追加末尾）。
-
-### 查询与解除
+## 执行创建
 
 ```bash
-e10-cli form serial-mark read <objId> <appId>           # 查看编号配置（绑定字段+组成段+代字）
-e10-cli form serial-mark fields <objId> <appId>          # 查可作为编号目标的字段
-e10-cli form serial-mark clear <objId> <appId> <字段ID>  # 解除编号绑定
+e10-cli form create <appId> "采购合同" --fields @fields.json --layout EXCEL
 ```
 
-**注意**：
-- 被编码字段平台自动设为只读（编号自动生成，不可手工改）
-- 流水号按 `前缀+年份+流水` 组合查重累进
-- 机制：markField 复杂编号（getEbMarkTargetId → getMarkSetForm → saveSingleMarkDef → saveOrUpdate → saveMarkField）；段对象必须来自 getMarkFieldAddData 预生成；已有绑定时复用持久化 markDef，段/代字不丢失
-
-## 日期区间 DateRange
-
-日期区间字段**必须**指定精度格式，通过 `format` 配置：
-
-```json
-{
-  "componentKey": "DateRange",
-  "fieldName": "出差时间",
-  "format": "yyyy-MM-dd HH:mm"
-}
-```
+创建流程会依次完成表单主体、字段和明细、布局初始化、字段高级属性、关联关系、选项、公式、分组、基础查看权限及默认台账配置。传入 `--menu` 时同时添加台账菜单入口。
 
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `format` | 否 | 区间精度。缺省 `yyyy-MM-dd`（年-月-日）；到分钟写 `yyyy-MM-dd HH:mm`；到秒 `yyyy-MM-dd HH:mm:ss` |
-| `startPlaceholder` / `endPlaceholder` | 否 | 开始/结束控件占位符。缺省按 format 自动生成中文（如 `年-月-日 时:分`） |
+记录命令返回的：
 
-> **CLI 自动展开**：创建时无需手写 `start`/`end`/`rangeInterval`——CLI 会把该字段展开为平台要求的 3 字段结构（主字段 + 「(开始时间)」「(结束时间)」两个 DateComponent，各带独立 fieldId），这是之前报 `DateIntervalFieldDto.getEnd()==null` 的根因（缺了 end 组件）。
->
-> **事后补加**：`e10-cli form add-field <objId> <appId> "回程时间" DateRange --format "yyyy-MM-dd HH:mm"`
+- `objId`：EB 表单业务对象 ID，多数 `form` 命令使用它。
+- `formId`：底层表单 ID，布局和部分底层接口使用它。
+- `listId`：默认台账 ID，通过 `form list-view` 查询。
 
-## 字段公式（fields.json 的 formula 属性）
+## 建成后配置
 
-创建表单时直接给字段绑定计算公式，CLI 自动完成「创建公式 + 绑定字段」两步（字段配置会带上 `ffExpress`）：
+按需求执行，未提出的配置不额外增加：
 
-```json
-{
-  "componentKey": "Number",
-  "fieldName": "出差天数",
-  "formula": "DAYS({主表.出差时间(开始时间)},{主表.出差时间(结束时间)})"
-}
-```
+| 需求 | 命令或指南 |
+|---|---|
+| 字段中英文名称 | `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`）时，先以中文名称创建字段，再设置多语言：
 
-```json
-"formula": { "expression": "DAYS({主表.出差时间(开始时间)},{主表.出差时间(结束时间)})", "returnType": "Number" }
+```bash
+e10-cli form field-lang set <objId> <appId> <fieldId> --zh "项目" --en "project"
 ```
 
-| 要点 | 说明 |
-|------|------|
-| 表达式语法 | 与 `form formula set --expression` 一致，用 `{主表.字段名}` 引用主表字段、`{明细表名.字段名}` 引用**明细表**字段（如 `DAYS({行程明细.行程开始时间},{行程明细.行程结束时间})`）。**fields.json create 与 formula set 两条路径都支持明细引用** |
-| **明细列求和** | **`SUM({明细表名.字段})`** 可对明细表某列跨行求和（如 `SUM({付款信息.付款金额})`），生效。可配合 `workflow node validate` 做"明细累加=主表字段"校验 |
-| **日期差** | 两个日期相减**不直接支持**，要用平台函数 **`DAYS({主表.开始},{主表.结束})`** |
-| 返回类型 | 缺省 `Number`；文本/日期类用对象形式指定 |
-| 事后补加 | `e10-cli form formula set <objId> <appId> --expression "..." --target <fieldId>` |
-
-> **明细表子字段选项**：`DetailTable` 的 `formFields` 里的 `Select/RadioBox/CheckBox` 也支持 `fieldOptions`，CLI 会自动给子字段配置选项（创建时无需额外操作）。
+## 完成核对
 
-## 完整示例
+使用与本次需求直接相关的读取命令核对即可：
 
 ```bash
-e10-cli form create 1283840156707348480 "采购合同" --fields @fields.json
+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>
 ```
 
-`fields.json` 内容：
-
-```json
-[
-  {"componentKey":"Text","fieldName":"合同编号"},
-  {"componentKey":"Text","fieldName":"供应商名称"},
-  {"componentKey":"Employee","fieldName":"采购负责人"},
-  {"componentKey":"Date","fieldName":"签订日期"},
-  {"componentKey":"Money","fieldName":"总金额"},
-  {"componentKey":"Select","fieldName":"合同状态","fieldOptions":[{"name":"待审批"},{"name":"已审批"},{"name":"已完成"}]},
-  {"componentKey":"DetailTable","fieldName":"采购明细","formFields":[{"componentKey":"Text","fieldName":"物品名称"},{"componentKey":"Number","fieldName":"数量"},{"componentKey":"Number","fieldName":"单价"}]}
-]
-```
+重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。
 
-## 创建成功后
+## 专题参考
 
-- 返回表单 ID
-- 用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出字段信息（机器可读 JSON）
-- 在代码中通过 `formApi.js` 读写该表单数据
+- [表单字段定义参考](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-association.md

@@ -56,10 +56,11 @@ e10-cli form association create <objId> <appId> "全部合同" --view <viewId> -
 
 | 参数 | 含义 |
 |---|---|
-| `--layouts 显示` | `showLayout="0"`：打开显示布局，关闭编辑布局 |
+| `--layouts 显示` | `showLayout="0"`：显示布局 |
+| `--layouts 新建` | `showLayout="1"`：新建布局 |
 | `--layouts 编辑` | `showLayout="2"`：仅编辑布局 |
-| `--layouts 显示 编辑` | `showLayout="0,2"`：两种布局都显示 |
-| `--layouts none` | 两种布局均不显示 |
+| `--layouts 显示 新建 编辑` | `showLayout="0,1,2"`：三种布局都显示 |
+| `--layouts none` | 三种布局均不显示 |
 | `--terminals PC MOBILE` | 两端适用；可只传其中一个 |
 | `--enabled true/false` | 启用或停用页签 |
 
@@ -71,6 +72,8 @@ e10-cli form association update <objId> <appId> <associationId> --view <newViewI
 
 `update` 保留未指定属性以及原动作、权限条件和提示。布局、终端参数表示替换对应集合。修改绑定视图且已有映射时必须显式提供新映射（`[]` 可清空），避免原目标表字段被用于新视图。
 
+仅启用或停用页签时，`update --enabled true|false` 使用 `updateIsOpenById` 独立接口并通过列表回读状态，不整包保存关联配置。
+
 ## 修改和清空关联数据筛选
 
 ```bash