weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/report/layout-showlocation-freeze-guide.md

@@ -1,196 +1,196 @@
-# 报表显示位置（居左/居中）与冻结单元格 · 功能解析（强制）
-
-> **适用**：用户要求「报表居左/居中」「冻结表头/冻结单元格」时 **必加载**。
-> **原则**：只改这两项（及用户同时点名的列宽等），**禁止**顺手重写单元格字体/颜色/行高。见 `targeted-fix-guide.md`。
-
----
-
-## 一、报表显示位置 `showLocation`
-
-### 1.1 UI → 存储枚举（前端验证）
-
-设计器「页面 → 页面布局 → 报表显示位置」写入：
-
-| 用户说法 | 写入值 | 说明 |
-|----------|--------|------|
-| **居左** | **`1`** | 前端：`showLocation = ("left" === t ? 1 : 2)` |
-| **居中** | **`2`** | 缺省；`tag` 缺失时前端也回落为 `2` |
-
-### 1.2 落点
-
-| 层 | 字段 |
-|----|------|
-| workbook | `sheets.Sheet1.tag.showLocation` |
-| 落库 | `sheetProps[0].showLocation`（由 save 从 sheet.tag 解析） |
-
-服务端：`workSheet.getTag().getIntValue("showLocation")`；**tag 为 null** 时默认写 `2`。
-
-### 1.3 致命错误：禁止写 `0` 当居左
-
-| 错误写法 | 后果 |
-|----------|------|
-| `showLocation: 0` | 前端用 **truthy** 判断：`tag.showLocation ? tag.showLocation : 2` → **`0` 被当成缺省 → 回落成 `2`（居中）**，居左「设置了但不生效」 |
-| 猜 `0`=空表默认=居左 | 空表 Java 侧曾写 `0`，**与 UI「居左」不是同一枚举** |
-
-**正确**：居左写 **`1`**；居中写 **`2`**。回读断言 `sheetProps.showLocation === 1|2`。
-
-### 1.4 视觉注意
-
-宽表（列宽×列数 ≥ 视口）时居左/居中视觉差可能不明显；仍须按枚举正确落库，不得因「看起来一样」改回错误值。
-
-### 1.5 ⚠️⚠️ 血案：手写 workbook 漏 `tag` → 显示位置被静默改成居中（2026-09-14）
-
-**症状**：修完 `tableName` 后用户反馈「报表上还是显示的不对」，定位 `fields[]`/`verify bind`/
-`listWithPageReport` **全部正常**，最终定位 `sheetProps.showLocation` 从 `1` 变成了 `2`。
-
-**根因**：用**手写临时脚本**构造 workbook 落库时，sheet 里**没有 `tag` 字段**（`tag: null`）。
-按 §1.2：**tag 为 null 时服务端默认写 `2`** → 居左被静默改成居中。
-
-**对比证据**：
-
-| 构建方式 | sheet 键数 | `tag` | showLocation 结果 |
-|---|---|---|---|
-| CLI 正规路径（`e10-cli report fix table-name` → `buildWorkbook`） | **18** | 完整对象 | ✅ 保留原值 `1` |
-| 手写临时脚本 | 7 | `null` | ❌ 被改成 `2` |
-
-CLI 正规路径的 `tag` 含：
-`childMerge` / `showLocation` / `filterSheet` / `tableNameSuffix` / `columnConfig` / `sheetConfig`；
-sheet 还含 `theme` / `names` / `__rowColHeaderVisible` / `__gridline` / `__printLineVisible` /
-`selections` / `colHeaderData` / `rowHeaderData` —— **这些都影响设计器渲染，一个都不能少**。
-
-**★ 铁律：禁止用「手写临时 workbook」直接落库生产报表。**
-服务端对缺失的非必填键**静默回落默认值**（不报错、不提示、无 diff 可查）。
-必须走 CLI 正规构建路径。
-
-**已加的护栏**：
-- `e10-cli report fix table-name` 新增 `--show-location 1|2`（显式修正）
-- dry-run 汇报打印 `显示位置 showLocation: live=X → 重建=Y (居左/居中)`
-- 落库后回读校验 `showLocation`，不一致计入失败判定
-
----
-
-## 二、冻结单元格 / 冻结表头
-
-### 2.1 UI 语义
-
-- 路径：页面 → 单元格 → **冻结单元格**
-- 冻结区域 = 锚点单元格的**上方行 + 左侧列**，**不含**锚点格本身
-- 「冻结表头」= 锚点放在**表头下一行、第 0 列**（或用户指定的首个数据格）
-
-### 2.2 设计器真实落点（前端 `setFixedCellByTarget`）
-
-仅写 `frozenRowCount` **不够**。完整落点：
-
-| 项 | 值 | 作用 |
-|----|-----|------|
-| **锚点 Const** | `cellText = "fixed-cell-tag"`，坐标 `(freezeX, freezeY)` | 设计器标记；样式透明/`1px` 字 |
-| **`cell.tag.fixed = true`** | 该锚点格 | 保存时回写 `field.fixed = 1` |
-| **`field.fixed = 1`** | 同上 | 预览引擎识别 |
-| **`sheet.tag.fixedCell`** | `{ x: freezeX, y: freezeY }` | 设计器记住锚点，取消冻结时清掉 |
-| **`frozenRowCount` / `frozenColCount`** | 通常 = `freezeX` / `freezeY` | Spread 设计区冻结线（辅助） |
-
-### 2.3 预览引擎（Custom / SimpleList）
-
-`AnalysisParams.analysisFrozenCell()`：
-
-1. 找 **第一个** `field.fixed == 1` 的字段
-2. `frozenRowCount = minCell.x`，`frozenColumnCount = minCell.y`
-3. 再应用到预览 workbook
-
-→ **没有 `fixed=1` 的锚点格，只改 sheet.`frozenRowCount`，预览不冻结。**
-
-### 2.4 如何选锚点坐标
-
-| 需求 | 锚点 `(x,y)` | 效果 |
-|------|--------------|------|
-| 冻结表头（仅行） | `(表头行+1, 0)` | 冻上方表头；不冻左侧数据列 |
-| 冻结到某数据格左上 | `(该格.x, 该格.y)` | 冻其上方与左侧（含左侧字段列） |
-| 快捷创建「锁定列」 | 给该 **Field** `fixed=1`（无 fixed-cell-tag） | 锚点=该 Field 的 minCell |
-
-**识别步骤（强制）**
-
-1. 从表布局找表头 Const 行 `headerX`、数据 Field 行 `dataX`（通常 `dataX = headerX + 1`）
-2. 「冻结表头」→ 锚点 **`(dataX, 0)`**，除非用户点名其它格
-3. 落库后回读：存在 `cellText===fixed-cell-tag` 且 `fixed===1`，坐标正确；`sheetProps`/`tag` 可核对 `fixedCell`
-
-### 2.5 取消冻结
-
-- 删除 `fixed-cell-tag` Const
-- 清所有 `field.fixed` / `tag.fixed`
-- 清 `sheet.tag.fixedCell`
-- `frozenRowCount`/`frozenColCount` → `0`
-
----
-
-### 2.6 API 落库（源码级定案 · 2026-09-14）
-
-> 用 `saveReportDevInfo` 整份落库时，**唯一真正持久化的冻结数据是 `cell.tag.fixed`**：
-
-| 项 | 保存侧是否读取 | 结论 |
-|---|---|---|
-| `cell.tag.fixed = true` | **是** → `field.fixed = 1`（`EdcReportDevDesignServiceImpl` 读 `cell.getTag().isFixed()`） | **必须写**，唯一权威 |
-| `sheet.frozenRowCount` / `frozenColCount` | **否**（保存侧无此读取） | 带上无害；预览/设计区由 `field.fixed` 推导 |
-| `sheet.tag.fixedCell = {x,y}` | **否**（sheetProps 只落 showLocation/childMerge/filterSheet/tableNameSuffix/dtTable/columnConfig/sheetConfig） | 带上无害；设计器加载时**从锚点字段重建** |
-
-**预览与设计区冻结线的唯一来源**（`AnalysisParams.analysisFrozenCell()`，仅 `Custom` / `SimpleList`）：
-
-```java
-Optional<AnalysisField> obj = this.fields.stream().filter(d -> d.getFixed() == 1).findFirst();
-OffSet cell = obj.get().getMinCell();
-setFrozenRowCount(cell.getX());      // 冻结锚点上方各行
-setFrozenColumnCount(cell.getY());   // 冻结锚点左侧各列
-```
-
-**推论（三条）**
-
-1. **锚点格不必是空格**。设计器 `setFixedCellByTarget` 只在锚点格 `cellType.typeName` 为假（空格）时才补写
-   `cellText="fixed-cell-tag"` + 透明样式；**占用格（数据字段所在格）它什么都不写**，只更新内存里的 `tag.fixedCell`。
-   所以「用 API 把锚点设在数据格上」是**唯一可行**的做法 —— 只置 `tag.fixed` 即可，预览照样冻结。
-2. **禁止**顺手给锚点格写 `cellText="fixed-cell-tag"`：服务端会据此把该格**边框 4 边 + 底色清空**
-   （`CustomEngine`/`SimpleListEngine` 的 `field.getFixed()==1 && "fixed-cell-tag".equals(cellText)` 分支），
-   属于改动未点名格的样式。
-3. **`fixed=1` 的字段必须唯一**。`findFirst()` 取的是字段列表里第一个 `fixed==1`，多个会以第一个为准（顺序 = x 升序、同 x 按 y）→ 落库前先清掉所有旧 `fixed`。
-
-**锚点坐标怎么选**
-
-| 目标 | 锚点 `(x, y)`（0 基） |
-|---|---|
-| 仅冻结表头（前 `h` 行） | `(h, 0)` |
-| 表头 + 左侧 `c` 列 | `(h, c)` |
-
-CLI：`e10-cli report fix freeze --report-id <id> --app-id <aid> --anchor 4,3 [--apply]`（默认 dry-run）。
-
-**脚本会拒绝落库的两种情况**
-
-1. **重建保真度不足**（除冻结点外与线上 `fields[]` 有差异）→ 拒绝，避免误伤；
-2. **重复坐标**（同一 `(x,y)` 在 `fields[]` 里有 ≥2 条记录）→ 报 `exit 3` 并列出各条 `id/createTime`。
-   典型成因：**在设计器里把字段拖到某个表头格上**，旧 Const 未被清掉 → 该格"表头 + 字段"两条记录并存。
-   此时 workbook 一个坐标只能放一格，重建必然丢一条 → 必须先由用户确认取舍（或先去设计器清理）。
-
----
-
-## 三、定点改 checklist（禁止伤样式）
-
-用户只说「列宽 / 冻结 / 居左」时：
-
-| 允许 | 禁止 |
-|------|------|
-| 改目标列 `width` + workbook `columns[]` 对应 `size` | 用默认 style 重建整表 cell |
-| 增/改 `fixed-cell-tag` + `showLocation` + freeze 计数 | 改未点名格的 font/backColor/border/行高 |
-| 其它格 **原样**写回（style JSON 原串） | 为「方便」从零 `fieldToCell` 丢 tag/合并/条件格式 |
-| 保留并回写原 `spans` / `xCount`/`yCount` | **拆掉或漏写合并**（无任何规则授权「取消合并」） |
-
-`columns` 必须是 **数组** `[{size:N}, …]`，不能是 `{ "3": {size:250} }` 对象。
-
-**合并单元格**：`fields.xCount/yCount` ↔ workbook `spans`（`row/col/rowCount/colCount`）及 cell `rowCount/colCount`。重建 workbook 漏 spans = 表头/表尾合并消失。
-
----
-
-## 四、与其它文档
-
-| 文档 | 关系 |
-|------|------|
-| `targeted-fix-guide.md` | 定点范围；样式禁碰 |
-| `report-designer-feature-map.md` §4.2 / §4.6 | UI 入口索引 |
-| `safe-partial-save-guide.md` | 完整 workbook 写回 |
-| `` → `fieldToCell` | 须把 `fixed` 写入 `cell.tag.fixed` |
+# 报表显示位置（居左/居中）与冻结单元格 · 功能解析（强制）
+
+> **适用**：用户要求「报表居左/居中」「冻结表头/冻结单元格」时 **必加载**。
+> **原则**：只改这两项（及用户同时点名的列宽等），**禁止**顺手重写单元格字体/颜色/行高。见 `targeted-fix-guide.md`。
+
+---
+
+## 一、报表显示位置 `showLocation`
+
+### 1.1 UI → 存储枚举（前端验证）
+
+设计器「页面 → 页面布局 → 报表显示位置」写入：
+
+| 用户说法 | 写入值 | 说明 |
+|----------|--------|------|
+| **居左** | **`1`** | 前端：`showLocation = ("left" === t ? 1 : 2)` |
+| **居中** | **`2`** | 缺省；`tag` 缺失时前端也回落为 `2` |
+
+### 1.2 落点
+
+| 层 | 字段 |
+|----|------|
+| workbook | `sheets.Sheet1.tag.showLocation` |
+| 落库 | `sheetProps[0].showLocation`（由 save 从 sheet.tag 解析） |
+
+服务端：`workSheet.getTag().getIntValue("showLocation")`；**tag 为 null** 时默认写 `2`。
+
+### 1.3 致命错误：禁止写 `0` 当居左
+
+| 错误写法 | 后果 |
+|----------|------|
+| `showLocation: 0` | 前端用 **truthy** 判断：`tag.showLocation ? tag.showLocation : 2` → **`0` 被当成缺省 → 回落成 `2`（居中）**，居左「设置了但不生效」 |
+| 猜 `0`=空表默认=居左 | 空表 Java 侧曾写 `0`，**与 UI「居左」不是同一枚举** |
+
+**正确**：居左写 **`1`**；居中写 **`2`**。回读断言 `sheetProps.showLocation === 1|2`。
+
+### 1.4 视觉注意
+
+宽表（列宽×列数 ≥ 视口）时居左/居中视觉差可能不明显；仍须按枚举正确落库，不得因「看起来一样」改回错误值。
+
+### 1.5 ⚠️⚠️ 血案：手写 workbook 漏 `tag` → 显示位置被静默改成居中（2026-09-14）
+
+**症状**：修完 `tableName` 后用户反馈「报表上还是显示的不对」，定位 `fields[]`/`verify bind`/
+`listWithPageReport` **全部正常**，最终定位 `sheetProps.showLocation` 从 `1` 变成了 `2`。
+
+**根因**：用**手写临时脚本**构造 workbook 落库时，sheet 里**没有 `tag` 字段**（`tag: null`）。
+按 §1.2：**tag 为 null 时服务端默认写 `2`** → 居左被静默改成居中。
+
+**对比证据**：
+
+| 构建方式 | sheet 键数 | `tag` | showLocation 结果 |
+|---|---|---|---|
+| CLI 正规路径（`e10-cli report fix table-name` → `buildWorkbook`） | **18** | 完整对象 | ✅ 保留原值 `1` |
+| 手写临时脚本 | 7 | `null` | ❌ 被改成 `2` |
+
+CLI 正规路径的 `tag` 含：
+`childMerge` / `showLocation` / `filterSheet` / `tableNameSuffix` / `columnConfig` / `sheetConfig`；
+sheet 还含 `theme` / `names` / `__rowColHeaderVisible` / `__gridline` / `__printLineVisible` /
+`selections` / `colHeaderData` / `rowHeaderData` —— **这些都影响设计器渲染，一个都不能少**。
+
+**★ 铁律：禁止用「手写临时 workbook」直接落库生产报表。**
+服务端对缺失的非必填键**静默回落默认值**（不报错、不提示、无 diff 可查）。
+必须走 CLI 正规构建路径。
+
+**已加的护栏**：
+- `e10-cli report fix table-name` 新增 `--show-location 1|2`（显式修正）
+- dry-run 汇报打印 `显示位置 showLocation: live=X → 重建=Y (居左/居中)`
+- 落库后回读校验 `showLocation`，不一致计入失败判定
+
+---
+
+## 二、冻结单元格 / 冻结表头
+
+### 2.1 UI 语义
+
+- 路径：页面 → 单元格 → **冻结单元格**
+- 冻结区域 = 锚点单元格的**上方行 + 左侧列**，**不含**锚点格本身
+- 「冻结表头」= 锚点放在**表头下一行、第 0 列**（或用户指定的首个数据格）
+
+### 2.2 设计器真实落点（前端 `setFixedCellByTarget`）
+
+仅写 `frozenRowCount` **不够**。完整落点：
+
+| 项 | 值 | 作用 |
+|----|-----|------|
+| **锚点 Const** | `cellText = "fixed-cell-tag"`，坐标 `(freezeX, freezeY)` | 设计器标记；样式透明/`1px` 字 |
+| **`cell.tag.fixed = true`** | 该锚点格 | 保存时回写 `field.fixed = 1` |
+| **`field.fixed = 1`** | 同上 | 预览引擎识别 |
+| **`sheet.tag.fixedCell`** | `{ x: freezeX, y: freezeY }` | 设计器记住锚点，取消冻结时清掉 |
+| **`frozenRowCount` / `frozenColCount`** | 通常 = `freezeX` / `freezeY` | Spread 设计区冻结线（辅助） |
+
+### 2.3 预览引擎（Custom / SimpleList）
+
+`AnalysisParams.analysisFrozenCell()`：
+
+1. 找 **第一个** `field.fixed == 1` 的字段
+2. `frozenRowCount = minCell.x`，`frozenColumnCount = minCell.y`
+3. 再应用到预览 workbook
+
+→ **没有 `fixed=1` 的锚点格，只改 sheet.`frozenRowCount`，预览不冻结。**
+
+### 2.4 如何选锚点坐标
+
+| 需求 | 锚点 `(x,y)` | 效果 |
+|------|--------------|------|
+| 冻结表头（仅行） | `(表头行+1, 0)` | 冻上方表头；不冻左侧数据列 |
+| 冻结到某数据格左上 | `(该格.x, 该格.y)` | 冻其上方与左侧（含左侧字段列） |
+| 快捷创建「锁定列」 | 给该 **Field** `fixed=1`（无 fixed-cell-tag） | 锚点=该 Field 的 minCell |
+
+**识别步骤（强制）**
+
+1. 从表布局找表头 Const 行 `headerX`、数据 Field 行 `dataX`（通常 `dataX = headerX + 1`）
+2. 「冻结表头」→ 锚点 **`(dataX, 0)`**，除非用户点名其它格
+3. 落库后回读：存在 `cellText===fixed-cell-tag` 且 `fixed===1`，坐标正确；`sheetProps`/`tag` 可核对 `fixedCell`
+
+### 2.5 取消冻结
+
+- 删除 `fixed-cell-tag` Const
+- 清所有 `field.fixed` / `tag.fixed`
+- 清 `sheet.tag.fixedCell`
+- `frozenRowCount`/`frozenColCount` → `0`
+
+---
+
+### 2.6 API 落库（源码级定案 · 2026-09-14）
+
+> 用 `saveReportDevInfo` 整份落库时，**唯一真正持久化的冻结数据是 `cell.tag.fixed`**：
+
+| 项 | 保存侧是否读取 | 结论 |
+|---|---|---|
+| `cell.tag.fixed = true` | **是** → `field.fixed = 1`（`EdcReportDevDesignServiceImpl` 读 `cell.getTag().isFixed()`） | **必须写**，唯一权威 |
+| `sheet.frozenRowCount` / `frozenColCount` | **否**（保存侧无此读取） | 带上无害；预览/设计区由 `field.fixed` 推导 |
+| `sheet.tag.fixedCell = {x,y}` | **否**（sheetProps 只落 showLocation/childMerge/filterSheet/tableNameSuffix/dtTable/columnConfig/sheetConfig） | 带上无害；设计器加载时**从锚点字段重建** |
+
+**预览与设计区冻结线的唯一来源**（`AnalysisParams.analysisFrozenCell()`，仅 `Custom` / `SimpleList`）：
+
+```java
+Optional<AnalysisField> obj = this.fields.stream().filter(d -> d.getFixed() == 1).findFirst();
+OffSet cell = obj.get().getMinCell();
+setFrozenRowCount(cell.getX());      // 冻结锚点上方各行
+setFrozenColumnCount(cell.getY());   // 冻结锚点左侧各列
+```
+
+**推论（三条）**
+
+1. **锚点格不必是空格**。设计器 `setFixedCellByTarget` 只在锚点格 `cellType.typeName` 为假（空格）时才补写
+   `cellText="fixed-cell-tag"` + 透明样式；**占用格（数据字段所在格）它什么都不写**，只更新内存里的 `tag.fixedCell`。
+   所以「用 API 把锚点设在数据格上」是**唯一可行**的做法 —— 只置 `tag.fixed` 即可，预览照样冻结。
+2. **禁止**顺手给锚点格写 `cellText="fixed-cell-tag"`：服务端会据此把该格**边框 4 边 + 底色清空**
+   （`CustomEngine`/`SimpleListEngine` 的 `field.getFixed()==1 && "fixed-cell-tag".equals(cellText)` 分支），
+   属于改动未点名格的样式。
+3. **`fixed=1` 的字段必须唯一**。`findFirst()` 取的是字段列表里第一个 `fixed==1`，多个会以第一个为准（顺序 = x 升序、同 x 按 y）→ 落库前先清掉所有旧 `fixed`。
+
+**锚点坐标怎么选**
+
+| 目标 | 锚点 `(x, y)`（0 基） |
+|---|---|
+| 仅冻结表头（前 `h` 行） | `(h, 0)` |
+| 表头 + 左侧 `c` 列 | `(h, c)` |
+
+CLI：`e10-cli report fix freeze --report-id <id> --app-id <aid> --anchor 4,3 [--apply]`（默认 dry-run）。
+
+**脚本会拒绝落库的两种情况**
+
+1. **重建保真度不足**（除冻结点外与线上 `fields[]` 有差异）→ 拒绝，避免误伤；
+2. **重复坐标**（同一 `(x,y)` 在 `fields[]` 里有 ≥2 条记录）→ 报 `exit 3` 并列出各条 `id/createTime`。
+   典型成因：**在设计器里把字段拖到某个表头格上**，旧 Const 未被清掉 → 该格"表头 + 字段"两条记录并存。
+   此时 workbook 一个坐标只能放一格，重建必然丢一条 → 必须先由用户确认取舍（或先去设计器清理）。
+
+---
+
+## 三、定点改 checklist（禁止伤样式）
+
+用户只说「列宽 / 冻结 / 居左」时：
+
+| 允许 | 禁止 |
+|------|------|
+| 改目标列 `width` + workbook `columns[]` 对应 `size` | 用默认 style 重建整表 cell |
+| 增/改 `fixed-cell-tag` + `showLocation` + freeze 计数 | 改未点名格的 font/backColor/border/行高 |
+| 其它格 **原样**写回（style JSON 原串） | 为「方便」从零 `fieldToCell` 丢 tag/合并/条件格式 |
+| 保留并回写原 `spans` / `xCount`/`yCount` | **拆掉或漏写合并**（无任何规则授权「取消合并」） |
+
+`columns` 必须是 **数组** `[{size:N}, …]`，不能是 `{ "3": {size:250} }` 对象。
+
+**合并单元格**：`fields.xCount/yCount` ↔ workbook `spans`（`row/col/rowCount/colCount`）及 cell `rowCount/colCount`。重建 workbook 漏 spans = 表头/表尾合并消失。
+
+---
+
+## 四、与其它文档
+
+| 文档 | 关系 |
+|------|------|
+| `targeted-fix-guide.md` | 定点范围；样式禁碰 |
+| `report-designer-feature-map.md` §4.2 / §4.6 | UI 入口索引 |
+| `safe-partial-save-guide.md` | 完整 workbook 写回 |
+| `` → `fieldToCell` | 须把 `fixed` 写入 `cell.tag.fixed` |