feat(holiday): 新增往年国省道调整并按前一日环比基期重算汇总

xyc

昨天 e92968f85531df814268b6afbe62f6e062f5a07f

 HANDOFF.md

@@ -2,17 +2,660 @@

> **用法**：新对话开始后，先读本文件 + 项目根目录 `AGENTS.md`，即可无缝接力。
> **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。
> **协作约定（2026-08-31）**：说「提交」= 本地 commit + 推送到远端 git（origin main，Gitblit），不再只做本地 commit。

## 一、当前状态（2026-08-27 合并后）
- 前后端**运行中**（8090/8080 已监听，start-dev.ps1 启动），登录页已接入真实认证（数据库校验）+ 行为验证码。
## 最新（2026-10-06）

### 10-06：方案 D 已实现（往年国省道调整表 + 环比基期只作用于前一日分母）

- **最终口径**：`HolidayStatService.loadVehicleByDate` 先用 `holiday_vehicle_adjustment` 覆盖对应历史年份的“当日值”，供走势图、同比、累计和快报使用；随后构造“前一日环比分母”，若前一日普通国省道 C 列有值，则用 C 替换该日前一日国省道值，并据此重算非营业性人员流动量、公路人员流动量和总计。所有环比行只继承这份分母。
- **关键边界**：C 只影响“下一日的环比分母”，不影响 C 所在日的当日值、累计或走势图；调整表只维护历史年份（`year < 当前年份`），2026 年调整仍由导入 Excel 的 D 列进入当日值。
- **本轮实现**：新增 `holiday_vehicle_adjustment` 表及 mapper/service/controller；前端在专项统计-节假日页的“节假日数据”和“观测站分日调查数据”之间新增“往年国省道数据调整”卡片（后续按用户提议保持该位置），支持年份筛选、新增、编辑、删除和原因留痕；部署脚本与 migration 清单已同步。
- **10-04 导入预检（只读，不写库）**：用 `C:\Users\jcxiong\Downloads\2026年十一数据 (2).xlsx` 以 `allowHistoricalOverwrite=false` 调导入接口，返回确认项：
  - `第4日 2026-10-04 普通国省道：原值 323.6551，导入值 322.7695`
  - `第3日 2026-10-03 普通国省道环比基期：原值 空，导入值 320.2418`
  因此 C5 由空变有值不会硬拒绝导入，只会要求历史变更确认；用户确认后即可随调整后的 Excel 重导写入。
- **当前库状态**：本地 `traffic_audit.holiday_vehicle_adjustment` 已执行 DDL（0 行）；2026-10-04 业务值仍为旧值 `323.6551`，等待用户自行重导调整后的 Excel。助手未执行任何业务数据导入、覆盖或重导。
- **验证**：后端 `mvn -o test` 9 个测试全绿（含 C5 只改 10-04 环比分母、历史调整进入 2025 当日值）、前端 `npm run build` 通过；页面实测“往年国省道数据调整”卡片与新增弹窗正常。
- **已知取整边界（需沿用现有口径或另作决策）**：快报百分比目前按既定规则先复现源 Excel 单元格格式，再取 1 位小数。10-04 总计环比原始值约 `4.5481%`，源格显示 `4.55%`，再取 1 位得到 `4.6%`；若直接从原始值一次取 1 位则是 `4.5%`。当前代码保留“先 Excel 显示、再快报 1 位”的既有口径；若领导要求改为一次取整，需要单独改快报百分比路径。

> 说明：本文件早前“环比基期只作备用、不参与计算”的段落已作废。该版本针对的是旧实现误把 C 放到 C 所在日本身计算的问题；自方案 D 起，C 的正确语义是**前一日环比分母的调整值**。

### 10-06（已作废，见上方方案 D）：普通国省道「环比基期」改为人工备用值（不再参与计算）

- **背景**：10-04 鄂州樊家庄站中小客流量断崖下跌（35419 -> 8856），领导要求剔除。手工稿快报的做法是：先用剔站后的数值算出 10-04 环比，把 10-03 国省道值挪到「环比基期」C 列备用，再把 10-03 恢复原值以免影响累计。用户明确口径：**「环比基期」只用于数据备用，不参与任何计算**。
- **旧行为（错）**：`HolidayStatService.nationalProvincialRingRatio` 在 2026 年只要 `comparison_base` 有值就按「当日 / 环比基期 - 1」算国省道环比；导出时 E 列写 `=(D{行}-C{行})/C{行}`。按手工稿的 C 列摆法（基期放在被比日那行），这样算还会错位（10-03 环比被算成 +1.11%）。
- **新行为（本次已改）**：国省道环比固定「当日 / 前一日 - 1」，2024/2025/2026 一致；`comparison_base` 只在导入/导出/页面展示时原样保存与回写，不参与环比、折算、累计。导出 E 列改为 `=(D{行}-D{上一日行})/D{上一日行}`，C 列照常回写备用值。
- **改动**：`HolidayStatService.java`（`nationalProvincialRingRatio` 去掉 year/comparisonBase 形参）、`HolidayWorkbookService.java`（新增 `ringRatioFormula`，导出按上一行同年 D 列）、`docs/database.md`（`comparison_base` 与计算口径两处）。
- **验证**：新增 `HolidayComparisonBaseTest`：① 库内存 `comparison_base=320.2418` 时，10-04 国省道环比仍按前一日 323.7837 计算，且不等于按基期算出的值；② 导出公式 = `=(D6-D5)/D5`。`mvn -o test` 全绿（4 个测试类）。

### 10-06：待确认——10-04 国省道剔站（鄂州樊家庄）怎么进系统

- **手工口径已逐项核对，与库内 `observation_station_flow` 完全对得上**：
  - 10-04 国省道值（2026/2025/2024）= 原值 − 樊家庄当日值 -> 322.7695 / 337.5009 / 322.5277 万辆次（樊家庄 8856 / 4492 / 2328）。
  - 10-04 环比分母 = 2026-10-03 原值 − 樊家庄 10-03 值 = 323.7837 − 3.5419 = **320.2418** 万辆次 -> 环比 = 322.7695/320.2418 − 1 = **+0.79%**。
  - 10-03 显示值与累计仍用原值 323.7837，被剔的 320.2418 只落到 C 列备用。
- **趋势结论（需先跟领导对齐）**：只剔樊家庄，10-04 国省道环比只有 **+0.79%**；同日高速小客车 **+9.78%**、铁路 +9.94%、民航 +11.69%、道路 +4.99%、水路 +4.33%。**剔一站填不平约 9 个百分点的趋势差**，与「让国省道和高速趋势一致」的预期并不相符，建议同时请鄂州核实原始记录。
- **待决策的代码方案**：因 `comparison_base` 已定为纯备用，系统无法从「当日值」反推剔站基期，需要另设机制。推荐新增「异常站剔除」配置（站点编号 + 生效日期 + 年份），算环比分母时用 `observation_station_flow` 的「该日站点合计 − 剔站值」作基期；显示值与累计仍用原值。
- **决策点**：① 做成可配置的通用「异常站剔除」（推荐，可复用于其他节假日/站点），还是只按本次 10-04 一次性处理；② 剔站只影响国省道环比分母，还是也要下沉到非营业性小客车/公路/全社会的环比（手工稿实际把 4.17% / 4.55% 也一起改了）。

## 最新（2026-10-05）

### 10-05 上午：关机快照（当前状态）

- **已完成**：v1.0.0 正式发布包 `deploy/traffic-audit-deploy-20261005-v1.0.0/`（zip **77.78 MB**）已生成，去密自检、版本自检、结构核对与真实启动冒烟均通过，待上传服务器。版本管理代码与文档均已提交推送（`main` = `93b36c8`）。
- **运行状态**：关机前本机 dev 服务仍在运行（后端 8090 java PID 64112、前端 8080 node PID 46472），随关机停止，无需处理；打包冒烟用的 8095 实例已停止、端口已释放。
- **工作区**：除若干本地临时文件（`_tmp_*`）与一份专项统计 xls 外，git 工作区与远端 `main` 一致；`docs/工作日结/`、`docs/功能测试报告/` 等按约定不入库。
- **下次接手**：先读根目录 `AGENTS.md` + 本文件；待办见第七节（数值精度统一改造、态势感知图、AI 助手 RAG、经济指标试算等），首要事项是跟进正式包在服务器的部署结果。

### 10-05 上午：正式发布包按新版本管理重新生成（v1.0.0，单端口瘦包）

- **背景**：`8b71049` 已把打包脚本改为固定 jar 名 + 版本自检（`traffic-audit-server.jar`、包名带 `v{version}`），但正式发布包还没按新脚本重新生成；版本改造前产出的 `deploy/traffic-audit-deploy-20261005-2/` 仍是旧 jar 名 `traffic-audit-server-1.0.0-SNAPSHOT.jar`。
- **重新生成**：`powershell -NoProfile -ExecutionPolicy Bypass -File pack-deploy.ps1 -NoFrontendDist -SkipServiceWrapper`（后端 clean package 重建、前端 `npm run build` 重建）。
- **产物**：`deploy/traffic-audit-deploy-20261005-v1.0.0/`（351 文件 / 94.58 MB），zip **77.78 MB**。
- **校验**：去密自检 + 版本自检通过（pom / `app-version.properties` / `MANIFEST.MF` 三者均 `1.0.0`）；包内 `backend\traffic-audit-server.jar` 为固定名；无 `frontend/`、无 `trafficAudit.exe/.xml/install-service*`；`backend\web` 44 文件与 `frontend\dist` 逐文件 SHA-256 一致；`README-部署说明.txt` 头部为「20261005，版本 v1.0.0」并含旧服务器一次性升级说明。
- **启动冒烟（真实包、只读）**：用本地开发库配置在 8095 端口启动包内 jar，`GET /api/version` 返回 `{"version":"1.0.0",...}`，`GET /` 返回登录页 200；验证后已按 PID 58652 精确停止冒烟进程。
- **状态**：待用户上传服务器。`deploy/traffic-audit-deploy-20261005-2/`（及更早的 `20261005/`）作废勿用。旧服务器首次升级按 README：先改 `trafficAudit.xml` 的 `<arguments>` 为 `-Dfile.encoding=UTF-8 -jar "%BASE%\traffic-audit-server.jar"` 再换 jar，以后只替换 jar。

### 10-05：版本管理采用方案 A（固定 jar 名，用户验收通过）

- **用户决策**：采用方案 A。`traffic-audit-server/pom.xml` 为唯一版本源，当前对外版本 `1.0.0`。
- **构建改造**：`<finalName>traffic-audit-server</finalName>`，产物固定为 `target/traffic-audit-server.jar`；Maven 资源过滤生成 `app-version.properties`（Spring Boot 父 POM 使用 `@project.version@` 分隔符），`maven-jar-plugin` 写入 `Implementation-Version`。
- **页面显示**：新增免登录 `GET /api/version`；登录页和页头显示 `V1.0.0`。同时修复可执行 jar 下 `buildTime` 为 `null` 的嵌套 URI 解析问题。
- **发布链路**：服务 XML、启动脚本、打包脚本全部改用固定 jar 名；`pack-deploy.ps1` 会校验 pom / `app-version.properties` / `MANIFEST.MF` 三者版本一致，发布包名为 `traffic-audit-deploy-YYYYMMDD-v1.0.0(.zip)`，并输出带 `{version}` 的部署 README。
- **旧服务器首次升级（仅一次）**：停止服务后，把 `trafficAudit.xml` 的 `<arguments>` 改为 `-Dfile.encoding=UTF-8 -jar "%BASE%\traffic-audit-server.jar"`，替换 jar 后启动。以后发版只替换 jar 并重启，不再改 XML。
- **验证**：`mvn -o test`、`mvn -o clean package -DskipTests`、固定名 jar 实际启动并访问 `/api/version`、前端 `npm run build`、本地浏览器登录页显示 `V1.0.0`、`pack-deploy.ps1 -SkipFrontend -NoFrontendDist -SkipServiceWrapper` 组装/去密/版本自检全部通过；负向验证确认版本不匹配和 `SNAPSHOT` 都会在打包前中止。测试报告：本地 `docs/功能测试报告/功能测试报告_版本管理方案A_2026-10-05.md`（目录不入库）。
- **状态**：版本管理代码提交为 `8b71049`，`main` 已同步；`v1.0.0` 已推送到公司 Gitblit并指向 `21a5bf7`。2026-10-05 用户确认本地登录页及所有登录后页面均正确显示 `V1.0.0`。正式发布包已于 10-05 上午用新版打包脚本重新生成（见上方 10-05 上午一节）。

### 10-04 深夜：折线数值标签回到贴近本点（v35，待用户验收）

- **用户反馈**：v31「避开折线」版本不如上一版 v27 —— 虽然标签不压线了，但很多标签离自己的数据点太远，一眼看不出标的是哪个点。要求回到贴近本点的效果。
- **新问题与旧需求的冲突**：更早的原始诉求是「数字压线看不清」；这次诉求是「数字必须贴近本点」。两者并存，必须同时满足。
- **实现（`HolidayTrendChartService`）**：
  - 标签排版**完整回退到 v27 算法**：按同日点位距离做代价（`ownDistance ×10`），候选含近/远的上、下、左、右及四角，动态规划保证同日标签与点位上下顺序一致（`lineLabelCost`、`lineLabelCandidates`）。v31 的线条掩膜、Chamfer 距离场、颜色亲和项全部移除。
  - **新增粗白描边（halo）** 解决「压线看不清」：`drawLabelWithHalo` 用 `TextLayout` 取字形轮廓，先以白色 `HALO_OUTLINE_WIDTH=4.0f` 圆角描边，再用本色填充。数字即使落在折线上也清晰可读，从而允许标签贴回本点。折线图、堆叠图外置标签、饼图标签统一走该方法。
  - 顺带清理调试遗留：删除 `LABEL_DEBUG`/`CHART_SEQ`/`TRENDDBG` 打印，以及不再使用的 `lineNormal(...)` 与 `DayLabel.normalX/normalY`。
- **量化验证（RapidOCR 标签包围框中心 ↔ 真实数据点坐标）**：标签到本点平均距离 v27=`36.8px`、v31=`53.2px`、v35=`36.7px`（越小越贴近本点）。v35 与用户认可的 v27 基本一致，明显优于被否的 v31。
- **其余验证**：`mvn compile`/`mvn test` 通过（无编译告警遗留）；Word COM 8 页 15 图（1+2×7）；RapidOCR 复检 12 张折线图数值标签包围框重叠数 = 0；`label_affinity` 复检图 11 每个数据标签到本线 3~8px 且本线是最近线（无「CLOSER TO 其他色」）；放大 6× 复核图 11 左上标签确为 `630.99`（低分辨率 OCR 曾误读为 `1630.99`）。v27↔v35 像素差约 1%，集中在标签处，即白描边生效且未破坏折线。
- **产物与状态**：`_tmp_holiday_verify/holiday_trend_2026-10-04_v35.docx`；下载副本 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-数字贴近折线-白边清晰）.docx`。未导入、覆盖或重导任何数据。待用户验收；验收前不提交、不推送；现有 `deploy/traffic-audit-deploy-20261004.zip` 仍是 v24 行为，验收后需重建。

### 10-05：走势图 v35 验收通过 + 单端口发布包（-NoFrontendDist -SkipServiceWrapper）

- **验收**：v35（折线数值标签回到贴近本点 + 白描边）2026-10-05 用户验收通过。
- **打包需求（用户澄清）**：服务器单端口，只需要 `backend\web`，不要独立的 `frontend/dist`；为保证包完整，`backend\web` + jar + docs 都要。服务器非首次发布、服务已装，可加 `-SkipServiceWrapper` 去掉服务注册器。
- **打包工具修正**：先前加的 `-NoFrontend` 语义错了（把 `backend\web` 也去掉了），现改为 `-NoFrontendDist`。它只跳过独立 `frontend\` 目录（不复制 dist / nginx 示例），**仍构建（或要求）dist 并同步 `backend\web`**（单端口必需，否则页面 404）。`-SkipFrontend` 仍为“不重建、复用现有 dist”。
- **发布包**：`deploy/traffic-audit-deploy-20261005-2/`（351 文件 / 94.55 MB；zip **77.78 MB**）。已核对：无 `frontend/`、无 `trafficAudit.exe/.xml/install-service*`（服务包装器已排除）；`backend\web` 44 文件与 `frontend\dist` 逐文件哈希一致；jar 内置配置全占位符（去密自检通过）；包内 `HolidayTrendChartService.class` 与 `target/classes` 一致（含 v35 代码）。较上一完整包（110.49 MB / zip 83.77 MB）省约 16 MB 解压 / 6 MB 压缩。
- **作废**：`deploy/traffic-audit-deploy-20261005/`（错误语义下的产物，缺 `backend\web`）已被 `-2` 取代，勿用。
- **部署注意**：覆盖 jar（及按需 `application.yml`）即可；`backend\web` 已随包提供。服务已装，无需重新注册。
- **状态**：已打包，待用户上传到服务器；该包为版本改造前产物，已由 10-05 上午的 `traffic-audit-deploy-20261005-v1.0.0` 取代（勿用）。

### 10-04 深夜：折线数值标签避开折线并贴近本线（v31，待用户验收）

- **用户反馈（领导看后，两轮）**：① 各年份数字离本线有远有近，希望贴近各自色线且不错乱；② 仍有数字压在折线上看不清（第一轮只是“贴近”，标签会落在线上）。用户建议：调纵轴刻度拉开折线、或加左右避让让标签不压线。
- **实现（`HolidayTrendChartService`）**：
  - 标签排版改为「动态规划 + 线条像素避让」。图表先画折线和标记，再把所有系列颜色像素（容差 45）做成掩膜，对每个候选标签位置统计其覆盖的线条像素数，`×700` 重罚——数字不再压线。
  - 为每条系列建立 Chamfer 距离场（到该色最近像素的距离）。代价新增两项：`max(0, 自己那条线的距离-3)×40`（把标签拉回本线旁，防止飘远）与颜色亲和项 `max(0, 自己线距 - 别的线距 + 4)×200`（要求本线是最近的线，避免贴到别的系列）。
  - 旧的「离别的同日点位更近」惩罚由 `×5000` 降到 `×400`，避免它压倒亲和项；`ITEM_LABEL_GAP` 12→10；候选含近/远的上、下、左、右及四角。
  - 保留同日标签与数据点一致的上下顺序，避免标签与折线上下反转。
- **调参过程提示**：v27（只按点位距离排序）→ 标签压线；v28（只加覆盖像素惩罚）→ 标签离本线、贴到别的色线旁；v31（覆盖惩罚 + 本线距离 + 颜色亲和）→ 两者兼顾。验证标签是否“贴错线”不能只看 OCR 包围框到异色的距离：相邻的异色**标签**会被误判为异色**线**，必须肉眼核对整图。
- **验证**：`mvn test -f traffic-audit-server\pom.xml` 通过。真实库只读生成 `_tmp_holiday_verify/holiday_trend_2026-10-04_v31.docx`；Word COM 8 页 15 图（1+2×7）。RapidOCR 复检 15 张图数值标签包围框重叠数为 0。肉眼核对图 1（跨区域人员流动量）、图 2（累计）、图 4（自驾）、图 6（水路）、图 9（高速）、图 11（车流总量）：数值标签均离开折线、位于各自色线旁、颜色对应正确；图 11 的 630.99/601.04/571.31 分别紧贴蓝/红/绿折线。
- **产物与状态**：`C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-数值标签避开折线）.docx`。未导入、覆盖或重导任何数据。待用户验收，验收前不提交、不推送；现有 `deploy/traffic-audit-deploy-20261004.zip` 仍是 v24 行为，需验收后重建。

### 10-04 晚：走势图 3 项坐标轴调整（v24，用户已验收）

- **用户修改项**：① 坐标轴单位（万人次、万辆次、公里/小时、拥挤度、日期）改成和刻度一样的颜色；② 两个堆叠图的坐标轴改成与其他图一样的黑色；③ “万人次/占比”继续放在堆叠图右上角。
- **实现**：`HolidayTrendChartService` 把 `drawUnitLabel`、`drawUnitLabelTopRight`、`drawDateLabel` 的文字色由黑色改为刻度灰 `(102,102,102)`；横向堆叠图在数据区底边补画 `2.2px` 纯黑基线，覆盖 JFreeChart 默认偏灰的 1px 轴线和抗锯齿边缘，不添加箭头。折线图黑色坐标轴逻辑未改，堆叠图单位仍绘制在右上角。
- **验证**：`mvn test -f traffic-audit-server\pom.xml` 通过。真实库只读生成 `_tmp_holiday_verify/holiday_trend_2026-10-04_v24.docx`；Word COM 实测 8 页、15 张图。像素检查：折线图左上单位、日期及堆叠图右上单位均为 `(102,102,102)`；图 12/13 底轴在 y=529 为纯黑连续线；普通折线图底轴仍为纯黑。
- **产物与状态**：`C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-最新）.docx` 当时被 Word/WPS 占用，已另存为 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-最新-坐标轴调整）.docx`；原“最新”文件未覆盖。未导入、覆盖或重导任何数据。2026-10-04 用户已验收通过，随本次提交推送。

### 10-04 晚：走势图 4 项修改（v23，待用户验收）

- **用户修改项**：① 折线数值标签与折线上下顺序反了（累计流动量图：蓝线在上、标签却在下；第一张图首日最高是蓝点、最近的标签却是棕色）；② 公路出行结构图例把自驾放前面（棕色），与每日客流构成一致；③ 横坐标应为万人次/占比（数值轴放到底部）、去掉纵轴线与箭头；④ 每日客流构成恢复 5 条（自驾/道路/铁路/民航/水路），占比小的数字标在色块右边、用颜色区分。
- **实现**：
  - `HolidayTrendChartService.drawXYItemLabels` 重写：先把同一日期各系列按点位 y 从上到下排序，标签再按该顺序从上往下摆（下界为前一个标签底部 +3），**从而不会出现标签与折线上下反转**；避让权重改为「标签重叠 × 1000 + 数据点重叠 × 1」，并删除原来会把标签一路推到图表下方的非白像素惩罚项（`nonWhiteRatio`）。
  - 横向堆叠图：`plot.setRangeAxisLocation(AxisLocation.BOTTOM_OR_LEFT)` 把数值轴放到底部（万人次 / 占比 就是横坐标）；`domainAxis.setAxisLineVisible(false)` + `setTickMarksVisible(false)` 去掉纵轴线和刻度；`render` 对横向堆叠图不再画坐标轴箭头；单位改到右上角（`drawUnitLabelTopRight`）。
  - 堆叠图块内放不下的小数字，改为在色块右侧用同色文字标注（同一行按色块位置排成一列，列 x 取该行最右色块端 +8，并限制在预留 74px 右边距内）；放得下仍用白字写在块内。
  - `HolidayTrendService.roadStructureSeries` 顺序改为 自驾出行量（棕）、道路客运量（蓝）；`dailyShareSeries` 恢复 自驾/道路/铁路/民航/水路 5 条，删除上一轮临时合并用的 `sumNullableLists`。
- **验证**：`mvn test -f traffic-audit-server\pom.xml` 通过；v23 Word COM 实测 8 页（1+2×7，15 张图）。RapidOCR 复检 12 张折线图无标签重叠；逐日比对标签颜色顺序与折线点位顺序一致（累计图 10月4日 点位 2025 在上/2024 在下，标签同样 2025 在上、2024 在下；修改前 v20 恰好相反）；首图 10月1日最高点（蓝色 2025）的数值标签就在该点位正上方。图 12 图例为「自驾出行量·道路客运量」，数值轴在底部 0–12,000，单位万人次在右上角，无箭头、无纵轴线；452/228 以蓝字标在蓝块右侧，648 白字在块内。图 13 图例恢复 5 项，87.8% 等大占比白字在块内，道路/民航/水路等小占比以同色数字标在右侧一列。
- **数据操作与状态**：未导入、覆盖或重导任何数据。最终文件已覆盖到 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-最新）.docx`；待用户验收，验收前不提交、不推送。

### 10-04 傍晚：走势图 5 项微调（v20，待用户验收）

- **用户修改项**：① 纵轴单位仍与纵轴重叠，继续上移；② 第 1 页除标题外全空白，需放 1 张图到第 1 页；③ 横纵坐标刻度与图例偏黑，稍微调淡；④ 饼图标签颜色改为与扇区一致；⑤ 两个堆叠图效果仍不好，块做大、数字写进块里。
- **实现**：`HolidayTrendChartService` 为坐标类图表预留 `UNIT_LABEL_BAND=58px` 的顶部空白（`reserveUnitLabelBand` 调 `plot.setInsets`），单位标签基线改为 `dataArea.getY()-22`，彻底脱离轴线与最高刻度；刻度/图例文字色由 (70,70,70) 调淡为 (102,102,102)，坐标轴线与箭头仍为黑色；饼图标签（含引线框内文字）通过 `TextFragment` 反射改为对应扇区色；堆叠图维持横向，`categoryMargin 0.08->0.05`、`itemMargin 0.05` 让色块变厚，块内放得下就用 17px 白字写在块内，放不下才用同色引线拉到块外；折线数据标签左侧最小留白 `dataArea.minX+16`，避免紧贴纵轴刻度。
- **验证**：`mvn test -f traffic-audit-server\pom.xml` 通过。真实库只读生成 `_tmp_holiday_verify/holiday_trend_2026-10-04_v20.docx`（571 KB，15 张图）；Word COM 实测 8 页，第 1 页标题+1 张图，第 2-8 页各 2 张图，无空白页。RapidOCR 复检 12 张折线图文字包围框重叠数为 0；单位“万人次/占比”与最高刻度、轴线已分离（图 1 单位 y=17..44、顶部刻度 y=53..77）；堆叠图 12 的 452/8,595、648/10,410、228/3,962 与堆叠图 13 的 87.8%/7.4% 均在块内，个别过窄的 4.8% 用同色引线拉到块外；饼图标签颜色与扇区一致（铁路绿、民航紫、道路蓝、水路青）。
- **口径变化提醒**：图 13「每日客流构成变化」（附录一）由原先 5 条（自驾/道路/铁路/民航/水路）合并为 3 条（自驾/道路/其他方式=铁路+民航+水路），目的是让色块足够宽、数字能写进块内；正文 5 种运输方式走势图未受影响。
- **数据操作与状态**：未导入、覆盖或重导任何数据。最终文件已覆盖到 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-最新）.docx`；待用户验收，验收前不提交、不推送。

### 10-04 下午（3）：走势图 8 项修改（待用户验收）

- **用户修改项**：纵轴单位上移避开箭头；删除附录二同比走势；同日期的三年折线点恢复垂直对齐；图表标题去掉“2026年”；“观测站”改为“普通国省道观测站”；堆叠图小占比改为柱外引线标注；文档改为每页 2 图；图例“道路营业性客运量”改为“道路客运量”、“非营业性自驾折算客流”改为“自驾出行量”。
- **实现**：`HolidayTrendChartService` 恢复所有年份同一 x 坐标，纵轴单位绘制在数据区上方，堆叠图小占比使用同色引线拉到柱外；折线数值标签改为对其他数值标签设置极高避让优先级，白描边保留。`HolidayTrendService` 删除附录二同比 2 图，原附录三顺延为附录二，并更新标题和图例文字，当前共 15 张图。`HolidayTrendWordService` 封面后强制分页，取消章节标题后的多余空段，再按每 2 图自动分页。
- **验证**：`mvn test -f traffic-audit-server\pom.xml` 通过。真实库只读生成 `_tmp_holiday_verify/holiday_trend_2026-10-04_v17.docx`；Word COM 实测 9 页，封面单独第 1 页，第 2–8 页均为 2 张图，最后 1 张图单独第 9 页，无空白页。RapidOCR 复检 12 张折线图的数值标签重叠数为 0；堆叠图图 12、13 的小占比数字均可见；图 3“水路 0.23%”仍在右侧；图例已识别为“道路客运量”“自驾出行量”，图表标题中不再出现“2026年”。
- **数据操作与状态**：未导入、覆盖或重导任何数据。最终验收文件已复制到 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-最新）.docx`（原“修改版”文件当时被 WPS 占用，未覆盖）；待用户验收，验收前不提交、不推送。

### 10-04 下午（2）：走势图标签、折线间距与横坐标准确性修正（待用户验收）

- **用户反馈**：饼图“水路”引线难辨认需固定到右侧；堆叠图要显示数值；图例改黑色放大；横轴“日期”上移；纵轴单位放到箭头上方；坐标轴和刻度改黑色并放大；折线加粗、尽量拉开；修复横轴错位一天；折线数值标签要与折线同色，并检查标签重叠。
- **修复**：`HolidayTrendChartService` 饼图子类改为在 JFreeChart 已分好的左右标签集合中把“水路”从左集合移到右集合；折线宽度由 4px 调至 6px，多序列按 ±0.08 做轻微横向错开；关闭 JFreeChart 默认折线标签，改为逐点自定义排版：按上/下/远上/远下/左/右候选位置避让已放标签和数据点，并对单位区域留空；标签使用对应折线颜色并加白色描边。横轴错位根因是原 `XYSeries.add(i + 1, ...)` 与 `SymbolAxis` 实际整数位置 `0..7` 不一致，已改为 `add(i, ...)`。
- **验证**：`mvn test -f traffic-audit-server\pom.xml` 通过；真实库只读生成 `_tmp_holiday_verify/holiday_trend_2026-10-04_v14.docx`。RapidOCR 复检 14 张折线图，数值标签包围框重叠数为 0，未再识别出两个数值粘连；三年折线每图均识别出 2026 年 3 个、2025 年 8 个、2024 年 7 个，共 18 个数值标签，颜色计数为红 3、蓝 8、绿 7。饼图“水路 0.23%”位于右侧（OCR 中心 x≈801.5），其他小占比标签在左侧；堆叠图数值可见。10 月 1 日轴刻度 x≈123.5，首日数据点已落在第一格。
- **数据操作与状态**：未导入、覆盖或重导任何数据。新版已复制到 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版）.docx`；待用户验收，验收前不提交、不推送。

### 10-04 中午：走势图外观按模板重制（待用户验收）

- **用户反馈的 7 项问题**：章节标题重复、图比模板大、字小线细、网格和浅灰背景、坐标轴无箭头且单位位置不符、纵轴范围不合适、饼图小占比标签应拉到圆外。
- **修复**：`HolidayTrendWordService` 克隆章节时移除模板自动编号；每张图按模板对应尺寸设置 `wp:extent` 和内部 `a:ext`，并移除模板旧 `srcRect`。`HolidayTrendChartService` 改为纯白背景、无网格/无交替灰色带、黑色坐标轴带箭头、左上方水平单位、右下角日期；折线字号按 Word 纸张实际显示尺寸放大、加粗线宽和点径；纵轴不强制从 0 开始并按数据上下留白；百分比堆积图固定 0%-100%；饼图关闭 `simpleLabels`，使用外部标签和引线。
- **验证**：`mvn test` 全部通过，新增图表浅灰背景与 Word 编号/尺寸回归断言；前端 `npm run build` 通过（仅原有 bundle 体积警告）。真实库生成最终稿 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版）.docx`，Word COM 实测 9 页、17 张图；程序检查全部 `gray243=0` 且 6 个章节段 `numPr=false`，图片尺寸与模板 7 种目标框一致。最终版 PNG 按模板显示框宽高比输出（不再被 Word 拉伸变形），刻度/图例 18px、数据标签 20px、单位 22px，线宽 4px。
- **数据操作**：全程只读，未导入、覆盖或重导任何数据。状态：待用户验收，验收后再提交/推送。

### 10-04 下午：新增节假日综合运输客流量走势图初版（外观已按反馈重制）

- **需求口径（用户 2026-10-04 确认）**：走势图分 12 张正文 + 附录；领导原话为“各种运输方式客流量走势图，高速和国省道车流量走势图”。最终正文分为三部分：`一、总体情况`（当日总客流、累计总客流、运输方式占比）；`二、各种运输方式客流量走势`（自驾、铁路、水路、民航、道路，共 5 种方式）；`三、车流量走势`（高速、普通国省道、车流总量、公路出行结构）。附录分为每日客流构成变化、同比走势、观测站路网运行。自驾作为运输方式之一，使用非营业性自驾折算客流，单位万人次；高速/普通国省道/车流总量单位万辆次。
- **实现**：新增 `HolidayTrendService`、`HolidayTrendChartService`、`HolidayTrendWordService` 和 `ObservationDailyOperation`，使用 JFreeChart 生成 17 张 PNG；Word 仍以 `docs/专项统计/重要节假日/2026年十一假期全省综合运输客流量走势图.docx` 为模板，重建正文、保留模板页眉页脚和图片尺寸，替换/追加媒体并重建图片关系。新增后端接口 `GET /api/holiday/trend?year=2026&holidayType=NATIONAL_DAY`；前端节假日统计页新增“下载走势图”按钮。
- **数据与口径**：2024/2025/2026 三年，横轴固定 8 天；2024、2026 无第 8 天数据时留空，2025 显示第 8 天。累计曲线只连接实际已有日期，缺日不延续最后累计值。观测站附录按 2026-10-01 至 10-08 查询每日平均机动车速度和平均拥挤度；2026 当前覆盖 10-01/02/03。
- **验证**：`mvn test` 全通过；前端 `npm run build` 成功（仅 bundle 体积原有警告）。真实库数据生成 `_tmp_holiday_verify/holiday_trend_2026-10-04_v3.docx`，Word 统计 12 页、17 张图；下载接口返回约 399 KB DOCX。未执行任何数据导入、覆盖或重导。
- **未跟踪项**：走势图模板和 `_tmp_holiday_verify/` 仍为未跟踪文件；本地可运行，若后续提交/部署需把模板纳入部署包或仓库。状态：外观问题已由本日中午段修复，最终稿待用户验收。

### 10-04 上午：10 月 3 日数据导入并生成快报

- **源文件**：`D:\03_公司\02_项目\27_湖北省道路运输事业发展中心\10_业务\99_专项统计\01_重要节假日\2026\十一\10月3日\2026年十一数据10月3日.xlsx`（2026-10-04 10:11 更新）；观测站原始数据为同目录 `观测站分日调查数据2026.10.3.xls`。
- **导入过程（修正）**：用户先于 10:13:34 导入主数据；助手随后在 10:17:41 又用同一文件重复导入了一次。接口返回 `passengerRows=14, vehicleRows=6, skippedRows=24, successRows=20, failRows=0`，未检测到 10 月 1、2 日历史数据变化。唯一键命中后仅更新 `updated_at`，没有新增重复行。
- **10 月 3 日入库值**：铁路 72.4、民航 5.7571、道路 73.12、水路 5.5668 万人次；高速 193.3634、普通国省道 323.7837 万辆次；合计人员流动量 1397.99694 万人次。
- **观测站数据（修正）**：用户先导入；助手重复导入时按同日覆盖重插，当前 2026-10-03 为 691 行 / 691 个唯一键，无重复；中小客流量合计 3,237,837 辆次（323.7837 万辆次），与普通国省道入库值一致。
- **快报**：已生成 `C:\Users\jcxiong\Downloads\湖北省国庆假期综合运输客流快报（10月3日）.docx`。正文：当日 1398.00 万人次，环比下降 3.3%，同比 2025 下降 10.1%，同比 2024 下降 5.0%；累计 4486.63 万人次，同比 2025 下降 6.3%，同比 2024 下降 2.7%。
- **人工稿比对（10-04 更新）**：手工稿与系统修正版提取文本逐行一致；系统原版仅有两处累计数差异，已随本次代码修正消除。今日走势图功能暂停。

### 10-04 上午（2）：快报累计数按 Excel 亿单位显示精度后再换算

- **问题**：系统原版与手工稿仅两处差异：非营业性小客车累计 `3961.76` 应为 `3961.77`；公路合计累计 `4189.31` 应为 `4189.32`。
- **根因**：源表 `人员流动量汇总!X5/AA5`（总计对应 `U5`）存的是亿单位，单元格格式为 `0.0000000_`。人先看到 7 位小数的显示值，再换算成万人次并保留 2 位；旧代码直接拿原始累计值换算后取 2 位，漏掉了 Excel 显示这一步。
- **修复**：`HolidayBulletinService` 新增 `displayedCumulativeWan(...)`，先按源单元格 7 位小数取整，再乘 10000，最后按快报 2 位输出；应用于总计、非营业性小客车、公路合计三处累计数。
- **验证**：新增单测覆盖 `3961.76472 -> 3961.77`、`4189.31472 -> 4189.32`、`4486.62652 -> 4486.63`；`mvn test` 全通过。重启后基于现有库重新生成 10 月 3 日快报，与手工稿提取文本逐行比对结果为 `NO DIFFERENCES`。本次未执行任何数据导入。
- **产物**：`_tmp_holiday_verify/bulletin_cumulative_display_2026-10-03.docx`。
- **状态**：待用户验收/提交；走势图功能仍暂停。

### 10-04 上午（3）：快报其余 Excel 显示精度路径审计

- **审计范围**：逐项映射快报正文和表格的所有数值来源，核对源工作簿的实际单元格格式、Excel 显示值和代码传入的显示精度。
- **结论**：除已修复的累计值 `U/X/AA` 外，没有发现其他未处理的快报取值路径。源表直接参与快报的 `0.00%` 单元格共 11 处：`人员流动量汇总` D/P/J、V/W/Y/Z/AB/AC，道路 H（同比2024年），水路 D（当日环比）；代码均先按源格式取 2 位，再按快报 1 位处理。
- **补修边界**：道路 H 原按 1 位源格式处理，10 月 3 日碰巧仍为 `6.6%`；改为先按 `0.00%` 得到 `6.62%` 后再取 1 位，边界值不会差 0.1 个百分点。
- **未纳入直接快报路径的格式**：`普通国省道` E/N 虽为 `0.00%`，快报使用的是 `人员流动量汇总` 汇总后的 P/R/T，不使用该两列；高速公路/普通国省道内部 4 位小数人员流动量同理只作为源公式中间列，不直接输出。
- **验证**：`mvn test` 全通过；重启后端后重新生成 10 月 3 日快报，与手工稿逐块、逐单元格比较无任何差异。10 月 2 日与手工稿的内容和表格文本一致，仅有 Word run 分段格式差异。`_tmp_holiday_verify/bulletin_after_road_format_2026-10-01/02/03.docx` 为本轮核对产物。
- **数据操作**：只读核对，未导入、覆盖或重导任何数据。
- **状态**：待用户验收/提交。

### 10-04：快报百分比按 Excel 单元格显示精度后再取 1 位

- **用户确认的业务口径**：人工核对以 `2026年十一数据.xlsx` 单元格实际显示值为准。比如总计累计同比 2025 底层精确值为 `-4.448602%`，Excel 单元格格式为 `0.00%`，人看到并用于核对的是 `-4.45%`，再取快报 1 位小数就是 `-4.5%`。此前“直接按底层值取一位得到 -4.4%”的结论已作废。
- **实现**：`HolidayBulletinService` 新增 `bulletinPercent(...)`，严格按百分比来源单元格格式先取显示精度，再取快报 1 位小数；正文措辞与表格百分比共用同一逻辑。当前源表逐列口径：多数源单元格为 `0.0%`；`人员流动量汇总` 的当日环比 D/P/J、累计同比 V/W/Y/Z/AB/AC，以及水路当日环比 D 为 `0.00%`。
- **领导分析报告核对规则**：领导分析报告不套用快报的 1 位小数，一律按该报告自身显示的小数位核对，确保与人工在文档里看到的值一致。
- **验证**：新增/更新单元测试覆盖 `-4.448602%` 的 `-4.4%`（1 位源格式）与 `-4.5%`（2 位源格式），以及 `-0.045% -> -0.05% -> -0.1%` 边界；后端 `mvn test` 全部通过。重启 8090 后用真实库数据生成 2026-10-02 快报，正文和表格与已人工核对的模板逐项一致，总计累计同比 2025/2024 为 `-4.5% / -1.6%`。
- **本地验证产物**：`_tmp_holiday_verify/bulletin_excel_display_rounding_2026-10-02.docx`；功能测试报告与工作日结按本地留档规则写入 `docs/功能测试报告/`、`docs/工作日结/`，不入库。
- **状态**：代码和口径说明随本次提交推送；服务保持运行，访问 `http://localhost:8080`。

## 最新（2026-10-03）

### 【新对话先读】当前状态与下一步（2026-10-03 深夜写入）

- **代码状态（已推送）**：`HEAD = origin/main = f329f50`，内容为 `feat(observation): 新增观测站分日调查数据导入与明细查看`，用户已「验收通过」。工作区除本 HANDOFF.md 的交接更新（尚未提交，等用户确认）外，无其他已跟踪文件改动；仅剩未跟踪的 `_tmp_doc_compare/`、`_tmp_holiday_verify/` 和 `docs/专项统计/重要节假日/观测站分日调查数据 (2026年10月1日).xls`（过程产物与源数据，按约定保留、不入库、不删除）。`docs/专项统计/重要节假日/2026年十一数据.xlsx` 已由用户改回原名，模板下载接口实测 HTTP 200 / 36335 字节。
- **服务状态**：后端 8090、前端 8080 均在运行，访问 `http://localhost:8080`；登录 admin/admin123。数据库 `127.0.0.1:3305/traffic_audit`（root/root）。
- **库内数据**：节假日 2026-09-30（铁路/民航前一日）、2026-10-01、2026-10-02 已导入；**2026-10-03 尚未导入**。观测站 `observation_station_flow` 现有 2026-10-01（692 站）与 2026-10-02（689 站）。
- **下一步（2026-10-04 早上）**：10 月 3 日数据出来后，按既有口径导入 2026-10-03 并生成当天「湖北省国庆假期综合运输客流快报」。领导要求 8:30 前出第一版，而民航数据可能晚于 8:30 才有：民航未到就先出缺民航版本（累计同比只与往年已覆盖日期比较），民航到齐后重新导入并重新生成。完整口径与已验证结论见本文件 10-03 各段。
- **无自动化**：曾建的心跳提醒（id `10-03`）已按用户要求删除，用户 2026-10-04 明确「到时我会手工操作」。明天早上由用户手工导入 10-03 数据并生成快报，助手只在其提出时配合核对/排查。不要在未获用户明确要求时自行创建定时任务或自动写库。
- **数据发现（供参考，无需改代码）**：2026-10-02 比 10-01 少 3 个观测站——`G348L149420501` 土门（宜昌市/市辖区）、`S464L105422828` 大典河（恩施州/鹤峰县）、`S483L105420801` 屈家岭（荆门市/市辖区）。已核对两份源 Excel，确属源数据当天未上报，不是导入漏行。
- **长期待办**：见下方第七节「数值精度统一改造」（既有 16 张表、228 个 double 列改 `DECIMAL(30,15)` + Java `BigDecimal`）。

### 10-03 晚：重要节假日新模板（2019/前一日）适配
- **模板变化**：`2026年十一数据.xlsx` 的道路表增加 2019 年及同比2019；铁路、民航增加“前一日”行；快报模板增加同比2024 列。旧模板已放在 `docs/专项统计/重要节假日/备份/`。
- **数据库初始化**：启动时直接写入 2019 道路数据，以及 2024/2025/2026 年铁路、民航前一日数据；`holiday_calendar.day_index=0` 表示“前一日”，旧库启动会自动补齐已有年份的前一日配置行，且不覆盖管理员已维护的日期。
- **正常导入口径**：只读取所选年份的当年列（2026 年铁路/民航/道路/水路为 C 列、高速为 C 列、普通国省道为 D 列）；同时只额外读取当前年份铁路/民航的“前一日”行。2019/2024/2025 历史列不参与导入。
- **快报口径**：同比只使用 2025、2024；假期第 1 日的铁路、民航环比使用“前一日”数据，公路、水路、总计及其他口径第 1 日仍显示“—”；第 2 日起正常计算环比。
- **迁移脚本**：`docs/sql_holiday_previous_day_migration.sql`，部署包同步为 `deploy-templates/db/sql_holiday_previous_day_migration.sql`，脚本可重复执行。
- **2019 显示补齐（10-03 晚追加）**：`holiday_calendar` 增加 2019-10-01 至 2019-10-08 配置；系统配置-节假日管理和专项统计-节假日均增加 2019 年份，历史库执行幂等迁移后即可查看 2019 年 8 天道路数据。
- **验证（本机 3305 库 + 真实模板）**：接口导入结果 `passengerRows=10, vehicleRows=4, successRows=14, failRows=0`；数据库抽查 2026-09-30 铁路=82.1、民航=6.6994，2026-10-01 铁路=113.8、民航=6.7482、道路=78.82、水路=1.311，2026-10-02 铁路=82.0、民航=6.3914、道路=75.61、水路=3.3373；2026-10-01 快报铁路环比=+38.6%、民航环比=+0.7%，总行环比为“—”；2026-10-02 铁路环比=-27.9%、民航环比=-5.3%。
- **运行状态**：后端 8090（重启后已加载新代码）、前端 8080 均在运行；访问 `http://localhost:8080`。

### 10-03 深夜：快报表格百分比与模板样式修复（已验收）
- **问题**：生成快报表格使用“增长/下降”文字，数字拆行并多出 1 页；复核发现模板路径正确，根因是 `HolidayBulletinService#setCellText` 替换单元格时只保留段落属性，未保留模板 run 的字体/字号属性。
- **口径**：表格环比/同比改为带符号一位小数（正数不加 `+`，负数保留 `-`），零或一位小数后为零显示 `0%`，缺失/基数为空或为零显示 `—`；正文继续使用“增长/下降”。
- **修复**：单元格替换时继承模板 `rPr`；新增 `HolidayBulletinServiceTest` 覆盖正数、负数、零、四舍五入为零、缺失和零基数。
- **验证**：Maven 编译和测试通过；重新生成 2026-10-01 快报，正文仍为“增长2.3%”且不含“增长了”；Word 导出由 2 页恢复为 1 页，数字不再拆行。最终样报见本地 `_tmp_holiday_verify/bulletin_final_signed_styled_2026-10-01.docx`。
- **状态**：2026-10-03 用户验收通过；本次提交只包含代码、回归测试和本交接记录，不包含 `_tmp_*` 过程产物及用户未提交的数据文件重命名。

### 10-03 深夜（2）：缺当日民航数据时的累计同比对比期间修正
- **快报民航累计同比对比期间修正（2026-10-03，缺当日民航数据场景）**：当某运输方式当年累计覆盖的日期短于所选日期（典型为 10 月 2 日民航数据未出、民航累计只有 10-01），累计同比改为「只和往年已经覆盖到的日期比较」——先找当年最后一个有该指标数据的日期，再取往年同日累计。修复后缺失民航的 10 月 2 日快报民航累计同比由 `-50.5%/-49.9%` 变为 `-10.0%/-0.9%`（与手工稿 -10.03%/-0.87% 的 1 位小数值一致）。实现见 `HolidayBulletinService.comparableCumulative`（仅作用于民航行），其余行与总人员流动量口径不变。
- **「累计同比 -4.65% vs 快报 -4.6%」结论（2026-10-03，无需改代码）**：Excel 显示的 -4.65% 是**两位小数**结果；底层精确比值是 `-4.64633%`（2026 累计 3082.23818、2025 累计 3232.42742），**一次四舍五入到 1 位小数就是 -4.6%**。把已经取到两位小数的 -4.65 再取一位才得到 -4.7，属二次取整，不采用。同理 2026 对 2024 为 `-1.7710%` → `-1.8%`。快报百分比统一 1 位小数口径不变。
  - **2026-10-04 修正**：按 Excel 单元格显示精度口径，`-4.65%` 再取一位应为 `-4.7%`；以文件顶部最新段为准。
- **「暂缺民航」提示**：用户确认由人工在生成的快报稿上修改，系统不生成该提示行，**不做代码改动**。
- **验证**：`HolidayBulletinServiceTest` 3 个用例通过（新增 2 个覆盖民航累计对比期间与无数据返回 null）；端到端用库内真实 2026-10-02 数据（铁路/道路/水路/车流齐全、缺民航）重新生成快报，民航累计同比 `-10.0%/-0.9%`、民航累计 `6.75`、总计累计 `3082.24`、总计累计同比 `-4.6%/-1.8%`，与手工稿口径一致。
- **Git**：本次改动待用户「验收通过」后再提交/推送。

### 10-03 深夜（3）：快报累计正文单位由「亿人次」改「万人次」（待验收）

- **口径（用户/领导确认）**：假期累计数值目前偏小（0.31 亿），正文可读性差，改为与当日一致的**万人次**；例如 `假期以来，全省全社会跨区域人员流动量累计3088.63万人次`，不再输出「0.31亿人次」。表格与其余口径不变。
- **实现**：`HolidayBulletinService` 抽出 `cumulativeParagraph(...)`，直接按万人次（2 位小数）输出累计值；同比仍为「增长/下降 + 一位小数」，**保持一次取整不变**（该处 2026-10-04 已修正：源单元格为 `0.00%`，Excel 显示 -4.45%，再取一位为 -4.5%；以文件顶部最新段为准）。
- **验证**：`HolidayBulletinServiceTest` 4 个用例通过（新增 `cumulativeParagraphUsesWanUnitAndSingleRounding` 固化「万人次 + 一次取整」）；重启后端后重新生成 2026-10-02 快报，正文为 `累计3088.63万人次，比2025年同期下降4.4%，比2024年同期下降1.6%`，与手工稿仅差既定的取整口径；2026-10-01 回归正常（`累计1643.17万人次`）。
- **状态**：待用户「验收通过」后提交/推送。

### 10-03 晚（4）：新增「观测站分日调查数据」原始数据导入（待验收）
- **背景（用户 2026-10-03 提出）**：普通国省道车流量的来源之一是观测站分日调查数据（模板 `docs/专项统计/重要节假日/观测站分日调查数据 (2026年10月1日).xls`，其中字段「中小客流量」即普通国省道车流量来源）。**系统内不做关联**，节假日统计仍走原有导入；本功能只做原始数据留存，为后续分析挖掘积累数据基础。
- **数据表**：新增 `observation_station_flow`，DDL 见 `docs/sql_observation_station.sql`，部署包同步为 `deploy-templates/db/sql_observation_station.sql`。保留模板全部 26 列（观测站编号/名称/观测里程/地市/区县/行驶方向 + 各车型流量 + 客车/货车/汽车/机动车流量 + 各类当量 + 机动车速度 + 拥挤度 + 来源文件名）。唯一键 `(obs_date, station_code, direction)`；**数值列一律 `DECIMAL(30,15)`**，Java 实体字段一律 `BigDecimal`，与节假日表同口径，无 float/double。
- **导入实现**：新增包 `com.trafficaudit.observation`（entity / mapper / dto / service / controller）。用 POI `WorkbookFactory` 同时支持 `.xls` 和 `.xlsx`；**表头按列名匹配**（列顺序变化不影响导入），扫描前 10 行定位表头；日期兼容 Excel 日期格式与 `yyyy-M-d`/`yyyy/M/d`/`yyyyMMdd`/中文年月日；同一日期**重复导入即整体覆盖**（先删该日期再插入），幂等。
- **接口**：`POST /api/observation/import`、`GET /api/observation/dates`（按日期汇总站数、中小客流量合计、最近导入时间）、`GET /api/observation/rows?date=&limit=`、`POST /api/observation/delete?date=`。
- **前端**：`traffic-audit-web/src/views/HolidayStat.vue`（专项统计 - 节假日）新增「观测站分日调查数据」卡片：选择文件 → 导入 → 按日期汇总表 → 查看明细（弹窗）→ 删除。
- **实测（真实模板，本机 3305）**：导入 692 行 / 692 站 / 0 跳过 / 0 失败；三项合计与源文件逐项一致（中小客流量 3,523,873、机动车流量 5,487,965、机动车当量 7,140,575）；**692 行 × 25 字段全量逐行比对 0 处不一致**；中文（站名/地市/区县）落库无乱码；重复导入仍为 692 行（覆盖而非累加）；上传非 Excel 返回明确错误。旁证：692 站中小客流量合计 3,523,873 辆 = 352.3873 万辆，与 2026-10-01 节假日「普通国省道」入库值完全一致，印证了数据来源关系。
- **顺带修复**：`pack-deploy.ps1` 把 db 脚本复制进包内 docs 的清单里漏了 `sql_holiday_previous_day_migration.sql`，本次一并补上 `sql_observation_station.sql`；`deploy-templates/README-部署说明.txt` 的 db 清单同步更新。
- **10-03 深夜追加（观测站界面微调）**：①「查看」明细弹窗按模板表头展示原始数据全部字段（观测日期/站号/站名/里程/地市/区县/方向 + 全部车型流量、客货汽车机动车流量、各类当量、速度、拥挤度，另附来源文件名，共 27 列，横向滚动）；②汇总表「中小客流量合计」单位由辆次改为**万辆次**、保留 4 位小数（`formatWanVehicles`，如 3,523,873 → 352.3873）。前端 dev server 已热更新编译通过。
- **10-03 深夜追加（观测站列表/明细修正）**：①**明细行序**原来按 `stationCode` 排序，与 Excel 行序对不上，改为按导入顺序（`id ASC`，即 Excel 行序），便于逐行比对；②明细**列顺序**与模板 26 列完全一致（末尾附来源文件名）；③**观测里程/机动车速度/拥挤度**改为按原始小数显示（`formatPlain`，去尾零，如 50.92 / 43.882 / 0.777 / 58），不再固定 2 位；④**17 个流量与当量列**改为整数显示（`formatInteger`，如 6413），与 Excel 一致；⑤汇总列表「观测日期」改为**正序**（mapper `ORDER BY obs_date ASC`）。已用 10-01/10-02 真实数据验证行序与 Excel 前 5 行一致（中帮/万店/沼山站/邾城站/白云）。
- **状态**：待用户「验收通过」后提交/推送。

---

### 补充（10-03 下午）：服务器部署报 “Access denied ... (using password: NO)” —— 根因与修复
- **现象**：把 `deploy/traffic-audit-release-20261002/` 部署到 `61.183.254.94` 后，后端启动报 `java.sql.SQLException: Access denied for user 'root'@'localhost' (using password: NO)`。
- **根因**：jar 内置配置里库口令是占位符 `${TRAFFIC_DB_PASSWORD:}`（默认空串），而 10-02 那个包**只含 jar + web + dist**，没有外置 `application.yml`、没有 `docs/`、`db/`、启动脚本。部署机没有任何外部配置覆盖，Spring 就拿空密码连本机 MySQL → `using password: NO`（注意：这是“末传密码”，不是密码错）。
- **服务器侧一步修复（无需重打包）**：在 jar 同级放 `application.yml`，把 `spring.datasource.url/username/password` 改成现场真实值后重启即可；也可用环境变量 `TRAFFIC_DB_PASSWORD` 代替。启动脚本已加预检提醒（缺 `application.yml` / password 仍是占位文字都会 WARN）。修复后若报“未找到数据目录 docs”则说明包内缺 `backend/docs`，从新包或源机器拷。
- **打包工具已修（原 “打包工具待修” 两项均已落实）**：`pack-deploy.ps1` 重写为五步：① 用新增模板 `deploy-templates/jar-application.yml`（**全占位符**）临时替换源码配置后 `mvn clean package`，无论成败都还原真实配置；② 解压 jar 去密自检；③ 前端构建；④ 组装**完整包**：`backend/{jar, application.yml, start-backend.cmd/.sh, docs/, web/}` + `frontend/dist` + `db/*.sql` + README（`backend/web` 从 dist 自动同步，逐文件一致）；⑤ 整包明文密钥扫描。新增 `-SkipBackend` 可复用现有 jar 快速重组包。
- **模板同步修正**：`deploy-templates/backend/application.yml` 的 `server.port` 由 8080 改回 8090（原值会导致后端起在 8080）、补 `static-locations: file:./web/` 与 password 陷阱注释；`README-部署说明.txt` 常见问题新增该报错处置；`docs/打包部署说明.md` 排错表新增该行；`application.yml.example` 环境变量名统一为 `TRAFFIC_DB_USER/TRAFFIC_DB_PASSWORD/TRAFFIC_JWT_SECRET`（原来误用 `MYSQL_PASSWORD`/`JWT_SECRET`，与 `start-dev.ps1` 不一致）。
- **新包（本地，不入库）**：`deploy/traffic-audit-deploy-20261003/`（388 文件 / 93.07 MB，zip 76.37 MB），已验证：jar 内置配置全占位符（去密自检通过）、`backend/web` 与 `frontend/dist` 逐文件一致（各 44 个）、`backend/docs/生成汇总大表` 母版存在、`功能测试报告/工作日结/问题汇总/_cache` 已排除。
- **踩坑（重要）**：本机 PowerShell 5.1 把无 BOM 的 `.ps1` 当 ANSI 读，中文注释会变成乱码并导致脚本解析失败。`pack-deploy.ps1` 必须保存为 **UTF-8 with BOM**（仓库其他 `*.ps1` 也都是 BOM）；排查中曾实际踩到。

- **运行状态（写交接时）**：后端 8090、前端 8080 均未监听；新对话如继续开发或测试，先执行 `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`。数据库仍为 `127.0.0.1:3305/traffic_audit`，MySQL 服务未停。
- **发布构建（已完成）**：应“发布编译”要求，已完成后端 `mvn clean package -DskipTests` 和前端 `npm run build`。jar 内已做去密自检，只保留环境变量占位符；构建后本机真实 `src/main/resources/application.yml` 已原样恢复。
- **发布产物（本地，未入库）**：
  - 后端 jar：`traffic-audit-server/target/traffic-audit-server-1.0.0-SNAPSHOT.jar`（约 54.6 MB）
  - 前端：`traffic-audit-web/dist`（44 个文件、约 3.55 MB）
  - 发布目录：`deploy/traffic-audit-release-20261002/`（含 `backend/`、`frontend/dist/`）
  - 发布压缩包：`deploy/traffic-audit-release-20261002.zip`（约 51.11 MB）
- **发布包结构说明**：`frontend/dist` 是标准前端发布目录；`backend/web` 是同一份 dist 的副本，用于后端 8090 单端口模式（当前静态资源路径为 `file:./web/,classpath:/static/`）。两处已逐文件比对，文件列表与 SHA-256 完全一致。
- **安全状态**：本机真实配置已保存在被忽略的 `traffic-audit-server/config/application.yml`；发布 jar 不含真实数据库口令、JWT secret 或 DeepSeek key。发布包不包含部署机的真实外部配置，部署时需要继续使用现场 `application.yml` 或按模板填写。
- **打包工具待修（重要）**：`pack-deploy.ps1` 目前直接消费 `src/main/resources/application.yml`，若该文件被本机真实配置覆盖，会在去密自检阶段中止；且它只把 dist 放到 `frontend/dist`，没有同步到 `backend/web`，默认包无法直接用于 8090 单端口模式。本次使用“临时占位符配置 → 构建自检 → 恢复真实配置”的方式完成。下次发布前建议改为从 `application.yml.example` 生成临时资源，并在组装阶段同时复制 `backend/web`。
- **Git/工作区（本段更新前）**：`HEAD = origin/main = 37f5209`；当前无已跟踪文件改动。未跟踪项有 `_tmp_holiday_verify/`（历史验证产物）和 `docs.zip`（约 31.6 MB，用户本地产物）；二者均保留，新对话不要误删或误提交。
- **下一步**：如需部署，直接使用上面发布目录或 zip；如需继续修复发布工具，先实现“占位符模板自动切换 + `backend/web` 自动组装 + jar 去密自检”后再重新产出发布包。

### Windows 开机自启（10-03 追加，用户选“方案 B”：注册成 Windows 服务）
- **先回答过的问题**：`start-backend.cmd` **不能**直接做开机自启（末尾有 `pause`、无日志重定向、依赖 PATH）。给出 A（计划任务）/B（Windows 服务）/C 三方案后，用户选 **B**。
- **新增模板（已入库）**：
  - `deploy-templates/backend/trafficAudit.xml`：WinSW 服务配置——id `TrafficAuditBackend`、`startmode=Automatic` + `delayedAutoStart=true`（等 MySQL 先就绪）、`onfailure restart 10s/30s/60s` + `resetfailure 1 hour`、`workingdirectory=%BASE%`、日志 `logs\trafficAudit.out.log|err.log`（10MB × 10 滚动）。
  - `deploy-templates/backend/install-service.ps1`：管理员安装/查看/重启/删除（`-Status/-Restart/-Remove/-NoStart/-JavaPath`）；自动定位 java（JAVA_HOME → PATH → JavaSoft 注册表 → Program Files）并把绝对路径写进 XML 的 `executable` 元素；重复执行幂等；非管理员直接拒绝。
  - `start-backend-service.cmd` + `install-autostart.ps1`（计划任务方式）保留为**备选**；注意 `New-ScheduledTask*` 需 Win8/Server 2012+，且**不可与服务方式同时启用**（会抢 8090）。
  - `pack-deploy.ps1`：新增 WinSW 获取（缓存 `deploy-templates/tools/winsw.exe` 并校 SHA-256，缺则从 GitHub 下载 v2.12.0 x64）与 `-SkipServiceWrapper`；包内输出 `backend\trafficAudit.exe`（改名以匹配 XML 文件名）。`.gitignore` 新增 `deploy-templates/tools/`（17.4MB 二进制不入库）。
- **WinSW = Windows Service Wrapper**：把普通程序包成 Windows 服务。java.exe 自己不是服务程序，直接 `sc create` 会报“服务没有及时响应启动或控制请求”；WinSW 实现了服务控制协议再拉起 `java -jar`，并管重启与日志。
- **实测验证（本机，未真正安装服务）**：`trafficAudit.exe status` 能读打包 XML 并输出 `NonExistent`（解析通过）；故意写坏 XML → `FATAL - The configuration file cound not be loaded`（证明该校验路径真实有效）；`install-service.ps1 -Status` 正常输出“未安装”，无参数 / `-Remove` 在非管理员下抛“必须管理员”且不产生注册项。
- **踩坑（重要）**：XML 改写最初用正则 `(?s)<executable>.*?</executable>`，会**先命中注释里的 `<executable>` 字样**，把注释头与 service 开头整段吞掉 → XML 非法。已改为 DOM（`SelectSingleNode('/service/executable')`）并把注释里的裸标签改掉。另：新增打包代码曾多一个 `}` 导致语法错，已用 `Parser::ParseFile` AST 复核，两个 ps1 现在语法 OK 且均为 UTF-8 with BOM。
- **兼容性（用户问“Win7/Win10/Win11/Server 是不是都可以”）**：服务机制完全一样（自动启动/延迟启动/失败重启都是系统能力），差别只在包装器依赖什么运行时。实测二进制：`WinSW-x64.exe` 2.12.0 是**自包含 .NET 6 单文件**（含 `singlefilehost`/`System.Private.CoreLib`/`Microsoft.NETCore.App 6.0.13`/`net6.0`），**不需要装 .NET Framework**；老系统（Win7 SP1/2008R2/2012R2）若报 `api-ms-win-*.dll` 缺失，可换官方 `WinSW.NET461.exe`（0.6MB，需 .NET 4.6.1+，改名成 `trafficAudit.exe` 即可，XML 不动）；32 位系统换 `WinSW-x86.exe`。
- **安全提示**：WinSW 官方产物**未做 Authenticode 签名**（本机 `Get-AuthenticodeSignature` = NotSigned），因此以固定 SHA-256 作完整性校验：`05B82D46AD331CC16BDC00DE5C6332C1EF818DF8CEEFCD49C726553209B3A0DA`（与 GitHub 发布资产 18,243,033 字节一致）。
- **未验证项（需在目标机做一次）**：本机当前不是管理员，**没真正 install 过服务**；开机自启、失败重启、日志滚动要在服务器上按 README 3.1 执行一次确认。
- **新包（本地，不入库）**：`deploy/traffic-audit-deploy-20261003-3/`（393 文件 / 110.49 MB，zip 83.77 MB）。已验证：服务三件套在 `backend\`、包内 `trafficAudit.exe` SHA-256 与固定值一致、`backend\web` 与 `frontend/dist` 各 44 文件、jar 去密自检通过、无明文 key。**旧的 `traffic-audit-deploy-20261003/` 与 `-2/` 已被取代**，部署请用 `-3`（旧包待用户确认后再删）。
- **运行状态（写本条时）**：开发用后端 8090（PID 43040）、前端 8080（PID 43152）均在跑；数据库 `127.0.0.1:3305/traffic_audit`。
- **补充可操作性（用户反馈“backend 下文件太多，不知道怎么操作”）**：
  - 新增双击入口 `deploy-templates/backend/install-service.cmd`：自动 UAC 提权 → 调 `install-service.ps1`；若找不到 `trafficAudit.exe` 则提示“必须整个 backend 一起拷”。
  - `install-service.ps1` 装完会自己探测端口（TCP 探测，兼容 PowerShell 2.0），打印 OK + 本机/对外网址；起不来时直接打印 `logs\*.log` 最后 15 行；若 `application.yml` 口令仍像占位符，最后再打一次醒目提示。
  - `README-部署说明.txt` 顶部新增【服务器上只要做这 3 步】+“哪些要拷/哪些不用拷”；`docs/打包部署说明.md` 的 5.4 改为“右键 `install-service.cmd` →以管理员运行”。
  - 三个 `.cmd` 模板统一为 CRLF（新增的两个原来是 LF，批处理在 Windows 上应用 CRLF）。
  - 实测：强制走“已提权”分支时 `cmd → install-service.ps1 -Status` 链路跑通、`%*` 传参正常；`Test-LocalPort` 对 8090 返回 True、对 8099 返回 False。
  - 新包：`deploy/traffic-audit-deploy-20261003-4/`（394 文件 / 110.50 MB，zip 83.78 MB）——**当前唯一可用包**。
- **发布包清理（10-03 晚，用户确认“只留 -4”）**：已删除 `traffic-audit-release-20261002/`(+zip)、`traffic-audit-deploy-20261003/`(+zip)、`-2/`(+zip)、`-3/`(+zip) 及空的 `server-fix/`，`deploy\` 现在只有 `traffic-audit-deploy-20261003-4/` 和它的 zip（释放约 671MB）。
  > 因此本文件上面提到的 `deploy/traffic-audit-deploy-20261003/`（388 文件）与 `deploy/traffic-audit-release-20261002/` 均为**历史记录**，磁盘上已不存在，别再去找。
- **紧急修复（10-03 晚）：`install-service.ps1` 密码解析崩溃，服务根本没装上**
  - 现象：用户在服务器（`D:\trafficAudit`）双击 `install-service.cmd`，报 `无法将“Trim”的参数“trimChars”转换为类型“System.Char”`，位置 `install-service.ps1:210`。
  - 根因：那行是 `.Trim(' ''', '"')`，其中 `' '''` 被 PowerShell 解析成一个**长度 2 的字符串**（空格 + 单引号），`Trim(char[])` 无法把 2 字符串转成单个 char → 整行抛异常（`MethodArgumentConversionInvalidCastArgument`）。
  - 修复：把这段抽成纯函数 `Test-AppConfigPassword`，改写为 `Trim()` → `Trim("'")` → `Trim('"')`；并加脚本级 `trap`，任何异常只打印一行说明 + 行号，不再甩红字堆栈。
  - 验证：8 个样本（缺文件 / 空值 / 中文占位符 / 裸值 / 双引号 / 单引号 / 含空格特殊字符 / 真实模板文件）全部符合预期；打包内脚本语法解析通过、`-Status` 实跑正常、非管理员时 trap 输出干净错误并 exit 1。
  - 教训：这条分支之前没被任何测试覆盖（`-Status` 提前 exit、非管理员在 `Assert-Admin` 就退出），所以解析类逻辑要抽成纯函数并用样本测。
  - 包名：修复版重打包时脚本复用了已释放的基础名，最终已删掉旧坏包并改名，`deploy\` 仍然是**唯一**的 `traffic-audit-deploy-20261003-4\`（含修复后的 install-service.ps1）与同名 zip。
  - 用户侧最小修复：只需用新包里的 `backend\install-service.ps1` 覆盖服务器 `D:\trafficAudit\install-service.ps1`，再重跑 `install-service.cmd`（不必重拷 110MB）。
- **服务器部署成功（10-03 晚，用户确认）**：服务器（部署目录 `D:\trafficAudit`，把 backend 里的内容直接铺在该目录下）用修复后的 `install-service.cmd` 安装服务 `TrafficAuditBackend` 成功。
  - **已验证（用户确认）**：① 办公电脑浏览器能打开服务器页面（说明网络/防火墙这一层通，无需额外放行 8090）；② **重启服务器后仍能从办公电脑打开页面 → 开机自启实测生效**（服务不依赖任何账号登录）。
  - **仍待做**：业务功能验收（登录 / 数据导入 / 报表导出 / Word 快报）；确认 `application.yml` 的 jwt.secret 已换成正式随机值、预置 admin/admin123 已改密。
  - 防火墙放行（老系统也能用）：`netsh advfirewall firewall add rule name="TrafficAudit 8090" dir=in action=allow protocol=TCP localport=8090`
  - 装完后常用：`install-service.ps1 -Status / -Restart / -Remove`；日志在 `D:\trafficAudit\logs\trafficAudit.out.log`（错误看 `trafficAudit.err.log`）。

## 最新（2026-10-02）

- **新模块（用户已验收，本次提交/推送）**：新增“专项统计-重要节假日”模块，含节假日配置、营业性客流、非营业性车流、客运系数 4 张表；系统配置菜单仅 admin 可维护，专项统计-节假日支持导入、导出、模板下载和 Word 快报下载。
- **数据初始化**：从 `docs/专项统计/重要节假日/2026年十一数据.xlsx` 初始化 2024/2025 年十一客流、车流和 2024-2026 年客运系数；源表 90 个数据单元格入库逐项比对差异 0。
- **日常导入口径**：只读取所选年份的当年列（2026 年为各客流工作表 C 列、普通国省道 D 列）；历史年份不要求日常重导。
- **历史数据保护**：导入时先检查更早历史日期是否被修改。有变化则先不写库，返回差异清单，前端弹窗让用户选择“允许导入/不允许”；确认后才覆盖。接口参数 `allowHistoricalOverwrite=true`。
- **快报**：默认下载系统日期前一天的《湖北省国庆假期综合运输客流快报（10月X日）.docx》，用户可自选日期；环比/同比按增长、下降、持平输出。
- **Excel 浮点精度（2026-10-02 追加）**：参考 `docs/Excel浮点数存储.txt`，新增 `HolidayNumberUtils`（`NumberToTextConverter.toText` + `BigDecimal`，`MathContext(15, HALF_UP)`）；节假日模块由 `Double` 全面改 `BigDecimal`；三张表数值列改 `DECIMAL(30,15)`；库内 6 条客运系数由 2.3999999999999995 校正为 2.4。迁移脚本 `docs/sql_holiday_decimal_migration.sql`。
- **菜单顺序**：“专项统计”已移到“报表生成”之后，当前为 报表生成 -> 专项统计 -> 规则管理 -> 用户管理 -> 系统配置。
- **节假日删除复活修复（2026-10-02 追加）**：原初始化逻辑每次启动补齐缺失的第 N 日，导致 admin 删除 2026-10-08 后被重新插入；现改为仅 `holiday_calendar` 整表为空时首次初始化。重启后 2026 年十一保持 10-01 至 10-07 共 7 天。
- **普通国省道环比基期（2026-10-02 追加，2026-10-06 方案 D 已修正）**：C 列语义最终确定为“下一日环比分母的调整值”；填写后只影响下一日的环比分母，不影响 C 所在日及累计、走势图。`holiday_vehicle_flow.comparison_base` 已入库，导入导出与历史变更确认均已接入。
- **快报首日口径（2026-10-02 追加）**：假期第1天没有前一日环比基数，正文不输出“环比增长/下降/持平”短语，表格当日环比列为“—”；第2天起仍按实际前一日输出环比。已用 2025-10-01/02 快报回归验证。
- **快报百分比精度（2026-10-02 追加）**：Word 快报中同比/环比百分比统一保留1位小数（如6.79%显示6.8%、11.46%显示11.5%）；人次、车流等业务数值仍保留2位小数。
- **验证结果**：后端编译、前端构建、权限/CRUD/负向导入、历史变更两阶段导入、Excel 导出、Word 快报、前端 admin/非 admin 烟测均通过；菜单顺序、客运系数 2.4 展示（系统配置页 + 节假日统计页）、`decimal(30,15)` 列型、历史变更两阶段导入回归均已实测；功能测试报告与工作日结按 2026-09-27 提交规范仅本地留存（不入库）：`docs/功能测试报告/功能测试报告_重要节假日专项统计_2026-10-02.md`、`docs/工作日结/工作日结_2026-10-02.md`。
- **运行状态**：后端 8090、前端 8080 已启动；数据库 `127.0.0.1:3305/traffic_audit`。测试产生的 2026 临时数据和导入批次已清理。
- **关机收尾（2026-10-02）**：已停掉本次开发用后端 8090、前端 8080 及各自进程树，端口均已释放；MySQL 服务保留。当前可安全关机。
- **Git**：用户已于 2026-10-02 明确验收通过；本次按要求合并远端 `origin/main` 后提交并推送，不覆盖远端同事提交。
- **部署模板同步**：节假日 4 张表已同步到 `deploy-templates/db/init.sql`；`sql_holiday.sql` 及两个旧库迁移脚本随部署包发布，避免新包缺表。

## 最新（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）。
- **09-28 收尾：`班线包车` 3 格重算问题已修**：`EO36`/`FN36`/`FO36` 在母版里改为**静态值**（0.181777001400256 / 2312.2199 / -0.586418964965219，与手工定稿一致），并把受影响的共享公式组孤儿子格（35 格）一并静态化（值零变化）。重新生成验证：生成件/母版/定稿三边一致，与上一版生成件仅 34 格为精度表示差异、无数值变化。
- **当前"需处理"仅剩 16 条**（均属手工侧/业务已确认，非程序问题）：` 货运` EA92~EA112 共 12 条（2022 各市州累计同比，2021 年基数口径不同，业务已确认软件对；含手工 `#DIV/0!` 2 条）、`班线包车` IL4/IL5（手工 `#REF!`）/IL50（手工反引号）3 条、`城市汇总!G20` 表头措辞 1 条。其余全部按口径忽略（草稿列/行号偏移/当月块/浮点尾差/文本型数字）。
- **未清项（有意保留）**：母版 11 个 `#REF!` + 356 个 `#DIV/0!` 历史错误值未清——手工定稿同类约 15 + 358，单清一边会凭空多出单边差异；要清需两边一起。
- **确认差异清单（本地）**：`docs/问题汇总/_已确认差异清单_2026-08_20260928.md`（不入库）。
- **09-28 口径全部落地，差异清单"需处理"归零**：
  - ① 按软件：手工定稿《 货运》EB64~EB78 等 12 格 2022 累计同比 + 《班线包车》IL4/IL5/IL50 已按软件值同步（备份 `2026年8月客运量、货运量定稿_同步软件前_20260928.xlsx`）。
  - ② 按手工统一措辞：母版《城市汇总!G20》改为手工写法"2025年1-12月全省累计完成城市客运量情况"（备份 `_bak_202608母版_0928措辞前.xlsx`）。
  - ③ 历史错误值留白：母版 363 格（`_bak_202608母版_0928留白前.xlsx`）、手工定稿 379 + 尾列 6 格（`..._留白尾列前_20260928.xlsx`）→ 两边现均为 0 个 `#REF!`/`#DIV/0!`。
  - 结果：按当前母版重新生成 2026-08 后，与手工定稿的**需处理差异 = 0**，其余全部落在"已忽略（约定差异）"。清单：`docs/问题汇总/_清单_母版最新生成件_20260928.md/.csv`（本地，不入库）。
  - 注意：桌面那份 `生成_道路运输量汇总表_2026-08.xlsx` 是旧导出（含旧错误值/旧基数），与更新后的定稿比对会显示较多差异，以"母版重新生成件"为准。
- **无表头草稿列清单（9 处，共 539 格）**：`公交/出租/网约车!U`（各 72）、`城市客运!U`（36）、`班线包车!DU`（55，表头"1-3月累计"）、`中口径明细!U`（90）、`中口径客运量!AB`（180）、` 货运!V` 与 ` 货运!AX`（各 74，用户所指 U 列在手工那份右移一列）。母版/生成件**已全部清空**，手工定稿仍保留 → 对比时归入「已知设计(无表头草稿列)」。其余"无表头列"是合并表头的正常列（` 货运!C…Q` 月份值列、各年块尾部累计/累计同比列、排名页 R 列等），两边都有、非草稿。明细见 `docs/问题汇总/_已确认差异清单_2026-08_20260928.md`。
- **待办**：① 排名页结构（块顺序、标题措辞、市州名短名/全名、周转量排名多 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`**）。
- LoginController：`captchaRequired=false` 时登录不校验验证码；新增公开接口 `GET /api/auth/captcha-config` 返回 `{required}`。
- Login.vue：启动时拉取该配置；`required=false` 时隐藏验证码区域并显示「测试模式：行为验证码已跳过」提示，登录跳过验证；配置请求失败时默认按启用处理（安全兜底）。
- 已实测：captcha-config 返回 required=false；admin/admin123 不带验证码直接登录 200；后端 mvn compile ✅、前端 npm run build ✅。
- ⚠️ 需重新打包才在测试环境生效；正式发布时把 `app.captcha.required` 改回 `true`。

### 2. 数据导入浏览器崩溃排查（进行中，用户线索更新）
- **【08-31 根因实锤更新】真正崩溃根因已找到：数据导入页 `<el-tabs>` 触发 Element UI 布局无限循环（详见下面第 4 节，commit 684da41）。此前「线程池占满/batches pending/慢上传」是另一条可复现机制，但不是用户场景的实锤根因；`/import/batches` pending 只是**表象**——el-tabs 布局风暴阻塞主线程后，页面后续请求（含 batches）全部发不出去/排队，表现为「batches pending + 浏览器无响应」。修复 el-tabs 后 dev 与打包形态均正常。
- 用户补充：共 3 台机器出现（对方开发机 + 昨天打包测试 1 台 + 今天 1 台）；对方记录的「迅雷/驱动」是其主观判断；现象时好时坏、每台约 1/3 用户崩。
- 已排除：/import/batches（limit≤200、81 条约 17KB）；进入页面无轮询/定时器。
- 用户怀疑「目录导入（浏览/扫描目录）」→ 已加固（见下）。注意：该功能需用户主动打开目录浏览/点目录导入才触发，与「点数据导入菜单就崩」现象不完全吻合，**待用户确认崩溃时点的具体按钮**。
- 加固（已完成，编译/构建通过）：后端 `listDirs` 子目录/文件列表各限 300（新增 `dirsTruncated`/`filesTruncated` 标记，`excelCount` 仍为真实总数）；前端「从目录批量导入」每批限 60 个文件（超限提示分批）；目录浏览弹窗显示截断提示。
- 待办：让崩溃机器用户在 Chrome 开 `chrome://crashes` 记下原因码（OOM / GPU / STATUS_ACCESS_VIOLATION 等），并确认崩溃时点的是侧边栏「数据导入」菜单还是页面上某个按钮；据此决定下一步。
- **重大进展（08-28 下午）**：
  - ~~请求根本没到后端~~（旧结论，已被推翻）：用户后来确认 **chunk JS 4ms/7ms 正常，pending 的是 `/api/import/batches` 接口**（页面已进入，loadBatches+loadOverview 两个 batches 请求全部 pending）；后端无日志=请求卡在 Tomcat 连接/线程层、未执行到 SQL。
  - 用户描述补充：点侧边栏「数据导入」菜单 → 无反应、停留主页 → 浏览器弹「应用程序无反应，是等待还是退出」= 渲染/浏览器进程 hang，非 crash。
  - 发布机器才是用户运行环境；本机 D:\trafficAudit 仅打包测试（17:39 后停止，日志正常）。
  - **本地打包形态压测（headless Chrome，20 轮菜单切换）**：导航 17~89ms、0 JS 错误、DOM 恒 949 节点无累积、堆内存 11~37MB 无泄漏、最长长任务 80ms → 应用 JS 层无死循环/大计算/泄漏。
  - **已加 Tomcat 访问日志**（`server.tomcat.basedir: .` + accesslog，jar 同级 `logs/access.*.log`，pattern 含 `%D` 耗时，静态资源也记录）——本地实测 chunk 请求 3ms。**重新打包发布后**，下次崩溃看 access log：chunk 请求是否到达、耗时多少 → 直接定位「服务器慢」还是「客户端没发出请求」。
  - 待用户：重新打包发布后，崩溃时看 ①服务器 `logs/access.*.log` ②客户端 F12 Network 中 `chunk-*.js` 请求状态（pending/stalled/耗时）。
  - **机制可复现（本机实验，非实锤）**：Tomcat 9 NIO 下慢连接不占线程（slowloris 无效，已测），但**慢速 multipart 上传会占线程**——240 个慢上传占满线程池后，chunk 与 batches 请求全部 pending/超时（与用户现象一致）。**数据导入是同步长任务**（4 万行导入占 1 个线程 5 分钟，前端超时 600s），多用户同时导入/目录导入串行 → 200 线程耗尽 → 新请求（batches、静态文件）排队 pending → 浏览器等 →「无响应」弹窗。**只崩数据导入页**因为它进页即发 2 个 batches 请求且用户多在导入场景操作；其他页面在同样时刻也会 pending 只是未被注意。
  - **修复（commit 728b372，已验证）**：① `server.tomcat.threads.max: 500`（application.yml + example）；② 数据导入页 `loadBatches`+`loadOverview` 合并为 `loadData`（进页/刷新/导入后只发 1 个 limit=200 请求，表格取前 50，概览复用同批数据）。**修复验证**：同样 240 慢上传压力下，batches 0.2s、chunk 0.1s 正常。
  - **遗留（建议下一步根治）**：导入异步化（@Async 独立线程池执行导入、前端轮询进度），彻底不占 Tomcat 请求线程；或 nginx 托管静态资源。对方 dev 机单用户也 pending，需看对方后端日志（可能 DB 连接/锁，或对方当时在跑导入），与本修复不冲突。
  - **用户反驳（08-28 晚）→ 线程池耗尽不是当前场景实锤根因**：崩溃时仅 3 个用户（1 人已登入、1 人未登入、1 人登入后即出问题），时间上不可能占满 200 线程。线程池 500 + batches 合并的修复仍有效（降低同类风险），但不要对用户宣称根因已实锤。真正待取证：重新打包发布后崩溃时看 ①服务器 `logs/access.*.log`（chunk/batches 是否到达、%D 耗时）②对方 dev 机（单用户也 pending 的复现机）后端日志（是否 DB 连接/锁/SQL 卡住）。

### 3. 前端 API 全局超时保护（已完成并推送 commit 41487b9）
- 背景：用户要求所有向后台的 API 请求都加超时保护，超时优雅提示（网络/服务器异常），不要无限 pending。
- 实现：`src/api/index.js` axios 实例默认 `timeout: 15000`；响应拦截器里 `ECONNABORTED` → 弹「请求超时：服务器繁忙或无响应，请稍后重试」、无 `response` → 弹「网络异常：无法连接服务器」，并给 error 打 `_toast` 标记，页面 catch 里 `if (e && e._toast) return` 避免重复弹；401 跳登录逻辑不变。
- 长耗时请求显式覆盖：文件上传 600s/300s（原有）、`/audit/execute` 120s、`/audit/review` `/audit/markAudited` `/explain/save` 60s、`/llm/chat` 120s、报表导出 120s、报表预览/就绪 60s、验证码接口 10s、登录 15s。
- 覆盖文件 11 个（api/index.js、AiChatDialog、Captcha3D、AuditResult、DataImport、DataView、ExplainReview、Login、ReportExport、RuleManage、UserManage），node24 构建通过，已提交推送。

### 4. 菜单/布局与强制登录全部解决（已推送）
- 用户反馈 4 个问题：①点「审核结果」菜单不高亮；②企业解释/用户管理顶部没有统一横栏；③某些页面退出登录不显示；④关标签页/浏览器后重开要求强制登录。四项均已完成并实测通过！
- ②③（commit 2bd663b）：ExplainReview.vue 重复 `components` 键覆盖（`{ AppHeader }` 被 `{ AiChatDialog }` 覆盖）→ 企业解释页 app-header 未注册无横栏；已合并。RuleManage/UserManage 旧版布局（无 app-header、退出藏菜单且失效）→ 统一为 app-header 上下布局。
- ④（commit c62a61c）：认证信息（token/username/realName/modules）从 localStorage 改存 **sessionStorage**，关标签页/浏览器后强制重新登录；同标签页 F5 刷新保持登录。偏好记忆（DataImport `dirLast_*`、ReportExport `report_note_*`）保留 localStorage。实测：新标签页直访 #/dashboard 被守卫重定向到 /login ✓；F5 后保持登录 ✓。
- **①根因实锤（commit 684da41，本日重大突破）：数据导入页的 `<el-tabs>` 触发 Element UI 布局无限循环（Chrome Trace 实测：主线程每秒 1000+ 次 Layout/UpdateLayoutTree，无 JS FunctionCall，组件挂载未完成→ batches 请求不发出→ `batchLoading` 永 true → el-loading 动画永转）。这就是用户「点数据导入菜单就浏览器无响应」和「点审核结果不高亮」的真正根因（与此前线程池/上传压力无关！）。
- 修复方式：将 el-tabs 改为 `<el-radio-group>` + `<el-radio-button>` 模块切换 + `v-show` 面板（功能等价，回避 el-tabs 触发器）。验证：★ dev + **打包形态（dist + 静态代理 8091）** 均正常：/import 进入 8ms 发出 batches，无长任务；完整点击 8 个菜单高亮全部正常。
- 测试脚本：`D:\Codex\_tools\pptr-core\` 下 import_probe2.js / import_verify.js / menu_final.js / session_test.js / prod_import_test2.js / prod_server.js（打包静态+API 代理，用于本地验证 dist）。trace 分析脚本在 %TEMP%\analyze_trace*.py。

### 5. 待办不变
- 用户反馈 4 个问题：①点「审核结果」菜单不高亮；②企业解释/用户管理顶部没有统一横栏；③某些页面退出登录不显示；④（新增）不点退出直接关标签页/浏览器，重开后跳过登录直接进主页，要求重开时强制登录。
- 已修复（②③）：ExplainReview.vue 有重复 `components` 键（`{ AppHeader }` 被后面的 `{ AiChatDialog }` 覆盖）→ app-header 未注册、企业解释页顶部横栏丢失；已合并为 `{ AppHeader, AiChatDialog }`。RuleManage.vue / UserManage.vue 还是旧版布局（`<el-container>` 无 direction、`<el-header>` 无用户/登出、退出登录藏在菜单里且 RuleManage 根本没有 logout 方法）→ 统一改为 `<app-header>` 上下布局、删菜单内退出项，与其余 6 页一致。
- 已实测（puppeteer headless，admin/admin123 登录后逐路由访问）：/explain /rules /users 均有 app-header + 退出按钮；/audit 直接访问时菜单高亮「审核结果」正常 → 问题① 不在 AuditResult 自身。
- **新发现（重要）**：/import（数据导入）页面挂载后 **JS 主线程卡死**（puppeteer evaluate 3s 超时，goto 已到 #/import 但页面脚本长时间不响应）——怀疑这就是「点审核结果不高亮」及此前「数据导入菜单一点就浏览器无响应」的根因方向（页面 JS 阻塞 → 点击事件/高亮更新被卡住）。下一步：profiling /import 页 loadData（batches 响应后 overview 构造 / 200 行表格渲染）找主线程长任务。
- 问题④ 未做（下次优先）：把认证信息（token/username/realName/modules）从 localStorage 改存 **sessionStorage**（关标签页即清空 → 强制登录），涉及 Login.vue、router/index.js、api/index.js、main.js、AppHeader.vue、ReportExport.vue；DataImport 的 `dirLast_*`、ReportExport 的 `report_note_*` 属偏好记忆保留 localStorage。注意：同标签页 F5 刷新保持登录、新开标签页需重登。
- 测试脚本：`D:\Codex\_tools\pptr-core\menu_test3.js`（点击遍历）、`menu_test4.js`（逐路由访问，推荐）、`login_debug.js`；node24 运行（`C:\Users\jcxiong\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe`）。

### 5. 待办不变
- `docs/打包部署说明.docx` 第六节「外置 application.yml 需包含完整配置」改为「属性级合并」后重新导出 docx（未做）。
- 崩溃根因确认后：修正 commit `cf57c2b` 中「指向客户端环境」的旧结论。
- ~~/import 页 JS 主线程卡死待调查~~ → 已实锤：el-tabs 布局循环，已修复（见上。
- ~~认证信息 localStorage → sessionStorage~~ → 已完成（commit c62a61c）。


## 〇、关机交接（2026-08-27 深夜，用户关机前）
- **当前运行状态**：前后端应用服务全部已停止（开发服务、打包版均未运行）；仅数据库在跑
  （MySQL80 服务=3305，本项目用；MySQL57=3306 勿动）；8080 上 IIS 站点仍在但本项目已不再依赖 IIS。
- **进行中/待验证（用户负责）**：用户在**打包环境**验证数据库合并结果——用 `admin/admin123` 登录
  （行为验证码需人工点击，无法自动化验证）；若登录及各业务模块数据正常，则全流程闭环。
- **部署知识（本轮确认）**：外置 `application.yml` 与 jar 内置是**属性级合并**（外置只需写要覆盖的项，其余自动沿用内置），
  不是文件级替换；Spring Boot 按**启动工作目录**找配置（`file:./config/` > `classpath:/config/` > `file:./` > `classpath:/`），
  在 jar 同级执行 `java -jar app.jar` 即可命中外部配置；推荐放 `config\` 子目录。
- **待办（下次）**：`docs/打包部署说明.docx` 第六节"外置 application.yml 需包含完整配置"表述不准确，
  应改为"属性级合并，只需写要覆盖的项"；改后重新导出 docx 并推送。

## 一、当前状态（2026-08-27 合并后，打包部署已完成）
- **开发服务已停止**（前后端均未运行），打包版测试**验收通过**。
- **打包部署方案（已定稿）**：Spring Boot 直接托管前端静态文件，单端口 8090，**不需要 IIS/nginx**。
  部署结构 = jar 同级 `web\`（前端 dist 内容）+ `docs\`（模板目录）；`java -jar app.jar` 启动后访问 `http://<服务器>:8090`。
  说明文档：`docs/打包部署说明.md` / `.docx`（含 nginx 备选方案、IIS 反代示例 `docs/iis-web.config.example`）。
- **数据库已合并（2026-08-27 晚）**：同事 Navicat 全表导出 `traffic_audit.sql`（27 表、约 6 万行，来自其 mysql80:3308）已全量导入本机库（MySQL 8.0.29，localhost:3305，root/root）。
  导入前已备份本机库 → `D:\03_公司\02_项目\27_湖北省道路运输事业发展中心\05_开发测试\00_开发\_db_backup_20260827.sql`。
  `sys_user` 现有 4 账号（admin + zhangsan/lisi/wangwu，均带 modules）；admin 密码已恢复为 BCrypt（admin/admin123），其余账号密码为同事原 hash。
  ⚠️ **MySQL 客户端用 8.0**（`C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe`），不要用 5.7 客户端（`D:\mysql\mysql-5.7.41-winx64`）。
- 本次配套改动：`SecurityConfig` 放行静态资源（`/`、`/js/**` 等）+ `application.yml` 加
  `spring.web.resources.static-locations: file:./web/`（application.yml 不入库，重打包时需保留该配置）。
- **2026-08-27 完成双方开发结果合并**：以对方（郑玉洁，另一开发人员）的代码为基础，并入我方三样改动
  （态势图/AI助手构想记录、登录行为验证码、登出与上下布局）。验证码采用**我方实现**（Captcha3D + 后端 captcha 包，
  内存存储，无 Redis 依赖），对方独立实现的 ShapeCaptcha（Canvas+Redis）已弃用、不入库。
- 新 git 仓库迁移进行中：旧 Gitee 仓库弃用，合并结果将提交到新仓库（地址见第九节，待用户提供后补全）。
- 新 git 仓库迁移**已完成**：合并结果已提交到 Gitblit 根仓库 `trafficAudit.git`（见第九节），旧 Gitee 仓库弃用；`~xyc/trafficAudit.git` 临时仓库已删。
- 数据库已补齐对方新增表（MySQL 8，库 traffic_audit，本机 3305）：h2031_enterprise_monthly、passenger_*、
  h204_*、investment_*、city_bus_monthly、city_taxi_monthly、city_taxi_auth、passenger_individual_monthly、audit_run；
  sys_user 已加 modules 列；admin 密码已重置为 BCrypt（admin/admin123）。
- 无已知阻塞性问题。

### 6. 08-31：菜单高亮间歇性根因修复（实锤）+ 修改密码功能（已完成并验证）
- **菜单高亮根因实锤**：不是 el-tabs 遗留问题，而是 Element UI `el-menu` 的 `handleItemClick` 在**同路由导航**（vue-router NavigationDuplicated）时，`routeToItem` 的 onError 回调把 `activeIndex` 恢复为点击前旧值（其只排除了 push 抛异常路径，未排除同路由回调路径）。触发场景：上一次菜单导航未完成时快速点另一个菜单（如「数据导入」未切完就点「审核结果」）→ 页面已是目标页但高亮停留在旧菜单，**间歇性、时好时坏**（复现：puppeteer 快速连点，puppeteer 用 node24：`C:\Users\jcxiong\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe`）。
- **修复**：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`。

## 二、快速启动
统一用一键脚本（必须沙箱外/提权运行）：
@@ -67,17 +710,24 @@
- 后续扩展：H203-1 公路旅客、W203 水路、P203 港口、H204 能源等（需求文档 v2/v3 计划），先把 H203-2 演示做好。
- 【新需求·仅记录未实现·2026-08-23】登录后首页新增「全省交通运输态势感知图」：把货运、客运、巡游出租、网约车、投资、能耗等方面的变化态势可视化展示。
- 【新需求·仅记录未实现·2026-08-23】扩展现有 AI 分析为「AI 助手」：以本地数据库数据为基础建立知识库，做 RAG，支持自然语言提问/聊天，灵活查看与挖掘数据。
- **2026-08-28 复核「点数据导入浏览器崩溃」（打包测试环境，部分用户）**：重点排查 `GET /api/import/batches`——后端 limit 上限 200；全表 81 条、error_detail 最长 2.6KB、全量响应约 17KB（前端只取 50 条）；前端表格仅 8 列短字段（errorDetail 不渲染）、无轮询/定时器。**结论：接口不是崩溃根因**（若接口有问题，所有用户都会崩，而非"部分用户"）。现象符合客户端环境差异（第三方扩展注入/旧显卡驱动/低配内存，与 08-27 迅雷扩展+Intel 旧驱动结论一致）。建议对崩溃用户依次验证：无痕模式→换 Edge→禁扩展，并看 chrome://crashes。
- 【新需求·仅记录未实现·2026-08-28】增加**经济指标试算功能**：领导非常关注经济指标，**货运是大头**；常驻现场的所有人都要会计算货运相关数据（货运量/周转量等）。领导经常要求把某个数据「压一压」，今后考虑在软件里增加试算功能——可按需要调整/测算指标数值（如模拟下调某企业/某口径的货运量后看汇总与趋势影响），辅助现场人员快速试算与应对。

- 【待办·2026-10-03】**数值精度统一改造**：把既有业务表的数值列由 `double` 改为 `DECIMAL(30,15)`，Java 实体字段由 `Double/Float` 改为 `BigDecimal`，与节假日表、观测站表统一口径（用户 2026-10-03 明确要求，择机实施）。
  - 现状盘点（traffic_audit，2026-10-03 查询）：**16 张表、共 228 个 double 列**——`freight_turnover_import` 48、`city_bus_monthly` 34、`h2032_enterprise_monthly` 33、`city_taxi_monthly` 29、`wyc_order_monthly` 22、`h2031_enterprise_monthly` 18、`h204_vehicle_quarterly` 12、`scale_split_transport` 9、`investment_monthly` 5、`investment_system` 5、`wyc_total_monthly` 4、`h204_auth_vehicle` 2、`investment_project` 2、`passenger_individual_monthly` 2、`transport_auth_vehicle` 2、`vehicle_track_mileage` 1。
  - 已是 decimal 口径、无需改动：`holiday_calendar` / `holiday_passenger_coefficient` / `holiday_passenger_flow` / `holiday_vehicle_flow` / `observation_station_flow`。
  - 改造范围不只是改列类型：实体类字段类型、导入解析（不要经 double 中转）、计算与取整逻辑、报表导出格式化，以及存量数据的迁移脚本，都要一起改；改完要做逐表数值抽查。

## 八、每日交接约定
1. 新对话第一步：读 `AGENTS.md` + `HANDOFF.md`；涉及 AI 分析/审核时参考 `docs/` 与数据库表结构。
2. 每天结束时：更新 `HANDOFF.md`（进展、坑、新需求、待办），再关对话。
3. 跨项目可复用经验沉淀到机器级顶层 AGENTS.md（本项目不再重复）。
## 九、Git 仓库（2026-08-27 起使用新仓库 Gitblit）
- **新仓库（在用）**：Gitblit 服务器 `61.183.254.94`，仓库 **`~xyc/trafficAudit.git`**（个人命名空间，已建为「限制查看/克隆/推送」私有）。
  - HTTPS 推送地址：`https://61.183.254.94:8443/r/~xyc/trafficAudit.git`（账号 `xyc`，密码已存本机 GCM 凭据管理器，直接 `git push` 即可）。
  - 服务器是**自签名证书**：本仓库已配置 `http.sslVerify false`（仅本项目）。
  - SSH 地址（备选，未配密钥暂不可用）：`ssh://xyc@61.183.254.94:29418/trafficAudit.git`——需先在 Gitblit Web（https://61.183.254.94:8443，登录 xyc）的用户页注册 SSH 公钥。
  - 本机 remote：`origin` = HTTPS（日常推送用）；`ssh-alt` = SSH 地址（备用）。
- **新仓库（在用）**：Gitblit 服务器 `61.183.254.94:3000`（HTTP），仓库 **`trafficAudit.git`**（根目录命名空间，非 `~xyc/` 个人空间）。
  - 推送地址：`http://xyc@61.183.254.94:3000/r/trafficAudit.git`（账号 `xyc` 密码 `gitP@ssw0rd`，已存本机 GCM 凭据管理器，直接 `git push` 即可）。
  - 说明：管理员已在 Gitblit Web（http://61.183.254.94:3000）给 `xyc` 授权该仓库推送（RW+），2026-08-27 已验证 `xyc` 推送成功；日常推送用 `xyc`。
  - 旧的 `~xyc/trafficAudit.git` 个人仓库已删除（2026-08-27，admin 在 Web 编辑页删除）。
  - 本机 remote：仅 `origin` = `http://xyc@61.183.254.94:3000/r/trafficAudit.git`（不用 SSH，ssh-alt 已删）。
- **旧仓库（弃用）**：Gitee https://gitee.com/jichengxiong/trafficAudit（2026-08-14 建立）——不再使用，未再推送。
- 合并历史：main 分支 = 原历史 + 我方 08-27 提交（`715e9e1`）+ 对方开发结果分支（`f713166`，partner-work）+ 合并提交 `ec9b25a`；对方未用 git，其代码经独立分支合入。
- 敏感配置不入库：`traffic-audit-server/src/main/resources/application.yml` 已在 `.gitignore` 中，
@@ -106,3 +756,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 失败数据直接验明细表，真实无失败数据验「暂无导入失败记录」空态。