| | |
|---|
| | | > **用法**：新对话开始后，先读本文件 + 项目根目录 `AGENTS.md`，即可无缝接力。 |
|---|
| | | > **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。 |
|---|
| | | |
|---|
| | | ## 一、当前状态（2026-08-27 合并后） |
|---|
| | | - 前后端**运行中**（8090/8080 已监听，start-dev.ps1 启动），登录页已接入真实认证（数据库校验）+ 行为验证码。 |
|---|
| | | ## 今日（2026-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. 数据导入浏览器崩溃排查（进行中，用户线索更新） |
|---|
| | | - 用户补充：共 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. 菜单/布局统一修复（commit 2bd663b，已推送） |
|---|
| | | - 用户反馈 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 主线程卡死待调查（相信为问题①高亮及浏览器无响应的根因）。 |
|---|
| | | - 认证信息 localStorage → sessionStorage（强制登录），见上面第 4 节。 |
|---|
| | | |
|---|
| | | |
|---|
| | | ## 〇、关机交接（2026-08-27 深夜，用户关机前） |
|---|
| | | - **当前运行状态**：前后端应用服务全部已停止（开发服务、打包版均未运行）；仅数据库在跑 |
|---|
| | | （MySQL80 服务=3305，本项目用；MySQL57=3306 勿动）；8080 上 IIS 站点仍在但本项目已不再依赖 IIS。 |
|---|
| | | - **进行中/待验证（用户负责）**：用户在**打包环境**验证数据库合并结果——用 `admin/admin123` 登录 |
|---|
| | | （行为验证码需人工点击，无法自动化验证）；若登录及各业务模块数据正常，则全流程闭环。 |
|---|
| | | - **部署知识（本轮确认）**：外置 `application.yml` 与 jar 内置是**属性级合并**（外置只需写要覆盖的项，其余自动沿用内置）， |
|---|
| | | 不是文件级替换；Spring Boot 按**启动工作目录**找配置（`file:./config/` > `classpath:/config/` > `file:./` > `classpath:/`）， |
|---|
| | | 在 jar 同级执行 `java -jar app.jar` 即可命中外部配置；推荐放 `config\` 子目录。 |
|---|
| | | - **待办（下次）**：`docs/打包部署说明.docx` 第六节"外置 application.yml 需包含完整配置"表述不准确， |
|---|
| | | 应改为"属性级合并，只需写要覆盖的项"；改后重新导出 docx 并推送。 |
|---|
| | | |
|---|
| | | ## 一、当前状态（2026-08-27 合并后，打包部署已完成） |
|---|
| | | - **开发服务已停止**（前后端均未运行），打包版测试**验收通过**。 |
|---|
| | | - **打包部署方案（已定稿）**：Spring Boot 直接托管前端静态文件，单端口 8090，**不需要 IIS/nginx**。 |
|---|
| | | 部署结构 = jar 同级 `web\`（前端 dist 内容）+ `docs\`（模板目录）；`java -jar app.jar` 启动后访问 `http://<服务器>:8090`。 |
|---|
| | | 说明文档：`docs/打包部署说明.md` / `.docx`（含 nginx 备选方案、IIS 反代示例 `docs/iis-web.config.example`）。 |
|---|
| | | - **数据库已合并（2026-08-27 晚）**：同事 Navicat 全表导出 `traffic_audit.sql`（27 表、约 6 万行，来自其 mysql80:3308）已全量导入本机库（MySQL 8.0.29，localhost:3305，root/root）。 |
|---|
| | | 导入前已备份本机库 → `D:\03_公司\02_项目\27_湖北省道路运输事业发展中心\05_开发测试\00_开发\_db_backup_20260827.sql`。 |
|---|
| | | `sys_user` 现有 4 账号（admin + zhangsan/lisi/wangwu，均带 modules）；admin 密码已恢复为 BCrypt（admin/admin123），其余账号密码为同事原 hash。 |
|---|
| | | ⚠️ **MySQL 客户端用 8.0**（`C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe`），不要用 5.7 客户端（`D:\mysql\mysql-5.7.41-winx64`）。 |
|---|
| | | - 本次配套改动：`SecurityConfig` 放行静态资源（`/`、`/js/**` 等）+ `application.yml` 加 |
|---|
| | | `spring.web.resources.static-locations: file:./web/`（application.yml 不入库，重打包时需保留该配置）。 |
|---|
| | | - **2026-08-27 完成双方开发结果合并**：以对方（郑玉洁，另一开发人员）的代码为基础，并入我方三样改动 |
|---|
| | | （态势图/AI助手构想记录、登录行为验证码、登出与上下布局）。验证码采用**我方实现**（Captcha3D + 后端 captcha 包， |
|---|
| | | 内存存储，无 Redis 依赖），对方独立实现的 ShapeCaptcha（Canvas+Redis）已弃用、不入库。 |
|---|
| | | - 新 git 仓库迁移进行中：旧 Gitee 仓库弃用，合并结果将提交到新仓库（地址见第九节，待用户提供后补全）。 |
|---|
| | | - 新 git 仓库迁移**已完成**：合并结果已提交到 Gitblit 根仓库 `trafficAudit.git`（见第九节），旧 Gitee 仓库弃用；`~xyc/trafficAudit.git` 临时仓库已删。 |
|---|
| | | - 数据库已补齐对方新增表（MySQL 8，库 traffic_audit，本机 3305）：h2031_enterprise_monthly、passenger_*、 |
|---|
| | | h204_*、investment_*、city_bus_monthly、city_taxi_monthly、city_taxi_auth、passenger_individual_monthly、audit_run； |
|---|
| | | sys_user 已加 modules 列；admin 密码已重置为 BCrypt（admin/admin123）。 |
|---|
| | |
|---|
| | | - 后续扩展：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 起迁移到新仓库） |
|---|
| | | - **旧仓库（弃用）**：Gitee https://gitee.com/jichengxiong/trafficAudit（2026-08-14 建立）——不再使用。 |
|---|
| | | - **新仓库**：地址待补（用户提供账号/仓库名后填写）。合并后的 main 分支已包含：原历史 + 我方 08-27 提交 + 对方开发结果分支 + 合并提交。 |
|---|
| | | - 对方未使用 git：其开发结果以独立分支（partner-work）合入，合并提交 `Merge partner-work`。 |
|---|
| | | ## 九、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`（凭据按新仓库要求配置）。 |
|---|
| | | - 日常流程：`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 可用）。 |
|---|
| | | |
|---|
