weaver-e10-builder 1.6.16 → 1.7.1

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

@@ -1,155 +1,155 @@
-# 定点修改 · 禁止整表重扫（强制）
-
-> **适用**：用户指出「某处不对 / 修某一格 / 改某条查询 / 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` | 仍可先交设计器链接；后台只验证改动面 |
+# 定点修改 · 禁止整表重扫（强制）
+
+> **适用**：用户指出「某处不对 / 修某一格 / 改某条查询 / 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

@@ -1,101 +1,101 @@
-# 仅改用户点名项 · 禁止擅自改删报表（最高优先级 · 强制）
-
-> **优先级**：高于一切「顺手优化 / 看起来更完整 / 方便下次」的冲动。
-> **必加载**：任何会 `saveReportDevInfo` / `deleteReport` / `lifecycle delete` / `rollbackReport` / 改查询·权限·快照·数据集 的任务开始前。
-> **CLI**：（打印本政策）；映射见 `e10-cli report-cli.md` §一。
-
----
-
-## 〇、一句话
-
-**用户没点名的：不读全表乱改、不执行、不删除、不重建。**
-已搭建好的配置视为成品；Agent **只允许**调整用户**本轮明确说明**的点。
-
----
-
-## 一、硬禁止（违反即事故）
-
-| 禁止 | 说明 |
-|------|------|
-| **禁止擅自删除报表** | 未明确说「删除 / 清理 / 删壳」时，禁止 `deleteReport`、`lifecycle delete`、`cleanup shells`（清理空壳仅当用户要求或失败删壳流程且目标确为空壳） |
-| **禁止擅自改未点名配置** | 未点名的单元格、合并、样式、行高、父格、公式、查询条件、数据集、权限、快照、分组、名称等 → **一律不动** |
-| **禁止「额外」命令** | 不为「验证方便」「对齐规范」「顺便修好」而主动跑改写类 API / 脚本；只读探测也须最小化 |
-| **禁止整表覆盖式「修复」** | 禁止为改一点而重做整张表、从兄弟报表 clone、无 spans 重建导致拆合并 |
-| **禁止扩大解释范围** | 「改列宽」≠ 改样式；「冻结」≠ 改布局；「居左」≠ 改主题；「某处不对」≠ 整表重扫 |
-
----
-
-## 二、允许做什么
-
-| 条件 | 允许 |
-|------|------|
-| 用户本轮明确列出的项 | 仅这些项的最小 patch |
-| 写布局必须整表回传 workbook | **语义**只改点名项；其余 fields/style/spans **原样写回** |
-| 落库自检 | 裁剪到改动面；发现无关损坏 → **先问用户**再动，禁止自行扩大修复面 |
-| 失败删空壳 | 仅 `failure-cleanup` 定义的未落库空壳，且遵守该指南；**禁止**删用户已有正式报表 |
-
----
-
-## 三、执行前自检（强制打勾）
-
-每次准备调用会改线上报表的 API / CLI / 脚本前：
-
-1. [ ] 用户原话点名的改动列表是什么？（写下来）
-2. [ ] 本次命令/脚本是否**严格落在该列表内**？
-3. [ ] 是否包含删除、重建、整表 save、改样式/合并/查询等**未点名**动作？→ 有则 **删掉该步骤**
-4. [ ] 若不确定是否在范围内 → **先问用户，禁止猜着改**
-
----
-
-## 四、典型违规（已发生过 · 禁止再犯）
-
-| 用户只要 | Agent 错误加戏 | 后果 |
-|----------|----------------|------|
-| 列宽 + 冻结 + 居左 | 整表重建 workbook、丢 spans、压行高 | 合并拆开、样式变了 |
-| 修一个条件格式 | 重配整表 / 删其它报表 | 配置被破坏 |
-| 无明确删除指令 | `cleanup` / `deleteReport` | 报表进回收站 |
-
----
-
-## 五、与其它文档
-
-| 文档 | 关系 |
-|------|------|
-| `targeted-fix-guide.md` | 定点改的细则（本文件是总闸） |
-| `safe-partial-save-guide.md` | 整表回传 ≠ 允许语义上乱改 |
-| `failure-cleanup-and-nonblocking-guide.md` | 唯一允许的「删壳」边界 |
-| `e10-cli report-cli.md` | CLI 映射；破坏性命令须用户点名才可跑 |
-| `layout-showlocation-freeze-guide.md` | 列宽/冻结/居左仍须保 spans/样式 |
-
----
-
-## 六、CLI 对照
-
-```bash
-# 打印本政策（Agent 改配置前可先跑一遍提醒自己）
-
-# 破坏性命令 —— 仅当用户明确要求时使用
-e10-cli report lifecycle delete ...
-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 + 点名的项**；快照留档 → 定点改 → 回读三项验收 → 有告警即当失败处理；新报表优先克隆已验收态、派生指标走数据源预计算。
+# 仅改用户点名项 · 禁止擅自改删报表（最高优先级 · 强制）
+
+> **优先级**：高于一切「顺手优化 / 看起来更完整 / 方便下次」的冲动。
+> **必加载**：任何会 `saveReportDevInfo` / `deleteReport` / `lifecycle delete` / `rollbackReport` / 改查询·权限·快照·数据集 的任务开始前。
+> **CLI**：（打印本政策）；映射见 `e10-cli report-cli.md` §一。
+
+---
+
+## 〇、一句话
+
+**用户没点名的：不读全表乱改、不执行、不删除、不重建。**
+已搭建好的配置视为成品；Agent **只允许**调整用户**本轮明确说明**的点。
+
+---
+
+## 一、硬禁止（违反即事故）
+
+| 禁止 | 说明 |
+|------|------|
+| **禁止擅自删除报表** | 未明确说「删除 / 清理 / 删壳」时，禁止 `deleteReport`、`lifecycle delete`、`cleanup shells`（清理空壳仅当用户要求或失败删壳流程且目标确为空壳） |
+| **禁止擅自改未点名配置** | 未点名的单元格、合并、样式、行高、父格、公式、查询条件、数据集、权限、快照、分组、名称等 → **一律不动** |
+| **禁止「额外」命令** | 不为「验证方便」「对齐规范」「顺便修好」而主动跑改写类 API / 脚本；只读探测也须最小化 |
+| **禁止整表覆盖式「修复」** | 禁止为改一点而重做整张表、从兄弟报表 clone、无 spans 重建导致拆合并 |
+| **禁止扩大解释范围** | 「改列宽」≠ 改样式；「冻结」≠ 改布局；「居左」≠ 改主题；「某处不对」≠ 整表重扫 |
+
+---
+
+## 二、允许做什么
+
+| 条件 | 允许 |
+|------|------|
+| 用户本轮明确列出的项 | 仅这些项的最小 patch |
+| 写布局必须整表回传 workbook | **语义**只改点名项；其余 fields/style/spans **原样写回** |
+| 落库自检 | 裁剪到改动面；发现无关损坏 → **先问用户**再动，禁止自行扩大修复面 |
+| 失败删空壳 | 仅 `failure-cleanup` 定义的未落库空壳，且遵守该指南；**禁止**删用户已有正式报表 |
+
+---
+
+## 三、执行前自检（强制打勾）
+
+每次准备调用会改线上报表的 API / CLI / 脚本前：
+
+1. [ ] 用户原话点名的改动列表是什么？（写下来）
+2. [ ] 本次命令/脚本是否**严格落在该列表内**？
+3. [ ] 是否包含删除、重建、整表 save、改样式/合并/查询等**未点名**动作？→ 有则 **删掉该步骤**
+4. [ ] 若不确定是否在范围内 → **先问用户，禁止猜着改**
+
+---
+
+## 四、典型违规（已发生过 · 禁止再犯）
+
+| 用户只要 | Agent 错误加戏 | 后果 |
+|----------|----------------|------|
+| 列宽 + 冻结 + 居左 | 整表重建 workbook、丢 spans、压行高 | 合并拆开、样式变了 |
+| 修一个条件格式 | 重配整表 / 删其它报表 | 配置被破坏 |
+| 无明确删除指令 | `cleanup` / `deleteReport` | 报表进回收站 |
+
+---
+
+## 五、与其它文档
+
+| 文档 | 关系 |
+|------|------|
+| `targeted-fix-guide.md` | 定点改的细则（本文件是总闸） |
+| `safe-partial-save-guide.md` | 整表回传 ≠ 允许语义上乱改 |
+| `failure-cleanup-and-nonblocking-guide.md` | 唯一允许的「删壳」边界 |
+| `e10-cli report-cli.md` | CLI 映射；破坏性命令须用户点名才可跑 |
+| `layout-showlocation-freeze-guide.md` | 列宽/冻结/居左仍须保 spans/样式 |
+
+---
+
+## 六、CLI 对照
+
+```bash
+# 打印本政策（Agent 改配置前可先跑一遍提醒自己）
+
+# 破坏性命令 —— 仅当用户明确要求时使用
+e10-cli report lifecycle delete ...
+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 + 点名的项**；快照留档 → 定点改 → 回读三项验收 → 有告警即当失败处理；新报表优先克隆已验收态、派生指标走数据源预计算。