weaver-work-cli 0.1.23 → 0.1.25

package/skills/weaver-e10-builder/references/form/guide-formula-linkage.md

@@ -0,0 +1,281 @@
+# 函数联动（本表字段间的公式赋值）指南
+
+## 概述
+
+函数联动：在**本表单内部**，当某个字段变化（或表单载入）时，用一张**公式**算出结果，赋值给本表的另一个字段。
+
+例：`数量` 或 `单价` 变化时 → `销售金额 = 数量 × 单价`。
+
+设计器里的位置是字段属性面板的「函数联动」，要配四件事：**在哪生效**（生效维度）、**什么时候触发**（触发时机，**可以挂多个**）、**谁触发**（触发字段）、**赋值给谁 + 怎么算**（目标字段 + 函数体）。
+
+> **不跨表。** 要查另一张表把值带回来，那是 `form field-linkage`（跨表带出），见 `guide-field-linkage.md`。
+
+## 四套联动对比
+
+| | 属性联动（显隐） | 关联表带出 | **字段联动（跨表带出）** | **函数联动（本表赋值）** |
+|---|---|---|---|---|
+| 命令 | `form linkage add` | `form relate` | `form field-linkage add` | `form formula-linkage add` |
+| 取值靠 | — | HRM 源 | ESB 动作流（查另一张表） | **一张公式** |
+| `linkageType` | （另一套存储） | — | `template` | `excel` |
+| 做的事 | 改字段显示属性 | 换 Employee/Department→带 HRM 属性 | 查任意表→带出字段赋值 | **本表字段→算→赋给本表字段** |
+| 跨表 | 否 | 否 | **是** | 否 |
+
+四者可以叠加：同一个字段既可以有显隐联动，也可以被函数联动赋值。
+
+## 赋值式：公式长什么样
+
+落库的 `expressSql` 是一条**赋值式**，左边是目标字段、右边是函数体：
+
+```
+{主表.销售金额}=VALUE({主表.数量})*VALUE({主表.单价})
+```
+
+CLI 的 `--expression` **只给右边**就行，左边的 `{主表.<目标>}=` 会自动拼上。
+
+从设计器里整段复制也行 —— 如果表达式里已经有赋值式，CLI 会校验它的左侧与 `--target` 是否指向同一字段：一致就沿用，不一致就**报错中止**（不会偷偷改目标）。
+
+> ⚠ **一个等号是赋值，两个等号才是比较 —— 两个层次别写反。**
+> - **顶层**那个 `=` 是「赋给谁」：`{主表.销售金额}=…`。**一个等号**。
+> - **函数体内部**做判断要用 `==`：`IF({主表.状态}=="已完成", 1, 0)`。**两个等号**。
+>
+> 函数体里写成单个 `=` 不报错，只是按赋值语义走、算出来不对。另：**函数名必须大写**（自定义 JS 脚本函数除外）、**跨表粘贴的公式要把 `{主表.X}`/`{明细表.X}` 逐个换成本表字段**、**选项型控件要比就得引用选项本身**（`{主表.性别}=={主表.性别.男}`，写成 `=='男'` 恒不成立）—— 合看 `guide-form-formula-functions.md` 的「写公式前先记住这几条」。
+
+### 字段引用的两种写法
+
+| 写法 | 场景 |
+|---|---|
+| `{主表.字段名}` / `{明细表名.字段名}` | 平台存储格式，整段复制来的就是这种 |
+| `[字段名]` / `[表名.字段名]` | 设计器编辑器里的显示格式 |
+
+两种都收，保存前统一归一化成花括号再下发（原样发方括号会静默失效，见 `guide-form-formula-functions.md`）。
+
+**函数体里不要出现裸方括号** —— 解析器把任何 `[...]` 都当字段引用，`SUBSTR("a[1]",…)` 这种会被当成找不到的字段。
+
+## 模块字段（系统字段）
+
+`{主表.主表数据id}`、`{主表.当前日期}`、`{主表.操作者部门}` 这类是**系统模块字段**，可以出现在公式右边，也能当触发字段，但**不能作为赋值目标**。
+
+原因很直白：平台在公式的 `extendParam.unSupportTargets` 里把这 21 个字段列成了「不可赋值」，而 CLI 就用这份清单做判据 —— 传了模块字段当 `--target` 会当场报错，不会建出一条平台不认的规则。
+
+两种写法都能用：
+
+```
+{主表.主表数据id}      ← 裸标签，平台存储格式
+[formDataId]          ← 语义键，等价；归一化后仍写成裸标签
+```
+
+`form formula-linkage columns` 会把两桶分开列：业务字段（可作目标）+ 系统模块字段（不可作目标）。
+
+## CLI 命令
+
+```bash
+# 看有哪些事件可选（值改变时 / 载入时 / 创建数据时 …）
+e10-cli form formula-linkage events <appId> <objId>
+
+# 看有哪些字段可用（业务字段 / 系统模块字段分两桶）
+e10-cli form formula-linkage columns <appId> <objId>
+e10-cli form formula-linkage columns <appId> <objId> --keyword 金额
+
+# 列出/回读（read 带公式表达式与参数）
+e10-cli form formula-linkage list <appId> <objId>
+e10-cli form formula-linkage read <appId> <objId> <linkageId>
+
+# 新增
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField \
+  --trigger 数量 --trigger 单价 \
+  --target 销售金额 \
+  --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+
+# 改（只传要改的；--event/--trigger 不传就沿用现有的）
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --trigger 产品类别
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --state off
+e10-cli form formula-linkage update <appId> <objId> <linkageId> --name "重算金额"
+
+# 删除（批量）
+e10-cli form formula-linkage delete <appId> <objId> <linkageId...>
+```
+
+### add 的参数
+
+| 参数 | 说明 |
+|---|---|
+| `--target <字段>` | **赋值目标**，被写入的字段。只能是业务字段 |
+| `--expression <函数体>` | 公式右侧。含引号/换行时可用 `@文件路径` |
+| `--event <事件...>` | **触发时机，可给多个**（一条联动能挂多个）。每个可自带触发字段：写 `事件名或 type`，或 `类型:字段,字段`。默认 `changeField`（值改变时） |
+| `--trigger <字段...>` | 触发字段，可多个。作用于**没有自带字段**的字段级事件；表单级 / 流程级事件不用给 |
+| `--effect <维度>` | 生效维度：`form`（默认，当前表单）/ `formLayout`（表单布局）/ `workFlow`（当前工作流）/ `includeNode`（选择节点，另需 `--node`）。后两者必给 `--workflow-id` |
+| `--name <名>` | 联动名。默认 `<公式名> - 公式_<时间戳>` |
+| `--formula-name <名>` | 公式名，默认取表单名 |
+| `--formula-id <id>` | 复用/更新已有公式，不新建 |
+
+### 生效维度（`--effect`）
+
+| 维度 | `--effect` | 生效范围 |
+|---|---|---|
+| 当前表单（默认） | 不传 或 `form` | 该表单的**所有布局**，以及所有关联了该表单的工作流 |
+| 表单布局 | `formLayout` | **只对选定的那一个布局** |
+
+```bash
+# 只在这个布局上生效
+e10-cli form formula-linkage add <appId> <objId> --effect formLayout \
+  --event changeField --trigger 数量 --target 销售金额 \
+  --expression "VALUE({主表.数量})"
+```
+
+> ⚠ 布局 id 取的是 `getFormLayout` 返回的 **`multipleLayoutId`**，不是 `formLayout.id` —— 同一张表上这两个值相邻但不同（如 `…375` / `…376`），**发错不报错，只是指向另一个布局**，回读时生效范围会是个空白。CLI 走的是与显隐联动同一套解析（`resolveEffect`），不用手填 id。
+
+### 触发事件
+
+| 分组 | 事件 | type | 要触发字段 |
+|---|---|---|---|
+| 字段 | 值改变时 / 获取输入焦点时 / 失去输入焦点时 / 鼠标单击时 / 鼠标双击时 | `changeField` / `onfocus` / `onblur` / `onclick` / `ondbclick` | 要 |
+| 表单 | 载入时 / 载入时(可编辑) / 载入时(新建) / 创建数据时 / 窗口滚动时 | `onLoadForm` / `onLoadFormEdit` / `onLoadFormCreate` / `createData` / `onscroll` | 不要 |
+| 流程 | 提交/批准时 / 转发时 / 保存时 / 退回时 / 转办时 / 意见征询时 / 传阅时 | `EVENT_SUBMIT_OR_AGREE` / `EVENT_FORWARD` / `EVENT_SAVE_DATA` / `EVENT_REJECT` / `EVENT_TURNTODO` / `EVENT_REMARKADVICE` / `EVENT_CIRCULATE` | 不要 |
+
+⚠ **「流程」那一组默认列不出来**：`form formula-linkage events` 不给 `--effect` 时只列前两组 10 个，加 `--effect workFlow --workflow-id <流程id>` 才列得出 17 个。用了流程事件就要把生效维度也设成「当前工作流 / 选择节点」——两者的关系不是可选的；换个维度又沿用旧事件时 CLI 会直接报错拦下。
+
+### 一条联动挂多个触发时机
+
+「触发时机」**不是单选**：设计器里勾几个，`monitorActions` 就存几条。
+
+```bash
+# 7 个流程时机一起挂（都不需要触发字段）
+e10-cli form formula-linkage add <appId> <objId> --effect workFlow --workflow-id <wf> \
+  --event EVENT_SUBMIT_OR_AGREE EVENT_FORWARD EVENT_SAVE_DATA \
+  --target 登记时间 --expression '{主表.当前日期}'
+
+# 各配各的触发字段：值改变时看「数量、单价」，鼠标单击时看「按钮」
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField:数量,单价 onclick:按钮 \
+  --target 销售金额 --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+
+# 老写法照旧：--trigger 给所有「没自带字段」的字段级事件
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField onclick --trigger 数量 \
+  --target 销售金额 --expression "VALUE({主表.数量})"
+```
+
+## 示例
+
+### 金额 = 数量 × 单价（两个触发字段）
+
+```bash
+e10-cli form formula-linkage add <appId> <objId> \
+  --event changeField --trigger 数量 --trigger 单价 \
+  --target 销售金额 \
+  --expression "VALUE({主表.数量})*VALUE({主表.单价})"
+```
+
+### 编号 = 数据ID + 订单号（引用系统模块字段）
+
+```bash
+e10-cli form formula-linkage add <appId> <objId> \
+  --event onLoadFormCreate \
+  --target 订单编号 \
+  --expression 'CONCAT({主表.主表数据id},{主表.订单编号})'
+```
+
+### 载入时赋当前日期（表单级事件，不给 --trigger）
+
+```bash
+e10-cli form formula-linkage add <appId> <objId> \
+  --event onLoadForm --target 登记日期 --expression '{主表.当前日期}'
+```
+
+## 注意事项
+
+> 公式**语言本身**的硬规则（函数名必须大写 / 比较用 `==` / 赋值用 `=` / 跨表粘贴要换字段变量）在 `guide-form-formula-functions.md` 的「写公式前先记住这四条」，写表达式前先过一遍 —— 这几条写错**不报错**，只是算不对。
+
+1. **目标只能是业务字段**。系统模块字段（`主表数据id`/`当前日期`/`操作者部门` 等 21 个）不能作 `--target`，但可以出现在公式右边、也可以当触发字段。
+2. **一个触发时机 × 一个触发字段 = 一条触发动作**。多个触发字段 → N 条 `actionType` 相同的动作；多个触发时机 → 多条 `actionType` 各异的动作。平台侧就是这张表，不是一条里挂 N 个字段 —— CLI 已按这个形状下发。**`update` 不给 `--event`/`--trigger` 时原样沿用现有的触发时机**，不会只留第一条。
+3. **触发字段与目标不能搞反**。`--trigger` 是「谁变了」，`--target` 是「谁被写」。写反了规则会反向生效，回读时表达式左边能看到真实目标。
+4. **字段名有歧义会报错**，不会默认取第一条。两张明细表里各有一个「编号」时，写 `编号` 会列出两个候选，改用字段 id 或 `明细表名.编号`。
+5. **业务字段与模块字段同名时**（如业务字段叫「标题」、模块字段 `name` 的标签也叫「标题」），按裸标签写会报歧义，用字段 id 或完整列名 `主表.标题` 区分。
+6. **生效范围四种**：缺省「当前表单」（所有布局 + 所有关联该表单的工作流）、`--effect formLayout`（只对某个布局生效）、`--effect workFlow`（当前工作流，需 `--workflow-id`）、`--effect includeNode`（选择节点，需 `--workflow-id` + `--node`）。布局 id 由 CLI 现查（见上「生效维度」）。`update` 不传 `--effect` 会沿用现有维度 —— 但**在「表单/布局」与「工作流/节点」之间换维度时必须同时给 `--event`**，否则会存出一条事件与维度对不上的坏规则。
+7. **改了公式不会同步 `inFields`/`outFields`**。平台的数据源上带这两组字段（公式用到的来源字段 / 被赋值的字段），它们反映的是**建这条联动时**的公式；后来改公式它们不跟着变。这不影响运行，但别拿它当「当前公式用了哪些字段」的依据 —— 用 `form formula-linkage read` 看表达式。
+8. **`form field-linkage` 看不见这类联动**。两者 `linkageType` 不同（`excel` vs `template`），各查各的。`form field-linkage list` 末尾会提示「另有 N 条函数联动」；`form field-linkage delete` 传函数联动的 id 会直接报错指路，不会静默删 0 条。
+9. **`--event` 里 `类型:字段,字段` 的分隔符只认半角 `:` 与 `,`**（全角「：」「，」不作分隔）。字段名里真含半角逗号时会被切坏 —— 那种字段改用 `--trigger`（空格分隔），或直接写字段 id。
+
+## 流程表单上的函数联动（`wf-form formula-linkage`）
+
+流程表单也支持函数联动，是**同一能力的另一条路由**。命令面与 eb 表逐字对齐，只有位置参数和多出来的选项不同：
+
+```bash
+wf-form formula-linkage list   <formId> --workflow-id <id>
+wf-form formula-linkage read   <formId> --workflow-id <id> <linkageId>
+wf-form formula-linkage events <formId> --workflow-id <id>
+wf-form formula-linkage columns<formId> --workflow-id <id>
+wf-form formula-linkage add    <formId> --workflow-id <id> --target <字段> --expression <函数体> [...]
+wf-form formula-linkage update <formId> --workflow-id <id> <linkageId> [...]
+wf-form formula-linkage delete <formId> --workflow-id <id> <linkageIds...>
+```
+
+`--workflow-id` 一个旗标管两件事：**`refId`**（这条联动挂在流程上）+「当前工作流 / 选择节点」两个维度的取值来源。不给就按 `formId` 兜底（查不到时先补上它）。流程 ID 用 `workflow search --name <流程名>` 拿。
+
+### 两条路由的差异
+
+| | eb 表 `form formula-linkage` | **流程表单 `wf-form formula-linkage`** |
+|---|---|---|
+| 位置参数 | `<appId> <objId>` | **`<formId>`** + `--workflow-id` |
+| 联动端点 | `/api/ebuilder/form/form/linkage` | `/api/ebuilder/flow/form/linkage`（**不带 `?apid=`**） |
+| `module` | `ebuilderform` | **`ebuildercard`** |
+| 定位入参 | `customParam: {appId, objId}`（读、存都发） | **顶层 `refId` = workflowId**；`customParam: {scene:'workflow'}` **只在读的时候发，保存报文里没有这个键** |
+| 公式参数里的 `appId` | 有 | **没有这个键** |
+| 不可作赋值目标的系统字段 | 21 项 | **30 项**（模块字段桶是 32 —— 差的两个见下） |
+| 触发事件 | 默认 10 个（字段组 5 + 表单组 5）；生效维度给 `workFlow`/`includeNode` 时取流程那套 = **17 个** | **恒 17 个**（这条路由一直取流程那套） |
+| 生效维度 | 四种：当前表单 / 表单布局 / 当前工作流 / 选择节点（后两者需 `--workflow-id`） | 同样四种 |
+
+### 多出来的「流程」触发事件
+
+除了字段组的 5 个与表单组的 5 个，还有 7 个流程级事件（都不需要 `--trigger`）：
+
+> ⚠ 这 7 个**不是流程表单专属**：eb 表选了「当前工作流 / 选择节点」维度时一样能用（设计器就这么配、也存得下）。差别只在**取清单**：eb 路由默认只给前两组 10 个，要给流程事件得加 `--effect workFlow --workflow-id <流程id>` 让它去取流程那套。
+
+```
+EVENT_SUBMIT_OR_AGREE  提交/批准时      EVENT_REJECT        退回时
+EVENT_FORWARD          转发时          EVENT_TURNTODO      转办时
+EVENT_SAVE_DATA        保存时          EVENT_REMARKADVICE  意见征询时
+                                      EVENT_CIRCULATE     传阅时
+```
+
+### 生效维度的四种取值
+
+```bash
+--effect form          # 默认。当前表单
+--effect formLayout    # 表单布局（--layout-id 可指定，不传取默认布局）
+--effect workFlow      # 当前工作流，必须给 --workflow-id
+--effect includeNode   # 选择节点，必须给 --workflow-id 与 --node
+```
+
+「选择节点」的 `--node` 可以给节点 id 或节点名。「当前工作流」的选项名是 `流程名【V活动版本号】`，版本号取活动版本 —— 与设计器发出的形状一致。
+
+四种取值 eb 表也有（1.5.11 起），命令面同名同义。另外：`fdEffect.effectModule` **跟生效维度走、不跟路由走** —— 「当前工作流 / 选择节点」两个维度归卡片模块（`ebuildercard`），即便这条联动挂在 eb 表上（`linkageModule` 仍是 `ebuilderform`）。
+
+### 系统字段里有两个**可以**当赋值目标
+
+流程表单的模块字段桶有 32 项，但平台标「不可赋值」的只有 30 项，差的是：
+
+```
+REQ_REQUEST_NAME   流程标题
+REQUEST_LEVEL      紧急程度
+```
+
+这两个**可以**作 `--target`。`columns` 命令会按「可作 / 不可作赋值目标」分桶列出，别拿「是不是系统字段」去判断。
+
+### 流程表单这条路由读不出字段时
+
+`wf-form` 的多数命令靠 `getFormLayout` + `getConfig` 读字段，但**部分流程表单上 `getFormLayout` 会直接 500**（`Form.isPhysicalTable()` 上 NPE）。函数联动**不受影响** —— 它的字段清单直接取 `findFormDrivingColumns`（这条路由自己给的），没走 `getConfig`。所以 `wf-form read` 读不出来的表单，`wf-form formula-linkage columns` 照样能列出字段。
+
+## 常见报错
+
+| 报错 | 原因 | 怎么办 |
+|---|---|---|
+| 系统模块字段「X」不能作为赋值目标 | `--target` 写了模块字段 | 换成业务字段；模块字段只能出现在公式右边 |
+| 「X」在…上匹配到 N 个字段 | 字段名有歧义 | 用字段 id（`form formula-linkage columns` 里）
+| 表达式里写的是一个赋值式，它的左侧是「A」，与 --target「B」不一致 | 粘贴的赋值式目标与 `--target` 不符 | 改 `--target`，或只给右侧函数体 |
+| 事件「载入时」是表单级/流程级的，不需要触发字段，--trigger 已忽略 | 表单级 / 流程级事件给了触发字段 | 无害提示；去掉字段即可 |
+| 事件「值改变时」需要指定触发字段 | 字段级事件没给触发字段 | 补 `--trigger`，或写成 `--event changeField:<字段,字段>` |
+| 未知事件「EVENT_FORWARD」，可用: …（只列 10 个） | 想在 eb 表上用流程级事件，但没换维度 | 加 `--effect workFlow --workflow-id <流程id>` 再试 |
+| 生效维度在「当前表单/表单布局」与「当前工作流/选择节点」之间切换时，必须同时用 --event 指定… | `update` 换了维度却沿用旧事件 | 一起给 `--event`（新的维度下可用的事件） |
+| 平台回读的表达式与提交不一致 | 归一化猜错了写法 | 以平台为准；把 `read` 的结果记下来反馈 |

package/skills/weaver-e10-builder/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/skills/weaver-e10-builder/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/skills/weaver-e10-builder/references/form/guide-list-stats.md

@@ -0,0 +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、明细条件、主表回归、重复运行、删除回读和移动端保护。不要改写用户已经配置的“合同付款金额”“付款记录数”；使用独立名称测试，结束清理临时项。实际金额与记录数须另用已知数据核对，不能仅凭保存成功认定数值正确。