docs(比对口径): 差异清单口径固化——货运新增行/U列草稿/无表头列/浮点尾差/排名表当月块/市州短名均按设计忽略；清单转本地不入库；HANDO...

zhizhijie

3 天以前 42e76278d347714fa27b5195bd3e5e15817d8c92

 HANDOFF.md

@@ -4,7 +4,211 @@
> **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。
> **协作约定（2026-08-31）**：说「提交」= 本地 commit + 推送到远端 git（origin main，Gitblit），不再只做本地 commit。

## 今日（2026-08-28）
## 最新（2026-09-28）

- **用户用 WPS 编辑母版**：改《班线包车》边框、《道路运输周转量》字号，并删除《中口径明细》`AW` 列（手工定稿同删）。已验证生成端正常：中口径明细 2024 及更早块整体左移（跨页/同页公式自动改引用，`#REF!` 2→0）、中口径排名块 J..R → A..I 均正确带入产物。
- **⚠️ WPS 保存的连带损坏（待回补）**：《班线包车》2019/2020 块约 **590 格**内容丢失（`FN/FO/FM`、`FP:FT`、`GE` 变空；`EO/EQ/ES/EU/EW/EY/DT/DW...EM` 共 **144 格**变 `#DIV/0!`）。生成件已带出（该页 `#DIV/0!` 228→372）。**待用户确认后按备份/定稿回补（只补值与公式，保留其边框与字号）。**
- **口径落地「缺数留空」**：母版《 货运》行 90/93（仙桃 规上两行）、108/111（林区）在 2021、2022 年块的 78 个 `0` 值已清空（与手工定稿按表头对齐逐格核对：母版=0 且定稿=空 78 格、冲突 0 格）；代码 `FreightCalc.buildMetrics` 当月分支改为「该月无规上记录 → 留空」，不再写 0（累计分支不变）。
- **纠正一条错判**：此前「程序少一列 11 月环比」不成立——生成件与手工定稿的环比期间集合完全一致（12月…1月 共 12 列）；差异根因是手工定稿《 货运》在 2025 年块多一列**无表头辅助列**（`U`，74 格），自该列起手工整体右移 1 列。**比对必须按表头期间对齐，不能按列位置比。**
- **验证**：生成两次（约 15 秒/次），第二次相对第一次**仅 78 格 0→空**，错误值数量不变；`公交!S5=98460.97` 等缓存值抽查保留。
- **运行状态**：后端已按 `start-dev.ps1` 重启（新 PID，8090/8080 在跑）；本机库仍为 `localhost:3308/traffic_audit`。
- **✅ 班线包车回补完成（09-28 下午）**：用户确认后按 09-27 母版备份（`_bak_202608母版文本数字转数值前_20260927.xlsx`）XML 精准回补《班线包车》2019/2020 块 —— **该页与 09-27 母版逐格一致（0 差异）**，错误值回到 `#REF!` 8 / `#DIV/0!` 228；母版其它页未受影响。验收生成：与 09-27 生成件 (6) 比对错误值逐页一致，差异仅剩既定改动（` 货运` 78 格清 0、中口径明细 4915 格删列位移、中口径排名 672 格块位移、班线包车 82 格浮点尾差/0-空）。
- **差异清单口径更新（09-28，用户确认）**：① ` 货运` 新增的「规上+规下货运量」「规下货运量」各 17 行（母版设计，共 34 行）不计差异；② ` 货运!U5:U112` 无表头草稿列不计；③ 排名表「当月块」为母版设计不计；④ 市州短名/全名不影响（工具归一化）；⑤ 小差异（取整尾差/文本型数字）只计数，只列差异大的并附原因。工具 `docs/工具/汇总大表差异比对.py` 已按此更新，两份清单已重生成。
- **新发现（待核对）**：`班线包车!EO36/FN36/FO36`（荆门 客运量 2020 累计/累计同比）**程序生成时重算为 -2731.41 / -1.0008 / -1.0002**，而母版与手工定稿均为 0.181777 / 2312.2199 / -0.586419 → 疑母版 2020 年块分母为 0，需核对公式与数据。
- **汇总大表差异比对（09-28，工具已固化口径）**：`docs/工具/汇总大表差异比对.py`（逐页按行/列标签序列对齐，可处理多列/多行/重复表头）。**清单属过程产物只留本地**（`docs/问题汇总/_清单_*.md/.csv`，已 gitignore 不入库）。
  - 已确认口径（不再重复确认/上报）：① 货运每市州 6 行 vs 手工 4 行（新增「规上+规下货运量」「规下货运量」各 17 行）属母版设计，行号偏移按"地区+指标"对齐后一致；② ` 货运` U 列（U2:U118）为人工草稿；③ 仅手工有且**无表头**的列 = 草稿；④ 浮点尾差、文本型数字忽略；⑤ 排名表「当月块」为母版设计；⑥ 市州短名/全名不影响。
  - **需处理（数值）**：`班线包车!EO36/FN36/FO36`（荆门 客运量 2020 累计/累计同比）——程序生成时重算为 -2731.41 / -1.0008 / -1.0002，母版与手工定稿均为 0.181777 / 2312.2199 / -0.586419（疑母版 2020 年块分母为 0），待核对；` 货运` 2022 年各市州「累计同比」10 条（业务已确认**软件对**，不改）。
  - 其余待办：手工侧 4 处脏数据（`班线包车!IL4/IL5` 断链、`IL50` 反引号、` 货运!EA93/EA111` 的 `#DIV/0!`）、286 格文本型数字、304 格草稿列；母版 11 个 `#REF!` + 356 个 `#DIV/0!`；`城市客运` 第 2 行第 3 个月起表头为日期序列号；缺 2026-09 母版；导出前基数体检（P0-3）。
- **待办**：① 排名页结构（块顺序、标题措辞、市州名短名/全名、周转量排名多 7 行）；② 排名页结构（块顺序、标题措辞、市州名短名/全名、周转量排名多 7 行）；③ 缺 2026-09 母版、导出前基数体检（P0-3）。

## 最新（2026-09-27）

- **提交规范改为同事方式（用户 09-27 决定，已写入 AGENTS.md）**：
  1. 《功能测试报告》《工作日结》改为**本地写、不入库**（`docs/功能测试报告/`、`docs/工作日结/` 已 gitignore，本次 109 个文件移出仓库、本地文件全部保留；其中《模块功能验证状态矩阵_2026-09-02》属团队共享信息，已移到 `docs/` 根目录继续入库）；
  2. **入库的是结论**：关键结论/口径/风险/待办写进本文件（`HANDOFF.md`）或 `docs/交接文档_*.md`、`docs/问题汇总/`，与该次代码改动放在同一条提交；
  3. 提交粒度与 message：一条提交一个改动（代码+相关文档），前缀 `feat(模块):` / `fix(模块):` / `docs:` / `docs(交接):`；禁止入库临时脚本/调试产物/构建产物/密钥/大体积 sql。
  > 参考数据：同事 xyc 55 次提交中 37 次更新本文件、功能测试报告仅 4 次、日结 7 次；此前我方 144 次提交里含 102 份报告 + 106 份日结。
- **打包去密（根因已修）**：旧部署包的 jar 内置 `BOOT-INF/classes/application.yml` 带着**真实密钥与库口令**（外层 application.yml 干净、运行时以外部为准，但 jar 可解压明文可见；且 zip 压缩导致直接 grep 搜不到）。
  现已改为：**进 jar 的配置只有占位符**（`${TRAFFIC_DB_*}`、`${DEEPSEEK_API_KEY:}`、`${TRAFFIC_JWT_SECRET:...}`）；本机真实值走 **Windows 用户环境变量**（`TRAFFIC_DB_PASSWORD` / `DEEPSEEK_API_KEY`），`start-dev.ps1` 增加了从注册表补齐的兜底。
- **新增脚本（已入库）**：`pack-deploy.ps1`（一键打包：构建 → **解压 jar 去密自检，命中真实密钥/明文口令即中止** → 重建前端 → 组装部署包到 `E:\试验\traffic-audit-deploy-<yyyyMMdd>`）、`set-secrets.ps1`（轮换后交互式更新本机环境变量）、`deploy-templates/`（打包模板入库：外部 application.yml、启动脚本、nginx 示例、db 建表 sql、部署 README——原先只在未跟踪的旧包里，删包即丢）。
- **清理旧部署件（用户确认后执行）**：删除 `E:\试验\traffic-audit-deploy-20260913`（目录 + **69.9 MB 的 zip**）、`deploy\traffic-audit-deploy-20260913`、`_deploytest`、空 `out`/`deploy`；旧 `target` jar 由 `mvn clean` 覆盖。全盘复查（仓库 + `E:\试验`）：**已无任何含明文 key 的 jar / 压缩包 / 文本文件**。
- **干净新包已产出**：`E:\试验\traffic-audit-deploy-20260927`（336 文件 / 96 MB，前端含最新「按市州汇总」；jar 内置配置全占位符）。
- **运行状态（09-27 实测）**：dev 后端 `8090`、前端 `8080` 在运行；**本机数据库为 MySQL80 `localhost:3308/traffic_audit`（root/口令走环境变量）**——注意 `docs/交接文档_2026-09-23.md` 写的 `3305` 是**同事机器**的配置，本机没有 3305，别再照抄。
- **待办（接手优先）**：
  1. **【需用户】轮换已泄露的 DeepSeek key**（控制台新建 + 删旧 → 跑 `set-secrets.ps1`）；
  2. **【需用户】服务器换包**：删旧包/zip → 拷 `traffic-audit-deploy-20260927` → 改 `backend\application.yml` 数据库三处（需要 AI 分析再填 `deepseek.api-key`）→ `start-backend.cmd`；
  3. P0 三项不变：P0-2 亿元投资项目按 Q7 按月追列、P0-3 导出前基数体检 +《数据缺失清单》页、P0-4 缺 2026-06/09 母版；
  3.1 **汇总大表现状复核（2026-09-27 实测，母版 `docs/生成汇总大表/2026年8月道路运输量汇总表.xlsx` + 最近生成件）**：
      - **累计列公式没覆盖到当期（实测 306 格）未落实**，确切位置（母版 `docs/生成汇总大表/2026年8月道路运输量汇总表.xlsx`）：
        · `公交!U5:U76`、`出租!U5:U76`、`网约车!U5:U76` 各 72 格 = 216 格，公式 `=V5+X5+Z5+AB5+AD5+AF5`（只累加 2025 年 1~6 月；U 列表头为空，位置在"2025年1月"块左侧，对应 2026 块的 `S` 列"2026年累计"，语义即"2025 年累计"）；
        · `城市客运!U4:U39` 36 格（同模式，只 6 个月）；`班线包车!DU4:DU57` 54 格（`DU2` 表头直接写"1-3月累计"，只 3 个月——属版式未随月份扩展）。
        → 业务口径为"可清空留空"；**生成件与母版逐格相同**（证实程序只补当期列、不碰历史列）。09-22 差异报告按另一分页口径统计为"304 格（含中口径明细 88 格）"，本次按公式模式定位到的是上述 306 格，两者为同一类问题、分页归类不同。
      - **2026-09-27 已处置：母版里的"人工核算草稿累计列"整体清空**（用户确认"这一列都可以留空，是人工核算时弄的草稿"）。清空范围共 **577 格**：`公交/出租/网约车!U5:U76`、`城市客运!U4:U39`、`班线包车!DU4:DU57`（含表头 `DU2`"1-3月累计"）、`中口径明细!U99:U188`、`中口径客运量!AB5:AB188`。
        · 依据：这些列在整本工作簿里**没有任何公式引用**（全簿扫描 0 命中），且程序**不写它们**（生成件与母版逐格相同）→ **只改母版即可，无需改代码**。
        · 做法：直接改 xlsx 内部 XML（只去对应单元格的 `<f>/<v>`、保留样式），**避免 openpyxl 保存导致全簿公式缓存值丢失**（该坑已实测复现：用 openpyxl 存一次后 `公交!S5` 由 98460.97 变 None，会破坏"中口径排名用母版 2025 静态列"）。
        · 验证：重新生成 2026-08（母版变更使缓存自动失效，`staleCache=true`）→ 新旧生成件逐格比对：**仅这 577 格变为空，19 页签与尺寸不变，其它一律不动**；依赖母版缓存值的口径（中口径排名 M3、道路运输周转量 G4、货运量排名 B4、城市汇总 B3、公交 S5/Q5、中口径明细 C99、班线包车 Q4）**全部一致**。
        · 备份（本地保留、不入库）：`docs/生成汇总大表/_bak_202608母版清空草稿累计列前_20260927.xlsx`；新生成件已存 `D:\桌面\生成数据\生成_道路运输量汇总表_2026-08 (4).xlsx`。
        · **表头措辞修复（按人工定稿为准）**：`轨道、轮渡!R2`、`R11` 由母版自带的"8月与去年同比"改为"同比"（与该页 `T2/T11`"累计同比"体例一致、与手工定稿一致；程序不写这两格，故只改母版）。
          验证：重新生成 2026-08 → 新旧生成件逐格比对 **仅这 2 格文字变化，19 页签与尺寸不变、其它一律不动**。
        · **判定为"程序正确、不改"的两处**：① `道路运输周转量!A23` 程序"2026年8月全省完成交通周转量情况"（该块是**当月值**：全省 2,301,720 vs 累计块 17,749,657 万吨公里）→ 手工定稿多写了"累计"；② ` 货运!EA92:EA112` 2022 年累计同比 10 条（业务已确认软件口径正确）。
        · **文本型数字统一为数值（用户口径"按程序对的改"）**：母版 157 格文本型数字 → 数值（`公交` 153 = AF 68 + M 68 + G 17；`轨道、轮渡` 4 = M 2 + E 2），仍用 XML 精准改类型（缓存值全部保留）。重新生成 2026-08 → 与上一版比对：**仅 68 格类型变化（str→数值、数值相同），无任何值/尺寸变化**（其余 89 格程序本就会写数值）。注：比对里另有 286 条"文本型数字"差异在**手工定稿侧**（手工存文本），需手工侧统一或忽略。
        · **排名页"两个块顺序对调"（实为顺序问题，不是多了一张表）**：程序 以模板 `docs/货运/生成_货运量排名.xlsx`（模板本身=累计块在行1、当月块在行23）填充 → `货运量排名` 程序=行1累计/行22当月，手工=行1当月（"2026年8月各市州货运量排名"）/行22累计；`货运周转量排名` 程序 44×18（累计在前）vs 手工 51×18（当月在前、且多 7 行待细看）。**用户口径：手工为准** → 需改模板（两块对调）+ 相应代码（块定位/标题写法 `ReportExportService:961-966/1315/1575-1583`）+ 市州名由 `RegionUtil.shortName()` 改全名；估 0.5~1 天含回归，待开工。
        · **手工多出的"辅助列"清单**：` 货运` 多 1 列（无表头，位于"同比"之后、2025 年 1 月之前 → 实为 `U` 列"2025 年 1-8 月累计"辅助列，74 格，从 V 列起手工整体右移）；`城市客运` 多 `AJ`="2025年1-7月累计"（母版 09-20 已删、程序已不输出）；`班线包车` 多 `DU`="1-3月累计"（即本次清空的草稿列）；`道路运输周转量` 末尾多 2 列（Z/AA，**表头与内容均为空**）。
        · 取整尾差 194 条：用户明确"不用管"。

        · **仍待业务定的版式/措辞项**：`货运量排名`/`货运周转量排名` 的标题、表头（程序"累计完成(万吨)" vs 手工"规上货运量(万吨）"）与市州名（程序按设计用短名"武汉/恩施/林区"、手工用"武汉市"等全名）——需业务确认以哪版为准。

        · ⚠ **待同事确认**：手工定稿侧也把这些草稿列留空，否则比对会从"程序有值/手工有值"变成"程序空/手工有值"（同类差异、方向相反）。

        · **清空的 7 列对照表（供同事复核；引用数为清空前的全簿扫描）**：

        | 页签 | 列 / 范围 | 清空格数 | 原表头 | 公式语义 | 清空前缓存值（首行样例） | 同页引用 | 跨页引用 |
        | --- | --- | ---: | --- | --- | --- | ---: | ---: |
        | 公交 | `U`（U5:U76） | 72 | （无表头） | `=V5+X5+Z5+AB5+AD5+AF5` → 2025 年 1~6 月累计 | 88908.91 | 0 | 0 |
        | 出租 | `U`（U5:U76） | 72 | （无表头） | `=V5+X5+Z5+AB5+AD5+AF5` → 2025 年 1~6 月累计 | 39797.94 | 0 | 0 |
        | 网约车 | `U`（U5:U76） | 72 | （无表头） | `=V5+X5+Z5+AB5+AD5+AF5` → 2025 年 1~6 月累计 | 16384.07 | 0 | 0 |
        | 城市客运 | `U`（U4:U39） | 36 | （无表头） | `=V4+X4+Z4+AB4+AD4+AF4` → 2025 年 1~6 月累计 | 206639.67 | 0 | 0 |
        | 班线包车 | `DU`（DU4:DU57） | 54 | 1-3月累计 | `=DO4+DQ4+DS4` → 1~3 月累计 | 5566.8922 | 0 | 0 |
        | 中口径明细 | `U`（U99:U188） | 90 | （无表头） | `=V99+X99+Z99+AB99+AD99+AF99+AH99` → 2025 年 1~7 月累计 | 1102278.385724 | 0 | 0 |
        | 中口径客运量 | `AB`（AB5:AB188） | 184 | （无表头） | `=AC5+AE5` → 2024 年 1~2 月累计 | 6088.1871 | 0 | 0 |

        · **⚠ 同名列别清错（反例对照）**：`中口径明细!AB3 = "2025年4月"` 是**正常月份列**，被 **700+ 处同页 + 34 处跨页公式引用**（例如 `中口径明细!J5 = I5/AB5-1` 2026 年 4 月同比、`T5 = S5/SUM(V5,X5,Z5,AB5,…)-1` 累计同比、`AT5 = X5+V5+Z5+AB5+…` 2025 累计、`中口径客运量!I11 = 中口径明细!AB11`），**本次未动、也不能清**。判据：该列**有表头**、**被引用数远大于 0**、公式语义是"被别的格引用"而不是引用其它月份列。

      - **生成件里错误值 356 个 `#DIV/0!` + 13 个 `#REF!`**：班线包车 228+8、中口径明细 64+2、货运 38+3、中口径客运量 26；业务口径未定（是否清成空白）。
      - **城市客运页表头仍是日期序列号（确证未修）**：母版与生成件第 2 行第 3 个月起均为序列号（G2=46082、I2=46113…），1、2 月是文字；`fixCityMonthHeaderText()` 未覆盖该页 → "按表头文字匹配列"方案在该页失效。（此前文档标"待核实"，现已确证。）
      - 缺 2026-09 母版（目录仅 7 月/8 月/版式原型 + 2 个 `_bak_*`）→ 9 月出表会 `ready=false`，需拍板方案 A（程序扩列）/ B（Excel 小工具）。
  4. 汇总大表 304 格「2025 累计列少加 7、8 月」清空（业务已确认口径，待执行）；
  5. 本机历史临时目录待清（`outputs/` 41MB、`_shots/`、`_test_check*`、`_test_passenger`、`.tmp_*`、`_tmp_codexhome`）；`_给同事_2026-09-21/`（52MB 全库备份）属交付件，未动。

## 最新（2026-09-23）

- **已同步**：本地 `main` 快进合并公司 `origin/main` 最新 `8b739ce`（同事 09-22 关机快照统一版），合并后 `HEAD = 8b739ce = origin/main`，工作区干净。
- **本次新增交接文档**：`docs/交接文档_2026-09-23.md`（09-23 增量：现状快照 + 腾讯文档读取调研 + 当前待办 + 文件索引）。系统全景与 P0/P1/P2 全量遗留仍以 `docs/交接文档_2026-09-21.md` 为准。
- **今日工作**：腾讯文档读取调研 + 潜江物流投资月报重导修正；无业务代码改动（见 `docs/工作日结/工作日结_2026-09-23.md`）。
- **潜江重导（已完成）**：潜江物流 2026-06/07/08 在应用实际库 `3305` 均改为“中国虾谷冷链仓储物流园” `11947.9 / 0 / 1135 / 0`；重复重导保持每月 1 条、无重名项目，2026-08 导出端到端核对通过。09-22 报告记录的验证库是 `3308`，与当前应用连接库不一致，故当前库 08 月旧值本次一并修正。报告 `docs/功能测试报告/功能测试报告_潜江投资物流月报重导_2026-09-23.md`。
- **腾讯文档读取调研（新结论）**：
  1. 只读分享链接（《2026年十一数据》，10 页签）**能读显示值** —— 浏览器「打印 → 整个工作簿 → 打印预览」渲染成 SVG 段，读 `<text>` 即得数值/日期/百分比/`#DIV/0!`；但读不到公式、隐藏行列、打印范围外内容，且不易恢复精确 A1 坐标。
  2. **trafficAudit 目前不支持**在线文档导入，只走本地文件上传（`DataImport.vue:57/502` → `DataImportController.java:33` → Apache POI）。
  3. **腾讯官方 Open API V3 可行**：`GET /openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}`（A1 范围，返回 `cellValue`），但需 OAuth 2.0 + 应用凭证 + `scope.sheet(.readonly)`；仅凭分享链接不能匿名调用。落产品建议走官方 API，不用打印预览。详见 `docs/交接文档_2026-09-23.md` §3。
- **运行状态（09-23 08:50 续接实测）**：dev 后端 `8090`、前端 `8080` 已启动并就绪，应用数据库 `localhost:3305/traffic_audit`。启动命令：`powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`（沙箱外）。
- **接手优先（更新）**：投资明细表 L/D/E/F 覆盖口径、武汉物流/黄冈客运 8 月源数据、未覆盖清单落文件；汇总大表 304 格「2025 累计列」；P0-2 亿元表按 Q7 追列、P0-3 导出前基数体检、P0-4 2026-09 母版。

## 最新（2026-09-22）

- **已同步**：本地 `main` 已合并公司 `origin/main` 最新 `db0ee92`（含投资明细取数/导入修复）；合并后 `mvn -q -DskipTests compile` 通过。
- **Codex 输入卡顿复核（已完成）**：电脑与 Codex 于 09-22 12:54 重启后，`Codex++` 修复脚本仍启用；主渲染进程空闲 CPU 约 13.3%（单核），调试守卫 `installed=true`、本次会话 `dropped=16`。对比修复前约 115%，卡顿问题已解决。
- **今日已完成（远端提交）**：数据查看补齐网约车/个体客运、按市州汇总与导出 Excel、汇总大表进度弹窗与结果落盘缓存。
- **汇总大表差异复核（2026-09-22）**：软件输出与手工定稿经 Excel 全量重算后逐格比对，930 条差异中实质数值差异 314 条；其中 304 条为 2025 累计列少加 7、8 月（业务已确认可清空），10 条 ` 货运` 历史同比业务已确认软件正确。报告见 `docs/问题汇总/汇总大表_软件输出与手工定稿差异清单_2026-08_20260922.md`，明细见同名目录 CSV。
- **未完成重点不变**：P0-2《亿元投资项目》按 Q7 追列、P0-3 导出前基数体检、P0-4 2026-09 母版；其余见 `docs/交接文档_2026-09-21.md` 第 4 章。

### 补充（2026-09-22 下午，投资取数修复第一轮）

- **已修（代码 + 重导 + 回归）**：① 导出去标点归一化匹配（荆州）；② 同名双档优先取当月有数据的档（十堰快递产业园二期）；③ 未覆盖行逐行 WARN 留痕；④ 导入表头去换行（天门 H/J/K 不再丢）；⑤ 导入按表内报表期选 sheet（**潜江不再把 2018 年数据当 2026-08**）。
- **结果**：2026-08 物流/客运明细逐格差异 **156 → 129**，无新增差异；未覆盖清单已能自动列出（物流武汉 6 行；客运黄石1/黄冈9/恩施1/仙桃1）。
- **遗留（下一轮）**：L/D/E/F 覆盖口径（需《建设阶段归一表》）、武汉物流与黄冈客运 8 月源数据、潜江 2026-06/07 历史错值重导、未覆盖清单出文件/页面提示（P1-9）。
- **报告**：`docs/功能测试报告/功能测试报告_投资明细表取数修复_2026-09-22.md`。

### 补充（2026-09-22 下午，投资明细表比对）

- **已完成**：软件《客运站投资明细表》《物流站场投资明细》与人工版逐格比对（156 格差异），报告 `docs/功能测试报告/数据比对报告_投资明细表软件生成与人工版_2026-09-22.md`。
- **捞出 3 类「会静默出数」的问题**（都指向取数而非算术）：
  1. 导出用底稿模板 + **按项目名匹配**库内当月数，匹配不上/库内无当月数就沿用上期值 —— 武汉物流（库内 0 条月度记录）整段保留 7 月值；荆州「中国供销公安商贸物流园」因库内名多一个点未覆盖。
  2. 库内**同名双档**：十堰「快递物流产业园二期」`id=154`(竣工2026)/`id=181`(竣工2029) 并存，导出取到旧档。
  3. **导入丢数**：天门「天门市物流中心建设项目」库内 2026-08 累计/自年初/本月全为 0，源文件是 16677.7/16677.7/500（**P1-5 原记录「源文件 H/J/K 列为空」与现文件不符，需更正**）。
- **另**：导出不覆盖 L（建设阶段）列、单渠道市州的分组小计行填法、0/空白写法差异，均已在报告第五节给出处置建议。

### 补充（2026-09-22 下午，另一会话收尾）

- **本会话已完成**（已推送）：汇总大表进度弹窗优化（完成后不再出现重复下载按钮）；导出结果**落盘缓存**（`docs/生成汇总大表/_cache/`，已 gitignore）；
  缓存守卫升级为**数据指纹**（依赖源表 `CHECKSUM TABLE` + 母版等文件身份，排除投资/能耗/审核/系统/导入日志）——无关导入不再失效、**换母版必定失效**，失效时进度弹窗给出说明。
- **当前环境**：后端 8090、前端 8080 运行中；导出缓存对 2026-08 有效（文件名带指纹）；最新提交 `06b1cb7`。
- **剩余待办（已逐条核查，同事未触碰）**：P0-2 亿元表按 Q7 追列（`ReportExportService.java:6251` 仍写同一格）、P0-3 基数体检（`getLastMidIssues()` 无调用方）、
  P0-4 2026-06/09 母版缺失、P1-7 投资资金渠道字段、P1-9 投资导出按月分目录 + 运行日志、P2-1 D 组增速排名措辞。
- **待核实**：`docs/交接文档_2026-09-21.md` 的 P2-2「城市客运页表头仍是日期序列号」可能过时——代码已有 `fixCityMonthHeaderText()`（09-03 加入），
  建议跑一次 2026-08 导出核对后再改文档。
- **入口**：`HANDOFF.md`（本文件）→ `AGENTS.md` → `docs/交接文档_2026-09-21.md` 第 4 章（P0/P1/P2 全量遗留）。

### 关机交接快照（2026-09-22 晚）

- **今日交付（两项，均已推送）**：
  1. 《投资明细表 软件生成 vs 人工版》逐格比对（156 格差异）+ 根因定位 —— `docs/功能测试报告/数据比对报告_投资明细表软件生成与人工版_2026-09-22.md`；
  2. 第一轮取数修复（导出 3 处 + 导入 2 处，含新发现的"潜江导入 2018 年历史 sheet"）—— `docs/功能测试报告/功能测试报告_投资明细表取数修复_2026-09-22.md`；回归后逐格差异 **156 → 129**，无新增差异。
- **git**：`main` = `db0ee92`，已同步公司 `origin/main`（已合并同事 `13c2d36` 汇总大表差异复核）。工作区干净；仅本地未跟踪的临时产物（`_tmp_diff_tables_0922.md`、`_tmp/gen_new_0922/`、`_tmp_*_0922.*`）和用户自己的 `docs/确认.docx` 未入库。
- **运行状态（17:2x 实测）**：dev 后端 `8090`、前端 `8080` **均在运行**（HTTP 200；后端为本次修复后的构建，16:43 经 `start-dev.ps1` 重启）；关机后自然停止、不需手工处理。数据库 `3308`（本项目）与 `3305/3306` 按惯例保留，数据已持久化。
- **下次启动**：项目根目录 `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`（脚本会跳过已在跑的端口；前后端需在沙箱外运行）。
- **保留产物（未经确认不删）**：汇总大表 930 条差异报告/CSV、投资比对与修复报告、`_tmp*_0922.*`、`_tmp/gen_new_0922/`。
- **本轮数据变更**：仅重导修正 `investment_monthly` 天门、潜江 2026-08 两处数值，未删除任何项目主档、未动其他市州/期间。
- **接手优先（明日）**：
  1. L/D/E/F 列覆盖口径（需先确认《建设阶段归一表》：源表 主体施工/竣工收尾/未开工/本年正式施工/暂停施工/前期 → 输出用词）；
  2. 补源数据：武汉物流 8 月无单表、黄冈客运 8 月无源文件（导出已能自动告警，共 15 行受影响）；
  3. 潜江 2026-06 / 2026-07 月度仍是 2018 历史 sheet 错值，**用 6/7 月源表**重导（不要用 8 月文件重导）；
  4. 「未覆盖行清单」目前只进 `backend.log`，按 P1-9 可再做成《校验报错_<年月>.xlsx》或页面提示；
  5. 既有 P0/P1 不变（亿元表按 Q7 追列、导出前基数体检、2026-09 母版等，见 `docs/交接文档_2026-09-21.md` 第 4 章）。

## 最新（2026-09-21）

- **最新总入口**：`docs/交接文档_2026-09-21.md`（系统现状、P0/P1/P2 遗留、操作手册）；汇总大表专项见 `docs/问题汇总/汇总大表问题交接_2026-09-21.md`。
- **本日完成**：
  1. 拉取并合并 origin/main 最新提交（含投资系统新模板、十堰源文件清理、汇总大表异步导出等）。
  2. 处理“中口径排名 vs 中口径明细”历史同比基数双轨制：用户采用**方案 A**，排名页累计同比基数改读母版《中口径明细》的 2025 静态列。
     - 黄冈 2026 年 1-8 月客运量累计同比由 `7.744917%` 修正为 `7.641733%`；
     - 17 市州 × 客运量/周转量累计值与同比 68 个数值对全部一致（最大差 `2.91e-11`）；
     - 8 月当月同比 34 个数值对无回归（最大差 `5.48e-15`）；
     - 见《功能测试报告_中口径排名同比基数方案A_2026-09-21.md》。
- **当前环境**：dev 后端 `8090`、前端 `8080` 运行中；数据库 `127.0.0.1:3305/traffic_audit`。
- **未完成重点**：2026-09 母版（人工母版或扩列器）、《亿元投资项目》按 Q7 追列、导出前基数体检 B4、P1/P2 其他事项（详见总交接文档第 4 章）。
- **测试产物**：`_tmp/qa_plan_a_20260921/`（按项目约定保留，未经同意不删）。

## 今日（2026-09-04）

### 13. 关机交接快照（09-04 晚）
- **今日内容**：仅查看 git，无代码改动、无 dev 启动。上午确认同事 573e111（报表新版式/导入校验/I004 保护）；下午确认同事 09-03~09-04 新增 10 个提交，远端最新 `fc2e76b`。**用户决定暂时不拉取**。
- **当前运行状态**：dev 前后端未运行（backend.log/frontend.log 最后写入 09-02，本日未启动）；MySQL80(3305)、MySQL57(3306) 均 Running，按惯例保留。其他项目（intoTrade vite）进程勿动。
- **git**：工作区干净，HEAD=`7d5f0d2`（09-02 关机快照），落后 origin/main **12 个提交**（573e111 + 11 个）。
- **同事新提交概要（fc2e76b 及之前 11 个，未拉）**：规上规下拆分导入识别 N月份 页签补当月行；城市客运新增网约车总数/网约车订单及全省总量两母版导入——**新增库表 wyc_order_monthly / wyc_total_monthly（需先同步数据库结构再测导入）**；汇总工作簿月度块按备份母版还原（1-4月→1-7月试点）+ fullCalcOnLoad；导出不再 autoFit/整数不显 .00/列宽自适应；报表预览显示指标名与单位；货运量合计除万修正；报表新版式（上累计+下当月）与表头列位校验、投资市州多 sheet、I004 整期缺失保护（573e111）。代码改动约：DataImportService +453、ReportExportService +920、新增 Wyc 两表实体/mapper；另有大量 docs（交接文档、口径 SQL、测试报告、拍板记录）。⚠️ 同事提交同时改动项目根 AGENTS.md，拉取时留意覆盖。
- **待办（下次）**：①拉取合并 12 个提交 → 对照 docs 交接文档/口径 SQL → 验证（先补 wyc 两表）→ 询问用户是否打包发布（用户环境已落后较多）；②正式发布前 app.captcha.required 改回 true；③浏览器崩溃如再现查 logs/access.*.log + 客户端 F12；④同事年报功能开发中（我方不动）；⑤态势图/AI RAG/经济指标试算仅记录未实现；⑥每日反思自动化未创建。

## 今日（2026-09-02）

### 11. 2026-09-02：同事提交拉取合并 + 三项改动验证（全部通过）
- **git**：拉取同事 `799ec67`（能耗并发锁+空车牌0过滤+前端防连点）；HEAD=`799ec67`，已同步 origin/main；用户环境仍落后 3 个提交（fbc1c15/91d7eee/799ec67），下次发布前需重新打包。
- **验证环境**：dev 起服（8090/8080 就绪）；真实模板/输入文件经接口导入 + puppeteer(Chrome headless) UI 验证 + 双并发接口实测。
- **通过项**：
  1. `fbc1c15` 投资多文件批量（/api/import/batch 新端点）：6月 3 个真实市州 xls → 成功 10 行（孝感3/恩施6/林区1，市州自动识别）；同文件重复导入 2 次幂等（investment_monthly 2026-06 客运站场恒 35 行不重复）；真实 .et 文件（襄阳市投资.et）成功解析 6 行；前端 accept 含 .et、多文件多选「批量导入」UI 与结果弹窗正常。
  2. `91d7eee` 投资系统导出表头兼容：模板_查询结果(投资系统-客运+物流 2026.7).xls 导入成功 148 条（investment_system 空表实测，表头含 行号/单位/时期/计划总投资）。
  3. `799ec67` 能耗：模板文件（1284 车辆行）导入 2026-08 成功；同报表期双并发导入互斥锁生效（第二请求阻塞约 5s，最终仍 1284 行、无翻倍/残留）；把一行车牌改为 0 的副本导入得 1283（0 车牌过滤生效）；前端 importing 防连点：mock 延迟期间按钮 loading+disabled、连点未产生第二次请求，完成后状态复位、无 JS 报错。
  4. `fbc1c15` 报表生成：/api/report/export/investPlan?period=2026-07 生成成功（178 项目行、无重复名称、模板规范名输出正常）；「瑞海物流园」两行合并场景开发库无对应数据未复现，去重逻辑（usedProjectIds 排除 + displayName 模板名优先）代码级确认。
- **清理**：测试数据已全部恢复——删 2026-08 能耗 1284 行、investment_system 2026-07 148 行、import_batch 测试记录 id 91~102；2026-06 投资经幂等重导与验证前一致（35 行、市州分布相同）；git 工作区干净。
- **临时文件**（保留，在 D:\Codex\_tools\pptr-core\）：_tmp_verify_0902.js（UI 验证脚本）、_tmp_investPlan_202607.xls、_tmp_energy_zero_plate.xlsx。
- **当前状态**：dev 前后端运行中（8090/8080）；MySQL80(3305)/MySQL57(3306) Running。待办不变：下次发布前重新打包（落后 3 提交）；正式发布前 app.captcha.required 改回 true；浏览器崩溃如再现查 logs + F12；同事年报开发中（我方不动）。

## 今日（2026-09-01，含 08-31 起积累记录）

### 9. 2026-09-01：同事年报功能开发中 + 新版本打包发布（已发布到用户环境）
- **git 进展（今天 4 个新提交）**：
  - `92528d9`（同事）：数据导入页模板名/下载路径对齐实际模板文件（.xls→.xlsx、补个体客运模板路径）
  - `b1be169`（我方）：2 个模板文件入库推送（docs/城市客运/导入模板_出租车信息(运政车辆信息).xlsx、docs/公路旅客/个体客运量汇总.xlsx；同事本地放好后我方核对后按惯例入库）
  - `053ebfe`（同事）：数据导入页分组改名（道路货运/站场投资/货运能耗季报）+ 新增「年报」分组 11 类选项
  - `0c16e56`（同事）：6 个年报模板入库（docs/年报/，.xls）
- **⚠️ 年报功能只有 UI 壳，同事开发中，我方约定不动：**前端 groups 有 11 个 annual* 选项，但 importApiMap 无 URL、后端 DataImportController 无 annual* 端点、templateName/templateUrl 无映射、模板只有 6/11 类 → 选了年报类型无法上传/下载。同事继续开发，后续拉取即可。
- **打包发布（已完成，用户已发布到用户环境）**：后端 mvn clean package（jar 57MB）+ 前端 npm run build（dist 38 文件）；部署到 D:\trafficAudit：app.jar 替换（旧包备份 app.jar.bak_20260901）、web/ 重建、docs 单向同步（新增 docs/年报 + 2 个新模板，保留 ai_demo/usage_screenshots）；本机启动验证 8090：Started TrafficAuditApplication、首页 200、/api/auth/captcha-config required=false，验证后已停。
- **待办不变**：正式发布前 app.captcha.required 改回 true；浏览器崩溃如在新包再现看 logs/access.*.log + 客户端 F12；态势图/AI RAG/经济指标试算仅记录未实现。

### 10. 关机交接快照（09-01 晚）
- **当前运行状态**：dev 前后端未运行；D:\trafficAudit 的 app.jar（PID 28976，14:40 用户自己启动）在 8090 运行，关机自然停止、不需处理；MySQL80(3305)、MySQL57(3306) 均 Running，按惯例保留。
- **git**：工作区干净，HEAD=`9b97b92`，已同步 origin/main。
- **今日交付**：拉取同事代码（92528d9/053ebfe/0c16e56）、模板入库（b1be169）、打包发布到 D:\trafficAudit 并本机验证通过（旧包备份 app.jar.bak_20260901），用户已发布到用户环境；版本号咨询已答复（SemVer，首次正式发布定 1.0.0）。
- **待办（不变）**：①正式发布前 app.captcha.required 改回 true；②浏览器崩溃如再现看 logs/access.*.log + 客户端 F12；③同事年报功能开发中（我方不动）；④态势图/AI RAG/经济指标试算仅记录未实现；⑤每日反思自动化未创建。
- **⚠️ 发布后又拉到同事 2 个新提交**（关机前发现）：`fbc1c15` 数据导入与报表生成多项改进、`91d7eee` 投资系统基准导入兼容查询结果表头（行号/单位/时期/计划总投资）。今天 11:43 打包发布的版本不含这两项，用户环境当前版本落后 HEAD 2 个提交；下次发布前需重新拉取 + 重新打包。

### 12. 关机交接快照（09-02 晚）
- **当前运行状态**：dev 前后端运行中（本日 13:44 一键脚本启动，8090/8080 就绪），关机自然停止、不需处理；MySQL80(3305)、MySQL57(3306) 均 Running，按惯例保留。
- **git**：本次提交 HANDOFF.md（含 11 节验证记录 + 本节快照）后推送 origin/main；同事提交 799ec67 已拉取合并。
- **今日交付**：验证同事 3 个提交（fbc1c15/91d7eee/799ec67）全部通过（详见第 11 节）：投资多文件批量 + 幂等 + .et 支持、投资系统导出表头兼容、能耗并发锁 + 空车牌0过滤 + 前端防连点、报表生成回归；测试数据已清理还原（删 2026-08 能耗 1284 行 / investment_system 148 行 / import_batch 91~102），git 工作区除 HANDOFF.md 外干净。
- **待办（不变）**：①下次发布前重新打包——用户环境仍落后 HEAD 3 个提交（fbc1c15/91d7eee/799ec67）；②正式发布前 app.captcha.required 改回 true；③浏览器崩溃如再现看 logs/access.*.log + 客户端 F12；④同事年报功能开发中（我方不动）；⑤态势图/AI RAG/经济指标试算仅记录未实现；⑥每日反思自动化未创建。
- **临时文件**（保留）：D:\Codex\_tools\pptr-core\_tmp_verify_0902.js / _tmp_investPlan_202607.xls / _tmp_energy_zero_plate.xlsx。

## 历史（2026-08-31，含 08-28 起积累记录）

### 1. 登录验证码：测试阶段可跳过（已完成并验证）
- 后端新增 `app.captcha.required` 开关（缺省 `true`=启用）；本机 application.yml 与 example 现为 `false`（测试阶段跳过，**正式发布前改回 `true`**）。
@@ -97,6 +301,24 @@
- **修复**：8 个页面 el-menu 统一改为 `ref="sideMenu"` + `:default-active="$route.path"` + `@select="onMenuSelect"`；`onMenuSelect` 加在 main.js 全局 mixin（setTimeout 宏任务强制纠正 activeIndex，宏任务晚于 push 的微任务 onError 回调，保证最终高亮正确）。验证：6 轮×3 场景（顺序点/快速连点/同路由往返）全部高亮正确。
- **修改密码**：后端 `POST /api/auth/change-password`（用户改自己密码，需旧密码校验、新密码≥6位、新旧不同）+ `POST /api/user/reset-password`（仅 admin，重置他人为 123456，admin 自身禁止重置）；JwtUtils 新增 `resolveUsername(Authorization头)`。前端 AppHeader 公共顶栏加「修改密码」弹窗（旧/新/确认），UserManage 操作列加「重置密码」按钮（`isAdmin` 控制显示，非 admin 隐藏+后端 403 双保险）。API 与 UI（admin/非admin 双视角）均已验证，**测试后数据库密码已恢复原状**（admin/admin123 有效，chenzj 等原 hash 未变）。
- 测试脚本：`D:\Codex\_tools\pptr-core\menu_audit_rounds.js`（高亮回归）、`pwd_ui_test.js`（改密 UI）。

### 7. 08-31 下班前：数据导入页重构（验收通过，commit 791e70f，已推送）
- **需求（用户 4 轮提出，全部验收通过）**：①「选择类型并挂载文件」→「选择数据类型」，删除报表期卡片说明文字；②删除「加入队列」、目录导入（粘贴路径「导入该目录」/「浏览…」/「跳过已导入文件」/目录进度列表）、目录浏览弹窗；③模板名+「下载模板」移到类型选择框旁并排（单行省略），删除各类型说明文字；④「导入记录」→「导入结果」：默认空白（「暂无导入失败记录」），仅失败批次平铺明细表（列：导入类型/报表期/文件名/失败位置/失败原因，「第 X 行（企业名）」来自后端 import_batch.error_detail，无需新接口）；⑤「本月导入进度」改为右侧抽屉式边栏（非卡片、左右收起/展开、默认收起；展开后内部滚动 overscroll-behavior: contain，不带动整页滚动）。
- **实现**：仅改 `traffic-audit-web/src/views/DataImport.vue`（累计 +119/-380）。前端 dev 编译 ✅ + puppeteer 双场景验证 ✅（真实无失败数据→空态；拦截 mock 失败数据→明细表渲染；侧栏 34px⇄342px 往返、5 组 18 项、内部滚动独立）。
- **踩坑**：①新方法 `parseFailDetails` 曾误加在 methods 对象**外面**（mounted 前），Vue 不识别 → 展开行渲染时抛 TypeError、el-table 展开行不渲染（现象像 Element UI expand 失效），报错是 [Vue warn] 只在 **console** 出现、pageerror 抓不到（puppeteer 须监听 console 事件）；移入 methods 后恢复。②puppeteer 验证 el-table 展开行不要用合成 click 点图标（时灵时不灵），直接拦截接口 mock 数据验证渲染更可靠。
- 测试脚本：`D:\Codex\_tools\pptr-core\_tmp_import_ui_final*.js`（mock 拦截验证）、`_tmp_import_ui_check*.js`；项目根 `_tmp_patch*.py`/`_tmp_probe*.py`/`_tmp_fix*.py`（改造脚本，按约定未删）。

### 8. 关机交接快照（08-31 晚更新，用户关机前）
- **当前运行状态**：dev 前后端均在运行——后端 8090（spring-boot:run，含今日改动）、前端 8080（vue-cli-service serve）。访问 http://localhost:8080，admin/admin123 登录正常。
- **数据库**：本机 MySQL 8.0.29（localhost:3305，traffic_audit）。4 个账号 admin/yangb/wangq/chenzj 密码哈希均未改动（admin 密码经今日改密测试后已恢复 admin123；chenzj 原哈希已恢复）。
- **git**：工作区干净；远端 Gitblit origin main 已同步到 `791e70f`（数据导入页重构）。
- **今日交付（验收通过）**：①菜单高亮间歇性失效根因修复（el-menu 同路由导航回滚，见第 6 节）；②修改密码功能（用户自改 + admin 重置他人为 123456，见第 6 节）；③数据导入页重构（选择数据类型/模板并排/失败明细表格/进度抽屉侧栏，见第 7 节）。
- **待办**：
  1. **重新打包发布测试环境**——`D:\trafficAudit` 的 app.jar/web 还是 08-27 旧包，不包含：el-tabs 修复（d42a044）、超时保护、菜单高亮修复（b051f00）、修改密码、验证码跳过、**数据导入页重构（791e70f）**。打包方法见 `docs/打包部署说明.md`（SpringBoot 托管 web/ + docs/，单端口 8090）。
  2. **正式发布前**把 `app.captcha.required` 改回 `true`（现在 application.yml 为 false 测试跳过）。
  3. 浏览器崩溃问题若在**新包**上仍出现：看服务器 jar 同级 `logs/access.*.log`（%D 耗时）+ 客户端 F12 Network（chunk/batches 状态），此前 el-tabs 根因（684da41/d42a044）应已消除。
  4. 态势图构想 + AI 助手 RAG 需求仍只记录未实现（见文档归档），后续排期。
- **测试脚本**：`D:\Codex\_tools\pptr-core\` 下 `menu_audit_rounds.js`（菜单高亮回归）、`pwd_ui_test.js`（改密 UI）、`prod_server.js`（打包静态+代理 8091）。puppeteer 用 node24 跑：`C:\Users\jcxiong\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe`。

## 二、快速启动
统一用一键脚本（必须沙箱外/提权运行）：
@@ -192,3 +414,6 @@
  sql 的规则 INSERT 改写为 INSERT IGNORE VALUES（兼容 MySQL 5.7/8.0，原派生表写法在 8.0.29 报 Unknown column t.rule_code）。
  ⑥ 验证：后端 mvn compile ✅、前端 npm run build ✅。坑：链接工作区 .git 是文件，robocopy /MIR 会把它删掉导致"not a git
  repository"，需重建 gitdir 文件；PowerShell 的 -e "..." 字符串里 $ 会被当变量展开，写 SQL 密码哈希要用 SQL 文件。


- 2026-08-31（下班前）：数据导入页重构验收通过（commit 791e70f 已推送，详见第 7 节）。改造全用 Python 替换写文件（apply_patch 本机必败）；关键坑：Vue 新方法误放 methods 外 → render TypeError、el-table 展开行不渲染，[Vue warn] 只在 console 不在 pageerror；验证用 puppeteer 拦截 /api/import/batches 返回 mock 失败数据直接验明细表，真实无失败数据验「暂无导入失败记录」空态。