# AGENTS.md — trafficAudit 项目运行须知

## 项目概览
交通货运统计审核系统（湖北货运量/周转量等）。
- 后端：Spring Boot，目录 `traffic-audit-server`，端口 8090。
- 前端：Vue 2 + Element UI，目录 `traffic-audit-web`，端口 8080，`/api` 代理到 8090。
- 需求文档在 `requirement/`、`docs/`；用户全程中文交流。

## 启动前后端（最重要）
统一使用一键脚本 `start-dev.ps1`（项目根目录），且必须**在沙箱外（require_escalated）运行**：
powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1

- 脚本会自动检测 8090/8080 是否已监听（已在跑则跳过），并等待验证就绪。
- 后端等价命令：`cmd /c mvn.cmd -q spring-boot:run -f traffic-audit-server\pom.xml > backend.log 2>&1`
  - 成功标志：backend.log 出现 `Started TrafficAuditApplication` 与 `Tomcat started on port(s): 8090`
- 前端等价命令（工作目录 `traffic-audit-web`）：`cmd /c npm.cmd run serve > frontend.log 2>&1`
  - 成功标志：frontend.log 出现 `Compiled successfully` 与 `App running at:`

## 必须避开的三个坑（历史教训）
1. 本机（Codex 子进程环境）同时存在 `Path` 与 `PATH` 两个环境变量（值相同）。
   `Start-Process`、`Get-Item env:Path` 会报“已添加了具有相同键的项”。
   对策：一律用 `cmd.exe /c ... > log 2>&1` + `[System.Diagnostics.ProcessStartInfo]` 启动，绝不用 `Start-Process`。
2. node 在沙箱内访问 `C:\Users\jcxiong` 会被拒（`EPERM: lstat`），导致前端起不来。
   对策：启动脚本整体在沙箱外（require_escalated）运行。
3. 嵌套 `powershell.exe -Command "..."` 的引号会被外层 shell 解析破坏。
   对策：直接运行 `.ps1` 文件，不做嵌套。

## 重启（停旧起新）
1. 按 PID 精确停旧进程：后端链 `cmd→java(maven)→java(app)`；前端链 `cmd→node(npm)→cmd→node(vue-cli-service)`。
2. 不要杀 `node_repl`（Codex MCP 内核）和用户自己开的 cmd 窗口。
3. 停干净后运行 `start-dev.ps1`。

## 验证注意
- 沙箱内 `Get-NetTCPConnection` 会因权限“拒绝访问”而静默失败，**不要**据此判定端口未监听；判断服务状态以 backend.log / frontend.log 为准。
- 用户要求：临时脚本/文件未经同意不删；导入失败要在页面显示行号；AI 分析结果要给结构化排版 + 逐字输出动画。