编辑 | blame | 历史 | 原始文档

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

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

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

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

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

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

7. 操作手册

7.1 启动 / 停止

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 数据库

& '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 交付规矩（硬性）

每做完一个功能：**先测试 → 写《功能测试报告》**（docs/功能测试报告/功能测试报告_<功能名>_<日期>.md，含正向/负向/入库抽查）→ 更新《工作日结》（docs/工作日结/工作日结_<日期>.md）。
然后 git fetch origin（个人 gitee，分支 master）与 git fetch gitea（公司，分支 main）比对合并，**禁止强推**，再 commit + push。
公司账号密码只走本机 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%，双页一致性回归通过

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

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

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

1.1 服务与进程

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

1.3 代码仓库

1.4 关键目录

2. 系统结构

2.1 技术栈

2.2 后端关键类

2.3 前端页面

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

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

3.1 货运量 / 周转量

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

3.3 城市客运

3.4 汇总大表（19 个页签）

3.5 投资（5 张表）

3.6 能耗 / 年报 / 审核

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

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

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

P2 —— 工程与整洁

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

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

7. 操作手册

7.1 启动 / 停止

7.2 数据库

7.3 本机特有的坑

7.4 交付规矩（硬性）

8. 接手第一小时 checklist

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