docs: 添加API接口测试指南
📝 新增测试文档： - 完整的API接口测试步骤说明 - 前置条件检查清单 - 常见问题排查指南 - 测试检查清单 - 测试报告模板 测试范围： - 登录功能 - 选手列表（普通评委 & 裁判长） - 评分功能 - 评分详情查看 - 评分修改（裁判长） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
505
doc/API接口测试指南.md
Normal file
505
doc/API接口测试指南.md
Normal file
@@ -0,0 +1,505 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user