HANDOFF.md — 每日交接文档

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

最新（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 通过；页面实测“往年国省道数据调整”卡片与新增弹窗正常。
• 取整口径（用户 2026-10-06 确认）：不做“从原始值一次取整”的备选。唯一要求是与 Excel 显示值一致：先按源 Excel 单元格格式生成显示值，再按快报统一 1 位小数。10-04 总计环比原始值约 4.5481%，源格显示 4.55%，快报取 1 位得到 4.6%；这属于既定口径，不是需要修正的边界问题。

说明：本文件早前“环比基期只作备用、不参与计算”的段落已作废。该版本针对的是旧实现误把 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 仓库迁移**已完成**：合并结果已提交到 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。

二、快速启动

统一用一键脚本（必须沙箱外/提权运行）：
powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1
- 脚本会自动检测 8090/8080 是否已监听并跳过重复启动，等待就绪后打印结果。
- 成功标志：backend.log 出现 Started TrafficAuditApplication；frontend.log 出现 Compiled successfully + App running at:。
- 访问地址：前端 http://localhost:8080（/api 代理到后端 8090）。
- 启动的三个历史坑及对策：见 AGENTS.md（Path/PATH 重复→不用 Start-Process；node 沙箱 EPERM→必须提权；不嵌套 powershell -Command）。

三、项目概览

• 系统：交通货运统计审核系统（湖北），先做"交企统H203-2表_道路货物运输月度生产情况"演示。
• 前端：Vue 2 + Element UI，traffic-audit-web，端口 8080。
• 后端：Spring Boot 2.x + MyBatis Plus + EasyExcel，traffic-audit-server，端口 8090。
• 数据库：MySQL（本机 3305 端口，库名 traffic_audit；账号密码见 traffic-audit-server/src/main/resources/application.yml）。
• LLM：DeepSeek API（deepseek-chat，配置同样在 application.yml；注意不要把 API Key 写进任何文档）。
• 核心模块：数据导入（货运/旅客/城市客运/投资/能耗多类）、审核引擎（规则驱动）、AI 分析（脱敏+查库+解释生成）、
  报表生成（货运/旅客/城市客运/投资/能耗 Tab 工作台）、用户权限（三员分离）、操作日志。
• 对方（郑玉洁）08-26/08-27 的完整开发记录见 docs/同事开发记录-20260827.md（含报表 Tab 工作台、目录导入、
  解释按需展开、动态报表标题、城市客运/公路旅客/投资/能耗模块等细节与踩坑）。

四、已完成功能（截至 08-07）

• 数据导入：H203-2月报、运政车辆、轨迹里程、规上规下拆分、货运量周转量；导入失败显示行号。
• 审核：规则表驱动（整车吨位范围 4≤且≤40、货运类型环比中文+数量等），结果支持按企业名称/规则过滤。
• AI 分析（AiChatDialog.vue）：结构化 Markdown 排版、逐字打字动画（约70字符/秒）、打字时同步平滑滚动、思考中蹦跳小人（发送后也显示）、语音输入+语音播报、对话可查数据库、弹窗固定屏幕居中圆角。
• 企业解释：独立菜单（ExplainReview），与审核结果分离；AI 逐条分析。
• 报表生成：货运量分市州明细、货运量排名、周转量排名。
• 布局：顶部标题+左侧菜单固定，内容区表格内部滚动；悬浮提示框已限宽（App.vue 全局 .el-tooltip__popper max-width）。
• 文档：AGENTS.md、start-dev.ps1、docs/Codex功能清单.md、docs/每日反思任务.md、docs/architecture.md、docs/database.md、docs/init.sql。

五、用户偏好 / 业务规则（务必遵守）

1. 全程中文交流；临时脚本/文件未经同意不删。
2. 报表期**以页面选择为准**（选几月就是几月，忽略 Excel 里的月份文字）；累计=1~N 月，N=所选月。
3. 规上规下拆分表"全省"行：**忠实导入，不要自己求和**（周转量、同比都一样，是什么就存什么）。
4. 数值处理：**不用 BigDecimal**，小数用 double 读入/运算/存储；整数存整数；可接受尾差。
5. 货运量周转量表是**输入**（每月导入），不是输出；货运量=规上+规下合计；规上货运量从 H203-2 按 17 市州合计（市州关系见 docs/各市州所属组织机构.xlsx），规下=合计−规上。
6. AI 交互数据**先脱敏再发送**（需求见 requirement/货运简化.docx 第78行；设计见 docs/database.md 第七章 llm_desensitize_map）。
7. AI 分析输出要"一眼看到结构和重点"：标题加粗、结论/建议/依据等标签块。
8. 审核结果与"企业解释 AI 分析"是两个独立功能，不要混在一起。
9. 本机有其他项目在跑 node 进程：08-23 已知 08-21 19:17 启动的两个 node 进程（当时 PID 13616/15412）属于**其他项目**，重启本项目时不要杀；杀任何进程前先核对命令行（CIM Win32_Process）与启动时间。

六、文档索引

• 需求：requirement/货运简化.docx（+ docs/ 副本）、docs/01-交通运输部门统计调查制度.docx、docs/02-交通运输企业统计调查制度.docx。
• 模板/生成表：docs/模板_*.xlsx、docs/生成_*.xlsx。
• 设计：docs/architecture.md、docs/database.md、docs/init.sql。
• 运维：AGENTS.md、start-dev.ps1、docs/每日反思任务.md（每日反思自动化待启用）。

七、待办 / 已知事项

• 每日反思自动化尚未创建（提示词已备好，见 docs/每日反思任务.md；需要 automation 工具可用的会话）。
• 官方 Codex 手册本机访问 403，docs/Codex功能清单.md 待网络恢复后补官方核实版。
• 后续扩展：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: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 中，
  仓库内只提交占位符模板 application.yml.example（${DEEPSEEK_API_KEY} 等）。新环境：复制模板为 application.yml 并填真实值。
• 日常流程：git add -A → git commit -m "..." → git push（HTTPS 推送免输密码）。
• 注意：backend.log、frontend.log、node_modules/、dist/、target/ 等不入库；docs/sql_city_bus.sql、
  docs/sql_city_taxi.sql 已入库（建表+审核规则，MySQL 8 可用）。

十、会话记录

• 2026-08-14：启动前后端验证正常（后均已停止）；建立 git 仓库（新增 .gitignore、脱敏模板 application.yml.example，真实 application.yml 不入库），创建 Gitee 私有仓库 jichengxiong/trafficAudit 并推送 main（2 commits：初始提交 + HANDOFF 补充 git 说明）。
• 2026-08-23：交接前核实——git 工作区干净、远端已同步；前后端均未在运行。
• 2026-08-23：交接后启动前后端验证正常（8090/8080 已监听）；记录两条新需求（态势感知图、AI 助手 RAG），仅记录未实现。
• 2026-08-27：登录功能改造完成——行为验证码（按提示顺序点击立体图形）。后端 security/captcha/CaptchaService.java 直接生成等轴测几何面（响应不含图形类型名，答案只在服务端），/api/auth/captcha 获取、/captcha/verify 校验（错 3 次换题）、/login 消费（一次性，未验证 4003/已过期 4002/顺序错 4001）；前端 Captcha3D.vue SVG 渲染（背景随机色+6 种图案、8 种立体图形随机位置/大小/旋转/颜色），Login.vue 接入真实登录（axios+token+localStorage），router 加登录守卫。实测通过：正确顺序验证成功、错误顺序提示重试、未验证拦截、错密码 401、登录跳转工作台。坑：Vue2 组件名大小写敏感，组件注册 Captcha3D 时模板必须写 （ 会被解析成 Captcha3d 匹配不上）。
• 2026-08-27（续）：登录页视觉与登出——验证码画布 340x190 缩为 340x148、图形 size 0.8~1.2 缩为 0.6~0.95、间距/抖动收紧、旋转 ±14°；登录卡片 420→400 宽、form 间距收紧（卡片高约 559px）。立方体/长方体改为斜二测教科书画法（前面正方形+顶/侧斜出，更立体）。新增公共 components/AppHeader.vue（标题+当前用户+退出登录，退出清 token 回登录页），替换 6 个业务页原有 el-header。坑：批量插入 components 时 ExplainReview 原有 components: { AiChatDialog } 被覆盖（重复键），需合并为 { AppHeader, AiChatDialog }。另：PowerShell 双引号字符串里的反引号会被吞掉，写 markdown 代码标记要避免。
• 2026-08-27（续2）：六棱柱改为标准等轴测正六边形顶面+3 侧面（此前顶面过扁认不出）；球改为径向渐变（亮→暗，前端渲染器新增 radial 渐变支持，gradient id 用 shape id 去重）。修布局回归：AppHeader 是自定义组件，el-container 检测不到 el-header 子组件导致外层容器变成横向（系统名称+登出只占左侧 435px）——6 个业务页外层容器显式加 direction="vertical" 修复（上：系统栏 左标题右用户+登出；下：左菜单右工作区）。坑：radialFaces 方法误放进 computed（Vue computed 不接受参数，s 为 undefined 报错），须放 methods；vue-loader 编译缓存/浏览器启发式缓存（index.html 无缓存头）导致改代码后页面仍加载旧 chunk——vue.config.js devServer.headers 加 Cache-Control: no-store，测试时用未访问过的 host:port。

• 2026-08-27（续3，双方合并）：合并流程——① 我方改动先提交（验证码+登出+布局，commit 前缀 feat:）；② 从 08-23 基线
  建 partner-work 分支，镜像对方目录 D:\03_公司\02_项目\27_湖北省道路运输事业发展中心\05_开发测试\00_开发\traffic-audit-project-20260827
  （排除 .git/dist/日志/对方验证码相关文件：ShapeCaptcha.vue、security/captcha/*、CAPTCHA.md、cp.txt、t_test.js），提交为对方开发结果；
  ③ git merge partner-work 解决冲突：LoginController=我方验证码+对方数据库校验（UserMapper+PasswordEncoder+modules/realName）；
  Login.vue=我方 Captcha3D 版（补存 realName/modules）；router 守卫用我方版本；6 个业务页=对方功能版+我方 AppHeader 上下布局
  （根容器 direction="vertical"、el-header 换 app-header、删菜单内退出登录、注册 AppHeader 组件）；HANDOFF.md 重写为合并版。
  ④ pom.xml 去掉对方加的 spring-boot-starter-data-redis（验证码用我方内存版，无需 Redis）；application.yml 本地合并
  （保留我方 3305 数据库参数，加 multipart 100MB、docs 模板目录配置；example 模板同步）。⑤ 数据库补齐（见第一节）；init.sql
  补 sys_user.modules 列、修正 admin 密码为真实 BCrypt、追加 passenger_individual_monthly 与 audit_run 表；城市客运两个
  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 失败数据直接验明细表，真实无失败数据验「暂无导入失败记录」空态。