交通货运统计审核系统 — 问题与注意事项汇总

用途：把项目运行、数据导入、报表生成、仓库协作中所有「踩过的坑」集中记录，供后续开发与运维快速查阅。
维护方式：新发现问题请直接在本文件追加，并注明日期。
最后更新：2026-09-16

一、速查表（最常见的 10 条）

#	事项	正确做法
1	启动前后端	项目根目录执行 `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`
2	端口占用判断	看 `backend.log` / `traffic-audit-web/frontend.log`，不要依赖 `Get-NetTCPConnection`
3	后端就绪标志	日志出现 `Started TrafficAuditApplication` + `Tomcat started on port(s): 8090`
4	前端就绪标志	日志出现 `Compiled successfully` + `App running at:`
5	连数据库	`mysql.exe --host=127.0.0.1 --port=3308 --user=root --default-character-set=utf8mb4 -D traffic_audit`
6	停旧进程	按 PID 精确停 `cmd → java(maven) → java(app)` 链；不要杀 node_repl 和用户自己的 cmd 窗口
7	脚本报「已添加了具有相同键的项」	本机同时存在 `Path` 与 `PATH`，改用 `cmd.exe /c ... > log 2>&1`，严禁用 `Start-Process`
8	写中文文件	用 UTF-8；`main.js` 带 BOM 必须写回 BOM；改文件前先确认原文件是 CRLF 还是 LF
9	提交前	先测试 + 写《功能测试报告》+ 更新《工作日结》，再 fetch/合并/推送
10	推公司 gitea	先 `git fetch gitea` 与远端 `main` 合并，禁止强推

二、启动与进程管理

问题	原因	处置
`Start-Process` 报「已添加了具有相同键的项」	环境变量同时存在 `Path` 与 `PATH`（值相同）	统一用 `cmd.exe /c ... > log 2>&1` 或 `ProcessStartInfo` 启动
前端在沙箱内起不来（`EPERM: lstat`）	node 访问用户目录被沙箱拦截	`start-dev.ps1` 整体在沙箱外执行
嵌套 `powershell.exe -Command` 引号被破坏	外层 shell 先解析一层引号	直接运行 `.ps1` 文件，不做嵌套
重启时误杀 Codex 内核	按名字杀 `node.exe` 会命中 `node_repl`	按 PID 精确停后端链 `cmd → java(maven) → java(app)`、前端链 `cmd → node(npm) → cmd → node(vue-cli-service)`
前端日志找不到	日志在子目录	`traffic-audit-web/frontend.log`；后端 `backend.log` 在仓库根目录

重启标准流程：列出 java.exe 进程 → 停 app → maven → cmd → 运行 start-dev.ps1（脚本自动跳过已在监听的端口）。

三、服务状态验证

沙箱内 Get-NetTCPConnection 会因权限「拒绝访问」而**静默失败**，据此判定端口未监听是错的。
判断服务状态一律以日志为准；HTTP 探活用：
后端：GET http://127.0.0.1:8090/api/auth/captcha-config（返回 {"code":200,...} 即通）
前端：http://localhost:8080/#/login
前端日志出现 Proxy error: Could not proxy request /api/... (ECONNREFUSED) 说明**后端当时没起来**，不是前端问题。

四、数据库

连接（本地开发库）：
& 'C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe' --host=127.0.0.1 --port=3308 --user=root --password=<见 AGENTS.md> --default-character-set=utf8mb4 -D traffic_audit
必须写 --host=127.0.0.1：写成 -h127.0.0.1 会被解析成 host 127，连接失败。
输出过滤 2>&1 | Select-String -NotMatch 'Warning' 可屏蔽密码警告。
常用表与关键列：

表	说明	关键列
`freight_turnover_import`	货运量/周转量	`report_period`、`region_name`、`freight_m01..m12`、`turnover_m01..m12`、`last_*`
`h2031_enterprise_monthly`	公路旅客 H203-1 月报	`report_period`、`enterprise_code`、`unified_credit_code`、`report_unit`
`import_batch`	导入批次	`import_type`、`report_period`、`file_name`、`success_rows`
`audit_result` / `audit_run`	审核结果/运行	`report_period`

排查「某期数据在不在」：SELECT report_period, COUNT(*) FROM <表> GROUP BY report_period ORDER BY report_period;
排查「某期导入来自哪个文件」：查 import_batch 的 file_name。
表结构变更要同步三处：实际库 DDL、docs/init.sql、docs/database.md。
测试用报表期建议用 2099-xx，测完用 POST /api/import/clear?period=... 或直接 DELETE 清理，避免污染真实月份下拉项。

五、数据导入：文件路径与期次约定

5.1 货运量/周转量（`/api/import/freightTurnover`）

源文件	覆盖期次	备注
`D:\05_数据分类\高速\定稿-湖北省各市州运输量数据（2026年1-8月）.xlsx`	2021-12 / 2022-12 / 2024-12 / 2025-12 / 2026-08	无 2023 年 Sheet
`D:\05_数据分类\货运\7月\定稿-湖北省各市州运输量数据（2026年1-7月）.xlsx`	多一个 `2023` Sheet	2023 年数据的来源；2021/2022/2024 与 8 月文件逐值一致

多年度工作簿识别规则（detectYearSheets）：

至少 2 个 Sheet（单 Sheet 文件不识别为多年度工作簿，会走老的月度模板路径）；
每个 Sheet 名匹配 ^\d{4}\s*年?$（2023年、2023 都可以）；
每个 Sheet 首行 A1 含「货运量」、B1 含「月」。
任一条件不满足 → 整体回退老的月度模板解析。

每个年度 Sheet 的结构：上方是「货运量(万吨)」块（约 20 行），下方是「周转量(万吨公里)」块；**同一市州名第二次出现即视为周转量块**。
报表期语义：**2021-12 这类期放的是该年 1–12 月的全年数据**（m01..m12 全部有值），不是 12 月单月。该年最后有数据的月份决定期号（2026 年只有 1–8 月 → 2026-08）。
上年同期：多年度文件里自动取**上一年度 Sheet**；若上一年度不存在（如 2021 无 2020 Sheet），last_* 为空。
只补某一年时，可另存一个只含该年 + 上一年的临时工作簿再导入（注意「至少 2 个 Sheet」规则）。

5.2 公路旅客 H203-1（`/api/import/passengerMonthly`）

源文件	备注
`docs\公路旅客\模板_交企统H203-1表_公路旅客运输月度生产情况.xlsx`	用户修改后的模板
`D:\桌面\测试数据\公路旅客\八月\公路旅客运输月度生产情况（2026）_2026-09-09 09_18_45.xls`	系统导出的老格式样例
`D:\需要导入的数据\公路旅客\*.xls`	历史各月导出文件

解析**按表头名取值**（buildHeaderMap），因此模板在中间插列/整体右移**不会**破坏其它字段。
新模板在「企业名称」后新增 2 列：统一社会信用代码、填报单位；老格式文件其实也带这两列（此前代码未读取）。
必需列缺失会直接报错，例如选错类型时提示「表头缺少必需列【企业名称】【客运量_总计】」。

5.3 其它

导入失败必须在页面显示**行号**（用户要求），新增解析逻辑时不要吞掉行号信息。

六、报表生成

「汇总大表」预览弹窗由 ReportExport.vue 渲染：
弹窗内**只保留一张指标表**（分类 / 指标 / 数据 / 同比），「中口径」之后不再渲染任何表格；
弹窗支持拖动（v-dialog-drag 指令，拖标题栏）+ 10px 圆角。
导出依赖**母版模板文件**：docs/生成汇总大表/YYYY年M月道路运输量汇总表.xlsx。缺失时报「母版定位失败：未找到模板文件」，**不是数据问题**。
接口层面自查（绕过前端，定位是前端还是后端问题）：
预览：GET /api/report/preview?period=2026-08&mode=month&types=summaryWorkbook
导出：GET /api/report/export/summaryWorkbook?...
失败提示已细分：能区分「连不上服务器」和「后端返回的具体原因」；导出接口是 responseType:'blob'，报错时 data 也是 Blob，必须先 text() 再解析。

七、登录与验证码

问题	原因	处置
登录页出现空白方框 + 「验证码加载失败，请检查网络」	前端 `captchaRequired` 默认 `true`，读取 `/api/auth/captcha-config` 失败时静默忽略，页面残留加载不出来的验证码框	默认值改 `false`，改为 fail-safe：只有后端明确返回 `required === true` 才显示；请求失败按「不需要验证码」处理
开关位置	后端 `application.yml` 的 `app.captcha.required`	关掉后应显示「测试模式：行为验证码已跳过」
换网络/换 IP 后接口 403	跨域白名单	CORS 需放行内网网段（已修复 `0d2a5fc`）

八、文件写入与文本处理的坑

本机文件**换行符不统一**：Login.vue、main.js 是 CRLF；ReportExport.vue、DataImportService.java、docs/*.md 是 LF。用 [System.IO.File]::WriteAllText 时必须匹配原换行符，否则后续 -replace / 字符串匹配会失败。
main.js 带 BOM（EF BB BF），改写时要用 New-Object System.Text.UTF8Encoding($true)。
git checkout -- <文件> 会把 LF 转成 CRLF（本仓库 core.autocrlf=true），会让后续基于 LF 的替换失效；操作前先确认真实换行符。
PowerShell 多行中文替换建议写 *.py 脚本用 python 执行（apply_patch 在本机不可用）。
字符串替换**注意锚点唯一性**：| enterprise_name | varchar(200) | 企业名称 | 在 docs/database.md 出现 4 次，直接 replace 会改错表；必须先截取目标章节再替换。
读 .xls：本机 python 无 xlrd，可用 Excel COM（New-Object -ComObject Excel.Application → Workbooks.Open → Cells.Item(r,c).Text，记得 Quit() + ReleaseComObject）。

九、浏览器自动化取证的坑

tab.playwright.evaluate() 读 DOM 才可信；AX 树可能读到缓存。
Playwright locator 对 Element UI 表格内按钮**会超时**（isVisible() 恒为 false）；改用 AX 索引 tab.click(index)。
tab.drag([x1,y1],[x2,y2]) 拖拽时，坐标必须落在**当前视口**内（本机内嵌浏览器视口很小，约 319×790），否则报 Coordinate is outside the active tab content viewport。
tab.click 的 AX 索引**在页面刷新后会失效**，可能命中别的控件；每次操作前重新 cua.getTab(...) 取新索引。
截图：const fs = await import('fs'); fs.writeFileSync(path, Buffer.from(await tab.getScreenshot()))（require 不可用）。
改 .vue 后需要 tab.reload()。
临时脚本/文件（_*.*）未经用户同意**不要删**。

十、Git 双仓库工作流

仓库	remote	分支	地址
个人	`origin`	`master`	`https://gitee.com/zhizhijie/traffic-audit.git`
公司	`gitea`	`main`	`http://61.183.254.94:3000/r/trafficAudit.git`（账号 zyj）

每次改动的固定顺序：
1. 测试 + 写《功能测试报告》 + 更新《工作日结》；
2. git fetch origin → 合并个人仓库新提交（避免覆盖用户改动）；
3. git fetch gitea → 与远端 main 对比合并 → 禁止强推；
4. git commit → git push。

凭据只走本机 git/临时 askpass，**禁止写进仓库任何文件**。
公司 gitea 网络不通时记录为遗留问题，**不要**用强推绕过。

十一、当前已知遗留问题（截至 2026-09-16）

#	问题	影响	状态
1	8 月源文件缺 2023 年 Sheet	已用 7 月文件补录 `2023-12` 解决	已解决
2	2026-01 ~ 2026-07 的 `last_*` 为空	这几期改动前即为空，非本次引入	待用户确认是否补
3	2026-01 ~ 2026-07 的 H203-1 `unified_credit_code` / `report_unit` 为空	新列本期才读取，历史期未回填	待用户确认是否重导
4	预览弹窗「共 0 行」与「月度覆盖：1~8月均有数据」口径不同	易误解	待用户确认改文案
5	公司 gitea 推送	网络无响应，未推成功	待补推
6	仓库根目录大量 `_.` 临时文件	体积/可读性	经用户同意后再清理

2026-09-16 傍晚更新：遗留问题 4（预览弹窗「共 0 行」文案）已按用户确认修改完毕——汇总大表改为显示「指标 N 项」，其它报表显示「共 N 行明细」。

十二、2026-09-16 补充：货运页签「累计」列修复（重要口径）

12.1 母版派生口径（必须遵守）

《货运》页行结构：
- 全省块：r5 货运量 / r6 周转量 / r7 其中规上货运量 / r8 其中规上周转量 / r9 其中规下货运量 / r10 其中规下周转量；
- 17 个市州块每块 6 行，首行 11,17,23,...,107（武汉市...林区），块内顺序：合计货运量 / 规上货运量 / 规下货运量 / 合计周转量 / 规上周转量 / 规下周转量。

规则：全省行必须完全由 17 市州行派生。
- r7 / r8 / r9 / r10 = SUM(17 市州对应行)；
- r5 = m7+m9，r6 = m8+m10。

历史教训：r9/r10（全省规下）曾是**写死常量**，与 17 市州规下之和不等 —— 2023 差 4.6e-3、2022 差 3.1e-3、2021 差 1.5e-4（2024/2025/2026 恰好为 0），导致 6 个累计列里 2022/2023 比源文件人工核算差 0.003 左右、2021 整列为空。2026-09-16 已全部改为公式。

累计列现状（全省行，4 位小数与源文件一致）：

列	年度	公式
S	2026(1-8月)	C+E+G+I+K+M+O+Q
AT	2025	V+X+...+AR
BV	2024	AX+AZ+...+BT
CW	2023	BY+CA+...+CU
DZ	2022	=SUM(DM:DX)（原为写死常量）
EO	2021	=SUM(EC:EN)（原为空）
EP	2021 累计同比	保持为空（页内无 2020 块，无基期）
EA	2022 累计同比	=IFERROR(DZ/SUM(EC:EN)-1, 空串)（原为写死常量）

12.2 母版改动方式与文件职责

必须用 Excel COM（改公式 -> CalculateFullRebuild -> Save），**不可用 openpyxl 另存**：会清空全本公式缓存值（曾导致 2021 年湖北省行变 0）。
导出件里的公式**无缓存值**：openpyxl(data_only=True) 读出来全是 None，核对数值必须用 Excel COM 重算或自写求值器。
文件职责：
YYYY年M月道路运输量汇总表.xlsx = 母版（唯一数据来源）；
生成_道路运输量汇总表.xlsx = 只作列宽参照（applySummaryReferenceLayout 只读列宽/隐藏标记，不读数值）；
2026年8月道路运输量汇总表_版式原型.xlsx = 运行时**无任何代码引用**。
同期备份母版还原机制：resolveSummaryDonor 只认文件名**以 _备份_ 开头且含「{年}月」**的文件，命中即整格回填覆盖母版。=> 自建的备份文件/目录**不要**用 _备份_ 前缀，否则可能被当成 donor 把母版改回旧值。

12.3 文本处理的坑（本机 PowerShell / git）

问题	原因	处置
公式被写成 =SUM(DM5)	"$m7" 被解析为变量 m7；"$r:DX" 里的 $r:DX 被当成「驱动器 r:」而吞掉	一律用 ${m} / ${r} 定界
命令整体不执行、无输出、退出码 1	一个命令里出现嵌套的单引号 here-string，外层在第一个结束符处提前结束	一个命令只放一个 here-string；或先 Out-File 写补丁文件，再用 Get-Content -Raw
apply_patch 传多行参数失败	.bat 包装器破坏了多行参数	直接调 codex.exe --codex-run-as-apply-patch $patch
git commit -m 报 "outside repository"	PowerShell 用反引号转义，消息里的反斜杠+引号会提前结束字符串	用 git commit -F <消息文件>
PS5.1 报乱码路径「无法找到 ...」	PS7 的 Out-File -Encoding utf8 写的是无 BOM UTF-8，PS5.1 按 GBK 读脚本	写 .ps1 时用 -Encoding utf8BOM

12.4 遗留问题增量（截至 2026-09-16 晚）

#	问题	影响	状态
7	h2032_enterprise_monthly 2026-09 脏期（实为 8 月文件误存为 9 月）	636 行 + import_batch 302	已删除，留可还原 SQL 备份
8	《货运》页累计列 2021/2022/2023 对不上人工核算	已修母版派生口径，6 列全部对上	已解决
9	2026-09 期还在 h204_vehicle_quarterly(1284 行) / investment_monthly(31 行) / audit_result(2061 行) / audit_run(3 行)	若按 2026-09 出报表会取到脏数据	待用户确认是否清理
10	2026-07 导出件《货运》页为 118x145（比 8 月少 2 列）	7 月母版是「1-4 月骨架」，非完整母版	待 7 月母版定稿
11	2026年8月道路运输量汇总表_版式原型.xlsx 的 S 列漏 8 月（缺 Q5）	运行时未被引用，暂无影响	待确认该文件去留
12	母版经 Excel 重存后体积 959,706 -> 1,492,121 字节（导出件 950,186 -> 1,331,599）	纯格式开销，数据无影响	记录

详见《功能测试报告/功能测试报告_货运页签累计列修复与脏期清理_2026-09-16.md》。

十三、2026-09-16 补充：2026-07 母版补齐 & 导出件「Excel 打不开」根因（P0）

13.1 症状与根因

项	内容
症状	`GET /api/report/export/summaryWorkbook?period=2026-07&mode=month` 生成的 xlsx，Excel 打不开（COM 报「不能取得类 Workbooks 的 Open 属性」；`CorruptLoad=1` 修复模式同样打不开）；2026-08 同接口正常
直接原因	导出件里有 19 个模式非法格：`<c r="E15" s="111" t="n"><v>67.0</v><is><t>67.00</t></is></c>` —— `t="n"` 不允许带 `<is>`（inlineStr 专用）
深层原因	7 月母版由 openpyxl 写出（`docProps/app.xml` = `Microsoft Excel Compatible / Openpyxl 3.1.5`，文本存 `<is>`）；8 月母版是 Excel 原生（文本走 sharedStrings）。POI 的部分写入路径只改 `t`/`<v>`、不清旧 `<is>`
触发路径	7 月存在 `_备份_2026年7月道路运输量汇总表_清理前_20260904.xlsx` → `restoreSummaryMonthlyBlocks` 整格回填 → 往 inlineStr 格里写值留下旧 `<is>`。8 月无 `_备份_*`，不走回填，故正常
命中位置	leave-one-out 定位到 sheet9《公交》17 格 + sheet12《轨道、轮渡》2 格

13.2 修复（`traffic-audit-server`）

exportSummaryWorkbook 新增 normalizeStaleInlineStrings(wb)：落盘前清掉所有「非 inlineStr 却残留 <is>」的格子（幂等），命中即打 warn 日志。
restoreSummaryMonthlyBlocks 新增 skipFreightHistoryBlocks：《货运》页 T 列及以后（2025/2024/2023/2022/2021 年度块 + 各年累计/累计同比列）**永不从备份母版回填** —— 与既有「中口径排名左块永不回填」同一思路，避免补齐被「生成又复活」。

13.3 2026-07 母版补齐（口径与 8 月母版对齐）

年度块（每列）：r7/r9/r8/r10 = SUM(17 市州对应行)、r5 = r7+r9、r6 = r8+r10 → 360 格；
累计列：DX = SUM(DK:DV)（2022）、EM = SUM(EA:EL)（2021，原**整列为空**）、DY = IFERROR(DX/SUM(EA:EL)-1,"")（2022 累计同比，原为**写死常量**）→ 324 格；
2023 累计 CU = BW+BY+…+CS 本来就正确，未改；EN（2021 累计同比）按口径保持为空。
一手证据：母版 DX5=144979.2825（旧常量 144979.285376043，差 0.0029 = 全省规下常量与 17 市州之和的差）、EM5=161309.53162、CU5=173045.296428512，与 8 月母版 DZ5/EO5/CW5 完全相等。
备份：docs/生成汇总大表/_bak_2026年7月道路运输量汇总表_补齐前_20260916.xlsx。**切勿改名为 _备份_ 开头**，否则会被 resolveSummaryDonor 当 donor 回填。

13.4 本次新增的排查坑

问题	原因	处置
Excel COM 间歇性报同一个错，导致误判「8 月件也打不开」	每次 `New-Object -ComObject Excel.Application` 留下的孤儿 EXCEL 进程会污染后续实例	每例测完把「本次新建的 EXCEL 进程」强杀再测下一例；`Quit()`+`ReleaseComObject` 并不够
编译报「找不到 isSetSheetData()」	`CTWorksheet.sheetData` 是 XSD 必填元素，不生成 `isSetXxx`	改用 `ctw.getSheetData() != null`
部件级 diff 太大跑不动	对 519KB 的 `styles.xml` 直接 `difflib` 是 O(n²)	先按部件比字节尺寸/是否相等，只在必要的小部件上做 diff

13.5 遗留问题增量

#	问题	影响	状态
13	2026-06 / 2026-09 无母版	预览 `ready=False`「未找到模板文件」，无法出数	需先建母版（用户第 5 问的延伸）
14	仓库根 `_.` 临时文件继续增多（`_hyb_` / `_loo_` / `_v2_` / `_final_` / `_fixed_` / `_t7_` / `_poijar`）	体积/可读性	经用户同意后再清理

第 10 项（2026-07 导出件少 2 列 / 7 月母版是「1-4 月骨架」）本节已处理：导出端会**自动补出 5/6/7 月表头与公式**并重算累计公式，母版已补齐 2021/2022/2023 累计列，故关闭该项。