fix(汇总大表): 扩列器整本重算写缓存（修公式无缓存导致的取数差异）待验收

zhizhijie

5 天以前 6f3dd209dee910a9ea899c35600ceaf84e528218

 HANDOFF.md

@@ -4,6 +4,135 @@
> **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。
> **协作约定（2026-08-31）**：说「提交」= 本地 commit + 推送到远端 git（origin main，Gitblit），不再只做本地 commit。

### 10-12（3）：修「9 月产物丢 8 月列 / 累计漏月」——扩列改为**以当期产物为底**【待验收】

- **现象（用户报告）**：生成的 9 月汇总大表里 **8 月列全空**，累计漏掉 8 月（规上货运量累计显示 31309.58，正确应为 1-7月 27734.46 + 8月 3665.36 + 9月 3575.12 = **34974.95**）。
- **根因（逐层证实）**：① 母版**不带"当期列"的值与公式**——`fillFreightSheet` 明确"只回填目标期当月，1..目标月-1 以母版为准"，全省行公式由生成时按当期补；② 8 月的数据只落在**8 月产物**里、未回写母版；③ 9 月母版是**从 8 月母版扩列**来的 → 继承"8 月列空" → 生成时又只补 9 月 → 8 月永久空缺、累计 `=C+E+…+Q(空)+S` 漏月。
- **修复**：扩列器**优先以「当期产物」为底**（产物含当期列的值与公式）——取该期**最新产物**（导出落盘缓存 `_cache/summaryWorkbook_<period>_month__v*.xlsx`，多根目录定位），取不到才回退母版并打 WARN；另修体检规则误报（②全口径缺失时不再报"规下为负"，改报"缺②全口径 → 规下无法计算"，否则 9 月只有规上时会对每个市州刷屏）。
- **关键实现点**：产物缓存定位必须用 3 候选根目录（`summaryTemplateDir` → `user.dir/…` → `user.dir/../…`）——首版用单相对路径，因 `spring-boot:run` 的工作目录是**模块目录**而找不到，静默回退到了母版（表现为"改了但还是空"）。
- **验证**：`docs/生成汇总大表/输出/_扩列_2026年9月_待确认_v3.xlsx`（日志确认 base=**产物** `summaryWorkbook_2026-08_month__v37…xlsx`）：
  - 8 月列有值：货运 全口径 **16888.7615** / 规上 **3665.3638** / 规下 **13223.3977**；公交全省 **12315.37**；
  - 累计公式 **含 8 月与 9 月**：`=C5+E5+…+Q5+S5`；累计同比分母 `SUM(X5,Z5,…,AL5,AN5)`（2025-01~09）；
  - 9 月列留空（无 9 月源数据）；7 个标题页标题 **1-9月 / 9月** 正确。
- **口径结论（写进设计）**：**新母版一律从"当期产物"派生**（产物带当期数据与公式），不再从旧母版派生——否则每月都会丢"当期列"，累计逐月漏数。
- **遗留**：① 待用户确认是否把 v3 落盘为正式 9 月母版（会先备份手工版）；② 扩列产物中被重写的公式暂无缓存值（只写公式 + `fullCalcOnLoad`，Excel/WPS 打开自动算）——建议补"整本重算写缓存"；③ `中口径明细` 表头行识别返回 `[2,4]`，需核查。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_扩列以当期产物为底_2026-10-12.md`。状态：**【待验收】**。
### 10-12（4）：扩列公式克隆两处修正 + 9 月母版落盘 + 端到端验证通过【待验收】

- **修前问题（同一批次的三个）**：① 克隆"当月值列"时公式未相对右移（新列写成 `=Q7+Q9`，应 `=S7+S9`）→ 全省行取到上月数；② 克隆"当月同比列"时分子指向旧月份（`=Q5/AN5-1`，应 `=S5/AN5-1`）→ 算的是"上月值÷去年同月"；③ POI `setCellFormula` **不接受前导 `=`** → 接口 500（`FormulaParseException`，§6.3 历史坑）。
- **修法**：新增 `shiftRefsAll`（克隆时对"本页/已扩列页"引用**无条件 +2**，相对复制）与 `cloneYoyCell`（不克隆，直接写 `本月值/表中定位的去年同月-1`，即 C3 口径）；公式串去掉前导 `=`。
- **9 月母版落盘（用户已确认）**：手工版备份为 `_bak_2026年9月母版_手工版_20261012.xlsx`；新母版 = "8 月产物 → 扩列"，1,083,567 B；输出目录命名理顺（最新件 `_扩列_2026年9月_待确认.xlsx`，旧版加 `_bak_` 前缀）。
- **端到端验证（用新母版生成 2026-09）**：
  - 货运 8 月列有值：全口径 **16888.7615**、规上 **3665.3638**、规下 **13223.3977**；
  - 9 月列：全口径 3575.1211（②表未导，只有①规上）、规上 3575.1211；
  - **累计：全口径 133887.0138（=1-8月 130311.89 + 9月 3575.12）、规上 34974.9459（=27734.46+3665.36+3575.12）、规下 98912.0679** ✓ 与手算一致；
  - 公交：8 月 12315.37、累计 110776.34 ✓。
- **遗留**：① 扩列产物被重写的公式无缓存值（建议补"整本重算写缓存"）；② `中口径明细` 表头行识别返回 `[2,4]` 待核查；③ ②表（全口径）9 月未导入前，"全口径"行显示等于规上（公式 =规上+规下、规下为空），体检已提示，导数据后自动正常。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_扩列公式克隆修正与9月验证_2026-10-12.md`。状态：**【待验收】**。
### 10-12（5）：修「9 月公交/出租月报导不进去」——导入改按表头名定位列【待验收】

- **现象**：用户导入 9 月公交/出租月报反复失败；`import_batch` 无记录、`city_bus_monthly`/`city_taxi_monthly` 无 2026-09 行 → **解析阶段即抛错**（没进写库）。
- **根因（实测三份文件）**：9 月模板比 7 月**少列导致整体左移**——公交 68→**66** 列（少 `统一社会信用代码`、`填报单位`，第 3 列起左移 2）；出租 41→**40** 列（少 `填报单位`，左移 1）。导入器原是**按固定列号取值 + 固定列位校验** → 校验直接抛「与文件内容不符」。必需列按名都在，是列位不匹配；且取值也按固定列号，不改会整体读错列。
- **改动（按 I4 口径兼容模板差异）**：新增 `colByName(hdr, fallback, name[, occurrence])`（按表头名取列，未命中回退原固定列号）与 `requireHeaderColsByName(...)`（只校验必需列按名存在、不校验列位）；`importCityBus`/`importCityTaxi` 所有字段改为按名取值；公交重复表头「其中：城市内」（2 次）用出现序号区分（`stopCity`=1、`passengerCity`=2）。映射取自实测表头（公交 42 字段、出租 37 字段全部命中）。
- **验证**：列位差异已定位；名称映射完备（42/42、37/37）；校验放宽仍保留"真缺列"的负向拦截；编译通过、后端已重启（PID 40592，13:17:38）。
- **待办**：**请用户在页面重导这两个 9 月文件**（助手不代导）；导入后助手做只读抽查（行数/市州/与源文件逐列对齐，尤其"城市内/城际城乡"口径字段）。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_公交出租导入按表头名定位_2026-10-12.md`。状态：**【待验收】**。
### 10-12（6）：修「城市分市州当月块标题停在 7 月」——标题写入行号差一行的 bug【待验收】

- **现象**：9 月产物（8 月产物同样）里 `城市分市州` 显示"城市客运客运量分市州**7月**情况"，标题不随月份更新。
- **根因（代码行号差一行）**：母版里当月块的**标题在 `A45`、单位在 `A46`**（周转量块是 `A67`/`A68`），但程序写的是 0 基 `45`/`67` = **Excel 第 46/68 行** → ① 真标题行 `A45/A67` 从未更新（一直停在母版旧月份）；② 程序的标题**覆盖了"单位：万人次/万人次公里"行**。累计块 `0/22` 正确，其余页（城市汇总 `0/11`、中口径分析 `0/9`、道路运输周转量 `0/22`、两张排名）行号均已核对无误。
- **改动**：① 代码 `smSetTitle(sh,45,…)`→`44`、`smSetTitle(sh,67,…)`→`66`；② 母版被覆盖的 `A46/A68` 用 **XML 精准改格**恢复为"单位：万人次 / 单位：万人次公里"（复用文件内既有共享字符串索引，不整本重写）。
- **验证（生成 2026-09 实测）**：`A45/A67` = `城市客运客运量/客运周转量分市州**9月**情况` ✓；`A46/A68` = `单位：万人次 / 单位：万人次公里` ✓；累计块 `A1/A2/A23/A24` 正常 ✓。
- **遗留（待用户确认后做）**：① `城市分市州` S50:S66 与 `道路运输周转量` I27:I43 各 **17 个 `#DIV/0!`**（占比分母=全省行在无数据月被写成 0）→ 建议"生成收尾统一错误值留白 + 母版占比公式加 IFERROR 兜底"；② `中口径分析` 9 月**网约车行**值 0/同比 −1（9 月网约车数据未导，属缺数）；③ `中口径明细` D107/D108/F107/F108 为硬编码 `0` 公式（母版既有）；④ **用户提出的"格式调整"尚未给出具体位置**，待提供后同步母版。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_城市分市州当月标题行号修正_2026-10-12.md`。状态：**【待验收】**。
### 10-12（7）：用户决定——以下三项**暂不处理**（记录，勿再作为待办提出）

- **明确决定（2026-10-12）**：以下三项用户决定**不改**，后续会话不要再当成待办重复提出；若用户以后主动提起再议。
  1. `城市分市州` S50:S66 与 `道路运输周转量` I27:I43 的 34 个 `#DIV/0!`（占比公式分母=全省行在无数据月被写成 0）——不做"错误值留白/IFERROR 兜底"。
  2. `中口径分析` 9 月网约车行（值 0、同比 −1，因 9 月网约车数据未导）——不额外处理，等数据到位自然恢复。
  3. 表格格式调整同步母版——用户不再提供具体改动，母版不做格式同步。
- **本日已完成并待验收的改动（汇总）**：Step 0 表头动态定位（`6d1ac61`）、货运体检 6 条规则（`91f6583`）、扩列以当期产物为底（`fb269f6`）、扩列公式克隆修正 + 9 月母版落盘（`3b3652e`）、公交/出租导入按表头名定位（`797f03b`）、城市分市州当月标题行号修正（`64f6466`）。
### 10-12（8）：按用户要求收敛为「一个母版」+ 母版格式按用户调整版【待验收】

- **用户要求（2026-10-12）**：格式按用户手工调整过的《生成_道路运输量汇总表_2026-09 (3).xlsx》来；母版只要一个。
- **已完成**：
  1. **母版收敛为一本**：`docs/生成汇总大表/` 下只留 `2026年9月道路运输量汇总表.xlsx`；把 7 月母版、8 月母版、8月版式原型、9月试做件、**版式参照件《生成_道路运输量汇总表.xlsx》** 共 5 件移入 `docs/生成汇总大表/归档/`（`_备份_`/`_bak_` 按 A3 仍留原地作回归对照，不算母版）。
  2. **停用参照件**：`exportSummaryWorkbook` 不再调用 `applySummaryReferenceLayout`（`widthApplied=0`），**版式一律以当期母版为准**（日志不再出现"套用参照件列宽"）。
  3. **用户样式套入母版**：用 Excel COM 精确套用（109 列宽 + 3 行高 + 1348 格字号 + 32 格单元格格式），并去掉母版 `fullCalcOnLoad` 以免 Excel 打开即重算。
  4. **验证**：生成 2026-09 → **产物与母版的列宽/行高/字号完全一致（差异 0）** ✓；与上一版产物比 **结构差异 0** ✓。
- **两处残留（均不可见，已核实）**：① 列宽 226 处 **±0.01**（Excel 按 1/256 字符存宽度）✓；② 32 个**空白格/合并区覆盖格**的填充与字体色（Excel 保存对空格格式的处理差异）✓。
- **一处需用户拍板的数值变化**：本次生成件 `中口径排名` 有 **46 格**（同比/排名，如 `D3` 0.0581→**0.0402**、`E4` 第10→第**9**）与上一版不同；**新值与《中口径分析》页逐位一致**（`B3=35028.0636`、`C3=0.04015856`）——即排名页与明细/分析页口径统一（原旧值是该页在母版里的旧缓存）。**保留新值 / 回退旧值待用户确认**。
- **归档说明**：`归档/` 内 5 件历史母版/版式件仍可随时取回（未删除）；母版目录以后只放"当期一本"。
- **状态**：**【待验收】**。
### 10-12（9）：扩列器加「整本重算写缓存」+ 明确保留中口径排名新值【待验收】

- **问题定位（用户问"为什么产生这 46 格差异"）**：母版里**大量公式只有公式、没有缓存值**（POI 写公式不带缓存）。实证：母版经 Excel 保存前后 **约 2.47 万格**由"空"变"有值"（如 ` 货运!U5: 空→130311.8927`）。`中口径排名` 的同比/排名由程序**读母版缓存**计算（方案 A）→ 缓存空时算旧值 `0.0581`，缓存补齐后算 `0.0402`（**与《中口径分析》逐位一致**）。**新值才是数据完整时的正确结果**。
- **改动**：`SummaryLayoutExpander` 新增 `recalcAndCache(wb)`（`clearAllCachedResultValues()` + `evaluateAll()` 写回缓存，失败仅 WARN），在 `expand()` 与 `fixTitles()` 中调用。
- **验证**：扩列 2026-08 → 公式格 **39,961** 个，**空缓存仅 4 格**（全在 ` 货运`，POI 无法求解的外部引用，Excel 打开会算）；修复前同类母版约 2.47 万格无缓存。
- **用户决定**：`中口径排名` 那 46 格**保留新值**（与中口径分析一致，口径统一）。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_扩列整本重算写缓存_2026-10-12.md`。状态：**【待验收】**。
## 最新（2026-10-12，zyj 线）

### 10-12：扩列器补「标题按母版期次重写」+ 修正 8 月母版标题【待验收】

- **用户反馈**：9 月版式件与 8 月母版里，7 个页签的标题仍是 `1-7月 / 7月`（货运量排名、货运周转量排名、城市汇总、城市分市州、中口径排名、中口径分析、道路运输周转量）。
- **根因（两条）**：① 按已确认口径这 7 页是 C 类页——**标题由生成程序在出表时现写**（`ReportExportService :969 / :1011 / :2707 / :2891 / :4446 / :4498 / :4499 / :4604` 均按 period 写），母版里的文字不参与出表，所以扩列器原本没动它们；② **我的实现确实漏了"标题 +1"这一步**——《扩列配置·核对版》动作 7 写了"标题：页面标题月份+1（逐页核对）"，我只做了 8 个台账页的表头克隆。
- **修复**：扩列器新增 `applyTitles(...)`——按**母版期次**重写标题（累计=`1-M月`、当月=`M月`），只处理 7 个标题页、**命中标题标记才改**（避免误伤 ` 货运!A1` 这类备注），4 位年份一并按目标年重写；新增只读接口参数 `?titlesOnly=true`（只改标题不扩列）。
- **8 月母版已修正**：7 页标题 `1-7月/7月` → **`1-8月/8月`**（修正前备份 `docs/生成汇总大表/_bak_2026年8月母版_标题修正前_20261012.xlsx`）；19 页签与公式抽查无损（`中口径明细!C5`、`公交!C5` 全省行公式、` 货运!A1` 备注均正常）。
- **9 月版式重跑**：7 页标题 → **`1-9月/9月`**；产出 `docs/生成汇总大表/输出/_扩列_2026年9月_待确认_v2.xlsx`（1,037,071 B）。
- **与手工 9 月母版复比**：851 条差异 = 8 个台账页 836 条（沿用 10-10 分类：累计/分母是否扩到 9 月 548、分隔符 153、表名引号 130、浮点尾差 1）＋ **标题页 15 条**（手工件标题为滞后的 `1-8月/7月`）。
- **踩坑**：重跑时目标文件被 Excel/WPS 占用（`being used by another process`）→ 先落 `_v2` 命名；用户关闭后可用原名重写。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_汇总大表扩列器标题修正_2026-10-12.md`；日结 `docs/工作日结/工作日结_2026-10-12.md`。
- **待用户验收/确认**：① 标题口径按"**标题期次=母版期次**"（8月→1-8月/8月、9月→1-9月/9月）是否正确；② `_扩列_2026年9月_待确认_v2.xlsx` 是否改名为正式名（原名那份是旧内容、被 WPS 存过，未经同意不动）；③ 累计/累计同比"是否扩到 9 月"（产出=已扩、手工版未扩）。
- **状态**：**【待验收】**。
### 10-12（2）：货运口径「导出前基数体检」（B4）6 条规则落地【待验收】

- **背景**：规下 = ②《货运量周转量表》全口径 − ①H203-2 规上÷10000，是**倒减**——①漏报会让规下虚高、极端还会算出负数。用户 2026-10-12 同意把这组规则加进 B4。
- **实现**：新增 `reportexport/calc/FreightReadinessCheck.java`（只读）；接入 `exportSummaryWorkbook` 的缺数收集 `dbProblems`（随导出日志输出）；新增只读接口 `GET /api/report/summaryWorkbook/freightCheck?period=YYYY-MM`。
- **规则**：① 某市州规下为负；② ②有全口径、①无规上记录（疑漏报→规下=全口径）；③ ②全口径 < ①规上；④ Σ17 市州 ≠ ②"湖北省"行（容差 0.01）；⑤ **本月与上月完全相同**（疑重复导入，两侧 ≥50 万吨/万吨公里）；⑥ **同比异常**（|去年同月→本月| > 50%，两侧 ≥50）；⑥' 累计勾稽（①周转量 1..M 求和 ÷10000 vs ③拆分表 CUMULATIVE）。
- **阈值修正（实测驱动，重要）**：首版用"规下环比 > 30%" → 2026-02 命中 22 条、2026-03 命中 32 条，复核确认**全是春节季节性**（各市州 2 月 −30~−40%、3 月 +30~+60%），非数据错误 → 改为"重复导入特征 + 同比>50%"；并给判据加**绝对门槛 50 万吨/万吨公里**，避免神农架林区（20~46 万吨）这类小基数噪声长期报警。
- **实测**：2026-01~08 **全期 0 命中**（无误报）；②表 `last_freight_m08`/`last_turnover_m08` **18/18 行有值** → 同比规则确实参与计算（非空跑）。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_货运基数体检B4六条规则_2026-10-12.md`；日结同日两条。
- **待用户验收/确认**：① 阈值（绝对门槛 50、同比 50%）是否合适；② 是否现在做 B4 剩余部分——导出前弹窗 + 生成件《数据缺失清单》页（P0-3 剩余）。
- **状态**：**【待验收】**。只读功能，未改动业务数据。
### 10-12（3）：生成数据「验证方法」成文（五段链条 + 反同源盲区）

- **成文**：`docs/汇总大表生成数据验证方法_2026-10-12.md`（回答"如何验证程序生成的数据是否正确"）。
- **口径**：把问题拆成 4 问（源数据 / 算法 / 版式 / 与定稿一致），每段配一个**独立于该段的参照**；链条五段 L0 源文件→库、L1 库→口径值、L2 口径值→单元格、L3 单元格→整本、L4 跨页合成页勾稽；**通过标准 L0~L4 已写死**（任一层未覆盖，结论不得写"已验证"）。
- **对既有"四层验证法"（10-08/10-12 会话）的三处补强**：① 补 L0 源数据层与**反同源盲区**——"生成件 vs 定稿"在母版与定稿同源时查不出源数据问题（今日 2025-11 两处即例）；② **体检通过 ≠ 数据齐全**，异常清单与缺数清单分开输出（今日 2026-08 体检 0 命中，但 9 月件 8 月列仍空）；③ 必须专门做一次「库内值 vs 母版缓存」全量 diff（10-09 待办）——**出表口径不切库**与**验证必须比一次**并不矛盾。
- **佐证**：2026-08 vs 9/13 定稿（1020 条 → 11 条关注，算法层通过）；库内 2025 vs 母版 2025（公交/出租/轨道轮渡 100% 一致，3 处需业务确认，报告见 `docs/功能测试报告/功能测试报告_库内2025与母版2025逐格核对_2026-10-12.md`）。
- **状态**：文档类，无需验收。
- **B4 关联（已核）**：10-12 上午的货运基数体检 B4 已由另一会话提交（`91f6583`，报告 `docs/功能测试报告/功能测试报告_货运基数体检B4六条规则_2026-10-12.md`）；本次 2026-08 核对实际调用了它的 `GET /api/report/summaryWorkbook/freightCheck`（2026-01~08 全期 0 命中）。
### 10-12（4）：汇总大表「缺数清单」落地（只读接口 + 接入导出日志）【待验收】

- **动因**：用户要求把「缺数」显式摆到台面上——当日两个真实问题（9 月生成件 8 月列为空、9 月周转量全 0）都属"该有的数没有"，而 `freightCheck` 体检当时 **0 命中**，两者必须分开。
- **实现**：新增 `reportexport/calc/SummaryMissingDataCheck.java`（只读）；接口 `GET /api/report/summaryWorkbook/missing?period=YYYY-MM`；接入 `exportSummaryWorkbook` 的 `dbProblems`（随导出日志输出）。
- **口径**：① 逐月回填页（班线包车/公交/出租/轨道轮渡）查 1..目标月 来源是否有数、17 市州是否齐全；② 货运/网约车只回填目标月，查目标月各项来源（货运①+②+③、网约车订单+全省 pin+出租平均运距）；③ 这两页的历史月由母版承担——**母版与同期备份母版（donor）都没有数**才算缺口（否则会误报 7 月那种"骨架母版 + donor 还原"）。
- **实测**（独立 8099 实例，未打扰 8090，测完已关；`mvn -o compile` exit=0）：2026-08 **0 条**、2026-07 **0 条**、2026-09 **11 条**（班线包车/公交/轨道轮渡/出租 无源 4 条 + 货运②③ 2 条 + 网约车 3 条 + 母版 8 月列空 2 条）——命中的正是当日两个真实问题。
- **修正**：首版只比母版 → 误报 2026-07 两条；已按生成链实现补上 donor 比对，复测 0 条。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_汇总大表缺数清单_2026-10-12.md`。
- **待办**：导出前弹窗 + 生成件《数据缺失清单》页（与 B4 的 P0-3 合并）。
- **状态**：**【待验收】**（只读功能；未落盘、未改业务数据）。
## 最新（2026-10-10，zyj 线）

### 10-10：Step 1 扩列器落地 + 8→9 月版式首轮产出【待验收】

- **新增扩列器**：`traffic-audit-server/.../reportexport/layout/SummaryLayoutExpander.java`；新增只读接口 `GET /api/report/export/summaryWorkbook/expand?period=YYYY-MM`（返回字节、**不落盘**）；`ReportExportService.expandSummaryWorkbook(period)` 负责取当期母版并调用。规则依据 `docs/汇总大表母版扩列配置_核对版_2026-10-09.md`（8 个可见台账页；4 个隐藏页不扩列但同步平移其跨页引用）。
- **产出（待确认件，未落盘为母版）**：`docs/生成汇总大表/输出/_扩列_2026年9月_待确认.xlsx`（1,036,939 B，2026-10-10 09:30:07）。只做版式，9 月数据列留空。
- **与手工 9 月母版逐格比对**：**` 货运` 差异 = 0**（规则正确的最强证据）；其余 7 页共 836 条差异，**全部非数值分歧**，分为四类：
  1. **548 条**：产出把「累计/累计同比分母」扩到 9 月，手工版未扩——正是 09-29《扩列进度》认定的待修项 ③④（"累计列只算到 8 月""去年基数只到 8 月"），即**手工 9 月母版这 7 页尚未修完**；
  2. 153 条：分母新增项分隔符写法（`SUM(a+b+…,c)` vs `SUM(a+b+…+c)`，等价同值）；
  3. 130 条：表名引号写法（`轨道、轮渡!C6` vs `'轨道、轮渡'!C6`，Excel 规范化所致，同值）；
  4. 1 条：浮点尾差。
- **8 月及以前列**：仅 28 条差异且全部属第 3 类引号写法（集中在 `城市客运`），未动数值/列号。
- **过程中修掉的两个实现缺陷**（重要，避免复现）：
  1. POI 5.2.5 的合并区 API 是 `addMergedRegion(CellRangeRangeAddress)`、`removeMergedRegion(int)`（无 CellRangeAddress 重载）——按下标摘除、按对象添加；
  2. 引用正则最初只认 ASCII 表名，**漏掉母版里 5,574 处"未带引号的中文表名"引用**（如 `轨道、轮渡!C6`）→ 已把表名字符类扩到 CJK，修正后列号与手工真值一致。
  3. 写件用 **POI**（与生成链路同源），不用 openpyxl（本项目历史上有 openpyxl 写出导致 Excel 拒绝打开的案例）。
- **报告（本地、不入库）**：`docs/功能测试报告/功能测试报告_汇总大表扩列器8月到9月版式_2026-10-10.md`；日结 `docs/工作日结/工作日结_2026-10-10.md`。
- **待用户验收/确认**：① 累计列与累计同比分母**是否应扩到 9 月**（产出=已扩；按 09-29 待修清单，方向与当时认定一致）；② 确认后是否把产出落盘为正式 9 月母版（按已确认口径：人工确认后落盘）。
- **状态**：**【待验收】**（版式类改动）。未导入任何业务数据、未改动生成主链。
- **下一步**：按确认结论微调（如需）→ 复跑 8→9 → 接入主链（`resolveSummaryMother` 找不到目标月母版时自动扩列）+ 归档目录与版式参照件按 C4 收尾。
## 最新（2026-10-09，zyj 线）

### 10-09：2025 数据现状核验（结论：已在库，无需补录）+ M0 规格补第十二节
@@ -47,6 +176,8 @@
- **文档更新**：`docs/汇总大表M0版式重建器规格_2026-10-06.md` 第十四节已定项替换"未决项"；规格表与配置初稿各追加口径补充。
- **状态**：【待验收】；未改动代码、未导入数据。

- **（同日已确认，非待确认项）落盘与文件管理**：扩列产物**先落 `docs/生成汇总大表/输出/`**（`_扩列_YYYY年M月_待确认.xlsx`），**人工确认后**才重命名落盘为当期母版；目录只留**当期一本**母版，历史期移入 `docs/生成汇总大表/归档/`，`2026年8月…_版式原型.xlsx` 一并归档；版式参照件 `生成_道路运输量汇总表.xlsx` 在扩列器跑通后归档（归档前做 C4 两步：列宽/隐藏一次性固化进母版 + `applySummaryReferenceLayout` 改按表头文字匹配列）。
- **实施要点（实测细节，非决策项）**：母版 vs 参照件实测 **列宽 320 处、隐藏标记 31 处**不同（` 货运` 77+8、班线包车 109、中口径明细 32+14、中口径排名 17+9 等）；`copyColumnWidth`（`ReportExportService.java:1186`）**只复制宽度、不复制 hidden**，扩列器克隆月份列时须补 hidden。
### 10-09（5）：Step 0 落地——四张跨页合成页取数改为**按表头动态定位**月份列【待验收】

- **改动**：`ReportExportService` 中 `SM_CUR_COL0 = 2`（2026年1月=C）/ `SM_LAST_COL0 = 21`（2025年1月=V）**废弃**，改由新增的 `smMonthCols(sheet, year)` + `smYearMonthOf(cell)` 按表头定位；`smSumMonths` 改吃「月份→列号」映射。**只换取数方式，不改版式与数值口径、不做扩列**。
@@ -56,8 +187,17 @@
- **踩坑（务必记住）**：首次对比的"0 差异"是**假的**——旧后端仍占 8090，`start-dev.ps1` 因端口已监听而跳过启动，且其报出的 PID 与真实监听 PID 不一致，导致误判"已换新进程"。**判断是否换了进程，必须看 `netstat -ano` 的真实监听 PID + 日志里的启动时间/PID，不能只信启停脚本输出。**
- **其它确认**：后端日志中文为 **GBK**（`Select-String` 中文模式匹配不到，需用 PID/类名等 ASCII 锚点）；两次产物 sha256 不同但 29 个 zip 条目内容全同（差异仅在 zip 容器元数据）。
- **报告**（本地、不入库）：`docs/功能测试报告/功能测试报告_汇总大表列位置表头动态定位_2026-10-09.md`；日结 `docs/工作日结/工作日结_2026-10-09.md`。
- **一致性旁证（2026-10-09，作为 Step 0 验收材料）**：用 `docs/工具/汇总大表差异比对.py` 把**新代码产物**与**手工定稿** `D:\05_数据分类\汇总表\8月汇总定稿\2026年8月客运量、货运量定稿.xlsx`（9/13 版）逐格比对，明细 1020 条：
  - 实质数值差异 **10**：全在《 货运》`DZ` 列（2022 年累计同比，仙桃/潜江/天门/林区）——即 09-21~09-28 已确认"**软件正确**"的那 10 条；
  - 需处理(非数值文本) **1**：班线包车 `IM50`（仙桃 客运量同比），生成件为数值 `0.0077858…`，手工侧值是**反引号脏字符**；
  - 错误值(手工) **364**：程序侧留空、手工侧 `#REF!`/`#DIV/0!`，属已确认的"历史错误值留白"口径；
  - 用户手工改动 **1**：`城市汇总!G20` 措辞（已登记 `USER_EDITS`）；
  - 其余 1009 条为已按口径忽略的结构/格式类（结构/设计、无表头草稿列、排名表当月/累计块、文本型数字 354、取整尾差、单边有值、措辞等）。
  - **结论**：与手工定稿**数字一致**，无新增需处理项；比 09-29"需处理=0"多出的部分全部源于该定稿为 **9/13 版**、尚未同步 09-28 之后的手工改动（措辞/清 0/错误值留白/按软件值同步）——属定稿滞后，非程序回归。报告（本地）：`_tmp/_step0/diff_0813.md` / `.csv`。

- **状态**：**【待验收】**（取数方式属口径相关改动）。未导入任何业务数据。
- **下一步**：Step 1 扩列器本体（配置驱动，8 个可见台账页；§5.2 三条必改点；产物先落 `输出/` 待人工确认后再落盘为下期母版）。

## 最新（2026-10-06，zyj 线）

### 10-06：拉取合并 + 验收门禁分级 + 汇总大表 M0 立项