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

API接口测试指南

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

---

🔧 已完成的修复

1. 切换数据模式为 API ✅

文件: config/env.config.js:17

dataMode: 'api',  // 已从 'mock' 改为 'api'

2. 修复 GET 请求参数 ✅

所有 GET 请求现在使用 params 而不是 data：

修复的文件:

• api/athlete.js: getMyAthletes, getAthletesForAdmin, getVenues, getProjects
• api/score.js: getDeductions

修复前:

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

修复后:

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

3. 优化 request.js 支持 params ✅

文件: utils/request.js:43-68

增加了对 params 参数的支持：

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: 启动后端服务

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: 刷新小程序前端

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
• ✅ 选手信息正确显示（姓名、身份证、队伍、编号）
• ✅ 已评分选手显示"我的评分"和"总分"
• ✅ 未评分选手显示"评分"按钮

查看请求详情:

// 控制台应该显示：
[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 跨域配置问题

解决方法:

# 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）

解决方法:

-- 查询邀请码
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. 比赛编码字段名错误

解决方法:

-- 查询比赛编码
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）

解决方法:

-- 查询选手
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. 前端请求路径错误

解决方法:

# 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 头部

解决方法:

// 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