docs: 切换日常推送账号为 xyc（已获仓库推送权限）

xyc

5 天以前 f620fcd86c8f389f6ca24023f36ddbb4fc70a671

 HANDOFF.md

@@ -3,78 +3,17 @@
> **用法**：新对话开始后，先读本文件 + 项目根目录 `AGENTS.md`，即可无缝接力。
> **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。

## 一、当前状态（2026-08-27）
- **2026-08-27（用户环境修复：Chrome 渲染进程崩溃=迅雷扩展，与应用无关）**：用户反馈「登录后点数据导入浏览器崩溃」。排查结论：**非应用代码问题**——无头 Chrome 完整流程多轮（真实登录→点击菜单→切 tab/下拉/刷新）+ Edge 均 0 崩溃、JS 0 错误；后端 /import/batches 有 limit 上限无大响应。本机 Crashpad 有 3 个**渲染进程**崩溃 dump（10:02/10:03/11:15），异常特征完全一致（code 0x517a7ed / addr 0xb57d5567=未初始化内存跳转），页面均为 localhost:8080，三次崩溃时唯一第三方扩展=「迅雷下载支持」（id ncennffkjdiamlpmcbajkmaiiiddgioo，document_start 全页面注入自带 Vue3 runtime + MutationObserver 观察整个 body DOM），Intel 旧驱动 27.20.100.9365 为叠加因素。用户已在 Chrome 移除该扩展并改用 Edge，均不再崩溃。
  - **坑（务必记住）**：①正式版 Chrome 已禁止命令行加载扩展（--load-extension/--disable-extensions-except 被忽略，日志提示 not allowed in Google Chrome），headless 无法复现「带扩展」场景；**Edge 允许命令行加载扩展**（msedge.exe --load-extension=... + --user-data-dir=独立目录），可用于复现扩展相关问题。②用户 Chrome 崩溃证据看 %LOCALAPPDATA%\Google\Chrome\User Data\Crashpad\reports\*.dmp（minidump 可手工解析：异常流 type=6、模块表 type=4，注释含 gpu-driver/extension-1/页面 URL）。③再遇「浏览器崩溃/白屏」先查 Crashpad 是否含第三方扩展，再查扩展/驱动，不要先怀疑应用。
  - 产物：_shots/import_crash_repro*.js（headless 复现）、_shots/edge_repro.js（Edge+扩展复现）、_shots/xunlei_ext/（扩展副本）、_shots/cft/（Chrome for Testing 下载残留）。
## 一、当前状态（2026-08-27 合并后）
- 前后端**运行中**（8090/8080 已监听，start-dev.ps1 启动），登录页已接入真实认证（数据库校验）+ 行为验证码。
- **2026-08-27 完成双方开发结果合并**：以对方（郑玉洁，另一开发人员）的代码为基础，并入我方三样改动
  （态势图/AI助手构想记录、登录行为验证码、登出与上下布局）。验证码采用**我方实现**（Captcha3D + 后端 captcha 包，
  内存存储，无 Redis 依赖），对方独立实现的 ShapeCaptcha（Canvas+Redis）已弃用、不入库。
- 新 git 仓库迁移进行中：旧 Gitee 仓库弃用，合并结果将提交到新仓库（地址见第九节，待用户提供后补全）。
- 数据库已补齐对方新增表（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）。
- 无已知阻塞性问题。

- **2026-08-26（晚间续8，报表生成页 UI 优化为「Tab 工作台」+ 备注弹窗，e2e 全绿）**：`ReportExport.vue`（23:27:55 Compiled）继续改版：
  - 报表类型改回**顶部 5 个 Tab**（货运/旅客/城市客运/投资/能耗，城市客运带「公交/出租/轨道轮渡/汇总」标签），替代续7的下拉框方案。
  - 查询区：周期单选（月报/年报，能耗只显示季报）+ 月份/年份**分组下拉**（能耗只列季度末月 3/6/9/12）+ 查询按钮；选 2026-07 后状态刷新。
  - 货运模块新增「源数据录入与校验」卡片：200 行源数据表格（企业名称/货运量/运输方式/统计月份），「校验数据」→ 错误列表 + 出错单元格红色高亮（cell-error），「自动计算」→ 汇总行（总货运量/平均货运量/各企业占比）；其余模块显示「暂未配置在线校验规则」提示。
  - 报表列表：勾选 + 报表名 + 状态标签（数据就绪/未审核/缺数据）+ 备注列 + 预览/导出；底部全选/批量预览/批量导出保留。
  - **备注弹窗**（`openNoteDialog`/`saveNote`）：按报表 key 本地记忆（`localStorage report_note_<key>`），保存后列表即时显示。
  - 无头 e2e `_shots/report_ui_opt_e2e.js`：5 Tab、周期/月份下拉、2026-07 三张报表数据就绪、校验失败 1 条+红色高亮、自动计算汇总、投资 4 张/能耗仅季报+季度末月、备注弹窗保存全部通过，JS 0 错误；截图 `_shots/report_ui_opt.png`。
  - **坑（已修复）**：备注弹窗 e2e 曾误报「空预览弹窗标题」——`querySelector('.el-dialog__title')` 命中的是 DOM 中第一个（隐藏的）预览弹窗标题；改为取**可见** `.el-dialog__wrapper` 内的标题/textarea/按钮后通过；另 localStorage 断言键应为当前 Tab 报表（energySummary 而非 cityDetail）。应用本身无缺陷（探针 `_shots/probe_note.js` 确认点编辑图标即开「编辑备注」弹窗）。
  - 遗留/待办不变：见续5（货运 7 月汇总表未导入、旅客 1-6 月/2025 同期缺失、8-12 月依赖数据源、能耗新规则阈值待确认）。
- **2026-08-26（晚间续4再补，解释模块改「按需展开」）**：用户反馈左右布局仍不美观。设计判断：问题不在位置而在「常驻显示」——把解释编辑器一直摆在每条问题旁必然显挤。改为**浏览轻、编辑按需展开**（前端 17:41:58 Compiled）：明细视图卡片头是「解释：已填写/未填写」可点击标签，点开才在卡片内展开解释编辑区（收起按钮可关）；合并视图「企业解释」列默认只显示状态标签+2 行摘要+「填写/修改」按钮，点开才展开 textarea；两条视图内跳转「解释」链接已移除（原 goExplain 链接改由展开面板承担，AI 分析仍在企业解释页）。默认页面回到干净状态。
- **2026-08-26（晚间续4补，解释模块改左右布局）**：用户反馈「解释放问题下面不好看，放右边」。已改（前端 17:38:55 Compiled）：明细视图卡片内 `card-body` 改 flex 两栏——左 `issue-detail`（规则+实际/基准/差异）、右 `explain-side`（固定宽 340 灰底面板：标签+已有解释+textarea+保存/重置）；合并视图把解释从问题明细单元格移出，**单独新增「企业解释」列（宽 360）**，位于「审核问题明细」与「操作」之间，非解释类报表（INVEST/H204）显示「—」。
- **2026-08-26（晚间续4，审核结果页内嵌企业解释）**：用户要求「审核问题明细后面直接加解释模块，不用跳转到另一个界面」。现状：审核结果页每条问题卡片只有跳转链接，且后端**原本没有保存解释的接口**（verifyExplanation 只读）。
  - 后端 `ExplainController` 新增 `POST /api/explain/save`（reportType/reportId/explanation，H2032/H2031/CITY_BUS/CITY_TAXI 四类，按 reportId 更新对应来源表 verifyExplanation，错误返回 Result.error）。
  - 前端 `AuditResult.vue`（17:35:24 Compiled）：明细视图每条问题卡片底部、合并视图每家企业问题明细下方，内嵌「企业解释」模块——已有解释/未填写标签 + 草稿 textarea + 保存解释/重置；草稿按 reportId 共享（同企业多条问题同 draft，保存后同步所有行）；加载结果统一走 `applyResults` 初始化草稿。企业解释页（ExplainReview）与审核结果页共用同一来源表，保存后两边一致；原「解释」跳转链接保留。
  - 验证：`POST /api/explain/save` 保存→DB 更新→explain/list 可见→已清测试数据；后端编译通过+重启就绪（PID 11732）。
- **2026-08-26（晚间续3，目录导入直连版 + 文件名自动识别月份）**：用户反馈目录导入太慢/操作绕，且明确「文件夹里是多个月的数据，要按 Excel 文件名分别存到每个月」。
  - 前端 `DataImport.vue`（17:21:59 Compiled）：去掉「选择文件夹」按钮，改为**目录路径输入框 + 「导入该目录」**（回车也可触发）+「浏览…」辅助查找 +「跳过已导入文件」勾选（默认开，记住上次目录 localStorage `dirLast_<type>`）；逐文件导入显示实时进度（待导入/导入中/成功/失败/已跳过 + 识别到的月份标签）；目录导入不再强制要求先选报表期（报表期仅作无年份文件的后备年份）。
  - 后端（编译通过+重启就绪，PID 10932）：`importDirFileByPath`/`importFromDir` 增加 **`detectPeriod(fileName, period)` 按文件名识别报表期**（支持 `2026年7月`/`2026年07月`/`2026.7`/`2026-07`/`202607`/`7月`；无年份用 period 年份或当前年份），识别不到且未选报表期则逐文件报错；新增**跳过已导入**（import_batch 同 period+fileName 且 failRows=0 则跳过，`skipImported` 参数默认 true）；`fromDirFile`/`fromDir` 的 period 改为可选。识别规则注意：`202607` 需 6 位连数字且年 2000-2100、月 1-12，避免误判。
  - 验证：`2026.6.xlsx→2026-06`、`202607.xlsx→2026-07`、`2026年5月.xlsx→2026-05`、`7月.xlsx→2026-07`（当前年）、`未标注月份.xlsx→报错`；重跑 skipImported=true 全部跳过；测试批次已清。
  - 语义提醒：同一类型同一报表期多个文件仍会「先清后写」互相覆盖（系统幂等规则），投资市州多文件请用专门的「市州单表批量导入」。
- **2026-08-26（晚间续2，文件夹导入改服务端目录浏览器 + 双击即导入）**：用户反馈原生文件夹选择框「单击/双击会跳进下一级目录、看不到选择确认」。
  - 根因一：浏览器原生 `webkitdirectory` 选择框交互（Chrome 需点右下角「选择文件夹」确认，用户没看到）；根因二：`DataImport.vue` 整体重写时丢了 `endpoint()` 方法（`importOne` 调 `this.endpoint(row.type)` 必抛 TypeError，**所有文件导入其实都是坏的**）——本次已补回完整 type→URL 映射。
  - 方案：弃用浏览器原生文件夹选择框，改为**服务端目录浏览器**（前后端同机，数据在 `docs/`）：后端新增 `GET /api/import/dirs?path=`（path 空=项目 docs，含子目录列表+当前目录 Excel 文件名/数量；docs 定位向上查找 4 层，兼容 IDEA 以 server 模块目录启动）与 `POST /api/import/fromDir`（type/period/dir，扫描直接包含的 .xlsx/.xls，`ByteArrayMultipartFile` 包装后复用各类型既有解析方法，逐文件返回成功/失败/错误）。
  - 前端 `DataImport.vue`：「选择文件夹」打开应用内对话框（当前路径/上级目录/数据目录 docs/子目录列表/当前目录 Excel 预览），**单击=进入子文件夹，双击目标文件夹=立即导入**；也可进入后点「选择此文件夹并导入」；导入结果逐文件弹窗展示；队列单文件导入流程保留。
  - 验证：后端编译通过+重启就绪（start-dev.ps1，PID 32576）；`/api/import/dirs` 返回 docs 各模块目录与 15 个城市客运 Excel；`/api/import/fromDir` 实测模板_轨迹里程.xlsx→628 行（真实解析成功）；测试产生的 track_mileage 2026-03 数据已用空文件重导清零、import_batch 测试记录(34/35/36)已删；前端 17:03:58 Compiled successfully。
  - 待办：请用户刷新页面手测「选择文件夹→双击目标文件夹即导入」；临时测试目录 `%TEMP%\dirimport_test`、`%TEMP%\dirimport_empty` 保留未删。
- **2026-08-26（晚间，报表标题全动态化）**：按用户要求「标题不要写死，根据审计员选择的月份/年份显示」完成收尾（承前：城市客运 6 表「导入模板_*.xlsx」已由既有「生成_*.xlsx」复制补齐，此前引用文件不存在导致 500）：
  - ① `dynamicTitle` 从「前 6 行」改为全表扫描：补上分市州第 2 块标题（r23「城市客运客运周转量分市州1-N月累计情况」）；「1-12月」整年对比块（2024/2025）标题保持原样，不再被误改成选中年。
  - ② 新增 `cumRange(month)`：1 月显示「1月」不再出现「1-1月」，应用于货运量/周转量排名累计块、中口径分析、投资预安排表头、城市客运标题。
  - ③ 新增 `fixPassengerHeaderYear`：公路旅客分市州/中口径明细表头年份动态化（此前选 2027 仍显示「2026年1月/2026年累计」）。
  - ④ 轨道轮渡明细补调 `dynamicTitle`（此前表头年份写死 2026）。
  - 验证：2026-01/2026-07/2026-12（年报）/2027-01 × 全模块 17 张导出标题全部断言通过（样例见 `%TEMP%\title_check\*FINAL*`）；汇总表 G1/M1/G12 对比块标题正确保留 2025/2024。
  - 遗留（属模板结构，未改）：投资亿元表 3 的季度固定列（1-3月实际/4月计划/Q2/1-4月累计/5月/6月等）为模板固定列，年份已动态、月份固定是模板设计；投资十五五模板 sheet0「年    月」占位与官方样例一致。
- **2026-08-26（晚间续，报表数据预览轻量版）**：导出前先看数据有没有缺/不对。后端新增 `GET /api/report/preview`（period/mode/types，复用 checkExportReady 的就绪/审核状态，逐模块算月度覆盖 + 核心指标摘要 + 问题清单）：货运=模板湖北省行 1..N 月列覆盖 + 全省累计货运量/周转量（合计/规上/规下）；旅客=源表逐月覆盖 + 企业/个体累计；城市客运=公交/出租/轨道/轮渡累计（汇总 3 表覆盖=公交∪出租，公交明细/轨道轮渡只看公交表）；投资=当月报表只提示当月缺失 + 项目数/本月完成/自年初/自开始累计；能耗=季度数据 + 车辆数/燃油消耗。前端 `ReportExport.vue` 每模块加「预览数据」按钮 + 弹窗（状态标签 就绪/缺数据/未审核、月度覆盖、摘要表、问题清单）。验证：2026-07 全模块 18 张、2026-08（未审核+缺数据）、2026-12 年报、2027-01 全部正确；前端 Compiled successfully。
  - 预览顺带暴露的数据现状（供用户核对）：货运模板仅 2026-07 一期且 7 月列为空（累计只有 1-6 月 9.7 万吨，规上 3754 万吨 → 规下为负，口径存疑）；旅客/出租仅 7 月、投资仅 6-7 月导入；公交月报未导入（轨道/轮渡 0 数据）。
- **2026-08-26（午后，报表生成 P0 三项 + 模板规则梳理）**：①导出前数据就绪校验——后端 `GET /api/report/ready`（按报表类型检查依赖表行数：货运=模板_货运量周转量+规上规下拆分表+H203-2、旅客=H203-1+个体、公交/出租、投资=investment_monthly、能耗=h204_vehicle_quarterly），前端导出前弹「数据未就绪」确认框（列出具体缺哪张表，可继续导出空表）；②错误透出——新增 `GlobalExceptionHandler`（HTTP 500 + Result{code,message}），前端 `failWith` 显示后端具体原因；③文件名统一——前端 4 个旅客 fileName 对齐后端（生成_公路旅客分市州明细/中口径明细/中口径排名/中口径分析.xlsx），`buildResponse` 按 .xls/.xlsx 设置 MIME；④顺手修 `ReportExport.vue` 缺 `activeMenu` 定义（侧边栏高亮失效）。验证：ready 接口数值与 DB 逐表核对一致（cityDetail=690=ft18+scale36+h2032=636、旅客 771、出租 17、投资 179、能耗 126、公交 0 因公交月报未导入）；无头浏览器两场景 PASS（缺数据弹确认框、数据齐全直接下载）；前端 12:55:10 Compiled。截图 `_shots/report_ready_dialog.png`。
### 2026-08-26 晚间会话：报表生成三口径落地（公式保留/动态插行/审核前置+1~N累计，已完成验证）
**背景**：用户确认三项口径——①所有模板保留公式、只填原始量、公式部分自动算；②动态插行并同步公式范围；③先审核再出表、1~N月累计=一月到N月求和。
**①公式保留（现状核对，无需改）**
- 能耗/城市客运/旅客 8 张导出已是「模板底稿 + 公式单元格保留 + evaluateAll 重算」：旅客分市州/中口径排名/分析、能耗汇总、城市客运 3 张合计/同比/占比公式均在导出后重算；投资 4 表与货运模板本身 0 公式（合计/同比由系统算好写入）。旅客模板历史 `#REF!` 引用不影响填充。
- 顺手修复（上下午会话）：`application.yml` 的 `passenger.template-dir` 原指向不存在的 `docs/公路旅客/输出` 导致旅客导出 500，已改为 `docs/公路旅客`；`REPORT_FILE_NAMES` 旅客 zip 内文件名改全名。旅客 4 表导出已恢复 HTTP 200（size≈13.6KB）。
**②动态插行（本次新增，投资 3 表）**
- 改动集中在 `ReportExportService.java`（`investPlan`/`investFiveYearLogistics`/`investCounty`）：结构扫描（块→市州小节→项目行）→ 原位填充模板行（记录已匹配项目 id）→ 自底向上按小节插行补齐 DB 多余项目 → 按块/市州重排序号。`insertRowsDown`（shiftRows + 合并区先摘除再按新行号恢复 + `createRowLike` 复制样式/行高/单行合并）、`renumberInvestSeq`（表1按块重置、表2按市州重置、表4全表连续）、`InvestSection` 等辅助方法一并加入。表3（亿元投资）原本就是动态生成，未动。
- 验证（2026-07）：模板 表1 客运 45 行/物流 121 行，DB 46/132 → 输出 179 行（46+133，其中 1 条为既有模糊匹配重复「荆州市瑞海国际物流园」，非本次引入）；十堰 物流小节模板 7 行→DB 38 个→插 31 行（DB 填报单位为十堰的 38 个项目全部上表，含名称带武汉/黄石的跨市项目，属数据现状）。表2 十五五 35 行=DB 35 个（模板 63 行无插行）；表4 经济强县 38 行（36 个 DB + 2 条既有重复匹配：枝江/应城）。合计/块/市州小节数值与 DB 聚合一致（全省 11429050.52、十堰物流 5111586）；合并区 111 个、0 重叠、随插行正确下移；序号连续（客运 1-46、物流 1-133）。
- 说明：投资模板无公式，「公式范围同步」无需处理；旅客/城市客运/能耗模板数据区固定（17/18 市州行）不会超行，若未来需要插行，shiftRows 会自动同步公式引用。
**③先审核再出表 + 1~N 累计（已就绪）**
- `checkExportReady` 已新增 `auditRows`/`audited` 字段（按 `audit_rule.report_type` → `audit_result.report_period` 统计），前端导出前弹窗区分「【缺数据】/【未审核】」。验证：跑 CITY_TAXI 审核（`POST /api/audit/execute?period=2026-07&reportType=CITY_TAXI`，4 条）后 ready 接口 `cityTaxiDetail auditRows=4 audited=true`，不再提示未审核。
- 1~N 月累计语义确认：`freightCum`/`midCumClass`/`passengerCumSum` 均为 1..N 月求和（如 2026-07 月报累计=1-7月之和；旅客分市州模板月度列固定 1-6 月，故 fillMonths=min(currentMonth,6)，超出部分以模板列数为准）。
**待确认/遗留**
- 其余类型审核尚未重跑（全库清空后仅 H2032=1002 条 + 本次 CITY_TAXI=4 条）：如需 ready 不再提示未审核，请在页面执行 H2031/INVEST/H204 审核（或让 AI 代跑）。
- 投资模糊匹配存在重复（同模板行匹配到同一 DB 项目），如需可用「已用项目集合」约束匹配（会改变现有输出，需确认）。
- 表1 十堰物流 38 个 DB 项目含大量名称带武汉/黄石的项目（填报单位=十堰），若数据口径有误需在导入源头核对。
- 遗留不变：7-12 月模板待用户提供；能耗新 6 条规则阈值口径待确认；代码仍未提交 Git。

- **2026-08-26（中午，M2 完成）**：投资市州单表批量导入落地并全量验证（`/api/import/investCityBatch`，参数 period/category=客运站场|物流园区，扫描 `docs/投资/输入/{客运（客运站）|物流（物流园区）}/{N月}`，跳过 pdf）：客运 6月35/7月46、物流 6月132/7月133 条，0 失败；`total_investment` 修复生效（航发智慧物流园=69876，导出合计 2038714.59 与 DB 聚合一致）；修复「总投资 vs 计划总投资（表头带空格）」+「公式单元格读缓存值（.et 跨表公式）」+「多 sheet 历史文件按报表期选 sheet（襄阳 .et 此前错选 2月 sheet）」。十五五模板 63 项规范化匹配 35 覆盖，28 个真实缺口清单在 `_shots/five_year_report.txt`（数据源不在市州单表，需用户提供）。
- **2026-08-26（凌晨）**：用户 4 项意见全部处理完毕（详见末尾「2026-08-26 凌晨会话」）：①模板一致性——修正 `application.yml` 模板路径（passenger→`docs/公路旅客/输出`，新增 `energy.template-dir: docs/能耗`），能耗模板文件名改为用户最新更新的 `生成_能运汇总表.xlsx`，货运/旅客/能耗/城市客运 10 张导出结构+合并+列宽全部与模板 PASS；②审核规则——H204 能耗补 6 条规则（RULE_E005~E010，共 10 条，需求 7 条全覆盖），实现规则管理页（后端 `RuleManageController` + `RuleManage.vue`，按报表类型查看 6 类全部规则、可启停/改阈值），CITY_TAXI 7 条确认引擎与入库完整；③企业解释行高压缩（ExplainReview.vue 紧凑行高 + 解释列限高滚动）；④重复导入确认后端全部幂等（同报表期先删后插）+ 前端 loading 防连点，不会存两份。
- **注意**：数据库已于 2026-08-26 00:45 按用户要求全库清空（26 张表 TRUNCATE，备份 `_shots/db_backup_20260826_004520.sql` 28MB），`audit_rule` 已恢复 33 旧条 + 新增 6 条=39 条（H2032=6/H2031=8/H204=10/INVEST=4/CITY_BUS=4/CITY_TAXI=7），`sys_role` 等配置表仍为空需重新初始化；业务数据需重新导入。
- **2026-08-25（晚上续）**：按用户确认口径完成：报表生成页重排（货运→公路旅客→城市客运在旅客右边→能耗→投资）、生成内容改「多选下拉+导出」单按钮、货运/旅客/城市客运/投资全部支持月报/年报（能耗保持季度末月）、能耗汇总表改为模板底稿生成（模板_能运汇总表 .xlsx）、投资 4 表列宽与样例对齐（样例无合并/无自定义列宽）、企业解释支持“未填写”+“仅显示已填写”开关、数据导入页美化（状态列/类型说明/默认期）。详见末尾交接记录。
- **2026-08-25（晚上续）**：按用户确认口径完成：报表生成页重排（货运→公路旅客→城市客运在旅客右边→能耗→投资）、生成内容改「多选下拉+导出」单按钮、货运/旅客/城市客运/投资全部支持月报/年报（能耗保持季度末月）、能耗汇总表改为模板底稿生成（模板_能运汇总表 .xlsx）、投资 4 表列宽与样例对齐（样例无合并/无自定义列宽）、企业解释支持“未填写”+“仅显示已填写”开关、数据导入页美化（状态列/类型说明/默认期）。详见末尾交接记录。
- **2026-08-25（下午）**：报表生成/企业解释/数据导入三页 UI 重构（详见末尾交接记录）：城市客运三模块合并为一张卡、五模块统一「勾选+一键全部zip」、报表期支持月报/年报、企业解释扩展 H2031/CITY_BUS/CITY_TAXI、数据导入分组+最近批次、报表生成留痕（sys_operation_log）。
- **2026-08-25（最新）**：数据库连接根因修复（JDBC URL 缺 `allowPublicKeyRetrieval=true，MySQL8 caching_sha2_password 导致所有 DB 查询 500），已加回并重启验证；城市客运公交/出租 2026-07 审核结果重跑恢复（53/6 条，与 08-24 一致）；6 张报表重新生成数值全部核对通过；汇总表网约车行修复为显式 0（详见末尾交接记录）。
- **2026-08-24（最新）**：城市客运公交/巡游出租报表改为**按目录下模板底稿生成**（`城市公交_模板.xlsx`/`巡游出租_模板.xlsx`），保留模板标题/表头/合并单元格/公式/样式，仅填数据区；全省 7 月四指标与模板 0 差异。
- **2026-08-24（最新）**：城市客运第 2 步（巡游出租）已落地：巡游出租月报导入（`/api/import/cityTaxi`，市州级 17 行）、出租车运政车辆导入（`/api/import/cityTaxiAuth`，42636 行，市州由证号/档案号/经营权/地址正则提取）、7 组审核规则（RULE_T001~T007，report_type=CITY_TAXI，7 月审核 6 条）、分市州报表（`/api/report/export/cityTaxiDetail`，全省+17 市州×4 指标，与 `巡游出租_模板.xlsx` 7 月数值 0 差异：5860.24/34236.60/5351.24/27422.13）。第 1 步公交（CITY_BUS）保持正常（53 条）。
- 前后端均在跑：后端 8090（start-dev.ps1 启动，日志 backend.log）、前端 8080（vue-cli serve，热更新已加载公交+巡游出租入口）。
- **2026-08-24（最新）**：城市客运报表系列（6 表 + zip）按目录模板生成落地：公交/出租/轨道轮渡明细、分市州累计、各市州明细表、汇总，见 `docs/城市客运/输出/`；轨道/轮渡数据从公交源文件扩展入库（详见续5）。
- 城市客运第 3 步（网约车拆分）待部级数据源；投资 M2（市州单表解析）已完成（见上方条目）。
- 投资 M2（市州单表批量导入）已完成并验证（详见末尾「2026-08-26 中午会话：M2 市州单表批量导入」）；28 个十五五项目缺口数据源待用户提供。
## 二、快速启动
统一用一键脚本（必须沙箱外/提权运行）：
```
@@ -91,7 +30,10 @@
- 后端：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 写进任何文档）。
- 核心模块：数据导入（5类）、审核引擎（规则驱动）、AI 分析（脱敏+查库+解释生成）、报表生成（3类）、用户权限（三员分离）。
- 核心模块：数据导入（货运/旅客/城市客运/投资/能耗多类）、审核引擎（规则驱动）、AI 分析（脱敏+查库+解释生成）、
  报表生成（货运/旅客/城市客运/投资/能耗 Tab 工作台）、用户权限（三员分离）、操作日志。
- 对方（郑玉洁）08-26/08-27 的完整开发记录见 `docs/同事开发记录-20260827.md`（含报表 Tab 工作台、目录导入、
  解释按需展开、动态报表标题、城市客运/公路旅客/投资/能耗模块等细节与踩坑）。

## 四、已完成功能（截至 08-07）
- 数据导入：H203-2月报、运政车辆、轨迹里程、规上规下拆分、货运量周转量；导入失败显示行号。
@@ -111,6 +53,7 @@
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`。
@@ -122,657 +65,44 @@
- 每日反思自动化尚未创建（提示词已备好，见 `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，支持自然语言提问/聊天，灵活查看与挖掘数据。

## 八、每日交接约定
1. 新对话第一步：读 `AGENTS.md` + `HANDOFF.md`；涉及 AI 分析/审核时参考 `docs/` 与数据库表结构。
2. 每天结束时：更新 `HANDOFF.md`（进展、坑、新需求、待办），再关对话。
3. 跨项目可复用经验沉淀到机器级顶层 AGENTS.md（本项目不再重复）。
## 九、Git 仓库（2026-08-14 建立）
- 远程：Gitee **私有**仓库 https://gitee.com/jichengxiong/trafficAudit ，分支 `main`（提交身份 xyc <jc_xiong@hotmail.com>）。
## 九、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` = HTTPS（日常推送用）；`ssh-alt` = SSH 地址（备用）。
- **旧仓库（弃用）**：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 push 需要 Gitee 私人令牌或已保存凭据）。
- 注意：`backend.log`、`frontend.log`、`node_modules/`、`dist/`、`target/` 等不入库。
- 日常流程：`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-22 ~ 08-23（扩展模块调研）
## 十、会话记录
- 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 时模板必须写 <captcha3-d>（<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。

### 背景
用户提出在货运（H203-2）基础上扩展新功能，业务范围含：公路旅客运输、能耗、城市客运、投资。

### 已做
1. **通读项目**：AGENTS.md / HANDOFF.md / docs 需求与设计 / requirement/货运简化.docx，掌握现状（代码仅货运一条链路）。
2. **模板实拆**（docs/扩展表模板/ 用户新放）：
   - 公路旅客 H203-1：企业月报明细（28 列）+ 运政对比 + 分市州生成表；审核 4 组规则
   - 能耗 H204（季报）：车辆粒度明细（18 列）+ 运政信息 + 汇总表；审核 7 组规则（2 组需跨表引用货运月报）
   - 城市客运：市州级生成表 + 网约车部级下发拆分；公交 4 组 + 出租 7 组规则
   - 投资：输入=17 市州 6/7 月客运站场+物流园区月报（**格式不统一**，xls/xlsx/et/pdf 混存，20~26 列）；输出=4 张固定格式领导表；另有投资系统查询导出可对接
3. **产出文档**：
   - docs/扩展模块评估.md：模块×复用度评估、实施顺序（H203-1→H204→城市客运→投资）、架构建议（报表类型注册表化、审核引擎新增比较类型）、工作量粗估
   - docs/开源项目对比.md：GitHub 检索结论（无直接同类）、四类参照项目（NIC MSR / RuoYi / JimuReport+DataEase / Griffin+GX+Soda）对比与启示
4. **临时文件**：根目录 .tmp_*.py（解析脚本）+ .tmp_货运简化.txt，未删（约定）；xlrd 已装入 bundled python（D:\...codex-runtimes\dependencies\python）。

### 关键结论
- 自研方向正确，不引入大框架重写；最值得借鉴的是 RuoYi 代码生成器（扩展提速）与审核规则声明式设计（Griffin 理念）。
- 建议开工顺序：公路旅客 H203-1（高复用、快速见效）→ 能耗 H204（补跨表引用）→ 城市客运（规则最复杂）→ 投资（独立模块，先定"对接投资系统 vs 解析市州报表"）。

### 待办 / 下一步
- 等用户确认开工方向（用户说"先讨论再开工"）。
- 若开工：先做 H203-1 表结构设计 + 规则初始化 SQL + 前端菜单。
- 技术债登记：Vue2/SB2 升级、代码生成器、操作日志注解化（远期）。
- Gitee API 未认证返回空，可人工浏览器补查 gitee 搜索。


## 十一、交接记录：2026-08-23（H203-1 公路旅客模块已开工并完成主体）

### 用户确认的 3 个口径（开工前讨论结论）
1. 报表期：主模式沿用「年-月」现算现导（任意历史月份可查），另加「按年」模式（选年份→全年 12 个月+累计+同比），不做预生成。
2. 分市州明细里的城际城乡公交/巡游出租/网约车：**保留指标行但留空**，表尾加说明行（数据待城市客运模块接入）。
3. 运政车辆数：随旅客月报一起导入（同文件第二 sheet），按报表期存储、重复导入覆盖；审核按同报表期匹配。

### 本轮已完成（全部经样例数据联调验证）
1. **数据库**（docs/init.sql 追加「八、公路旅客运输（H203-1）」段）：
   - 新表 h2031_enterprise_monthly（28 字段，对齐样例列）、passenger_auth_vehicle（企业代码/名称/车辆数/载客位数）
   - 预置 H2031 规则 8 条（RULE_P001~P008，report_type=H2031；compare_type 新增 MOM_EQ_ZERO/MOM_PCT/MOM_EQ/EXISTENCE）
2. **后端**：
   - 导入：`DataImportService.importPassengerMonthly`（sheet0 月报按表头解析 + sheet1 运政固定 4 列；幂等覆盖；只清 H2031 规则审核结果，不误删货运结果）；`/api/import/passengerMonthly`
   - 审核：`AuditEngineService.executePassengerAudit`（4 组规则：运政 DIFF 车辆±3/载客位±50；客运量+周转量环比=0；平均运距环比±10%；包车平均运距=上月；无班线/无包车有量矛盾）；`/api/audit/execute|results` 增加 reportType 参数（H2032/H2031）
   - 报表：`ReportExportService.exportPassengerCityDetail(period, mode)`（month/year 两种模式；当年 1-N 月或全年 12 月 + 累计 + 同比；自动带出近 3 年区块；全省=17 市州汇总；客运量/周转量换算万人、平均运距=周转量/客运量加权）；`/api/report/export/passengerCityDetail?period=&mode=`
   - 数据查看：`DataViewController` 新增 h2031 / passengerAuth 类型
3. **前端**：数据导入加「H203-1旅客月报」；数据查看加「H203-1旅客月报/旅客运政车辆」；审核结果加报表类型切换；报表生成加旅客区块（月报/年报切换）；工作台文案更新
4. **文档**：docs/database.md 补 H203-1 两表 + 14 条规则 + 旅客报表行

### 联调结果（样例 2026 年 6 月，769 家企业）
- 导入：769 行成功（5 月/6 月各一次，5 月为模拟上月数据）
- 审核 2026-06：共 2057 条问题，6 类规则全部触发验证通过（运政对比 67/110、环比=0 各 737、包车平均运距=上月 397、无包车有量 4、平均运距环比 5）
- 报表：月报 94 列 / 年报 106 列，累计=5+6 月、同比与去年区块正确、说明行在
- 前端 4 个 chunk 已包含新页面（js/3,4,5,7.js）

### 环境重要变化（务必记录）
- 本机 MySQL 5.7（D:\mysql\mysql-5.7.41-winx64）原来没在跑，且 root 密码与配置不符；已用 --skip-grant-tables 重置 root 密码为 `root` 并正常启动在 **3305**（与 application.yml 一致）。
- traffic_audit 库原来是无关旧结构（audit_results/reports 等 5 张表），已按 README 流程重跑完整 docs/init.sql 重建项目库；遗留旧表 audit_results/audit_rules/report_data/reports 未删（无害）。
- 启动：`powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`（沙箱内直接 ProcessStartInfo 起后台被策略拦截，必须走 start-dev.ps1）。

### 已知边界 / 待办
- H203-1 企业解释页（ExplainReview）仍只列 H2032；旅客 sheet 无核实解释列，暂不接解释流程（需求未要求）。
- 审核结果按 reportType 过滤在前端切换；audit_result.report_id 同时可指向 h2032/h2031，attachInfo 已兼容双表。
- 下一步：能耗 H204（车辆粒度，需审核引擎补 CROSS_TABLE 跨表引用货运月报）→ 城市客运（TREND/RATIO_CHANGE 规则 + 部级下发数据源）→ 投资（先定对接投资系统 vs 解析市州 Excel）。
- 待用户确认后提交 Git（仓库 Gitee 私有，见第九节）。

### 2026-08-23 IDEA 手动运行报「找不到或无法加载主类 com.trafficaudit.TrafficAuditApplication」
- 根因：不是代码问题。IDEA 的 Maven 导入/索引重建尚未完成时点 Run，   raffic-audit-server\target\classes 下没有编译出的 .class（只剩 yml），Spring Boot 运行配置的 Make 步骤没产出，classpath 里没有主类。
- 修复：命令行执行 cmd /c mvn.cmd -q -f traffic-audit-server\pom.xml compile 补出 55 个 .class（含 TrafficAuditApplication.class）；停掉了命令行后端链（cmd 33764 / mvn java 28228 / app java 15952，由 start-dev.ps1 启动），释放 8090。
- 用户再点 IDEA 绿色 ▶ 即可；若仍失败：Build → Rebuild Project，或 File → Invalidate Caches and Restart。
- 注意：用户贴的运行命令里 Java 路径显示 jdk1.8.0\_202（带下划线）是复制显示误差，实际 JDK 是 C:\Program Files\Java\jdk1.8.0_202（存在，无需改）。
- 前端 8080（node 31196/24168）仍在跑，代理指向 8090；IDEA 后端一起即可用。

### 2026-08-23 下午会话：IDEA 跑通 + 数据查询失败排查（已解决）
**最终状态：项目可正常使用，旅客运输数据可导入**
- 后端最终在 **IntelliJ IDEA** 里跑通：用户手动在 IDEA 打开项目后，通过 UI 自动化触发运行（Shift+F10），成功启动 `TrafficAuditApplication`（最终进程 PID 9188，14:42 启动，8090 监听）。此后用户可在 IDEA 里直接点 ▶/■ 管理后端。
- 前端：8080 中途掉线，已用 `npm run serve` 重新拉起（`traffic-audit-web/frontend.log` 记录，PID 3324），`/api` 代理正常。
- 环境确认：IDEA 路径 `D:\Development_Tool\IntelliJ IDEA 2020.1.1\bin\idea64.exe`（注意是 `Development_Tool` 无下划线）；JDK `C:\Program Files\Java\jdk1.8.0_202`；IDEA 运行配置 `TrafficAuditApplication`（module=traffic-audit-server）已存在于 `.idea/workspace.xml`，无需新建。

**数据查询失败排查记录（重要，避免下个会话重复踩坑）**
- 现象：前端 `DataView.vue` 报「数据查询失败」，后端 `/api/data/list?type=h2032` 等全部 500（只有 default 分支的 type 返回 200）。
- 排查结论：**不是代码/数据库问题**。已核对：7 张表全部存在且为空、实体字段与表列完全匹配（脚本逐一对比）、SQL 逻辑正常。
- 验证方法：临时命令行起 8091 诊断实例（`mvn spring-boot:run` 加 `-Dspring-boot.run.arguments="--server.port=8091 ..."`，参数必须用引号包裹、空格分隔），同一份代码所有类型查询全部 200 → 排除代码/DB。
- 结果：之后 IDEA 实例（同一 PID 9188 未重启）所有类型也恢复 200，判断为**启动初期的临时异常**（可能与 IDEA Make 增量编译/classpath 就绪时序有关），无需修复代码。
- 已验证类型：`h2032 / transportAuth / trackMileage / scaleSplit / freightTurnover / h2031 / passengerAuth`，8090 直连和 8080 前端代理均 200。诊断实例已停（8091 无残留进程）。
- 若再遇到同类 500：先直接 curl `http://localhost:8090/api/data/list?type=h2032` 判断后端状态；后端没问题就刷新页面；必要时让用户在 IDEA 里 **Build → Rebuild Project** 后重 Run。

**本会话已讨论、待下个会话开工的内容（用户已确认方向）**
1. 需求范围：货运审核规则（已有）+ **公路旅客运输（H203-1，已实现并可导入）** + **城市公交/城市客运** + **投资模块**（用户已把模板放到 `扩展表模板`）。
2. 报表体验需求（用户问题 1）：希望**按年/按月动态出表**——不预生成所有表，而是用户查询哪年哪月就生成哪种表，参考报表导出现有模式做动态参数化（月报/年报已在旅客模块实现 `passengerCityDetail?period=&mode=`，可作样板）。
3. 功能 2/3（用户问题 2、3）：整体思路参考货运模块的做法（导入→审核→报表 同链路），具体细节待新会话按 `docs/扩展模块评估.md` 展开。
4. 竞品/开源对比已产出：`docs/开源项目对比.md`（结论：无直接可复用的开源竞品，自研+模块化扩展是合理路线）。
5. 代码仍未提交 Git（Gitee 私有仓库）——待用户确认后提交。

**下个会话建议从哪开始**
- 先让用户确认优先级：a) 动态年/月报表生成（体验优化，改动集中在报表导出）→ b) 城市公交/城市客运模块 → c) 投资模块。
- 若会话再次变长，继续把进展追加到本文件末尾并提醒用户开新会话。

### 2026-08-23 晚间会话：旅客中口径 3 表 + 能耗 H204 模块（已完成并验证）
**需求（用户原话）**
1. 《公路旅客运输月度生产情况》根据《公路旅客月报》生成：公路旅客分市州明细（已有）+ **中口径明细、中口径排名、中口径分析**（本次新增）。
2. 《道路货运车辆能源消耗情况（2026年）》根据《第二季度货车能耗明细》与《运政车辆信息》对应字段校验，**有误报出提醒**；无误则生成《能运汇总表》。

**已完成（后端已编译，端到端验证通过）**
- 数据导入：`DataImportService.importEnergyMonthly`（能耗明细 sheet0：每行 5 组×18 列，列起点 0-based 3/21/39/57/75；运政 sheet1 固定 5 列；码表转中文；幂等删除同 period 两表+H204 审核结果；失败带行号），端点 `POST /api/import/energyMonthly`。实体 `EnergyVehicleQuarterly` 的 `fuelPer100km` 加了 `@TableField("fuel_per_100km")`（表列名带下划线，曾导致导入全失败）。
- 审核：`AuditEngineService.executeEnergyAudit`（4 条规则已入库：RULE_E001/E002 车辆类型/燃料类型 CROSS_DIFF、RULE_E003 标记吨位 CROSS_DIFF threshold=0.05 且牵引车(码11)用准牵引质量、RULE_E004 EXISTENCE_AUTH 车牌缺失）；`AuditController` 已加 H204 分支。样例结果 577 条（吨位 383、运政缺失 192、车辆类型 2）。
- 汇总表：`ReportExportService.exportEnergySummary(period)` → 全省 + 17 市州各一张 sheet（按燃料类型分 6 行 + 合计；平均吨位=总吨位/车辆数、平均运距=周转量/货运量、百公里单耗=消耗量/总行程*100、周转量单耗=消耗量/周转量*100*系数：柴油0.86*1.4571、汽油0.73*1.4714、LNG/CNG 1.7572、纯电0.1229、氢0.3329*12.1951）。样例导出与模板一致（仅总行程/载货里程比模板示例少 34，经源文件直接求和确认是模板旧数据，非代码问题）。
- 旅客中口径：`exportPassengerMidDetail/Rank/Analysis(period, mode)`（month/year 动态出表；明细=客运量块+周转量块各 18 地区×5 指标；排名=左块当月+右块 1-N 月累计，双块均为客运量/周转量+排名/同比/增速排名；分析=全省累计+同比+占比），端点 `/api/report/export/passengerMidDetail|MidRank|MidAnalysis`。
- 前端：`ReportExport.vue` 旅客卡片加 3 个中口径按钮 + H204 能运汇总卡片；`DataImport.vue` 加 `energyMonthly` 导入类型；`AuditResult.vue` 加 H204 报表类型。
- 文档：`docs/init.sql` 追加「九、H204」段（两表 DDL + 4 条规则）、`docs/database.md` 补 h204 两表说明；`HANDOFF.md` 本段。
- 修复：`AuditEngineService.attachInfo` 改为按规则 reportType 分表回填企业名称（h2032/旅客/H204 三表 id 各自自增，原来 putIfAbsent 会串企业名）。

**当前运行状态（23:31）**
- 后端：命令行 `start-dev.ps1` 启动（8090，日志 `backend.log`，PID 链 cmd→mvn→java）。**IDEA 实例已不在**（无 java 进程），用户若要回 IDEA 需 **Build → Rebuild Project** 后再 Run。
- 前端：`npm run serve` 重启（8080，PID 15900，日志 `traffic-audit-web\frontend.log`）。
- DB 已有 H204 样例数据（1284 辆 + 1114 运政，period=2026-06）与 577 条审核结果，页面可直接查看。
- 临时文件：项目根 `energy-test.log`（8091 诊断日志）保留未删；临时 py 脚本在 `%TEMP%\check_*.py`。

**已知边界/决策**
- 中口径的城际城乡公交/巡游出租/网约车无数据源（等城市客运模块），明细/排名/分析中这些行留空，公路班线=旅客月报一~四类+包车合计；总=四者之和（当前=公路班线）。
- 能耗车辆类型码→中文采用反推码表（01 普通/02 平板/03 仓栅/04 厢式/06 罐/07 特殊结构/08 自卸/09 车辆运输车/11 半挂牵引车）；审核对比时先去掉运政"重/中/轻型"前缀再按允许集合匹配，避免误报。
- 能耗汇总只统计能耗明细全部车辆（含运政缺失的），"运政缺失"由审核提醒而非剔除。

**下个会话建议**
- 城市客运（公交/出租/网约车数据源）→ 投资模块。若用户回 IDEA 运行，需先 Rebuild。

### 2026-08-24 会话：投资模块实拆 + 实施方案（待用户确认后开工）
**产出**
- 已实拆 `docs/扩展表模板/投资/` 全部样例（输出 4 张领导表、投资系统导出、市州上报客运/物流报表、全省汇总中间表），结论与方案见 **`docs/投资模块实施方案.md`**（新增）。
- 关键发现：
  - 投资系统导出（`查询结果(投资系统-客运+物流 2026.7).xls`）8 列最干净，但**无市州、无进度/批复字段**，只能做审核比对基准。
  - 市州上报表格式不统一（列数 18~24、.xls/.xlsx/.et/.pdf 混存、标题行位置不一），需容错解析。
  - 全省汇总中间表（`6月/7月客运站投资明细表.xlsx`、`6月物流站场投资明细.xls`）**格式统一**，建议一期主入口。
  - 4 张输出表 = 同一批项目 4 种视角（全省预安排计划 / 十五五物流重点 / ≥1亿规上 / 经济强县），抽一套项目主档即可复用。
- 方案要点：两期落地（M1 全省汇总大表导入+4 张报表；M2 市州单表容错解析+系统导出比对审核）；数据模型 `investment_project` + `investment_monthly` 两张表；审核规则 report_type=INVEST（CROSS_DIFF/RANGE/LOGIC/NULL_CHECK）；4 个导出端点 `investPlan/investFiveYearLogistics/investBillion/investCounty`。

**待用户确认（明天开工前）**
1. 主数据源：先"全省汇总大表"（M1）还是直接"市州单表解析"？
2. 系统导出是否每月都有、能否提供项目-市州对照（导出无市州字段）？
3. 亿元项目口径 ≥10000 万是否准确？经济强县是否有固定名单？

**当前运行状态**
- 后端 8090（start-dev.ps1 启动，跑含 H204 的新代码）、前端 8080（npm run serve，PID 15900）均在跑；H204 样例数据与 577 条审核结果在库。
- 临时文件：项目根 `energy-test.log` 保留；`%TEMP%\pyxlrd`（xlrd 2.0.2 临时安装）、`%TEMP%\dump_xls*.py`、`%TEMP%\check_*.py` 保留。
- 环境备注：系统 python 的 site-packages 无写权限，装库需 `pip install --target %TEMP%\pyxlrd` 后 `sys.path.insert`。

**下个会话建议**
- 先请用户确认上面 3 个问题 → 按 `docs/投资模块实施方案.md` 开工 M1（全省汇总大表导入 + 4 张报表，用 6/7 月样例核对）。
- 若用户想先做城市客运，则需先确认网约车拆分口径与部级数据源（此前结论：投资在前、城市客运在后）。

### 2026-08-24 晚会话：投资模块 M1 落地验证 + 审核匹配误报修复
**背景**：用户确认 ①主数据源先按“全省汇总大表”做；②市州小表主要更新 自开始建设累计/自年初累计/本月完成/建设阶段/形象进度 字段，并与《查询结果(投资系统-客运+物流 2026.7)》相应字段校验；③4 张输出表为固定格式项目。
**已完成（M1）**
- 数据模型：`investment_project`(148) + `investment_monthly`(148, 2026-07) + `investment_system`(148) 三表；导入类型=投资月报（全省汇总大表）+投资系统导出。
- 4 张报表导出端点已跑通：`investPlan`(预安排计划进度汇总 247行)、`investFive`(十五五物流 54行)、`investBillion`(亿元项目 2sheet：投资总表+规上项目表 56项)、`investCounty`(经济强县 45行)；样例文件在 `%TEMP%\invest_*.xlsx`。
- 审核规则 4 条（RULE_I001~I004，report_type=INVEST）。
**报表内容核对结论（与 docs/扩展表模板/投资/输出/ 7月样例比对）**
- 经济强县表：41 项目逐行与样例一致（总投资/自开始累计/本年计划/自年初累计/本月完成 0 差异）。
- 预安排计划表：内部自洽（29 市州小计=明细，客运+物流=合计）；83 个同名项目数值仅 5 处“2026年计划”差异（丹江口右岸/丹江口柑桔/军山矿业/同洲智慧/神农架物流园，源于汇总大表与市州表数据不同）；生成 149 项目 vs 样例 167（覆盖差异）。
- 十五五物流表：35 项目数值与样例 0 差异；样例另有 28 项目不在汇总大表中（待二期市州单表补）。
- 亿元项目表：56 项目全部 ≥1亿 筛选正确、合计自洽；与样例 7 处数值差异均为**样例自身填错**（样例把 自开始累计/1-7月累计 误填到 总投资/全年计划 列，生成表用汇总大表正确值）；月度计划/完成列样例有、生成表留空（源数据无）。
**审核匹配误报修复（AuditEngineService 投资部分）**
- 修复前 15 条问题中 4 条跨表差异为误报：①孝感东城客运换乘中心(更名为…) 被模糊匹配错配到 郧西县客运换乘中心；②咸丰县综合物流园 与 罗田县综合物流园 归一化后同名(“综合物流园”)导致错配。
- 修复内容：sysMap 改为 归一化名→候选列表；精确命中按县区消歧；模糊匹配改“评分取最优”（前缀>中后部包含>5字>子序列），不再首命中返回；归一化增加 Ⅱ/II 统一；新增子序列兜底（综合枢纽↔综合客运枢纽、物流中心↔物流园中心、智慧/二级站等插入词）。
- 修复后：RULE_I001/I002/I003 全部 0 误报；缺失提醒 11→5（丹江口右岸/汉川北站/通山城西/国胜智慧/小河港区Ⅱ期/天门 6 条已正确匹配且数值全同；剩余 5 条为真实缺失需人工核实：郑万高铁巴东综合客运枢纽、唐白河港散货转运中心项目、湖北长江现代物流产业集聚示范区·现代物流园、弘业现代物流产业园、崇阳县国家级综合物流枢纽及配套设施建设项目）。
**当前运行状态**
- 后端 8090（start-dev.ps1 重启，PID 7668，日志 backend.log）、前端 8080（npm run serve，原进程）均在跑；H204 与投资模块数据都在库。
- 临时文件：`%TEMP%\invest_*.xlsx`（4 张导出验证件）、`%TEMP%\invest_dump.txt`、`%TEMP%\sample_dump.txt`、`%TEMP%\sample_plan.txt`、`%TEMP%\plan_diff.txt`、根目录 energy-test.log 均保留。
**待办**
- M2：17 市州单表容错解析（补充十五五表缺的 28 个项目）+ 市州小表“本月完成/建设阶段/形象进度”字段更新入库。
- 4 张报表与 7 月样例差异点（5 处 2026年计划、预安排覆盖差异、亿元表月度列留空）请用户核对口径。
- 亿元表“投资总表”sheet 目前仅“（五）其他=106.65亿（本年计划合计）”，其余行空白，待确认季度拆分口径。

### 2026-08-24 深夜会话：城市客运开工讨论（结论：可以做，等数据源）
**用户提问**：现在是否可以加城市客运模块？
**结论**：可以上，且正好补全旅客中口径报表——H203-1 中口径明细/排名/分析里一直空着的 城际城乡公交/巡游出租/网约车 三行，等城市客运数据进来即可填上。框架已由投资模块验证（多数据源导入+审核+报表全链路复用），无需新架构。模板 `docs/城市客运/城市客运数据模板.xlsx`（11 sheet：公交/出租/网约车/轨道轮渡/城市分市州/中口径等，含 2026 年 1-7 月分市州数值）。
**开工前需用户确认（按优先级）**
1. 公交、巡游出租分市州月度原始数据来源（市州上报 or 系统可查）——需一份真实数据文件做导入样例（最大前置）。
2. 网约车拆分口径与部级下发文件（模板拆分公式多处 #REF!，放最后做）。
3. “客运量同比环比 0% 需核实”业务口径（模板目录同名 txt），确认哪些算正常避免误报。
**建议实施三步（先易后难）**：①公交（4 组规则）先跑通导入+审核+分市州报表；②巡游出租（7 组规则，补 运营车数 vs 运政 对比，复用 H203-1 运政对比）；③网约车拆分（部级数据到位后做，顺手补中口径三表空行）。
**工作量**：后端 6~10 + 前端 2~3 人天（docs/扩展模块评估.md）；比投资 M2 小。
**下一步**：用户提供公交月度数据文件后开工第 1 步。


### 2026-08-24 深夜会话（续）：城市客运第 1 步（公交）落地
**背景**：用户确认公交月度数据源 = `docs/城市客运/导入_城市公共交通月度运营情况（2026年7月）.xls`（实为 xlsx 内容、.xls 扩展名，企业级明细 143 行，含公共汽电车/轨道/轮渡三类，第 1 步只取公共汽电车字段）；运政数据待用户后补（属出租步骤）。
**已完成（公交 M1）**
- 数据模型：`city_bus_monthly` 表（企业级月度，44 字段）；建表+规则 SQL 见 `docs/sql_city_bus.sql`。
- 导入：`/api/import/cityBus`（period=2026-07 成功 142 条、0 失败；幂等：同报表期先清旧数据与 CITY_BUS 审核结果；失败显示 Excel 行号）。市州由 `RegionUtil.cityByCode(所属地区)` 映射到 17 市州。
- 审核：4 条规则（report_type=CITY_BUS，compare_type=TREND_CONSISTENCY / RATIO_CHANGE / AVG_DIST_CHANGE，均为 YELLOW）：
  - RULE_B001 城市内与城际城乡客运量趋势一致（环比/同比各一对，趋势不一致且增速>2%）
  - RULE_B002 客运量与旅客周转量趋势一致（环比/同比各一对，趋势不一致且增速>2%）
  - RULE_B003 城市内/城际城乡客运量占比与上月变化>1%（用文件内环比增速反推上月占比）
  - RULE_B004 平均运距环比增减>3 公里（文件直读）或城际城乡平均运距变化>3 公里（由 周转量/客运量 环比反推）
  - 2026-07 审核结果 53 条：B001=25、B002=12、B003=15、B004=1（嘉鱼鸿昌城际城乡平均运距 4.8 公里）。
- 报表：`/api/report/export/cityBusDetail` 生成_城市公交客运量分市州明细.xlsx（全省+17 市州 × 4 指标 × 1..N 月+月同比+本年累计+上年 1-12 月+累计）；全省 7 月 12974.73/87147.68/11508.07/59265.28 与模板 0 差异。
- 前端：数据导入页新增「城市公交月报」、数据查看页新增「城市公交月报」、审核结果页新增「CITY_BUS」、报表生成页新增「城市客运报表（公交，第1步）」卡片；均已热更新生效。
**踩坑记录**
- 数据文件扩展名 .xls 但内容是 xlsx（ZIP 魔数），openpyxl 按扩展名拒绝——复制成 .xlsx 即可；后端 POI `WorkbookFactory` 按内容自动识别，不受影响。
- `start-dev.ps1` 经 `powershell ... | Select-Object` 管道启动时，后台 cmd/mvn/java 继承管道句柄会导致会话挂起；改为 `*> start-script.log` 输出重定向后脚本正常收尾（但会话仍会挂到结束，勿 Ctrl+C 以免误杀后端进程树）。另注意：后端曾被 IntelliJ 启动（idea64 下的 java 应用进程），按 PID 只杀应用链即可，勿动 idea64。
- MySQL 5.7 的 `INSERT ... SELECT ... WHERE NOT EXISTS(派生表列)` 报 Unknown column，改逐条 `WHERE NOT EXISTS(SELECT 1 FROM audit_rule WHERE rule_code=...)`。
**待办/口径待确认**
- 客运量同比环比 0% 需核实（`docs/城市客运/客运量的同比环比是0% 需核实（主要出现在公交）.txt`）暂未纳入规则，等业务口径确认。
- 公交报表的 2025 年各月列待 2025 数据导入后自动填充（同比同理由库内上年数据计算）。
- 第 2 步巡游出租已完成（见下方补充记录）；第 3 步网约车拆分等部级数据。
**当前运行状态**
- 后端 8090（start-dev.ps1 重启，PID 12712，日志 backend.log）、前端 8080 均在跑；`city_bus_monthly` 已有 2026-07 数据（142 行）。
- 临时文件：`%TEMP%\bus_data.xlsx / bus_dump.txt / tpl_dump.txt / city_bus_detail.xlsx / city_bus_report*.txt / dump*.py`、项目根 `start-script.log`、`docs/sql_city_bus.sql`（建表+规则迁移脚本，建议保留）均未删。

### 2026-08-24（续2）：城市客运第 2 步（巡游出租）落地
**背景**：用户已放入运政数据（`输入_出租车信息(运政车辆信息).xls`，真 OLE .xls，28MB，42636 行）。月报数据源 = `导入_巡游出租汽车运营服务情况月报（2026年7月）.xls`（真 .xls，市州级 17 行、41 列）。
**已完成（巡游出租）**
- 数据模型：`city_taxi_monthly`（市州月报 41 字段）+ `city_taxi_auth`（运政车辆明细）；建表+规则 SQL 见 `docs/sql_city_taxi.sql`（含规则 INSERT，可重复执行）。
- 导入：`/api/import/cityTaxi`（17 行 0 失败，幂等清旧+审核结果）；`/api/import/cityTaxiAuth`（42636 行，约 6 分钟，幂等清旧）。市州归属：月报按区划代码（`RegionUtil.cityByCode`，恩施州 422800/神农架 429021 正常识别），运政按 证号→档案→经营权→地址 正则 `(4290\d{2}|42(?:0[1-9]|1[0-3]|28)\d{2})` 提取（实测 42636 行全部归市州）。
- 审核：7 条规则（report_type=CITY_TAXI）：
  - RULE_T001 运营车数 vs 运政对比（CROSS_DIFF_PCT，3%，RED）
  - RULE_T002 城市内/城际城乡客运量趋势一致（TREND_CONSISTENCY）
  - RULE_T003 客运量/周转量趋势一致（TREND_CONSISTENCY，周转量环比由 客运量环比×平均运距环比 推导，check_field=turnoverMomDerived）
  - RULE_T004 城市内客运量占比变化>1%（RATIO_CHANGE）
  - RULE_T005 平均运距变化>3公里（AVG_DIST_CHANGE，城际城乡由上期平均运距=本期−增减反推）
  - RULE_T006 单车次载客人数变化>0.2人（PAX_PER_TRIP_CHANGE，由上期 载客车次/客运量环比 反推）
  - RULE_T007 载客车次/客运量趋势一致（TREND_CONSISTENCY，阈值 0.01）
  - 2026-07 审核 6 条：T001 黄冈 1931vs2043(5.48%)、神农架 59vs71(16.9%)；T002 潜江；T004 孝感/咸宁/潜江。
- 报表：`/api/report/export/cityTaxiDetail` 生成_巡游出租客运量分市州明细.xlsx（全省+17市州×4指标×1..N月+同比+累计+去年12月），全省 7 月 5860.24/34236.60/5351.24/27422.13 与 `巡游出租_模板.xlsx` 0 差异。
- 前端：数据导入页新增「巡游出租月报」「出租车运政车辆」、数据查看页新增同两项、审核结果页新增「CITY_TAXI」、报表生成页新增「城市客运报表（巡游出租，第2步）」；均已热更新生效。
**踩坑记录**
- Spring 默认上传上限 10MB，28MB 运政文件被拒 → `application.yml` 加 `spring.servlet.multipart.max-file-size/max-request-size=100MB`。
- `audit_result` 表无 enterprise_name 列（瞬态字段），`attachInfo` 回填时 CITY_BUS/CITY_TAXI 落到 H2032 表导致名称显示“原数据已重新导入”占位 → 已修：按 report_type 分表回填公交（企业名）/巡游出租（市州名）+核实说明，公交/出租均受益。
- 月报城市字段原用 `normalizeCityName(企业名称)`，恩施“恩施土家族苗族自治州”无法识别 → 改用 `cityOf(地区代码,名称)` 优先按区划代码，并给 RegionUtil 增加“恩施土家族苗族自治州→恩施州”别名。
- 运政 42636 行逐条 insert 曾约 6 分钟，前端 axios 30s 超时导致页面"导入失败"；已改 MyBatis BATCH 批量插入 + JDBC `rewriteBatchedStatements=true` + 前端 timeout 600000，数据库插入阶段约 30 秒（总耗时约 5 分钟主要在 26.8MB xls 的 POI 解析）；同报表期重导先删后插，幂等实测收敛 42636 行。
**当前运行状态**
- 后端 8090（start-dev.ps1 重启，日志 backend.log）：当前进程链 cmd 31740 → mvn(java) 31652 → app(java) 31452（勿误杀；重启时按此链停）；前端 8080（用户进程，勿杀）均在跑；`city_taxi_monthly` 17 行、`city_taxi_auth` 42636 行（2026-07/2026-08 各 42636 行，2026-08 为修复批量导入后的完整重导，非脏数据）。
- 临时文件：`%TEMP%\taxi_data.xlsx / taxi_dump.txt / yz_stat2.txt / yz_full.txt / city_taxi_detail.xlsx`、根目录 `start-script.log`、`docs/sql_city_taxi.sql` 均保留未删。
- 待办：第 3 步网约车拆分（等部级数据）；公交/出租报表的 2025 年各月列待 2025 数据导入后自动填充。


### 2026-08-24（续3）：城市客运报表改为按模板底稿生成
**需求**：城市客运输出要“根据目录下的模板按照模板生成对应的输出模板”。
**实现**（`ReportExportService`）
- `exportCityBusDetail` / `exportCityTaxiDetail` 不再从零建表，改为 `exportCityByTemplate(模板文件名, period, 今年各月数据, 去年各月数据)`：读 `docs/城市客运/城市公交_模板.xlsx` / `巡游出租_模板.xlsx` 为底稿，保留标题/表头/合并单元格（63 处）/边框/数字格式（0.00_）/公式，仅替换数据区市州月度值。
- 模板结构：Sheet1，row1 标题、row3-4 表头、数据区 row5-76（全省+17市州×4指标，每地区 4 行）；2026 月度列 0-based col2,4,...,14，2025 月度列 col19,21,...,41，同比/累计列为公式（全省行月度列=17市州求和公式）。
- 填充规则：市州行 2026 年 1..N 月有值填 2 位小数、无值清空模板样例；2025 年 1..12 月库内有值填、否则清空（等 2025 数据导入后自动填充并触发同比公式）；全省行与同比/累计公式一律保留；写回前 `FormulaEvaluator.evaluateAll()` 重算公式缓存值（Excel 打开也可重算）。
- 模板定位：`application.yml` 新增 `city-passenger.template-dir: docs/城市客运`，`resolveTemplate` 按 配置目录→user.dir→user.dir/.. 三级回退；数据区行数守卫（<75 行报错防模板改版错位）。
**验证**：2026-07 导出，全省+17市州×4指标（客运量/周转量/城市内客运量/城市内周转量）与库内聚合 0 差异；公交全省 12974.73/87147.68/11508.07/59265.28，巡游出租 5860.24/34236.60/5351.24/27422.13；输出 sheet 名/合并单元格/表头与模板完全一致。
**注意**：模板 2026 段同比公式引用 2025 列，当前 2025 列无数据，Excel 打开同比显示 #DIV/0!（模板原样行为），2025 数据导入后自动算对。


### 2026-08-24（续4）：运政车辆导入"不能导入"修复
**现象**：`导入_出租车信息(运政车辆信息).xls`（26.8MB，42636 行）在数据导入页点"开始导入"一直失败。
**根因**：
- 前端 `src/api/index.js` 全局 axios `timeout: 30000`，后端旧实现逐条 `insert` 约 6 分钟 → 30 秒后请求被前端断开，页面报"导入失败"。
- 前端 `DataImport.vue` 的 cityTaxiAuth 模板提示名误写为 `输入_...`（实际文件是 `导入_...`）。
**修复**（均已生效）：
- `DataImportService.importCityTaxiAuth` 改 MyBatis BATCH 模式（`openSession(ExecutorType.BATCH)` + `flushStatements()` + `commit()`），方法加 `synchronized` 防并发重复导入；
- `application.yml` JDBC URL 加 `rewriteBatchedStatements=true`（批量 flush 由约 4 分钟降至约 30 秒）；
- `DataImport.vue` cityTaxiAuth 模板名改回 `导入_`，导入请求 `timeout: 600000`。
**验证**：21:57 重新导入 2026-07，`import_batch` id=31 为 42636/42636/0，`city_taxi_auth` 2026-07 恰好 42636 行（幂等：id=30 与 id=31 两次导入均收敛 42636）；2026-08 旧代码重复导入产生的 77262 行脏数据已 DELETE。
**注意**：总耗时约 5.3 分钟，主要是 POI(HSSF) 解析 26.8MB/42636 行，仍在 600s 超时内；如需更快可后续改事件流解析（easyexcel）或拆分文件。
### 2026-08-24（续5）：城市客运报表系列按模板生成（6 表 + zip）
**需求**：识别《导入_城市公共交通月度运营情况（2026年7月）》《导入_出租车信息(运政车辆信息)》《导入_巡游出租汽车运营服务情况月报（2026年7月）》三份源数据，按目录下模板生成系列输出表；格式（列宽/表头/合并规则）与模板完全一致，仅替换数据。
**目录变化**：模板目录由 `docs/扩展表模板/城市客运` 移至 `docs/城市客运`；`application.yml` 的 `city-passenger.template-dir` 已同步改为 `docs/城市客运`（`ReportExportService` 的 `@Value` 默认回退值一并修正）。
**实现**（`ReportExportService` + `ReportExportController` + `ReportExport.vue`）
- 数据扩展：公交源文件（企业级 142 行）除公共汽电车外还含**轨道**（武汉 11701.74/周转 96240.86，黄石 30.09/404.37）与**轮渡**（武汉 46.05/156.57）；`city_bus_monthly` 加 4 列（rail/ferry 客运量+周转量），`importCityBus` 映射 0 基列 13/14/17/18（N/O/R/S）后 142 行重导成功。
- 新导出接口（`/api/report/export/`）：
  - `cityRailFerryDetail`：轨道行 Excel 4/6/8（全省/武汉/黄石，+1 为周转量行），轮渡行 13/15；全省月度列保留求和公式。
  - `cityPassengerCitySum`（`城市分市州_模板` / `城市客运各市州明细表_模板`）：客运量区 r5-22、周转量区 r27-44；B=总累计、G=公交、L=出租、Q=网约车（无源数据清空）、V=轨道、X=轮渡；E/J/O/T/W/Y 增速列无去年同期 → 清空模板样例。
  - `cityPassengerSummary`（`城市汇总_模板`）：2026 段 B/D 填库内累计、C/E 同比清空、网约车行置 0；2025/2024 段（G..Q 列）保留模板历史参考值不动。
  - `cityPassengerSeries`：一键 zip（公交/出租/轨道轮渡明细 + 分市州累计 + 各市州明细表 + 汇总）。
- 前端 `ReportExport.vue` 新增“城市客运报表（系列）”卡片（4 个单表按钮 + 一键打包 zip）。
**POI 0 基教训**：POI 行号是 0 基，之前按 Excel 1 基写导致整块错位一行（轨道读到 96645.23 等错位值）；已改 0 基（轨道 3/5/7、轮渡 12/14、分市州 4/26、汇总 2..8），重生成后数据全部核对通过。
**验证（2026-07）**：轨道 武汉 11701.74/96240.86、黄石 30.09/404.37；轮渡 全省=武汉 46.05/156.57；分市州累计 武汉 B=17060.44（=公交 4218.74+出租 1093.91+轨道 11701.74+轮渡 46.05）、黄石 B=1254.8、林区 B=27.15；汇总 总客运量 B3=30612.85、公交 12974.73、出租/巡游 5860.24、轨道 11731.83、轮渡 46.05；2025/2024 段与模板一致；表头/合并/列宽全部 MATCH（仅数据行按设计替换）。
**输出**：`docs/城市客运/输出/生成_城市公交客运量分市州明细.xlsx`、`生成_巡游出租客运量分市州明细.xlsx`、`生成_轨道轮渡客运量分市州明细.xlsx`、`生成_城市客运客运量分市州累计.xlsx`、`生成_城市客运各市州明细表.xlsx`、`生成_城市客运汇总.xlsx` 共 6 个文件。
**坑（脚本编码）**：`%TEMP%\gen_series2.ps1` 若用无 BOM 的 UTF-8 保存，PowerShell 5.1 按 ANSI 读取会把中文路径读成乱码，复制到 `D:\鏂囨。\ChatGPT\traffic-audit\docs\...`（本次误建的乱码目录，未删）；已用带 BOM 版本重写，现正确写入 `docs\城市客运\输出`。



### 2026-08-25 上午会话：城市客运链路恢复验证 + 数据库连接根因修复
**现象**：新对话启动前后端（start-dev.ps1 确认 8090/8080 就绪）后，`/api/data/list` 全部类型 500、`/api/audit/results` 500；仅 default 分支（investment*）返回 200 空数据。
**排查**：后端是 IDEA 启动实例（日志不进 backend.log），起 8091 诊断实例（`mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8091`）复现，堆栈根因：
- `java.sql.SQLNonTransientConnectionException: Public Key Retrieval is not allowed`（HikariPool 初始化失败）。
- 本机 MySQL 8 root 认证插件为 `caching_sha2_password`（mysql 客户端可连），JDBC URL 缺 `allowPublicKeyRetrieval=true` → 非 SSL 连接拒绝取公钥。
**修复**：`application.yml` / `application.yml.example` / `target/classes`（同步）JDBC URL 加 `allowPublicKeyRetrieval=true`（保留 rewriteBatchedStatements=true）；停 IDEA 旧实例 → start-dev.ps1 重启 → 全部类型 200。
**恢复验证（全部与 08-24 记录一致）**：
- 重跑审核：CITY_BUS 2026-07 = 53 条（B001=25/B002=12/B003=15/B004=1）；CITY_TAXI 2026-07 = 6 条（T001=2/T002=1/T004=3）。之前公交 53 条被 23:21 的 142 行重导（幂等清结果）冲掉且未重跑；出租库里残留的是 2026-08 的 6 条。
- 6 张报表重新生成（`docs/城市客运/输出/`），关键数值全部核对：公交全省 12974.73/87147.68/11508.07/59265.28；出租武汉 1093.91/8532.5；轨道武汉 11701.74/96240.86、黄石 30.09/404.37；轮渡 46.05/156.57；分市州累计 武汉 B=17060.44/黄石 1254.8/林区 27.15；汇总 总 30612.85/公交 12974.73/出租 5860.24/轨道 11731.83/轮渡 46.05；系列 zip 6 文件齐全。
**小修复（与 HANDOFF 08-24 设计不符处）**：`setDataCell` 对 `v==0` 执行 `c.setBlank()`，导致汇总表"网约车行置 0"实际输出为空；新增 `setZeroCell`（显式写 0.0）用于 B7/D7，重生成后 B7=0、D7=0，其余数值不变。
**待办不变**：城市客运第 3 步（网约车拆分）等部级数据源；公交 2025 各月列等 2025 数据导入；"客运量同比环比 0% 需核实"（txt 为空）等业务口径；中口径三表（H203-1 明细/排名/分析）的 城际城乡公交/巡游出租 行可在城市客运数据基础上接入（建议下一步，需确认口径：公交取 passengerChengxiang 字段，出租源文件无城际城乡客运量字段需确认拆分口径）。
**坑**：apply_patch 在本环境全部报 "Access is denied"（连根目录文件也拒），改用 PowerShell `[System.IO.File]::ReadAllText/WriteAllText`（UTF-8 无 BOM）编辑；`mvn spring-boot:run` 不会自动重拷 resources，改 yml 后需手动同步 target/classes 或跑 `mvn compile`。


### 2026-08-25 下午会话：报表生成/企业解释/数据导入 UI 重构（用户确认口径后开工）
**需求**：①城市客运报表在报表生成页合并为一个模块；②页面美化 + 报表可选生成/一键全部 + 支持一个月/几个月/一年；③企业解释加入公路旅客与城市客运（能耗/投资无解释，不做）；④数据导入界面优化；⑤货运/旅客/投资等模块同步统一。
**后端新增/修改**（已编译重启，8090 就绪）
- `ReportExportService`：新增 `exportFreightSeries` / `exportPassengerSeries` / `exportInvestSeries` / `exportSelectedSeries`（前端「生成选中」多选时按 type 列表打包 zip，避免浏览器拦截多个下载）；`REPORT_FILE_NAMES` 映射 18 张表。
- `ReportExportController`：新增 `/export/freightSeries`、`/export/passengerSeries`、`/export/investSeries`、`/export/selected?types=a,b,c&mode=` 四个 zip 端点；全部导出端点加 `logExport` 留痕。
- 新增 `OperationLog` 实体 + `OperationLogMapper` + `OperationLogService`（自动从 Authorization 头解析用户、X-Forwarded-For 取 IP），写入 `sys_operation_log`（表原本为空，现已有记录）。
- `ExplainController`：`/api/explain/list` 加 `reportType` 参数，支持 H2032/H2031/CITY_BUS/CITY_TAXI 四类，返回类型对应列。
- `DataImportController`：新增 `GET /api/import/batches?type=&limit=`（导入批次历史，`import_batch` 表）。
- `DbQueryExecutor`：白名单注册 `h2031_enterprise_monthly` / `city_bus_monthly` / `city_taxi_monthly`（AI 对话可查）；`LLMService` 系统提示支持 context 传入 `reportType`/`tableName` 引导查表。
**前端（vue-cli 热更新已生效）**
- `ReportExport.vue` 重写：五个模块（货运/旅客/能耗/投资/城市客运）统一卡片布局（grid），城市客运 6 张表合并为一张卡；每模块 checkbox 多选 + 「生成选中」（单选直下、多选打包 zip）+「一键生成全部(zip)」；旅客保留月报/年报两档（年报选年份，period=yyyy&mode=year）；底部使用提示说明期数口径（选 07=1~7 月、选 12=全年+上年同比）。
- `ExplainReview.vue`：报表类型下拉（货运/公路旅客/城市公交/巡游出租），表格列按类型动态显示，关键字标签随类型切换（出租按市州）；AI 分析 context 增加 reportType/tableName。
- `DataImport.vue`：导入类型按 货运/公路旅客/能耗/城市客运/投资 五组分区展示；右侧导入设置卡；下方「最近导入记录」表格（类型/期/文件名/总行数/成功/失败/时间，来自 /import/batches）；cityTaxiAuth 显示约 5 分钟耗时提示。
**验证（全部通过）**
- `/api/import/batches`：正常返回最近 10 条。
- `/api/explain/list`：H2032=28 条（2026-07）、H2031=0、CITY_BUS=109、CITY_TAXI=8（神农架等 8 市州有解释）。
- zip：selected（cityBusDetail+cityTaxiDetail+cityPassengerSummary）、freightSeries、passengerSeries（month/year）、investSeries 文件齐全；旅客年报 104810/47498 字节（>月报 95824/43439，正确）。
- 留痕：sys_operation_log 已记录 6 条「报表生成」（未登录时 userId 为空，detail 为 UTF-8 中文正常）。
- 前端 chunk 7/4/1 已包含新代码（report/export/selected、import/batches、reportType 等标记），无编译错误。
**说明/边界**
- 能耗模块只有 1 张表，不显示「一键生成全部」。
- 「几年」维度：固定模板表只支持当年 1~12 月 + 上年同比两段（领导表格式），多年对比如需可后续加非模板「区间明细导出」。
- 企业解释 H2031 当前 0 条是因为样例数据该期未填解释，接入逻辑本身已通。
- apply_patch 仍不可用（Access denied），前端大文件用 Python 整文件重写，小改动用字符串替换。



### 2026-08-25 晚上会话：月报/年报全模块 + 能耗模板化 + 企业解释未填写 + 报表页下拉导出（用户确认口径后实施）
**需求**：①布局改为 货运→公路旅客→城市客运（旅客右边）→能耗→投资；②月报/年报切换加到 货运/旅客/城市客运/投资；③生成内容改多选下拉框 + 单按钮《导出》；④数据导入界面进一步美化；⑤企业解释加“未填写”与过滤开关；⑥硬性要求：货运/旅客/投资/客运新表必须与【格式模板】列宽/表头/合并规则完全一致，仅替换数据，导出 Excel。
**后端（已编译重启验证）**
- 年报 mode 扩展：`monthOf(period, mode)`（year→12）；`exportCityDetail/exportFreightRank/exportTurnoverRank`、`exportCityBusDetail/exportCityTaxiDetail/exportCityRailFerryDetail/exportCityPassengerCitySum/exportCityPassengerSummary`、`exportCityByTemplate`、`investPlan/investFiveYearLogistics/investBillion/investCounty` 及三个 series 与 `selectedReportData` 全部加 mode 透传；控制器 16 个端点加 `mode` 参数。货运年报标题显示「报表期：2026年全年」。
- 能耗 `exportEnergySummary` 改为模板底稿：`docs/公路旅客+能耗/模板_能运汇总表 .xlsx`（新增 `energy.template-dir` 配置 + `resolveAnyTemplate`），保留标题/表头/合并(A1:M1、A11:G11)/公式(D/J/L/M 与合计 SUM)/列宽/样式，仅填数值列（B/C/E/F/G/H/I/K）；全省 + 17 市州 clone sheet；季度标题改中文数字（2026年第二季度）。
- 投资 4 表去掉 `autoWidth`：与 7 月样例一致（样例 0 合并、无自定义列宽，表头/内容 08-24 已验证逐行一致）。
- `ExplainController`：默认返回全部记录（含空解释），新增 `hasExplanation=true` 过滤；`DataImportService.importPassengerMonthly` 补解析「核实性原因解释」列（当前源文件 28 列无此列 → H2031 全部显示“未填写”，属源数据问题）。
**前端（chunk 1/7 已含新代码）**
- `ReportExport.vue` 重写：模块顺序 货运→公路旅客→城市客运→能耗→投资（grid：货运整行，旅客左/城市客运右，能耗左/投资右）；生成内容 = el-select 多选下拉（全选/清空）+ 单按钮「导出」（选 1 张直下、多张 zip，按钮显示张数）；货运/旅客/城市客运/投资均有月报/年报 radio（能耗保持季度末月）。
- `ExplainReview.vue`：「仅显示已填写」el-switch（→ hasExplanation）+ 空解释显示「未填写」warning 标签。
- `DataImport.vue`：默认报表期=当前月；批次表加成功/失败着色与「状态」列（成功/部分失败/无数据）；每类型加一句导入说明。
**验证（全部通过）**
- explain：H2031 无过滤 771 / 过滤 0；H2032 过滤 28；CITY_BUS 142；CITY_TAXI 17。
- 能耗：18 sheets（全省+17 市州），标题「2026年第二季度能耗汇总情况表」，公式/合并保留，武汉柴油车 375 等数值正确。
- 年报：货运 28 列（12 月+同比）、城市公交 45 列（2026 12 月+2025 12 月）；`selected?period=2026&mode=year&types=...` zip 4 文件正常。
- 前端编译成功（Compiled successfully），chunk 1/7 含 hasExplanation/select-wrap/exportChecked 标记。
**坑**
- 分段替换（Python）时 `c.find()` 找到早于目标的行导致文件复制出一整段城市客运代码 → 编译报“重复方法”+ Lombok 连锁报错 → 用行索引精确删除重复块 [2033..2560) 后 `mvn clean compile` 通过。教训：批量替换后必须 clean compile + 检查方法唯一性。
- start-dev.ps1 若上次会话未退出（`*>` 重定向被后台子进程持有句柄）会并发重复启动 → 先确认 8090/8080 空端口再启动；backend.log 判就绪要确认是新写入内容（旧日志会误判 OK）。
**待办 / 需用户提供**
- 【格式模板】基准文件：货运输出表（货运量分市州明细/货运量排名/周转量排名）与旅客输出表（分市州明细 + 中口径 3 表）目前仓库无输出格式模板（`docs/货运` 只有输入模板与 08-04 生成件；`模板_交企统H203-1表` 是空壳），需用户提供基准文件才能做“仅替换数据”改造；城市客运（8 模板）、能耗（1 模板）、投资（7月样例 4 .xls）已按模板/样例对齐。
- 投资 DB 当前仅 50 条 2026-07 月度数据（41 个经济强县项目仅 1 条有月度数据），需重新导入完整投资月报才能生成完整报表（报表逻辑正常，是数据量问题）。
- 旅客中口径的城际城乡公交/巡游出租/网约车行仍待城市客运口径接入。

### 2026-08-25（续5，调研测试）：用户更新旅客输入/输出样例 + 投资校验需求（待确认口径后实施）
**用户改动（本次会话开头发现）**
- 公路旅客输入 `docs/公路旅客+能耗/公路旅客简化工作.xlsx` 更新（11:21，707KB），现含 6 sheet：公路旅客6月报（28列×770行，仍无核实性原因解释列）、运政车辆数、公路旅客分市州明细/中口径明细/中口径排名/中口径分析（4 个内嵌样例）。
- 新增 `docs/公路旅客+能耗/输出/` 4 张**模板格式样例**（用户手工基准，非程序生成）：
  - `生成_公路旅客分市州.xlsx`：58行×284列、237 合并；r4-7=全省(客运量/周转量/个体客运量/个体周转量)，r8 起 17 市州 2~4 行不等（武汉/鄂州/荆州/恩施/仙桃/潜江/天门/林区无个体行）；C..O=2026年1-6月+累计、R..AP=2025年12月+累计、AS..=2024 全年；同比/累计=公式，历史值样例自带。
  - `生成_中口径明细.xlsx`：188行×43列、143 合并；客运量块 r5-94 + 周转量块 r99-188，各=全省+17市州×5指标(总/班线/公交/出租/网约车)；数据区 **2378 个外部引用公式**（`[1]班线包车!C8`、`[1]公交!C9-[1]公交!C11`、`[1]出租!`、`[1]网约车!`）指向 `D:\王琴的工作文件\客货运月度数据汇总\2026年\6月\2026年6月客运量、货运量(111)1.xlsx`；内部公式 4818 个（同比/累计）。
  - `生成_中口径排名.xlsx`：20行×9列**单块累计**（市州/客运量/排名/同比/增速排名/周转量/排名/同比/增速排名，RANK+SUM 公式，标题"2026年1-6月全省分市州累计完成道路客运生产情况"）——注意工作簿内嵌 sheet 是双块(当月+累计18列)，独立样例改成单块，需与用户确认按哪种生成。
  - `生成_中口径分析.xlsx`：7行×8列、1 合并；总/班线/公交/出租/网约车 × 累计客运量/同比/占比 + 累计周转量/同比/占比（总=23496.1693/0.0777、周转 917059.1993/-0.0295）。
- 投资新增 3 个 0 字节需求 txt：①投资输入要与《模板_查询结果(投资系统-客运+物流 2026.7)》校验、不一致弹窗；②按 6/7 月文件夹市州报表更新《6/7月物流站场投资明细》项目和数据；③按 6/7 月文件夹更新《更新_6/7月客运站投资明细表》两张大表（用户原文疑似笔误，应为 6月/7月两张）。
**测试结果（前后端均在跑：8090/8080）**
- 旅客导入新 xlsx：`POST /api/import/passengerMonthly` → 769 条成功+767 运政，0 失败；`/api/data/list?type=h2031&period=2026-07` total=769 ✓；cityBus=142、cityTaxi=17 ✓。
- 旅客 4 表当前导出结构全部与样例不符：分市州 401×96/0合并 vs 58×284/237；中口径明细 191×96/0 vs 188×43/143；排名 18列双块 vs 9列单块；分析 7×8/0合并 vs 7×8/1合并 → 需全部按样例模板化。
- 投资校验：`POST /api/audit/execute?reportType=INVEST&period=2026-07` → 2 条 PENDING（RULE_I004 郑万高铁巴东综合客运枢纽投资系统缺失；RULE_I003 天门市物流中心本月完成 3058 vs 投资系统 600，绝对差2458/相对差409.7%）✓ 校验数据已具备（investment_project/monthly/system 各 148 条），**前端弹窗未实现**。
- 投资 4 表导出 investPlan/FiveYearLogistics/Billion/County 全部 OK ✓（08-24 已验证与 7 月样例一致）。
**待用户确认口径后实施**
1. 旅客 4 表模板化（仿 `exportCityByTemplate`）：以 `docs/公路旅客+能耗/输出/` 4 张为底稿，保留表头/合并/列宽/行高/样式/内部公式，数据区填库内值；**外部引用公式必须替换为数值**（源文件 `王琴的工作文件` 不在项目内，否则打开断链弹更新）；生成后 `FormulaEvaluator.evaluateAll()` 重算缓存值。
2. 需确认：分市州"个体客运量/周转量"行数据源（输入无个体字段）；中口径 出租/网约车 城际城乡口径（样例出租 3131.95/网约车 2063.45 为用户参考值，DB 无此字段，公交有 passengerChengxiang/turnoverChengxiang 可填）；排名表按单块累计还是当月+累计双块。
3. 投资弹窗：DataImport.vue 导入投资月报后调 audit/execute?reportType=INVEST，有 PENDING 弹窗列差异明细。
4. 投资输入更新 M2：解析 6/7 月文件夹市州 xls 报表→按项目名更新《更新_6/7月客运站/物流站场投资明细》字段（自开始累计/自年初累计/本月完成/建设阶段/形象进度），需先定匹配键与覆盖策略，建议 1 市州原型。
**临时产物**：`_test_passenger/`（4 张旅客现导出 + 4 张投资现导出，对比用）。

### 2026-08-25（续6，实施完成）：旅客 4 表模板化 + 个体客运量导入 + 投资校验弹窗（用户已拍板 3 口径）
**口径确认**：①中口径明细跨簿公式→替换为库内数值（2025 列保留模板缓存值）；②分市州"个体客运量/周转量"行=用户导入个体数据后按市州聚合填充；③中口径排名=单块累计（选 1 个月出当月、1-6 月出累计）。
**后端（已编译重启验证）**
- `application.yml` 新增 `passenger.template-dir: docs/公路旅客+能耗/输出`；`ReportExportService` 4 个旅客导出方法全部改为模板底稿生成（保留表头/合并/列宽/公式/样式，仅替换数据）：
  - 分市州：2026 年 1..6 月列填库内班线客运量/周转量（metric 0/1），个体行填个体导入数据，2025/2024 历史列保留模板值，累计/同比/全省行公式保留重算。
  - 中口径明细：数据区 2378 个跨簿引用全部替换——2026 月度列填库内值（班线=h2031、公交=cityBus 城际城乡、出租/网约车=显式 0），2025 列替换为模板缓存值（去年数据不丢），累计/同比/总行公式保留重算。
  - 中口径排名：单块累计，标题随报表期（1 月="2026年1月…"，1-6 月="2026年1-6月…累计"，年报="1-12月…"）；B/D/F/H 填值，RANK/SUM 公式保留。
  - 中口径分析：B/C/F/G 填值（总/班线/公交/出租/网约车累计+同比），占比公式保留。
- 新增个体客运量导入：表 `passenger_individual_monthly`（period/region_code/enterprise_code/enterprise_name/passenger_count/turnover），接口 `POST /api/import/passengerIndividual`（POI 解析列名含"个体客运量/个体周转量"，同 period 幂等），实体/Mapper `PassengerIndividualMonthly`。
- 文件名统一为样例名：生成_公路旅客分市州.xlsx、生成_中口径明细.xlsx、生成_中口径排名.xlsx、生成_中口径分析.xlsx（REPORT_FILE_NAMES + series zip + 前端同步）。
**前端（chunk 4/7 已含新代码）**
- `DataImport.vue`：公路旅客组新增「个体客运量/周转量」导入；投资月报（客运/物流）导入成功后自动调 `audit/execute?reportType=INVEST`，有 PENDING 弹窗列出差异明细（规则名/项目/实际/基准/差异），无差异提示一致。
- `ReportExport.vue`：旅客 4 张选项名与样例一致，提示语更新。
**验证（全部通过）**
- 4 张表 dims/合并单元格与样例完全一致（分市州 58×284/237、中口径明细 188×43/143、排名 20×9/1、分析 7×8/1），外部引用残留 0。
- 数值抽查：武汉 6 月班线客运量 341.1759/周转量 19301.074（与样例一致）；黄石个体客运量 3.0/周转量 150.0（导入 30000 人/150 万人公里）；2025 列保留模板值且转数值（R11=255.17）；全省行公式重算正确（周转量 K 列 112416.37）。
- 个体导入：4 条成功 0 失败，重复导入幂等；测试数据已清理（DB 0 条）。
- 年报模式：标题"2026年1-12月…"正确。
- 投资校验：2 条 PENDING（郑万高铁巴东枢纽缺失、天门物流 3058 vs 600）→ 前端弹窗数据源就绪。
**踩坑（重要）**
- **POI 5.2.5 `Cell.setCellValue(double)` 对公式单元格只更新缓存值、不移除公式**！写入前必须先 `setBlank()` 再 `setCellValue`；显式 0 需操作底层 XML（`getCTCell().setT(N).setV("0")`）。中口径明细外部引用替换因此返工一次。
- 分市州模板周转量/个体行 A 列为空（合并单元格只写首行）→ 行识别须用 B 列指标 + 前一个非空 A 列（currentRegion），否则这些行被跳过保留模板样例值。
- 原 `metricValue(agg, 1)` 返回客运量（0/1 口径相同）→ 分市州周转量行直接取 `agg.turnoverTotal/10000`。
- 共享公式判断：POI `getCellFormula()` 展开正常，但 `keepCached`/`fillMidCell` 必须先读缓存值再 setBlank（顺序不可反）。
**待办**：①分市州/中口径明细模板仅 1-6 月列，7-12 月需用户下半年模板；②中口径出租/网约车城际城乡数据源待接入（现显式 0）；③投资 M2（按 6/7 月文件夹市州报表更新《更新_6/7月客运站/物流站场投资明细》）未开工，需定匹配规则；④DB 投资月度仅 50 条 2026-07（investment_monthly），完整报表需补导入。

### 2026-08-25（续7）：模板一致性全量核查 + 货运 3 表模板化改造（已完成验证）
**用户要求**：核查 城市客运/货运/能耗/板块（旅客/投资）导出是否满足「与导入模板的列宽、表头、合并规则完全一致，仅替换数据，导出 Excel」。
**核查结论（14 张全部 PASS）**
- 城市客运 6 张（公交/巡游出租/轨道轮渡/分市州累计/各市州明细/汇总）：结构完全一致（含 63/63/95/18/18/4 合并、列宽、表头）；数据差异均为口径所致（选当月/累计、同比清空、网约车显式 0）。
- 公路旅客 4 张（分市州/中口径明细/排名/分析）：结构完全一致（237/143/1/1 合并）。
- 能耗 1 张：全省 Sheet1 与 `模板_能运汇总表 .xlsx` 完全一致（合并 2、列宽 5）；另按需求生成 17 市州 sheet；标题改回模板的「第X季度」（原代码写「X季度」）。
- 货运 3 张：**本次从零建表改造为模板底稿生成**（模板=`docs/货运/生成_*.xlsx`，与 `货运简化工作.xlsx` 同结构）：
  - 分市州明细：以模板为底稿，填 C~M 月度值/同比 + O/P 累计/累计同比；月度列仅 1-6 月（模板固定），累计列按所选期 1..N 月（N>6 时月度列仍只显示 1-6 月，与旅客口径一致，7-12 月待下半年模板）。
  - 货运量排名/周转量排名：以模板为底稿，填 B~P（规上/规下/合计 + 排名/占全省比重/同比/增速排名）；货运量 Q/R 占比公式保留不动，周转量 Q/R 按新数据重算。
  - 排名表补上了原先缺失的 规上同比/规下同比（全省+市州；规下同比=模板去年合计-H2032去年规上）。
- 新增 `freight.template-dir: docs/货运` 配置（application.yml）+ `resolveFreightTemplate`。
- 修复过程中发现的坑：POI 列号 0-based 差一列（月度值写到 B/D/F/..，已修正为 C/E/G/..）；写值前须 setBlank（POI 公式单元格只更新缓存）。
**验证方式**：`_test_check2/v5_*.xlsx`（14 张现导出）逐一与模板对比 dims/合并集合/列宽集合，全部 PASS；抽查排名表 2026-07 规上数据落位正确（全省 186.8988、武汉 72.9224 排名 1、占全省比重 0.3902）；能耗标题=2026年第二季度能耗汇总情况表。
**注意**：货运 DB 当前仅 h2032 有 2026-07 数据（40 条），`freight_turnover_import`/`scale_split_transport` 为空 → 明细/排名现导出大部分为空（仅规上行有值），属数据未导入，非格式问题；用户需先导入《模板_货运量周转量》《规上规下拆分表》。
**待办不变**：①模板仅 1-6 月列，7-12 月需下半年模板（货运/旅客同）；②投资 4 表仍为代码自建布局（样例为 .xls 无合并/无自定义列宽，暂与样例对齐），未纳入模板底稿。

### 2026-08-25（续8）：投资 4 表改为「模板底稿原位替换」（已完成验证）
**用户要求**：公路旅客、城市客运、能耗、投资四个模块必须按【格式模板】的列宽、表头、合并规则完全一致生成，仅替换数据，导出 Excel。
**本轮改造（ReportExportService.java，`traffic-audit-server/src/main/java/com/trafficaudit/reportexport/service/ReportExportService.java`）**
- `investPlan`（全省预安排计划进度情况汇总，约 2380 行起）：逐行扫描 R5~末尾，按 合计行/块标题行/市州小节/分组标题/项目行 分类；未匹配项目整行清空（保留合并样式）；`一、客运站场基础设施建设`→客运站场块、`二、交通物流基础设施建设`→物流园区块、`三、老旧营运货车报废更新`→整块清空（无数据源）。
- `investFiveYearLogistics`（十五五规划物流项目，约 2511 行起）：sheet1 全量原位替换（85×248/99 合并）；sheet0（月2）仅更新日历标题（模板 sheet0 本身无样例数据）。
- `investBillion`（亿元投资）：上轮已为模板底稿，保持（17×6/2 + 80×24/25）。
- `investCounty`（经济强县，约 2659 行起）：遍历 R4 起按 B 列项目名匹配，未匹配保留空白。
- 新增辅助方法（约 2710 行起）：`nvl`/`blankInvestRow`（setBlank 0..lastCol 保留样式/合并）/`templateCityFull`（模板短名→规范市州，含 林区/恩施 别名，走 RegionUtil）/`isCityLabel`/`matchInvest`（先按类别/市州过滤候选，再评分取最优）/`normInvestName`/`investNameScore`（归一化精确>前缀包含>中后部包含>5字>子序列>LCS 兜底；县区前缀不一致扣 400；归一化同名且模板带县区但候选不含→拒绝，避免 宜都↔当阳 误配）/`isInvestSubsequence`/`investLcs`/`extractInvestCounty`。
- `writeInvestAggHssf`：移除 col12（自筹）写入（无数据源），保留 7/8/9/22/23。
**验证（全部通过）**
- 结构对比 `_shots/cmp_invest2.py`：4 表 dims/合并/列宽与模板完全一致（investPlan 272×38/111；investFiveYearLogistics sheet0 32×24/33 + sheet1 85×248/99；investBillion 17×6/2 + 80×24/25；investCounty 65534×256/57）PASS。
- 数据落位 `_shots/dump_data_check.py`：全省合计、市州小节、项目数据、老旧货车段清空、五五表合计行清空、强县表项目及备案号写入均正确。
- 名称匹配质量 `_shots/sim_match3.py`：PLAN 130/183、FIVEYEAR 40/63、COUNTY 41/41；未匹配均为“模板样例有但汇总大表/DB 无”的项目（老旧货车段、农村站亭、武汉天河综合客运枢纽、荆州市铁水联运物流中心等），属数据缺失非误配。
- 产物：`_shots/invest_out2/`（4 .xls + selected4.zip）；本轮 API 复测：`GET /api/report/export/selected?period=2026-07&mode=month&types=investPlan,investFiveYearLogistics,investBillion,investCounty` 正常返回 zip（4 文件齐全，命名正确）。
**前端现状确认（本轮核对，无需再改）**
- 报表生成页：第一排 货运/公路旅客/城市客运，第二排 能耗/投资；生成内容多选下拉+全选/清空+单「导出」按钮（1 张直接下载、多张打包 zip）；月报/年报 单选齐全。截图 `_shots/report_page.png`。
- 数据导入页：报表期卡片 + 货运/公路旅客/城市客运/能耗/投资五个下拉框（模块选择），上传/导入/最近记录齐全。
- 企业解释页：4 类报表字段完整（企业名称/车辆数/客运量/周转量/平均运距/企业解释等），无“只能看到企业名”问题。
- 数据查看：轨迹里程/货运量周转量/H203-1/城市公交月报/巡游出租月报 均有「全屏查看」。
- 密码加密：sys_user.admin 已是 BCrypt（60 位），满足“账号加密存储”需求。
**遗留**：①老旧货车报废更新块/五五表合计行无数据源（等二期数据）；②货运 DB 缺《模板_货运量周转量》《规上规下拆分表》导入，明细/排名导出大部分为空（格式正常，数据未导入）；③模板仅 1-6 月列，7-12 月需下半年模板（货运/旅客同）；④投资 M2（市州单表解析）未开工。


### 2026-08-25（续9）：HANDOFF.md 恢复 + 下班前收尾（已完成）
**事件**：本会话中 HANDOFF.md 曾被误覆盖（一条 PowerShell WriteAllLines 命令因 AddRange(Object[]) 类型错误失败，`$result` 只剩新头行 → 文件被覆盖成 506 字节），随后一次有 bug 的重放又把它污染成 28,084 字节（「十节」重复）。
**恢复方法（已完成并验证）**：从 4 个会话 JSONL 日志重放 31 条历史写入命令到沙盒 `_shots/handoff_replay/`（必须用 pwsh 7.6.4 + 路径替换修复版脚本，路径含反斜杠需用 chr(92) 拼接避免被 Python 解析成转义），逐字校验：base 与 08-22 原文一致、文件头尾与破坏前读取快照一致、各步输出与原始输出对齐。已恢复为 74,447 字节（原 74,547，差 100 字节/52 字符为中间段空白级差异，日志已截断无法恢复，不影响内容）。污染版备份在 `_shots/HANDOFF.md.polluted_1633.bak`（保留未删）。
**下班前收尾**：已用 `start-dev.ps1` 完整重启前后端并验证：
- 后端 8090 就绪（日志 backend.log，`Started TrafficAuditApplication` + `Tomcat started on port(s): 8090`，PID 30380，HTTP 200）。
- 前端 8080 就绪（日志 traffic-audit-web/frontend.log，`Compiled successfully` + `App running at:`，PID 23624，HTTP 200）。
- IDEA 本体在运行（idea64.exe，11:00 启动）；后端当前由命令行/start-dev 管理，若想改回 IDEA 管理：先在 IDEA Run 配置选 `TrafficAuditApplication` 点 ▶（会占用 8090，需先停命令行实例），或直接用脚本重启。
**下次开工建议**：先读 AGENTS.md + 本文件；确认投资 M2（市州单表解析）优先级；遗留事项见续8（货运明细/排名缺数据源、模板仅 1-6 月列、老旧货车报废更新块等二期）。


### 2026-08-26 凌晨会话：数据库清空 + 用户 4 项意见处理（已完成验证）
**用户指令**：①所有输出文档必须与【格式模板】列宽/表头/合并完全一致、仅替换数据；②逐模块核对需求（点名：巡游出租规则 7 条界面只显示 4 条、能耗规则没看）；③企业解释行间距太大；④重复导入是否会存两份。
**0. 数据库清空（用户要求）**
- 26 张表 TRUNCATE 全清（表结构保留、自增重置），备份 `_shots/db_backup_20260826_004520.sql`（28,115,426 字节，含全库结构与数据）。
- 清空后已恢复 `audit_rule`：从备份提取原 33 条 + 新增 H204 6 条 = 39 条。`sys_role`(4)/`sys_dept`/`sys_user` 未恢复（原 sys_user 本就 0 行；需要时从备份或 init.sql 重新初始化）。
**1. 模板一致性（核心修复：路径配置错误）**
- 发现：`application.yml` 的 `passenger.template-dir: docs/公路旅客+能耗/输出` 指向**不存在**的目录（实际目录 `docs/公路旅客/输出`）；能耗无 `energy.template-dir` 配置（默认 `docs/公路旅客+能耗` 同样不存在）；代码读能耗模板 `模板_能运汇总表 .xlsx` 而用户凌晨更新的是 `docs/能耗/生成_能运汇总表.xlsx`（00:24~00:43 用户批量更新了货运 3 张 + 旅客 4 张 + 能耗 1 张模板）。
- 修复：`application.yml` → passenger=docs/公路旅客/输出、新增 energy=docs/能耗；`ReportExportService` 能耗模板名改为 `生成_能运汇总表.xlsx`。
- 验证：10 张导出（货运 3 + 旅客 4 + 能耗 1 + 城市公交/巡游出租）调用 `/api/report/export/*` 全部 200，用 openpyxl 对比模板与导出：sheet 维度/合并单元格数/列宽 全部 PASS；投资 4 表 zip（selected）正常返回（结构此前已验）。
**2. 审核规则核对**
- CITY_TAXI：`sql_city_taxi.sql` 与清空前 `audit_rule` 均 7 条（RULE_T001~T007），`AuditEngineService` 引擎 5 种 compareType 全部实现（含 T003 周转量环比推导、T006 单车次载客人数反推、T007 载客车次与客运量趋势）。“界面只有 4 条”原因：审核结果页只显示**触发的问题记录**，未触发的规则看不到；且原规则管理页是空壳 `<div>规则管理</div>`、后端无规则 API。→ 已实现规则管理页（见下）。
- H204 能耗：需求 7 条，原只实现 4 条（E001~E004，E004 为需求外补充）。**新增 RULE_E005~E010**（引擎 `checkEnergyLoadedRatio/FuelRange/FuelMom/VsFreightReport/AvgDistVsFreight/LoadedTonnageRatio` + `prevQuarter`/`fuelPer100kmMedian` 辅助；`executeEnergyAudit` 增加上一季度环比基准与 H2032 企业月报基准；`docs/init.sql` 补种子；已入库）。
- 规则管理页：新增 `RuleManageController.java`（GET /api/rules/list、POST /api/rules/toggle、POST /api/rules/update）+ 重写 `RuleManage.vue`（6 类报表类型切换、规则全列表、阈值可编辑、等级可选、启用开关）。
**3. 企业解释行高**
- `ExplainReview.vue`：表格 `size="mini"` + 行高 32px + 单元格 padding 3px；解释列 `max-height:62px` 内部滚动，不再把行撑得过高。
**4. 重复导入幂等确认**
- 后端所有导入方法（H2032/H2031/个体/能耗/运政/轨迹/规上规下/货运周转量/投资/系统导出/公交/出租/出租运政）均为「同报表期先删旧数据+清理对应审核结果再插入」，重复导入**不会存两份**；`import_batch` 每次导入记一条属操作留痕（预期）。
- 前端 `DataImport.vue` 按钮 `:loading` 防连点；`importCityTaxiAuth` 有 `synchronized`，其余方法无锁（单用户实际无并发问题，如需强一致可加）。
**当前运行状态**
- 后端 8090 已用 start-dev.ps1 重启加载新代码（backend.log `Started TrafficAuditApplication` + `Tomcat started on port(s): 8090`，HTTP 200；`/api/rules/list?reportType=H204` 返回 10 条）。
- 前端 8080 在跑（frontend.log `Compiled successfully` + `App running at:`，热更新已加载 RuleManage/ExplainReview 新页面）。
- 验证产物：`_shots/verify_export/`（10 张导出 + invest_selected.zip）、`_shots/cmp_struct2.py`、`_shots/cmp_width.py`、`_shots/extract_rules.py`、`_shots/old_audit_rule.sql`、`_shots/patch_*.py` 均保留。
**遗留/待办**：①投资 M2（市州单表容错解析）仍未开工（素材在 `docs/投资/输入/` 齐备）；②7-12 月模板需用户提供下半年模板（或确认自行扩展 1-6 月模板）；③货运《模板_货运量周转量》《规上规下拆分表》未导入（明细/排名导出数据为空）；④老旧货车报废更新块/五五表合计行无数据源；⑤数据库已清空，业务数据与 `sys_role`/`sys_user` 需重新初始化；⑥能耗新 6 条规则的阈值（中位数±50%、环比±50%、月报对比 50%/60% 等）请用户确认口径。


### 2026-08-26 上午会话：审核结果页体验优化（keep-alive + 按条明细卡片视图，已完成验证）
**用户 2 个问题**：①点「数据」链接跳转 DataView 返回后，审核结果丢失需重新点「执行审核」；②「按条明细」界面太丑、企业和问题都看不全。
**本轮改动（纯前端，无需后端）**
- `traffic-audit-web/src/App.vue`：`<router-view />` 外包 `<keep-alive include="AuditResult">`，跳转「数据/解释」再返回时组件实例被缓存，报表期/过滤条件/审核结果/选中状态原样保留，不再需要重新执行审核。
- `traffic-audit-web/src/views/AuditResult.vue`：按条明细由 el-table 改为「一条问题一张卡片」：
  - 卡片头部：勾选框 + 企业名（完整展示）+ 报表期 + 等级 tag + 状态 tag + 「数据/解释」链接 + 确认/忽略按钮；
  - 卡片主体：规则名 + 规则编码 + 实际/基准/差异 三行（浅灰底分组展示，长文本自动换行）；
  - 顶部工具栏加「全选当前 N 条」（含半选态 indeterminate），配合原有批量确认/忽略；
  - 红色问题卡片左边框红色、黄色左边框橙色、已处理卡片整体淡化，列表区独立滚动。
- 数据加载时给每条结果初始化 `_selected:false`（保证 el-checkbox 响应式），批量选择改为 `filteredResults.filter(r => r._selected)` 实时计算。
**验证**：frontend.log `Compiled successfully in 678ms`（热更新生效，10:31:11）；页面路由跳转/返回状态保留逻辑由 keep-alive 保证。
- 追加（10:42）：用户反馈问题区域仍偏小 → 新增「聚焦查看」模式（`focusMode`）：一键隐藏统计卡/筛选栏/规则统计/h3 标题，仅留报表类型+报表期+按钮一行 + 问题列表占满（`main-focus` 收紧内边距）；退出聚焦还原。frontend.log `Compiled successfully in 1103ms`（10:42:30）。patch：`_shots/patch_focus_mode.py`。
**产物**：`_shots/patch_detail_view.py`（本轮 patch 脚本，保留）。
**遗留/待办不变**：投资 M2 仍未开工（素材在 `docs/投资/输入/` 齐备）；7-12 月模板待用户提供或确认扩展；货运《模板_货运量周转量》《规上规下拆分表》未导入（明细/排名导出数据为空）；能耗新 6 条规则阈值口径待用户确认。


### 2026-08-26 上午会话（续2）：数据导入模块补全旅客/能耗运政独立导入（已完成验证）
**用户反馈**：数据导入页「公路旅客」下拉只有月报+个体两项（货运却有 5 项），「能耗」只有 1 项；实际 `docs/公路旅客/模板_公路旅客运政车辆数.xlsx`、`docs/能耗/模板_能耗车辆运政信息.xlsx` 都有独立模板但无法单独导入（只能随月报/季报第二个 sheet 自动解析）。
**设计结论**：模块下拉 = 该模块模板清单；运政类模板支持独立导入，同时保留「随主文件第二个 sheet 自动导入」的兼容行为（后导入覆盖，幂等）。
**后端**（`DataImportService.java` + `DataImportController.java`）
- 新增 `POST /api/import/passengerAuth`：解析 4 列（企业代码/企业名称/车辆数/载客位数）→ `passenger_auth_vehicle`，同报表期先删旧数据 + 清 H2031 审核结果（`deleteRuleResults` 新私有方法）。
- 新增 `POST /api/import/energyAuth`：解析 5 列（车牌号/车辆类型/燃料类型/标记吨位/准牵引质量）→ `h204_auth_vehicle`，同报表期先删 + 清 H204 审核结果。
**前端**（`DataImport.vue`）
- 公路旅客下拉加「运政车辆数」，能耗下拉加「能耗车辆运政信息」；TYPE_LABELS 补新类型 + 大写键（最近导入记录 H2031/H204/PASSENGER_AUTH 等显示友好名）；typeDesc/templateName/endpoint 同步补充。
**验证**：后端 `mvn compile` 通过；重启后 curl 实测：旅客运政模板导入 767 条、能耗运政模板导入 1114 条，均成功（测试期 2099-01 已清理）；前端 frontend.log `Compiled successfully in 308ms`（10:55:35）。
**说明**：城市客运的轨道/轮渡/网约车模板属月报字段与拆分逻辑（需求文档确认），非独立导入类型，下拉保持 3 项；投资模板按市州上报原始文件 + 汇总大表处理，下拉保持 3 项。
**产物**：`_shots/patch_auth_import.py`（后端）、`_shots/patch_dataimport_options.py`（前端）、`_shots/compile_auth_import.log`。


### 2026-08-26 上午会话（续3）：数据导入页改版——待导入队列 + 本月导入进度总览（已完成验证）
**用户反馈**：导入页五个模块下拉互斥（选一个清空其他），一次只能传一个文件，每月重复操作多；要一份"本月各模块导入状态"的检查清单。
**前端**（`DataImport.vue` 整体重写，`_shots/rewrite_dataimport.py`）
- 五个模块下拉互相独立（互斥逻辑删除），选类型后行内出现「选择文件 → 加入队列」；模板名/说明/大文件耗时提示跟随当前选中类型显示。
- 新增「待导入队列」卡片：模块/类型/文件/状态（待导入/导入中/成功/失败）/结果（失败带原因）/操作（单条导入、移除），顶部「全部导入（N）」串行逐个执行，投资类型导入后自动触发投资系统校验弹窗。
- 新增「本月导入进度」卡片：按报表期 × 模块类型展示 已导入N行（绿）/部分失败（橙）/未导入（灰），随报表期切换自动刷新。
- 「导入记录」改为按当前报表期过滤显示（limit 50）；文案修正为"选择类型并挂载文件"。
**后端**（`DataImportController.java`）
- `/api/import/batches` 增加可选 `period` 参数（limit 上限提到 200），供进度总览按报表期拉取。
**验证**：后端 `mvn compile` 通过 + start-dev.ps1 重启就绪；`GET /api/import/batches?period=2026-07` 正常返回该期记录（货运量周转量/规上规下/轨迹/运政/巡游出租均已导入）；前端 frontend.log `Compiled successfully in 522ms`（11:01:41）。
**待办（用户可选的锦上添花）**：每个导入类型旁加「下载模板」链接（后端暴露 docs 模板静态文件），用户不用去文件夹找模板。


### 2026-08-26 上午会话（续4）：数据导入页「下载模板」入口（已完成验证）
**实现**
- 后端：`application.yml` 新增 `docs.template-root: docs`；新建 `TemplateDownloadController.java`（`com.trafficaudit.config`）：`GET /api/templates/{*path}` 下载 docs 下模板，Content-Disposition 带 UTF-8 文件名，防路径穿越；模板定位与报表模块一致（配置目录 → user.dir → user.dir/.. 逐级回退，因 spring-boot:run 的 user.dir 是 traffic-audit-server）。静态资源映射方案（WebConfig）因相对路径解析失败已弃用删除。
- 前端 `DataImport.vue`：每个导入类型新增 `templateUrl`（docs 相对路径），模板说明区显示「下载模板」链接；投资两模板指向 `docs/投资/输入/客运（客运站）/` 与 `docs/投资/输入/物流（物流园区）/` 下的更新明细文件；`passengerIndividual` 无独立模板文件，不显示下载。
**验证**：14 个模板下载全部 200（含中文路径与全角括号/逗号）；前端 frontend.log `Compiled successfully in 505ms`（11:10:10）。
**注意**：投资模板文件名带月份（更新_7月…），每月需同步更新 `DataImport.vue` 的 templateUrl 或改为动态映射。


### 2026-08-26 中午会话：数据导入页 tabs 化 + 全局模块顺序统一（已完成验证）
**用户反馈**：①数据导入界面模块太多、风格繁琐；②所有页面模块顺序应统一为「货运 → 公路旅客 → 城市客运 → 投资 → 能耗」（当前部分页面把投资/能耗排在前面）。
**前端改动（4 个 Vue 文件）**
- `DataImport.vue`：五个模块下拉并排改为 **el-tabs 选项卡**（顺序：货运/公路旅客/城市客运/投资/能耗），选中类型后显示「选择文件 → 立即导入 / 加入队列」；卡片头部加引导文案；`groups` 重排为新顺序；`activeModule: 'freight'` 加入 data。操作链不变：选类型→挂文件→立即导入/加入队列→全部导入。
- `AuditResult.vue`：报表类型 radio 顺序改为 货运H2032→旅客H2031→城市公交CITY_BUS→巡游出租CITY_TAXI→投资INVEST→能耗H204。
- `RuleManage.vue`：同上顺序。
- `ReportExport.vue`：`modules` 顺序改为 freight→passenger→cityPassenger→invest→energy，卡片 CSS `repeat(6,1fr)`，第1-3张 span2、第4-5张 span3（第一排 货运/旅客/城市客运，第二排 投资/能耗）。
**验证（无头浏览器真实 DOM + 截图）**
- 前端 frontend.log 最新 `Compiled successfully`（11:30:34），无编译错误。
- 导入页 tabs = `["货运","公路旅客","城市客运","投资","能耗"]`，active=货运，按钮 = `["选择文件","立即导入","加入队列"]`，overviewGroups 同顺序，0 个 JS 错误；截图 `_shots/import_page_tabs2.png`（人工确认清爽无异常）。
- 侧边栏切页验证：审核结果 radio=货运/旅客/城市公交/巡游出租/投资/能耗 + 按条明细/按企业合并；规则管理 radio 前6项同序；报表生成卡片=货运(H203-2)/公路旅客(H203-1)/城市客运/投资/能耗(H204)；截图 `_shots/order_check3.png`（卡片布局美观）。
- **路由切页坑**：`location.hash='#/audit'` 直接赋值不生效（被重置回 #/import），必须点击侧边栏 `.el-menu-item` 切页。
**产物**：`_shots/patch_module_order.py`、`_shots/patch_radio_order.py`、`_shots/patch_tab_clean.py`、`_shots/shot_import_tabs.js`、`_shots/shot_import_tabs2.js`、`_shots/order_check.js`、`_shots/order_check2.js`、`_shots/order_check3.js`。
**待办（可选锦上添花）**：若用户仍觉繁琐，可把「本月导入进度」与「选择类型挂载文件」两张卡合并成一张；导入类型旁「下载模板」链接已在续4落地。


### 2026-08-26 中午会话：投资 M2 市州单表批量导入（已完成验证）
**需求**：HANDOFF 遗留「投资 M2（市州单表解析）未开工」→ 实现按市州单表目录批量导入客运站场/物流园区月度数据。
**实现**
- 后端 `DataImportService.importInvestCityDir(period, category)` + `POST /api/import/investCityBatch`（period=yyyy-MM，category=客运站场|物流园区）：扫描 `docs/投资/输入/{类别目录}/{N月}` 下全部 xls/xlsx/et（跳过 pdf，N月由 period 推导），容错解析每个文件（定位表头行 + 列名关键词映射 + 双层表头合并 + 市州小节行识别），逐文件返回行数/失败行号，幂等（同类别同报表期月度+INVEST 审核先删，项目主档按「项目名+类别」upsert）；与「模板_十五五规划物流项目进展情况.xls」规范化匹配标记 is_five_year。
- 前端 `DataImport.vue` 投资 tab 新增「市州单表批量导入（客运站场/物流园区）」类型 +「从目录批量导入」按钮 + 逐文件结果弹窗。
- 文件读取：只读文件必须 `new FileInputStream(f)` 包一层（直接 `WorkbookFactory.create(File)` 抛「拒绝访问」）。
**DB 现状（mysql 3308 / traffic_audit）**
- investment_project：客运站场 46、物流园区 132（已清 2 个孤儿残留）；全部 total_investment>0。
- investment_monthly：客运 6月35/7月46、物流 6月132/7月133（共 346），0 失败；2026-07 十五五项目 35 个。
- 导出 `GET /api/report/export/investFiveYearLogistics?period=2026-07` 合计：总投资 2038714.59 / 自开始累计 691375.3 / 自年初累计 246779.55，与 DB 聚合逐分一致（probe：`_shots/verify_export_m2/report_v2.txt`）。
**本轮新踩坑（务必记住）**
1. 「总投资」vs「计划总投资」：武汉等表头是「总投资」；宜昌/襄阳等是「计划   总投资（万元）」（中间有空格）→ 列映射必须 `contains("计划总投资")||contains("总投资")` 且排除「累计」，否则 total=0。
2. **公式单元格**：.et（WPS 跨表公式 `='2026年6月 '!I12+L12`）`DataFormatter.formatCellValue` 无 evaluator 时只返回公式文本→解析 0。修复：`getDecimal/getDecimalOrNull/getString` 对 FORMULA 单元格读 `getCachedFormulaResultType()`/`getNumericCellValue()`。
3. **多 sheet 历史文件选期**：襄阳 .et 含 1-7 月 12 个 sheet，原逻辑「选 countInvestRows 最多」会错选 2月 sheet（首个 6 行），7月数据错存 2月值。修复：`investSheetMatchesPeriod` 按 sheet 名含「N月/0N月/period」优先（数据行>0 时 +1000000 分）。
4. 项目名含换行（`咸宁高新区冻库冷链项目
（一期）`）：`replaceAll("[\r\n]+","")`；修复前残留的孤儿项目（黑豹国际物流园/咸宁冻库）已从 investment_project 删除（无月度引用）。
5. 无 seq 列（随州 Sheet2）：有 seq 按序号判定、无 seq 用 `investmentCity(nt)` 识别市州行。
6. 「填报单位」市州提取必须 contains 匹配（"武汉市交通运输局客运事业发展中心"）。
7. 潜江/林区文件解析 1 条（潜江传化公路港）是正确的；多 sheet 选期修复不影响其结论。
**十五五 28 个缺项目（真实缺口）**
- 模板 63 项，规范化匹配 35 覆盖 / 缺 28（数据源不在市州单表）：清单见 `_shots/five_year_report.txt`，需用户提供数据或确认口径。
**产物**：`_shots/insert_m2.py`（M2 代码插入）、`_shots/fix_*.py`（各 bug 修复）、`_shots/fix_formula_cached.py`、`_shots/fix_sheet_period.py`、`_shots/m2_compile*.log`、`_shots/ProbeEt*.java`（POI 公式/多 sheet 探测）、`_shots/verify_export_m2/`（十五五导出复验）、`_shots/five_year_report.txt`、`_shots/verify_m2.js` + `_shots/m2_batch_dialog.png`（前端弹窗验证）。
**待办**：①28 个十五五项目缺口等用户提供数据源；②能耗新 6 条规则阈值口径待确认；③货运《模板_货运量周转量》《规上规下拆分表》未导入；④7-12 月模板待用户提供；⑤可选「本月导入进度」与「挂载文件」两卡合并。


### 2026-08-26 午后会话：报表生成 P0 三项 + 模板数据规则梳理（已完成验证）
**背景**：用户问「报表生成模块怎么看」→ 给出评估（模板底稿生成是亮点；数据完备性不可见/错误信息被吞/文件名不一致/单文件过大/月报语义易误读），用户同意先做 P0 三项。
**P0-1 数据就绪校验**
- 后端 `ReportExportService.checkExportReady(period, mode, types)` + `GET /api/report/ready`：按报表类型统计依赖表行数（month 精确匹配 report_period、year 用 likeRight 年份前缀）：
  - 货运三表 → 模板_货运量周转量(freight_turnover_import) + 规上规下拆分表(scale_split_transport) + H203-2 月报(h2032_enterprise_monthly)
  - 旅客四表 → H203-1 月报(h2031_enterprise_monthly) + 个体(passenger_individual_monthly)
  - cityBus/cityRailFerry → city_bus_monthly；cityTaxi → city_taxi_monthly；城市客运汇总三表 → 公交+出租
  - 投资四表 → investment_monthly；能耗 → h204_vehicle_quarterly
- 前端 `exportChecked` 先调 ready：有缺数据表 → `$confirm`「数据未就绪」列出缺哪些（如「城市公交客运量分市州明细（缺数据：城市公交月报）」），可「仍要导出/取消」；无缺 → 直接导出。
**P0-2 错误透出**
- 新增 `GlobalExceptionHandler`（com.trafficaudit.common）：Exception → HTTP 500 + `Result.error(500, message)`（log.error 全量堆栈）；前端 `failWith(err)` 读 `err.response.data.message` 显示具体原因。
- 验证：`curl /api/report/export/energySummary?period=2026-99` → `{"code":500,"message":"32",...}` 链路通。
**P0-3 文件名统一 + MIME**
- 前端旅客 4 个 fileName 对齐后端全名（公路旅客分市州明细/中口径明细/中口径排名/中口径分析）；`buildResponse` 按 .xls 用 `application/vnd.ms-excel`、.xlsx 用 ooxml。
**顺手修复**：`ReportExport.vue` data 缺 `activeMenu: '/report'`（此前侧边栏当前页不高亮 + Vue warn）。
**验证**：ready 各表数值与 DB 逐表核对一致（cityDetail=690、passenger=771+缺个体、cityTaxi=17、invest=179、energy=126、cityBus=0 准确反映公交月报未导入）；无头浏览器（`_shots/report_ready_dialog.js`）：case1 缺数据弹「数据未就绪」确认框内容正确、case2 数据齐全直接下载+「报表导出成功」；JS 0 错误；前端 12:55:10 Compiled successfully。
**模板数据规则（用户新确认的需求方向，待口径确认）**：模板即权威，系统严格按模板三类规则填数——A 填放规则（数据区行/列/合并对号入座）、B 计算规则（模板已有公式如能耗折算系数 D3=C3/B3、M3=K3/I3*100*0.86*1.4571、城市汇总合计 P3=P4+P5+P8+P9、同比 L14=H14/M14-1 等 → 保留公式只填原始量；模板无公式如货运_货运量周转量 → 系统按口径算好填入）、C 格式规则（列宽/表头/合并/单位完全一致）。**待用户确认**：①公式类模板保留公式 vs 系统写死算好的值；②数据行数超模板预留行数时是否动态插行并同步公式；③「数据规则」是否还包括单位换算/审核后填数/月报 1~N 月口径。

### 2026-08-26 下午续：审核标记表（audit_run）落地，历史已审核数据不再误报「未审核」（已完成验证）
**用户口径（关键）**：现有数据（7 月及以前）都是线下审核通过的、可直接导出，不应提示未审核；只有 **8 月数据未审核**。之前用 `audit_result` 问题条数判断 audited 是错的——审核全通过时 0 条会误判为未审核。
**方案**：新增 `audit_run` 标记表（report_type + report_period 唯一），「已审核」以该表为准；导出前 ready 校验查 audit_run，不再依赖 audit_result 行数（auditRows 保留为信息字段）。
**后端（已编译重启验证）**
- 建表 `audit_run`（id/report_type/report_period/created_at，uk_type_period，utf8mb4），MySQL 3308 traffic_audit。
- 新增 `AuditRun` 实体 + `AuditRunMapper`（BaseMapper）。
- `AuditEngineService`：4 参数 `markAudited(reportType, period, rules, hasData)`（幂等，无规则/无数据不写）+ 新增 2 参数重载 `boolean markAudited(reportType, period)`——内部按类型取启用规则（rulesOf）+ 按类型查数据表（H2032→h2032、H2031→passenger、H204→energy、INVEST→investMonthly、CITY_BUS→cityBus、CITY_TAXI→cityTaxi）再写标记；6 个 execute 方法末尾已调 2 参数版（执行审核后自动写标记）。
- `AuditController`：`POST /api/audit/markAudited?period=&reportType=` 返回 `Result<Boolean>`（是否写入标记）。
- `ReportExportService.checkExportReady`：`audited` 改为逐 auditType 查 `audit_run`（month=eq 精确 / year=likeRight），任一类型有标记即 audited=true；注入 `AuditRunMapper`。
**前端（热更新已生效，Compiled successfully）**
- `AuditResult.vue`：「执行审核」旁新增「标记已审核」按钮（调 markAudited，成功提示/无规则无数据提示并刷新列表）。
- `ReportExport.vue` 无需改：`unaudited = ready && audited===false` 逻辑已与 audit_run 语义吻合。
**历史数据补标（audit_run 已写入 6 条）**：H2031 07、H2032 07、H204 07、INVEST 06+07、CITY_TAXI 07；**H2032 08 未标**（8 月未审核）；CITY_BUS 无数据不标。
**验证（全部通过）**
- `GET /api/report/ready?period=2026-07&mode=month&types=cityDetail,passengerCityDetail,cityTaxiDetail,investPlan,energySummary` → 全部 audited=true（passengerCityDetail auditRows=0 但 audited=true，正是修复点）。
- `period=2026-08` → cityDetail rows=142（H2032 8 月有数据）audited=false，其余无数据 ready=false。
- `POST /api/audit/markAudited`：H2032/2026-07 → true（幂等）；CITY_BUS/2026-07 → false（无数据不标记）。
- 后端 start-dev.ps1 重启 OK（Started + 8090）；前端 14:32:12 Compiled。
**产物**：`_shots/compile_auditrun.log`、`%TEMP%\patch_*.py`（audit_2arg / audit_controller2 / report_audited / auditresult_vue2）、`%TEMP%\db_mark_history.py`。
**遗留/待办不变**：投资 M2 未开工；7-12 月模板待提供；货运《模板_货运量周转量》《规上规下拆分表》未导入；能耗新规则阈值待确认。

### 2026-08-26 下午续2：登录接通 + 用户管理（负责模块勾选）+ 报表生成页软隔离（已完成验证）
**需求（用户确认）**：报表生成页按「三人分工」做软隔离（货运1人、旅客+投资+能耗1人、城市客运1人）——登录后默认只看自己负责的模块、可切换「查看全部模块」；模块归属在**用户上勾选**（更灵活）。
**现状发现**：登录原为假登录（Login.vue 直接跳转不校验）、UserManage.vue 为占位页、sys_user/sys_role 表为空 → 本次一并补齐链路。
**数据库**：`sys_user` 加 `modules` 字段（逗号分隔：freight,passenger,invest,energy,cityPassenger）；初始化 4 个账号（密码均 123456，BCrypt 由 spring-security-crypto 生成）：
- admin/管理员（5 模块全选）、zhangsan/张三（freight）、lisi/李四（passenger,invest,energy）、wangwu/王五（cityPassenger）。
**后端（已编译重启）**
- `User` 实体加 modules；新增 `UserController`（/api/user/list 关键字搜索、/save 新增编辑=密码留空不改+BCrypt、/delete 禁止删 admin）；`LoginController` 登录返回 token+username+realName+modules（错误 401）。
**前端（热更新已生效，Compiled successfully 15:20:43）**
- `Login.vue` 调 /api/auth/login，存 token/username/realName/modules；`router/index.js` 加登录守卫（无 token 访问业务页跳 /login）；`main.js` 全局 mixin logout（清 localStorage 回登录页），8 个业务页侧边栏统一加「退出登录」菜单项。
- `UserManage.vue` 重写：用户列表（用户名/姓名/手机号/负责模块 tags/状态/创建时间/编辑删除）+ 新增编辑弹窗（含「负责模块」el-checkbox-group 5 项 + 状态）。
- `ReportExport.vue` 软隔离：顶部 focus-bar 显示「当前用户/负责模块」+ 「查看全部模块」el-switch；`visibleModules` computed 默认过滤自己的模块（未配置或过滤为空则显示全部）。
**验证（全部通过）**
- 登录：admin 返回 5 模块、zhangsan 返回 freight、错误密码 401；用户 CRUD：新增/重名 400/编辑改模块/删除，测试账号已清理，最终 4 用户。
- 无头浏览器 e2e（`_shots/usermgr_e2e.js/png`）：未登录访问 #/report → 跳 #/login；zhangsan 登录 → /report 只显示货运卡（focus-bar：当前用户：张三 负责模块：货运报表（H203-2）），点开关 → 5 张卡全显示；admin 登录 → /users 表格 4 行；JS 0 错误。
**产物**：`_shots/usermgr_e2e.js/png`、`_shots/compile_usermgr.log`、`%TEMP%\db_init_users.py`（初始化账号 SQL，可复用）。
**遗留/待办不变**：投资 M2 未开工；7-12 月模板待提供；货运《模板_货运量周转量》《规上规下拆分表》未导入；能耗新规则阈值待确认。报表页「状态可视化（数据就绪/已审核状态条）」与「最近生成记录」仍在待办讨论列表。

### 2026-08-26 晚间续5：报表模板自动向右扩列（1-6月 → 1-12月）+ 报表生成页单模块工作台（已完成验证）
**需求（用户确认）**：①按当前想法先出一版看效果（单模块工作台界面）；②月度模板**自动向右扩展列**：复制列头/公式/样式并同步公式引用，扩列格式与规则按 1-6 月既有规则举一反三，无需逐月人工确认。
**后端扩列（已编译重启 + HTTP 导出验证通过）**
- 三张报表启用扩列：`exportCityDetail`（货运分市州）、`exportPassengerCityDetail`（公路旅客分市州）、`exportPassengerMidDetail`（中口径明细）。`fillMonths = Math.min(currentMonth,6)` 改为 `currentMonth`；`fillMonths > 6` 时调用 `extendMonthlyColumns(sheet, headerRow, year, dataStart, dataEnd)`。
- 扩列逻辑：累计列对从 14/15 列移到 26/27 列（AB）；7-12 月列对由 1 月列对克隆（表头文本/日期修正、样式复制、非跨簿公式克隆且列引用同步平移，正则 `shiftMonthFormula`）；累计列公式重写为 12 个月值之和（`fixCumulativeFormulas`，公式不带 `=` 前缀，POI `setCellFormula` 不接受 `=` 开头——已踩坑修复）。
- 同比列：原 #REF! 公式覆写为 Java 库内计算值。货运调 `getCityMonthYoy`/`getProvinceMonthYoy`；旅客新增 `passengerCumYoy`/`passengerMonthVal` + 累计同比覆写；中口径新增 `fillMidYoyCell`/`fillMidCumYoyColumn`。循环起点 r=4 → r=3（R4 是全省区域标记行，A4:A7 合并），旅客 #REF! 清零。
- 已知口径（沿用现状，未改）：模板表头为「1月与去年同比」，7-12 月同比列沿用 1-6 月列做法，即「去年同月 vs 今年同月」的同比数值（`yearYoy`）。若后续要求改为「环比上月」需另改。
- **数据源缺口（非代码问题，需用户补数据）**：①`freight_turnover_import` 2026-07 的当月字段（freight_m07/turnover_m07）为 NULL，只有去年同月 → 7 月列只有 H2032 规上货运量 + 拆分表周转量，全省合计/规下货运量 7 月为空（预览弹窗「缺月数据：7月」与此一致）；②`h2031_enterprise_monthly` 只有 2026-07（771 行），1-6 月与 2025 年均为空 → 旅客表 1-6 月列空、累计同比（AB 列）空；③8-12 月列数据依赖后续月份数据源。
- HTTP 导出验证（2026-07 月报）：cityDetail A1:AB112、passengerCityDetail A1:AB58、passengerMidDetail A1:AB94；表头 1-12 月 + 累计 + 同比正确；#REF! 全部清零；累计列公式 =C+E+G+…+Y（12 个月值列之和）；合并单元格同步。
**前端：ReportExport.vue 重写为单模块工作台（热更新已生效，无编译错误）**
- 左侧 240px 模块导航（模块名 + 张数 + 当前报表期），右侧单模块面板：顶部报表方式/报表期，中间报表表格（勾选 + 报表名 + 数据状态标签「数据就绪/未审核/缺数据」+ 备注 + 预览/导出），底部全选 +「预览选中/导出选中（zip）」。
- 默认聚焦当前用户负责模块（登录时按用户 modules 过滤），顶部「查看全部模块」开关可切换全部 5 模块；保留 `/report/ready` 状态刷新、`/report/preview` 预览弹窗、`/report/export/{key}` 单张导出、`/report/export/selected` zip 多张导出。
- 无头浏览器 e2e（`_shots/report_workbench_e2e2.js`）：张三登录 → 只显示货运模块（navCount=1）；开「查看全部模块」→ 5 模块全显；货运 2026-07 三张报表状态均「数据就绪」；预览弹窗标题「预览数据 - 货运报表（H203-2）（2026-07）」+ 汇总/覆盖/缺月提示正确；JS 0 错误。截图 `_shots/report_workbench*.png`；HTTP 导出样张 `_shots/dl/*.xlsx`。
**验证命令/产物**：`GET /api/report/export/{key}?period=2026-07&mode=month`（三种 key 均 200）；`_verify_http_export*.py`、`_verify_expand*.py`、`_test_expand_*.xlsx`。
**遗留/待办不变**：投资 M2 未开工；货运《模板_货运量周转量》汇总表 7 月数据未导入（影响合计/规下 7 月列）；旅客 2025 年同期数据缺失（累计同比空）；8-12 月列数据依赖数据源；能耗新规则阈值待确认。

### 2026-08-26 晚间续6：报表生成页「报表方式/报表期」改为下拉框（已完成验证）
**需求（用户确认）**：界面上可选项改为下拉框选择方式。
**改动（ReportExport.vue）**
- 「报表方式」由 el-radio-group 改为 el-select（月报/年报）；切换方式时自动清空报表期（新增 `onModeChange`）。
- 「报表期」由 el-date-picker 改为 el-select 分组下拉（新增 `periodGroups`）：年报列出 2025/2026/2027 年；月报按年分组列出 1-12 月；能耗模块（季度报）只列季度末月 3/6/9/12，分组标题标注「（季度末月）」。
- 无头浏览器 e2e（`_shots/report_dropdowns_e2e.js`）：月报↔年报切换、年份/月份分组下拉、选 2026-07 后状态刷新「数据就绪」、JS 0 错误。截图 `_shots/report_dropdowns.png`。
**遗留/待办不变**：见晚间续5（数据源缺口等）。

### 2026-08-26 晚间续7：报表类型改为下拉框（已完成验证）
**需求（用户澄清）**：上次改的是「报表方式/报表期」下拉框，用户实际指的是「选择报表的类型」也要用下拉框。
**改动（ReportExport.vue）**
- 删除左侧 240px 模块导航栏（module-nav）与「查看全部模块」开关（showAllModules 及 visibleModules 计算属性一并移除）。
- 面板头部改为「报表类型」el-select：列出全部 5 个模块（货运/公路旅客/城市客运/投资/能耗），默认仍聚焦当前用户负责模块（张三→货运），可在下拉框自由切换其他模块（软隔离 + 灵活兼顾）。
- 报表方式、报表期下拉框保持不变；能耗模块报表期仍只列季度末月 3/6/9/12。
- 清理：selectModule→onModuleChange、删除 periodText、删除 module-nav 相关 CSS。
**验证（无头浏览器 `_shots/report_type_dropdown_e2e.js`）**
- 无编译错误、JS 0 错误；报表类型下拉 5 个选项齐全；默认值「货运报表（H203-2）」；切投资→4 张报表、切能耗→1 张（能运汇总表）；能耗报表期仅季度末月；切回货运正常。截图 `_shots/report_type_dropdown.png`。
**遗留/待办不变**：见晚间续5（货运 7 月汇总表未导入、旅客 1-6 月/2025 同期缺失、8-12 月数据依赖数据源）。
- 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 文件。