docs(汇总大表): M0 月度版式重建器规格（10 页规格表、改动清单、工作量重估 3.5-5 天）

zhizhijie

2026-10-06 5194ad0c471cf6fa81786ad7fbe4269c364f8f0c

docs(汇总大表): M0 月度版式重建器规格（10 页规格表、改动清单、工作量重估 3.5-5 天）

 docs/»ã×Ü´ó±íM0°æʽÖؽ¨Æ÷¹æ¸ñ_2026-10-06.md

New file
@@ -0,0 +1,106 @@
# æ±‡æ€»å¤§è¡¨ M0「月度版式重建器」规格（2026-10-06）

> çŠ¶æ€ï¼š**【待验收】本轮只定规格与工作量，不含代码改动**；规格经用户审定后再开工。
> ä¾æ®ï¼š`docs/汇总大表数据驱动改造方案_2026-09-07.md`（含 2026-09-08 é™„录）、`HANDOFF.md` çš„ 2026-09-28 / 09-29 ä¸¤èŠ‚、2026-09-29 ç”¨æˆ·æ‰‹å·¥äº§å‡ºçš„ 9 æœˆæ¯ç‰ˆã€‚

## ä¸€ã€èƒŒæ™¯ä¸Žç›®æ ‡

- **现状**：汇总大表的数据驱动回填（方案 M1–M3）已落地——`exportSummaryWorkbook` å·²æŒ‰ã€Œè¯»åº“计算 â†’ å›žå¡«æ¯ç‰ˆ â†’ æ•´æœ¬é‡ç®—」运行（`ReportExportService.java:3634` èµ·ï¼Œè®¡ç®—层 `reportexport/calc`）。
- **唯一卡点**：**月度列版式**。程序只按 `{year}å¹´{month}月道路运输量汇总表.xlsx` ç²¾ç¡®åŒ¹é…æ¯ç‰ˆï¼ˆ`ReportExportService.resolveSummaryMother`，同文件 4576 è¡Œï¼‰ï¼Œç›®æ ‡æœˆæ²¡æœ‰å¯¹åº”母版就直接抛错，不会自动扩列。9 æœˆæ¯ç‰ˆæ˜¯ç”¨æˆ· 09-29 åœ¨ Excel é‡Œæ‰‹å·¥æ‰©å‡ºæ¥çš„（本机 `docs/生成汇总大表/2026å¹´9月道路运输量汇总表.xlsx`、`_试做_20260929.xlsx`，均未入库）。
- **目标（M0）**：给定「一本可用母版 + ç›®æ ‡å¹´æœˆã€ï¼Œç¨‹åºè‡ªåŠ¨æŠŠåˆ—版式重建到目标月，产出可直接回填的母版版式，替代每月手工扩列。
- **出口验收**：① é‡å»ºåŽç”Ÿæˆ 2026-07，数值与已修正 7 æœˆæ¯ç‰ˆé€æ ¼ diff=0（仅列位变化）；② ç”Ÿæˆ 2026-09，与用户手工 9 æœˆæ¯ç‰ˆé€æ ¼ diff=0。

## äºŒã€ä¸ºä»€ä¹ˆæ˜¯å¢žé‡æ”¹é€ è€Œä¸æ˜¯é‡å†™

| å±‚次 | çŽ°çŠ¶ | ç»“论 |
|---|---|---|
| è®¡ç®—层 | `reportexport/calc/{PaxCalc,FreightCalc,MidCalc,WycSplitCalc}`，约 900 è¡Œ | ç›´æŽ¥å¤ç”¨ |
| å›žå¡«å±‚ | `SummaryWorkbookFiller`（899 è¡Œï¼‰ï¼š`fillMonthlyLedger` / `ensureMonthFormulas` / `ensureMonthYoyFormulas` / `repairCumulativeYoyFormulas` / `yearMonthCols` / `usableMonthCols` / `cumulativeHelperCols` | ç›´æŽ¥å¤ç”¨ |
| æ‰©åˆ—原语 | `ReportExportService.java:1039-1200`：`moveColumnPair` / `cloneColumnPair` / `cloneCellForMonth` / `cloneMergedRegion` / `copyColumnWidth` / `fixCumulativeFormulas`；且已跑通 `extendMonthlyColumns`（独立小表 1–6 æœˆ â†’ 1–12 æœˆï¼‰ | ç›´æŽ¥å¤ç”¨ |
| **缺口** | æŠŠä¸Šè¿°åŽŸè¯­**编排**到汇总大表 19 ä¸ªé¡µç­¾é‡Œçš„ 10 ä¸ªé•¿è¡¨é¡µï¼Œå¹¶é€é¡µé…ç½®è§„则 + å›žå½’自检 | **本次新增** |

已有投入（不可丢弃）：38 ä¸ªæäº¤ã€930 æ ¼å·®å¼‚核对、A1–E3/Q1–Q3 ä¸€è½®å£å¾„拍板。重写不划算。

## ä¸‰ã€åˆ—版式规则（0 åŸºåˆ—号）

| é¡¹ | è§„则 |
|---|---|
| å½“月值列 | 1 æœˆ = 2（C åˆ—）；m æœˆ = `2 + 2 Ã— (m âˆ’ 1)` |
| å½“月同比列 | å½“月值列 + 1 |
| ç´¯è®¡åˆ— / ç´¯è®¡åŒæ¯”列 | 2026 ç»„末尾，当前 14/15（O/P）；扩到 12 æœˆåŽä¸º 26/27 |
| 2025 åŠæ›´æ—©å‚照组 | æ¯æ‰©ä¸€ä¸ªæœˆæ•´ä½“右移 2 åˆ— |
| å·²ç¡®è®¤å£å¾„（方案 D1） | å½“月值列+同比列插在累计之前、累计滚动、2025+ å‚照组右移——等价于本文件的「月度版式重建器」 |

`SummaryWorkbookFiller.FIRST_MONTH_COL=2`（同文件 47 è¡Œï¼‰ä¸Žè¯¥å…¬å¼ä¸€è‡´ï¼Œä½†å±žç¡¬ç¼–码锚点，见第七节第 4 æ¡ã€‚

## å››ã€éœ€è¦æ‰©åˆ—çš„ 10 ä¸ªé•¿è¡¨é¡µï¼ˆæ•°å­—取自方案 v1 é™„录实测）

| é¡µç­¾ | maxCol | åˆå¹¶åŒº | éœ€å¹³ç§»çš„公式数 |
|---|---|---|---|
| ` è´§è¿`（注意前导空格） | 145 | 140 | 6638 |
| ç­çº¿åŒ…车 | 285 | 204 | 5688 |
| ä¸­å£å¾„明细 | 87 | 157 | 6654 |
| å…¬äº¤ | 86 | 76 | 2004 |
| å‡ºç§Ÿ | 86 | 76 | 1872 |
| ç½‘约车 | 86 | 70 | 1664 |
| å…¬è·¯æ€»å®¢è¿ | 274 | 194 | æœªå•ç‹¬ç»Ÿè®¡ |
| åŸŽå¸‚客运 | 72 | 55 | æœªå•ç‹¬ç»Ÿè®¡ |
| è½¨é“、轮渡 | 72 | 110 | æœªå•ç‹¬ç»Ÿè®¡ |
| ä¸­å£å¾„客运量 | 68 | 111 | æœªå•ç‹¬ç»Ÿè®¡ |

已知 6 é¡µå…¬å¼å¹³ç§»åˆè®¡çº¦ **24,520 å¤„**（公交 2004 / å‡ºç§Ÿ 1872 / ç½‘约 1664 / ä¸­å£å¾„明细 6654 / è´§è¿ 6638 / ç­çº¿ 5688）。

## äº”、不需要扩列的页

- **6 ä¸ªæˆå“é¡µ**（当月块与累计块是行结构、列位固定，直接按映射填值/公式）：货运量排名、货运周转量排名、中口径排名、城市汇总、城市分市州、道路运输周转量。
- **3 ä¸ªé™æ€é¡µ**（不动）：中口径分析、2025年城市客运量、中口径计算过程。

## å…­ã€æ”¹åŠ¨æ–‡ä»¶æ¸…单

- æ–°å¢ž `traffic-audit-server/src/main/java/com/trafficaudit/reportexport/layout/SummaryLayoutRebuilder.java`：编排层，按目标月重建 10 ä¸ªé•¿è¡¨é¡µçš„列布局。
- æ–°å¢ž `traffic-audit-server/src/main/java/com/trafficaudit/reportexport/layout/SummarySheetRule.java`：逐页规则配置（表头行、数据起止行、月份组起点、累计列位、是否派生页、合并区策略）。
- æ–°å¢ž `traffic-audit-server/src/test/java/com/trafficaudit/reportexport/layout/SummaryLayoutRebuilderTest.java`：扩列后 7/9 æœˆæ•°å€¼å›žå½’自检。
- æ”¹é€  `ReportExportService.exportSummaryWorkbook`（同文件 3634 è¡Œèµ·ï¼‰ï¼šæ¯ç‰ˆç¼ºå¤±æ—¶ä¸å†æŠ›é”™ï¼Œæ”¹ä¸ºã€Œå–最近可用母版 â†’ é‡å»ºåˆ°ç›®æ ‡æœˆ â†’ ç»§ç»­å›žå¡«ã€ã€‚
- æ”¹é€  `ReportExportService.resolveSummaryMother`（同文件 4576 è¡Œï¼‰ï¼šæ”¾å¼€"仅精确匹配"限制，保留"找不到任何蓝本才报错"。
- å¯é€‰ï¼ˆå»ºè®®åšï¼‰ï¼šæŠŠ `SummaryWorkbookFiller.FIRST_MONTH_COL` ç¡¬ç¼–码改为按表头 `yearMonthCols` è¯­ä¹‰å®šä½ï¼Œé¿å…æ¯ç‰ˆæŒªåˆ—后静默写错列。
- å‰ç«¯ï¼šæ— éœ€æ”¹åŠ¨ï¼ˆå…¥å£ä¸Žå‚数不变）。
- æ–‡æ¡£ï¼šæœ¬è§„æ ¼ + `HANDOFF.md` ç»“论；`_试做_20260929.xlsx` ç­‰è¿‡ç¨‹äº§ç‰©ä¸å…¥åº“。

## ä¸ƒã€å…³é”®ç®—法

1. **选蓝本**：目标月母版存在则直接用；不存在则取最近可用母版（默认 9 æœˆæ‰‹å·¥ç‰ˆï¼Œè§ç¬¬åèŠ‚待确认项 1）。
2. **定位**：复用 `yearMonthCols` çš„表头识别（支持文本 `2026å¹´8月` ä¸Žæ•°å€¼æ—¥æœŸåºåˆ—表头，只认今年/去年），在前 5 è¡Œå†…找出各月份组的实际列位——先认位置再动列，不盲信固定列号。
3. **重建**（对每个长表页）：移动累计列对到 2026 ç»„末尾 â†’ æŒ‰æœˆå…‹éš†æœˆä»½åˆ—对（表头文本/日期修正、样式、合并区、列宽、跨页公式列引用同步）→ ä¿®æ­£ç´¯è®¡ä¸Žç´¯è®¡åŒæ¯”公式。
4. **重算与自检**：`setFullCalcOnLoad(true)` + æ•´æœ¬é‡ç®—；输出前跑「#REF! è®¡æ•° = 0」「累计列覆盖到当期」自检，不通过则中止。

## å…«ã€éªŒè¯æ–¹æ¡ˆï¼ˆM0 å‡ºå£ï¼‰

| ç¼–号 | ç”¨ä¾‹ | é¢„期 |
|---|---|---|
| 1 | é‡å»ºç‰ˆå¼åŽç”Ÿæˆ 2026-07 | ä¸Žå·²ä¿®æ­£ 7 æœˆæ¯ç‰ˆè¢«å¡«åŒºåŸŸé€æ ¼ diff=0，仅列位变化 |
| 2 | ç”Ÿæˆ 2026-09 | ä¸Žç”¨æˆ·æ‰‹å·¥ 9 æœˆæ¯ç‰ˆé€æ ¼ diff=0 |
| 3 | å…¬å¼è‡ªæ£€ | å…¨ç°¿ `#REF!` = 0；累计/累计同比覆盖到当期 |
| 4 | ç‰ˆå¼è‡ªæ£€ | åˆå¹¶åŒºã€åˆ—宽、隐藏标记、打印区与手工 9 æœˆæ¯ç‰ˆä¸€è‡´ï¼›Excel/WPS æ‰“开无修复告警 |
| 5 | è´Ÿå‘：目标月源数据缺失 | ç»™å‡ºç¼ºæ•°æ¸…单，不静默输出空表 |
| 6 | è´Ÿå‘：母版被改导致月份表头识别不到 | æ˜Žç¡®æŠ¥é”™ï¼Œä¸çŒœæµ‹åˆ—位 |

## ä¹ã€å·¥ä½œé‡é¢„ä¼°

| é˜¶æ®µ | é¢„ä¼° |
|---|---|
| è§„格表定稿（本文件 + ç”¨æˆ·å®¡å®šï¼‰ | 0.5 å¤© |
| Rebuilder + é€é¡µè§„则 + å•æµ‹ | 1.5–2.5 å¤© |
| 7/8 æœˆå›žå½’ + 9 æœˆå¯¹ç…§æ ¸å¯¹ | 1 å¤© |
| é£Žé™©ç¼“冲 | 0.5–1 å¤© |
| **合计** | **约 3.5–5 å¤©**（含测试与验收） |

说明：`HANDOFF.md` 09-29 èŠ‚曾估「0.5~1 å¤©ã€ï¼Œé‚£åªæ˜¯æ‰©åˆ—原语的复用估计；按附录实测（约 2.45 ä¸‡å¤„公式平移 + 2 åƒä½™å¤„合并区）重估为 3.5–5 å¤©ã€‚

## åã€é£Žé™©ä¸Žå¾…确认

1. **待确认：以哪本作扩列蓝本。** å»ºè®®ä»¥ç”¨æˆ·æ‰‹å·¥çš„ 9 æœˆæ¯ç‰ˆä¸ºå‡†ï¼ˆç‰ˆå¼å·²ç”±ç”¨æˆ·å›ºåŒ–）。
2. **待确认：是否一次建成 12 æœˆæ»¡ç‰ˆå¼ã€‚** æ–¹æ¡ˆ v1 å»ºè®®æ»¡ç‰ˆå¼ã€åŽç»­æœˆä»½åªåšã€Œéšè—/置灰未到月份 + ç´¯è®¡é‡ç®— + å¡«å½“月」，可显著降低后续风险；若坚持逐月插入，复杂度与回归成本更高。
3. **母版历史坑要一并覆盖**：母版由 openpyxl å†™å‡ºï¼Œå­˜åœ¨é«˜åŽ‹ç¼©ï¼ˆå·²ç”¨ `ZipSecureFile.setMinInflateRatio` ç»•è¿‡ï¼‰ä¸Žæ®‹ç•™ `<is>` éžæ³•æ ¼ï¼ˆ`normalizeStaleInlineStrings` æ¸…理）两类问题，逐列克隆时需保持这两处处理。
4. **城市客运页参照组是压缩结构**（同比 + 1-X æœˆç´¯è®¡ï¼‰ï¼Œä¸Žå…¶å®ƒé•¿è¡¨é¡µä¸åŒï¼Œéœ€å•ç‹¬è§„则。
5. **跨年开新本（2027）不在 M0 èŒƒå›´**，需另定"新年块"规则。
6. **未覆盖页**：中口径分析等 3 ä¸ªé™æ€é¡µä»æ²¿ç”¨æ¯ç‰ˆé™æ€å†…容，本阶段不改。