weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/spec-build-schema.md

@@ -1,11 +1,11 @@
 # 声明式搭表 spec（一次性落库 · 推荐默认路径）
 
-> **CLI**：`e10-cli report build --spec <spec.json> [--dry-run] [--form-confirmed] [--source-id <id>] [--field-confirmed "标题1,标题2"]`
+> **CLI**：`e10-cli report build spec --spec <spec.json> [--dry-run] [--form-confirmed] [--source-id <id>] [--field-confirmed "标题1,标题2"]`
 > **脚本**：`e10-cli report build` · 公共库 `e10-cli report build`
 > **强制流程**：应用内定源 → **建表前字段预检**（`fieldsBySource`，**不建表**）→ **目标名** `baseInfo` → 本表 `addDataset`（同源只挂一次）→ `fieldsKey`（**再校验一次**）→ `saveReportDevInfo` → 回读。
 > **禁止**：`__build_*` / `__probe_*` 空壳、落库后再 rename、跨报表复用 datasetId、模糊表名未确认就搭表、**字段精确匹配失败时静默兜底（含回退系统字段）**。
 
-> ### ⚠ 两条「停下来问用户」规则（强制 · 2026-09-11 · `e10-cli report --help`）
+> ### ⚠ 两条「停下来问用户」规则（强制 · 2026-09-11 · ）
 >
 > | 规则 | 触发 | 行为 |
 > |------|------|------|
@@ -36,36 +36,12 @@
 | `sourceType` | | 默认 `LOGIC`；共享表应用用 `form` |
 | `sourceGroup` | | 默认 `weaver-ebuilder-form-service`；共享表用 appId |
 | `sourceName` | | 数据集回显名；**缺后缀时自动补** `(业务模块)`/`(表单)`（裸表单名 → 面板缺后缀） |
-| `sources[]` | | **多数据源**。写了它就以它为准（`form`/`sourceId`/`sourceType` 等下沉到每一项）。见 `guide-report-multisource.md` |
-
-> **两个最常写错的键名**：列定义是 **`columns[]`**（不是 `fields`）；**`form` 是表单名字符串**（不是对象）——
-> 要用表单 id 就写 `sourceId`。写错时命令会回「spec 需要包含 appId / name(报表名) / columns[]」。
-
-### 1.0 多数据源 `sources[]` / `columns[].source`
-
-```json
-"sources": [
-  { "key": "customer", "form": "客户信息表" },
-  { "key": "order", "form": "销售订单表",
-    "link": { "parent": "customer", "parentField": "客户名称",
-              "childField": "客户名称", "type": "Equals" } }
-],
-"columns": [ { "source": "customer", "title": "客户名称", "field": "客户名称" },
-             { "source": "order",    "title": "订单编号", "field": "订单编号" } ]
-```
-
-- `sources[0]` = **父源**（不写 `link`）；`columns[].source` 缺省 = 父源 —— **不写 `sources` 时行为与单源完全一致**。
-- `link.parent` 必须是**左边紧邻**的源；`parentField`/`childField` 写显示名或 `field_xxx`，各自在本方表里解析（歧义即报错）。
-- `link.type` 用 **TitleCase** 白名单（`Equals`/`NotContain`/`Null`…）；`eq`/`contains` 这类简写平台不认。
-- 子源只能占**一段**连续区域；同区域**只有入口格**配父格筛选，其余格普通链式。
-- 多源时 `fieldMap`/`fieldConfirmed` 用 **`"源key.列标题"`** 限定同名不同源的列。
-- 跨源报表自动双保存并关预聚合；异常分支与限制见 `guide-report-multisource.md`。
 
 \* `form` 与 `sourceId` **均可省** → 走**规则 B**：exit **3**，列出应用内候选请用户指定表（**不会**按关键词猜、**不会**建表）。
 
 ### 1.1 定源规则 · 规则 B（表没指明 / 非精确匹配 → 让用户指定）
 
-`resolveFormWithPrompt()` / `e10-cli report find` 统一语义：
+`resolveFormWithPrompt()` / `e10-cli report find form` 统一语义：
 
 | 触发 | `reason` | 行为 |
 |------|----------|------|
@@ -77,7 +53,7 @@
 确认后复跑（二选一）：
 
 ```bash
-e10-cli report build --spec a.json --form-confirmed --source-id <id>
+e10-cli report build spec --spec a.json --form-confirmed --source-id <id>
 ```
 ```json
 { "formConfirmed": true, "sourceId": "<id>", "form": "<准确表名>" }
@@ -86,8 +62,8 @@ e10-cli report build --spec a.json --form-confirmed --source-id <id>
 浏览候选（**不建表**）：
 
 ```bash
-e10-cli report find <appId> --list
-e10-cli report find <appId> --suggest "关键词1,关键词2"
+e10-cli report find form <appId> --list
+e10-cli report find form <appId> --suggest "关键词1,关键词2"
 ```
 
 > **禁止**：按关键词自行挑一张「最像的」表；先建壳/试探表再判断对不对。
@@ -107,8 +83,7 @@ e10-cli report find <appId> --suggest "关键词1,关键词2"
 
 | 字段 | 说明 |
 |------|------|
-| `title` | 表头文案（**也是字段匹配依据**，见 §二.1） |
-| `source` | 该列属于哪个源（`sources[].key`）；缺省 = 父源 |
+| `title` | 表头文案（**也是字段匹配依据**，见 §二.1）。⚠️ **A0.10**：设计器回显串 = `{tableName}.{格内文字}({字段名})`，而「格内文字」= **Field 格的 `text`** → 写自定义标题会让设计器**不回显字段名**（用户误判「未匹配到正确字段」）。**另起 Const 标题行时，`title` 只放字段真实显示名**；确实要自定义列名才用 `confirmDisplayMismatch` |
 | `field` | 对应 fieldsKey 的 text/name（精确匹配） |
 | `fieldName` | **显式指定** fieldsKey.name（优先于 `field`/`title`） |
 | `confirmDisplayMismatch` | `true` = 该列允许「文案 ≠ 字段真实显示名」（用户认可自定义列名） |
@@ -116,7 +91,10 @@ e10-cli report find <appId> --suggest "关键词1,关键词2"
 | `format` | 见下表；`huobi` 等 |
 | `formula` | 公式表达式（无 `=` 前缀；公式列不参与字段匹配） |
 | `groupType` | 日期分组等 |
+| `display` | 显示方式：`"tree"`=折叠树形（`displayType=Tree`+左父格无+isActiveParent · 场景 I；缺省 Group），见 `advanced-crosstab-tree-guide.md` |
 | `rule` | 条件格式，见 §五 |
+| `sort` | `asc`/`desc` → Field 格 `orderType`（数据钻取场景 D；预览点击排序以验证为准） |
+| `link` | 钻取链接 `{type:"report\|list\|card\|custom", reportId\|formId\|url, params:{参数名:"SELF\|列标题"}, openType}` → `pcHreflink`；引用右列（超出左父格链）**构建即报错**（A0.11）；详见 `drilldown-report-guide.md` |
 
 ### 2.1 字段绑定门禁 · 规则 A（**字段找不到 → 让用户指定 · 禁止静默兜底 · 2026-09-11 强制**）
 
@@ -134,25 +112,25 @@ e10-cli report find <appId> --suggest "关键词1,关键词2"
 
 ```json
 {
- "action": "confirm_field", "rule": "A", "reportCreated": false,
- "unmatched": [
- { "column": "党组织", "reason": "no_exact_match",
- "prompt": "需求字段「党组织」在当前数据集表单中不存在：请用户从 allFields/candidates 中指定字段。",
- "candidates": [{ "name": "field_1475883017323040117", "text": "所属党委", "system": false }] }
- ],
- "allFields": [ { "name": "field_3505883017323279926", "text": "发展人", "system": false } ],
- "next": { "specFields": { "fieldMap": { "<列标题>": "<字段显示名 | field_雪花 | 系统字段名>" } } }
+  "action": "confirm_field", "rule": "A", "reportCreated": false,
+  "unmatched": [
+    { "column": "党组织", "reason": "no_exact_match",
+      "prompt": "需求字段「党组织」在当前数据集表单中不存在：请用户从 allFields/candidates 中指定字段。",
+      "candidates": [{ "name": "field_1475883017323040117", "text": "所属党委", "system": false }] }
+  ],
+  "allFields": [ { "name": "field_3505883017323279926", "text": "发展人", "system": false } ],
+  "next": { "specFields": { "fieldMap": { "<列标题>": "<字段显示名 | field_雪花 | 系统字段名>" } } }
 }
 ```
 
 用户指定后复跑：
 
 ```bash
-e10-cli report build --spec a.json --field-confirmed "党组织,姓名"
+e10-cli report build spec --spec a.json --field-confirmed "党组织,姓名"
 ```
 ```json
 { "fieldMap": { "党组织": "field_1475883083739840137", "姓名": "发展人" },
- "fieldConfirmed": ["党组织", "姓名"] }
+  "fieldConfirmed": ["党组织", "姓名"] }
 ```
 
 > 事故：列「姓名」在表单无对应字段时被静默绑到系统字段 `name`（真实显示名「标题」）→ 列语义被改写且属性面板回显不符。
@@ -201,16 +179,11 @@ e10-cli report build --spec a.json --field-confirmed "党组织,姓名"
 ```
 
 - `title`：第 0 行合并标题
-- `freezeRows`：**冻结顶部几行**，锚点行就是 `freezeRows`（平台冻的是「锚点上方」的行）。
-  | 写法 | 锚点 | 实际冻结 |
-  |---|---|---|
-  | `0` / 不写 | 无 | 不冻结 |
-  | `1` | 表头首格 `(1,0)` | 只冻**标题行** |
-  | `2` | 数据首格 `(2,0)` | 冻**标题 + 表头**（与 `report fix freeze` 默认一致） |
-
-  锚点必须落在**真实存在的单元格**上，所以最多只能冻到首个数据行；写超了会直接报错，
-  不会静默按 1 处理。要冻更多行用 `report fix freeze --anchor <x,y>` 在已有报表上做。
+- `freezeRows: 1`：冻上方表头（锚点自动落**首个数据行**，冻标题+表头全部 · 场景 F 修正语义）
+- `freezeCols: N`：**冻左侧 N 列**（与 freezeRows 可组合；仅写 freezeCols 不写 freezeRows = 只冻列不冻行）；锚点语义与验收见 `shard-freeze-report-guide.md`
 - `showLocation`：`left`=1；**禁止 0**
+- `pageRowCount: N`：**每页固定 N 行**（分页分组报表 · 场景 E；`pagination:true` 经 saveReportWithCacheConfig 落库，见 `paged-group-report-guide.md`）
+- `paginate: false`：**不分页**（宽表/分片冻结表 · 场景 F；同通道落 `pagination:false`，与 pageRowCount 二选一）
 
 ---
 
@@ -225,23 +198,23 @@ e10-cli report build --spec a.json --field-confirmed "党组织,姓名"
 
 ```json
 {
- "appId": "770979194185342976",
- "name": "资产信息统计",
- "form": "轻资产信息",
- "layout": { "title": "轻资产信息统计表", "freezeRows": 1 },
- "columns": [
- { "title": "资产名称", "field": "资产名称", "width": 160 },
- { "title": "库存数量", "field": "库存数量", "width": 110 }
- ]
+  "appId": "770979194185342976",
+  "name": "资产信息统计",
+  "form": "轻资产信息",
+  "layout": { "title": "轻资产信息统计表", "freezeRows": 1 },
+  "columns": [
+    { "title": "资产名称", "field": "资产名称", "width": 160 },
+    { "title": "库存数量", "field": "库存数量", "width": 110 }
+  ]
 }
 ```
 
 模糊表名确认后再搭：
 
 ```bash
-e10-cli report build --spec a.json
+e10-cli report build spec --spec a.json
 # exit 3 → 用户确认 sourceId
-e10-cli report build --spec a.json --form-confirmed --source-id 770981333078605824
+e10-cli report build spec --spec a.json --form-confirmed --source-id 770981333078605824
 ```
 
 ---
@@ -264,16 +237,16 @@ e10-cli report build --spec a.json --form-confirmed --source-id 7709813330786058
 
 ```json
 {
- "action": "confirm_field",
- "rule": "A",
- "reportCreated": false,
- "unmatched": [
- { "column": "姓名", "reason": "no_exact_match",
- "message": "列「姓名」在该数据源 fieldsKey 中没有精确匹配的显示名…",
- "prompt": "需求字段「姓名」在当前数据集表单中不存在：请用户从 allFields/candidates 中指定字段。",
- "candidates": [{ "name": "field_1475883001898540109", "text": "培养人" }] }
- ],
- "allFields": [ { "name": "field_3505883017323279926", "text": "发展人", "system": false } ]
+  "action": "confirm_field",
+  "rule": "A",
+  "reportCreated": false,
+  "unmatched": [
+    { "column": "姓名", "reason": "no_exact_match",
+      "message": "列「姓名」在该数据源 fieldsKey 中没有精确匹配的显示名…",
+      "prompt": "需求字段「姓名」在当前数据集表单中不存在：请用户从 allFields/candidates 中指定字段。",
+      "candidates": [{ "name": "field_1475883001898540109", "text": "培养人" }] }
+  ],
+  "allFields": [ { "name": "field_3505883017323279926", "text": "发展人", "system": false } ]
 }
 ```
 
@@ -292,3 +265,30 @@ e10-cli report build --spec a.json --form-confirmed --source-id 7709813330786058
 | `add-dataset-registration-guide.md` | LOGIC 注册 |
 | `failure-cleanup-and-nonblocking-guide.md` | 仅失败删未完成表，禁止故意建空壳 |
 | `report-delivery-contract.md` | 交链即停 |
+
+---
+
+## 多 Sheet 蓝图（rebuild_from_blueprint · 2026-10-29 验证 e-cology）
+
+```json
+{
+  "reportId": "...", "appId": "...", "datasets": [...],
+  "sheets": [
+    { "name": "Sheet1", "cells": [ ... ] },
+    { "name": "Sheet2", "cells": [ ... ] }   // 格上可写 sheetIndex（自动按 sheets 序号注入）
+  ]
+}
+```
+兼容旧蓝图 `cells`（单 sheet）。克隆纪律自检按 sheet 维度执行（跨 sheet 坐标允许重复）。
+
+### ★ 注意点 BUILD-55：横向合并必须用 `yCount`，`xCount` 是纵向跨度
+- `xCount` = **纵向**（行向）合并、`yCount` = **横向**（列向）合并 —— 与直觉相反（sheet1 标题条即 `yCount:8` 横跨 8 列）。
+- 血案：多 sheet 摘要页标题写 `xCount:9` → 生成「纵向 9 行」span，**服务端静默丢弃 span 覆盖区内的所有格**（回读 31/35，恰好丢 4 个行首格），且报错信息（`重建格数 N!=M`）指向别处，极难定位。
+- 定位手法：回读 fields 按 sheetIndex 分组 diff 蓝图 → 找缺失格 → 检查缺失格是否落在某个 span 覆盖区内。
+- 修复后回读 `107/107` 全对齐。
+
+### ★ 多 sheet 存储形态（回读观察）
+- 服务端把每个 sheet 的 **y=0 列（A 列）保留为锚位区**：自然多 sheet 报表内容全部在 y≥1，行首根格 `left=(x,0)` 指向不回读的隐式锚。
+- API 保存时 y=0 内容格**可能被吸收/丢弃**（本例 v4 验证）→ **多 sheet 内容一律从 y=1 起写**。
+- `sheetProps` 回读顺序与 workbook.sheets 键序无关（验证按名称倒序），tab 顺序以设计器为准；sheet 命名建议直接在设计器里改（同时修正顺序）。
+- 回读校验器已支持多 sheet：按 sheetIndex 分组重建后合并（防跨 sheet 坐标重叠误报 `重建格数 N!=M`）。

package/skill-docs/references/report/targeted-fix-guide.md

@@ -1,97 +1,155 @@
-# 定点修改 · 禁止整表重扫（强制）
-
-> **适用**：用户指出「某处不对 / 修某一格 / 改某条查询 / M4 父格」等**已定位**问题；以及「只改列宽 / 冻结 / 居左 / 分页 / 快照 / 打印」等**已列明范围**的调整；**改已有报表设计器内容**时一律适用。 
-> **目标**：少读配置、少调 API、少改无关格，避免整表重扫浪费时间与额度。 
-> **总闸（更高优先级）**：`user-request-scope-only-guide.md` — **仅改用户点名项**；未点名禁止改删、禁止额外命令。 
-> **硬约束**：用户说「只对提出的要求做调整，其他不要动」时，**样式/行高/字体/颜色/边框/未点名格一律禁止改写**——即便为写 workbook 必须整表回传，语义上也只能 patch 点名项。 
-> **禁止**：因编辑需求而重新走完整「需求分析 → 识别全部搭建配置 → 整表重建」。
-
----
-
-## 一、硬原则
-
-| 原则 | 说明 |
-|------|------|
-| **仅用户点名（总闸）** | 见 `user-request-scope-only-guide.md`；CLI `e10-cli report fix --help` |
-| **听指定位置** | 用户点名单元格（如 M4）、查询条件名、字段名、dataset → **只处理该范围** |
-| **禁止整表重扫** | 不得因修一格而：全量 dump 所有 fields、重拉全部数据集元数据、重跑整表 verify、从参考表整表 clone 覆盖 |
-| **禁止顺手重构** | 未点名时禁止批量改其它 Field 父格、禁止重写全部查询条件、禁止「顺便」对齐整表样式 |
-| **禁止顺手改样式（强制）** | 用户未点名「改样式/行高/主题/字体/颜色」时：**禁止**重建 cell `style`、禁止改 `rows[].size`（行高）、禁止用默认模板覆盖已有外观。列宽/冻结/居左 ≠ 许可重做报表样式 |
-| **禁止拆合并（强制）** | **没有任何规则要求拆分合并单元格**。从 fields 重建 workbook 时必须带上原 `xCount`/`yCount` → `cell.rowCount`/`colCount` + `sheet.spans`；漏写 = 等价于取消合并。用户未要求「取消合并」时禁止丢 spans |
-| **禁止擅自删除** | 未点名删除时禁止 `deleteReport` / `lifecycle delete` / `cleanup shells` |
-| **最小读** | 只需 `getReportDevInfo` 时优先按坐标/条件 id **过滤后使用**；不要为定位一格打印全表 |
-| **最小写** | 查询 → 只 `saveQueryItem` 改目标条；父格/超链接 → 在**完整 workbook 保护**前提下只 patch 目标 cellType（见下） |
-
----
-
-## 二、问题类型 → 动作范围
-
-| 用户说法（例） | 允许动作 | 禁止 |
-|----------------|----------|------|
-| 「M4 左/上父格不对」 | 只读 `(3,12)`（及占位依赖格如 `(3,11)`）；只改该 Const 的父格/`pcHreflink` | 重扫全部 Const/Field 父格；整表从兄弟报表覆盖 |
-| 「供应商等级没选项」 | 只读/改该条 `getQueryItem`；按 §3.2 拉该字段 options | 重配全部查询条件；重扫布局 |
-| 「查询显示方式不对」 | 只改目标条 `showWhere` | 新建一套条件 |
-| 「某 Field 绑错」 | 只改该格 `name`/`fieldKey` + workbook 对应 cell | 全表 remap |
-| 「整表父格都要默认」 | **仅当用户明确整表要求** 才批量；否则只更新 Skill 规则 | 把「规则说明」当成改线上表的许可 |
-| 「列宽 N / 冻结表头 / 居左」 | 只改 `width`+`columns`、冻结锚点、`showLocation`（见 `layout-showlocation-freeze-guide.md`） | 重建整表 style/行高；猜 `showLocation=0`；只写 `frozenRowCount` 不写 `fixed-cell-tag`；**丢掉 spans/合并** |
-
----
-
-## 二点五、合并单元格（spans）保护
-
-服务端从 workbook **`spans`**（或 cell.`rowCount`/`colCount`>1）回写 `field.xCount`/`yCount`。 
-`safe_report_save.js` 的 `fieldToCell` / `buildWorkbookFromFields` **必须**把 `xCount`/`yCount` 写回 cell + `spans`。
-
-**反例（本次事故）**：只为改列宽/冻结，用无 `spans` 的 workbook 整表 `saveReportDevInfo` → 表头标题、表尾合计行合并被拆成 1×1。 
-**正例**：有原 workbook 时优先 `mergeWorkbookSafe` 原地 patch；无 workbook 时从 fields 重建也必须带 spans。
-
----
-
-## 三、布局类定点改（仍须保护设计区）
-
-修**单格**父格/超链接时：
-
-1. **仍须**按 `safe-partial-save-guide.md` 提交**完整** `fields` + 从 fields 重建的 workbook（禁止空/残 workbook）。
-2. **语义上只改目标格**：其它格原样写回；禁止顺带改 Field 左父格链。
-3. **Const**：`ConstCellType` 必须显式带 `leftX/leftY/topX/topY` 与（若有）`pcHreflink`——服务端从 workbook 回写；缺 `leftX` → `0` → 伪 A1。见 `report-self-check-guide.md` §2.2。
-4. **保存后自检范围收窄**：只断言**被改格** + Field 总数不降；**不要**为修 M4 再跑全表字段遍历报告。
-
-```
-用户指 M4 →
- GET getReportDevInfo（内存过滤 x,y）
- patch fields 中该格 + 重建 workbook（全表 cell 保留，仅该格 ConstCellType 变）
- saveReportDevInfo
- 回读：仅检查该格 left/top/href/text + Field.count
-```
-
----
-
-## 四、查询类定点改
-
-1. `getQueryItem` → 按显示名 / `asNameIndex` / `id` **定位一条**。
-2. 只改该条：`showWhere` / `displayType` / `selectOptions` / `relation` 等。
-3. 下拉选项：`selectKey`=选项 ID，`selectValue`=显示名；`fieldName` 用裸雪花 ID。见 `query-condition-api-guide.md` §3.2。
-4. 回读**只核对该条**，不必打印全部 queryItems。
-
----
-
-## 五、列宽 / 冻结 / 居左（样式敏感）
-
-1. **必加载** `layout-showlocation-freeze-guide.md`。 
-2. 其它 cell 的 `style` JSON **原样**进入 workbook；禁止为省事用空白 style 重生。 
-3. 居左 = `showLocation: 1`（**不是 0**）；冻结表头 = `fixed-cell-tag` 锚点 + `tag.fixed` + `tag.fixedCell`，不能只设 `frozenRowCount`。 
-4. 回读只断言：目标列宽、`showLocation`、锚点 `(x,y)`/`fixed==1`；**不要**为调列宽去「优化」行高。
-
----
-
-## 六、与其它文档关系
-
-| 文档 | 关系 |
-|------|------|
-| `user-request-scope-only-guide.md` | **总闸**：仅改用户点名项；禁止擅自改删 |
-| `safe-partial-save-guide.md` | 写布局时的 workbook 完整性（与「语义定点」不矛盾） |
-| `layout-showlocation-freeze-guide.md` | 居左枚举 + 冻结锚点；禁止伤样式 |
-| `report-self-check-guide.md` | 落库门禁；定点场景下**检查项可裁剪到改动面** |
-| `datasource-selection-and-parent-filter-guide.md` §〇 | 父格规则；「默认」≠ 批量改已有表 |
-| `query-condition-api-guide.md` | 查询/选项映射 |
-| `report-delivery-contract.md` | 仍可先交设计器链接；后台只验证改动面 |
+# 定点修改 · 禁止整表重扫（强制）
+
+> **适用**：用户指出「某处不对 / 修某一格 / 改某条查询 / M4 父格」等**已定位**问题；以及「只改列宽 / 冻结 / 居左 / 分页 / 快照 / 打印」等**已列明范围**的调整；**改已有报表设计器内容**时一律适用。
+> **目标**：少读配置、少调 API、少改无关格，避免整表重扫浪费时间与额度。
+> **总闸（更高优先级）**：`user-request-scope-only-guide.md` — **仅改用户点名项**；未点名禁止改删、禁止额外命令。
+> **硬约束**：用户说「只对提出的要求做调整，其他不要动」时，**样式/行高/字体/颜色/边框/未点名格一律禁止改写**——即便为写 workbook 必须整表回传，语义上也只能 patch 点名项。
+> **禁止**：因编辑需求而重新走完整「需求分析 → 识别全部搭建配置 → 整表重建」。
+
+---
+
+## 〇、术语与硬禁止：**整表重建**（强制 · 最高优先级）
+
+> **一句话**：改**已有报表**，只允许「**定点补丁**」；**任何形式的「整表重建」一律杜绝**。
+
+**平台事实（为什么必须这么定）**：
+`saveReportDevInfo` 是**整份 workbook 覆盖式替换**（gzip+base64），且 `getReportDevInfo.workbookProps.sheets` 恒为 `{}`
+（服务端**不回传 dataTable**）。所以「改动」在**传输层**必然是整份回传 —— 但**语义层**只能是定点 patch。
+
+| 概念 | 定义 | 判定 |
+|------|------|------|
+| ❌ **整表重建** | 用**脚本里手写的 schema / 列定义 / 单元格构造**重新生成 workbook 落库（如自写 `dash.js`、`create_xxx.js`） | **禁止**。与线上状态脱钩，必丢 `tag` / `selections` / `colHeaderData` / `rowHeaderData` / `tag.formatterType` / 服务端派生键；历史上已致**公式格消失**、**文本·数值格式被抹成 common**、**显示位置被改成居中** |
+| ✅ **定点补丁** | `getReportDevInfo.fields` → **原样派生** workbook（全键保真）→ 只改**点名键** → dry-run 保真自检 → `--apply` → 落库后**回读 diff** | **唯一允许** |
+| ✅ **声明式搭建** | 仅用于**全新报表**（此时没有「线上原状」需要保护），走 `build_from_spec` / spec 驱动 | 允许 —— 但**不适用于「改已有报表」** |
+
+**唯一允许的落库入口**（全部默认 dry-run）：
+```
+e10-cli report fix table-name --report-id <id> [--set-json "x,y:key:JSON值"]... [--set-parent "x,y=lx,ly"]... [--apply]
+e10-cli report fix echo | freeze | query-style | query-default
+e10-cli report query save --item <item.json>
+```
+- 通用 `--set-json "x,y:key:JSON值"` 可改**任意单元格键**，形如：
+  · 藏列 `--set-json "1,12:width:0"`（隐藏列 = **列宽 0**）
+  · 汇总 `--set-json "2,8:displayType:Count"`
+  · 转换 `--set-json "2,10:transType:select"`
+  · 格式 `--set-json "2,1:formatterType:[\"text\"]"`
+  · **格内文字改回字段真名** `--set-json "2,8:text:\"现供应商等级\""`（见 §三.1 · 回显正确性）
+- 它的实现就是「读 live fields → 原样派生 workbook → 改点名键 → 自检 → 落库 → 回读」，**不会**重新定义其它格。
+- `--prefer-canonical`（**可选开关，默认关闭**）：`tableName` 以**数据集规范显示名**为准，压过「参照单元格已有值」。
+  用途是修「既有值本身是错的」——例如建表时把已带后缀的 `datasetName` 又拼了一次，存成 `xxx(业务模块)(业务模块)`；
+  该错值会被默认优先级「② 参照单元格最权威」永久沿用，不显式开关就永远修不掉。
+  权威对照 = `verify contract` 打印的 `dataset = …` 行。
+  ⚠️ **反向风险**：规范名有时只回传**裸 id**（验证报表 `1313903497535856640`），此时本开关会回落参照值/数据集名，行为与默认一致。
+
+**硬禁止清单**：
+- 禁止**为改一格/一列而重跑整表 spec 生成**、**重新定义全部单元格**、**从参考报表整表 clone 覆盖**。
+- 禁止**未跑 dry-run**（未看到「保真自检 不一致键 0 处」）就 `--apply`。
+- 禁止只回读「目标格」而不做**逐格 `Object.keys` 差集**（`CMP_KEYS` 是白名单，自检「0 差异」不可信）。
+
+**唯一例外**：用户**明确要求整表重做/新建**，且已接受上述丢失风险。
+
+> 术语防混淆：`e10-cli report fix table-name` 等脚本日志里出现的「**重建 workbook**」，指的是
+> **从 live `fields` 原样派生**（合法，即定点补丁）；**不要**与本节禁止的「整表重建」
+> （从**脚本手写的 schema** 生成新 workbook）混为一谈。
+
+---
+
+## 一、硬原则
+
+| 原则 | 说明 |
+|------|------|
+| **仅用户点名（总闸）** | 见 `user-request-scope-only-guide.md`；CLI  |
+| **听指定位置** | 用户点名单元格（如 M4）、查询条件名、字段名、dataset → **只处理该范围** |
+| **禁止整表重扫** | 不得因修一格而：全量 dump 所有 fields、重拉全部数据集元数据、重跑整表 verify、从参考表整表 clone 覆盖 |
+| **禁止顺手重构** | 未点名时禁止批量改其它 Field 父格、禁止重写全部查询条件、禁止「顺便」对齐整表样式 |
+| **禁止顺手改样式（强制）** | 用户未点名「改样式/行高/主题/字体/颜色」时：**禁止**重建 cell `style`、禁止改 `rows[].size`（行高）、禁止用默认模板覆盖已有外观。列宽/冻结/居左 ≠ 许可重做报表样式 |
+| **禁止拆合并（强制）** | **没有任何规则要求拆分合并单元格**。从 fields 重建 workbook 时必须带上原 `xCount`/`yCount` → `cell.rowCount`/`colCount` + `sheet.spans`；漏写 = 等价于取消合并。用户未要求「取消合并」时禁止丢 spans |
+| **禁止擅自删除** | 未点名删除时禁止 `deleteReport` / `lifecycle delete` / `cleanup shells` |
+| **最小读** | 只需 `getReportDevInfo` 时优先按坐标/条件 id **过滤后使用**；不要为定位一格打印全表 |
+| **最小写** | 查询 → 只 `saveQueryItem` 改目标条；父格/超链接 → 在**完整 workbook 保护**前提下只 patch 目标 cellType（见下） |
+
+---
+
+## 二、问题类型 → 动作范围
+
+| 用户说法（例） | 允许动作 | 禁止 |
+|----------------|----------|------|
+| 「M4 左/上父格不对」 | 只读 `(3,12)`（及占位依赖格如 `(3,11)`）；只改该 Const 的父格/`pcHreflink` | 重扫全部 Const/Field 父格；整表从兄弟报表覆盖 |
+| 「供应商等级没选项」 | 只读/改该条 `getQueryItem`；按 §3.2 拉该字段 options | 重配全部查询条件；重扫布局 |
+| 「查询显示方式不对」 | 只改目标条 `showWhere` | 新建一套条件 |
+| 「某 Field 绑错」 | 只改该格 `name`/`fieldKey` + workbook 对应 cell | 全表 remap |
+| 「整表父格都要默认」 | **仅当用户明确整表要求** 才批量；否则只更新 Skill 规则 | 把「规则说明」当成改线上表的许可 |
+| 「列宽 N / 冻结表头 / 居左」 | 只改 `width`+`columns`、冻结锚点、`showLocation`（见 `layout-showlocation-freeze-guide.md`） | 重建整表 style/行高；猜 `showLocation=0`；只写 `frozenRowCount` 不写 `fixed-cell-tag`；**丢掉 spans/合并** |
+
+---
+
+## 二点五、合并单元格（spans）保护
+
+服务端从 workbook **`spans`**（或 cell.`rowCount`/`colCount`>1）回写 `field.xCount`/`yCount`。
+`` 的 `fieldToCell` / `buildWorkbookFromFields` **必须**把 `xCount`/`yCount` 写回 cell + `spans`。
+
+**反例（本次事故）**：只为改列宽/冻结，用无 `spans` 的 workbook 整表 `saveReportDevInfo` → 表头标题、表尾合计行合并被拆成 1×1。
+**正例**：有原 workbook 时优先 `mergeWorkbookSafe` 原地 patch；无 workbook 时从 fields 重建也必须带 spans。
+
+---
+
+## 三、布局类定点改（仍须保护设计区）
+
+修**单格**父格/超链接时：
+
+1. **仍须**按 `safe-partial-save-guide.md` 提交**完整** `fields` + 从 fields 重建的 workbook（禁止空/残 workbook）。
+2. **语义上只改目标格**：其它格原样写回；禁止顺带改 Field 左父格链。
+3. **Const**：`ConstCellType` 必须显式带 `leftX/leftY/topX/topY` 与（若有）`pcHreflink`——服务端从 workbook 回写；缺 `leftX` → `0` → 伪 A1。见 `report-self-check-guide.md` §2.2。
+4. **保存后自检范围收窄**：只断言**被改格** + Field 总数不降；**不要**为修 M4 再跑全表字段遍历报告。
+
+```
+用户指 M4 →
+  GET getReportDevInfo（内存过滤 x,y）
+  patch fields 中该格 + 重建 workbook（全表 cell 保留，仅该格 ConstCellType 变）
+  saveReportDevInfo
+  回读：仅检查该格 left/top/href/text + Field.count
+```
+
+### 三.1 回显正确性：Field 格 `text` 与 `tableName`（★ A0.10）
+
+设计器 Field 格的**回显串** = `{tableName}.{cell.text}({字段名})`。「格内文字」**直接取 `cell.text`**，
+设计器**不会**自动改用字段显示名 → `text` 写错，整串回显就是错的（用户会报「未匹配到正确字段」）。
+
+| 症状 | 根因 | 定点修法 |
+|------|------|----------|
+| 该格回显的是**业务标题**（如「最近评级」）而非字段真名（「现供应商等级」） | 建表时把列标题写进了 Field 格的 `text` | `--set-json "2,8:text:\"现供应商等级\""`（标题只留 Const 标题行） |
+| 数据集名重后缀 `xxx(业务模块)(业务模块)` | `datasetName` 已带后缀又拼了一次 | `--prefer-canonical` |
+
+**自检**：逐格比对 `cell.text` vs「`fieldKey` 末段字段在源表元数据里的 `text`」，不一致即中招（`pitfalls BUILD-19/20`）。
+
+---
+
+## 四、查询类定点改
+
+1. `getQueryItem` → 按显示名 / `asNameIndex` / `id` **定位一条**。
+2. 只改该条：`showWhere` / `displayType` / `selectOptions` / `relation` 等。
+3. 下拉选项：`selectKey`=选项 ID，`selectValue`=显示名；`fieldName` 用裸雪花 ID。见 `query-condition-api-guide.md` §3.2。
+4. 回读**只核对该条**，不必打印全部 queryItems。
+
+---
+
+## 五、列宽 / 冻结 / 居左（样式敏感）
+
+1. **必加载** `layout-showlocation-freeze-guide.md`。
+2. 其它 cell 的 `style` JSON **原样**进入 workbook；禁止为省事用空白 style 重生。
+3. 居左 = `showLocation: 1`（**不是 0**）；冻结表头 = `fixed-cell-tag` 锚点 + `tag.fixed` + `tag.fixedCell`，不能只设 `frozenRowCount`。
+4. 回读只断言：目标列宽、`showLocation`、锚点 `(x,y)`/`fixed==1`；**不要**为调列宽去「优化」行高。
+
+---
+
+## 六、与其它文档关系
+
+| 文档 | 关系 |
+|------|------|
+| `user-request-scope-only-guide.md` | **总闸**：仅改用户点名项；禁止擅自改删 |
+| `safe-partial-save-guide.md` | 写布局时的 workbook 完整性（与「语义定点」不矛盾） |
+| `layout-showlocation-freeze-guide.md` | 居左枚举 + 冻结锚点；禁止伤样式 |
+| `report-self-check-guide.md` | 落库门禁；定点场景下**检查项可裁剪到改动面** |
+| `datasource-selection-and-parent-filter-guide.md` §〇 | 父格规则；「默认」≠ 批量改已有表 |
+| `query-condition-api-guide.md` | 查询/选项映射 |
+| `report-delivery-contract.md` | 仍可先交设计器链接；后台只验证改动面 |

package/skill-docs/references/report/user-request-scope-only-guide.md

@@ -2,7 +2,7 @@
 
 > **优先级**：高于一切「顺手优化 / 看起来更完整 / 方便下次」的冲动。
 > **必加载**：任何会 `saveReportDevInfo` / `deleteReport` / `lifecycle delete` / `rollbackReport` / 改查询·权限·快照·数据集 的任务开始前。
-> **CLI**：`e10-cli report fix --help`（打印本政策）；映射见 `e10-cli report -cli.md` §一。
+> **CLI**：（打印本政策）；映射见 `e10-cli report-cli.md` §一。
 
 ---
 
@@ -64,7 +64,7 @@
 | `targeted-fix-guide.md` | 定点改的细则（本文件是总闸） |
 | `safe-partial-save-guide.md` | 整表回传 ≠ 允许语义上乱改 |
 | `failure-cleanup-and-nonblocking-guide.md` | 唯一允许的「删壳」边界 |
-| `e10-cli report -cli.md` | CLI 映射；破坏性命令须用户点名才可跑 |
+| `e10-cli report-cli.md` | CLI 映射；破坏性命令须用户点名才可跑 |
 | `layout-showlocation-freeze-guide.md` | 列宽/冻结/居左仍须保 spans/样式 |
 
 ---
@@ -73,10 +73,29 @@
 
 ```bash
 # 打印本政策（Agent 改配置前可先跑一遍提醒自己）
-e10-cli report fix --help
 
 # 破坏性命令 —— 仅当用户明确要求时使用
 e10-cli report lifecycle delete ...
-e10-cli report cleanup ...
+e10-cli report cleanup shells ...
 e10-cli report restore ...
 ```
+
+---
+
+## 七、强化案例（policy 级铁律 · 2026-10-14 固化）
+
+| # | 铁律 | 说明 |
+|---|------|------|
+| ① | **只改用户点名的 `reportId`** | 一次任务只碰**被点名**的那张报表；其余报表**只读不写** |
+| ② | **「截图来自哪张表」≠「授权改哪张表」** | 截图/示例只用于**对齐口径**，**不构成改动授权**；要改哪张必须**点名** |
+| ③ | **用户手动复制 / 手调的副本未经点名不得碰** | 用户自己 clone、手动调过的表 → **默认不动**，除非明确点名 |
+| ④ | **误改后从「落库前快照」完整恢复** | 并**回读核对格数**一致；禁止「改回去大概就行」 |
+| ⑤ | **改前快照 + 改后回读三项验收** | 每次修改前 `getReportDevInfo` **快照留档**；落库后回读验收 **格数 / 冲突数 / 目标字段值** 三项 |
+| ⑥ | **save 200 ≠ 成功** | `saveReportDevInfo` 返回 200 但 `data` 带**告警**（如**父格循环依赖**）**也算失败** → 必须处理告警再看 |
+| ⑦ | **旧会话勿保存** | 用户设计器开着**旧会话**时，**提醒勿点保存**（旧页面保存会**覆盖服务端新布局**）；改动涉及已打开报表 → 要求**强刷后**再核对 |
+| ⑧ | **改列 / 重排后重建左父格链** | 移动列、重排后必须**重建左父格链**，防止 `left` 指向**已删格 / 自身**（save 200 但带告警） |
+| ⑨ | **保存判定 = `saved.json.code===200 && fail!==true`（BUILD-51）** | **禁用** `raw.includes('fail')` —— 响应恒带 `"fail":false` 键名，会把**成功误判为失败**（进而不必要重试/覆盖）；只用 `saveResultOk()` 判定（**解析后**字段）；`data` 非空 / 无告警由**回读验收**把关 |
+| ⑩ | **新报表优先克隆已验收状态，禁整表重建（BUILD-54）** | 克隆源必须是**用户确认的最新验收状态**；落库前自检 **0 旧 datasetId / 0 坐标冲突 / META 键已清**（`checkCloneDiscipline`）；禁止对已验收报表整表重建 |
+| ⑪ | **比率 / 派生指标走数据源侧预计算列（语义正解）** | 表单加字段或数据集 SQL **直出结果列**，报表**纯绑字段** —— 绕开平台级公式重映射缺陷；不要用报表内跨带公式硬凑比例 |
+
+> 一句话：**改动面 = 用户本轮点名的 reportId + 点名的项**；快照留档 → 定点改 → 回读三项验收 → 有告警即当失败处理；新报表优先克隆已验收态、派生指标走数据源预计算。

package/skill-docs/references/workflow/guide-after-submit-comment.md

@@ -0,0 +1,58 @@
+# 提交后显示与评论设置
+
+两个命令均位于 `workflow base`。无修改参数时读取当前配置，`--schema` 查看本环境字段、可选值和默认值。首次保存读取程序默认值，已有配置先读后合并；同一命令支持初始化和修改，不另建重复配置。保存后回读，返回 before/after/verified。未开放字段拒绝写入。
+
+## 提交流程后显示内容
+
+```sh
+e10-cli workflow base after-submit-display <wf> --schema
+e10-cli workflow base after-submit-display <wf> --custom 1 --pc-type 1 --pc-stay 1 --mobile-type 0
+e10-cli workflow base after-submit-display <wf> --mobile-type 3 --mobile-url '/page?requestId=${requestId}&workflowId=${workflowId}'
+e10-cli workflow base after-submit-display <wf> --custom 0
+```
+
+| 参数 | 含义 |
+|---|---|
+| --custom 0/1 | 继承全局/自定义 |
+| --pc-type、--mobile-type | 0不显示、1流程图、2审批流转情况、3自定义页面；可传实时选项名称 |
+| --pc-stay、--mobile-stay 0/1 | 是否停留在流程图（选择流程图时生效） |
+| --pc-url、--mobile-url | 自定义页面地址；内部以 / 开头，外部以 http(s) 开头；选择自定义页面时必填 |
+
+地址里的 `${requestId}`、`${workflowId}` 用单引号包裹，避免 shell 提前展开。命令只保存地址，不访问地址。修改某端时保留另一端配置。
+
+## 评论设置
+
+```sh
+e10-cli workflow base comment-set <wf> --schema
+e10-cli workflow base comment-set <wf> --custom 1 --enable 1 --allow-relate 1 --relate-range 0 --allow-upload 1 --display-type 1 --display-reply 1 --default-expand 1
+e10-cli workflow base comment-set <wf> --candidates relate
+e10-cli workflow base comment-set <wf> --relate-range 1 --relate-items workflow document
+e10-cli workflow base comment-set <wf> --candidates catalog
+e10-cli workflow base comment-set <wf> --upload-catalog <目录ID>
+e10-cli workflow base comment-set <wf> --enable 0
+e10-cli workflow base comment-set <wf> --custom 0
+```
+
+| 参数 | 含义 |
+|---|---|
+| --custom 0/1 | 继承全局/自定义评论 |
+| --enable 0/1 | 关闭/开启评论，与自定义开关独立 |
+| --allow-relate 0/1 | 允许评论关联事项 |
+| --relate-range 0/1 | 全部/选择事项类型 |
+| --relate-items ID... | 事项类型 ID，须从候选查询；不是流程实例 ID |
+| --clear-relate-items | 清空事项类型；启用选择范围时不可为空 |
+| --allow-upload 0/1 | 允许评论上传附件 |
+| --upload-catalog ID | 指定单个附件目录，0清空；需要环境开放知识管理 |
+| --display-type 0/1 | 与意见合并/评论独立显示 |
+| --display-reply 0/1 | 独立显示时，对意见的回复显示在意见区 |
+| --default-expand 0/1 | 审批意见中默认展开评论；独立显示时需显示回复才有展示效果 |
+
+候选查询返回首100项/目录根节点；事项列表不完整时停止写入，目录按选中ID回查验证。浏览器ID使用字符串。
+
+**兼容行为变更：** 旧 `--enable` 同时改两个开关，现只改启用评论。当前继承全局时修改具体项需同时显式 `--custom 1`，否则报错，避免悄悄改变继承行为。
+
+关闭自定义请单独 `--custom 0`。评论读取接口此时返回全局生效值，回读只核对自定义开关，并标注 effectiveScope=application；不声称隐藏的旧自定义值与原配置一致。未指定的普通配置项按读取结果保留。
+
+## JSON 部分修改
+
+均支持 `--data JSON` 或 `--data @文件`。不能和单独参数重复指定同一字段，不能修改 global/workflowId 等保留字段。开关使用true/false，复选框使用[]/["0"]；提交后字段见 --help，评论字段见 --help。`--schema`、`--candidates` 不与写参数混用。

package/skill-docs/references/workflow/guide-workflow.md

@@ -630,3 +630,9 @@ e10-cli workflow base file-set <workflowId> --async-delete 0
 `--create-delete`：仅发起节点才能删除附件；`--async-delete`：删除流程的同时删除表单、意见及评论附件。均支持 0/1，修改先读后合并并自动回读验证。
 
 七项功能设置完整参数、范围配置和限制见 [功能设置指南](guide-function-settings.md)。
+
+### 提交后显示与评论设置
+
+- `workflow base after-submit-display`：自定义开关、PC/移动端显示类型、流程图停留、自定义页面地址。
+- `workflow base comment-set`：自定义与评论开关独立，关联事项范围、附件目录、显示方式、回复位置、默认展开。
+- 初始化和修改均先读取程序默认/已有配置、仅合并指定项、保存后回读。详见 [提交后显示与评论指南](guide-after-submit-comment.md)。