HANDOFF.md — 每日交接文档

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

一、当前状态（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）。
• 无已知阻塞性问题。

二、快速启动

统一用一键脚本（必须沙箱外/提权运行）：
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，支持自然语言提问/聊天，灵活查看与挖掘数据。

八、每日交接约定

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 = 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 推送免输密码）。
• 注意：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 文件。