weaver-e10-builder 1.0.11-beta → 1.1.0

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

@@ -0,0 +1,409 @@
+# 新建 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` 读写该表单数据

package/skill-docs/references/form/guide-ebuilder-filter.md

@@ -0,0 +1,73 @@
+# EBuilder 关联字段数据过滤
+
+用于配置表单中 EBuilder 关联字段的“数据过滤设置”。它决定关联弹窗里哪些目标表单数据可被选择，不是表格视图的常用搜索。
+
+## 命令
+
+```bash
+# 读取并解析当前规则
+e10-cli form ebuilder-filter get <源objId> <appId> <EBuilder字段fieldId>
+
+# 设置规则；rules 支持 JSON 字符串或 @文件
+e10-cli form ebuilder-filter set <源objId> <appId> <EBuilder字段fieldId> \
+  --rules @filter-rules.json \
+  --logic and
+
+# 清空规则
+e10-cli form ebuilder-filter clear <源objId> <appId> <EBuilder字段fieldId>
+```
+
+`--logic and|or` 表示满足全部或任一规则；`--fill-null 0|1` 控制关联值为空时是否填充。未传时保留原设置。
+
+## 规则格式
+
+每条规则统一使用目标字段的准确名称或 `fieldId`，不要手写 `filterParams`：
+
+```json
+[
+  {
+    "field": "合同名称",
+    "operator": "like",
+    "value": "测试合同"
+  },
+  {
+    "field": "合同金额",
+    "operator": "like",
+    "value": { "min": 100, "max": 500 }
+  },
+  {
+    "field": "合同状态",
+    "operator": "eq",
+    "value": ["已退回"]
+  }
+]
+```
+
+字段名重复时必须改用 `fieldId`。Select/RadioBox/CheckBox 的 `value` 可以写选项名称或 `valueKey`，CLI 会查询选项并转换；浏览类字段应写对象 ID。
+
+## 字段与条件
+
+| 目标字段 | operator | value |
+|---|---|---|
+| 固定标题 `name` | `like`、`eq`、`neq` | 单值 |
+| 固定创建者 `creator` | `eq`、`neq` | ID 或 ID 数组 |
+| 固定创建时间 `create_time` | `like` | `{"start":"...","end":"..."}` |
+| Text/TextArea/Email/Phone/Mobile | `like`、`eq`、`neq`、`null`、`notnull` | 单值；空值条件不传 value |
+| Money/Number | `like`、`null`、`notnull` | `like` 使用 `{"min":...,"max":...}` |
+| Date/DateComponent | `like`、`beq`、`seq`、`null`、`notnull` | 范围或单值 |
+| Select/RadioBox/CheckBox | `eq`、`neq`、`null`、`notnull` | 名称/valueKey 数组 |
+| Employee/Department 等浏览类 | `eq`、`neq`、`null`、`notnull` | ID 或 ID 数组 |
+
+条件来自当前设计器契约。未知组件或不支持的条件必须在写入前失败，禁止猜测。
+
+## 保存与验证
+
+CLI 会：
+
+1. 验证源字段确为已绑定目标表单的 EBuilder 字段。
+2. 从目标表单读取字段类型和选项，不按名称猜类型。
+3. 同时生成运行时 `filterParams` 和设计器回显 `filterQueryParams`。
+4. 通过字段布局接口保存，并保留其他字段布局设置。
+5. 从 `getFormLayout.fieldLayout` 独立回读；两份配置不一致即报错。
+
+当前只支持常量过滤。变量来源、未确认的新控件和无法取得选项契约的跨应用字段，不应强行写入。

package/skill-docs/references/form/guide-ebuilder-scope.md

@@ -0,0 +1,82 @@
+# 关联浏览数据范围设置（浏览数据定义 → 数据范围）
+
+配置表单中 EBuilder 关联字段的**数据范围设置**——决定关联浏览弹窗里**哪些被关联数据可选**（如关联客户时只选"客户状态=启用"的客户）。对应设计器「浏览数据定义 → 数据范围设置」面板。
+
+走平台 `browserDataScope` 接口（selectPage 读 / batchSave 写+清），设计器能识别、浏览时生效。
+
+## 命令
+
+```bash
+# 读取已设数据范围
+e10-cli form ebuilder-scope get <源objId> <appId> <EBuilder字段fieldId>
+
+# 设置数据范围：被关联数据须满足条件才可选
+e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> \
+  --rules @scope-rules.json --logic and
+
+# 清空
+e10-cli form ebuilder-scope clear <源objId> <appId> <EBuilder字段fieldId>
+```
+
+- `<源objId>`：含关联浏览字段的表单 objId
+- `<appId>`：应用 ID
+- `<EBuilder字段fieldId>`：关联浏览字段的 fieldId（`form read` 获取，类型为 Ebuilder）
+- `--logic and|or`：多规则关系（默认 `and`）
+- `--fill-null`：关联字段为空时是否填充（默认关闭）
+
+## 规则格式
+
+```json
+[
+  {"field":"客户状态","operator":"eq","value":"启用"},
+  {"field":"客户名称","operator":"like","value":"上海"}
+]
+```
+
+| 字段 | 说明 |
+|------|------|
+| `field` | 目标表单字段名或 fieldId（CLI 自动解析） |
+| `operator` | `eq`(等于)/`neq`(不等于)/`like`(包含)/`isnull`(为空)/`notnull`(不为空) |
+| `value` | 选项类用**选项名**，CLI 自动解析 valueKey；文本/数字/日期用字面值。`isnull`/`notnull` 不需要 value |
+
+> 选项类字段（Select/Radio/CheckBox）：`value` 填选项名，CLI 自动反查目标表该字段的选项、解析出 valueKey，填 `selectValue`/`customBrowserValue`/`config.options`。选项名必须在目标表选项中存在，否则报错并列出可选值。
+
+## 示例
+
+**关联客户只选启用状态**（典型场景：客户状态=启用才可选）：
+
+```bash
+e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> \
+  --rules '[{"field":"客户状态","operator":"eq","value":"启用"}]'
+```
+
+**多条件**（启用且名称含上海）：
+
+```bash
+e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> \
+  --rules '[{"field":"客户状态","operator":"eq","value":"启用"},{"field":"客户名称","operator":"like","value":"上海"}]' \
+  --logic and
+```
+
+**清空恢复全部可选**：
+
+```bash
+e10-cli form ebuilder-scope clear <源objId> <appId> <EBuilder字段fieldId>
+```
+
+## 验证
+
+- `set` 命令保存后自动回读校验规则数是否一致
+- 设计器打开「数据范围设置」面板应显示所设条件
+- 关联浏览时被关联数据应按条件过滤（不满足的不可选）
+
+## 与旧 `ebuilder-filter` 的区别
+
+| | `ebuilder-scope`（推荐） | `ebuilder-filter`（已废弃，保留兼容） |
+|---|---|---|
+| 接口 | `browserDataScope`（数据范围专用） | 字段布局 `filterParams` |
+| 设计器识别 | ✅ | ❌ |
+| 浏览时生效 | ✅ | 不保证 |
+| 用途 | 关联浏览筛选 | 旧机制，已被 scope 取代 |
+
+> ⚠️ `ebuilder-filter` 的旧配置不保证被设计器识别；新建关联浏览筛选一律用 `ebuilder-scope`。