Files

T

zhangxiang 5c65139fd8 chore(config): 参考 novavis 完善 Agent 配置体系

- AGENTS.md: 新增 §20 工具脚本复用 / §21 分析结论复用 / §22 Flaky 门禁，更新文档配置表
- .pi/: 新增 settings.json、rules/guardrails.md、prompts/{debug,review,ship}-gym-manage.md
- .agents/: 新增 Hook 配置与 4 个 Hook 脚本（session-start/pre-agent-check/check-completeness/stop-check）
  及 protocols/systematic-debugging.md（check-completeness 含接口链缺口检测）
- scripts/flaky-scan.sh: vitest shuffle 稳定性扫描（gym-manage-web）
- .gitignore: 追踪 AGENTS.md 与 .pi 配置，忽略运行时缓存（todos/taskflows-runs/tokenomy/sessions）

2026-08-04 12:02:12 +08:00

2.2 KiB

Raw Blame History

系统化调试协议（Systematic Debugging）

通用规则见 AGENTS.md §15（系统调试优先：先定位根因再修复，禁止"试试看"）。

适用范围

本项目任何层级的 Bug：后端 Java（gym-manage-api）、Gateway 路由、Web 前端（gym-manage-web）、 UniApp 小程序（gym-manage-uniapp / gym-manage-coach-uniapp）、数据库（PostgreSQL:55432）。

协议步骤

Step 1 — 复现确认

拿到最小复现步骤：单测试 / 单操作 / 单输入
区分环境：本地 Dev（Web:3002）、Docker（docker-compose logs -f backend/frontend/postgres）、微信开发者工具（小程序，urlCheck: false 已关闭 URL 校验）

Step 2 — 分层隔离

层级	排查入口	快速验证
后端 Java	Gateway/App 控制台日志（DEBUG 输出 stdout）	`cd gym-manage-api && mvn compile`
Gateway 路由	`/api/**` → 8084 转发日志	`docker-compose logs -f gateway`
数据库	SQL / 数据不一致	`psql -U novalon -d manage_system -p 55432`
Web 前端	DevTools Console + Network	`cd gym-manage-web && pnpm test`
UniApp	微信开发者工具控制台	jest（`gym-manage-uniapp`）

按上表顺序定位，一次只换一个变量。

Step 3 — 假设驱动

对每个假设写下一行验证方法，先验证最可能/最便宜的假设
Java 逻辑：加 SLF4J DEBUG 日志或补单测缩小范围
接口联调：用 Swagger（:8084/swagger-ui.html）直调接口确认后端，再查前端参数
UI：Vue DevTools 组件树 + Network 请求/响应比对

Step 4 — 检查最近变更

git diff --name-only HEAD~5   # 最近 5 次提交变更
git log --oneline -10         # 最近 10 条提交

Step 5 — 运行受影响测试

cd gym-manage-api && mvn test -pl <受影响模块> -am   # 后端
cd gym-manage-web && pnpm test                       # Web 前端
cd gym-manage-web && pnpm test:e2e                   # Web E2E

Step 6 — 确认根因后才提修复方案

记录完整复现路径与根因证据
修复后走完整验证：受影响单测 + 类型检查（vue-tsc）+ 真实后端联调
Mock 通过 ≠ 功能可用（AGENTS.md §13）——需真实后端验证

2.2 KiB Raw Blame History Unescape Escape