weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/safe-partial-save-guide.md

@@ -1,151 +1,151 @@
-# 局部功能保存 · 设计区保护规范
-
-> **适用场景**：通过 API / 脚本修改**快照、权限、查询条件、数据集筛选、页面布局**等「非布局主体」能力时。 
-> **事故根因（已验证）**：对 `saveReportDevInfo` 提交**空 workbook** 或 **workbookProps.sheets 无单元格** 的 payload，会**全量替换** `edc_reportsheetfield_dev` 等表，导致设计器字段与单元格配置被清空。 
-> **硬约束**：除非用户**明确要求删除/清除字段**，否则设计区域内容**不得被置空**。
-
----
-
-## 一、核心原则
-
-| 原则 | 说明 |
-|------|------|
-| **布局不可丢** | `getReportDevInfo.fields.length > 0` 是保存前最低门槛；保存后必须回读验证 |
-| **禁止空 workbook 落库** | `workbookProps.sheets` 为空 **且** `fields` 为空 → **禁止**调用 `saveReportDevInfo`；`fields>0` 但 sheets 空 → **必须从 fields 重建**（含 spans）后再存 |
-| **剔除 `(0,0)` 空 Const** | `x=0,y=0` 且文案空的 Const 为异常幽灵格，保存前删除 |
-| **workbookProps 不可盲信** | 线上常见 `fields=12` 但 `workbookProps.dataTable` 为空；此时必须从 **fields 重建** dataTable |
-| **groupId 原样回传** | `saveReportDevInfo` 的 `groupId`/`nameLabelId` 取自 `baseInfo`，禁止硬编码改分组 |
-| **专用接口优先** | 权限 → `savePermissions`；查询 → `saveQueryItem`；数据集筛选 → `queryInfoSave`；版本还原 → `rollbackReport` |
-| **快照是唯一例外需写 workbook** | 快照配置挂在 `workbook.snapshot`，必须走 `saveReportDevInfo`，但须套用 **§三 安全合并** |
-| **快照 ID 禁 Number()** | `sheetId`/`id`/`jobId` 必须 **String(雪花)**；`Number(reportId)` 截断 → **设计区空白**（见 `designer-blank-prevention-guide.md`） |
-| **快照默认名** | 未指定时 **`{报表名}-{date}-{time}`** |
-| **showLocation 禁 0** | 合并 workbook 时若为 0 → 改为 **2**（或用户点名居左则 1） |
-| **保存前快照版本** | 对已有报表做任意 `saveReportDevInfo` 前，建议 `saveAsVersion --list-only` 确认有版本可还原 |
-
----
-
-## 二、接口与布局影响矩阵
-
-| 操作 | 推荐接口 | 是否触及 layout/fields | 备注 |
-|------|----------|------------------------|------|
-| 使用/禁用权限 | `permission/table/savePermissions` | **否** | 全量替换权限 JSON，不动 fields |
-| 矩阵权限 | `permission/matrix/save` | **否** | |
-| 查询条件 | `saveQueryItem` / `saveQueryConfig` | **否** | |
-| 数据集筛选 | `queryInfoSave` | **否** | |
-| 存为新版本 | `saveAsVersion` | **否**（复制快照） | |
-| 还原版本 | `GET rollbackReport` | **是**（整表替换） | 用户显式还原；会重置快照配置 |
-| 页面布局/分页 | `allPageSetting` | **否**（pageSetting 独立） | |
-| 定时快照 | `saveReportDevInfo` + `workbook.snapshot` | **是（若 workbook 空则灾难）** | 必须 §三 |
-| 修改单元格/父格 | `saveReportDevInfo` +（可选）`saveReportWithCacheConfig` | **是** | **新空报表必须先 dev 后 cache**；见 `api-report-build-fast-path.md` |
-
----
-
-## 三、saveReportDevInfo 安全合并流程（强制）
-
-凡必须调用 `saveReportDevInfo` 且**不是**「从零新建报表」或「用户要求清空」：
-
-```
-1. GET getReportDevInfo?reportId=
-2. fields = data.fields || []
-3. IF fields.length === 0 → ABORT（提示先 rollbackReport 或从版本还原）
-4. wb = mergeWorkbookSafe(data, patchFn)
- ├─ 若 countCells(workbookProps) > 0 → 深拷贝 workbookProps
- └─ 否则 → buildWorkbookFromFields(fields, sheetProps) // 禁止提交空 sheets
-5. patchFn(wb) // 仅改 snapshot / 必要字段，勿删 sheets/dataTable
-6. POST saveReportDevInfo（带当前 designKey + ebBusinessId）
-7. GET getReportDevInfo 回读：
- - fields.length 不得小于保存前
- - 若用户未要求删除，fields.length === 0 → 视为事故，立即 rollbackReport
-```
-
-### 3.1 buildWorkbookFromFields 最低要求
-
-从 `fields[]` 重建时，每个 field 须写入 `data.dataTable[x][y].style`（含 `cellType` 关键属性：父格、fieldKey、leftFilterField 等）。 
-**禁止**只提交 `{ version, sheets: {} }` 或 `{ sheets: { Sheet1: { data: { dataTable: {} } } } }`。
-
-**Const（强制）**：`style.cellType` 须为完整 `ConstCellType`，至少包含：
-
-| 属性 | 说明 |
-|------|------|
-| `cellText` | 有展示文案时必填 |
-| `leftX/leftY/topX/topY` | **禁止省略**（省略 → Java int 默认 0 → 伪自定义 A1） |
-| `pcHreflink` / `openType` | 超链接 Const 必填；服务端**只认 workbook cellType**，不只认 `fields[]` 顶层 |
-
-普通 Const 父格写 `-1`；超链接含 `{L4}` 时左父格指向依赖数据格。见 `report-self-check-guide.md` §2.2。
-
-**定点修改**：用户只点一格时，语义上只改该格，但仍须整表 fields 原样写回 + 完整 workbook（见 `targeted-fix-guide.md`）。
-
-### 3.2 快照配置 patch 示例
-
-```javascript
-const wb = mergeWorkbookSafe(dev.data, (wb) => {
- wb.snapshot = {
- enableSnapshot: true,
- cron: '0 0 0 * * ?',
- // 未指定名称时的平台默认
- snapshotName: `${reportName}-{date}-{time}`,
- params: JSON.stringify({ searchCondition: {} }),
- // 雪花 ID 必须字符串，禁止 Number(reportId)（超 MAX_SAFE_INTEGER 会截断，设计器空白）
- sheetId: String(reportId),
- // 更新已有配置时可带 id/jobId（同样用 String）；rollback 后建议 omit 让服务端重建调度
- };
- // 禁止 showLocation=0
- for (const sh of Object.values(wb.sheets || {})) {
- if (!sh.tag) sh.tag = {};
- if (!sh.tag.showLocation || sh.tag.showLocation === 0) sh.tag.showLocation = 2;
- }
-});
-```
-
-### 3.3 保存后验证清单
-
-| 检查项 | 通过标准 |
-|--------|----------|
-| `fields.length` | ≥ 保存前数量（允许只增不减，除非用户要求删格） |
-| 关键单元格抽样 | 如 `(1,0)` 供应商等级 `(1,5)` 进货单编号 仍存在 |
-| `snapshot.enableSnapshot` | 若本次任务为开快照，回读为 true |
-| 设计器肉眼 | 提示用户 Ctrl+F5 强刷 |
-
----
-
-## 四、事故恢复
-
-| 现象 | 处理 |
-|------|------|
-| 设计器空白、`fields.length===0` | `GET rollbackReport?sheetId={版本snapshotId}&originSheetId={reportId}` |
-| 无版本 | 查 `getVersionWithPage`；或本地 `inspect_*.json` / 脚本备份 |
-| 快照误伤后 layout 已还原 | 快照需在设计器 **页面→快照设置** 重配，或 `set_snapshot_schedule.js`（已含保护） |
-
-**版本 ID 来源**：`save_as_version.js --list-only` → `snapshotId` 列。
-
----
-
-## 五、脚本与模块
-
-| 文件 | 用途 |
-|------|------|
-| `e10-cli report fix（内部走安全局部保存）` | **安全合并 workbook**、保存前断言、保存后验证 |
-| `e10-cli report snapshot set` | 定时快照（默认名 `{报表名}-{date}-{time}`；ID 字符串；依赖 safe_report_save） |
-| `e10-cli report verify blank` | 防设计区空白门禁（sheetId/showLocation/scrollPage） |
-| `e10-cli report restore` | 从版本 snapshotId 还原 layout |
-| `references/designer-blank-prevention-guide.md` | **设计区空白禁令与定位** |
-| `已由 CLI 取代` | `merge_workbook_safe` / `assert_layout_not_empty` / `verify_layout_preserved` |
-
----
-
-## 六、Agent 硬约束（写入 SKILL 摘要）
-
-1. **默认禁止**对已有报表提交空 workbook 或 0 fields 的 `saveReportDevInfo`。
-2. 设置权限 / 查询 / 数据集筛选 / 菜单 / 复制 → **不得**调用 `saveReportDevInfo`。
-3. 设置快照 → **必须** `mergeWorkbookSafe` + 保存前后 `fields.length` 校验。
-4. 用户未说「删除」「清空」「重置布局」→ **任何步骤不得使 fields 归零**。
-5. 保存前：`saveAsVersion` 或确认 `getVersionWithPage` 有可用版本。
-6. 保存后：`getReportDevInfo` 回读失败 → **停止后续操作**，优先 `rollbackReport`。
-
----
-
-## 七、源码依据
-
-- `EdcReportDevDesignServiceImpl.saveReportDevInfoLast`：解压 workbook → `getFieldsFromWorkbook(wb)` → **全量** `saveFields` 覆盖 DB。
-- `Workbook.snapshot`：`saveSnapshot(wb, reportId)` 仅在 workbook 含 snapshot 对象时执行；与 fields 同一保存事务。
-- `workbookProps` 与 `fields` 分离存储；API 返回的 `workbookProps.sheets` 常不含 dataTable，**不能**作为唯一布局来源。
+# 局部功能保存 · 设计区保护规范
+
+> **适用场景**：通过 API / 脚本修改**快照、权限、查询条件、数据集筛选、页面布局**等「非布局主体」能力时。
+> **事故根因（已验证）**：对 `saveReportDevInfo` 提交**空 workbook** 或 **workbookProps.sheets 无单元格** 的 payload，会**全量替换** `edc_reportsheetfield_dev` 等表，导致设计器字段与单元格配置被清空。
+> **硬约束**：除非用户**明确要求删除/清除字段**，否则设计区域内容**不得被置空**。
+
+---
+
+## 一、核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **布局不可丢** | `getReportDevInfo.fields.length > 0` 是保存前最低门槛；保存后必须回读验证 |
+| **禁止空 workbook 落库** | `workbookProps.sheets` 为空 **且** `fields` 为空 → **禁止**调用 `saveReportDevInfo`；`fields>0` 但 sheets 空 → **必须从 fields 重建**（含 spans）后再存 |
+| **剔除 `(0,0)` 空 Const** | `x=0,y=0` 且文案空的 Const 为异常幽灵格，保存前删除 |
+| **workbookProps 不可盲信** | 线上常见 `fields=12` 但 `workbookProps.dataTable` 为空；此时必须从 **fields 重建** dataTable |
+| **groupId 原样回传** | `saveReportDevInfo` 的 `groupId`/`nameLabelId` 取自 `baseInfo`，禁止硬编码改分组 |
+| **专用接口优先** | 权限 → `savePermissions`；查询 → `saveQueryItem`；数据集筛选 → `queryInfoSave`；版本还原 → `rollbackReport` |
+| **快照是唯一例外需写 workbook** | 快照配置挂在 `workbook.snapshot`，必须走 `saveReportDevInfo`，但须套用 **§三 安全合并** |
+| **快照 ID 禁 Number()** | `sheetId`/`id`/`jobId` 必须 **String(雪花)**；`Number(reportId)` 截断 → **设计区空白**（见 `designer-blank-prevention-guide.md`） |
+| **快照默认名** | 未指定时 **`{报表名}-{date}-{time}`** |
+| **showLocation 禁 0** | 合并 workbook 时若为 0 → 改为 **2**（或用户点名居左则 1） |
+| **保存前快照版本** | 对已有报表做任意 `saveReportDevInfo` 前，建议 `saveAsVersion --list-only` 确认有版本可还原 |
+
+---
+
+## 二、接口与布局影响矩阵
+
+| 操作 | 推荐接口 | 是否触及 layout/fields | 备注 |
+|------|----------|------------------------|------|
+| 使用/禁用权限 | `permission/table/savePermissions` | **否** | 全量替换权限 JSON，不动 fields |
+| 矩阵权限 | `permission/matrix/save` | **否** | |
+| 查询条件 | `saveQueryItem` / `saveQueryConfig` | **否** | |
+| 数据集筛选 | `queryInfoSave` | **否** | |
+| 存为新版本 | `saveAsVersion` | **否**（复制快照） | |
+| 还原版本 | `GET rollbackReport` | **是**（整表替换） | 用户显式还原；会重置快照配置 |
+| 页面布局/分页 | `allPageSetting` | **否**（pageSetting 独立） | |
+| 定时快照 | `saveReportDevInfo` + `workbook.snapshot` | **是（若 workbook 空则灾难）** | 必须 §三 |
+| 修改单元格/父格 | `saveReportDevInfo` +（可选）`saveReportWithCacheConfig` | **是** | **新空报表必须先 dev 后 cache**；见 `api-report-build-fast-path.md` |
+
+---
+
+## 三、saveReportDevInfo 安全合并流程（强制）
+
+凡必须调用 `saveReportDevInfo` 且**不是**「从零新建报表」或「用户要求清空」：
+
+```
+1. GET getReportDevInfo?reportId=
+2. fields = data.fields || []
+3. IF fields.length === 0 → ABORT（提示先 rollbackReport 或从版本还原）
+4. wb = mergeWorkbookSafe(data, patchFn)
+     ├─ 若 countCells(workbookProps) > 0 → 深拷贝 workbookProps
+     └─ 否则 → buildWorkbookFromFields(fields, sheetProps)  // 禁止提交空 sheets
+5. patchFn(wb)  // 仅改 snapshot / 必要字段，勿删 sheets/dataTable
+6. POST saveReportDevInfo（带当前 designKey + ebBusinessId）
+7. GET getReportDevInfo 回读：
+     - fields.length 不得小于保存前
+     - 若用户未要求删除，fields.length === 0 → 视为事故，立即 rollbackReport
+```
+
+### 3.1 buildWorkbookFromFields 最低要求
+
+从 `fields[]` 重建时，每个 field 须写入 `data.dataTable[x][y].style`（含 `cellType` 关键属性：父格、fieldKey、leftFilterField 等）。
+**禁止**只提交 `{ version, sheets: {} }` 或 `{ sheets: { Sheet1: { data: { dataTable: {} } } } }`。
+
+**Const（强制）**：`style.cellType` 须为完整 `ConstCellType`，至少包含：
+
+| 属性 | 说明 |
+|------|------|
+| `cellText` | 有展示文案时必填 |
+| `leftX/leftY/topX/topY` | **禁止省略**（省略 → Java int 默认 0 → 伪自定义 A1） |
+| `pcHreflink` / `openType` | 超链接 Const 必填；服务端**只认 workbook cellType**，不只认 `fields[]` 顶层 |
+
+普通 Const 父格写 `-1`；超链接含 `{L4}` 时左父格指向依赖数据格。见 `report-self-check-guide.md` §2.2。
+
+**定点修改**：用户只点一格时，语义上只改该格，但仍须整表 fields 原样写回 + 完整 workbook（见 `targeted-fix-guide.md`）。
+
+### 3.2 快照配置 patch 示例
+
+```javascript
+const wb = mergeWorkbookSafe(dev.data, (wb) => {
+  wb.snapshot = {
+    enableSnapshot: true,
+    cron: '0 0 0 * * ?',
+    // 未指定名称时的平台默认
+    snapshotName: `${reportName}-{date}-{time}`,
+    params: JSON.stringify({ searchCondition: {} }),
+    // 雪花 ID 必须字符串，禁止 Number(reportId)（超 MAX_SAFE_INTEGER 会截断，设计器空白）
+    sheetId: String(reportId),
+    // 更新已有配置时可带 id/jobId（同样用 String）；rollback 后建议 omit 让服务端重建调度
+  };
+  // 禁止 showLocation=0
+  for (const sh of Object.values(wb.sheets || {})) {
+    if (!sh.tag) sh.tag = {};
+    if (!sh.tag.showLocation || sh.tag.showLocation === 0) sh.tag.showLocation = 2;
+  }
+});
+```
+
+### 3.3 保存后验证清单
+
+| 检查项 | 通过标准 |
+|--------|----------|
+| `fields.length` | ≥ 保存前数量（允许只增不减，除非用户要求删格） |
+| 关键单元格抽样 | 如 `(1,0)` 供应商等级 `(1,5)` 进货单编号 仍存在 |
+| `snapshot.enableSnapshot` | 若本次任务为开快照，回读为 true |
+| 设计器肉眼 | 提示用户 Ctrl+F5 强刷 |
+
+---
+
+## 四、事故恢复
+
+| 现象 | 处理 |
+|------|------|
+| 设计器空白、`fields.length===0` | `GET rollbackReport?sheetId={版本snapshotId}&originSheetId={reportId}` |
+| 无版本 | 查 `getVersionWithPage`；或本地 `inspect_*.json` / 脚本备份 |
+| 快照误伤后 layout 已还原 | 快照需在设计器 **页面→快照设置** 重配，或 `e10-cli report snapshot`（已含保护） |
+
+**版本 ID 来源**：`e10-cli report version --list-only` → `snapshotId` 列。
+
+---
+
+## 五、脚本与模块
+
+| 文件 | 用途 |
+|------|------|
+| `` | **安全合并 workbook**、保存前断言、保存后验证 |
+| `e10-cli report snapshot` | 定时快照（默认名 `{报表名}-{date}-{time}`；ID 字符串；依赖 safe_report_save） |
+| `e10-cli report validate blank` | 防设计区空白门禁（sheetId/showLocation/scrollPage） |
+| `e10-cli report restore` | 从版本 snapshotId 还原 layout |
+| `references/designer-blank-prevention-guide.md` | **设计区空白禁令与定位** |
+|  | `merge_workbook_safe` / `assert_layout_not_empty` / `verify_layout_preserved` |
+
+---
+
+## 六、Agent 硬约束（写入 SKILL 摘要）
+
+1. **默认禁止**对已有报表提交空 workbook 或 0 fields 的 `saveReportDevInfo`。
+2. 设置权限 / 查询 / 数据集筛选 / 菜单 / 复制 → **不得**调用 `saveReportDevInfo`。
+3. 设置快照 → **必须** `mergeWorkbookSafe` + 保存前后 `fields.length` 校验。
+4. 用户未说「删除」「清空」「重置布局」→ **任何步骤不得使 fields 归零**。
+5. 保存前：`saveAsVersion` 或确认 `getVersionWithPage` 有可用版本。
+6. 保存后：`getReportDevInfo` 回读失败 → **停止后续操作**，优先 `rollbackReport`。
+
+---
+
+## 七、源码依据
+
+- `EdcReportDevDesignServiceImpl.saveReportDevInfoLast`：解压 workbook → `getFieldsFromWorkbook(wb)` → **全量** `saveFields` 覆盖 DB。
+- `Workbook.snapshot`：`saveSnapshot(wb, reportId)` 仅在 workbook 含 snapshot 对象时执行；与 fields 同一保存事务。
+- `workbookProps` 与 `fields` 分离存储；API 返回的 `workbookProps.sheets` 常不含 dataTable，**不能**作为唯一布局来源。

package/skill-docs/references/report/shard-freeze-report-guide.md

@@ -0,0 +1,97 @@
+# 多源分片与冻结表 · 场景 F（SKILL A0.16）
+
+> 典型案例：产品信息统计大宽表 —— 左侧「产品类别+产品名称」行维度，右侧规则分三片
+> （按货主地区 / 按供应商 / 按雇员统计），每片若干数值列+小计，底部总计行；
+> 长宽都大 → **不分页** + **冻结左侧行维度列与上方表头**。
+
+---
+
+## 一、案例解析（特性 → 机制 → CLI 落点）
+
+| # | 特性 | 机制 | CLI 落点 |
+|---|---|---|---|
+| ① | 多源分片（三片各挂一个统计维度） | 一张报表挂**多个数据集**（`addDataset` ×N，各返回独立 datasetId）；每片 = 一个交叉块，片内数值格 `dataSetId`/`fieldKey` 指向**各自**数据集；片与片之间用普通 Const 列隔开 | 蓝图通道：`e10-cli report rebuild from-blueprint`，spec 用 `datasets[]`（各配 `key`），格上写 `datasetKey` 选片（§6.5 crosstab guide）；**datasetId 隔离铁律照常生效**（check-ids / assertNoStaleDatasetIds） |
+| ② | 交叉统计（维度×指标） | 列维度 `Horizontal+Group`，片内数值格 `Count/sum`，**左父格→行维度、上父格→列维度**；小计/总计行公式左父格必须自定义（crosstab guide §2/§4.2） | 同交叉表直构路径（`e10-cli report build` / 蓝图），**禁手写临时 workbook** |
+| ③ | 不分页 | `pageSetting.pagination=false`（第二次保存 `saveReportWithCacheConfig`，同 card_ops 实证通道） | **`build spec` 已内置**：`layout.paginate: false`（A0.16 起；此前只有 pageRowCount 开分页方向） |
+| ④ | 冻结左侧+上方表头 | 唯一权威 = 某格 `tag.fixed=true`（保存侧→`field.fixed=1`）；预览引擎取该格 `minCell`：**上方行+左侧列**全部冻结（不含锚点自身） | **`build spec` 已内置**：`layout.freezeRows`（冻到表头）+ `layout.freezeCols`（冻左 N 列），可组合 |
+| ⑤ | 宽表居左 | `sheet.tag.showLocation=1` | `layout.showLocation:'left'`（禁 0，血案见 freeze guide §1.5） |
+
+## 二、冻结锚点语义（★ A0.16 修正版，替换旧 build spec 行为）
+
+预览引擎（`AnalysisParams.analysisFrozenCell`）只认 **fixed=1 那一格的 minCell**：
+
+```
+frozenRowCount = 锚点格.x      → 冻结其上方所有行（不含锚点行）
+frozenColumnCount = 锚点格.y   → 冻结其左侧所有列（不含锚点列）
+```
+
+所以锚点**落点决定冻结范围**，`build spec` 自动选点：
+
+| 需求 | layout 写法 | 锚点落点（自动） | 效果 |
+|---|---|---|---|
+| 冻标题+表头 | `freezeRows:1` | 首个数据行 `(dataX, 0)` | 上方全部冻住（锚点在数据格是唯一可行做法，freeze guide §2.6 推论1） |
+| 冻标题+表头+左侧 N 列 | `freezeRows:1, freezeCols:N` | `(dataX, N)` | 上方全部 + 左 N 列 |
+| 仅冻左侧 N 列（不冻行） | `freezeCols:N`（不写 freezeRows） | `(0, N)` | 只冻列 |
+| 不冻结 | 不写 | — | — |
+
+⚠️ **坑 F-1（本次修正）**：旧版 build spec 把 fixed 打在**表头格**上 → 引擎只冻「表头上方」：
+带标题时只冻标题行、无标题时一行都冻不住。已改为锚点落首个数据行。
+`e10-cli report fix freeze --anchor` 手动通道不受影响（用户显式给坐标）。
+
+⚠️ **坑 F-2**：`fixed=1` 全表**必须唯一**（引擎 `findFirst()`）；重建/改结构后回读核对。
+
+⚠️ **坑 F-3**：**禁**给锚点格写 `cellText="fixed-cell-tag"` → 服务端清空该格边框+底色。
+
+## 三、最小 spec（分片单源版；真多源走蓝图通道）
+
+```json
+{
+  "appId": "<appId>", "sourceId": "<sid>", "sourceName": "<表名>",
+  "reportName": "产品信息统计-分片冻结",
+  "columns": [
+    { "title": "产品类别", "field": "产品类别" },
+    { "title": "产品名称", "field": "产品名称" },
+    { "title": "数量", "field": "数量", "format": "value" },
+    { "title": "订购金额", "field": "订购金额", "format": "huobi" }
+  ],
+  "layout": {
+    "title": "多源分片与冻结", "showLocation": "left",
+    "freezeRows": 1, "freezeCols": 2, "paginate": false
+  }
+}
+```
+
+多源分片（三片各一数据集）spec 骨架（`rebuild from-blueprint`）：
+
+```json
+{
+  "datasets": [
+    { "key": "region", "sourceId": "<sid1>", "sourceName": "<表1>" },
+    { "key": "supplier", "sourceId": "<sid2>", "sourceName": "<表2>" },
+    { "key": "employee", "sourceId": "<sid3>", "sourceName": "<表3>" }
+  ],
+  "cells": [
+    { "r": 2, "c": 0, "datasetKey": "region", "field": "产品名称", "expand": "Vertical" },
+    { "r": 2, "c": 3, "datasetKey": "region", "field": "数量", "left": [2,0], "top": [0,3] },
+    { "r": 2, "c": 9, "datasetKey": "supplier", "field": "数量", "left": [2,0], "top": [0,9] }
+  ]
+}
+```
+
+## 四、搭建提示语句（用户照此说即可）
+
+> 按多源分片与冻结格式搭一张报表：左侧行维度「类别+名称」两列，
+> 右侧三片分别按「地区 / 供应商 / 雇员」统计数量与金额，每片带小计，底部总计行；
+> 数据源 `<sourceId/sourceName 列表>`（appId `<appId>`）；
+> 不分页、冻结左侧 2 列和上方表头、报表居左；
+> 用 `build spec`（单源）或 `rebuild from-blueprint`（多源分片）落库，
+> 落库后回读验收：fixed=1 唯一且坐标正确、pagination=false、showLocation=1。
+
+## 五、验证清单
+
+1. 回读 `getReportDevInfo`：`fixed=1` **唯一**且 minCell=锚点坐标；无 `fixed-cell-tag` 文本格
+2. `allPageSetting`（或设计器「打印与分页」）：`pagination=false`
+3. `sheetProps.showLocation === 1`
+4. 多源时跑 `e10-cli report check-ids`（exit 3 = 有外来 datasetId，禁止落库）
+5. 交叉块回读：列维度 `Horizontal`、数值格双父格（left→行维度 / top→列维度）、小计公式左父格自定义
+6. 预览冻结表现以设计器确认为准（渲染接口取不到展开数据，crosstab guide §5.4）

package/skill-docs/references/report/snowflake-id-precision-guide.md

@@ -1,84 +1,84 @@
-# 雪花 ID 精度安全指南
-
-> **适用场景**：复制报表、权限绑定、添加到菜单、删除/回收站等一切涉及 `reportId` / `pageId` 的 API 链路。 
-> **事故案例**：`copySheet` 返回 `1311221384923619328`，Node `JSON.parse` 后变为 `1311221384923619300`（末位差 28），导致权限与菜单绑到不存在的 ID。
-
----
-
-## 一、根因
-
-| 项 | 值 |
-|----|-----|
-| E10 ID 类型 | 64 位雪花 ID（19 位十进制） |
-| JS 安全整数上限 | `Number.MAX_SAFE_INTEGER = 9007199254740991`（16 位） |
-| 后果 | `JSON.parse('{"id":1311221384923619328}')` → `id === 1311221384923619300` |
-
-**Python 注意**：`json.loads` 大整数默认可保留，但 `int(report_id)` 传给部分接口仍会溢出；**全程用 `str` 承载 ID**。
-
----
-
-## 二、强制规则（Agent）
-
-1. **禁止**对含 `id` / `reportId` / `pageId` 的 API 响应裸用 `JSON.parse` / `json.loads` 后直接当数字用。
-2. **必须**使用 Skill 工具：
- - Node：`内置雪花安全解析` → `parseJsonSnowflakeSafe` / `extractIdFromRaw`
- - Python：`内置雪花安全解析` → 同名函数
-3. **copySheet 后取新 ID 双保险**：
- ```javascript
- const newId = extractIdFromRaw(copyRes.raw) || stringifyId(copyRes.json.data?.id);
- ```
- ```python
- new_id = extract_id_from_raw(cli.last_raw) or str((result.get("data") or {}).get("id", ""))
- ```
-4. **后续 API 一律字符串**：`pageId`、`sourceId`、`reportId`、`sheetId` 参数禁止 `Number(id)`。
-5. **交付给用户/手册的 reportId** 必须来自 raw 提取或 snowflake 安全解析，禁止直接打印 `json.data.id`（未安全解析时）。
-
----
-
-## 三、安全解析原理
-
-仅对**已知 ID 字段名**的 ≥16 位数字加引号后再 `JSON.parse`，**不**对嵌套 JSON 字符串内数字做全局替换（避免破坏 `tabs` 等字段）。
-
-```javascript
-// 内置雪花安全解析
-parseJsonSnowflakeSafe(rawText)
-extractIdFromRaw(rawText, ['id', 'reportId', 'pageId'])
-```
-
-```python
-# 内置雪花安全解析
-parse_json_snowflake_safe(raw_text)
-extract_id_from_raw(raw_text, keys=("id", "reportId", "pageId"))
-```
-
----
-
-## 四、受影响 API（必用安全 ID）
-
-| 操作 | API | ID 字段 |
-|------|-----|---------|
-| 复制 | `GET copySheet?sheetId=` | 响应 `data.id` |
-| 权限 | `POST savePermissions` | body key、`sourceId` |
-| 添加到菜单 | `POST savePublishMenu` | `page.pageId` |
-| 删除 | `GET deleteReport?id=` | query `id` |
-| 设计器 | `GET baseInfo?id=` | query `id` |
-| 列表 | `GET report/list` | 每项 `id` |
-
----
-
-## 五、验证清单
-
-- [ ] copySheet 后 `newReportId` 与设计器 URL 中 ID 一致（末四位无漂移）
-- [ ] `baseInfo?id={newId}` 能返回报表名称
-- [ ] 菜单 `allMenus` 中 `pageId` 与报表 ID 字符串完全一致
-- [ ] 权限 `getQueryItem` / `permission/table/list/new` 的 `sourceId` 正确
-
----
-
-## 六、相关文档
-
-| 文件 | 用途 |
-|------|------|
-| `report-lifecycle-api-guide.md` | 复制 / 权限 / 添加到菜单 API |
-| `已由 CLI 取代` | Python 客户端（已接入 snowflake 解析） |
-| `内置雪花安全解析` / `.py` | 跨语言安全解析 |
+# 雪花 ID 精度安全指南
+
+> **适用场景**：复制报表、权限绑定、添加到菜单、删除/回收站等一切涉及 `reportId` / `pageId` 的 API 链路。
+> **事故案例**：`copySheet` 返回 `1311221384923619328`，Node `JSON.parse` 后变为 `1311221384923619300`（末位差 28），导致权限与菜单绑到不存在的 ID。
+
+---
+
+## 一、根因
+
+| 项 | 值 |
+|----|-----|
+| E10 ID 类型 | 64 位雪花 ID（19 位十进制） |
+| JS 安全整数上限 | `Number.MAX_SAFE_INTEGER = 9007199254740991`（16 位） |
+| 后果 | `JSON.parse('{"id":1311221384923619328}')` → `id === 1311221384923619300` |
+
+**Python 注意**：`json.loads` 大整数默认可保留，但 `int(report_id)` 传给部分接口仍会溢出；**全程用 `str` 承载 ID**。
+
+---
+
+## 二、强制规则（Agent）
+
+1. **禁止**对含 `id` / `reportId` / `pageId` 的 API 响应裸用 `JSON.parse` / `json.loads` 后直接当数字用。
+2. **必须**使用 Skill 工具：
+   - Node：`` → `parseJsonSnowflakeSafe` / `extractIdFromRaw`
+   - Python：`` → 同名函数
+3. **copySheet 后取新 ID 双保险**：
+   ```javascript
+   const newId = extractIdFromRaw(copyRes.raw) || stringifyId(copyRes.json.data?.id);
+   ```
+   ```python
+   new_id = extract_id_from_raw(cli.last_raw) or str((result.get("data") or {}).get("id", ""))
+   ```
+4. **后续 API 一律字符串**：`pageId`、`sourceId`、`reportId`、`sheetId` 参数禁止 `Number(id)`。
+5. **交付给用户/手册的 reportId** 必须来自 raw 提取或 snowflake 安全解析，禁止直接打印 `json.data.id`（未安全解析时）。
+
+---
+
+## 三、安全解析原理
+
+仅对**已知 ID 字段名**的 ≥16 位数字加引号后再 `JSON.parse`，**不**对嵌套 JSON 字符串内数字做全局替换（避免破坏 `tabs` 等字段）。
+
+```javascript
+//
+parseJsonSnowflakeSafe(rawText)
+extractIdFromRaw(rawText, ['id', 'reportId', 'pageId'])
+```
+
+```python
+#
+parse_json_snowflake_safe(raw_text)
+extract_id_from_raw(raw_text, keys=("id", "reportId", "pageId"))
+```
+
+---
+
+## 四、受影响 API（必用安全 ID）
+
+| 操作 | API | ID 字段 |
+|------|-----|---------|
+| 复制 | `GET copySheet?sheetId=` | 响应 `data.id` |
+| 权限 | `POST savePermissions` | body key、`sourceId` |
+| 添加到菜单 | `POST savePublishMenu` | `page.pageId` |
+| 删除 | `GET deleteReport?id=` | query `id` |
+| 设计器 | `GET baseInfo?id=` | query `id` |
+| 列表 | `GET report/list` | 每项 `id` |
+
+---
+
+## 五、验证清单
+
+- [ ] copySheet 后 `newReportId` 与设计器 URL 中 ID 一致（末四位无漂移）
+- [ ] `baseInfo?id={newId}` 能返回报表名称
+- [ ] 菜单 `allMenus` 中 `pageId` 与报表 ID 字符串完全一致
+- [ ] 权限 `getQueryItem` / `permission/table/list/new` 的 `sourceId` 正确
+
+---
+
+## 六、相关文档
+
+| 文件 | 用途 |
+|------|------|
+| `report-lifecycle-api-guide.md` | 复制 / 权限 / 添加到菜单 API |
+|  | Python 客户端（已接入 snowflake 解析） |
+| `` / `.py` | 跨语言安全解析 |