交通统计审核
编辑 | 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 起；2026-09-27 按同事提交方式调整）

  1. 每做完一个功能，立即测试（测试要求不变）
  • 测试至少覆盖：正向用例（正常数据）、负向用例（错类型/错列位/缺列等）、入库抽查（与源文件逐项对齐）。
  • 《功能测试报告》写在本地 docs/功能测试报告/，命名：功能测试报告_<功能名>_<YYYY-MM-DD>.md；**该目录已 gitignore，不入库**（自己留档/复查用）。
  • 报告须包含：功能说明、测试环境、用例表（输入/预期/实际/结论）、发现的问题与处置、结论。
  • 入库的是结论：把关键结论/口径/风险/待办写进 HANDOFF.md（必要时另写 docs/交接文档_<日期>.md、docs/问题汇总/），与该次代码改动**放在同一条提交**里。
  1. 《工作日结》本地写、不入库
  • 写入本地 docs/工作日结/，命名：工作日结_<YYYY-MM-DD>.md；**该目录已 gitignore，不入库**（给自己看）。
  • 内容至少包含：今天做了什么、测试结果摘要、遗留问题与待办、明天计划；当天无代码/测试工作也要写一句话说明。
  • 需要交接的部分：把"当前状态 + 待办"追加到 HANDOFF.md（同事的做法就是这样）。
  1. git 工作流（2026-09-03 用户授权，无需再询问是否推送；提交粒度参考同事 xyc）
  • 一条提交 = 一个改动：代码/脚本 + 该改动的说明文档（HANDOFF.md / 方案 / 口径清单）放在同一条提交里；不要为每个小改动单独建报告再单独提交。
  • message 写法：feat(模块): … / fix(模块): … / docs: … / docs(交接): …，一句话说清"改了什么"。
  • 禁止入库：临时脚本与调试产物（_tmp_*、_shots/、outputs/）、构建产物（jar / dist / target）、密钥与口令、大体积备份（*.sql 全库导出）；过程日志与日结只留本地。
  • 推送前：先按上面完成测试，再 git fetch origin 与远端 main 对比合并（必要时解决冲突），确认无误后 commit 并 push 到公司 gitea（http://61.183.254.94:3000/r/trafficAudit.git，账号 zyj）。
  • 若远端已有同事新提交：必须先合并/基于最新再推，禁止强推覆盖同事代码。
  • 公司 git 账号密码只通过本机 git 凭据/临时 askpass 使用，禁止写进仓库内任何文档或提交内容。
  1. git 单仓库约定（2026-09-21 用户确认，替代 2026-09-07 的双仓库约定）
  • 本机只使用公司 gitea：origin = http://61.183.254.94:3000/r/trafficAudit.git（账号 zyj）。个人 gitee 仓库已不再使用，不要再把它当作 origin 或额外拉取源。
  • 拉取/推送一律走 origin（远端分支 main）：先拉合并，禁强推，再 commit/push。