# 交通货运统计审核系统 —— 总交接文档（2026-09-21）

> **用途**：接手人（开发/运维/业务对接）在不问人的前提下，能独立跑起来、看懂架构、知道哪些活没干完、哪些坑不能再踩。
> **读者**：接手本系统的同事 / 后续接手的 AI 会话。
> **维护约定**：每完成一项就把第 4 章对应条目的「状态」改成 ✅ 并注明日期；新问题直接追加，别另起新文件。
> **本文与其它文档的关系**：本文是**唯一入口**；汇总大表那条线的细节在 `docs/问题汇总/汇总大表问题交接_2026-09-21.md`（本文第 4 章只做摘要，不重复正文）；
> 历史坑索引在 `docs/问题汇总/问题与注意事项汇总_2026-09-16.md`。

---

## 0. 先读这一页（接手的第 1 小时）

1. **先把系统跑起来**，再谈改代码。见 §7.1（一键脚本，必须在沙箱外执行）。
2. **当前最紧急的 4 件事**（详见 §4 P0）：① 《亿元投资项目》月份列每月覆盖上月（用户 Q7 要的「加一列」未做）；
   ② 导出前「基数体检 + 弹窗 +《数据缺失清单》页」只做了一半；③ 缺 2026-06 / 2026-09 母版，那两期出不了表；
   ④ 汇总大表「中口径排名 vs 中口径明细」历史同比基数双轨制（16 个市州有差）。
   > 原「8 月十堰物流源文件含非十堰段」已于 2026-09-21 闭环，见 §4 P0-1。
3. **别自己拍板业务口径**，第 5 章列的是必须业务确认的事。
4. 改完必须：写《功能测试报告》→ 更新《工作日结》→ 双仓库推送（§7.4）。这是本项目的硬规矩。

---

## 1. 现状快照（2026-09-21 上午实测）

### 1.1 服务与进程

| 项 | 值 |
| --- | --- |
| 后端 | Spring Boot，端口 **8090**，日志 `backend.log`（仓库根）；今晨有导出动作（PID 31328，09:17） |
| 前端 | Vue2 + Element UI，端口 **8080**，日志 `traffic-audit-web/frontend.log`（今晨 08:30） |
| 数据库 | MySQL `127.0.0.1:3308`，库 `traffic_audit`，账号 `root/123456`；客户端 `D:\mysql\mysql-5.7.41-winx64\bin\mysql.exe` |
| 启停 | `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1` / `stop-dev.ps1`，**必须沙箱外（提权）运行** |

> 判断服务是否起来：**只看日志**（后端 `Started TrafficAuditApplication` + `Tomcat started on port(s): 8090`；前端 `App running at`）。
> 沙箱内 `Get-NetTCPConnection` 会静默失败，据此判断会误判。

### 1.2 数据库现状（`SELECT COUNT(*)`）

| 表 | 行数 | 说明 |
| --- | --- | --- |
| `investment_project` | **152** | 投资主档（客运站场 + 物流园区） |
| `investment_monthly` | **284** | 2026-06: 76 / 2026-07: 72 / **2026-08: 136** |
| `freight_turnover_import` | **234** | 18 行/期 × 13 期（2021-12 ~ 2026-08） |
| `h2031_enterprise_monthly` | 15811 | 公路旅客（中口径维度 1 的来源之一） |
| `h2032_enterprise_monthly` | 13056 | 货运企业月报 |
| `investment_system` | 2026-07: 148 / **2026-08: 129** | 投资系统导出（投资审核的比对基准）；08 期用**新模板**导入 |
| `import_batch` | 417 | 导入批次台账（异步导出的「数据版本守卫」用它） |

- **2026-09 脏期已清理干净**（本次核实：`h204_vehicle_quarterly` 只有 2026-07/08；`audit_run`/`audit_result` 只有 2026-05~08；`investment_monthly` 只有 06~08）。
  此前 09-16 记录的「2026-09 有 1284/31/2061/3 行脏数据」**已解决**。
- 报表期分布是「**2021-12 这类期存全年 1-12 月**」的语义（不是 12 月单月），见 §3.1。

### 1.3 代码仓库

| 项 | 值 |
| --- | --- |
| 工作区 | `D:\文档\ChatGPT\traffic-audit`，分支 `main` |
| HEAD | `a08c70d feat(投资): 市州月报统一填报模板 + 县(市、区)列解析 + 表头行判定收紧` |
| 个人远端 | `origin` → `https://gitee.com/zhizhijie/traffic-audit.git`（分支 `master`） |
| 公司远端 | `gitea` → `http://61.183.254.94:3000/r/trafficAudit.git`（分支 `main`，账号 zyj） |
| 工作区状态 | 干净（交接文档、汇总大表问题交接、日结、投资系统新模板支持均已提交并推送两端） |

### 1.4 关键目录

| 路径 | 内容 |
| --- | --- |
| `docs/生成汇总大表/` | **汇总大表母版**（`{yyyy}年{M}月道路运输量汇总表.xlsx`）+ `_bak_`/`_备份_` 历史件（**未经同意不要删**） |
| `docs/投资/模板/` | 投资 5 张表的母版 + 2 份新市州填报模板 |
| `docs/投资/输入/{客运（客运站）,物流（物流园区）}/{N}月/` | 市州月报源文件（程序按「报表期 → `{N}月`」目录自动扫描） |
| `docs/投资/输出/` | 解析/校验/清理报告、备份 |
| `docs/功能测试报告/`、`docs/工作日结/`、`docs/问题汇总/` | 交付物与问题台账（硬规矩，见 §7.4） |
| `_tmp/_qa_out/`、`_tmp/qa_wh/` | 排查脚本与证据（gitignore，不入库）；`_pylibs/` 放 openpyxl / xlrd |

---

## 2. 系统结构

### 2.1 技术栈

- 后端：Spring Boot（`traffic-audit-server`，Maven），MySQL 8.0，Apache POI（HSSF 处理 .xls / XSSF 处理 .xlsx）。
- 前端：Vue 2 + Element UI（`traffic-audit-web`，vue-cli），`/api` 代理到 8090。
- 报表两种形态：**数据源表**（导入库）与**生成件**（POI 往母版里填值，母版不入库、不随程序分发）。

### 2.2 后端关键类

| 类 | 职责 |
| --- | --- |
| `dataimport/service/DataImportService.java` | 所有导入解析（货运周转量、H203-1、城市客运、投资市州单表/投资系统导出、网约车报告…） |
| `dataimport/controller/DataImportController.java` | 导入与清理接口（`/api/import/*`） |
| `reportexport/service/ReportExportService.java` | 所有生成件（汇总大表、投资 5 张表、各类独立报表、预览、就绪校验） |
| `reportexport/service/ReportExportTaskService.java` | 汇总大表异步导出任务 + 进度 + 10 分钟内存缓存 + 数据版本守卫 |
| `reportexport/calc/SummaryWorkbookFiller.java` | 汇总大表台账页回填 + 公式按月补齐 |
| `reportexport/calc/WycSplitCalc.java` | 网约车拆分（订单占比 × 全省 pin；城市内用巡游出租城市内占比代理） |
| `dataimport/service/AuditService`（及 `audit/*`） | 审核规则（RULE001…）与审核结果落库 |

> 逐行代码地图见 `docs/问题汇总/汇总大表问题交接_2026-09-21.md` 第 8 节（含行号，务必用它，不要重新满仓库找）。

### 2.3 前端页面

| 页面 | 文件 | 说明 |
| --- | --- | --- |
| 数据导入 | `views/DataImport.vue` | 按类型导入；结果弹窗可拖动、内容可滚动、可导出明细 CSV；「网约车订单及全省总量」已隐藏 |
| 数据查看 | `views/DataView.vue` | 「报表期」在「数据类型」之前；已含**投资**（投资项目基础表 / 投资系统每月导入项目表）与**能耗**分组 |
| 报表生成 | `views/ReportExport.vue` | 预览（单表指标：分类/指标/数据/同比，已删除「中口径」之后的所有表）+ 下载；含两张投资明细表、进度弹窗 |
| 审核结果 / 规则管理 / 用户管理 / 登录 | `views/AuditResult.vue`、`RuleManage.vue`、`UserManage.vue`、`Login.vue` | 验证码默认**不显示**（`captchaRequired` fail-safe 为 false） |

### 2.4 常用接口（排查时绕过前端用）

| 用途 | 接口 |
| --- | --- |
| 某期某报表是否可出 | `GET /api/report/ready?period=2026-08` |
| 预览 | `GET /api/report/preview?period=2026-08&mode=month&types=summaryWorkbook` |
| 汇总大表导出（同步/异步） | `GET /api/report/export/summaryWorkbook?...`、`POST /api/report/exportTask/summaryWorkbook` + `GET /api/report/exportTask/{id}` |
| 投资市州单表批量导入 | `POST /api/import/investCityBatch?period=2026-08&category=客运站场`（另一类 `物流园区`） |
| 导入批次查询 | `GET /api/import/batches?type=...` |
| 清某期数据 | `POST /api/import/clear?period=...` |

> 本地调试自签 JWT：`_tmp/_qa_out/mktoken.py`（secret 在后端 `application.yml` 的 `jwt.secret`，2 小时过期，401 就重签）。

---

## 3. 数据链（源 → 库 → 生成件）

### 3.1 货运量 / 周转量

| 项 | 内容 |
| --- | --- |
| 源 | `D:\05_数据分类\高速\定稿-湖北省各市州运输量数据（2026年1-8月）.xlsx`（**无 2023 年 Sheet**）；2023 年来自 7 月那份（多一个 `2023` Sheet） |
| 接口 | `POST /api/import/freightTurnover` |
| 库 | `freight_turnover_import`（`freight_m01..m12` / `turnover_m01..m12` / `last_*`） |
| 期次语义 | **`2021-12` 放的是该年 1-12 月全年数据**；该年最后一个有数据的月份决定期号（2026 只有 1-8 月 → `2026-08`） |
| 生成件 | 汇总大表《货运》《道路运输周转量》《货运量排名》《货运周转量排名》页 |

- 多年度工作簿识别规则（`detectYearSheets`）：≥2 个 Sheet + Sheet 名匹配 `^\d{4}\s*年?$` + 首行 A1 含「货运量」B1 含「月」；任一不满足则回退老的月度模板解析。
- 一个 Sheet 里「货运量」块在上、「周转量」块在下，**同一市州名第二次出现即视为周转量块**。

### 3.2 公路旅客 H203-1（中口径的来源）

| 项 | 内容 |
| --- | --- |
| 源 | `docs/公路旅客/模板_交企统H203-1表_公路旅客运输月度生产情况.xlsx`（模板已按用户要求改过，新增 `统一社会信用代码`、`填报单位` 两列） |
| 接口 | `POST /api/import/passengerMonthly` |
| 库 | `h2031_enterprise_monthly`（+ `passenger_individual_monthly` 个体） |
| 要点 | 解析**按表头名取值**，所以模板插列/右移不会算错；缺必需列会报「表头缺少必需列【企业名称】【客运量_总计】」 |

### 3.3 城市客运

| 项 | 表 | 备注 |
| --- | --- | --- |
| 城市公交 | `city_bus_monthly` | 中口径维度 2 = 「总量 − 城市内」**现算** |
| 巡游出租 | `city_taxi_monthly` | 维度 3 = 「总量 − 城市内」；同时是网约车拆分的代理输入 |
| 网约车 | `wyc_order_monthly` / `wyc_total_monthly` | 维度 4：订单占比 × 全省 pin；先查库，库里没有才回落 `docs/城市客运/网约车订单及全省总量.xlsx` |
| 网约车分析报告 | `POST /api/import/wycOrderReport` | 解析 `.docx` 报告里的市州订单表；**这是导入过 `湖北网络预约出租汽车2025年09月分析报告` 那个入口** |

### 3.4 汇总大表（19 个页签）

- 入口：报表生成页勾「汇总大表」→ `ReportExportTaskService`（异步）→ `ReportExportService.exportSummaryWorkbook()`。
- 六步：找母版 → 回填 6 张台账页 → 公式按月右移 → 现算 4 张成品页 → 搬 3 张排名页的值 → 两位小数格式 + `evaluateAll` 重算 + `fullCalcOnLoad`。
- **关键认知**：母版是公式驱动的。全省行 = Σ17 市州；城市客运 / 中口径明细是跨表引用，不需要单独写数，只要公式按月补齐 + 重算。
- 母版：`docs/生成汇总大表/{yyyy}年{M}月道路运输量汇总表.xlsx`，**程序不会自己建**（见 P0-4）。

### 3.5 投资（5 张表）

| 步骤 | 目标表（母版） | 规则 |
| --- | --- | --- |
| Step1 月报 → 明细表 | `模板_X月客运站投资明细表.xlsx`、`模板_X月物流站场投资明细.xls` | 以**项目名称**为键：已有→更新 H/I/J/K/L/M；没有→**新增整行**（已实现动态插行） |
| Step2 明细 → 汇总 | `模板_全省预安排计划进度情况汇总.xls` | 同名更新 4 项；没有的新增；模板有而月报没有的**保持原值**（已实现动态插行 + 「有总投资无月度数」补计） |
| Step3 明细 → 3 张固定表 | `模板_十五五规划物流项目进展情况.xls`、`模板_亿元投资项目.xls`、`模板_经济强县投资统计报表.xls` | 项目清单固定，只更新指定指标（三张表都已实现动态插行逻辑，其中亿元表见 P0-2） |

- 入库：`investment_project`（主档）+ `investment_monthly`（当期月度数，按「市州 + 类别」幂等清理后重建）。
- 市州填报：**统一模板已生成** `docs/投资/模板/模板_市州月报_客运站场.xlsx` / `模板_市州月报_物流园区.xlsx`，口径说明见 `docs/投资/填报口径与统一模板_2026-09-20.md`。

### 3.6 能耗 / 年报 / 审核

- 能耗：`POST /api/import/energyMonthly`、`/api/import/energyAuth`；台账在数据查看「能耗」组。
- 审核：规则在 `RuleManage`，结果在 `audit_result` / `audit_run`（按报表期）。

---

## 4. 未完成的工作（按优先级）

> 状态列：❌ 未做 / 🔶 部分完成 / ⏸ 待业务确认 / 🔒 被外部阻塞

### P0 —— 会直接影响出数正确性或会反复发生

| # | 事项 | 现象 / 影响 | 现状与证据 | 下一步 | 状态 |
| --- | --- | --- | --- | --- | --- |
| P0-1 | ~~8 月十堰物流汇总表含「非十堰段」~~ | —— | **已闭环（2026-09-21）**：用户确认「清除掉」→ 用 Excel COM 删除源文件第 11~63 行（武汉 27 + 黄石 4），原件备份 `docs/投资/输出/源文件备份/…_原始含武汉黄石_20260921.xls`；重导验证该文件 38 → **7 条**，8 月物流 128 → 97，库内仍 152 项目 / 136 条 2026-08 月度数 | 无需再处理（后续若再加回非本文件市州段，需重新清理） | ✅ |
| P0-2 | **《亿元投资项目》规上项目表月份列会被覆盖** | 代码只重写表头文字（`ReportExportService.java:6128-6139` 写 `col5`/`col23`），模板 row2 第 24 列原本是「2026年7月实际完成投资」。8 月导出把它改成「2026年8月…」并写 8 月数 → **7 月那一列的数据消失** | 用户已在《待确认清单》Q7 明确：「只更新 F 列 + 在 2026年X月实际完成投资后**加一列** 2026年X+1月实际完成投资」→ 未实现 | 按 Q7 改为「按月追加一列」；同表其它写死月份列（1-3月/4月/5月/6月/第二季度）同样要一起看 | ❌ |
| P0-3 | **导出前「基数体检 + 弹窗 +《数据缺失清单》页」（B4）** | 去年同月基数残缺时程序照算，曾把中口径排名全省累计同比算成 **+73.89%**（真值 +5.81%）。加体检后可根治复发 | 后端已收集问题清单 `midIssues`（`ReportExportService.java:2436`）与 `dbProblems`，但 **`getLastMidIssues()` 没有任何调用方**，前端也无消费，没有《数据缺失清单》页 → 只做了 B5（日志）与 B3（完备性校验） | ① 就绪/预览接口返回 issues；② 导出前弹窗；③ 生成件追加《数据缺失清单》页 | 🔶 |
| P0-4 | **缺 2026-06 / 2026-09 母版** | 这两期预览 `ready=false`「未找到模板文件」，出不了表 | `docs/生成汇总大表/` 下只有 2026年7月 / 2026年8月 + 版式原型；程序**只按文件名精确匹配**、不会自建 | 用户 Q13 已暂缓（要问同事「能不能用母版自动生成后续每月模板」）。短期：人工放一份 9 月母版；长期：扩列器（详见汇总大表交接 P0-2） | ⏸ |

### P1 —— 口径类 / 需要业务确认（不阻塞日常，但会影响定稿）

| # | 事项 | 说明 | 状态 |
| --- | --- | --- | --- |
| P1-1 | 中口径排名 vs 中口径明细「历史同期基数双轨制」 | 除武汉外 16 个市州累计同比都有差（黄冈 7.74% vs 7.64%）；根因是母版 2025 年 3、4 月网约车拆分用了一套与出租列自相矛盾的旧输入。**方案 A 已实施并回归：排名页改用母版 2025 静态列**；黄冈 1-8 月累计同比修正为 `7.641733%`，17 市州 × 两指标共 68 个同比/累计格全部一致（最大差 `2.91e-11`），当月同比无回归 | ✅（2026-09-21，详见汇总大表交接第 4 章） |
| P1-2 | 中口径排名全省行差 0.0002 万人公里 | 母版公式 `=SUM(O4:O20)` 先四舍五入再求和的结构性差异，是否改全精度写值需拍板 | ⏸ |
| P1-3 | 中口径明细 4 格 `#DIV/0!` | 2025 年 8 月基数为 0（不可比），是否改空白需业务确认 | ⏸ |
| P1-4 | 全省 h2031 1-8 月 27524.49 vs Σ17 市州 24481.74 | 差 **3042.75**（企业上报的「全省」含市州明细外的数据，或某市州漏报）。程序一律按母版口径（Σ市州）走 → 建议业务侧核一次 | ⏸ |
| P1-5 | 天门物流源文件 `8月份物流园中心建设项目(天门).xlsx` 的 H/J/K 列为空 | 该市州本期累计/计划/月完成取不到 | 🔒 等同事给数 |
| P1-6 | 荆州 / 黄石「规划内 / 规划外」拆分口径 | 影响明细表分块归位 | ⏸ 等同事 |
| P1-7 | 投资「资金渠道」分组未入库 | 明细表里「一、车购税 / 二、省燃油税 / 三、农村综合运输服务站 / 四、候车亭」分组行在导入时被 `^[一二三四五六七八九十]+、.*` 规则跳过 → 项目落不到具体渠道块。需给 `investment_project` 加 `fund_channel` 并重导 7/8 月 | ❌ |
| P1-8 | 武汉 8 月物流无单表 | 该市州小计现在只有「总投资」，缺自开始累计/本年计划/月完成（已按「有总投资无本期月度数」补计，不污染累计列） | 🔒 需武汉单表或省厅口径 |
| P1-9 | 投资导出输出目录约定（Q10 已答「同意」） | 约定：`docs/投资/输出/<YYYY-MM>/` 按月分目录、原格式原样输出、运行前自动备份 `_bak_<文件名>_<时间戳>`、另出 `运行日志_<年月>.md` 与 `校验报错_<年月>.xlsx` → **代码里没有实现**（无任何「输出」目录写入逻辑） | ❌ |
| P1-10 | 运输量 2026-01~07 的 `last_*` 为空 / H203-1 2026-01~07 的 `unified_credit_code`、`report_unit` 为空 | 前者是改动前就为空，后者是新列本期才读取；是否补/重导待确认 | ⏸ |
| P1-11 | 货运「持续在规 545 家」vs「官方全口径」两版同比（+2.90% vs +4.54%） | 口径不同，已分别注明；若要随《差异率汇总表》上报，建议加注差异原因 | ⏸ |
| P1-12 | 高速运距同比（用户表格 O 列）的来源/期间待确认 | 确认后方可算「运距增速差」 | 🔒 等用户 |
| P1-13 | 投资系统导出的**新模板**（`2026年X月投资系统项目明细`） | 已支持按表头定位解析（09-21，129 条入库）。**待定**：① 新模板多出的「项目所处阶段」未落库，如需比对建设阶段要加列并同步 `docs/init.sql`/`docs/database.md`；② 新模板**没有「自年初累计」列**，该维度审核已改为「基准缺失即跳过 + WARN 日志」（RULE_I002 实测 0 条），若业务仍要比对需模板补回该列 | 🔶 |

### P2 —— 工程与整洁

| # | 事项 | 说明 | 状态 |
| --- | --- | --- | --- |
| P2-1 | 「增速排名」措辞（D 组） | 只在同比齐全时排名，否则标注「去年同期基数缺失，暂不排名」 | ❌ |
| P2-2 | 城市客运页表头仍是**日期序列号** | 任何「按表头文字匹配列」的长效方案在该页会失效，需先把 G/I/K/M/O/Q、AD/AF/AH/AK 改成文字表头 | ❌ |
| P2-3 | `applySummaryReferenceLayout()` 按**列序号**套列宽/隐藏 | 参照件一加减列就整体错位，应改为按表头文字匹配 | ❌ |
| P2-4 | 缺母版提示（T08）未实测 | 有测试副本时补测 | ❌ |
| P2-5 | 部署包内是**带 AJ 列的旧母版** | `deploy/traffic-audit-deploy-20260913/backend/docs/生成汇总大表/`、`_deploytest/`；用户 09-20 明确「部署包先不管」，发包前必须同步 | ⏸ |
| P2-6 | ~~导出缓存是内存态~~ | **已解决（2026-09-22）**：结果落盘到 `docs/生成汇总大表/_cache/`（文件名带数据版本 `MAX(import_batch.id)`），内存 → 落盘 → 真算逐级命中，重启后端后仍可秒回复用；有新导入即失效，7 天上限并自动清理。遗留项已闭环（2026-09-22 下午）：版本号升级为**数据指纹**（依赖源表 `CHECKSUM TABLE` + 母版等文件身份，排除投资/能耗/审核/系统/导入日志），无关导入不再失效、换母版必定失效；失效时进度弹窗会说明原因 | ✅ |
| P2-7 | 市州单表「多市州块」兜底提示 | 是否在识别到一份文件含多个市州块时弹窗提示/跳过，待确认（与 P0-1 同一根因） | ⏸ |
| P2-8 | 仓库根目录 `_*.*` 临时文件增多 | `_chk_*`（本次汇总大表排查产生，见汇总大表交接第 10 节）、`_hyb_*`、`_loo_*` 等，**经用户同意后再清** | ⏸ |
| P2-9 | `2026年8月道路运输量汇总表_版式原型.xlsx` 去留 | 运行时未被引用 | ⏸ |
| P2-10 | 「班线包车」页 2020 年历史列 `#VALUE!` | 既有现象，Excel 打开按 `fullCalcOnLoad` 会重算 | 记录 |
| P2-11 | 报表生成页「中口径」之后表格已删、弹窗可拖动 + 圆角 | 已实现（09-16/09-20），别再改回去 | ✅ |

---

## 5. 待用户 / 业务确认清单（接手人先别自己拍）

1. **P0-1**：8 月十堰物流源文件的「非十堰段」由谁清、什么时候清？（建议：接手人删段并备份）
2. **P0-2**：《亿元投资项目》按月追加列的做法确认（用户 Q7 已给规则，实施前再确认一次列位）。
3. **P0-4**：2026-09 母版怎么办 —— 直接放一份人工母版，还是先做扩列器？（用户正在问同事）
4. **P1-1**：中口径排名历史基数——用户已拍板并完成方案 A（排名页改用母版 2025 静态列），无需再确认。
5. **P1-2 / P1-3**：0.0002 万人公里是否改全精度写值；`#DIV/0!` 是否改空白。
6. **P1-4**：h2031 全省行与 Σ17 市州差 3042.75 的业务解释。
7. **P1-6**：荆州 / 黄石「规划内 / 规划外」口径。
8. **P1-7**:投资资金渠道分组是否要入库（要的话需要加字段 + 重导 7/8 月）。
9. **P1-9**：投资导出「按月分目录 + 自动备份 + 运行日志/校验报错」是否按约定实施。
10. **P2-1 / P2-7 / P2-8**：增速排名措辞、多市州块提示、临时文件清理。

---

## 6. 历史坑索引（别重踩）

| 文档 | 覆盖内容 |
| --- | --- |
| `docs/问题汇总/问题与注意事项汇总_2026-09-16.md` | 启动/进程、DB、导入路径约定、报表生成、登录验证码、文件写入（换行/BOM）、浏览器取证、Git 双仓库、货运累计列口径、Excel「打不开」根因（inlineStr 残留） |
| `docs/问题汇总/汇总表问题汇总_2026-09-17.md` | 8 月空白/排名不对、投资预安排导出为空（月份选错）、报表生成页两张投资明细表 |
| `docs/问题汇总/汇总表三条主线修复方案_2026-09-18.md` | 「公式不重算」统一根因 + 页范围漏项 + 口径缺口 |
| `docs/问题汇总/中口径排名同比与城市客运列错位_根因与长效方案_2026-09-18.md` | 2025 基数三处缺陷（公交城际城乡=0、网约车 pin 缺失、出租 6 月重复）与 A/B/C/D 四组方案 |
| `docs/问题汇总/汇总大表问题交接_2026-09-21.md` | 汇总大表**逐行代码地图**与 P0-1/P0-2 详细论证（接手必读） |

**最容易被改回去的 6 个点**（取自汇总大表交接第 6 节）：

1. 城市客运页 AJ 列已删（母版有**两本**，改之前先确认改对哪本）。
2. `colIndexOf()` 必须返回 **0 基**列号（曾因 1 基导致 360 格循环引用）。
3. `setCellFormula` **不接受**带 `=` 前缀的公式串。
4. 公式必须 `evaluateAll` 重算写缓存值，否则预览/二次处理看到旧值。
5. 中口径「城际城乡」一律用「总量 − 城市内」现算。
6. `setValOrBlank()` 遇到公式格直接 return —— 别想用写值改排名页全省行。

---

## 7. 操作手册

### 7.1 启动 / 停止

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File D:\文档\ChatGPT\traffic-audit\start-dev.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File D:\文档\ChatGPT\traffic-audit\stop-dev.ps1
```

- 脚本自动跳过已在监听的端口；就绪判据看 `backend.log` / `traffic-audit-web/frontend.log`。
- 重启要**按 PID 精确停**（后端链 `cmd → java(maven) → java(app)`；前端链 `cmd → node(npm) → cmd → node(vue-cli-service)`），**不要**按名字杀 `node.exe`（会杀掉 Codex 自己的 `node_repl`）。

### 7.2 数据库

```powershell
& 'D:\mysql\mysql-5.7.41-winx64\bin\mysql.exe' '--host=127.0.0.1' '--port=3308' '--user=root' '--password=123456' '--default-character-set=utf8mb4' 'traffic_audit' '-e' "SQL"
```

- **必须写 `--host=127.0.0.1`**（写成 `-h127.0.0.1` 会被解析成 host `127`）。
- 表结构变更要**同步三处**：实际库 DDL、`docs/init.sql`、`docs/database.md`。

### 7.3 本机特有的坑

| 坑 | 对策 |
| --- | --- |
| 同时存在 `Path` 与 `PATH` → `Start-Process` 报「已添加了具有相同键的项」 | 一律 `cmd.exe /c ... > log 2>&1`，**严禁 `Start-Process`** |
| 沙箱内 node 访问用户目录被拒（`EPERM: lstat`） | 启动/编译/推送一律在**沙箱外**执行 |
| 沙箱内 `Get-NetTCPConnection` 静默失败 | 只用日志判断服务状态 |
| 中文控制台乱码 | 写文件后用 `Get-Content -Encoding UTF8` 看，别靠控制台输出判断 |
| 换行符不统一（`.vue` CRLF、`.java`/`.md` LF；`main.js` 带 BOM） | 改文件前先确认；`git checkout -- <file>` 会把 LF 转 CRLF |
| `apply_patch` 在本机不可用 | 写 `.py` 脚本用 `python` 执行替换 |
| python 缺库 | `sys.path.insert(0, r"D:\文档\ChatGPT\traffic-audit\_pylibs")` 后才有 openpyxl / xlrd |

### 7.4 交付规矩（硬性）

1. 每做完一个功能：**先测试 → 写《功能测试报告》**（`docs/功能测试报告/功能测试报告_<功能名>_<日期>.md`，含正向/负向/入库抽查）→ **更新《工作日结》**（`docs/工作日结/工作日结_<日期>.md`）。
2. 然后 `git fetch origin`（个人 gitee，分支 `master`）与 `git fetch gitea`（公司，分支 `main`）比对合并，**禁止强推**，再 commit + push。
3. 公司账号密码只走本机 git 凭据，**禁止写进仓库任何文件**。

---

## 8. 接手第一小时 checklist

- [ ] §7.1 起服务，看两个日志确认就绪（注意：**本次交接时服务正在运行，别重复起**）。
- [ ] `GET http://127.0.0.1:8090/api/auth/captcha-config` 通 → 后端 OK；打开 `http://localhost:8080/#/login` 能登录。
- [ ] 用 §1.2 的 SQL 核对库内行数（152 / 284 / 136）是否与本文一致。
- [ ] 生成一次 2026-08 汇总大表（报表生成页或 §2.4 接口），确认能产出、能打开。
- [ ] 读 `docs/问题汇总/汇总大表问题交接_2026-09-21.md`（重点第 3、4、5 章）。
- [ ] 读本文 §4，按 P0 顺序和用户确认前 4 件事怎么推进。
- [ ] 确认自己知道「改完要写测试报告 + 工作日结 + 双仓库推送」。

---

**交接人**：郑玉洁　**交接日期**：2026-09-21　**下次更新时请改文首日期并在此追加一行变更记录**

| 日期 | 变更 |
| --- | --- |
| 2026-09-21 | 首次成文：整合汇总大表交接（`docs/问题汇总/汇总大表问题交接_2026-09-21.md`）与投资/货运/客运各线遗留 |
| 2026-09-21（下午） | P0-1 闭环（十堰源文件已删段 + 重导验证）；新增 P1-13（投资系统新模板支持）；数据快照补 `investment_system` 行 |
| 2026-09-22（下午） | 导出缓存：结果落盘 + 数据指纹守卫 + 失效提示（P2-6 闭环） |
| 2026-09-21（下午） | P1-1 闭环：用户采用方案 A，中口径排名的 2025 累计基数改读母版《中口径明细》静态列；黄冈累计同比由 7.74% 修正为 7.641733%，双页一致性回归通过 |