编辑 | blame | 历史 | 原始文档

汇总大表（道路运输量汇总表）问题交接说明

交接日期：2026-09-21　交接人：郑玉洁　接手人：待定
范围：报表生成 → 汇总大表（生成_道路运输量汇总表.xlsx，19 个页签）一键生成功能及其全部遗留问题
本文只写「接手人动手前必须知道的事」，功能全貌见第 1 节列的前置文档。

0. 一句话现状

8 月汇总大表已能做到「导入基础数据 → 一键生成」，与人工母版逐格比对基本一致。但有两个高危遗留：

~~**历史同期（2025 年）列在两套口径之间没有统一** —— 「中口径排名」页与「中口径明细」页的累计同比对不上（黄冈 7.74% vs 7.64%），**这是第一优先问题**。~~ 已于 2026-09-21 按方案 A 解决，见第 4 章。
每月要人工准备一份新母版，程序不会自己扩列，9 月及以后不解决就会卡住出表。

1. 前置阅读（先看这 5 份，约 30 分钟建立概念）

文档	作用
`docs/生成汇总大表/输入输出与逻辑关系总表_2026-09-03.md`	每个页签的输入、输出、取数来源
`docs/生成汇总大表/页签逻辑关系说明.md`	页签之间的公式依赖关系
`docs/汇总大表数据驱动改造方案_2026-09-07.md`	数据驱动改造的整体设计
`docs/问题汇总/汇总表问题汇总_2026-09-17.md`	第一批（8 月空白/排名不对）的问题与根因
`docs/问题汇总/汇总表三条主线修复方案_2026-09-18.md`	「公式不重算」主线的修复方案

对外/对同事解释用：D:\桌面\报表生成原理说明_2026-09-20.md、D:\桌面\系统实现汇总说明_2026-09-20.md。

2. 生成原理速览（6 步）

入口：前端 traffic-audit-web/src/views/ReportExport.vue（报表生成页勾选「汇总大表」）→ 后端 ReportExportController → ReportExportTaskService（异步任务 + 进度 + 10 分钟内存缓存）→ ReportExportService.exportSummaryWorkbook()（ReportExportService.java:3522）。

找母版：resolveSummaryMother()（:4464）在 docs/生成汇总大表/ 下按文件名 {yyyy}年{M}月道路运输量汇总表.xlsx 精确查找，找不到直接报「未找到模板文件」。母版**不入库、不随程序分发**。
回填台账页当月值：SummaryWorkbookFiller.fillMonthlyLedger()（SummaryWorkbookFiller.java:54）回填 6 张台账页 —— 班线包车/公交/出租（fillCityRows()，写 1~当月全月）、轨道轮渡、货运、网约车（后两者**只写当月**，历史月沿用母版）。
补齐公式：ensureMonthFormulas()（:432）+ ensureMonthYoyFormulas()（:549）按月把「当月值/同比/累计」公式右移；repairCumulativeYoyFormulas()（:777）修累计同比分母。
现算成品页：refreshSummaryCumulativeSheets()（:3984）重算城市汇总 / 城市分市州 / 中口径分析 / 道路运输周转量四页。
搬值排名页：refreshSummaryRankSheets()（:3753）→ copyRankValues()（:3766）把 exportFreightRank / exportTurnoverRank / exportPassengerMidRank 三个独立生成器的结果拷进货运量排名 / 货运周转量排名 / 中口径排名。
收尾：applyTwoDecimalFormat()（全精度存储 + 显示两位小数）→ recalcWorkbookFormulas()（:3601，evaluateAll 写回缓存值）→ fullCalcOnLoad=true → 输出。

关键认知：母版本身就是公式驱动的。全省行 = Σ17 市州；城市客运 / 中口径明细 = 跨表引用（如 城市客运!C9 = =公交!C16+出租!C16+网约车!C16+'轨道、轮渡'!C9）。所以这两页**不需要单独写数**，只要公式按月补齐 + 重算即可。

3. 问题总览

编号	问题	状态	优先级
P0-1	历史同比基数「双轨制」：中口径排名 vs 中口径明细累计同比全市州不一致	已解决（2026-09-21，方案 A）	高
P0-2	母版依赖：每月要人工准备新母版，程序不会自己扩列	未解决	高

| P1-1 | 城市客运页 AJ 列（2025年1-7月累计）残留在生成表 | 已修复 09-20 | - |
| P1-2 | 中口径排名周转量口径与人工列不一致 | 已修复 09-19 | - |
| P1-3 | 中口径排名同比与城市客运列错位 | 已修复 09-18 | - |
| P1-4 | 公式写了但无缓存值，预览/二次处理看到旧值 | 已修复 09-18 | - |
| P2-1 | 导出前基数体检 + 弹窗 +《数据缺失清单》页（B4） | 待排期 | 中 |
| P2-2 | 增速排名措辞（D 组） | 待排期 | 低 |
| P2-3 | 中口径明细 4 格 #DIV/0!（2025 年 8 月基数为 0） | 待业务确认 | 低 |
| P2-4 | 缺母版提示未实测；部署包内是带 AJ 列的旧母版 | 待处理 | 低 |

4. P0-1 历史同比基数「双轨制」（本次交接重点）

状态更新（2026-09-21）：用户采用方案 A，已实施并回归通过。 排名页的 2025 累计基数改读母版《中口径明细》静态列；黄冈 1-8 月累计同比由 7.744917% 修正为 7.641733%，与明细页一致。

4.1 现象

D:\桌面\生成数据\生成_道路运输量汇总表 (3).xlsx（2026-09-20 14:42 生成）：

「中口径排名」M13 黄冈 1-8 月累计同比 = 7.744917%
「中口径明细」T55 同一格 = 7.641733%
两页当月累计值完全相同（3480.930066022），差的只是**去年同期基数**：排名页 3230.713965 vs 明细页 3233.810859，差 3.096894。

4.2 根因：两页的去年同期基数来源不同

页签	去年同期（2025）怎么来的	代码位置
中口径排名	查库现算，四个维度全部现算（含网约车拆分）	`loadMidClassMap()` `ReportExportService.java:2441`；网约车维度 :2531；同比 `midCumYoy()` :2404
中口径明细	2025 列在母版里是写死的静态数值（无公式），程序不重算	生成件「中口径明细」V/X/Z…AJ 列；`fillMonthlyLedger()` 不写 2025 列

4.3 差异定位（已逐层验证到单元格）

四个维度分别比对 2025 年 1-8 月：班线+个体、城际城乡公交、城际城乡巡游出租 全部逐位一致；只有**城际城乡网约车**一维不同。
该维只有 2025 年 3、4 月不同（其余 6 个月逐位一致）：

	母版静态值	库现算	差
2025-03 黄冈	5.203089147	3.938965484	1.264123663
2025-04 黄冈	6.585331252	4.752560757	1.832770495
合计	56.317159454	53.220265295	3.096894158

与两页基数差 3.096894 完全吻合。

用**母版自己的出租列**（与库逐格一致）+ 订单 + pin 套现算法复算：**1/2/5/6/7/8 月逐位复现（偏差 0.000000000）**，3/4 月复现不出来 → 算法没问题，是那两格另有来源。

4.4 那两格到底是什么（重要，避免接手后走弯路）

母版（含 9/8 程序尚未改动前的原始母版 docs/生成汇总大表/_bak_202608母版修改前_20260916/2026年8月道路运输量汇总表.xlsx）里，这两格**本来就是** 5.203089147 / 6.585331252 —— 不是程序算出来的，是省里提供的模板自带的。
不是 9/16 出租补录导致的：9/8 原始母版的出租列（417.01/404.51、410.7/398.38）就已经和现在库里一模一样。
反推这两格隐含的输入（前提已验证：母版 17 市州「城市内」加总 = 2504.28 = 全省 pin 城市内，分毫不差，武汉自留 → 分摊规则与现算法完全相同）：

市州	现库出租城市内	反推当时值	差
荆州	755.90	714.52	-41.38
恩施	496.19	461.54	-34.65
黄冈	404.51	378.38	-26.13
十堰	339.59	319.28	-20.31
宜昌	649.59	651.86	+2.27

（2025-04 同量级：荆州 -43.71、黄冈 -28.11、恩施 -27.20…）

结论：母版 2025 年 3、4 月的网约车拆分，是用**另一份「巡游出租城市内客运量」**（16 个市州里 15 个都比现在低）算出来的，而母版/库里同一张表的出租列却是调整后的值 —— 母版这两列自相矛盾。9/16 出租入库后，排名页一现算，矛盾才第一次显性化。

4.5 影响面

不只黄冈：除武汉（网约车城市内占比 = 100%，不参与分摊）外，**16 个市州全都有差**。

市州	同比差(百分点)	市州	同比差(百分点)
宜昌	+0.5476	荆州	-0.3187
十堰	-0.3529	鄂州	-0.2986
黄冈	-0.1032	荆门	-0.2524
恩施	-0.1342	黄石	+0.0914
孝感	-0.0662	咸宁	-0.0526
随州	-0.0349	襄阳	-0.0352
仙桃	-0.0020	潜江	-0.0174
天门	-0.0236	神农架	-0.0031

全省行两页完全一致（31528.0607 / 5.810558%），因为这是**市州之间的分摊差异**，全省加总相互抵消。

4.6 处置方案（2026-09-21：方案 A 已实施）

实施结果：exportPassengerMidRank() 在汇总导出中复用内存母版，在独立排名表导出中打开对应母版，按表头读取《中口径明细》2025 年「总客运量」「总旅客周转量」1..N 月静态值；全省基数由 17 市州求和。静态列不完整时自动回退原库内现算并写 WARN 日志。

回归证据：2026-08 汇总大表黄冈客运量累计同比排名/明细均为 7.641733%；17 市州 × 客运量/周转量的累计值与累计同比共 68 个数值对全部一致，最大绝对差 2.91e-11；当月同比 34 个数值对最大差 5.48e-15。详见《功能测试报告_中口径排名同比基数方案A_2026-09-21.md》。

方案 A（推荐，改动小）：让 exportPassengerMidRank() 取「去年同期累计」时，改用母版那份 2025 静态列（与中口径明细同源）。
理由：对外发布的同比，基数本该用去年定稿值；只动排名页 midCumYoy/midCumClass 的取数来源，2026 当月值不受影响。
要点：把母版 2025 列读成内存映射（按「市州+指标+月」）供排名页取用；或直接让排名页同比格改成引用中口径明细页的公式。
方案 B：把中口径明细 2025 列也改成库内现算，两页都用库。
代价：会改动**所有已定稿的 2025 基数**，必须省局确认。
附带建议：加一条导出校验 —— 两页同城同月基数不一致就写进 problems（B4 体检已有框架，见 P2-1）。

4.7 回归验证方法（改完必须跑）

生成 2026-08 汇总表；
对 17 市州 × 客运量/周转量，逐格比对「中口径排名」与「中口径明细」的累计同比，要求**全部一致**；
反向校验全省行仍等于 Σ17 市州、且全省同比两页一致；
顺带确认 2026 年 1-8 月各月当月同比两页仍一致（当前是一致的，别改坏）。

5. P0-2 母版依赖与「每月换母版」

5.1 现状机制

母版目录 docs/生成汇总大表/，合法文件名只有 {yyyy}年{M}月道路运输量汇总表.xlsx 一种（resolveSummaryMother() :4464）。
程序**只按文件名精确匹配**，找不到即报「未找到模板文件」，**不会自己建模板**。
另有 _备份_ 前缀的历史同期母版还原逻辑（resolveSummaryDonor）和一批 _bak_ 备份文件，**别乱删**。

5.2 痛点

要出 9 月表，就必须人工先做一份《2026年9月道路运输量汇总表.xlsx》放进母版目录；用户明确表示「这样很麻烦」。
每加一个月要动的地方（经核实只有 3 处）：

新月份列的同比公式（=Q{row}/AJ{row}-1 这类，右移 2 列）；
累计列的枚举要补当月（如 SUM(V,X,Z,AB,AD,AF,AH,AJ) → 再补 AL）；
插列右侧的 2025/2024/2023 三块历史区及其几千条公式引用需要 +2 —— POI 不会像 Excel 那样自动改写引用，必须程序显式平移。

5.3 方案（待拍板）

方案 A（程序自动扩列）：预计 2-3 天。第一步只做「扩列器 + 用 7 月母版扩出 8 月、与真实 8 月母版逐格 diff」的验证报告，证明扩列器可靠后再做整链。
方案 B（本机 Excel 小工具一键扩列）：预计 1 天。用 Excel COM 插列（引用由 Excel 自动调整，省掉第 3 处平移），生成新母版。
建议：先 B 应急（保证 9 月出表），再 A 做长效。

5.4 验证方法

用 7 月母版扩列出 8 月结构，与 docs/生成汇总大表/2026年8月道路运输量汇总表.xlsx（已人工删过 AJ 列）逐格 diff，差异必须为 0 或全部可解释。

6. 已修复但必须知悉的历史坑（避免改回去）

城市客运页 AJ 列（09-20）：8 月母版城市客运页多了一列「2025年1-7月累计」，把 2025 年 8 月列挤到 AK，导致 8 月同比变成「8月 ÷ 1-7月累计」、累计同比漏计。已用 Excel COM 整列删除 AJ 并还原 36 处被 #REF! 的公式；备份 _bak_202608母版删除AJ列前_20260920.xlsx。**注意：用户当时删的是 7 月母版，而 8 月导出用的是 8 月母版 —— 母版有两本，改之前先确认改对哪本。**
列号 0 基/1 基（09-20）：colIndexOf() 曾返回 1 基列号，POI 要 0 基，导致公式右移 2 列变成自引用、360 格循环引用。已修，新写列号换算时务必复测。
setCellFormula 不接受带 = 前缀（09-20）：异常又被 catch (Exception ignore) 吞掉，导致累计同比分母修正静默失效。已改成 WARN 日志，**接手后新写公式时不要再吞异常**。
公式必须重算写缓存值（09-18）：POI 写文件不算公式，Excel 打开靠 fullCalcOnLoad 会算，但系统预览、二次处理、部分 WPS 看不到。现已在收尾统一 evaluateAll（recalcWorkbookFormulas() :3601）。
中口径排名周转量口径统一（09-19）：城际城乡一律用「总量 - 城市内」现算（ReportExportService.java:2504 附近注释），原「字段值优先」会在个别企业行差 ±0.01。
setValOrBlank() 遇到公式单元格直接 return（ReportExportService.java:2740）：所以中口径排名全省行的 SUM 公式不会被覆盖，别试图用写值去改它。

7. P2 其他待办

B4 导出前基数体检：导出前检查各页签基数/期次是否齐备，缺失就弹窗 + 生成《数据缺失清单》页。已有 midIssues（:2435）和 dbProblems 两个问题清单可挂。
D 组增速排名措辞：待排期。
中口径明细 4 格 #DIV/0!：2025 年 8 月基数为 0，不可比，是否改空白待业务口径确认。
缺母版提示（T08）未实测。
部署包母版是旧版（deploy/traffic-audit-deploy-20260913/backend/docs/生成汇总大表/、_deploytest/）：用户 09-20 明确「部署包先不管」，发包前需同步。
同期存在的其他线：天门物流源文件缺失、荆州/黄石「规划内/规划外」口径待确认。

8. 关键代码地图

文件	位置	职责
`reportexport/service/ReportExportService.java`	:139	`checkExportReady()` 导出就绪校验
	:285	`reportPreview()` 预览
	:2209	`exportPassengerMidDetail()` 中口径明细独立生成器
	:2441	`loadMidClassMap()` 中口径五维（0 总量 / 1 班线+个体 / 2 城际城乡公交 / 3 城际城乡巡游出租 / 4 城际城乡网约车）—— 全部查库现算
	:2531	维度 4 网约车 = `WycSplitCalc.calc()`
	:2683	`exportPassengerMidRank()` 中口径排名独立生成器
	:3522	`exportSummaryWorkbook()` 汇总大表主入口
	:3753 / :3766	`refreshSummaryRankSheets()` / `copyRankValues()` 排名页搬值
	:3984	`refreshSummaryCumulativeSheets()` 四页成品页现算
	:4464	`resolveSummaryMother()` 母版定位
	:4476	`exportWycSplit()` 网约车拆分
`reportexport/calc/SummaryWorkbookFiller.java`	:54	`fillMonthlyLedger()` 六张台账页回填
	:432 / :549 / :777	`ensureMonthFormulas()` / `ensureMonthYoyFormulas()` / `repairCumulativeYoyFormulas()` 公式按月补齐与修分母
	:586 / :589	`isMonthLedgerSheet()` / `isFilledLedgerSheet()` 页范围判断，曾因两者不一致出 bug
	:864	`monthColumnCapacity()` 母版能容纳的月份列数
`reportexport/calc/WycSplitCalc.java`	:93	`calc()` 网约车拆分（订单占比 × 全省 pin；城市内用巡游出租「城市内占比」代理，武汉自留、其余按剩余占比重分摊）
	:201 / :241	`loadMonthlyInput()` 取数：先查库 `wyc_order_monthly`，库里没有才回落到 `docs/城市客运/网约车订单及全省总量.xlsx`

9. 数据与环境

后端 Spring Boot 端口 8090；前端 Vue2 + ElementUI 端口 8080（/api 代理到 8090）。
一键启停：start-dev.ps1（项目根目录），**必须在沙箱外运行**。
数据库：MySQL 8.0 127.0.0.1:3308/traffic_audit（root/123456）；客户端 D:\mysql\mysql-5.7.41-winx64\bin\mysql.exe。
汇总大表用到的表：

表	用途
`h2031_enterprise_monthly`	公路客运企业月报（班线/包车，中口径维度 1）
`passenger_individual_monthly`	个体客运（并入维度 1）
`city_bus_monthly`	城市公交（维度 2 = 总量 - 城市内）
`city_taxi_monthly`	巡游出租（维度 3 = 总量 - 城市内；也是网约车拆分的代理输入）
`wyc_order_monthly` / `wyc_total_monthly`	网约车订单占比与全省 pin（维度 4）
`h2032_enterprise_monthly`	货运量与周转量

母版目录：docs/生成汇总大表/（含 _bak_/_备份_ 历史件，**未经同意不要删**）。
单位约定：库内为原始单位，写入表格时 ÷10000 得「万人 / 万吨 / 万人公里」；**全精度写入，显示两位小数**（applyTwoDecimalFormat()）。

10. 本次排查产生的证据文件（在项目根目录，尚未清理）

文件	内容
`_chk_mid.txt`、`_chk_hg*.txt`	中口径明细/排名页黄冈数据与公式 dump
`_chk_wyc.txt` ~ `_chk_wyc7.txt`	网约车拆分逐市逐月复算与母版比对
`_chk_taxidiff.txt`	出租页 vs 库出租逐格比对
`_chk_lineage.txt`、`_chk_lineage2.txt`	母版历史版本血缘（7 份母版的 2025-03/04 值）
`_chk_backsolve.txt`	由母版网约车反推当时的出租输入
`_chk_rule.txt`	候选分摊公式拟合结果（排除法）
`_chk_orig.txt`	9/8 原始母版关键格
`_chk_all_pref.txt`	17 市州两页同比差异清单
`_chk_code*.txt`、`_chk_wyccalc.txt`、`_chk_wycdb.txt`、`_chk_filler.txt`、`_chk_freight.txt`	相关代码段摘录

说明（2026-09-27）：上表中的 _chk_* 证据件为当时的临时文本 dump，已随历史临时文件一并清理（本地不再保留）；如需复现，按本章方法重跑（数据源与步骤见上）。

11. 待用户/业务确认清单（接手人先别自己拍）

~~P0-1 走方案 A 还是 B？（建议 A）~~ 用户已选择方案 A，2026-09-21 已实施并回归通过。
P0-2 走方案 A（程序自动扩列）还是 B（Excel 小工具）？9 月是否先用 B 应急？
中口径明细 4 格 #DIV/0! 是否改空白？
B4 基数体检的触发时机与弹窗文案。

12. 建议的接手顺序

跑通环境 + 生成一次 2026-08 汇总大表，确认能复现本文所有现象（半天）。
~~处理 P0-1 方案 A（1 天，含回归）。~~ 已于 2026-09-21 完成。
处理 P0-2 方案 B 出 9 月母版（1 天），随后排 A。
补 B4 基数体检（1-2 天）。