fix(summary): 修 2026-07 导出件「Excel 打不开」+ 补齐 7 月母版 2021/2022/2023 累计列

zhizhijie

2026-09-16 80e08795ef502404dd4e343a9779c68cd8567846

 docs/ÎÊÌâ»ã×Ü/ÎÊÌâÓë×¢ÒâÊÂÏî»ã×Ü_2026-09-16.md

@@ -179,3 +179,111 @@
| 4 | é¢„览弹窗「共 0 è¡Œã€ä¸Žã€Œæœˆåº¦è¦†ç›–：1~8月均有数据」口径不同 | æ˜“误解 | å¾…用户确认改文案 |
| 5 | å…¬å¸ gitea æŽ¨é€ | ç½‘络无响应，未推成功 | å¾…补推 |
| 6 | ä»“库根目录大量 `_*.*` ä¸´æ—¶æ–‡ä»¶ | ä½“积/可读性 | ç»ç”¨æˆ·åŒæ„åŽå†æ¸…理 |

> 2026-09-16 å‚æ™šæ›´æ–°ï¼šé—留问题 4（预览弹窗「共 0 è¡Œã€æ–‡æ¡ˆï¼‰å·²æŒ‰ç”¨æˆ·ç¡®è®¤ä¿®æ”¹å®Œæ¯•â€”—汇总大表改为显示「指标 N é¡¹ã€ï¼Œå…¶å®ƒæŠ¥è¡¨æ˜¾ç¤ºã€Œå…± N è¡Œæ˜Žç»†ã€ã€‚

---

## åäºŒã€2026-09-16 è¡¥å……：货运页签「累计」列修复（重要口径）

### 12.1 æ¯ç‰ˆæ´¾ç”Ÿå£å¾„（必须遵守）

《 è´§è¿ã€‹é¡µè¡Œç»“构：
- å…¨çœå—：r5 è´§è¿é‡ / r6 å‘¨è½¬é‡ / r7 å…¶ä¸­è§„上货运量 / r8 å…¶ä¸­è§„上周转量 / r9 å…¶ä¸­è§„下货运量 / r10 å…¶ä¸­è§„下周转量；
- 17 ä¸ªå¸‚州块每块 6 è¡Œï¼Œé¦–è¡Œ 11,17,23,...,107（武汉市...林区），块内顺序：合计货运量 / è§„上货运量 / è§„下货运量 / åˆè®¡å‘¨è½¬é‡ / è§„上周转量 / è§„下周转量。

**规则：全省行必须完全由 17 å¸‚州行派生。**
- r7 / r8 / r9 / r10 = SUM(17 å¸‚州对应行)；
- r5 = m7+m9，r6 = m8+m10。

历史教训：r9/r10（全省规下）曾是**写死常量**，与 17 å¸‚州规下之和不等 â€”— 2023 å·® 4.6e-3、2022 å·® 3.1e-3、2021 å·® 1.5e-4（2024/2025/2026 æ°å¥½ä¸º 0），导致 6 ä¸ªç´¯è®¡åˆ—里 2022/2023 æ¯”源文件人工核算差 0.003 å·¦å³ã€2021 æ•´åˆ—为空。2026-09-16 å·²å…¨éƒ¨æ”¹ä¸ºå…¬å¼ã€‚

累计列现状（全省行，4 ä½å°æ•°ä¸Žæºæ–‡ä»¶ä¸€è‡´ï¼‰ï¼š

| åˆ— | å¹´åº¦ | å…¬å¼ |
|---|---|---|
| S | 2026(1-8月) | C+E+G+I+K+M+O+Q |
| AT | 2025 | V+X+...+AR |
| BV | 2024 | AX+AZ+...+BT |
| CW | 2023 | BY+CA+...+CU |
| DZ | 2022 | =SUM(DM:DX)（原为写死常量） |
| EO | 2021 | =SUM(EC:EN)（原为**空**） |
| EP | 2021 ç´¯è®¡åŒæ¯” | ä¿æŒä¸ºç©ºï¼ˆé¡µå†…æ—  2020 å—，无基期） |
| EA | 2022 ç´¯è®¡åŒæ¯” | =IFERROR(DZ/SUM(EC:EN)-1, ç©ºä¸²)（原为写死常量） |

### 12.2 æ¯ç‰ˆæ”¹åŠ¨æ–¹å¼ä¸Žæ–‡ä»¶èŒè´£

- **必须用 Excel COM**（改公式 -> CalculateFullRebuild -> Save），**不可用 openpyxl å¦å­˜**：会清空全本公式缓存值（曾导致 2021 å¹´æ¹–北省行变 0）。
- å¯¼å‡ºä»¶é‡Œçš„公式**无缓存值**：openpyxl(data_only=True) è¯»å‡ºæ¥å…¨æ˜¯ None，核对数值必须用 Excel COM é‡ç®—或自写求值器。
- æ–‡ä»¶èŒè´£ï¼š
  - YYYYå¹´M月道路运输量汇总表.xlsx = **母版**（唯一数据来源）；
  - ç”Ÿæˆ_道路运输量汇总表.xlsx = **只作列宽参照**（applySummaryReferenceLayout åªè¯»åˆ—宽/隐藏标记，不读数值）；
  - 2026å¹´8月道路运输量汇总表_版式原型.xlsx = è¿è¡Œæ—¶**无任何代码引用**。
- åŒæœŸå¤‡ä»½æ¯ç‰ˆè¿˜åŽŸæœºåˆ¶ï¼šresolveSummaryDonor åªè®¤æ–‡ä»¶å**以 `_备份_` å¼€å¤´ä¸”含「{å¹´}月」**的文件，命中即整格回填覆盖母版。=> è‡ªå»ºçš„备份文件/目录**不要**用 `_备份_` å‰ç¼€ï¼Œå¦åˆ™å¯èƒ½è¢«å½“成 donor æŠŠæ¯ç‰ˆæ”¹å›žæ—§å€¼ã€‚

### 12.3 æ–‡æœ¬å¤„理的坑（本机 PowerShell / git）

| é—®é¢˜ | åŽŸå›  | å¤„ç½® |
|---|---|---|
| å…¬å¼è¢«å†™æˆ =SUM(DM5) | "$m7" è¢«è§£æžä¸ºå˜é‡ m7；"$r:DX" é‡Œçš„ $r:DX è¢«å½“成「驱动器 r:」而吞掉 | ä¸€å¾‹ç”¨ ${m} / ${r} å®šç•Œ |
| å‘½ä»¤æ•´ä½“不执行、无输出、退出码 1 | ä¸€ä¸ªå‘½ä»¤é‡Œå‡ºçŽ°**嵌套的单引号 here-string**，外层在第一个结束符处提前结束 | ä¸€ä¸ªå‘½ä»¤åªæ”¾ä¸€ä¸ª here-string；或先 Out-File å†™è¡¥ä¸æ–‡ä»¶ï¼Œå†ç”¨ Get-Content -Raw |
| apply_patch ä¼ å¤šè¡Œå‚数失败 | .bat åŒ…装器破坏了多行参数 | ç›´æŽ¥è°ƒ codex.exe --codex-run-as-apply-patch $patch |
| git commit -m æŠ¥ "outside repository" | PowerShell ç”¨åå¼•å·è½¬ä¹‰ï¼Œæ¶ˆæ¯é‡Œçš„反斜杠+引号会提前结束字符串 | ç”¨ git commit -F <消息文件> |
| PS5.1 æŠ¥ä¹±ç è·¯å¾„「无法找到 ...」 | PS7 çš„ Out-File -Encoding utf8 å†™çš„是**无 BOM** UTF-8，PS5.1 æŒ‰ GBK è¯»è„šæœ¬ | å†™ .ps1 æ—¶ç”¨ -Encoding utf8BOM |

### 12.4 é—留问题增量（截至 2026-09-16 æ™šï¼‰

| # | é—®é¢˜ | å½±å“ | çŠ¶æ€ |
|---|---|---|---|
| 7 | h2032_enterprise_monthly 2026-09 è„æœŸï¼ˆå®žä¸º 8 æœˆæ–‡ä»¶è¯¯å­˜ä¸º 9 æœˆï¼‰ | 636 è¡Œ + import_batch 302 | **已删除**，留可还原 SQL å¤‡ä»½ |
| 8 | ã€Š è´§è¿ã€‹é¡µç´¯è®¡åˆ— 2021/2022/2023 å¯¹ä¸ä¸Šäººå·¥æ ¸ç®— | å·²ä¿®æ¯ç‰ˆæ´¾ç”Ÿå£å¾„，6 åˆ—全部对上 | **已解决** |
| 9 | 2026-09 æœŸè¿˜åœ¨ h204_vehicle_quarterly(1284 è¡Œ) / investment_monthly(31 è¡Œ) / audit_result(2061 è¡Œ) / audit_run(3 è¡Œ) | è‹¥æŒ‰ 2026-09 å‡ºæŠ¥è¡¨ä¼šå–到脏数据 | å¾…用户确认是否清理 |
| 10 | 2026-07 å¯¼å‡ºä»¶ã€Š è´§è¿ã€‹é¡µä¸º 118x145（比 8 æœˆå°‘ 2 åˆ—） | 7 æœˆæ¯ç‰ˆæ˜¯ã€Œ1-4 æœˆéª¨æž¶ã€ï¼Œéžå®Œæ•´æ¯ç‰ˆ | å¾… 7 æœˆæ¯ç‰ˆå®šç¨¿ |
| 11 | 2026å¹´8月道路运输量汇总表_版式原型.xlsx çš„ S åˆ—漏 8 æœˆï¼ˆç¼º Q5） | è¿è¡Œæ—¶æœªè¢«å¼•ç”¨ï¼Œæš‚无影响 | å¾…确认该文件去留 |
| 12 | æ¯ç‰ˆç» Excel é‡å­˜åŽä½“积 959,706 -> 1,492,121 å­—节（导出件 950,186 -> 1,331,599） | çº¯æ ¼å¼å¼€é”€ï¼Œæ•°æ®æ— å½±å“ | è®°å½• |

详见《功能测试报告/功能测试报告_货运页签累计列修复与脏期清理_2026-09-16.md》。

---

## åä¸‰ã€2026-09-16 è¡¥å……：2026-07 æ¯ç‰ˆè¡¥é½ & å¯¼å‡ºä»¶ã€ŒExcel æ‰“不开」根因（P0）

### 13.1 ç—‡çŠ¶ä¸Žæ ¹å› 

| é¡¹ | å†…容 |
|---|---|
| ç—‡çŠ¶ | `GET /api/report/export/summaryWorkbook?period=2026-07&mode=month` ç”Ÿæˆçš„ xlsx，**Excel æ‰“不开**（COM æŠ¥ã€Œä¸èƒ½å–å¾—ç±» Workbooks çš„ Open å±žæ€§ã€ï¼›`CorruptLoad=1` ä¿®å¤æ¨¡å¼åŒæ ·æ‰“不开）；2026-08 åŒæŽ¥å£æ­£å¸¸ |
| ç›´æŽ¥åŽŸå›  | å¯¼å‡ºä»¶é‡Œæœ‰ **19 ä¸ªæ¨¡å¼éžæ³•æ ¼**：`<c r="E15" s="111" t="n"><v>67.0</v><is><t>67.00</t></is></c>` â€”— `t="n"` ä¸å…è®¸å¸¦ `<is>`（inlineStr ä¸“用） |
| æ·±å±‚原因 | 7 æœˆæ¯ç‰ˆç”± **openpyxl** å†™å‡ºï¼ˆ`docProps/app.xml` = `Microsoft Excel Compatible / Openpyxl 3.1.5`，文本存 `<is>`）；8 æœˆæ¯ç‰ˆæ˜¯ **Excel åŽŸç”Ÿ**（文本走 sharedStrings）。POI çš„部分写入路径只改 `t`/`<v>`、不清旧 `<is>` |
| è§¦å‘路径 | 7 æœˆå­˜åœ¨ `_备份_2026å¹´7月道路运输量汇总表_清理前_20260904.xlsx` â†’ `restoreSummaryMonthlyBlocks` æ•´æ ¼å›žå¡« â†’ å¾€ inlineStr æ ¼é‡Œå†™å€¼ç•™ä¸‹æ—§ `<is>`。8 æœˆæ—  `_备份_*`，不走回填，故正常 |
| å‘½ä¸­ä½ç½® | leave-one-out å®šä½åˆ° **sheet9《公交》17 æ ¼ + sheet12《轨道、轮渡》2 æ ¼** |

### 13.2 ä¿®å¤ï¼ˆ`traffic-audit-server`）

1. **`exportSummaryWorkbook` æ–°å¢ž `normalizeStaleInlineStrings(wb)`**：落盘前清掉所有「非 `inlineStr` å´æ®‹ç•™ `<is>`」的格子（幂等），命中即打 warn æ—¥å¿—。
2. **`restoreSummaryMonthlyBlocks` æ–°å¢ž `skipFreightHistoryBlocks`**：《 è´§è¿ã€‹é¡µ **T åˆ—及以后**（2025/2024/2023/2022/2021 å¹´åº¦å— + å„年累计/累计同比列）**永不从备份母版回填** â€”— ä¸Žæ—¢æœ‰ã€Œä¸­å£å¾„排名左块永不回填」同一思路，避免补齐被「生成又复活」。

### 13.3 2026-07 æ¯ç‰ˆè¡¥é½ï¼ˆå£å¾„与 8 æœˆæ¯ç‰ˆå¯¹é½ï¼‰

- å¹´åº¦å—（每列）：`r7/r9/r8/r10 = SUM(17 å¸‚州对应行)`、`r5 = r7+r9`、`r6 = r8+r10` â†’ 360 æ ¼ï¼›
- ç´¯è®¡åˆ—：`DX = SUM(DK:DV)`（2022）、`EM = SUM(EA:EL)`（2021，原**整列为空**）、`DY = IFERROR(DX/SUM(EA:EL)-1,"")`（2022 ç´¯è®¡åŒæ¯”，原为**写死常量**）→ 324 æ ¼ï¼›
- 2023 ç´¯è®¡ `CU = BW+BY+…+CS` æœ¬æ¥å°±æ­£ç¡®ï¼Œæœªæ”¹ï¼›`EN`（2021 ç´¯è®¡åŒæ¯”）按口径保持为空。
- ä¸€æ‰‹è¯æ®ï¼šæ¯ç‰ˆ `DX5=144979.2825`（旧常量 `144979.285376043`，差 0.0029 = å…¨çœè§„下常量与 17 å¸‚州之和的差）、`EM5=161309.53162`、`CU5=173045.296428512`，与 8 æœˆæ¯ç‰ˆ `DZ5/EO5/CW5` **完全相等**。
- å¤‡ä»½ï¼š`docs/生成汇总大表/_bak_2026å¹´7月道路运输量汇总表_补齐前_20260916.xlsx`。**切勿改名为 `_备份_` å¼€å¤´**，否则会被 `resolveSummaryDonor` å½“ donor å›žå¡«ã€‚

### 13.4 æœ¬æ¬¡æ–°å¢žçš„排查坑

| é—®é¢˜ | åŽŸå›  | å¤„ç½® |
|---|---|---|
| Excel COM **间歇性**报同一个错，导致误判「8 æœˆä»¶ä¹Ÿæ‰“不开」 | æ¯æ¬¡ `New-Object -ComObject Excel.Application` ç•™ä¸‹çš„**孤儿 EXCEL è¿›ç¨‹**会污染后续实例 | æ¯ä¾‹æµ‹å®ŒæŠŠã€Œæœ¬æ¬¡æ–°å»ºçš„ EXCEL è¿›ç¨‹ã€å¼ºæ€å†æµ‹ä¸‹ä¸€ä¾‹ï¼›`Quit()`+`ReleaseComObject` å¹¶ä¸å¤Ÿ |
| ç¼–译报「找不到 isSetSheetData()」 | `CTWorksheet.sheetData` æ˜¯ XSD **必填**元素，不生成 `isSetXxx` | æ”¹ç”¨ `ctw.getSheetData() != null` |
| éƒ¨ä»¶çº§ diff å¤ªå¤§è·‘不动 | å¯¹ 519KB çš„ `styles.xml` ç›´æŽ¥ `difflib` æ˜¯ O(n²) | å…ˆæŒ‰éƒ¨ä»¶æ¯”字节尺寸/是否相等，只在必要的小部件上做 diff |

### 13.5 é—留问题增量

| # | é—®é¢˜ | å½±å“ | çŠ¶æ€ |
|---|---|---|---|
| 13 | 2026-06 / 2026-09 æ— æ¯ç‰ˆ | é¢„览 `ready=False`「未找到模板文件」，无法出数 | éœ€å…ˆå»ºæ¯ç‰ˆï¼ˆç”¨æˆ·ç¬¬ 5 é—®çš„延伸） |
| 14 | ä»“库根 `_*.*` ä¸´æ—¶æ–‡ä»¶ç»§ç»­å¢žå¤šï¼ˆ`_hyb_*` / `_loo_*` / `_v2_*` / `_final_*` / `_fixed_*` / `_t7_*` / `_poijar`） | ä½“积/可读性 | ç»ç”¨æˆ·åŒæ„åŽå†æ¸…理 |

> ç¬¬ 10 é¡¹ï¼ˆ2026-07 å¯¼å‡ºä»¶å°‘ 2 åˆ— / 7 æœˆæ¯ç‰ˆæ˜¯ã€Œ1-4 æœˆéª¨æž¶ã€ï¼‰æœ¬èŠ‚已处理：导出端会**自动补出 5/6/7 æœˆè¡¨å¤´ä¸Žå…¬å¼**并重算累计公式，母版已补齐 2021/2022/2023 ç´¯è®¡åˆ—，故关闭该项。