martial-admin-mini/doc/API接口测试指南.md

# API接口测试指南

**日期**: 2025-12-11
**状态**: ✅ 已切换到API模式，准备测试

---

## 🔧 已完成的修复

### 1. 切换数据模式为 API ✅
**文件**: `config/env.config.js:17`
```javascript
dataMode: 'api',  // 已从 'mock' 改为 'api'
```

### 2. 修复 GET 请求参数 ✅
所有 GET 请求现在使用 `params` 而不是 `data`：

**修复的文件**:
- `api/athlete.js`: getMyAthletes, getAthletesForAdmin, getVenues, getProjects
- `api/score.js`: getDeductions

**修复前**:
```javascript
return request({
  url: '/api/mini/athletes',
  method: 'GET',
  data: params  // ❌ 错误：GET请求不应使用data
})
```

**修复后**:
```javascript
return request({
  url: '/api/mini/athletes',
  method: 'GET',
  params: params  // ✅ 正确：GET请求使用params作为查询参数
})
```

### 3. 优化 request.js 支持 params ✅
**文件**: `utils/request.js:43-68`

增加了对 `params` 参数的支持：
```javascript
function request(options = {}) {
  const {
    method = 'GET',
    data = {},
    params = {},  // 新增：支持params参数
    // ...
  } = options

  // 对于 GET 请求，使用 params 作为查询参数
  const requestData = method === 'GET' ? params : data

  uni.request({
    data: requestData,  // GET使用params，POST/PUT使用data
    // ...
  })
}
```

---

## 🚀 如何测试

### 前置条件

1. **后端服务已启动** ✅
   - 项目路径: `D:\workspace\31.比赛项目\project\martial-master`
   - 运行地址: `http://localhost:8080`
   - 验证方法: 浏览器访问 `http://localhost:8080/doc.html` 查看API文档

2. **数据库已准备** ✅
   - 需要有测试数据（比赛、评委、邀请码、选手等）
   - 参考: `doc/API接口对接完成报告.md` 的数据库准备章节

3. **前端项目配置** ✅
   - config/env.config.js: `dataMode: 'api'`
   - config/env.config.js: `apiBaseURL: 'http://localhost:8080'`

### 测试步骤

#### 步骤1: 启动后端服务

```bash
cd D:\workspace\31.比赛项目\project\martial-master

# 方式1: 使用IDEA
# 右键 Application.java -> Run

# 方式2: 使用命令行（如果配置了Maven）
mvn spring-boot:run
```

验证后端启动成功：
- 访问 `http://localhost:8080/doc.html`
- 应该看到 Swagger API 文档页面

#### 步骤2: 刷新小程序前端

```bash
cd D:\workspace\31.比赛项目\project\martial-admin-mini

# 如果使用 HBuilderX
# 1. 关闭当前运行的小程序
# 2. 重新点击"运行" -> "运行到小程序模拟器"

# 如果使用命令行
npm run dev:mp-weixin
```

**重要**: 修改配置后必须重启项目才能生效！

#### 步骤3: 打开浏览器控制台

访问 `http://localhost:8081/#/pages/score-list/score-list`

按 `F12` 打开浏览器开发者工具，查看 Console 面板。

你应该看到类似这样的调试信息：
```
[API请求] GET /api/mini/athletes {judgeId: "456", venueId: "1", projectId: "5"}
[API响应] GET /api/mini/athletes {code: 200, success: true, data: [...]}
```

#### 步骤4: 测试登录功能

1. 访问登录页: `http://localhost:8081/#/pages/login/login`
2. 输入测试数据：
   - **比赛编码**: [从数据库 martial_competition 表获取 competition_code]
   - **邀请码**: [从数据库 martial_judge_invite 表获取 invite_code]
3. 点击"登录"按钮
4. 查看控制台输出：
   ```
   [API请求] POST /api/mini/login {matchCode: "...", inviteCode: "..."}
   [API响应] POST /api/mini/login {code: 200, data: {token: "...", ...}}
   ```
5. 验证是否跳转到选手列表页

#### 步骤5: 测试选手列表（普通评委）

登录成功后，应该自动跳转到 `/pages/score-list/score-list`

**验证点**:
- ✅ 页面显示选手列表
- ✅ 控制台显示 `[API请求] GET /api/mini/athletes`
- ✅ 选手信息正确显示（姓名、身份证、队伍、编号）
- ✅ 已评分选手显示"我的评分"和"总分"
- ✅ 未评分选手显示"评分"按钮

**查看请求详情**:
```javascript
// 控制台应该显示：
[API请求] GET /api/mini/athletes {
  judgeId: "456",
  venueId: "1",
  projectId: "5"
}

// 响应格式：
[API响应] GET /api/mini/athletes {
  code: 200,
  success: true,
  data: [
    {
      athleteId: "1",
      name: "张三",
      idCard: "123456789000000000",
      team: "少林寺武术大学院",
      number: "123-4567898275",
      scored: true,
      myScore: 8.906,
      totalScore: 8.907
    }
  ]
}
```

#### 步骤6: 测试选手列表（裁判长）

如果登录的是裁判长账号，应该跳转到 `/pages/score-list-multi/score-list-multi`

**验证点**:
- ✅ 显示场地切换选项卡
- ✅ 显示项目切换按钮
- ✅ 控制台显示：
  ```
  [API请求] GET /martial/venue/list
  [API请求] GET /martial/project/list
  [API请求] GET /api/mini/athletes/admin
  ```
- ✅ 选手列表显示总分和"修改"按钮
- ✅ 切换场地/项目时重新加载选手列表

#### 步骤7: 测试评分功能

1. 点击某个未评分选手的"评分"按钮
2. 应该跳转到 `/pages/score-detail/score-detail`
3. 验证页面加载扣分项：
   ```
   [API请求] GET /martial/deductionItem/list {projectId: "5"}
   ```
4. 修改分数，选择扣分项，填写备注
5. 点击"提交"按钮
6. 验证提交请求：
   ```
   [API请求] POST /martial/score/submit {
     athleteId: "1",
     judgeId: "456",
     score: 8.906,
     deductions: [...],
     note: "备注"
   }
   ```
7. 验证提交成功后返回选手列表

#### 步骤8: 测试评分详情（裁判长）

1. 裁判长登录后，在选手列表点击"修改"按钮
2. 应该跳转到 `/pages/modify-score/modify-score`
3. 验证加载评分详情：
   ```
   [API请求] GET /api/mini/score/detail/1
   [API响应] {
     athleteInfo: {...},
     judgeScores: [...],
     modification: {...}
   }
   ```
4. 验证显示：
   - 选手基本信息
   - 所有评委的评分列表
   - 修改记录（如果有）

#### 步骤9: 测试修改评分（裁判长）

1. 在修改评分页面调整分数
2. 填写修改原因
3. 点击"修改"按钮
4. 验证修改请求：
   ```
   [API请求] PUT /api/mini/score/modify {
     athleteId: "1",
     modifierId: "789",
     modifiedScore: 8.910,
     note: "修改原因"
   }
   ```
5. 验证修改成功后返回选手列表

---

## 🐛 常见问题排查

### 问题1: 页面显示"网络错误"

**可能原因**:
1. 后端服务未启动
2. 后端端口不是 8080
3. CORS 跨域配置问题

**解决方法**:
```bash
# 1. 检查后端是否启动
curl http://localhost:8080/doc.html

# 2. 检查后端日志
# 查看 martial-master 控制台输出

# 3. 检查前端配置
# config/env.config.js 的 apiBaseURL 是否正确
```

### 问题2: 登录后显示"邀请码不存在"

**可能原因**:
1. 数据库中没有对应的邀请码
2. 邀请码已过期（expire_time < NOW()）
3. 邀请码已被删除（is_deleted = 1）

**解决方法**:
```sql
-- 查询邀请码
SELECT * FROM martial_judge_invite
WHERE invite_code = 'ABC123'
AND is_deleted = 0;

-- 如果不存在，插入测试邀请码
INSERT INTO martial_judge_invite (
  competition_id, judge_id, invite_code, role, venue_id, projects,
  expire_time, is_used, is_deleted, create_time, update_time
) VALUES (
  1, 1, 'ABC123', 'judge', 1, '[1,2,3]',
  DATE_ADD(NOW(), INTERVAL 7 DAY), 0, 0, NOW(), NOW()
);
```

### 问题3: 登录后显示"比赛编码不匹配"

**可能原因**:
1. 输入的比赛编码与数据库不一致
2. 比赛编码字段名错误

**解决方法**:
```sql
-- 查询比赛编码
SELECT id, competition_code, competition_name
FROM martial_competition
WHERE is_deleted = 0;

-- 注意：后端已修正为使用 competition_code 字段
```

### 问题4: 选手列表为空

**可能原因**:
1. 数据库中没有选手数据
2. 选手的 venue_id 或 project_id 不匹配
3. 选手被标记为删除（is_deleted = 1）

**解决方法**:
```sql
-- 查询选手
SELECT * FROM martial_athlete
WHERE project_id = 5
AND is_deleted = 0
ORDER BY player_no;

-- 如果为空，插入测试选手
INSERT INTO martial_athlete (
  competition_id, project_id, player_name, player_no,
  id_card, team_name, is_deleted, create_time, update_time
) VALUES (
  1, 5, '测试选手', 'A001', '123456789000000000',
  '测试队伍', 0, NOW(), NOW()
);
```

### 问题5: 控制台显示 404 错误

**可能原因**:
1. 后端接口路径不存在
2. 后端 Controller 未正确注册
3. 前端请求路径错误

**解决方法**:
```bash
# 1. 访问 Swagger 文档验证接口
http://localhost:8080/doc.html

# 2. 查找小程序专用接口
# 搜索: MartialMiniController
# 应该看到 5 个接口:
#   POST /api/mini/login
#   GET  /api/mini/athletes
#   GET  /api/mini/athletes/admin
#   GET  /api/mini/score/detail/{athleteId}
#   PUT  /api/mini/score/modify

# 3. 手动测试接口
curl -X GET "http://localhost:8080/api/mini/athletes?judgeId=1&venueId=1&projectId=5" \
  -H "Blade-Auth: Bearer YOUR_TOKEN"
```

### 问题6: Token 未正确传递

**可能原因**:
1. 登录成功但未保存 token 到 localStorage
2. request.js 未正确添加 Blade-Auth 头部

**解决方法**:
```javascript
// 1. 检查 token 是否保存
// 在浏览器控制台执行：
uni.getStorageSync('token')

// 2. 检查请求头
// 查看 Network 面板，选择某个请求
// Headers 中应该有：
// Blade-Auth: Bearer xxxxx

// 3. 手动保存 token 测试
uni.setStorageSync('token', 'test-token-123')
```

---

## 📊 测试检查清单

使用以下清单验证所有功能：

### 登录功能
- [ ] 输入正确的比赛编码和邀请码，能成功登录
- [ ] 登录成功后保存 token 到 localStorage
- [ ] 登录成功后跳转到对应页面（普通评委 → score-list，裁判长 → score-list-multi）
- [ ] 输入错误的邀请码，显示"邀请码不存在"
- [ ] 输入错误的比赛编码，显示"比赛编码不匹配"

### 选手列表（普通评委）
- [ ] 加载选手列表成功
- [ ] 显示选手基本信息（姓名、身份证、队伍、编号）
- [ ] 已评分选手显示"我的评分"和"总分"
- [ ] 未评分选手显示"评分"按钮
- [ ] 评分统计正确（已评分数/总数）

### 选手列表（裁判长）
- [ ] 显示场地切换选项卡
- [ ] 显示项目切换按钮
- [ ] 加载场地列表成功
- [ ] 加载项目列表成功
- [ ] 加载选手列表成功（含评分统计）
- [ ] 切换场地时重新加载选手
- [ ] 切换项目时重新加载选手
- [ ] 有总分的选手显示"修改"按钮

### 评分功能（普通评委）
- [ ] 点击"评分"按钮跳转到评分页面
- [ ] 加载扣分项列表成功
- [ ] 可以调整分数（5.000-10.000）
- [ ] 可以选择扣分项（多选）
- [ ] 可以填写备注
- [ ] 提交评分成功
- [ ] 提交后返回选手列表
- [ ] 选手状态更新为"已评分"

### 评分详情（裁判长）
- [ ] 点击"修改"按钮跳转到修改页面
- [ ] 显示选手基本信息
- [ ] 显示当前总分
- [ ] 显示所有评委的评分列表
- [ ] 显示修改记录（如果有）

### 修改评分（裁判长）
- [ ] 可以调整总分
- [ ] 可以填写修改原因
- [ ] 提交修改成功
- [ ] 提交后返回选手列表
- [ ] 选手总分已更新
- [ ] 修改记录已保存

---

## 📝 测试报告模板

测试完成后，请填写以下报告：

```
测试时间: ______
测试人员: ______
后端版本: ______
前端版本: commit 6d42c4a

### 登录测试
- 状态: ✅ 通过 / ❌ 失败
- 备注: ______

### 选手列表测试（普通评委）
- 状态: ✅ 通过 / ❌ 失败
- 备注: ______

### 选手列表测试（裁判长）
- 状态: ✅ 通过 / ❌ 失败
- 备注: ______

### 评分功能测试
- 状态: ✅ 通过 / ❌ 失败
- 备注: ______

### 评分详情测试
- 状态: ✅ 通过 / ❌ 失败
- 备注: ______

### 修改评分测试
- 状态: ✅ 通过 / ❌ 失败
- 备注: ______

### 发现的问题
1. ______
2. ______
3. ______

### 改进建议
1. ______
2. ______
3. ______
```

---

## 🎯 下一步计划

测试通过后：
1. ✅ 合并 feature/api-integration 分支到 main
2. ✅ 部署到测试环境
3. ✅ 进行真实数据测试
4. ✅ 收集用户反馈
5. ✅ 优化性能和体验

---

**文档版本**: v1.0
**最后更新**: 2025-12-11
**维护者**: Claude Code Assistant