HANDOFF.md — 每日交接文档

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

今日（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/经济指标试算仅记录未实现。

历史（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】增加**经济指标试算功能**：领导非常关注经济指标，**货运是大头**；常驻现场的所有人都要会计算货运相关数据（货运量/周转量等）。领导经常要求把某个数据「压一压」，今后考虑在软件里增加试算功能——可按需要调整/测算指标数值（如模拟下调某企业/某口径的货运量后看汇总与趋势影响），辅助现场人员快速试算与应对。

八、每日交接约定

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 失败数据直接验明细表，真实无失败数据验「暂无导入失败记录」空态。