weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/form/guide-list-columns.md

@@ -12,6 +12,14 @@ e10-cli form list-columns <objId> <appId> <listId> --remove <字段ID1> <字段I
 
 `--add` 按输入顺序追加到隐藏主键之前，已存在的列复用原配置；重复执行且无变化时返回 `unchanged:true`，不保存。`--remove` 可与 `--add` 同时使用，但不能对同一字段同时增删。移除不存在的列会报错；数据主键禁止移除。
 
+## 显示列落在哪一层
+
+- **非空 `listField` 优先**：列表式 / 卡片布局的显示列在 `config.listField` + `cardLayout`，请改用 `form nlist add-field|remove-field|apply`；在列表式视图上执行本命令会直接报错给指引。
+- 否则 `tableField` 非空就是表格式：**可编辑表格（`mode` 8/9/11）的 `type` 也是 `NList`，但显示列在 `tableField`**，本命令正常可用。
+- 两边都空才按视图类型兜底。
+
+> 注意 `getNListConfig.tableField`（显示列清单）与 `getListFields.pc[]`（列属性：宽度/对齐/冻结…）是**两层**。平台自动铺出来的台账可能只有前者、`pc[]` 为空——这时 `form list-columns attr show` 会明确显示 0 条，`attr set` 会报错并说明“本命令只改列属性层，不会重建显示列”，不会把已有列清空。
+
 ## 一次设置顺序、宽度和格式
 
 先读取当前列，按需求生成 UTF-8 的 `columns.json`。数组表示**完整业务列清单**：未列入的业务列会移除；数组顺序就是显示顺序。字段 ID 使用字符串，支持 `fieldId` 或 `id`，也支持仅填 ID 字符串。

package/skill-docs/references/form/guide-list-stats.md

@@ -1,136 +1,136 @@
-# 顶部统计：主表与明细
-
-`form list-stats` 配置已有台账视图的统计。支持 sum/count/avg/max/min，以及千分位、小数位、万/亿单位、条件统计；还能配**每条统计项的启用状态**与**统计面板三项**（显示位置 / 手动加载统计值 / 点击统计结果过滤列表数据）。来源表单 `objId`、应用 `appId`、目标视图 `listId` 与明细子表 `subFormId` 是不同 ID。
-
-## 查询及单项配置
-
-```bash
-e10-cli form list-stats <objId> <appId> <listId> --json
-e10-cli form list-stats <objId> <appId> <listId> --add @stat.json
-e10-cli form list-stats <objId> <appId> <listId> --remove <statId>
-```
-
-主表与明细字段均使用真实 fieldId；CLI 展开 `ds/fields` 的明细分组，未命中时按 `getFormField` 补查。字段必须属于当前表单，指定 subFormId 时必须与字段实际归属一致。
-
-付款金额统计示例：
-
-```json
-{
-  "fieldId": "1310832033224278033",
-  "type": "sum",
-  "name": "合同付款金额",
-  "decimalPlaces": "2",
-  "thousandths": true
-}
-```
-
-明细记录计数可省略 fieldId：
-
-```json
-{
-  "type": "count",
-  "subFormId": "1310832033224278030",
-  "name": "付款记录数"
-}
-```
-
-计数写为 `fieldId="5" + subFormId`，统计明细记录数。传明细字段做 count 也会转成该子表的记录计数，并非此字段非空值计数。主表记录计数可使用 `{"type":"count","name":"记录数"}`；已有传主表 fieldId 的用法继续接受。
-
-主表的 subFormId 写 `-1`，明细写实际子表 ID。**当前平台会将明细字段 sum 等字段聚合回读的 subFormId 规范化为 `-1`，仍由唯一 fieldId 定位明细字段；明细 count 必须保留子表 ID。** 回读校验兼容这种规范化，不允许字段或计数子表发生变化。
-
-格式参数：`thousandths` 为布尔值；`decimalPlaces` 为 -1 或 0–20 的整数；单位支持 `unit: "万"/"亿"` 或 `unitType: "none"/"tenThousand"/"hundredMillion"`。主表保持原默认小数位 -1，明细非计数默认 2，计数默认 -1。sum/avg 要求数值字段。
-
-## 条件统计
-
-```json
-{
-  "fieldId": "1310832033224278033",
-  "type": "sum",
-  "name": "正数付款金额",
-  "conditions": [
-    {"fieldId": "1310832033224278033", "func": "gt", "value": 0}
-  ]
-}
-```
-
-条件支持主表字段和本次统计子表字段，多个条件默认 AND。`valueField` 可引用字段 ID 或唯一名称，字段引用也校验子表归属。跨其他明细子表的条件拒绝保存，避免产生不明确的关联语义。
-
-条件写入明文 `rootdata`，无需 LZW。明细节点携带 `mainField=false`、`subTableId` 等信息；不能把它当成主表字段。操作符与现有条件构建器一致：eq/neq/gt/lt/range/aggregate/unaggregate/contains/uncontains/empty/nempty/startWith/endWith，支持原兼容别名。
-
-## 批量明细统计
-
-```bash
-e10-cli form list-stats detail <objId> <appId> <listId> <subFormId> --fields <金额fieldId> --name-prefix "付款-"
-```
-
-为指定数值字段分别生成 sum，并增加一项子表 count；一次保存。省略 `--fields` 时使用字段目录中该子表的全部数值字段。名称为“前缀+字段名+合计”和“前缀+子表名+记录数”。
-
-重复运行时，已有同名同配置项会复用并返回 `unchanged/reused`，不会重复新增；同名不同配置则报错，应先查询并明确移除旧项。批量操作同样可以使用 `--pc-only`。
-
-## 启用状态
-
-每条统计项**单独**有启用状态。建的时候可以直接建成停用：
-
-```json
-{ "fieldId": "1310832033224278033", "type": "sum", "name": "备用金额", "enable": false }
-```
-
-改**已有**项的启用状态用 `--enable` / `--disable`（逗号分隔统计项 ID）：
-
-```bash
-e10-cli form list-stats <objId> <appId> <listId> --disable 1310832033224278099
-e10-cli form list-stats <objId> <appId> <listId> --enable  1310832033224278099
-```
-
-⚠ `--add` 遇到**同名同配置**已存在的项会复用，**不会**顺带改它的启用状态 —— 要改就用 `--enable` / `--disable`。已经是目标状态时跳过、不算改动（重复执行返回 `unchanged`）。
-
-## 面板三项
-
-显示位置、手动加载统计值、点击统计结果过滤列表数据是**每视图一份**的统计面板设置：
-
-```bash
-# 显示位置：顶部显示 / 顶部简约显示 / 右上角显示（也收中文标签）
-e10-cli form list-stats <objId> <appId> <listId> --position topRight
-# 手动加载统计值（开了就不进视图自动跑）
-e10-cli form list-stats <objId> <appId> <listId> --manual-load on
-# 点击统计结果过滤列表数据
-e10-cli form list-stats <objId> <appId> <listId> --filter-data on
-```
-
-三项都是**三态**：`on|off`，**不传就是保持原值**，不会把没提到的开关覆盖掉。位置三档的取值 `top` / `topSimple` / `topRight` 对应界面上的「顶部显示 / 顶部简约显示 / 右上角显示」。
-
-⚠ **别被报文骗了**：设计器保存请求里带的 `statisticsPositionSpan` 是**陈旧值** —— 切到「顶部简约显示」或「右上角显示」时，请求体里仍然发「顶部显示」。但服务端读回来会**按 `position` 重算**成对应文案（`topSimple` → 顶部简约显示、`topRight` → 右上角显示）。命令两边都写死，发出去的报文自洽，并在回读时同时核对位置与文案。
-
-⚠ 面板三项只写 PC 侧，**不动移动端配置**。统计随 `listId` 共享，平台会把它同步到移动端读回；正因为如此，移动端一致性校验会把这四个面板键和 `statisticsList` 一起排除（它们的变化是共享造成的，不是「移动端其它配置被冲掉」）。
-
-## 条件里的日期快捷档
-
-统计条件的日期字段选「区间」时，可以直接用设计器那排快捷（今天 / 本周 / 今年 …，共 16 档）代替起止日期：
-
-```json
-{
-  "fieldId": "1310832033224278033",
-  "type": "sum",
-  "name": "今年付款额",
-  "conditions": [{ "fieldId": "<创建时间fieldId>", "quick": "今年" }]
-}
-```
-
-`quick` 与 `func` / `value` / `valueField` **互斥**（快捷档本身已经决定了区间）。口径与设计器一致：起点为首日 `00:00:00`、终点为末日 `23:59:59`，**周从周一起算**。
-
-⚠ 与设计器行为相同，落下来是**静态**起止日期（不是运行期动态刷新），每次执行按当时日期重算。中文标签在部分终端经命令行传参会遇到编码问题，此时可用英文别名（`thisYear` / `thisMonth` / `lastWeek` …）或 `--add @文件`。
-
-## 保存与移动端
-
-- 保留 PC 完整配置，仅更新 `listStatistics`；删除用 `operation: DELETE`，不能只从数组移除。
-- 读取真实移动端配置作为 `mConfig` 原样回传。默认移动端读取失败就停止；仅明确不使用移动端时加 `--pc-only`。
-- 保存后校验新增项、原有项、删除结果及移动端配置。`verified: true` 表示配置回读一致，不等于已经核对实际统计数值。
-- **维森测试93当前平台按 listId 共享 PC/MOBILE 统计项。** 当保存前后两端统计集合均对应一致时，返回 `mobileStatistics: "shared"`；改统计会同时影响两端。移动端独有统计丢失或其他配置变化仍报错。不要承诺共享环境下“只改 PC 统计”。
-- 比较移动端配置时，仅排除已实证每次读取会重建的按钮事件临时 ID，以及**随 `listId` 共享的统计项与统计面板键**（`statisticsList` / `statisticsPosition` / `statisticsPositionSpan` / `statisticsManualLoad` / `enableStatisticsFilterData`）；业务按钮 ID、动作内容、列配置等仍核对。`mobilePreserved` 表示移动端其余配置及独立统计得到保护。
-- 如果提示“已保存，但回读不一致”，先查询统计和移动端状态，不直接重试新增。
-
-## 计划与验收
-
-计划模板 3.3 的顶部统计项应记录：视图 ID、主表/明细范围、子表名称/ID、字段名称/ID、聚合方式、条件、格式、统计项 ID、PC/MOBILE 共享状态及验证结果。
-
-在“合同付款”视图验证：明细金额 sum、子表 count、明细条件、主表回归、重复运行、删除回读和移动端保护。不要改写用户已经配置的“合同付款金额”“付款记录数”；使用独立名称测试，结束清理临时项。实际金额与记录数须另用已知数据核对，不能仅凭保存成功认定数值正确。
+# 顶部统计：主表与明细
+
+`form list-stats` 配置已有台账视图的统计。支持 sum/count/avg/max/min，以及千分位、小数位、万/亿单位、条件统计；还能配**每条统计项的启用状态**与**统计面板三项**（显示位置 / 手动加载统计值 / 点击统计结果过滤列表数据）。来源表单 `objId`、应用 `appId`、目标视图 `listId` 与明细子表 `subFormId` 是不同 ID。
+
+## 查询及单项配置
+
+```bash
+e10-cli form list-stats <objId> <appId> <listId> --json
+e10-cli form list-stats <objId> <appId> <listId> --add @stat.json
+e10-cli form list-stats <objId> <appId> <listId> --remove <statId>
+```
+
+主表与明细字段均使用真实 fieldId；CLI 展开 `ds/fields` 的明细分组，未命中时按 `getFormField` 补查。字段必须属于当前表单，指定 subFormId 时必须与字段实际归属一致。
+
+付款金额统计示例：
+
+```json
+{
+  "fieldId": "1310832033224278033",
+  "type": "sum",
+  "name": "合同付款金额",
+  "decimalPlaces": "2",
+  "thousandths": true
+}
+```
+
+明细记录计数可省略 fieldId：
+
+```json
+{
+  "type": "count",
+  "subFormId": "1310832033224278030",
+  "name": "付款记录数"
+}
+```
+
+计数写为 `fieldId="5" + subFormId`，统计明细记录数。传明细字段做 count 也会转成该子表的记录计数，并非此字段非空值计数。主表记录计数可使用 `{"type":"count","name":"记录数"}`；已有传主表 fieldId 的用法继续接受。
+
+主表的 subFormId 写 `-1`，明细写实际子表 ID。**当前平台会将明细字段 sum 等字段聚合回读的 subFormId 规范化为 `-1`，仍由唯一 fieldId 定位明细字段；明细 count 必须保留子表 ID。** 回读校验兼容这种规范化，不允许字段或计数子表发生变化。
+
+格式参数：`thousandths` 为布尔值；`decimalPlaces` 为 -1 或 0–20 的整数；单位支持 `unit: "万"/"亿"` 或 `unitType: "none"/"tenThousand"/"hundredMillion"`。主表保持原默认小数位 -1，明细非计数默认 2，计数默认 -1。sum/avg 要求数值字段。
+
+## 条件统计
+
+```json
+{
+  "fieldId": "1310832033224278033",
+  "type": "sum",
+  "name": "正数付款金额",
+  "conditions": [
+    {"fieldId": "1310832033224278033", "func": "gt", "value": 0}
+  ]
+}
+```
+
+条件支持主表字段和本次统计子表字段，多个条件默认 AND。`valueField` 可引用字段 ID 或唯一名称，字段引用也校验子表归属。跨其他明细子表的条件拒绝保存，避免产生不明确的关联语义。
+
+条件写入明文 `rootdata`，无需 LZW。明细节点携带 `mainField=false`、`subTableId` 等信息；不能把它当成主表字段。操作符与现有条件构建器一致：eq/neq/gt/lt/range/aggregate/unaggregate/contains/uncontains/empty/nempty/startWith/endWith，支持原兼容别名。
+
+## 批量明细统计
+
+```bash
+e10-cli form list-stats detail <objId> <appId> <listId> <subFormId> --fields <金额fieldId> --name-prefix "付款-"
+```
+
+为指定数值字段分别生成 sum，并增加一项子表 count；一次保存。省略 `--fields` 时使用字段目录中该子表的全部数值字段。名称为“前缀+字段名+合计”和“前缀+子表名+记录数”。
+
+重复运行时，已有同名同配置项会复用并返回 `unchanged/reused`，不会重复新增；同名不同配置则报错，应先查询并明确移除旧项。批量操作同样可以使用 `--pc-only`。
+
+## 启用状态
+
+每条统计项**单独**有启用状态。建的时候可以直接建成停用：
+
+```json
+{ "fieldId": "1310832033224278033", "type": "sum", "name": "备用金额", "enable": false }
+```
+
+改**已有**项的启用状态用 `--enable` / `--disable`（逗号分隔统计项 ID）：
+
+```bash
+e10-cli form list-stats <objId> <appId> <listId> --disable 1310832033224278099
+e10-cli form list-stats <objId> <appId> <listId> --enable  1310832033224278099
+```
+
+⚠ `--add` 遇到**同名同配置**已存在的项会复用，**不会**顺带改它的启用状态 —— 要改就用 `--enable` / `--disable`。已经是目标状态时跳过、不算改动（重复执行返回 `unchanged`）。
+
+## 面板三项
+
+显示位置、手动加载统计值、点击统计结果过滤列表数据是**每视图一份**的统计面板设置：
+
+```bash
+# 显示位置：顶部显示 / 顶部简约显示 / 右上角显示（也收中文标签）
+e10-cli form list-stats <objId> <appId> <listId> --position topRight
+# 手动加载统计值（开了就不进视图自动跑）
+e10-cli form list-stats <objId> <appId> <listId> --manual-load on
+# 点击统计结果过滤列表数据
+e10-cli form list-stats <objId> <appId> <listId> --filter-data on
+```
+
+三项都是**三态**：`on|off`，**不传就是保持原值**，不会把没提到的开关覆盖掉。位置三档的取值 `top` / `topSimple` / `topRight` 对应界面上的「顶部显示 / 顶部简约显示 / 右上角显示」。
+
+⚠ **别被报文骗了**：设计器保存请求里带的 `statisticsPositionSpan` 是**陈旧值** —— 切到「顶部简约显示」或「右上角显示」时，请求体里仍然发「顶部显示」。但服务端读回来会**按 `position` 重算**成对应文案（`topSimple` → 顶部简约显示、`topRight` → 右上角显示）。命令两边都写死，发出去的报文自洽，并在回读时同时核对位置与文案。
+
+⚠ 面板三项只写 PC 侧，**不动移动端配置**。统计随 `listId` 共享，平台会把它同步到移动端读回；正因为如此，移动端一致性校验会把这四个面板键和 `statisticsList` 一起排除（它们的变化是共享造成的，不是「移动端其它配置被冲掉」）。
+
+## 条件里的日期快捷档
+
+统计条件的日期字段选「区间」时，可以直接用设计器那排快捷（今天 / 本周 / 今年 …，共 16 档）代替起止日期：
+
+```json
+{
+  "fieldId": "1310832033224278033",
+  "type": "sum",
+  "name": "今年付款额",
+  "conditions": [{ "fieldId": "<创建时间fieldId>", "quick": "今年" }]
+}
+```
+
+`quick` 与 `func` / `value` / `valueField` **互斥**（快捷档本身已经决定了区间）。口径与设计器一致：起点为首日 `00:00:00`、终点为末日 `23:59:59`，**周从周一起算**。
+
+⚠ 与设计器行为相同，落下来是**静态**起止日期（不是运行期动态刷新），每次执行按当时日期重算。中文标签在部分终端经命令行传参会遇到编码问题，此时可用英文别名（`thisYear` / `thisMonth` / `lastWeek` …）或 `--add @文件`。
+
+## 保存与移动端
+
+- 保留 PC 完整配置，仅更新 `listStatistics`；删除用 `operation: DELETE`，不能只从数组移除。
+- 读取真实移动端配置作为 `mConfig` 原样回传。默认移动端读取失败就停止；仅明确不使用移动端时加 `--pc-only`。
+- 保存后校验新增项、原有项、删除结果及移动端配置。`verified: true` 表示配置回读一致，不等于已经核对实际统计数值。
+- **维森测试93当前平台按 listId 共享 PC/MOBILE 统计项。** 当保存前后两端统计集合均对应一致时，返回 `mobileStatistics: "shared"`；改统计会同时影响两端。移动端独有统计丢失或其他配置变化仍报错。不要承诺共享环境下“只改 PC 统计”。
+- 比较移动端配置时，仅排除已实证每次读取会重建的按钮事件临时 ID，以及**随 `listId` 共享的统计项与统计面板键**（`statisticsList` / `statisticsPosition` / `statisticsPositionSpan` / `statisticsManualLoad` / `enableStatisticsFilterData`）；业务按钮 ID、动作内容、列配置等仍核对。`mobilePreserved` 表示移动端其余配置及独立统计得到保护。
+- 如果提示“已保存，但回读不一致”，先查询统计和移动端状态，不直接重试新增。
+
+## 计划与验收
+
+计划模板 3.3 的顶部统计项应记录：视图 ID、主表/明细范围、子表名称/ID、字段名称/ID、聚合方式、条件、格式、统计项 ID、PC/MOBILE 共享状态及验证结果。
+
+在“合同付款”视图验证：明细金额 sum、子表 count、明细条件、主表回归、重复运行、删除回读和移动端保护。不要改写用户已经配置的“合同付款金额”“付款记录数”；使用独立名称测试，结束清理临时项。实际金额与记录数须另用已知数据核对，不能仅凭保存成功认定数值正确。

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

@@ -1,156 +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、选用字段、字段映射、布局和视图。执行时依次销号数据源定位、主键校验、字段映射、创建、布局和视图配置。
+# 虚拟表创建与维护
+
+虚拟表把已有数据源的字段映射为 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、选用字段、字段映射、布局和视图。执行时依次销号数据源定位、主键校验、字段映射、创建、布局和视图配置。