weaver-e10-builder 1.1.3 → 1.1.5

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

@@ -1,409 +1,464 @@
-# 新建 Ebuilder 表单
-
-通过 `e10-cli form create` 创建表单。
-
-建表自带默认台账；方案要求同一表单的普通列表时，查询 `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)。
-
-### 布局类型（流式/表格式）
-
-```bash
-e10-cli form create {应用ID} "表单名" --fields @fields.json --layout FLOW   # 流式
-e10-cli form create {应用ID} "表单名" --fields @fields.json --layout EXCEL  # 表格（缺省）
-```
-
-| 要点 | 说明 |
-|------|------|
-| **布局类型建表时定死** | 平台建表后不可切换（流式↔表格式），只能创建时选。`--layout` 写在建表请求里（`layoutType` + `isAdvance:false`） |
-| **流式模板** | FLOW 用特殊模板 `820000000000000001`（非通用版本 id，跨环境一致）；CLI 自动配 |
-| 缺省 | 不传 `--layout` 时缺省 `EXCEL`（表格，行为不变） |
-
-## 自定义字段
-
-```bash
-e10-cli form create {应用ID} "表单名" --fields @fields.json
-```
-
-字段 JSON 格式（保存在 `fields.json` 中）：
-
-```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级"}]}
-]
-```
-
-> **明细表（DetailTable）放最下面**：主表字段在前、明细表放数组末尾。布局/铺列按数组顺序处理，明细在前会打乱主表字段排布。
-> ```json
-> [
->   {"componentKey":"Text","fieldName":"合同名称"},
->   {"componentKey":"Money","fieldName":"合同金额"},
->   {"componentKey":"DetailTable","fieldName":"付款明细","formFields":[
->     {"componentKey":"Text","fieldName":"付款条件"},
->     {"componentKey":"Number","fieldName":"付款金额","precision":2}
->   ]}
-> ]
-> ```
-
-> **`valueKey` 可选**：Select/RadioBox/CheckBox 的 `fieldOptions` 只需写 `name`，`valueKey` 由 CLI 自动生成。也可以手动指定短码如 `"valueKey":"a"`。
-
-**字段读写属性**：`required` 必填 / `readOnly` 只读 / `hidden` 隐藏（字段不展示但保留参与计算，如运算/派生字段）：
-```json
-{"componentKey":"Number","fieldName":"请假时长(小时)","readOnly":true,"hidden":true},
-{"componentKey":"FileComponent","fieldName":"证明材料","required":true}
-```
-> `hidden:true` → 布局属性"显示"取消（show:false）；`readOnly` → 布局"禁止手工编辑"；`required` → 布局"必填"。这些是**布局属性**（优先级：字段在布局中的设置 > 字段管理中字段设置 > 模块默认），建表时一次配好，勿依赖平台默认值。
-
-**独占一行**：字段写 `"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":"备注"}
-]
-```
-> 不写 `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），不是比值。
-
-**Number/Money 默认值**：`"defaultValue":1000` → 存 `content` + `isDefault:true`（如 工时单价默认 1000 元）：
-```json
-{"componentKey":"Number","fieldName":"工时单价","defaultValue":1000}
-```
-> 平台机制：设默认值必须连 `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+开关）。
-
-**文本最大长度**：Text 缺省 100、TextArea 缺省 4000，用 `"maxLen"` 覆盖（主表 + 明细子字段都支持）：
-```json
-{"componentKey":"Text","fieldName":"备注","maxLen":500},
-{"componentKey":"TextArea","fieldName":"详情","maxLen":8000}
-```
-> add-field 用 `--max-len <n>`。
-
-## EBuilder 关联字段
-
-关联其他表单记录（下拉选择/搜索），选中后展示目标表单的某个字段值。
-
-```json
-{
-  "componentKey": "EBuilder",
-  "fieldName": "关联客户",
-  "sformId": "1296220571782152199",
-  "dataTitle": "客户名称"
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `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` 清空。
-
-### EBuilder + 值带出（relateFrom）
-
-选关联记录后自动带出其他字段值（如选客户→带出联系人/地址）：
-
-```json
-{
-  "componentKey": "Text",
-  "fieldName": "联系人",
-  "relateFrom": { "ebuilderField": "关联客户", "sourceFieldId": "1296220571782152194" }
-}
-```
-
-- `ebuilderField`：本表单中的 EBuilder 字段名
-- `sourceFieldId`：目标表单中要复制值的字段 **fieldId（数字 ID）**。⚠️ **不能传字段名**，用 `form read --app-id` 获取
-
-创建后补配值带出：`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": "交付日期"}
-  ]
-}
-```
-
-子字段也支持带选项的类型。
-
-## 复杂编号（年份编号）：serial-mark
-
-编号（如 `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}
-]
-```
-
-### 段类型参考（任意组合，数组顺序决定拼接顺序）
-
-| 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`：
-
-```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>  # 解除编号绑定
-```
-
-**注意**：
-- 被编码字段平台自动设为只读（编号自动生成，不可手工改）
-- 流水号按 `前缀+年份+流水` 组合查重累进
-- 机制：markField 复杂编号（getEbMarkTargetId → getMarkSetForm → saveSingleMarkDef → saveOrUpdate → saveMarkField）；段对象必须来自 getMarkFieldAddData 预生成；已有绑定时复用持久化 markDef，段/代字不丢失
-
-## 日期区间 DateRange
-
-日期区间字段**必须**指定精度格式，通过 `format` 配置：
-
-```json
-{
-  "componentKey": "DateRange",
-  "fieldName": "出差时间",
-  "format": "yyyy-MM-dd HH:mm"
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `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"`
-
-## 字段公式（fields.json 的 formula 属性）
-
-创建表单时直接给字段绑定计算公式，CLI 自动完成「创建公式 + 绑定字段」两步（字段配置会带上 `ffExpress`）：
-
-```json
-{
-  "componentKey": "Number",
-  "fieldName": "出差天数",
-  "formula": "DAYS({主表.出差时间(开始时间)},{主表.出差时间(结束时间)})"
-}
-```
-
-或对象形式指定返回类型：
-
-```json
-"formula": { "expression": "DAYS({主表.出差时间(开始时间)},{主表.出差时间(结束时间)})", "returnType": "Number" }
-```
-
-| 要点 | 说明 |
-|------|------|
-| 表达式语法 | 与 `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
-```
-
-`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":"单价"}]}
-]
-```
-
-## 创建成功后
-
-- 返回表单 ID
-- 用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出字段信息（机器可读 JSON）
-- 在代码中通过 `formApi.js` 读写该表单数据
+# 新建 Ebuilder 表单
+
+通过 `e10-cli form create` 创建表单。
+
+建表自带默认台账；方案要求同一表单的普通列表时，查询 `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)。
+
+### 布局类型（流式/表格式）
+
+```bash
+e10-cli form create {应用ID} "表单名" --fields @fields.json --layout FLOW   # 流式
+e10-cli form create {应用ID} "表单名" --fields @fields.json --layout EXCEL  # 表格（缺省）
+```
+
+| 要点 | 说明 |
+|------|------|
+| **布局类型建表时定死** | 平台建表后不可切换（流式↔表格式），只能创建时选。`--layout` 写在建表请求里（`layoutType` + `isAdvance:false`） |
+| **流式模板** | FLOW 用特殊模板 `820000000000000001`（非通用版本 id，跨环境一致）；CLI 自动配 |
+| 缺省 | 不传 `--layout` 时缺省 `EXCEL`（表格，行为不变） |
+
+> **⚠ 建表前必须和用户确认布局类型**：表单要**流式(FLOW)** 还是**表格式(EXCEL)**——平台建表后不可切换，只能创建时定死。需求文档/截图没明确表态时，不要默认 EXCEL 直接建，先向用户问清。流程表单同理（`workflow create-workflow --layout FLOW|EXCEL`）。
+
+### 从需求文档识别完整布局样表
+
+识别发生在读取需求文档之后、编写 `plan.md` 之前。先完成字段定义识别，再扫描布局章节；不要等到创建表单时才回头猜布局。
+
+出现下列任一特征时，将表格作为“布局样表”候选，而不是普通字段清单：
+
+- 上下文出现“表格式布局”“Excel样式”“按照如下布局构建”等说明；
+- 单元格包含 `[字段名]`，或呈现“标签｜字段｜标签｜字段”的交替结构；
+- 存在独占行的表单标题、分组标题、有意义的空白单元格或同一行多个字段；
+- 表格描述字段摆放位置，而不是“字段名称/字段类型/字段说明”的重复记录。
+
+逐行识别单元格角色：表单标题、分组标题、字段标签、字段控件、空白占位。字段控件后的必填、只读、金额大写等归字段显示属性；条件式必填/隐藏归显隐联动；字段比较归校验；公式归字段公式。空白单元格和同排关系属于布局信息，不能丢弃。
+
+优先读取 `e10-cli docx read` 生成的 Markdown 表格。只有 Markdown 不能确定合并单元格或跨列范围时，才查看原 DOCX 对应页面或表格结构；不能确定时在 plan 标“待确认”，不得自行猜测。
+
+识别结果必须双份落入 plan：
+
+1. “字段定义”保存字段类型和可直接创建的字段属性；
+2. 紧随其后的“表单布局蓝图”逐行保存标题、分组、字段同排关系、顺序、空白占位、跨列信息及原文说明。
+
+`group`、`singleRow` 和字段数组顺序只是字段级布局提示，不能替代完整布局蓝图。生成 plan 后做一次轻量核对：原样表每个 `[字段]` 均同时出现在字段定义和布局蓝图中，且同排关系、分组顺序和原文属性没有遗漏。
+
+“表单布局蓝图”只负责完整保存需求并指导后续执行，不作为单独的人工审核项，也不增加额外确认步骤。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
+```
+
+字段 JSON 格式（保存在 `fields.json` 中）：
+
+```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级"}]}
+]
+```
+
+> **明细表（DetailTable）放最下面**：主表字段在前、明细表放数组末尾。布局/铺列按数组顺序处理，明细在前会打乱主表字段排布。
+> ```json
+> [
+>   {"componentKey":"Text","fieldName":"合同名称"},
+>   {"componentKey":"Money","fieldName":"合同金额"},
+>   {"componentKey":"DetailTable","fieldName":"付款明细","formFields":[
+>     {"componentKey":"Text","fieldName":"付款条件"},
+>     {"componentKey":"Number","fieldName":"付款金额","precision":2}
+>   ]}
+> ]
+> ```
+
+> **`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":"优先级模板"}
+```
+
+- 选项不落字段上（`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` → 布局"必填"。这些是**布局属性**（优先级：字段在布局中的设置 > 字段管理中字段设置 > 模块默认），建表时一次配好，勿依赖平台默认值。
+
+**独占一行**：字段写 `"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":"备注"}
+]
+```
+> 不写 `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），不是比值。
+
+**Number/Money 默认值**：`"defaultValue":1000` → 存 `content` + `isDefault:true`（如 工时单价默认 1000 元）：
+```json
+{"componentKey":"Number","fieldName":"工时单价","defaultValue":1000}
+```
+> 平台机制：设默认值必须连 `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+开关）。
+
+**文本最大长度**：Text 缺省 100、TextArea 缺省 4000，用 `"maxLen"` 覆盖（主表 + 明细子字段都支持）：
+```json
+{"componentKey":"Text","fieldName":"备注","maxLen":500},
+{"componentKey":"TextArea","fieldName":"详情","maxLen":8000}
+```
+> add-field 用 `--max-len <n>`。
+
+## EBuilder 关联字段
+
+关联其他表单记录（下拉选择/搜索），选中后展示目标表单的某个字段值。
+
+```json
+{
+  "componentKey": "EBuilder",
+  "fieldName": "关联客户",
+  "sformId": "1296220571782152199",
+  "dataTitle": "客户名称"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `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` 清空。
+
+### EBuilder + 值带出（relateFrom）
+
+选关联记录后自动带出其他字段值（如选客户→带出联系人/地址）：
+
+```json
+{
+  "componentKey": "Text",
+  "fieldName": "联系人",
+  "relateFrom": { "ebuilderField": "关联客户", "sourceFieldId": "1296220571782152194" }
+}
+```
+
+- `ebuilderField`：本表单中的 EBuilder 字段名
+- `sourceFieldId`：目标表单中要复制值的字段 **fieldId（数字 ID）**。⚠️ **不能传字段名**，用 `form read --app-id` 获取
+
+创建后补配值带出：`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、校验不能关联自身，并在保存后回读确认。
+
+```json
+[
+  {"componentKey":"DetailTable","fieldName":"明细表2","formFields":[
+    {"componentKey":"Text","fieldName":"名称"}
+  ]},
+  {"componentKey":"DetailTable","fieldName":"明细表3","enableSubDetail":true,"defaultExpandRow":true,
+   "subDetailConfig":[{"subForm":"明细表2","subField":"名称"}],"formFields":[
+    {"componentKey":"Text","fieldName":"说明"}
+  ]}
+]
+```
+
+平台实测默认配置为 `parentMark=rowId`、`displayMode=inside`、`filterType=single`；通常不必显式填写。已有表单可用 `form detail-table sub-detail set` 配置，用 `disable` 暂停但保留关系，用 `clear` 清除关系。
+
+子字段也支持带选项的类型。
+
+## 复杂编号（年份编号）：serial-mark
+
+编号（如 `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}
+]
+```
+
+### 段类型参考（任意组合，数组顺序决定拼接顺序）
+
+| 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`：
+
+```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>  # 解除编号绑定
+```
+
+**注意**：
+- 被编码字段平台自动设为只读（编号自动生成，不可手工改）
+- 流水号按 `前缀+年份+流水` 组合查重累进
+- 机制：markField 复杂编号（getEbMarkTargetId → getMarkSetForm → saveSingleMarkDef → saveOrUpdate → saveMarkField）；段对象必须来自 getMarkFieldAddData 预生成；已有绑定时复用持久化 markDef，段/代字不丢失
+
+## 日期区间 DateRange
+
+日期区间字段**必须**指定精度格式，通过 `format` 配置：
+
+```json
+{
+  "componentKey": "DateRange",
+  "fieldName": "出差时间",
+  "format": "yyyy-MM-dd HH:mm"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `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"`
+
+## 字段公式（fields.json 的 formula 属性）
+
+创建表单时直接给字段绑定计算公式，CLI 自动完成「创建公式 + 绑定字段」两步（字段配置会带上 `ffExpress`）：
+
+```json
+{
+  "componentKey": "Number",
+  "fieldName": "出差天数",
+  "formula": "DAYS({主表.出差时间(开始时间)},{主表.出差时间(结束时间)})"
+}
+```
+
+或对象形式指定返回类型：
+
+```json
+"formula": { "expression": "DAYS({主表.出差时间(开始时间)},{主表.出差时间(结束时间)})", "returnType": "Number" }
+```
+
+| 要点 | 说明 |
+|------|------|
+| 表达式语法 | 与 `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
+```
+
+`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":"单价"}]}
+]
+```
+
+## 创建成功后
+
+- 返回表单 ID
+- 用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出字段信息（机器可读 JSON）
+- 在代码中通过 `formApi.js` 读写该表单数据