docs/»ã×Ü´ó±íM0°æÊ½Öؽ¨Æ÷¹æ¸ñ_2026-10-06.md
@@ -103,4 +103,102 @@
3. **母版历史坑要一并覆盖**:母版由 openpyxl å†™å‡ºï¼Œå­˜åœ¨é«˜åŽ‹ç¼©ï¼ˆå·²ç”¨ `ZipSecureFile.setMinInflateRatio` ç»•过)与残留 `<is>` éžæ³•格(`normalizeStaleInlineStrings` æ¸…理)两类问题,逐列克隆时需保持这两处处理。
4. **城市客运页参照组是压缩结构**(同比 + 1-X æœˆç´¯è®¡ï¼‰ï¼Œä¸Žå…¶å®ƒé•¿è¡¨é¡µä¸åŒï¼Œéœ€å•独规则。
5. **跨年开新本(2027)不在 M0 èŒƒå›´**,需另定"新年块"规则。
6. **未覆盖页**:中口径分析等 3 ä¸ªé™æ€é¡µä»æ²¿ç”¨æ¯ç‰ˆé™æ€å†…容,本阶段不改。
6. **未覆盖页**:中口径分析等 3 ä¸ªé™æ€é¡µä»æ²¿ç”¨æ¯ç‰ˆé™æ€å†…容,本阶段不改。
## åä¸€ã€å‚照同事「专项统计」的设计映射与落地路线(2026-10-08)
### 11.1 å¯¹é½è¡¨ï¼šä»–为什么能一个母版,我们对应怎么做
| åŒäº‹ä¸“项统计的做法 | ä»–为什么能成立 | æ±‡æ€»å¤§è¡¨çš„对应做法 |
|---|---|---|
| ä¸€ä»½æ¯ç‰ˆï¼ˆ`2026年十一数据.xlsx`),**天为行、年为列** | å¢žé•¿ç»´åº¦æ˜¯ã€Œå¹´ã€ï¼Œä¸€å¹´åŠ ä¸€ç»„åˆ—ï¼›å¤©æ•°å›ºå®š 8 | å†»ç»“《道路运输量汇总表_标准母版.xlsx》:**12 ä¸ªæœˆæ»¡ç‰ˆå¼ä¸€æ¬¡åˆ°ä½**,只读 |
| æ¯ç‰ˆåŒæ—¶æ˜¯æ•°æ®å®¹å™¨ï¼ˆåŽ†å²å¹´ä»½çš„å€¼å°±åœ¨å¹¶æŽ’å¹´åˆ—é‡Œï¼‰ | åŽ†å²å€¼éšæ¨¡æ¿ä¸€èµ·èµ° | **反过来做**:历史参照值入库,母版只留版式,参照组由 DB å›žå¡« |
| è¡¨å¤´/行标签语义定位(`findYearColumn` / `parseDayIndex`) | åˆ—序变了也能导 | æ–°å¢žé¡µè§„则表 `SummarySheetRule`:按表头认月份组、按行标签认市州/指标,不用硬编码列锚点 |
| æ˜“漂移口径外置成表(`holiday_calendar` / `passenger_coefficient` / `vehicle_adjustment`) | è§„则不散在代码与单元格里 | å‚照年保留组数、排名口径(全省不排名)、周转量系数 B=G+L/2+Q/10、缺数置空规则 å¤–ç½® |
| `DECIMAL(30,15)` + `BigDecimal` + æŒ‰ Excel æ˜¾ç¤ºç²¾åº¦å–值 | ç²¾åº¦å£å¾„统一,无浮点尾差 | æ‰¿æŽ¥é•¿æœŸå¾…办「16 å¼ è¡¨ 228 ä¸ª double åˆ—改 DECIMAL + BigDecimal」 |
| å¯¼å…¥ä¸¤é˜¶æ®µç¡®è®¤ + å…¨ç¨‹åªè¯»æ ¸å¯¹ | åŽ†å²æ•°æ®ä¸è¢«è¯¯è¦†ç›– | ç”Ÿæˆå‰å…ˆå‡ºç¼ºæ•°/差异清单,人工确认后再出表(现有 B4 åŸºæ•°ä½“检补齐) |
| è¾“出走模板文件(docx / PNG) | ç‰ˆå¼æ¥æºå•一 | ä¿ç•™çŽ°æœ‰åšæ³•ï¼ˆå¿«æŠ¥æ”¹ `word/document.xml`、JFreeChart å‡º PNG) |
### 11.2 è½åœ°è·¯çº¿ï¼ˆå››é˜¶æ®µï¼‰
- **阶段 1(= M0,3.5–5 å¤©ï¼‰**:标准母版冻结 + æ»¡ç‰ˆå¼ + è·¨å¹´é‡å»º + é¡µè§„则表。
  æ–°å¢ž `SummaryLayoutRebuilder` / `SummarySheetRule` / å•测。
  å‡ºå£ï¼š7 æœˆå›žå½’ diff=0;9 æœˆå¯¹ç…§æ‰‹å·¥ç‰ˆ diff=0;10 æœˆèµ·å¯ç›´æŽ¥å‡ºè¡¨ã€‚
- **阶段 2(+1–2 å¤©ï¼‰**:把现有三份文件依赖合并为一份。
  çŽ°çŠ¶ä¾èµ–ï¼šæœˆåº¦æ¯ç‰ˆï¼ˆ`resolveSummaryMother`)+ `_备份_` donor(`resolveSummaryDonor` / `restoreSummaryMonthlyBlocks`)+ ç‰ˆå¼å‚照件(`resolveSummaryLayoutRef`)。
  ç›®æ ‡ï¼šåªç•™ã€Šé“路运输量汇总表_标准母版.xlsx》,参照值从库回填,停用 donor ä¸Žè¿˜åŽŸæœºåˆ¶ã€‚
  å‡ºå£ï¼š`docs/生成汇总大表/` ä¸‹åªå‰© 1 ä¸ªæ¨¡æ¿æ–‡ä»¶ + è¾“出目录(`_bak_*` ç­‰æœ¬åœ°ç•™å­˜ã€ä¸å…¥åº“)。
- **阶段 3(可选,+2–3 å¤©ï¼‰**:母版内用命名区域/占位符标注需填格,程序按名填写;母版被挪列/插行时明确报错。
- **阶段 4(可选,+5–10 å¤©ï¼‰**:把 10 ä¸ªé•¿è¡¨é¡µçš„版式参数化(列组规则 + åˆå¹¶åŒº + åˆ—宽 + æ•°å­—格式 + æ‰“印区),程序从版式定义渲染,母版文件降级为一次性样式提取源;
  3 ä¸ªéšè—å…¬å¼é¡µï¼ˆä¸­å£å¾„计算过程 / 2025年城市客运量 / ä¸­å£å¾„分析)保留文件形态。
### 11.3 ä¸¤æ¡ä¸ç…§æ¬
1. **不把 Excel å½“数据源**:同事那边业务每天填同一形状的 Excel æ–‡ä»¶ï¼›æ±‡æ€»å¤§è¡¨æ•°æ®å¿…须走 DB å¯¼å…¥ + ä¸¤é˜¶æ®µç¡®è®¤ï¼Œä¸èƒ½é€€å›ž"手工填母版"。
2. **必须有「新年组」逻辑**:他的天数是常数(8 å¤©ï¼‰ï¼Œè·¨å¹´åªæ˜¯åŠ ä¸€ç»„å¹´åˆ—ï¼›æˆ‘ä»¬è·¨å¹´è¦æ–°å¢žä¸‹ä¸€å¹´åº¦åˆ—ç»„å¹¶æŠŠå½“å¹´ç»„é™çº§ä¸ºå‚ç…§ç»„ï¼Œè¿™ä¸€æ­¥ä»–æ²¡æœ‰å¯¹åº”å®žçŽ°ã€‚
### 11.4 åº•线与风险
- 3 ä¸ªéšè—å…¬å¼é¡µä¾èµ–母版现成公式,阶段 1–2 å¿…须原样保留,阶段 4 æ‰è°ˆé‡å»ºã€‚
- æ‰“印区、页眉页脚、条件格式、列宽必须逐页核对,是"肉眼版式"最易漏的点。
- ä¸šåŠ¡æ”¹æŒ‡æ ‡è¡Œ/页签/边框属于需求变更,任何方案都要一次适配;本方案把频率从「每月一次」降到「偶尔一次」。
- æ¯ç‰ˆæ”¹ä¸ºåªè¯»ï¼Œå¯é¡ºå¸¦è§„避 WPS/openpyxl é‡å­˜å¸¦æ¥çš„高压缩与残留 `<is>` éžæ³•格两类历史坑。
## åäºŒã€å­˜å‚¨å±‚/展示层约定:参照同事「二维表」模式(2026-10-09)
### 12.1 ä¸‰å±‚职责
- **存储层(DB)**:一张张二维表,键与值明确;存三类内容——原始值、配置值、人工调整值。
- **计算层**:导出时按口径计算(累计、同比、环比、占比、排名)。
- **展示层(Excel)**:只把值和公式按版式摆出来,不承担存储职责。
### 12.2 ã€Œä¸€è¡¨ä¸€ç²’度」约定(示例取自同事的专项统计)
| è¡¨ | ä¸»é”®ï¼ˆç²’度) | å€¼ | ç±»åˆ« |
|---|---|---|---|
| holiday_passenger_flow | å¹´ + æ—¥æœŸ + è¿è¾“方式 | å®¢è¿é‡ | åŽŸå§‹å€¼ |
| holiday_vehicle_flow | å¹´ + æ—¥æœŸ + é“路类别 + è½¦åž‹ | è½¦æµé‡ã€çŽ¯æ¯”åŸºæœŸ | åŽŸå§‹å€¼ |
| holiday_calendar | å¹´ + èŠ‚å‡æ—¥ç±»åž‹ + ç¬¬å‡ æ—¥ | æ—¥æœŸ | é…ç½®å€¼ |
| holiday_passenger_coefficient | å¹´ + æ—¥æœŸç±»åˆ« | å®¢è¿ç³»æ•° | é…ç½®å€¼ |
| holiday_vehicle_adjustment | å¹´ + æ—¥æœŸ | è°ƒæ•´åŽå€¼ + åŽŸå›  | äººå·¥è°ƒæ•´å€¼ |
我们现有导入表同样满足该约定:`city_bus_monthly`(报表期 + åœ°åŒº + ä¼ä¸šï¼‰ã€`city_taxi_monthly`(报表期 + åœ°åŒºï¼‰ã€`freight_turnover_import`(报表期 + åœ°åŒºï¼‰ã€`scale_split_transport`(报表期 + åœ°åŒº + æœˆ/累计)、`h2031_enterprise_monthly`(报表期 + ä¼ä¸šï¼‰ã€`h2032_enterprise_monthly`、`wyc_order_monthly` / `wyc_total_monthly`、`passenger_individual_monthly`。存储层形态是对的。
### 12.3 äººå·¥è°ƒæ•´å€¼ä¸€å¾‹å•独建表(覆盖层)
- æ¨¡å¼ï¼š**原始记录不动**,另表存「覆盖值 + åŽŸå›  + æ—¶é—´ã€ï¼Œå”¯ä¸€é”®ä¸Žæ‰€è¦†ç›–对象一致(参照同事的 `holiday_vehicle_adjustment`)。
- æˆ‘们的适用对象:2025 å‚照值修正、异常站剔除、业务临时改数等。
### 12.4 çŽ°çŠ¶æ ¸éªŒï¼ˆ2026-10-09 å®žæµ‹ï¼Œä¿®æ­£æ—©æœŸåˆ¤æ–­ï¼‰
实测库 `127.0.0.1:3308 / traffic_audit`(MySQL 8.0.29):
| è¡¨ | 2025 æœˆä»½æ•° | ç»“论 |
|---|---|---|
| city_bus_monthly | 12/12 | é½å…¨ |
| city_taxi_monthly | 12/12 | é½å…¨ |
| wyc_order_monthly / wyc_total_monthly | 12/12 | é½å…¨ |
| h2031_enterprise_monthly / h2032_enterprise_monthly | 12/12 | é½å…¨ |
| passenger_individual_monthly | 12/12 | é½å…¨ |
| freight_turnover_import | 1/12(仅 2025-12) | **不构成缺口**:表带 `last_freight_m01..m12` / `last_turnover_m01..m12`,2026 å„期文件自带去年同月值 |
| scale_split_transport | 0/12 | **不构成缺口**:表带 `above/below/total_yoy`,同比已随 2026 å„期入库 |
- æ—©æœŸ"库里没有 2025 å¹´åŸŽå¸‚客运数据"的注释与提示文案(`ReportExportService.java:499 / 558 / 561`)**已过期**,触发条件不再成立;同比取数走的是库内去年同期(`aggOf(data, year-1, m, "湖北省")`,约 540 è¡Œï¼‰ã€‚
- **真正遗留的是口径问题,不是缺数据**:中口径排名/明细的 2025 åˆ—仍以**母版静态定稿值**为准(`readMidDetailLastYearCumulative`,`ReportExportService.java:2745` èµ·ï¼‰ï¼Œä»£ç æ³¨é‡Šï¼ˆ2686-2689 è¡Œï¼‰è¯´æ˜ŽåŽŸå› â€”â€”"排名页原先查库现算,两者在 **2025-03/04 ç½‘约车拆分**上不同"。
- å¤„置:先做「库内 2025 vs æ¯ç‰ˆ 2025」逐项 diff(中口径 4 ç»„ä»¶ Ã— 17 å¸‚å·ž Ã— 12 æœˆ + ç´¯è®¡ï¼‰ï¼Œäº¤ä¸šåŠ¡ç¡®è®¤ä»¥å“ªè¾¹ä¸ºå‡†ï¼Œå†å†³å®šæ˜¯å¦åˆ‡æ¢è¯»åº“ã€‚
### 12.5 ç»“果层(比同事更进一步,可选)
- åŒäº‹åº“里**不存计算结果**:累计、同比、占比、环比均导出时算,Excel å†…表现为公式。
- æˆ‘们可选增加一张结果表,粒度 = æœŸé—´ + é¡µ + æŒ‡æ ‡ + å¸‚å·ž + å½“月/累计;Calc å†™å…¥ã€Filler è¯»å–。
- æ”¶ç›Šï¼šå°è¡¨ä¸Žè·¨é¡µåˆæˆé¡µå…±ç”¨ä¸€å¥—结果;逐格 diff æ—¶èƒ½ç›´æŽ¥åŒºåˆ†ã€Œç®—错」还是「填错」。
- çº¦å®šï¼šæŒ‰æœŸé—´**幂等重算**(先删该期间再插);显示取整不下沉到库,只在展示层舍入。
### 12.6 è‡ªæ£€çºªå¾‹ï¼ˆçº¢çº¿ï¼‰
> **母版里不允许存在「只有它才有的数据」。**
判定方法:把母版所有值清空后,程序能否重新生成一张完全一致的表?能 â†’ æ•°æ®éƒ½åœ¨åº“;不能 â†’ è¿˜æœ‰æ•°æ®è—åœ¨ Excel é‡Œï¼Œç»§ç»­å¾€åº“里搬。
### 12.7 ä¸Ž M0 çš„关系(依赖顺序)
- 12.4 çš„口径核对不阻塞 M0 é˜¶æ®µ 1(版式重建)。
- M0 é˜¶æ®µ 2「停用 `_备份_` donor è¿˜åŽŸã€çš„æ•°æ®å‰æ**已基本满足**(2025 å·²åœ¨åº“);但仍需先关闭 12.4 çš„差异,否则切换取数来源会让数字变动、无法通过 diff=0 å›žå½’。