docs: 汇总大表生成数据验证方法成文（补提交）

zhizhijie

5 天以前 7f958f5bea92039eaf6d4f2af3cc0c46a86b8c94

docs: 汇总大表生成数据验证方法成文（补提交）

 docs/»ã×Ü´ó±íÉú³ÉÊý¾ÝÑéÖ¤·½·¨_2026-10-12.md

New file
@@ -0,0 +1,89 @@
# æ±‡æ€»å¤§è¡¨ã€Œç”Ÿæˆæ•°æ®æ˜¯å¦æ­£ç¡®ã€éªŒè¯æ–¹æ³•ï¼ˆ2026-10-12）

> ç”¨é€”：回答"程序生成的数据对不对"。
> **一句话原则**：每一段都要有一个**独立于该段的参照**——两边同源，就验不出东西。
> æœ¬æ–¹æ³•æ˜¯ 2026-10-12 ç”¨ä¸¤ç»„真实数据跑出来并修正过的（见第七节）。

## ä¸€ã€å…ˆæŠŠé—®é¢˜æ‹†å¼€ï¼ˆå¦åˆ™"正确"没有定义）

"程序生成的数据是否正确"实际是 4 ä¸ªä¸åŒçš„问题，参照和责任人都不同：

| # | é—®é¢˜ | å‚照（必须独立于被验对象） | è°è´Ÿè´£ | ç¨‹åºèƒ½è‡ªè¯å— |
|---|---|---|---|---|
| 1 | æºæ•°æ®å¯¹ä¸å¯¹ | æºæ–‡ä»¶ / çœé‡Œä¸‹å‘表模板 | æ•°æ®ã€ä¸šåŠ¡ | ä¸èƒ½ |
| 2 | ç®—法、口径对不对 | æ‰‹å†™ SQL å¤ç®—（不看母版、不看定稿） | ç¨‹åº | èƒ½ |
| 3 | å†™å›žã€ç‰ˆå¼å¯¹ä¸å¯¹ | ä¸Šä¸€æœŸæ¯ç‰ˆï¼ˆåŒæºå¯¹æ¯”，要求"不该动的格未变"） | ç¨‹åº | èƒ½ |
| 4 | ä¸Žäººå·¥å®šç¨¿ä¸€è‡´å— | æ‰‹å·¥å®šç¨¿ï¼ˆå¿…须记版本 + sha256） | åŒæ–¹å¤æ ¸ | éƒ¨åˆ† |

所以单问"数据对不对"没有答案；先问"**哪一段**"。

## äºŒã€äº”段链条与各自的验证手段（含失败模式）

### L0 æºæ–‡ä»¶ â†’ åº“
- **参照**：源文件本身。
- **手段**：行数（`import_batch` çš„ total/success/fail vs è¡¨å†… `COUNT(*)`）；逐行抽查（每市州 1~2 æ¡ + è¾¹ç•Œï¼šæœ€å¤§ã€æœ€å°ã€ç¼ºæŠ¥å¸‚州）；单位核对（吨 vs ä¸‡å¨ï¼‰ï¼›åˆè®¡å‹¾ç¨½ï¼ˆÎ£17 å¸‚å·ž = æºè¡¨"湖北省"行）。
- **典型失败**：某月漏导；列错位；单位差 10000；重复导入叠加（"某月逐市州值与相邻月完全相同"是重复导入的指纹）。
- **工具**：`_compare_freight.py` é‚£ç±»"文件 vs åº“"脚本；`import_batch`。

### L1 åº“ â†’ å£å¾„值（**最值得投入的一层**）
- **参照**：把口径写成 SQL/脚本**自己算一遍**，不依赖母版、不依赖定稿。
- **手段**：① å¼‚常体检 `GET /api/report/summaryWorkbook/freightCheck?period=YYYY-MM`（倒减为负、①漏报、Σ市州≠省行、环比异常、累计勾稽）；② **缺数清单**（目标期该有的月份/市州是否齐全）；③ é”šç‚¹å¤ç®—（全省 + æŠ½ 2 ä¸ªå¸‚州；覆盖 è§„上/规下/合计/周转量/中口径四维/城市内）。
- **典型失败**：规下倒减为负或虚高；全省行与 Î£å¸‚州不闭合；来源表缺期。
- **注意**：**体检通过 â‰  æ•°æ®é½å…¨**。2026-08 ä½“检 0 å‘½ä¸­ï¼Œä½† 9 æœˆç”Ÿæˆä»¶çš„ 8 æœˆåˆ—仍空、9 æœˆå‘¨è½¬é‡ä»ä¸º 0 â†’ å¼‚常清单与缺数清单必须**分开输出**。

### L2 å£å¾„值 â†’ å•å…ƒæ ¼ï¼ˆå†™å›žå±‚）
- **参照**：上一期母版 / ä¸Šä¸€æœŸç”Ÿæˆä»¶ã€‚
- **手段**：逐格 diff，**值模式与公式模式各跑一遍**；目标月列是否真的写进去了；上期及以前列是否 0 å˜åŒ–。
- **典型失败**：当月列没写（本次实证：货运、网约车只回填"目标月"，母版缺上月就补不上）；上期列被重算冲掉；公式断链。

### L3 å•å…ƒæ ¼ â†’ æ•´æœ¬ï¼ˆå‡ºè¡¨å±‚）
- **参照**：手工定稿（**必须记录版本 + sha256**，只在定稿未滞后时有效）。
- **手段**：`python docs\工具\汇总大表差异比对.py <生成件> <手工定稿> <输出前缀>`；只判读 **实质数值差异 / éœ€å¤„理(非数值文本)** ä¸¤ç±»ï¼›å·®å¼‚按预登记白名单分类。
- **典型失败**：把"定稿滞后"当成"程序回归"（本次：定稿是 9/13 ç‰ˆï¼Œç¼º 09-28 ä¹‹åŽçš„手工改动 â†’ å¤šå‡º 364 æ¡æ‰‹å·¥ä¾§é”™è¯¯å€¼ + 10 æ¡å·²ç¡®è®¤é¡¹ï¼‰ã€‚

### L4 è·¨é¡µåˆæˆé¡µå‹¾ç¨½ï¼ˆ**最容易被漏**）
- **参照**：勾稽式本身。
- **手段**：`城市汇总`、`城市分市州`、`中口径明细`、`道路运输周转量` æ¯é¡µç»™ä¸€æ¡å‹¾ç¨½å¼è‡ªæ£€ï¼Œä¾‹ï¼šé“路运输周转量 `B = G（货运页规上+规下周转量） + L/2（城市客运量） + Q/10（公路旅客周转量）`。
- **典型失败**：源页都对、合成页引用错列。本次 2025-03/04 ç½‘约车拆分的影响面，就是靠"排名页 vs æ˜Žç»†é¡µä¸¤æ¡é“¾è·¯å¯¹ä¸ä¸Š"暴露的。

## ä¸‰ã€ååŒæºç›²åŒºï¼ˆ**最重要的一条**）

今日实证：**"生成件 vs æ‰‹å·¥å®šç¨¿"这一层，在母版与定稿同源时，源数据本身的错永远查不出来。**
- 2025-11 è´§è¿å®œæ˜Œå‘¨è½¬é‡å·® 34.30（2 æ ¼ï¼‰ã€ç­çº¿åŒ…车个体周转量差（5 æ ¼ï¼‰ï¼Œåœ¨"生成件 vs å®šç¨¿"里是 **0 æ¡**，只有"**库现算 vs æ¯ç‰ˆç¼“å­˜**"才暴露。
- æ‰€ä»¥ï¼š**必须专门做一次"库内值 vs æ¯ç‰ˆç¼“存值"的全量 diff**——这也正是 2026-10-09 äº¤æŽ¥åˆ—为"需先做"的待办，是"能不能切读库"的唯一前置条件。
- æŽªè¾žè¦åˆ†æ¸…：**出表口径**上"库不能替代母版缓存"（F8/Q1）；**验证方法**上必须专门比一次。两者不矛盾。

## å››ã€æ“ä½œé¡ºåºï¼ˆç…§æŠ„即可）

1. **冻结**：记 æ¯ç‰ˆ sha256、关键源表 `max(report_period)` ä¸Žè¡Œæ•°ã€åŽç«¯è¿›ç¨‹ PID + å¯åŠ¨æ—¶é—´ã€‚
   ï¼ˆ"判断是否换了新进程"必须看 `netstat -ano` çš„真实监听 PID + æ—¥å¿—启动行，不能只信启停脚本输出。）
2. å¼‚常体检 + ç¼ºæ•°æ¸…单（**分两份输出**）。
3. å£å¾„复算锚点（全省 + 2 å¸‚州；至少覆盖 è§„上/规下/合计/周转量/中口径/城市内）。
4. ç‰ˆå¼è‡ªæ£€ï¼šå½“月列已写；上期及以前列 0 å˜åŒ–ï¼›`#REF!` æ•°ä¸å¢žï¼›æ ‡é¢˜æœŸæ¬¡ = ç›®æ ‡æœŸï¼›ç´¯è®¡ = 1..M。
5. ä¸Žå®šç¨¿é€æ ¼ diff（只看两类）；差异按白名单分类。
6. åˆæˆé¡µå‹¾ç¨½ï¼ˆL4）。
7. å†™ç»“论：通过项 / æœªé€šè¿‡é¡¹ / **未覆盖项**（明确说清哪几层没验）。

## äº”、通过标准（建议写死）

- **L0**：行数与勾稽一致（0 å·®å¼‚）。
- **L1**：体检 0 å‘½ä¸­ + ç¼ºæ•°æ¸…单为空（或缺数已确认为业务事实）+ é”šç‚¹å¤ç®— 0 å·®å¼‚。
- **L2**：上期及以前列 0 å˜åŒ–；当月列写入格数 = é¢„期。
- **L3**：定稿 diff çš„"实质数值差异"只含白名单项。
- **L4**：勾稽式 0 å·®å¼‚。
- **任一层未覆盖 â†’ ç»“论只能写"未覆盖"，不得写"已验证"。**

## å…­ã€ä¸‰æ¡çºªå¾‹

1. **独立参照**：同源的两种产物互比等于没验。
2. **一次只换一个变量**：换代码 / æ¢æ•°æ® / æ¢æ¯ç‰ˆåˆ†å¼€éªŒï¼Œå¦åˆ™å·®å¼‚无法归因。
3. **差异先分类再结论**：结构/格式/浮点尾差只计数；只有"实质数值差异 + éœ€å¤„理"进清单。白名单（`USER_EDITS`、已确认项）预登记，不要每次重新判读。

## ä¸ƒã€æœ¬æ–¹æ³•çš„实证（2026-10-12）

1. **2026-08 ç”Ÿæˆä»¶ vs 9/13 æ‰‹å·¥å®šç¨¿**：1020 æ¡æ˜Žç»†é‡Œåªæœ‰ 11 æ¡è¦å…³æ³¨ï¼ˆ10 æ¡è´§è¿ 2022 ç´¯è®¡åŒæ¯”【业务已确认软件对】+ 1 æ¡æ‰‹å·¥ä¾§è„å­—符），其余全是约定差异（结构/草稿列/文本型数字 354/取整尾差/手工侧错误值 364）→ **算法层通过**。
2. **库内 2025 vs æ¯ç‰ˆ 2025**：公交、出租、轨道轮渡 **100% ä¸€è‡´**；货运、班线包车除个别格一致；查出 3 å¤„需业务确认：
   - ç½‘约车 2025-03/04「其中城市内」口径 60 æ ¼ï¼ˆå¦æœ‰ 12 æœˆ 12 æ ¼å°å·®ï¼‰â€”—2026-09-21 å·²å®šä½ï¼ˆæ¯ç‰ˆç”¨äº†å¦ä¸€ä»½æ—§çš„出租城市内输入）；
   - è´§è¿ å®œæ˜Œ 2025-11 å‘¨è½¬é‡ 2 æ ¼ï¼ˆå·® 34.30）；
   - ç­çº¿åŒ…车 2025-11 ä¸ªä½“旅客周转量 5 æ ¼ã€‚
   åŽä¸¤å¤„为**源数据层新发现**，此前无任何记录（因为历史核对都在同源的"生成件 vs å®šç¨¿"层）。