# 系统化调试协议（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 — 检查最近变更
```bash
git diff --name-only HEAD~5   # 最近 5 次提交变更
git log --oneline -10         # 最近 10 条提交
```

### Step 5 — 运行受影响测试
```bash
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）——需真实后端验证