汇总大表“数据驱动自动填表”改造方案 v1（2026-09-07）

前置拍板：见 docs/确认回执汇总与剩余疑问_汇总大表数据驱动改造_2026-09-07.md（A1–E3、Q1–Q3 已全部确认）。本方案据此编写。

一、目标

让《道路运输量汇总表》从“复制母版+备份还原”变为：**用户点“生成” → 程序读导入库数据 → 按确认口径计算 → 填入母版版式 → 输出当月/累计/同比/排名/占比全部正确的整本**。
验收门槛（E1/E2）：

回归：生成 2026-07 == 已修正母版（被填区域逐格 diff=0）；
实弹：生成 2026-08，逐市州加总=全省、与源月报逐项对齐、同比区间合理。

二、现状与差距

现状：exportSummaryWorkbook = 复制母版 → restoreSummaryMonthlyBlocks 用备份还原 → 年份动态化 → 输出。月度块全部来自母版静态内容，**不读库、不计算**（A4 决定改掉）。
差距：需要新增“读库计算层”并把结果写到母版对应格；备份还原机制保留到回归通过后删除（A3）。
有利条件：表结构/期间已核实（见第五节）；现有 export 小表生成器已实现大部分取数与版式（exportCityBusDetail / exportCityTaxiDetail / exportCityRailFerryDetail / exportCityPassengerSummary / exportPassengerMidDetail / exportFreightRank / exportTurnoverRank / exportWycSplit / exportPassengerCityDetail 等），可抽取复用（D5 口径一致）。

三、总体架构

数据源（导入表，report_period=YYYY-MM）
  ├─ city_bus_monthly（U203：公交+轨道+轮渡，含城市内/城际城乡）
  ├─ city_taxi_monthly（巡游出租 17 市州）
  ├─ wyc_order_monthly / wyc_total_monthly（网约车订单+全省pin）
  ├─ freight_turnover_import（货运量周转量月报：含去年同月列）
  ├─ scale_split_transport（规上规下拆分月报）
  ├─ h2031_enterprise_monthly（公路旅客企业 H203-1）
  └─ passenger_individual_monthly（个体客运）
        ↓ 聚合/计算服务（抽取自现有 export 逻辑，供大表与小表共用）
  [PaxCalc] 公交/出租/网约/轨道/轮渡 各口径(总/城市内/城际城乡) × 市州 × 月
  [FreightCalc] 规上/规下/合计 货运量与周转量 × 市州 × 月
  [MidCalc] 中口径链路：明细→客运量页→排名/分析（B3/B6/C5）
        ↓ SummaryFiller（按页签/行列映射写回母版版式）
  道路运输量汇总表_YYYY-MM.xlsx

抽取的 XxxCalc 计算服务返回“指标×市州×期间×当月/累计”矩阵；独立小表与汇总大表**共用同一套矩阵**（消除两套口径不一致，回应“同事表与系统表对不上”）。

四、页签映射清单（实现基准；7 月数值回算对账后再定稿细节）

通用列位（台账类页）：2026 当月值 m → 列 2m+1、当月同比 → 2m+2、2026 累计 Q/R；2025 参照组从 2025-01 起（整年 12 月值与同比 + 累计）。**城市客运页参照组为压缩结构（同比+1-X月累计），单独定义。**

页签	数据块/行	来源（DB 聚合/计算）	关键口径（拍板编号）
`货运`	R7 规上 / R9 规下 / R5 合计；R8/R10/R6 周转；城市块 R11-16；2026 当月列 + 累计	scale_split_transport（above_scale_freight/turnover、below_scale_、total_）；freight_turnover_import（合计=freight_mXX/turnover_mXX，去年=last_*_mXX）	B1：合计=两表一致；规下=合计−规上；2025 及以前保留母版
`公交`	每市州 4 行：客运量/周转量/城市内客运/城市内周转	city_bus_monthly 按 region_code 汇总公共汽电车字段	城市内=passenger_city/turnover_city
`轨道、轮渡`	轨道：武汉/黄石客运+周转；轮渡：武汉	city_bus_monthly 按 region 汇总 rail_/ferry_	B4：轨道轮渡在 U203 同一表
`出租`	巡游出租 17 市州客运/周转/城市内	city_taxi_monthly 按 region 汇总	B5：出租=巡游出租月报
`网约车`	全省 + 17 市州客运/周转	exportWycSplit 结果（wyc_order_monthly + wyc_total_monthly + 巡游拆分）	B5：订单+pin+巡游拆分
`班线包车`	全省/城市客运行	h2031_enterprise_monthly + passenger_individual_monthly	B2：以 `docs/公路旅客/` 模板与简化说明映射（Q3）
`公路总客运`	汇总行	班线/个体聚合	B2/B6
`中口径明细/中口径客运量`	4 类组件×市州	PaxCalc 城际城乡 + 班线：班线包车、城际城乡公交、城际城乡出租、城际城乡网约	B3 公式重算；B6 城市间定义
`中口径排名/中口径分析`	当月/累计块	只取“中口径客运量”页生成（C5）	C1 全省不排名；C4 按列分母
`城市汇总`	总/公交/出租车(巡游+网约)/巡游/网约/轨道/轮渡	PaxCalc 城市内合计	C7：总计=公交+出租车+轨道+轮渡，轨道轮渡全算城市内
`城市分市州`	客运当月/累计块、周转当月/累计块（B/G/L/Q/V/X + 排名/占比/增速）	PaxCalc 城市内分市州 + RANK/占比	C1-C4
`道路运输周转量`	当月/累计块 G/L/Q + B	FreightCalc 周转、城市内客运、中口径客运周转	C6：B=G+L/2+Q/10 系数暂固定
隐藏页（2025 城市客运量/中口径计算过程/公路总客运）	保留母版版式	仅作中间参考，视需要由 Calc 回填	不与动态填表冲突

五、数据现状（已实测库）

已入库期间：city_bus/city_taxi/freight_turnover/scale_split/h2031 个体/wyc 均 2026-01 ~ 2026-07；h2031_enterprise_monthly 另有 2026-08（767 行）。
粒度：city_bus 企业级(142 行/期)；city_taxi 17 市州/期；freight_turnover_import 18 行/期（全省+17）；scale_split 36 行/期（18×月页）；h2031 企业级(~780)；个体 7 行/期；wyc 全省 1 行/期（order 含分市州订单列）。
2025 参照：母版各页城市行 2025-01~12 数值齐全（全省行为求和公式，程序勿依赖无缓存公式值，需自行按城市行求和或读母版缓存列）。

六、逐月扩列策略（D1/D2/D3 落地建议）

现状 7 月母版列结构：2026 组当月值 m→列 2m+1/2m+2，累计在 17/18，**2025 参照组从第 20 列起**；每扩一个月需把 2025+ 参照组整体右移 2 列（POI 列插入=复杂操作）。
建议（M0 一次性解决）：把当前母版的 2026 组直接扩到 12 月满版式（2025 参照组右移至全年 12 月版终位），后续每月生成**不再插入列**，只做三件事：
1. 隐藏/置灰 M+1..12 的当月值+同比列（或留空，未到月份不填）；
2. 累计列按 1..M 重算（公式/值）；
3. 填 M 当月值并算同比（分母取 2025-M 参照，Q1：母版缓存优先、库校验提示）。
- 与 D3 契合：2027 年新开一本时，2026 组整体转为“上一年参照组”（固定 12 月版式），2027 组新增到 12 月满版。
- 12 月满版母版由一次脚本生成并请业务核对版式后作为新母版（替代现 7 月母版）。7 月回归仍以“已修正 7 月母版”数值为基准，不因版式变化改变数值。

七、里程碑与验证（每步按 AGENTS 出测试报告）

里程碑	内容	验证/出口
M0	12 月满版母版 + 列版式生成器（POI 实现“参照组定版式”重建或一次性列扩展脚本）	7 月母版数值在新版式上不变（数值 diff=0，仅列位变化），业务确认版式
M1	抽取 PaxCalc/FreightCalc/MidCalc + 单测	7 月各页程序计算值 vs 已修正母版对应格 diff=0；逐项对账（如公交武汉城市内 2026-07=4198.33、轨道全省=11731.83、规上=3754.7823…）
M2	SummaryFiller v1：按映射写回台账+成品页 2026 当月/累计/同比/排名/占比	`生成 2026-07` 与已修正母版逐格 diff=0（E1）
M3	8 月实弹：导齐 8 月数据 → `生成 2026-08`	E2：逐市州加总=全省、源月报逐项对齐、缺数清单生效
M4	前端“点生成”入口/提示、删除备份还原机制（A3）、独立小表下线（D5 内部中间表保留）	回归 7/8 月不回归；小表入口隐藏，中间表仅内部

八、改动文件预估

后端新增：calc/（PaxCalc、FreightCalc、MidCalc、WyCSplitCalc）、summary/SummaryFiller、SummaryLayout（页签/行列/列版式定义）、母版列扩展脚本（或版式生成器）。
后端改造：ReportExportService.exportSummaryWorkbook 由“复制+还原”改为“复制 → Calc 取数 → Filler 写值 → 输出”；删除/冻结 restoreSummaryMonthlyBlocks（M4）。
前端：报表生成界面“汇总大表”按钮走新逻辑；M4 处理小表入口。
文档：母版（12 月满版）、映射定稿表、测试报告、工作日结。

九、不做/待外部清单

2025 定稿数据“前台导入校验”本身另立任务（Q1 只先做提示位）；本期同比一律以母版缓存为基准。
轨迹测算/审核类分析数据不进大表（E3）。
投资、能耗、年报等页签不在本期自动填表范围（保留母版现状）。
独立小表对外交付下线（M4），内部中间表保留不展示。

十、风险

台账列移动/12 月满版式改动面大（合并单元格、公式引用、打印区）→ M0 先出“版式对比产物”请业务确认再往下。
U203 的城际城乡(chengxiang)字段与中口径明细组件公式的对应需逐格对账（7 月回算），可能有口径差。
网约拆分历史口径（B5）需以 7 月已拆分结果锁定输入输出，避免升级后数值漂移。
城市客运页参照组为压缩结构，与其它台账页不同，单独实现，7 月对账覆盖。