weaver-e10-builder 1.6.9 → 1.6.11

package/skill-docs/references/report/crosstab-raw-workbook-guide.md

@@ -0,0 +1,265 @@
+# 交叉表原始 workbook 直构指南（月份横向扩展 × 多指标）
+
+> 适用：build spec / buildWorkbook 只支持平铺表头（expandType 固定 NoExpand/Vertical），无法表达
+> 「列维度横向扩展 + 月份下挂多指标 + 合计行」。此时直接构造原始 workbook，走与 build spec
+> 相同的保存通道（`saveReportDevInfo` + `designKey:''` + gzip base64 workbook）。
+> 2026-09-15 在「采招投标预算合同统计表」(reportId 1315344454775046144) 验证通过：
+> 1.9s 落库，10 个 Formula 格全部存活，verify self 0 错 0 警。
+
+## 1. 何时用
+
+- 效果图是交叉矩阵（行维度 × 时间横向扩展 × 每格多指标 + 合计行/合计列）
+- 复用已有报表时：先 `getReportDevInfo` 取 `fields[]`（含 dataSetId/name/nameIndex/fieldId/tableName），按 text 匹配绑定字段，重写 workbook 后原 reportId 覆盖保存（数据集无需重挂）。
+- ★ **重建一律调用 `e10-cli report build`**（`buildWorkbookFromFields(devData, {sheetConfig, setCells})`，构建态公式格保活、格数不符即拒绝输出）。禁止会话内临时手写重建脚本 —— 临时脚本会被清理，下次小改从零重写（PERF-6 / BUILD-23：单点小改曾拖到 12 分钟）。
+- 定向小改优先走固化命令：关预聚合 `e10-cli report preagg disable --apply`；改父格/单元格键 `e10-cli report fix parent --set-parent ... --set-json ...`；只有结构级改动才整包重建。
+
+## 2. 坐标与父格（x=行, y=列, 0-based）
+
+效果图标准结构（行维度 A 列，月份自 B 列横向扩展，全年累计 3 列固定）：
+
+```
+x=0  A1 需求类型Const   B1 日期Field(Horizontal/Group/yearmonth)   E1 "全年累计"Const(colCount 3)
+x=1  B2/C2/D2 预算|合同|节约率 Const(上父格→B1)    E2/F2/G2 全年表头Const
+x=2  A3 行维度Field(Vertical/Group)  B3/C3 指标Field(sum, 左父格→A3, 上父格→B1)
+     D3 节约率公式(左父格→A3, 上父格→B1)   E3 SUM(B3)  F3 SUM(C3)  G3 比率公式(左父格→A3)
+x=3  A4 "合计"Const   B4/C4 SUM公式(上父格→B1, 左父格无)   E4/F4/G4 全年总计(无父格)
+```
+
+关键规则（report-knowledge-base §4.3 + LAYOUT-4）：
+- 列维度：`expandType:'Horizontal', displayType:'Group', groupType:'yearmonth'`，父格无，`isActiveParent:true`
+- 行维度：`expandType:'Vertical', displayType:'Group'`，左父格 default
+- 交叉指标格：`displayType:'Count', countType:'sum'`，**左父格 custom→行维度，上父格 custom→列维度**
+- 月份下指标表头（Const）：上父格 custom→列维度，不扩展 → 随月份横向复制
+- 合计行公式：上父格 custom→列维度、左父格无 → 随月份扩展，每份 SUM 各自月份列
+- 交叉后固定列：左父格 custom→行维度；公式 `SUM(B3)` 引用扩展格 = 对全部横向实例求和
+
+## 3. 公式格存活条件（血案新证）
+
+fix table-name 的重建路径丢 Formula 格（13→11），但 **build spec 与本指南的直构路径 Formula 全存活**。
+差异：以构建态完整结构写入（typeName:'FormulaCellType' + editorType + subordination 等全键，
+`formula` 键同步挂在 cell 上），designKey 传空串。改公式相关内容一律走 spec/直构重建，禁止 fix 定点。
+
+## 4. 样式与格式
+
+- formatter 键白名单见 build_from_spec FORMATS：value/percent/huobi… `style.formatter` + `cellType.formatterType:[key]` + `tag.formatterType:[key]` 三处一致
+- 条件色：`cellType.conditionRule.highlightDatas[]`（relation: highlight:greater/less，foreColor，bold）
+- 表头深蓝白字：backColor #2E5E9E / foreColor #FFF / bold / hAlign 1；合计行 #DCE6F1 bold
+- 冻结：`sheet.frozenRowCount/frozenColCount` + `sheet.tag.fixedCell:{x:数据首行,y:数据首列}`；首格 cell.tag.fixed=true
+- 跨度：合并格写 `cell.rowCount/colCount` + `sheet.spans[]`（rowCount=行跨度, colCount=列跨度）
+- sheet 禁写 gridline 族键（→500）
+
+## 4.1 表头合并（用户口径 · 2026-09-15 验证落库）
+
+效果图里表头必须成块合并，**合并写 `cell.rowCount/colCount`**，回读键名为 **`xCount`（行跨度）/`yCount`（列跨度）**：
+
+| 位置 | 合并 | 写法 | 回读 |
+|---|---|---|---|
+| 左上角维度列头（覆盖表头两行） | A1:A2 纵向 | `constCell(..., { rowCount: 2 })` + span `{rowCount:2,colCount:1}` | xCount=2 |
+| 月份列维度（下挂 3 个指标） | B1:D1 每实例跨 3 列 | 列维度格 `colCount: 3` + span `{rowCount:1,colCount:3}` | yCount=3 |
+| 右侧固定块表头（全年累计） | E1:G1 | 同上一行 | yCount=3 |
+
+- **只写一个块宽**（3 列），禁止照抄 Excel 展开后的总列数（LAYOUT-3）
+- 列维度格合并 + `expandType: Horizontal` 可共存：每个月份实例都按 3 列合并
+- 表头第 2 行的子表头（预算/合同/节约率）不合并，只设上父格→列维度
+
+## 4.2 合计/总计整行公式 —— 左父格必须自定义（用户口径 · ★★强制）
+
+整行计算（合计行、总计行、小计行）的公式格 **禁止用默认左父格**：
+
+- **有参考字段**（挂在某分组下的小计）→ 左父格自定义指向该分组格
+- **整体合计/总计（无参考字段）** → 左父格**统一自定义为最前面的自定义文本格**（如合计行首格「合计」A4）
+- 合计行若同时要随列维度横向扩展 → 保留 `topParent`→列维度；两者并存：
+  `left: [3,0]`（指向 A4「合计」）+ `top: [0,1]`（指向列维度）
+
+## 4.3 横向日期扩展交叉区：双父格显式配置 + OFFSET 派生公式（全局规则 A0.21 · ★★强制 · 2026-10-29 基准样例）
+
+> 触发条件 = 日期/年月维度**横向扩展**（`expandType:'Horizontal'` + `groupType:'yearmonth'`）+ 行维度纵向扩展
+> 形成交叉扩展区 + 区域内含派生指标列（当月结存/当月期初/累计结存等）。**所有报表生成任务统一生效。**
+
+**金标准**：物资收发存报表 `1331358433604124672`（设计器人工调优后落库配置，getReportDevInfo 验证）。
+布局：A=物资名称（纵向扩展根）、B1=单据日期（横向扩展根，`yCount:4` —— 每个月份横向展开为一组 4 列：
+入库/出库/当月结存/累计结存）。
+
+### 4.3.1 交叉区数据格：双父格必须「自定义」显式配置（禁默认 -1,-1）
+
+交叉扩展区（物资名称纵向 × 年月横向）内的**每一个**数据格——Field 指标格与 Formula 派生格 alike——统一：
+
+| 配置 | 取值 | 含义 |
+|---|---|---|
+| `leftX/leftY` | **行维度扩展根坐标**（如 `2,0` = A3 物资名称） | 左父格：数据实例随物资纵向归属 |
+| `topX/topY` | **日期横向扩展格坐标**（如 `0,1` = B1 单据日期） | 上父格：数据实例随月份横向归属 |
+| `expandType` | `Vertical`（数据格自身随行维度扩展） | 纵向扩展 |
+| `subordination` | 入库 Field 格保留跨数据集关联键 `["台账.物资id","明细.物资id"]`；Formula 格 `["",""]` | 绑定链不破坏 |
+
+父格留默认（-1,-1）→ 扩展后数据错位、串月串行（注意点 **BUILD-99**）。
+
+### 4.3.2 月组表头：公共上父格，左父格不设置（★★ 用户口径 · 2026-10-29 更正，推翻串链）
+
+横向扩展日期格的**子表头格**（月组内指标表头 Const 行）统一：
+
+- **上父格 = 日期横向扩展格**（公共，如 `top:0,1`）——每个表头实例随月份归属；
+- **左父格不设置**（`left:-1,-1`，设计器面板显示「无」）——**禁止 left 串链前格**（旧串链口径已废弃，用户验证以公共上父格为准）。
+
+（2026-10-29 上午口径「首格 top 挂日期格、后续格 left 串链」作废——用户在设计器确认定案：表头格只认公共上父格，left 留空。）
+
+### 4.3.3 派生列公式：OFFSET 外层必须包 SUM + 禁静态混合引用（★★ 核心）
+
+横向扩展后**列位随月份平移**，静态列字母引用（含 `SUM($B3:B3)` 混合引用）不跟随 ⇒ 累计值只算首月或错乱。
+**必须用 OFFSET（基准单元格，向下偏移行数，向右偏移列数，[高度]，[宽度]）按相对位置引用扩展出来的兄弟格**，
+且 **OFFSET 公式外层必须包一层 SUM**（`=SUM(OFFSET(Q3,0,-16),0)` 形态）：
+
+- **为什么包 SUM**：向左偏移跨月组时路径上存在**文本类型单元格**（如角格/物资名称列），裸 OFFSET/IFERROR 包裹会把文本传播进运算导致计算异常；
+  `SUM(...,0)` 把路径上的文本按 0 兜底，数值稳定（2026-10-29 用户验证定案）。
+- 组间偏移量 = **月组列数 yCount**（示例表 16 列即 `-16`），随 yCount 推导、禁止按月份个数硬编码。
+
+| 派生列 | 公式（月组列数 = yCount） | 说明 |
+|---|---|---|
+| 当月结存（月组内直引） | `IFERROR(B3-C3,"")` | 月组内偏移固定（B=入库/C=出库），可直引 |
+| **累计结存（滚动）** | `SUM(OFFSET(E3,0,-1),OFFSET(E3,0,-4))` | 本月当月结存（左偏 1 列）+ 上月累计结存（左偏 yCount 列） |
+| **跨月组取数（期初/上月值等）** | `SUM(OFFSET(Q3,0,-yCount),0)` | ★ 单 OFFSET 也必须 SUM 包裹 + `,0` 兜底 |
+| 期末/其他跨组派生 | 同理按 `±yCount` 推导组间偏移 | **禁止硬编码月份个数** |
+
+构建期自动校验：`rebuild_from_fields.buildWorkbookFromFields` 在 workbook 含横向扩展格时，
+对 Formula 格的静态区间引用（`SUM($Xn:Xn)` 类带冒号区间）**exit 3 拒绝落库**（`assertOffsetCumulativeFormulas`，
+`opts.enforceOffsetCumulative=false` 可关）；`verify_self_check` 在线校验同步接入（error 级）。
+
+### 4.3.4 角格合并展示（美观规范 · 2026-10-29 用户口径）
+
+交叉扩展报表**左上角表头单元格**（如「物资名称/月份」「分行/品名 \ 单据年月」）**纵向合并覆盖表头两行**：
+
+- 角格 `xCount: 2`（行跨度 2，回读 rowCount=2）+ span `{row:0, col:0, rowCount:2, colCount:1}`；
+- 合并文案用 `\` 分隔行列维度名（如 `物资名称/月份`）；
+- 与 §4.1 一致：只写**一个块宽**的跨度，禁止照抄展开后的总列数。
+
+### 4.3.4 交叉区左父格筛选：每个跨源 Field 数据格各自配置（2026-10-29 用户实证 · ★★强制）
+
+A0.21 双父格布局下，交叉区**每个** Field 数据格的 `leftX/leftY` 都直指**行维度扩展根**（如 A3 物资名称，异源）
+—— 这与 A0.7「连续同源区域只配入口格」的**前提不同**（A0.7 要求后续格以入口格为父格，此处不是）。
+故按左父格筛选一般规则（`cross-dataset-filter-guide.md §2.1`：当前格数据集 ≠ 左父格数据集 ⇒ 必配）：
+
+- 交叉区内**每一个**绑定异源父格的 Field 数据格（入库、出库、…），**各自**配置
+  `subordination`（[父格关联键, 本格数据集关联键]）+ `leftFilterField`（Equals，`id` = `currentField`）；
+- 漏配症状：设计器右面板该格「左父格筛选 = 请选择」空白（用户截图实证 2026-10-29 物资收发存报表 (2,2)）；
+- Formula 派生格不绑字段，`subordination:["",""]`、无筛选，不受此条约束。
+
+### 4.3.5 日期维度父格默认升序（2026-10-29 用户规则 A0.22 · ★★强制）
+
+凡按日期/年月维度统计的报表，日期作为父格（列维度横向格或行维度格）时，**默认**配
+`orderType: 'asc'`（升序A-Z）——保证月份从早到晚展开；用户点名降序时才用 `'desc'`，其余维度格维持 `'no'`。
+
+## 5. 验证
+
+1. 保存后 `getReportDevInfo` 回读：cellTypes 计数、expandType=Horizontal 的格、formula 列表
+2. **合并与父格要单独回读核对**：`xCount/yCount`（跨度）、`leftX/leftY`、`topX/topY`
+3. `e10-cli report verify self <reportId> --app-id <appId>` 0 错 0 警
+4. ⚠️ **渲染接口口径（2026-09-15 验证）**：本环境 `/api/edc/report/view/analysis` 取回的 workbook 只含
+   配置态网格（cell = `{value, style}`，网格尺寸 = 设计网格），**纯列表对照报表同样取不到展开数据**
+   → **不能**用渲染返回来判定「是否展开/是否有数据」，最终形态以设计器确认为准。
+5. 交设计器地址即停；「按年分签」(dynamicField) 尚无 API 写法，留设计器操作
+
+## 6. 数据集 id 隔离（跨报表复用蓝图 · ★★强制 · 2026-10-10）
+
+> **铁律**：**当前报表 `addDataset` 返回的 datasetId 就是唯一合法 id。**
+> 复用另一张报表的蓝图/结构时，**模板报表的 id 一律不得落进本报表**。
+
+### 6.1 症状 → 根因
+
+复用蓝图后，设计器里出现：
+
+| 症状 | 根因（都在同一个病灶上） |
+|------|--------------------------|
+| 右侧「字段」下拉**空白**（选不出字段） | 格的 `fieldKey` 首段仍是**模板报表**的数据集 id（三段式 `datasetId.nameIndex.field`）→ 设计器按它解析数据集失败 |
+| 左父格**筛选不回显** | `leftFilterField` 里 `currentField` / `parentField` 的**前缀**仍是模板报表的 id |
+| 数据串源 / 整列为空 | 同上，跨源筛选链指向了不存在的数据集 |
+
+血案（2026-10-10 · chl测试1010 复用 chl测试002 蓝图）：13 格里 **4 个 Field 格全中**。
+
+### 6.2 三处必须检查的键
+
+| 键 | 形态 | 说明 |
+|----|------|------|
+| `dataSetId` | 纯雪花号 | 该格所属数据集 |
+| `fieldKey` | `datasetId.nameIndex.fieldName` | **首段**必须 == 本格 `dataSetId`（自查判据） |
+| `leftFilterField` / `topFilterField` / `customFilterField` / `dataFilterField` | JSON 数组字符串 | 每项的 `currentField` / `parentField` **首段**是数据集 id |
+
+### 6.3 两个经典错法（勿再犯）
+
+1. **重映射时拿「`id.` 带点整体」查映射表** —— 用 `^(\d+)\.` 取出 id 却把 `"123…."` 整段拿去 `map[key]` → 永远查不到 → **替换静默失效**（没有任何报错）。
+   正解：剥出纯 id 再查，或直接用**数字边界正则** `(?<!\d)旧id(?!\d)` 全串替换。
+2. **`fieldKey` 只在「缺失」时才生成** —— 蓝图自带的旧 `fieldKey` 会被**原样复制**。正解：**一律**由本格 `dataSetId` 重算。
+
+### 6.4 正确做法（统一通道）
+
+```js
+const { buildWorkbookFromFields, remapDatasetIds } = require('./rebuild_from_fields.js');
+
+// ① 先重映射（旧 datasetId → 本报表 addDataset 返回的新 id）
+const mapped = remapDatasetIds(templateDevData, { '旧id1': '新id1', '旧id2': '新id2' });
+// ② 再构建：fieldKey 自动由本格 dataSetId 重算；allNeedFields 自动推导；
+//    并跑 assertNoStaleDatasetIds 硬门禁（命中白名单外的 id 直接 throw，拒绝落库）
+const { workbook, stats } = buildWorkbookFromFields(mapped.data, {
+  allowedDatasetIds: ['新id1', '新id2'],   // 本报表真实数据集 id
+});
+```
+
+- **落库前硬门禁**：`assertNoStaleDatasetIds(workbook, allowedIds)` —— 扫出 workbook 内**所有** dataset-id 引用，
+  凡不在白名单即 **throw**（默认），并列出「哪一行哪一列、哪个键、哪个外来 id」。
+- **`allNeedFields`**：曾在重建白名单 `FIELD_KEYS` 里缺失 → 恒被丢弃；现已补入，且 `deriveAllNeedFields()`
+  可按「本格字段 ∪ 该数据集被任何格筛选引用的关联键字段」自动推导（实证对齐 002：学院表 `sort,title` / 专业表 `dwh,zyh,zymc`）。
+
+### 6.5 蓝图重建入口
+
+`e10-cli report rebuild from-blueprint --blueprint <file.json> [--apply] [--allow-ids <id,id>]`
+
+- `dataset`（key=`default`）或 `datasets[]`（各配 `key`）；多数据集时格上写 `datasetKey` 选择。
+- `dataSetId` / `fieldKey` / 四个筛选键 / `tableName` / `allNeedFields` **绝不从 `styleSource` 模板格继承**。
+- 落库前自动跑门禁；dry-run 就会打印「数据集 id 门禁：引用 N 处，全部 ∈ 白名单 ✅」。
+
+### 6.6 存量体检（只读）+ 存量修复
+
+```bash
+# 先看（只读）：权威白名单 = 该报表的 dataset/list
+e10-cli report check-ids --report-id <rid> --app-id <appId> [--json]
+# 别名：e10-cli report dataset id-check ...
+
+# 后修（默认 dry-run）：
+e10-cli report fix dataset-id --report-id <rid> --app-id <appId> [--apply]
+e10-cli report fix dataset-id --app-id <appId> [--apply]          # 应用级批量
+```
+
+`check-ids` 输出「外来 id 清单」+「Field 格 `fieldKey` 首段 ≠ `dataSetId`」，**exit 3** = 有外来 id。
+定位用 `--own-ids <id,id>`（替换白名单）/ `--dev-file <json>`（离线跑）。
+
+**`fix dataset-id` 的机械修复原理（关键洞察）**：
+三段式 `fieldKey = datasetId.sourceId.field`，其中 **`sourceId` 跨报表不变**（同一张数据加工 SQL 视图 / 表单
+在各报表里的 sourceId 相同，datasetId 不同）；而每格还带 top-level `nameIndex`(= sourceId)。于是：
+
+```
+外来 datasetId  --(该引用自身的 sourceId，即三段式第 2 段)-->  本报表 dataset/list 里同 sourceId 的 id
+```
+
+**确定性反查，无需人工提供映射表**。⚠️ 筛选项必须按**各自 token 的第 2 段**解析 ——
+`leftFilterField` 里的 `parentField` 指向**别的数据集**（如专业名称格的 parentField 指学院表），
+若用「本格 nameIndex」会**错挂到本格数据集**上（本命令内置映射冲突检测，冲突即 exit 3 不落库）。
+
+细则：`pitfalls BUILD-42`；SKILL **A0.12**。
+
+---
+
+## 七、交叉报表父格两条铁律（场景 D · 2026-10-29 用户口径固化 · 2026-10-30 重建自 e10-cli report scene SCENES.D）
+
+> 检测/修复命令：`e10-cli report scene check|apply --report-id <rid> --app-id <appId> --scene D [--keep-left] [--apply]`（幂等；识别不依赖业务关键词，见 `expandType=Horizontal` 即交叉结构）
+
+### 7.1 横向扩展字段：左父格保持默认
+
+- 交叉表头行里的**横向扩展锚**（如「签订年份」）：**无特殊场景（左侧不存在数据表字段）时不要设置左父格**，保持 `left=(-1,-1)`。
+
+### 7.2 交叉区后面的字段/公式格：上父格绑同列标题 Const
+
+- **交叉区后面的字段 / 公式格**（如同列的「合计金额 / 合计数量」）：上父格必须**自定义指向**该列的**标题自定义文本 Const**（交叉表头行里同列的那个非扩展 Const）。
+- 交叉格本身（横向锚正下方）上父格**维持指向横向锚**不变。
+
+### 7.3 范围边界
+
+- 锚列之前的维度列不管；交叉格 top 维持指横向锚；标题锚只取 y > min(锚列 y)。
+- 与 §4.3（A0.21 横向日期扩展交叉区）的关系：§4.3 管**交叉扩展区内部**的数据格双父格与 OFFSET 公式；本节管**交叉区之后**的静态汇总列上父格。两者共用同一 `expandType=Horizontal` 识别入口（scene check --scene D）。