From 1ba89d73a1784c864c3d9c0619f612edf9742eb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=AE=85=E6=88=BF?= Date: Thu, 11 Dec 2025 19:02:08 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0API=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📝 新增测试文档： - 完整的API接口测试步骤说明 - 前置条件检查清单 - 常见问题排查指南 - 测试检查清单 - 测试报告模板 测试范围： - 登录功能 - 选手列表（普通评委 & 裁判长） - 评分功能 - 评分详情查看 - 评分修改（裁判长） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- doc/API接口测试指南.md | 505 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 505 insertions(+) create mode 100644 doc/API接口测试指南.md diff --git a/doc/API接口测试指南.md b/doc/API接口测试指南.md new file mode 100644 index 0000000..899cef0 --- /dev/null +++ b/doc/API接口测试指南.md @@ -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