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 分析结果要给结构化排版 + 逐字输出动画。