weaver-e10-builder 1.1.9 → 1.2.2

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`

package/skill-docs/references/form/style-templates.md

@@ -1,44 +1,97 @@
 # 表单布局样式模板
 
-> `form layout init --style-template <名|id>` 用这些模板初始化布局。模板列表基本不变，以下为内置 PC/EXCEL 模板（共 20 个）。
+`form layout init --style-template <名|id>` 用这些模板初始化布局。
 
-| styleTemplateId | 模板名 | 说明 |
+## ⚠ 流式和表格式是**两套独立模板**，不能混用
+
+同一个名字在两套里往往是**不同的 id**（紧凑版 / 轻便版 / 碧海蓝天 / 极简白 / 极简淡蓝 /
+清新蓝绿 / 商务蓝 / 淡雅丁香 两套都有），而且各自还有对方没有的模板。所以**解析模板名必须
+先知道表单的布局类型**。
+
+| 表单布局 | 接口 | 内置模板数 |
 |---|---|---|
-| `700000000000000007` | 标准版 | 默认推荐，字段可编辑 |
-| `700000000000000008` | 表格版 | **注意：生成的 comps 默认只读** |
-| `700000000000000009` | 紧凑版 | |
-| `700000000000000010` | 轻便版 | |
-| `830421425497325568` | 靛青线条 | |
-| `830662158415355904` | 简约深蓝 | |
-| `830714355284320256` | 极简淡蓝 | |
-| `830718787623460864` | 现代简约 | |
-| `830722618751066113` | 商务淡蓝 | |
-| `830743788745531393` | 极简白 | |
-| `830749075757998081` | 极简灰 | |
-| `830751622581329920` | 清新蓝绿 | |
-| `830764108161785857` | 淡蓝水晶 | |
-| `830765800429674496` | 银光浅灰 | |
-| `831747419499700225` | 暗夜流光 | |
-| `831759140499447809` | 公文样式 | |
-| `831897833480421377` | 淡雅丁香 | |
-| `917557790734188546` | 商务蓝 | |
-| `933871446777094145` | 碧海蓝天 | |
-| `1000599952745676801` | 青蓝冰水 | |
+| 流式 `FLOW` | `/api/form/flow/template/list` | 24（本环境另有若干用户导入的） |
+| 表格式 `EXCEL` | `/api/form/form/layout/template/listTemplateAdvancedByPage` | 20 |
+
+**拿错一套不会报错**——平台收到一个不属于该布局类型的 id，直接忽略；命令照常打印"已初始化"，
+样式却纹丝不动。这是最容易踩的坑：改了没效果，还以为模板名写错了。
+
+CLI 已按布局类型自动选接口并校验：传了不属于当前布局那一套的名字或 id 会直接报错，并列出该
+布局类型下可用的模板。
 
 ## 用法
 
 ```bash
-# 用模板名（推荐，好记）
-e10-cli form layout init <objId> <appId> --style-template 标准版
+# 按名字（按当前表单的布局类型实时解析，推荐）
+e10-cli form layout init <objId> <appId> --style-template 碧空如洗
+
+# 按 id（同样会校验它属于当前布局那一套）
+e10-cli form layout init <objId> <appId> --style-template 830000000000000022
 
-# 或用 id
-e10-cli form layout init <objId> <appId> --style-template 700000000000000007
+# 不传则用该布局类型的缺省模板：流式=标准版、表格式=表格版
+e10-cli form layout init <objId> <appId>
 
 # 指定视图 + 只读/必填
 e10-cli form layout init <objId> <appId> --view-id <viewId> --style-template 紧凑版 --read-only
 ```
 
+## 内置模板
+
+> 模板列表**按租户动态**（用户可以自行导入模板，本环境流式那套就多出十几个带「(导入)」的
+> 副本），**以命令输出为准**；下表是验证环境的内置项，供参考。
+
+### 流式（FLOW）
+
+| styleTemplateId | 模板名 |
+|---|---|
+| `820000000000000001` | 标准版（**缺省**） |
+| `820000000000000002` | 标准版（无表头） |
+| `820000000000000011` | 表格版 |
+| `810000000001000004` | 轻量设置版 |
+| `810000000001000001` / `002` / `003` | 分区卡片版 1 / 2 / 3 |
+| `830000000000000010` | 紧凑版 |
+| `830000000000000011` | 轻便版 |
+| `830000000000000012` | word版 |
+| `830000000000000015` / `016` / `017` | 轻量紫 / 轻量白 / 轻量蓝 |
+| `830000000000000018` | 简约瀑布流 |
+| `830000000000000019` | 半透蒙版 |
+| `830000000000000021` | 碧海蓝天 |
+| `830000000000000022` | 碧空如洗 |
+| `830000000000000023` | 淡雅丁香 |
+| `830000000000000024` | 极简白 |
+| `830000000000000025` | 极简淡蓝 |
+| `830000000000000026` | 简洁现代 |
+| `830000000000000027` | 清新蓝绿 |
+| `830000000000000028` | 深蓝商务 |
+| `830000000000000029` | 商务蓝 |
+
+### 表格式（EXCEL）
+
+| styleTemplateId | 模板名 |
+|---|---|
+| `700000000000000007` | 标准版 |
+| `700000000000000008` | 表格版（**缺省**，生成的 comps 默认只读） |
+| `700000000000000009` | 紧凑版 |
+| `700000000000000010` | 轻便版 |
+| `830421425497325568` | 靛青线条 |
+| `830662158415355904` | 简约深蓝 |
+| `830714355284320256` | 极简淡蓝 |
+| `830718787623460864` | 现代简约 |
+| `830722618751066113` | 商务淡蓝 |
+| `830743788745531393` | 极简白 |
+| `830749075757998081` | 极简灰 |
+| `830751622581329920` | 清新蓝绿 |
+| `830764108161785857` | 淡蓝水晶 |
+| `830765800429674496` | 银光浅灰 |
+| `831747419499700225` | 暗夜流光 |
+| `831759140499447809` | 公文样式 |
+| `831897833480421377` | 淡雅丁香 |
+| `917557790734188546` | 商务蓝 |
+| `933871446777094145` | 碧海蓝天 |
+| `1000599952745676801` | 青蓝冰水 |
+
 ## 注意
 
 - 模板只影响**布局样式**（间距/边框/配色），不影响字段的 readOnly/required（这俩由 `--read-only`/`--required` 或 fields.json 控制）。
-- `表格版`（008）历史问题：生成的 comps 默认 readOnly=true。`form layout init` 会显式按 `--read-only`（默认 false 可编辑）覆盖，所以即使用 008 也能可编辑。
+- `表格版`（EXCEL 008）历史问题：生成的 comps 默认 readOnly=true。`form layout init` 会显式按 `--read-only`（默认 false 可编辑）覆盖，所以即使用 008 也能可编辑。
+- 建表（`form create`）时**不能**指定样式模板，只能建完再 `form layout init --style-template` 换。