weaver-e10-builder 1.1.9 → 1.2.3

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`。

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

@@ -0,0 +1,156 @@
+# 虚拟表创建与维护
+
+虚拟表把已有数据源的字段映射为 EB 表单，用于统一展示 EB 表单、系统业务表或数据加工结果。虚拟表保留来源字段的数据键与类型，布局、视图和菜单继续使用表单现有能力。
+
+## 创建顺序
+
+1. 确定来源类别和数据源。
+2. 校验数据源具有稳定 ID 字段。
+3. 读取来源字段，选择需要展示的字段。
+4. 按来源类型保留字段映射，设置名称、顺序和显示属性。
+5. 创建虚拟表并初始化 FLOW 或 EXCEL 布局。
+6. 按需求配置分组、默认台账、显示列和菜单。
+
+## 数据源类别
+
+| 来源 | `dataSourceType` | `dataSourceGroup` |
+| --- | --- | --- |
+| EB 表单 | `LOGIC` | `weaver-ebuilder-form-service` |
+| 系统业务表 | `LOGIC` | 对应业务服务，如 `weaver-hrm-service` |
+| 数据加工 | `ETEAMS` | 数据集分组 ID |
+
+查询普通逻辑数据源：
+
+```bash
+e10-cli form virtual source-groups --source-type LOGIC
+e10-cli form virtual sources <groupId> --source-type LOGIC --name <名称>
+```
+
+查询数据加工：
+
+```bash
+e10-cli form virtual dataset-groups
+e10-cli form virtual datasets <groupId> --name <名称>
+e10-cli form virtual dataset-info <datasetId>
+```
+
+## 数据源与字段预检
+
+```bash
+e10-cli form virtual fields <appId> \
+  --source-type LOGIC \
+  --source-group weaver-hrm-service \
+  --source-id <数据源ID>
+```
+
+命令先检查来源是否具有稳定 ID，再返回可选字段。每个字段重点保留：
+
+```text
+dataKey
+virtualFieldId
+sourceFieldType
+sourceFieldTitle
+type / componentKey
+```
+
+## 字段选择文件
+
+
+```json
+[
+  "username",
+  {
+    "sourceField": "ACTIVE_DATE",
+    "fieldName": "激活时间",
+    "componentKey": "DateTime",
+    "format": "yyyy-MM-dd HH:mm",
+    "readOnly": true,
+    "singleRow": false
+  }
+]
+```
+
+- 字符串简写按 `dataKey`、`virtualFieldId` 或来源字段名称匹配。
+- 未指定 `componentKey` 时使用平台推荐类型。
+- `fieldName`、`required`、`readOnly`、`hidden`、`singleRow` 用于表单展示。
+- 来源字段标识由 CLI 从接口结果中补齐。
+
+## 类型兼容
+
+| 来源类型 | 默认类型 | 可用的同族展示类型 |
+| --- | --- | --- |
+| `String-普通文本` | `Text` | `Text`、`TextArea` |
+| `Number-数值` | `Number` | `Number`、`Money` |
+| `Date-日期` | `Date` | `Date`、`DateTime` |
+| 选项、人员、部门、关联等复杂字段 | 来源组件 | 保留来源组件类型与配置 |
+
+CLI 在保存前校验类型兼容性。长度、数字精度和日期格式可在同族类型内设置；复杂字段沿用数据源返回的组件结构。
+
+## 创建
+
+系统业务表：
+
+```bash
+e10-cli form virtual create <appId> "人员虚拟表" \
+  --source-type LOGIC \
+  --source-group weaver-hrm-service \
+  --source-id <人员表数据源ID> \
+  --source-name "人员表" \
+  --source-module hrm \
+  --fields @virtual-fields.json \
+  --layout FLOW
+```
+
+EB 表单：
+
+```bash
+e10-cli form virtual create <appId> "项目虚拟表" \
+  --source-type LOGIC \
+  --source-group weaver-ebuilder-form-service \
+  --source-id <来源表单数据源ID> \
+  --source-app-id <来源应用ID> \
+  --fields @virtual-fields.json \
+  --layout FLOW
+```
+
+数据加工：
+
+```bash
+e10-cli form virtual create <appId> "合同加工结果" \
+  --source-type ETEAMS \
+  --source-group <数据集分组ID> \
+  --source-id <数据集ID> \
+  --dataset-type sql \
+  --fields @virtual-fields.json \
+  --layout FLOW
+```
+
+创建结果返回 `objId`、`formId` 和默认视图 ID。来源访问范围随已选择的数据源配置保存，虚拟表命令不单独修改数据源权限。
+
+## 读取与增加字段
+
+```bash
+e10-cli form virtual read <objId> <appId>
+
+e10-cli form virtual add-fields <objId> <appId> <formId> \
+  --source-type LOGIC \
+  --source-group weaver-hrm-service \
+  --source-id <数据源ID> \
+  --fields @add-fields.json
+```
+
+增加字段时重新从原数据源读取当前可选字段，并保留来源映射。字段移除和更换数据源按取得的实际接口配置另行维护。
+
+## 后续配置
+
+虚拟表创建后继续使用现有命令：
+
+- 布局：`form layout read/init/move/set-read-only/set-required`
+- 分组：`form group`
+- 默认台账和显示列：`form list-columns`、`form nlist`
+- 视图：`form view`、`form table-view`
+- 菜单：`menu add-table`
+
+## Plan 记录
+
+虚拟表在表单清单中注明：名称、来源类别、数据源名称或 ID、选用字段、字段映射、布局和视图。执行时依次销号数据源定位、主键校验、字段映射、创建、布局和视图配置。

package/skill-docs/references/form/ref-form-fields.md

@@ -1,148 +1,287 @@
-# 表单字段定义参考
+# 表单字段类型与配置
 
-本参考用于编写 EB 表单的 `fields.json`。标准创建顺序见 [新建 EBuilder 表单](guide-create-form.md)。
+本文件维护 EB 表单字段的类型码表、选型规则和通用配置。表单结构、明细表和布局组件的创建方式见 `guide-create-form.md`。
 
 ## 通用结构
 
 ```json
-{"componentKey":"Text","fieldName":"项目名称","required":true,"readOnly":false,"hidden":false,"singleRow":true,"group":"基本信息"}
+{
+  "componentKey": "Text",
+  "fieldName": "项目名称",
+  "required": true,
+  "readOnly": false,
+  "hidden": false,
+  "singleRow": false,
+  "group": "基本信息",
+  "defaultValue": ""
+}
 ```
 
 | 属性 | 说明 |
-|---|---|
-| `componentKey` | 字段类型 |
-| `fieldName` | 字段中文名称 |
+| --- | --- |
+| `componentKey` | 字段类型标识 |
+| `fieldName` | 字段名称 |
 | `required` / `readOnly` / `hidden` | 必填、只读、隐藏 |
 | `singleRow` | 独占一行 |
-| `group` | 需求指定的字段分组 |
-| `multiple` | 支持多选的类型设置为多选 |
+| `group` | 所属分组 |
+| `multiple` | 是否多选；`false` 为单选，`true` 为多选 |
 | `defaultValue` | 默认值；人员、部门和日期写 `true` 表示动态当前值 |
 
-## 支持的字段类型
-
-| `componentKey` | 用途 | 常用专属属性 |
-|---|---|---|
-| `Text` | 单行文本 | `maxLen`，缺省 100 |
-| `TextArea` | 多行文本 | `maxLen`，缺省 4000 |
-| `Email` / `Phone` / `Mobile` / `IDCard` | 邮箱、电话、手机、身份证 | `maxLen` |
-| `Number` | 数字 | `precision`、`percent`、`delimiter`、`capital` |
-| `Money` | 金额 | `precision`、`delimiter`、`capital` |
-| `Date` / `DateTime` | 日期、日期时间 | `format`、`minField`、`maxField` |
-| `DateRange` | 日期区间 | `format`、`startPlaceholder`、`endPlaceholder` |
-| `Time` | 时间 | 格式 `HH:mm:ss` |
-| `Select` / `RadioBox` / `CheckBox` | 选项字段 | `fieldOptions`、`optionTemplate`、`multiple` |
-| `Employee` / `Department` | 人员、部门 | `multiple`、`defaultValue` |
-| `FileComponent` | 附件 | 通用显示属性 |
-| `EInvoice` | 电子发票 | 通用显示属性 |
-| `AudioRecord` / `VideoRecord` | 语音、视频 | 通用显示属性 |
-| `DetailTable` | 明细表 | `formFields`、二级明细属性 |
-| `EBuilder` | 关联 EB 表单 | `sformId`、`dataTitle`、`displayColumns`、`multiple` |
-| `Flow` | 关联流程数据 | `sformId` 指向流程绑定的表单 objId |
-| `Browser` / `RelateBrowser` | 通用关联浏览 | `browserType`、`browserFormSource`、`multiple` |
-| `Project` / `Task` / `Document` / `Agenda` | 项目、任务、文档、日程 | `multiple` |
-| `FormData` | 原生关联表单数据 | `multiple` |
-| `Customer` / `Clue` / `Contact` / `Chance` | CRM 关联 | `multiple` |
-| `Product` / `Activity` / `Quote` / `Competitor` | CRM 业务关联 | `multiple` |
-| `Performance` / `Report` / `Attend` | 绩效、汇报、考勤 | 类型专属配置 |
-| `RelateODoc` / `RelateTag` | 公文、标签 | `multiple`、类型专属配置 |
-| `DrivingRecord` | 行车记录 | `defaultRows` |
-
-人员相关业务字段使用 `Employee`，附件字段使用 `FileComponent`。
-
-## 文本、数字和日期
+## 字段类型分类
 
-```json
-{"componentKey":"Text","fieldName":"项目编号","maxLen":500},
-{"componentKey":"TextArea","fieldName":"项目简介","maxLen":4000,"singleRow":true},
-{"componentKey":"Number","fieldName":"成本占比","precision":2,"percent":true},
-{"componentKey":"Money","fieldName":"合同金额","precision":2,"delimiter":true,"capital":true},
-{"componentKey":"Date","fieldName":"计划结束日期","minField":"计划开始日期"},
-{"componentKey":"DateRange","fieldName":"合同有效期","format":"yyyy-MM-dd"}
-```
+### 基本类型
 
-- `Number` 缺省精度为 0；`Money` 缺省精度为 2。
-- 百分比字段以百分数显示，比例公式需要得到 0–100 的数值。
-- `minField` 表示本字段最早不得早于目标字段；`maxField` 表示最晚不得晚于目标字段。
-- 日期字段需要当前日期默认值时写 `"defaultValue":true`。
-- 字段本身包含起止含义时优先使用 `DateRange`。
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 单行文本 | `Text` | `maxLen`，缺省 100 |
+| 多行文本 | `TextArea` | `maxLen`，缺省 4000 |
+| 邮箱 / 电话 / 手机 / 身份证 | `Email` / `Phone` / `Mobile` / `IDCard` | `maxLen`、对应格式校验 |
+| 数字 | `Number` | `precision`、`delimiter`、`percent`、`capital` |
+| 金额 | `Money` | `precision`、`delimiter`、`capital` |
+| 开关 | `Switch` | 开关值 |
+| 附件 | `FileComponent` / `Attachment` | 附件上传设置 |
+| 图片 | `Image` | 图片上传设置 |
+| 语音 | `AudioRecord` | 语音录制与上传 |
+| 视频 | `VideoRecord` | 视频录制与上传 |
 
-## 选项、默认值与多选
+### 选项类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 下拉单选 | `Select` | `fieldOptions` 或 `optionTemplate` |
+| 下拉多选 | `SelectMultiple` | `fieldOptions` 或 `optionTemplate` |
+| 单选框 | `RadioBox` | `fieldOptions` 或 `optionTemplate` |
+| 复选框 | `CheckBox` | `fieldOptions` 或 `optionTemplate` |
+| 级联选择 | `Cascade` | 级联选项数据 |
+| 树形选择 | `Tree` | 树形选项数据 |
+| 矩阵选择 | `Matrix` | 矩阵配置 |
+
+### 日期类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 日期 | `Date` | `format`、`minField`、`maxField`、`defaultValue` |
+| 日期时间 | `DateTime` | `format`、`minField`、`maxField`、`defaultValue` |
+| 日期区间 | `DateRange` / `DateInterval` | `format`、`startPlaceholder`、`endPlaceholder` |
+| 时间 | `Time` | 格式 `HH:mm:ss`；平台组件是 `TimeComponent`（`componentKey` 与类型名不同） |
+
+一个字段名称或业务含义同时包含开始、结束、起止、期间、周期等区间含义时，优先使用日期区间；两个独立字段分别表达起点和终点时，再使用两个日期字段并通过 `minField` / `maxField` 约束。
+
+### 组织类型
+
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 人员选择 | `Employee` | `multiple` |
+| 部门选择 | `Department` | `multiple` |
+| 共享人 | `Sharer` | 共享范围设置 |
+
+### 关联类型
+
+以下为原生关联对象码表。需求明确指向这些业务对象时，直接使用对应类型。
+
+| 界面名称 | `componentKey` | 平台组件 | 主要配置或说明 |
+| --- | --- | --- | --- |
+| 关联 e-builder | `EBuilder` | `Ebuilder` | `sformId`、`dataTitle`、`displayColumns` |
+| 关联项目 | `Project` | `Mainline` | 项目选择范围 |
+| 关联任务 | `Task` | `Task` | 任务选择范围 |
+| 关联文档 | `Document` | `Document` | 文档选择范围 |
+| 关联流程 | `Flow` | `Workflow` | `target_workflow_form_name`、流程范围 |
+| 关联日程 | `Agenda` | `AgendaComponent` | 日程选择范围 |
+| 关联上报 | `FormData` | `FormComponent` | 上报表单、显示列、条件和数据标题 |
+| 关联客户 | `Customer` | `CustomerComponent` | 客户选择范围 |
+| 关联线索 | `Clue` | `ClueComponent` | 线索选择范围 |
+| 关联联系人 | `Contact` | `ContactComponent` | 联系人选择范围 |
+| 关联商机 | `Chance` | `ChanceComponent` | 商机选择范围 |
+| 关联订单 | `Order` | `OrderComponent` | 订单选择范围；不执行客户编号未填校验 |
+| 关联合同 | `Contract` | `ContractComponent` | 合同选择范围 |
+| 关联产品 | `Product` | `ProductionComponent` | 产品选择范围 |
+| 关联活动 | `Activity` | `ActivityComponent` | 活动选择范围 |
+| 关联报价 | `Quote` | `QuoteComponent` | 报价选择范围 |
+| 关联对手 | `Competitor` | `CompetitorComponent` | 竞争对手选择范围 |
+| 关联绩效 | `Performance` | `KpiFlowComponent` | 绩效选择范围 |
+| 关联报告 | `Report` | `WorkreportComponent` | 报告选择范围 |
+| 关联考勤 | `Attend` | `AttendComponent` | `attendDateType` |
+| 关联浏览 | `Browser` / `RelateBrowser` | `RelateBrowser` | 通过 `browserType` 选择浏览子类 |
+| 电子发票 | `EInvoice` | `EinvoiceComponent` | 发票选择配置 |
+| 行车记录 | `DrivingRecord` | `DrivingRecord` | `defaultRows` |
+| 关联公文 | `RelateODoc` | `RelateODoc` | 公文选择范围 |
+| 关联标签 | `RelateTag` | `RelateTag` | `range` |
+
+#### 关联类型选型
+
+| 需求语义 | 选择 |
+| --- | --- |
+| 关联电子发票 | `EInvoice` |
+| 关联上报数据 | `FormData` |
+| 关联合同业务对象 | `Contract` |
+| 关联某张 EB 表单，如“合同信息表” | `EBuilder` |
+| 关联人事合同 | `RelateBrowser`，`browserType: "hrcontract"` |
+| 关联流程数据 | `Flow` |
+| 浏览工作流定义 | `RelateBrowser`，`browserType: "workflow"` |
+| 关联业务表单或 EB 表单数据 | `RelateBrowser`，`browserType: "form"` |
+
+`FormData` 表示“关联上报”，与通用关联浏览中的表单浏览不是同一配置。`EBuilder` 用于关联明确的 EB 表单；`RelateBrowser + form` 用于通用表单浏览。
+
+#### 关联 e-builder
 
 ```json
-{"componentKey":"Select","fieldName":"状态","fieldOptions":[{"name":"启用"},{"name":"停用"}]},
-{"componentKey":"Employee","fieldName":"项目成员","multiple":true}
+{
+  "fieldName": "关联客户",
+  "componentKey": "EBuilder",
+  "target_form_name": "客户信息表",
+  "dataTitle": "客户名称",
+  "displayColumns": ["客户名称", "客户编号"],
+  "multiple": false
+}
 ```
 
-`valueKey` 可省略，由 CLI 生成；手工指定时使用数字字符串。共享选项可使用：
+- `sformId` 可直接指定目标表单 ID；按需求编排时也可使用 `target_form_name`，执行阶段解析为目标表单。
+- `dataTitle` 指定已选数据的标题字段。
+- `displayColumns` 指定选择窗口显示列；省略时使用目标表单的业务字段。
+- `multiple: false` 对应单选，`multiple: true` 对应多选。
+
+字段带出使用 `relateFrom`：
 
 ```json
-{"componentKey":"Select","fieldName":"优先级","optionTemplate":"优先级模板"}
+{
+  "fieldName": "客户名称",
+  "componentKey": "Text",
+  "relateFrom": {
+    "ebuilderField": "关联客户",
+    "sourceFieldId": "目标表单字段ID"
+  }
+}
 ```
 
-`fieldOptions` 与 `optionTemplate` 选择其中一种。不写 `multiple` 或写 `false` 表示单选（`isSingle:true`）；写 `true` 表示多选（`isSingle:false`）。多选 Select 由 CLI 转为 `SelectMultiple`。
+`sourceFieldId` 使用目标表单字段的数字 ID。
+
+#### 通用关联浏览子类
 
-## EBuilder 与字段带出
+| `browserType` | 作用 | 主要配置 |
+| --- | --- | --- |
+| `workflow` | 浏览工作流定义 | 工作流范围 |
+| `hrcontract` | 浏览人事合同 | 人事合同范围 |
+| `form` | 浏览业务表单或 EB 表单数据 | `browserFormSource`、目标表单、标题和显示列 |
+| `role` | 浏览角色 | 角色范围 |
+| `archive` | 浏览档案 | 档案范围 |
+| `hrm_sex` | 浏览人事「性别」 | — |
+| `hrmJobcall` | 浏览人事「职称」 | — |
+
+已明确的专属参数包括考勤 `attendDateType`、行车记录 `defaultRows`、标签 `range`。参数值按实际需求或接口返回配置。
+
+业务表单浏览：
 
 ```json
-{"componentKey":"EBuilder","fieldName":"关联客户","sformId":"<目标表单objId>","dataTitle":"客户名称","displayColumns":["客户名称","客户类型"]}
+{
+  "fieldName": "关联业务数据",
+  "componentKey": "RelateBrowser",
+  "browserType": "form",
+  "browserFormSource": "business",
+  "target_form_name": "业务表单",
+  "multiple": false
+}
 ```
 
-`displayColumns` 未指定时，CLI 选择目标表单的业务字段作为浏览显示列。需要从关联记录带出值时，在目标字段写：
+EB 表单浏览：
 
 ```json
-{"componentKey":"Text","fieldName":"联系人","relateFrom":{"ebuilderField":"关联客户","sourceFieldId":"<目标字段fieldId>"}}
+{
+  "fieldName": "关联EB数据",
+  "componentKey": "RelateBrowser",
+  "browserType": "form",
+  "browserFormSource": "ebuilder",
+  "target_form_name": "客户信息表",
+  "multiple": true
+}
 ```
 
-`sourceFieldId` 使用目标表单字段的数字 ID。
+### 行政区域
 
-## 原生关联类型码表
-
-| 关联对象 | `fields.json componentKey` | 平台组件 |
-|---|---|---|
-| 项目 | `Project` | `Mainline` |
-| 任务 | `Task` | `Task` |
-| 文档 | `Document` | `Document` |
-| 日程 | `Agenda` | `AgendaComponent` |
-| 表单数据 | `FormData` | `FormComponent` |
-| 客户、线索、联系人、商机 | `Customer` / `Clue` / `Contact` / `Chance` | 对应 CRM Component |
-| 订单、合同 | `Order` / `Contract` | `OrderComponent` / `ContractComponent` |
-| 产品、市场活动、报价、竞争对手 | `Product` / `Activity` / `Quote` / `Competitor` | 对应业务 Component |
-| 绩效、工作汇报、考勤 | `Performance` / `Report` / `Attend` | 对应业务 Component |
-| 通用浏览 | `Browser` / `RelateBrowser` | `RelateBrowser` |
-| 公文、标签 | `RelateODoc` / `RelateTag` | 同名平台组件 |
-| 行车记录 | `DrivingRecord` | `DrivingRecord` |
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 行政区域 / 城市选择 | `City` | 区域层级与选择范围 |
 
-已明确的专属参数包括考勤 `attendDateType`、行车记录 `defaultRows`、标签 `range`。参数值按实际需求或接口返回配置。
+### 其他
 
-## 通用关联浏览
+| 用途 | `componentKey` | 主要配置 |
+| --- | --- | --- |
+| 进度 | `Progress` | 进度值范围 |
+| 评分 | `Score` | 评分范围 |
+| 签名 | `Signature` | 签名设置 |
+| 定位 | `Location` | 位置信息；用于支持该组件的布局 |
+| 颜色选择 | `ColorPicker` | 颜色值 |
+| 富文本 | `RichText` | 富文本内容 |
+| 文档目录 | `DocFolder` / `DocFloder` | 文档目录选择 |
 
-| 浏览对象 | `browserType` | 其他参数 |
-|---|---|---|
-| 工作流 | `workflow` | 缺省类型 |
-| 人事合同 | `hrcontract` | — |
-| 表单 | `form` | `browserFormSource:business|ebuilder` |
-| 角色 | `role` | — |
-| 档案 | `archive` | — |
+## 文本、数字和日期配置
 
 ```json
-{"componentKey":"Browser","fieldName":"关联业务表单","browserType":"form","browserFormSource":"business"},
-{"componentKey":"Browser","fieldName":"关联EB表单","browserType":"form","browserFormSource":"ebuilder"}
+[
+  {"fieldName": "标题", "componentKey": "Text", "maxLen": 100},
+  {"fieldName": "说明", "componentKey": "TextArea", "maxLen": 4000},
+  {"fieldName": "数量", "componentKey": "Number", "precision": 0},
+  {"fieldName": "金额", "componentKey": "Money", "precision": 2, "delimiter": true},
+  {"fieldName": "完成比例", "componentKey": "Number", "precision": 2, "percent": true},
+  {"fieldName": "开始日期", "componentKey": "Date"},
+  {"fieldName": "结束日期", "componentKey": "Date", "minField": "开始日期"},
+  {"fieldName": "创建日期", "componentKey": "Date", "defaultValue": true}
+]
 ```
 
-## 明细表与公式
+- 百分比字段按 0–100 的显示语义设计，公式按实际业务口径编写。
+- `Number` 缺省精度为 0；`Money` 缺省精度为 2。
+- `minField` / `maxField` 用于两个独立日期字段的先后约束。
+- 日期字段的 `defaultValue: true` 表示默认当前日期。
+
+## 选项、默认值与多选
+
+```json
+{
+  "fieldName": "项目状态",
+  "componentKey": "Select",
+  "fieldOptions": [
+    {"name": "审批"},
+    {"name": "立项"},
+    {"name": "执行"},
+    {"name": "结案"}
+  ]
+}
+```
+
+- `valueKey` 可省略，由 CLI 生成；手工指定时使用稳定的数字字符串。
+- 公共选项模板使用 `optionTemplate`；`fieldOptions` 与 `optionTemplate` 二选一。
+- `multiple: false` 保存为单选（`isSingle: true`），`multiple: true` 保存为多选（`isSingle: false`）。
+- `Select` 开启多选后使用 `SelectMultiple`。
 
 ```json
-{"componentKey":"DetailTable","fieldName":"订单明细","formFields":[
-  {"componentKey":"Text","fieldName":"商品名称"},
-  {"componentKey":"Number","fieldName":"数量"},
-  {"componentKey":"Number","fieldName":"单价","precision":2}
-]}
+{
+  "fieldName": "重要程度",
+  "componentKey": "Select",
+  "optionTemplate": "重要程度"
+}
 ```
 
-二级明细使用 `enableSubDetail`、`defaultExpandRow` 和 `subDetailConfig`。明细子字段支持常用属性、选项、日期限制和公式。
+## 公式
 
 ```json
-{"componentKey":"Number","fieldName":"合计金额","formula":"SUM({付款明细.付款金额})"}
+{
+  "fieldName": "项目收益",
+  "componentKey": "Number",
+  "precision": 2,
+  "readOnly": true,
+  "formula": "{主表.项目已收款}-({主表.项目工时}*100+{主表.项目费用})"
+}
 ```
 
-公式对象还可以包含 `expression`、`returnType` 和 `name`。完整表达式规则见 [字段公式函数参考](guide-form-formula-functions.md)。
+- 公式字段通常设为只读。
+- 主表字段使用 `{主表.字段名}`，明细字段按对应表和字段引用。
+- 公式对象还可包含 `expression`、`returnType` 和 `name`。
+- 公式、联动和校验在字段与布局初始化后使用各自命令配置。
+
+## 相关文档
+
+- 表单创建与主表、明细表结构：`guide-create-form.md`
+- 布局：`guide-form-layout.md`
+- 字段事件：`guide-field-event.md`
+- 字段公式函数：`guide-form-formula-functions.md`
+- CLI 命令：`../common/ref-cli-commands.md`