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

> **v1.1 修订（2026-09-08，用户拍板）**：本文件正文中“12 月满版列版式”建议**作废**；扩列按“每月需增月份时再扩列”执行（=D1 原口径：当月值列+同比列插入累计之前、累计滚动、2025+ 参照组右移）。执行顺序按 E1：先回归 7 月、再填 8 月。D5 落地：货运/公路旅客/城市客运三类独立小表前端全部隐藏，内部中间表保留不展示。已确认口径以《确认回执汇总…2026-09-07》文档（含六/七节补充）为唯一决策基线。


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

## 一、目标
- 让《道路运输量汇总表》从“复制母版+备份还原”变为：**用户点“生成” → 程序读导入库数据 → 按确认口径计算 → 填入母版版式 → 输出当月/累计/同比/排名/占比全部正确的整本**。
- 验收门槛（E1/E2）：
  1. 回归：`生成 2026-07 == 已修正母版`（被填区域逐格 diff=0）；
  2. 实弹：`生成 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），内部中间表保留不展示。

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

## 附录：M0 影响面实测（2026-09-08，母版 2026-07 → 08）
- 需要“逐月扩列（在累计列前插入当月值+同比 2 列，累计滚动，2025+ 参照组右移 2 列）”的页 = **10 个长表页**：` 货运`(maxCol145/合并140)、公路总客运(274/194)、班线包车(285/204)、城市客运(72/55)、公交(86/76)、出租(86/76)、网约车(86/70)、轨道轮渡(72/110)、中口径明细(87/157)、中口径客运量(68/111)；平移区公式数以千计（涉平移列引用：公交 2004 / 出租 1872 / 网约 1664 / 中口径明细 6654 / 货运 6638 / 班线 5688）。
- **不需要随月扩列**：6 个成品页（货运量排名/货运周转量排名/中口径排名/城市汇总/城市分市州/道路运输周转量，当月块与累计块为行结构，固定列位，由数据驱动填充值/公式）；中口径分析、2025年城市客运量、中口径计算过程列数不足 17 或为计算页，不动。
- **M0 实现策略（技术自定）**：采用“**月度版式重建器**”而非 POI 就地列平移——把 10 个长表页的列布局参数化为“月份组(m 月值列=2m+1/同比=2m+2/累计=2m+3/累计同比=2m+4，2025+ 参照组起点随之右移）”，生成目标月时按 m 重建列布局与月份表头/累计/同比公式，源内容(7月版母版)作为版式蓝本和 2025 参照数据基准。一次建成后 8..12 月与跨年新本复用。成品页不走扩列，直接按映射填当月/累计/排名。