weaver-work-cli 0.1.24 → 0.1.26

package/skills/weaver-e10-builder/references/report/guide-report-query.md

@@ -0,0 +1,98 @@
+# 报表查询条件（高级搜索 / 筛选）
+
+> 细则与完整字段表见 `query-condition-api-guide.md`；本条是入口与最容易踩的几点。
+
+---
+
+## 一、先分清「显示方式」与「条件本身」
+
+报表页顶部的查询区有两种形态：
+
+| 显示方式 | 落库 `queryType` | 用户在页面上看到 |
+|---|---|---|
+| 高级搜索 | `'["advance"]'` | 点开才展开的高级搜索面板 |
+| 筛选 | `'["filter"]'` | 顶部平铺的筛选条 |
+
+**必须写成 JSON 数组短码**。写成 `"advancedSearch"` 这种长码，服务端照收，
+但设计器「显示方式」不勾选 —— 用户会以为配置丢了。
+
+```bash
+e10-cli report query check-echo <reportId> --app-id <appId>   # 体检
+e10-cli report query fix-echo   <reportId> --app-id <appId>   # 修复
+```
+
+---
+
+## 二、两条不可逾越的线
+
+### 2.1 `updateQueryType` 是**报表级**批量覆盖
+
+它会把入参写到**所有**条件上，不是只改你这一条。
+
+所以：**只有用户明确点名要改显示方式时才调用**。不点名时 `report query type` 只回读、不写。
+
+混着筛选和高级搜索的报表，被它跑一次就全拉平了。
+
+### 2.2 绝不注入 `advancedSearchType`
+
+写 `'openCondition'` 会把报表页查询区从「默认样式」改成「展开条件」——
+这是**擅改用户的展示样式**。入参里没有这个键就不要写。
+
+存量误注入的清理：`e10-cli report fix query-style <reportId> --app-id <appId> --apply`
+
+---
+
+## 三、保存一条条件
+
+```bash
+e10-cli report query save <reportId> --app-id <appId> --item item.json
+e10-cli report query save <reportId> --app-id <appId> --item item.json --show-where 高级搜索
+```
+
+CLI 会自动补齐：
+
+- **默认值三件套** `defaultValueType` / `defaultValue` / `type1DefaultValue` / `type2DefaultValue`
+  （漏写会让设计器弹窗「默认值类型」=请选择、默认值区炸开、后面整段字段被顶出可视区）
+- `filterParam` 默认对象
+- `displayType`（按字段元数据推断：人员/部门→关联浏览，日期→区间，下拉→等于，其余→包含）
+- 关联浏览的**富对象**（简写 `[{id:'HrmEmployeeComInfo'}]` 不足以让设计器「关联类型」回显）
+
+**必须带 `id`**，否则服务端会当成新增，产生重复条件。
+
+---
+
+## 四、改完必查
+
+```bash
+e10-cli report query verify <reportId> --app-id <appId>          # Q1~Q10
+e10-cli report query verify <reportId> --app-id <appId> --fix    # 顺带做幂等修复
+```
+
+`--fix` 只做三件安全事：清 `advancedSearchType`、补三件套、`queryType` 短码化。
+**绝不新增或删除条件** —— 增删条件是用户的决定。
+
+Q1~Q10 判据速查：
+
+| 码 | 判据 |
+|---|---|
+| Q1 | `queryType` 是数组短码 |
+| Q2 | `advancedSearchType` 必须为空 |
+| Q3~Q5 | 默认值三件套齐全 |
+| Q6 | 有 `id`、`asNameIndex` 唯一 |
+| Q7 | `displayType=browser` 时 `browserType` 富对象非空 |
+| Q8 | `filterParam` 存在（`showType` 缺只作提示） |
+| Q9 | `showOrder` 建议为 0（仅提示） |
+| Q10 | 报表级 `queryType` 不混杂 |
+
+---
+
+## 五、常见需求对照
+
+| 用户说 | 怎么做 |
+|---|---|
+| 「加个按客户名查」 | `query save`，`displayType=text`，`relation=Contain` |
+| 「按年月筛选」 | `displayType=date.ym`，`relation=between`，默认值给 `["{yearmonth:-0}",""]` |
+| 「按部门筛选，默认本部门」 | `displayType=browser`（自动取富对象）+ 默认值走 custom |
+| 「这条件放筛选条不放高级搜索」 | `--show-where 筛选`（**只在这一条上**；会触发报表级覆盖，要确认用户是整表统一） |
+| 「条件顺序调一下」 | `report fix query-default --show-order 0` |
+| 「默认值不对」 | `report fix query-default --set "年月=custom:[\"{yearmonth:-0}\",\"\"]" --apply` |

package/skills/weaver-e10-builder/references/report/hidden-row-and-header-merge-guide.md

@@ -0,0 +1,100 @@
+# 空白行 与 表头合并（Excel → 报表 对齐）
+
+> 触发场景：用户拿一份 Excel 效果图来搭表，之后反馈
+> 「第 N 行多了一个空白行」「表头标题没有参考 Excel 合并」。
+> 2026-09-14 事故实录：考勤汇总报表 `1314970921403138199`。
+
+## 一、`rows[i].size = 0` **不会隐藏行**
+
+workbook `sheets.Sheet1.rows` 是**行高数组**，不是可见性开关。
+
+| 写法 | 服务端行为 | 结果 |
+|------|-----------|------|
+| `{ size: 0 }` | 规范化为 `null`（落回默认行高） | ❌ **照旧渲染成一条可见空行** |
+| 不写这一行 | — | ✅ 该行不存在 |
+| `rowVisible: 0`（field 层） | 仅影响字段格 | 不用于「整行不要」 |
+
+**结论：要让某一行不存在，就在 `dataTable` + `rows` 里根本不放它，后续行整体上移。**
+
+### Excel 的 `hidden=1` 行怎么处理
+
+Excel 里 `ht="0" hidden="1"` 的行（常见用途：表头与数据之间的**垫行**），
+在 Excel 中不可见 → 报表里也应**直接删掉**，让表头下一行就是数据行。
+
+对齐判据（用户视角）：Excel 隐藏行=看不见 → 报表里也不该出现这一行。
+
+## 二、合并单元格 = workbook `spans`
+
+> 合并**只能**靠 `sheets.Sheet1.spans` 表达，`style.border`/`hAlign` 与合并无关。
+
+```js
+spans = [
+ { row: 2, col: 0, rowCount: 2, colCount: 1 }, // 固定列表头纵向合并（Excel B3:B4）
+ { row: 2, col: 45, rowCount: 1, colCount: 3 }, // 日期区横向合并（Excel AU3:AW3）
+]
+```
+
+| 字段 | 含义 | 对应 `fields` |
+|------|------|---------------|
+| `row` / `col` | 合并区左上角（**0-based**，row=行、col=列） | `x` = row、`y` = col |
+| `rowCount` | **行**跨度 | `fields.xCount` |
+| `colCount` | **列**跨度 | `fields.yCount` |
+
+要点：
+
+1. **`row`/`col` 是 0-based**，而 Excel 的 `mergeCells` 是 1-based → 换算 `row = excelRow - 1`、`col = excelColNum - 1`。
+2. 日期/交叉维度区块本就必须 `colCount = 块宽`（本包默认日期块 3 列），**不要再叠加一次**，否则块宽翻倍。
+3. **只写 `spans` 即可生效**，可不写 cell 级 `rowCount`/`colCount`（服务端统一按 spans 回写 `xCount`/`yCount`）。
+4. 合并区内的非左上角单元格**不要放内容**（Excel 同理），否则合并语义混乱。
+
+### 从 Excel 提取 mergeCells（本环境 xlsx 常被 openpyxl 拒读）
+
+`openpyxl` 遇到非法 `styles.xml`（如非法 border `style`）会抛 `ValueError` → 改为**解 zip 直读 XML**：
+
+```python
+import zipfile, xml.etree.ElementTree as ET
+NS = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
+sh = ET.fromstring(zipfile.ZipFile(path).read("xl/worksheets/sheet1.xml"))
+mc = sh.find(f"{NS}mergeCells")
+refs = [m.attrib["ref"] for m in mc.findall(f"{NS}mergeCell")] # ["B3:B4", "AU3:AW3", ...]
+```
+
+映射规律（常见表头）：
+
+| Excel merge | 报表 spans | 说明 |
+|---|---|---|
+| `B3:B4` … `AT3:AT4` | 每列 `{row:2, col:i, rowCount:2, colCount:1}` | 固定列表头纵向跨「列名 + 星期」两行 |
+| `AU3:AW3` | `{row:2, col:45, rowCount:1, colCount:3}` | 日期表头横向跨 3 列 |
+| `AU4:AW4` | `{row:3, col:45, rowCount:1, colCount:3}` | 星期行同理 |
+| `AU1:CH1`（跨全部日期块） | 设计态只写**一个块宽**（`colCount:3`） | 设计态只摆 1 个日期块，展开由引擎做；照抄 42 列会把块宽搞错 |
+
+## 三、验证：渲染回读（唯一可信证据）
+
+设计态 `getReportDevInfo` **不返回 workbook**（`workbookProps.sheets` 恒为 `{}`），
+只能看 `fields`（含 `xCount`/`yCount`）——**不能证明渲染效果**。要看用户到底看见什么，必须走渲染链：
+
+```
+POST /api/edc/report/view/analysis (multipart；sheetId=reportId、pageFilter、pageNum…)
+ → data.json[0] = sessionKey
+GET /api/edc/report/view/getJsonStr?sessionKey=<key>
+ → gunzip → workbook（含展开后的 dataTable / rows / spans）
+```
+
+判据：
+
+- **无多余空行**：下一行（0-based = `数据行 index`）应已是非空数据行。
+ 例：表头 r2、星期 r3 → r4 必须是数据（此前 r4 全空 = 事故）。
+- **表头合并生效**：渲染 `spans` 中应存在 `{row:表头行, rowCount:2, colCount:1}` 共 N 条（N=固定列数）、
+ 以及 `{row:表头行, col:日期起始列, colCount:块宽}`。
+
+⚠️ 渲染有 **50000 单元格上限**（超限 `code:555`）。估算：`渲染行数 × 列数`。
+本例 `1004 × 48 ≈ 48192` 勉强过关；列维度一展开就会超，需靠默认查询条件收敛。
+
+## 四、修复动线（保持同一 reportId）
+
+1. `getReportDevInfo` 取当前 `designKey`；`baseInfo` 取当前 `name`。
+2. 按新布局重建 workbook（`rows` 少一行、`spans` 补齐）。
+3. `saveReportDevInfo`（multipart：`groupId/appId/reportId/name/nameLabelId/designKey/workbook`）。
+4. 渲染回读复核 → 交设计器地址。
+
+**不需要**重新建表，**不要**另建报表（一次任务只建 1 壳）。

package/skills/weaver-e10-builder/references/report/layout-showlocation-freeze-guide.md

@@ -0,0 +1,167 @@
+# 报表显示位置（居左/居中）与冻结单元格 · 功能解析（强制）
+
+> **适用**：用户要求「报表居左/居中」「冻结表头/冻结单元格」时 **必加载**。
+> **原则**：只改这两项（及用户同时点名的列宽等），**禁止**顺手重写单元格字体/颜色/行高。见 `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 视觉注意
+
+宽表（列宽×列数 ≥ 视口）时居左/居中视觉差可能不明显；仍须按枚举正确落库，不得因「看起来一样」改回错误值。
+
+---
+
+## 二、冻结单元格 / 冻结表头
+
+### 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 写回 |
+| `safe_report_save.js` → `fieldToCell` | 须把 `fixed` 写入 `cell.tag.fixed` |

package/skills/weaver-e10-builder/references/report/preaggregate-auto-disable-guide.md

@@ -0,0 +1,107 @@
+# 数据预聚合自动关闭指南
+
+> **解析优化 · 数据预聚合**（设计器「页面 → 报表展示 · 解析优化」）对应 `sheetConfig.dataPreAgg`（默认 `true`）。
+> 当数据源字段或报表布局不满足引擎预聚合条件时，**必须自动关闭**，避免预览/解析异常或静默降级。
+> **勿混淆**：左侧数据集菜单「**数据聚合**」是 `aggregationSave`（见 `dataset-sidebar-ops-guide.md`），不是本指南的 `dataPreAgg`。
+
+---
+
+## 一、源码依据
+
+| 来源 | 规则 |
+|------|------|
+| `SheetServiceImpl.existNotAllAllowAggregate` | 数据集字段 `gdBySelf=true` → 不支持预聚合 |
+| 同上 | 字段 `usage == "list"` → 不支持（仅 `""`/`all`/`char`/`aggregate` 支持分组） |
+| `BaseEngine.initDataSetByGroup` | `sheetConfig.dataPreAgg=false` → 全局跳过 |
+| 同上 | 单元格存在 `customFilterField` 或 `dataFilterField` → 该 dataset 不参与预聚合 |
+| 同上 | 存在 `displayType=List`（排列）字段 → 该 dataset 不参与 |
+| `GCONST.NO_GROUP_COMP_TYPE` | 分组字段 `compType` 为 `TextArea` / `RichText` → 不可预分组 |
+
+---
+
+## 二、检测时机（Agent 必做）
+
+在 **addDataset 后、saveReportWithCacheConfig 前**：
+
+1. 调用 `GET /api/bs/edc/dataset/fieldsAndOriginFields?datasetId={id}&hasField=true&isFront=true`
+2. 读取 `data.fieldsKey` 或 `data.originFields` 中每个字段的 `usage`、`originField.compType`、`gdBySelf`（若在 dataset 级）
+3. 结合已规划的报表字段（displayType、customFilterField）运行检测脚本
+
+```bash
+python e10-cli report py preagg --fields-json <fields.json> [--layout-json <report_fields.json>]
+```
+
+---
+
+## 三、判定逻辑（摘要）
+
+**以下任一成立 → `dataPreAgg: false`**
+
+### 3.1 字段元数据（数据源）
+
+- 任一绑定字段 `usage == "list"`
+- 任一作为**分组**使用的字段 `originField.compType ∈ {TextArea, RichText}`
+- 数据集级标记 `gdBySelf == true`
+
+### 3.2 报表布局
+
+- 任一字段 `displayType == "List"`（排列）
+- 任一字段 `customFilterField` 或 `dataFilterField` 非空
+- 多数据集且存在跨表 `leftFilterField`（父格筛选参与取数，引擎对涉及 dataset 跳过预聚合）
+
+---
+
+## 四、写入方式
+
+### 4.1 pageSetting / sheetConfig
+
+双保存时 `pageSetting` 或 sheet props 中写入：
+
+```json
+{
+ "0": {
+ "rowHeader": 0,
+ "colHeader": 0,
+ "gridLine": 0,
+ "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+ }
+}
+```
+
+> **注意**：`rowHeader` / `colHeader` / `gridLine` 保持 **0**（默认关闭）。勿为写 `sheetConfig` 而顺带把网格线/行号列头写成 `1`；见 `report-designer-feature-map.md` §4.6.1。
+
+### 4.2 ReportProps JSON
+
+```json
+"sheetProps": {
+ "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+}
+```
+
+### 4.3 脚本辅助
+
+`check_preaggregate_support.py` 输出：
+
+```json
+{
+ "dataPreAgg": false,
+ "reasons": ["字段[备注] usage=list 不支持预聚合", "…"],
+ "sheetConfig": "{\"dataPreAgg\":false,\"simpleList\":false}"
+}
+```
+
+---
+
+## 五、Agent 流程嵌入
+
+1. 获取字段元数据 → 运行 `check_preaggregate_support.py`
+2. 若 `dataPreAgg=false`，在 save 载荷中写入 `sheetConfig`，并在 HTML 手册 `tips` 中注明「已关闭数据预聚合：原因…」
+3. 保存后 `getReportDevInfo` / 设计器「页面 → 解析优化」确认开关状态
+
+---
+
+## 六、相关文档
+
+- `report-designer-feature-map.md` — 解析优化入口
+- `report-knowledge-base.md` §1.2 — 预聚合概念
+- `report-delivery-contract.md` — 交付自检含预聚合项