交通统计审核
编辑 | blame | 历史 | 原始文档

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

工作规范（2026-09-02 起，必须遵守）

  1. 每做完一个功能，立即测试并写《功能测试报告》
  • 测试至少覆盖：正向用例（正常数据）、负向用例（错类型/错列位/缺列等）、入库抽查（与源文件逐项对齐）。
  • 报告写入 docs/功能测试报告/，命名：功能测试报告_<功能名>_<YYYY-MM-DD>.md。
  • 报告须包含：功能说明、测试环境、用例表（输入/预期/实际/结论）、发现的问题与处置、结论。
  1. 每天下班前写《工作日结》，命名附日期
  • 写入 docs/工作日结/，命名：工作日结_<YYYY-MM-DD>.md。
  • 内容至少包含：今天做了什么（功能/修复）、测试结果摘要、遗留问题与待办、明天计划。
  • 当天没有代码/测试工作时，也要写（一句话说明“今日无代码改动”即可）。
  1. git 工作流（2026-09-03 用户授权，无需再询问是否推送）
  • 每次修改代码/文档后：先测试并写《功能测试报告》/更新《工作日结》，再 git fetch gitea 与远端 main 对比合并（必要时解决冲突），确认无误后 commit 并 push 到公司 gitea（http://61.183.254.94:3000/r/trafficAudit.git，账号 zyj）。
  • 若远端已有同事新提交：必须先合并/基于最新再推，禁止强推覆盖同事代码。
  • 公司 git 账号密码只通过本机 git 凭据/临时 askpass 使用，禁止写进仓库内任何文档或提交内容。
  1. git 双仓库约定（2026-09-07 用户确认补充）
  • 个人仓库 = origin（https://gitee.com/zhizhijie/traffic-audit.git）：只要用户有改动，先 git fetch origin 查看并合并其个人仓库新提交（目前远端分支为 master），再继续本地工作，避免覆盖用户改动。
  • 公司仓库推送：一律按第 3 条执行（先测试/写报告或更新工作日结 → git fetch gitea 与远端 main 对比合并、禁强推 → commit → push 公司 gitea），不再逐次询问。