# HANDOFF.md — 每日交接文档

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

## 一、当前状态（2026-08-23）
- 前后端**均未运行**（8080/8090 连接被拒），需要先启动（见下）。
- 最近代码改动截至 08-07；08-14 起代码已入库 Gitee 私有仓库（见第九节），main 分支工作区干净、已推送。
- 无已知阻塞性问题。

## 二、快速启动
统一用一键脚本（必须沙箱外/提权运行）：
```
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 写进任何文档）。
- 核心模块：数据导入（5类）、审核引擎（规则驱动）、AI 分析（脱敏+查库+解释生成）、报表生成（3类）、用户权限（三员分离）。

## 四、已完成功能（截至 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 分析"是两个独立功能，不要混在一起。

## 六、文档索引
- 需求：`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 演示做好。

## 八、每日交接约定
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>）。
- 敏感配置不入库：`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`（凭据已存 Windows 凭据管理器，本机 push 无需再输令牌；换机器需重新提供令牌）。
- 注意：`backend.log`、`frontend.log`、`node_modules/`、`dist/`、`target/` 等不入库。

## 十、会话记录
- 2026-08-14：启动前后端验证正常（后均已停止）；建立 git 仓库（新增 `.gitignore`、脱敏模板 `application.yml.example`，真实 `application.yml` 不入库），创建 Gitee 私有仓库 `jichengxiong/trafficAudit` 并推送 `main`（2 commits：初始提交 + HANDOFF 补充 git 说明）。
- 2026-08-23：交接前核实——git 工作区干净、远端已同步；前后端均未在运行。