weaver-e10-builder 1.0.12-beta → 1.1.1

package/skill-docs/references/form/guide-field-linkage.md

@@ -0,0 +1,121 @@
+# 字段联动（跨表带出赋值）指南
+
+## 概述
+
+字段联动（FormDataLinkage）：表单字段值改变时，自动查询**另一张表**（按数据ID=触发字段值过滤），把查到的字段值**带出赋值**到本表单字段。支持单跳（一次直接带出）和多跳链式（多次中转后带出）。
+
+背后是一个 ESB FieldLinkage 动作流（触发 + N 个 EnquiryForm 查询 + Output 赋值），CLI 自动完成建 ESB app + saveDesign + 绑定。
+
+## 三种联动对比
+
+| | 属性联动（显隐） | 关联表带出（form relate） | **字段联动（field-linkage）** |
+|---|---|---|---|
+| 命令 | `form linkage add` | `form relate` | `form field-linkage add` |
+| 接口 | viewlinkage | ffRelateField module:hrm | saveFormDataLinkage + saveDesign（ESB） |
+| 作用 | 改字段显示属性（hide/show/required） | 换 Employee/Department→带 HRM 属性 | **查任意表→带出任意字段赋值** |
+| 源 | 表单字段值条件 | Employee/Department（HRM 源） | 任意字段→任意表查询 |
+| 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表多跳，ESB 动作流） |
+| 关系 | — | — | **字段联动是关联表带出的进阶版** |
+
+## 何时用多跳
+
+**Text 字段赋值必须用名称（多跳），不能直接赋 ID。**
+
+| 场景 | 跳数 | 示例 |
+|------|------|------|
+| 带出字段是 EBuilder（存 ID）→ 目标也是 EBuilder | 单跳 | 关联合同→查合同信息表→带出关联客户（ID→EBuilder 字段） |
+| 带出字段存 ID → 目标是 Text（要名称） | **多跳** | 关联客户→查客户信息表→客户类型(ID)→查客户类型表→类型名称(Text)→填 Text 字段 |
+
+**判断原则**：目标字段是 EBuilder/Select（存 ID）→ 单跳即可；目标字段是 Text（要展示名称）→ 必须多跳到名称表取名称。
+
+## CLI 命令
+
+```bash
+# 列出
+e10-cli form field-linkage list <appId> <objId>
+
+# 回读单条
+e10-cli form field-linkage read <appId> <objId> <linkageId>
+
+# 查源表可带出字段
+e10-cli form field-linkage fields <appId> <formId>
+
+# 删除（批量）
+e10-cli form field-linkage delete <appId> <objId> <linkageId...>
+```
+
+### 新增（add）
+
+**单跳**（一次直接带出）：
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger <触发字段名> \
+  --source-form <目标表objId> \
+  --query-field <目标表带出字段名> \
+  --target <本表目标字段名>
+```
+
+**多跳**（多次中转后带出）：
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger <触发字段名> \
+  --target <本表目标字段名> \
+  --hops "<源表objId:带出字段名,源表objId:带出字段名,...>"
+```
+
+`--hops` 格式：每跳 `objId:字段名`，逗号分隔。前一跳的带出值 = 下一跳的过滤值（数据ID=前一跳结果）。最后一跳的带出值赋给 `--target`。
+
+## 配置示例
+
+### 示例1：单跳——关联合同→合同信息表→关联客户
+
+```
+关联合同(EBuilder→合同信息表) 值改变
+→ 查合同信息表 by 数据ID=关联合同
+→ 带出关联客户(EBuilder→客户信息表，存ID)
+→ 赋值到本表.关联客户(EBuilder字段，存ID)
+```
+
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger 关联合同 --source-form <合同信息表objId> --query-field 关联客户 --target 关联客户
+```
+
+### 示例2：多跳——关联客户→客户信息表→客户类型→客户类型表→类型名称→填Text
+
+```
+关联客户(EBuilder→客户信息表) 值改变
+→ Step1: 查客户信息表 by 数据ID=关联客户 → 带出客户类型(EBuilder→客户类型表，存ID)
+→ Step2: 查客户类型表 by 数据ID=客户类型(Step1结果) → 带出类型名称(Text)
+→ 赋值到本表.客户类型(Text字段，要名称不要ID)
+```
+
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger 关联客户 --target 客户类型 \
+  --hops "<客户信息表objId>:客户类型,<客户类型表objId>:类型名称"
+```
+
+### 示例3：链式联动（两条独立 linkage 串联）
+
+关联合同→(linkage1)→关联客户→(linkage2)→客户类型→(linkage3)→类型名称
+
+每条 linkage 的 `--trigger` 是上一条的 `--target`。分开 `add` 多次即可。
+
+## 查源表字段
+
+```bash
+# 查某表单有哪些可带出字段
+e10-cli form field-linkage fields <appId> <formId>
+```
+
+或用 `e10-cli form read <objId> --app-id <appId>` 取字段 fieldId（配置 --hops 时需知道字段名）。
+
+## 注意事项
+
+1. **Text 字段必须多跳取名称**：目标字段是 Text → 带出值必须是名称（文本），不能是 ID。如果源表存的是 ID（EBuilder/Select），需多跳到名称表取名称。
+2. **orgId 必须正确**：CLI 自动从 getForm 取 orgId，传给 application/save 建 ESB app。没有 orgId 的 app 不完整，saveDesign 会 500。
+3. **多跳 EnquiryForm 需要 sources**：非首跳的查询动作必须有 `sources` 指向前一跳，否则服务器报"有两个起始执行组件"（CLI 已处理）。
+4. **FormData 引用格式**：触发字段 `FormData.<本表formId>.<触发字段id>`；查询结果 `FormData.<源表objId>[].field_<带出字段id>`。
+5. **--hops 的 objId 是表单 objId**（不是 formId）。CLI 内部自动解析 objId→formId。
+6. **联动名称**：不传 `--name` 时自动生成 `<本表名>.<触发字段>→<最后源表名>.<最后带出字段>`。

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

@@ -0,0 +1,108 @@
+# 关联页签：目标视图、显示布局与数据筛选
+
+在来源表单的记录页面上新增关联页签，打开已有目标视图，并将当前记录字段作为筛选参数传入。例如：客户信息表 → “全部合同”页签 → 合同信息表的“全部合同”视图。
+
+## 配置前查询
+
+```bash
+e10-cli form association list <objId> <appId>
+e10-cli form association views <objId> <appId>
+e10-cli form association fields <objId> <appId> --view <viewId>
+e10-cli --json form association get <objId> <appId> <associationId>
+```
+
+- `objId` 是放置页签的来源表单，不是目标视图所属表单。
+- `views` 返回目标视图 ID、名称、所属表单。名称重复时必须传 ID。
+- `fields` 分别返回来源字段 `source` 与目标字段 `target`。不要把两端字段 ID 混用。
+- 跨应用通过 `--target-app <appId>` 显式选择，命令验证目标应用菜单树和视图实际归属。
+- `get --json` 的正确写法是全局 `--json`（如上），保留原始权限配置，并额外提供解析后的权限条件 `rules`。
+
+## 创建关联页签
+
+```bash
+e10-cli form association create <objId> <appId> "全部合同" --view <viewId> --layouts 显示 --terminals PC MOBILE --permissions @association-permissions.json --mappings @association-mappings.json
+```
+
+创建时必须明确权限。方案要求所有人可见时，`association-permissions.json` 可写：
+
+```json
+[
+  {
+    "selectedType": "all",
+    "dataid": "0",
+    "levelScope": {"minShowlevel": "", "maxShowlevel": ""},
+    "condition": {"rootdata": ""}
+  }
+]
+```
+
+不要在方案没有要求时默认采用所有人权限。其他组织、角色等权限按平台实际配置提供完整数组；本命令不推断权限对象。
+
+筛选映射文件格式：
+
+```json
+[
+  {"targetField": "关联客户", "sourceField": "客户名称"}
+]
+```
+
+每项含义为“目标视图字段 ← 当前来源记录字段”。支持字段 ID 或唯一显示名称，自动补全 `compType/fieldName/dataIndex` 等元数据。仅支持主表字段到主表字段的映射；明细字段及固定值筛选不在本次支持范围。
+
+上例复现抓包中的配置，不代表所有关联字段都应传名称。目标 EBuilder 字段可能需要记录 ID：应按业务语义选择 `sourceField: "数据ID"` 或指定字段，并用实际记录确认筛选结果。命令不会擅自把用户提供的名称字段改成 ID。
+
+默认启用，默认适用于 PC 和 MOBILE，默认仅显示布局。省略 `--mappings` 表示不添加关联参数；目标视图自身的筛选仍独立生效。创建检测同名页签，重复时停止，改用 `update`。
+
+## 显示布局与其他设置
+
+| 参数 | 含义 |
+|---|---|
+| `--layouts 显示` | `showLayout="0"`：打开显示布局，关闭编辑布局 |
+| `--layouts 编辑` | `showLayout="2"`：仅编辑布局 |
+| `--layouts 显示 编辑` | `showLayout="0,2"`：两种布局都显示 |
+| `--layouts none` | 两种布局均不显示 |
+| `--terminals PC MOBILE` | 两端适用；可只传其中一个 |
+| `--enabled true/false` | 启用或停用页签 |
+
+```bash
+e10-cli form association update <objId> <appId> <associationId> --layouts 显示
+e10-cli form association update <objId> <appId> <associationId> --name "相关合同" --terminals PC --enabled true
+e10-cli form association update <objId> <appId> <associationId> --view <newViewId> --mappings @association-mappings.json
+```
+
+`update` 保留未指定属性以及原动作、权限条件和提示。布局、终端参数表示替换对应集合。修改绑定视图且已有映射时必须显式提供新映射（`[]` 可清空），避免原目标表字段被用于新视图。
+
+## 修改和清空关联数据筛选
+
+```bash
+e10-cli form association set-filter <objId> <appId> <associationId> --mappings @association-mappings.json
+e10-cli form association clear-filter <objId> <appId> <associationId>
+```
+
+设置会替换目标动作的全部筛选映射。存在多个视图动作时，用 `--action <actionId>` 明确选择；只修改该动作，其余动作保留。
+
+这里处理的是 `associationActions[].url` 内的 `params`（`nameType/type=FORMFIELDS`），不会修改目标视图的全局过滤，也不会修改页签的权限条件。
+
+## 权限条件是另一项能力
+
+```bash
+e10-cli form association set-condition <objId> <appId> <associationId> --perm 1 --rules @permission-rules.json --logic or
+e10-cli form association clear-condition <objId> <appId> <associationId> --perm 1
+```
+
+这两条操作 `associationPermissions[].condition.rootdata`，规则格式为 `[{"fieldId":"...","func":"contains","value":"..."}]`。`--perm` 为 1 开始的序号或 `selectedType`；支持 `and/or`。此条件按来源表单字段生成，与“目标视图数据筛选映射”分别配置。
+
+平台权限条件读回是明文 JSON，写入需 LZW 压缩。更新布局或数据筛选时也会重新压缩原有权限条件；不要自行传入压缩字符串。
+
+## 验证与计划
+
+保存后回读目标视图、筛选映射、显示布局、终端、动作和权限相关配置，成功输出 `verified: true`。创建响应可能不带顶层 ID，命令通过列表差集和详情确定新关联 ID。若提示已提交但无法匹配，先 `list/get`，不要直接再次创建。
+
+配置回读不等于验证了浏览器展示或实际筛选结果。验收还应打开来源记录的显示/编辑布局，检查页签显示范围，并用已知关联与非关联记录检查目标视图结果。
+
+在计划模板 3.3 中逐项填写：
+
+- 关联页签：来源表单/objId、页签名称/associationId、目标应用/表单/视图 ID、权限依据。
+- 布局与终端：显示布局是否开启、编辑布局是否开启、PC/MOBILE、启用状态。
+- 数据筛选：每条目标字段 ← 来源字段，注明传记录 ID 还是字段值，以及配置回读和实际结果验收情况。
+
+先创建目标视图，再创建依赖它的关联页签；关联 ID、视图 ID、动作 ID 不能互换。未验证的项保留待办，不预先打勾。

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

@@ -0,0 +1,54 @@
+# 台账视图按钮显示位置
+
+用于将已有系统按钮或自定义按钮显示在指定视图的行上、行末下拉或顶部。配置的是按钮 `showPosition`，与整行点击的 `form list-event`、字段点击的 `form list-click` 独立。
+
+## 查询与设置
+
+```bash
+e10-cli form button list <objId> <appId>
+e10-cli form button views <objId> <appId> <buttonId>
+e10-cli form button position <objId> <appId> <buttonId> --view <listId> --position 行上
+```
+
+`views` 返回平台 `getViewDatas` 对此按钮开放的视图，以及现有位置配置。`--view` 支持视图 ID、唯一名称、表单页语义“新建/编辑/显示”；多个同名视图必须用 ID。省略视图或使用“台账”时，必须只有一个可选台账，否则拒绝保存。
+
+| 显示位置 | 平台值 |
+|---|---|
+| 右上 | `rightTop` |
+| 右上下拉 | `rightTopDropDown` |
+| 行上（行内） | `lineEnd` |
+| 行末下拉 | `LineEndDropDown` |
+
+行上、行末下拉只适用于台账，不适用于表单新建/编辑/显示页。
+
+## 多视图及替换语义
+
+普通设置默认合并：仅更新指定视图，保留其余台账及表单页的位置。同一视图的旧位置数组由此次指定的位置数组替换；需要多位置时一次传齐。
+
+```bash
+e10-cli form button position <objId> <appId> <buttonId> --view <listId> --position 行上 右上
+e10-cli form button position <objId> <appId> <buttonId> --show-position @button-positions.json
+```
+
+不同视图使用不同位置时，JSON 文件示例（将 ID 占位替换为实际值）：
+
+```json
+{
+  "<listIdA>_table": ["lineEnd"],
+  "<listIdB>_table": ["LineEndDropDown"],
+  "show_form": ["rightTop"],
+  "edit_form": ["rightTopDropDown"]
+}
+```
+
+`--show-position` 也默认合并，不能与 `--position/--view` 同时使用。显式 `--replace` 才替换全部页面配置；未列出的页面不再显示该按钮。`--show-position '{}' --replace` 清空所有显示位置。
+
+新建自定义按钮也支持 `form button add ... --view <listId> --position 行上`。按钮点击动作仍由原有动作配置决定；改变显示位置不会自动添加行数据参数。
+
+## 保存与验证
+
+命令先分页查找按钮，再读取动作、权限和可选视图。提交时保留按钮基础配置、完整动作和权限，及接口返回的日志/自定义提示设置，并按视图实际名称重建 `showPositionSpan`。
+
+保存后回读按钮位置并核对动作、权限 ID 集合；成功输出 `verified: true`。若提示“已保存，但回读不一致”，远端可能已修改，必须先重新查询再处理。该验证属于配置回读，不代表已验证按钮点击行为或浏览器渲染。
+
+计划模板 3.3 中必须记录：按钮名称/ID、目标视图名称/ID、显示位置、验证结果。只有需求涉及按钮展示时才填写，无需求标“— 无”。系统删除按钮测试仅核对配置和显示，不点击删除业务数据。

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

@@ -5,9 +5,19 @@
 ## 需求判别
 
 - “新建表单” → `form create --fields`。
-- “在已有表单下新增表格视图” → `form table-view create`；命令必须同时保存显示列并回读。
+- “客户信息表需要一个客户信息视图”等普通列表需求 → 先查询并复用该表单默认台账；“客户信息表”和“客户信息”的名称差异不构成额外新建理由。
+- “在已有表单下明确新增一个额外表格视图” → `form table-view create`；命令必须同时保存显示列并回读。
 - “在已有表单下新增表单视图” → `form view create --type formView`，随后必须 `form view populate`；不得新建另一张表单。
 
+## 默认台账复用
+
+1. 用 `form list-view <objId> <appId>` 查询已有列表，确认目标属于当前表单且用途符合需求，记录实际名称和 listId。存在多个候选时核对数据范围、权限和展示配置，不仅凭名称或第一条记录选择。
+2. 普通列表需求直接在该 listId 上配置显示列、筛选、排序、统计和事件；需要整组配置显示列时用 `form list-columns <objId> <appId> <listId> --set @columns.json`。`table-view ensure` 只用于空列补齐，不负责视图选择或重命名。
+3. 默认保留平台生成的名称，不统一去掉末尾“表”字。用户明确要求名称对齐时应改已有视图名称并保留 ID；目前 CLI 未提供视图重命名命令，不能用新建同用途视图代替改名。表单名、视图名和菜单名分别处理。
+4. 只有明确需要“我的客户”“重点客户”等额外独立视图，或不同展示类型时，才进入新增流程。已有重复视图需先核对菜单、关联页签等引用及配置，不能自动删除。
+
+例如：已建“客户信息表”，方案中的“客户信息视图”可由其默认台账满足，plan 标记“复用默认台账”，填写实际 listId 即可。
+
 ## 命令
 
 ```bash
@@ -52,10 +62,10 @@ e10-cli form view create <objId> <appId> "交付日历" \
 
 `tableView`/`nListView` 不得传给普通视图命令。真实表格视图固定使用 `form table-view create`。
 
-## 表格视图固定闭环
+## 额外表格视图新建闭环
 
 ```bash
-# 1. 确认目标表单和同名列表不存在
+# 1. 已确认需要额外独立视图，再查询目标表单和已有列表
 e10-cli form list <appId>
 e10-cli form list-view <objId> <appId>
 
@@ -66,7 +76,7 @@ e10-cli --json form table-view create <objId> <appId> "<表格视图名>" --pc-o
 e10-cli --json form list-view <objId> <appId>
 ```
 
-命令先用 `viewType=nListView` 创建，再以新 `listId` 读取 PC 配置；业务列必须取自 `/api/ebuilder/common/ds/fields` 的完整字段对象，不能只拼字段 ID。保存时保留服务端配置和隐藏主键 `id=5`，最后回读 `tableField` 和列表实体。已有同名视图时停止，不盲目重建。
+命令先用 `viewType=nListView` 创建，再以新 `listId` 读取 PC 配置；业务列必须取自 `/api/ebuilder/common/ds/fields` 的完整字段对象，不能只拼字段 ID。保存时保留服务端配置和隐藏主键 `id=5`，最后回读 `tableField` 和列表实体。命令只拦截完全同名的视图，不识别简称或业务用途；执行前必须完成复用判断，不能因名称未完全匹配就新建。已有同名视图时停止，不盲目重建。
 
 `--pc-only` 只用于已确认本次验收为 PC 的场景。未指定时，命令必须取得真实 MOBILE 配置，禁止用 PC 配置推导移动端。
 
@@ -144,15 +154,19 @@ e10-cli --json form table-view search-field configure \
 
 ## 台账显示列/搜索/排序/统计/视图数据条件/行事件/启用分组/视图权限/分类搜索（list-columns / list-search / list-sort / list-stats / list-filter / list-event / list-group / list-permission / list-search-group）
 
-直接改默认台账（nListView）的显示列、搜索条件、排序、顶部统计、视图数据条件。listId 取 `form list-view` 返回的列表视图 ID。这些命令都只改 PC 端，**保存时先读回真实移动端 mConfig 原样回传，不会清空移动端**（`saveNListConfig` 一次请求里 `config`→PC 端、`mConfig`→移动端，两端列集合/uid 各自独立）。只有明确目标只使用 PC、移动端配置确实不存在时，才加 `--pc-only`。
+直接改默认台账（nListView）的显示列、搜索条件、排序、顶部统计、视图数据条件。listId 取 `form list-view` 返回的列表视图 ID。默认改 PC 端；`list-columns --terminal mobile` 可改移动端显示列。**保存时先读回真实移动端 mConfig 原样回传，不会清空移动端**（`saveNListConfig` 一次请求里 `config`→PC 端、`mConfig`→移动端，两端列集合/uid 各自独立）。只有明确目标只使用 PC、移动端配置确实不存在时，才加 `--pc-only`。
 
 ```bash
 # 查看当前显示列
 e10-cli form list-columns <objId> <appId> <listId>
 
-# 追加字段到显示列 / 移除字段
-e10-cli form list-columns <objId> <appId> <listId> --add <fieldId>
-e10-cli form list-columns <objId> <appId> <listId> --remove <fieldId>
+# 批量追加字段到显示列 / 移除字段
+e10-cli form list-columns <objId> <appId> <listId> --add <fieldId1> <fieldId2>
+e10-cli form list-columns <objId> <appId> <listId> --remove <fieldId1> <fieldId2>
+
+# 按文件完整设置业务列顺序、宽度和格式（未列入的业务列会移除）
+e10-cli form list-columns <objId> <appId> <listId> --set @columns.json --json
+# 详见 references/form/guide-list-columns.md
 
 # 列显示格式：千分位/小数位（Number/Money 列，走列对象 format/decimalLength）
 e10-cli form list-format <objId> <appId> <listId> <fieldId> --thousandths --decimal 2
@@ -169,6 +183,9 @@ e10-cli form list-search <objId> <appId> <listId> --quick <fieldId1> <fieldId2>
 e10-cli form list-sort <objId> <appId> <listId> --field <fieldId1> <fieldId2> --order ASC
 e10-cli form list-sort <objId> <appId> <listId> --clear
 
+# 主表/明细统计完整指南：references/form/guide-list-stats.md
+# 明细 count 支持只填 type/subFormId；批量入口：form list-stats detail
+# PC/MOBILE 可能共享统计项；以保存后的 mobileStatistics 为准，不能承诺只影响 PC
 # 顶部统计：type=sum 求和 / count 计数 / avg 平均 / max 最大 / min 最小
 # 可选：thousandths=true 千分位 / decimalPlaces="2" 小数位 / unit="万" 单位（unitType=tenThousand）
 e10-cli form list-stats <objId> <appId> <listId> --add '{"fieldId":"...","type":"sum","name":"合同总金额","thousandths":true,"decimalPlaces":"2","unit":"万"}'
@@ -232,7 +249,7 @@ e10-cli form list-search-group <objId> <appId> <listId> --remove <fieldId>
 e10-cli form list-search-group <objId> <appId> <listId> --clear
 ```
 
-字段 ID 来自 `form read <objId> --app-id <appId>` 或 `form list-columns` 当前列（系统列如 `2`创建者/`3`创建时间/`5`数据ID 也可增删）。保存成功后命令打印 `移动端配置: 保持原样` 即确认移动端未被触碰。
+字段 ID 来自 `form read <objId> --app-id <appId>` 或 `form list-columns` 当前列（系统列如 `2`创建者/`3`创建时间也可增删；`5`数据ID主键自动保留，禁止移除）。显示列命令保存后回读校验，`otherTerminalPreserved:true` 表示另一终端配置核对一致。
 
 ## formView 固定闭环
 

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

@@ -0,0 +1,52 @@
+# 台账显示列批量配置
+
+适用于已有 `nListView`、`multiView` 的显示列。`listId` 取 `form list-view <objId> <appId>`；新建表格视图仍使用 `form table-view create`。关联浏览框的显示字段使用 `form ebuilder-columns`。
+
+## 查看、追加、移除
+
+```shell
+e10-cli form list-columns <objId> <appId> <listId> --json
+e10-cli form list-columns <objId> <appId> <listId> --add <字段ID1> <字段ID2> --json
+e10-cli form list-columns <objId> <appId> <listId> --remove <字段ID1> <字段ID2> --json
+```
+
+`--add` 按输入顺序追加到隐藏主键之前，已存在的列复用原配置；重复执行且无变化时返回 `unchanged:true`，不保存。`--remove` 可与 `--add` 同时使用，但不能对同一字段同时增删。移除不存在的列会报错；数据主键禁止移除。
+
+## 一次设置顺序、宽度和格式
+
+先读取当前列，按需求生成 UTF-8 的 `columns.json`。数组表示**完整业务列清单**：未列入的业务列会移除；数组顺序就是显示顺序。字段 ID 使用字符串，支持 `fieldId` 或 `id`，也支持仅填 ID 字符串。
+
+```json
+[
+  {"fieldId":"1310832462830059523","width":220},
+  {"fieldId":"1310832462830059527","width":150,"format":"yyyy-MM-dd"},
+  {"fieldId":"1310832462830059528","width":150,"format":"THOUSANDS","decimalLength":2}
+]
+```
+
+```shell
+e10-cli form list-columns <objId> <appId> <listId> --set @columns.json --json
+```
+
+示例 ID 来自维森测试93项目任务表，其他表单需替换。`--set` 不能与增删选项混用；空数组只保留数据主键。配置文件不是原始 `tableField` 快照，不要填隐藏主键、uid、eventGroup 等内部属性。
+
+| 属性 | 语义 |
+|---|---|
+| `fieldId` / `id` | 必填，当前表单的字段 ID，不可重复 |
+| `text` | 非空显示名称 |
+| `width` | 正数列宽，新列默认 150 |
+| `format` | 日期格式或数值 `THOUSANDS`；`null` 清除 |
+| `decimalLength` | 0–20 整数；`null` 清除 |
+| `hidden` | 是否隐藏业务列，布尔值 |
+| `viewDataDetail` | 是否显示关联数据详情，布尔值 |
+
+已有列只覆盖明确提供的属性，未指定的格式、单位、点击事件、uid 等保留；新列从字段元数据构造。明细子字段从 `ds/fields` 嵌套目录解析，必要时 `getFormField` 补查；设置 `mainField:false`，不带明细展开容器属性。不能把明细子表容器作为普通列添加。
+
+## 保存与验收
+
+- 默认改 PC，可用 `--terminal mobile` 修改移动端 `tableField`；移动端卡片布局的 `listField/cardLayout` 不属于此命令。
+- 全部字段与参数解析成功后，只调用一次 `saveNListConfig`。先读取真实 PC/MOBILE 配置，另一终端原样回传；读取失败默认中止。仅明确只用 PC 时允许 `--pc-only`，此时若移动端读取失败，结果标明未保留校验。
+- 自动保留隐藏数据主键，缺失时补齐。保存后回读核对列 ID、顺序、属性以及另一终端配置；仅忽略平台每次读取重新生成的按钮动作/事件 ID。
+- `verified:true` 表示接口回读通过。回读不一致时返回错误，保存可能已发生，应读取配置定位差异后处理；页面实际显示仍按需求验收。
+
+计划模板的「台账/视图配置 → 显示列批量设置」记录目标视图、终端、增量或整组模式、字段顺序、宽度/格式、配置文件路径与回读/页面验收结果。

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

@@ -0,0 +1,83 @@
+# 顶部统计：主表与明细
+
+`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`。
+
+## 保存与移动端
+
+- 保留 PC 完整配置，仅更新 `listStatistics`；删除用 `operation: DELETE`，不能只从数组移除。
+- 读取真实移动端配置作为 `mConfig` 原样回传。默认移动端读取失败就停止；仅明确不使用移动端时加 `--pc-only`。
+- 保存后校验新增项、原有项、删除结果及移动端配置。`verified: true` 表示配置回读一致，不等于已经核对实际统计数值。
+- **维森测试93当前平台按 listId 共享 PC/MOBILE 统计项。** 当保存前后两端统计集合均对应一致时，返回 `mobileStatistics: "shared"`；改统计会同时影响两端。移动端独有统计丢失或其他配置变化仍报错。不要承诺共享环境下“只改 PC 统计”。
+- 比较移动端配置时，仅排除已实证每次读取会重建的按钮事件临时 ID；业务按钮 ID、动作内容、列配置等仍核对。`mobilePreserved` 表示移动端其余配置及独立统计得到保护。
+- 如果提示“已保存，但回读不一致”，先查询统计和移动端状态，不直接重试新增。
+
+## 计划与验收
+
+计划模板 3.3 的顶部统计项应记录：视图 ID、主表/明细范围、子表名称/ID、字段名称/ID、聚合方式、条件、格式、统计项 ID、PC/MOBILE 共享状态及验证结果。
+
+在“合同付款”视图验证：明细金额 sum、子表 count、明细条件、主表回归、重复运行、删除回读和移动端保护。不要改写用户已经配置的“合同付款金额”“付款记录数”；使用独立名称测试，结束清理临时项。实际金额与记录数须另用已知数据核对，不能仅凭保存成功认定数值正确。