martial-admin-mini/doc/API对接快速启动指南.md

API对接快速启动指南

立即开始API对接 - 5分钟快速上手 更新时间: 2025-12-12 状态: ✅ 前端已就绪，可以立即开始

---

🚀 快速开始（3步）

步骤1: 确认环境配置（已完成✅）

当前配置：config/env.config.js

dataMode: 'api'  // ✅ 已设置为API模式
apiBaseURL: 'http://localhost:8080'  // 后端地址

如果后端地址不同，请修改 apiBaseURL

---

步骤2: 启动后端服务

# 进入后端项目目录
cd ../martial-master

# 启动后端服务（根据实际情况）
mvn spring-boot:run
# 或
java -jar target/martial-master.jar

确认后端服务启动成功: 访问 http://localhost:8080/doc.html

---

步骤3: 启动前端项目

# 在当前目录（martial-admin-mini）
npm run dev:mp-weixin
# 或使用 HBuilderX 运行到微信开发者工具

---

🧪 立即测试

测试1: 登录功能（2分钟）

1. 打开登录页面
2. 输入测试数据:
   • 比赛编码: 123（需要后端提供真实数据）
   • 邀请码: pub（普通评委）或 admin（裁判长）
3. 点击"立即评分"
4. 查看控制台日志:

   [API请求] POST /api/mini/login { matchCode: '123', inviteCode: 'pub' }
   

预期结果:

• ✅ 成功: 跳转到评分列表页面
• ❌ 失败: 查看错误信息，检查后端接口

---

测试2: 选手列表（1分钟）

登录成功后，自动进入评分列表页面。

查看控制台日志:

[API请求] GET /api/mini/athletes?judgeId=456&venueId=1&projectId=5

预期结果:

• ✅ 成功: 显示选手列表
• ❌ 失败: 查看错误信息

---

测试3: 评分提交（2分钟）

1. 点击未评分选手的"评分"按钮
2. 选择扣分项
3. 输入备注
4. 点击"提交评分"

查看控制台日志:

[API请求] POST /martial/score/submit { athleteId: '1', judgeId: '456', ... }

---

🔍 调试技巧

1. 开启调试模式（已开启✅）

config/env.config.js

debug: true  // ✅ 已开启

控制台会显示:

• 每个API请求的URL和参数
• 每个API响应的数据
• dataAdapter的模式切换信息

---

2. 查看网络请求

微信开发者工具:

1. 打开"调试器"
2. 切换到"Network"标签
3. 查看所有HTTP请求

关键信息:

• 请求URL是否正确
• 请求头是否包含 Blade-Auth: Bearer {token}
• 响应状态码（200/401/500）
• 响应数据格式

---

3. 切换到Mock模式测试

如果后端接口未就绪，可以先用Mock模式测试UI：

// config/env.config.js
dataMode: 'mock'  // 切换到Mock模式

Mock模式特点:

• ✅ 无需后端服务
• ✅ 完整的业务流程
• ✅ 可以演示所有功能
• ✅ 数据格式与API一致

---

⚠️ 常见问题

问题1: 登录失败 - "网络错误"

原因: 后端服务未启动或地址错误

解决:

1. 检查后端服务是否启动: http://localhost:8080/doc.html
2. 检查 apiBaseURL 配置是否正确
3. 检查网络连接

---

问题2: 登录失败 - "比赛编码不存在"

原因: 数据库中没有测试数据

解决:

1. 联系后端开发者准备测试数据
2. 或者使用Mock模式: dataMode: 'mock'

---

问题3: 接口返回401 - "Token已过期"

原因: Token过期或无效

解决:

1. 重新登录获取新Token
2. 检查后端Token验证逻辑

自动处理: utils/request.js:114-131 已实现自动跳转到登录页

---

问题4: 选手列表为空

原因:

• 数据库中没有选手数据
• 接口参数错误
• 后端接口未实现

解决:

1. 检查控制台日志，查看请求参数
2. 检查后端数据库是否有数据
3. 使用Mock模式验证前端逻辑

---

问题5: 跨域错误（CORS）

现象: 控制台显示 "CORS policy" 错误

解决: 后端需要配置CORS

// 后端配置示例
@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOrigin("*");
        config.addAllowedHeader("*");
        config.addAllowedMethod("*");
        // ...
    }
}

---

📋 后端接口状态检查

必须实现的接口（5个）

接口	路径	状态	测试方法
登录验证	POST /api/mini/login	⚪ 待确认	登录页面测试
普通评委选手列表	GET /api/mini/athletes	⚪ 待确认	评分列表页面
裁判长选手列表	GET /api/mini/athletes/admin	⚪ 待确认	多场地管理页面
评分详情	GET /api/mini/score/detail/{id}	⚪ 待确认	修改评分页面
修改评分	PUT /api/mini/score/modify	⚪ 待确认	修改评分提交

可以复用的接口（4个）

接口	路径	状态	测试方法
场地列表	GET /martial/venue/list	✅ 已有	多场地管理页面
项目列表	GET /martial/project/list	✅ 已有	多场地管理页面
扣分项列表	GET /martial/deductionItem/list	✅ 已有	评分详情页面
提交评分	POST /martial/score/submit	✅ 已有	评分详情页面

---

🧪 完整测试流程

测试场景1: 普通评委评分流程

1. 登录（pub角色）
   ↓
2. 查看选手列表
   ↓
3. 点击"评分"按钮
   ↓
4. 选择扣分项
   ↓
5. 提交评分
   ↓
6. 返回列表，查看状态更新

涉及接口:

• POST /api/mini/login
• GET /api/mini/athletes
• GET /martial/deductionItem/list
• POST /martial/score/submit

---

测试场景2: 裁判长修改评分流程

1. 登录（admin角色）
   ↓
2. 选择场地和项目
   ↓
3. 查看选手列表
   ↓
4. 点击"修改"按钮
   ↓
5. 查看评分详情
   ↓
6. 修改分数
   ↓
7. 提交修改

涉及接口:

• POST /api/mini/login
• GET /martial/venue/list
• GET /martial/project/list
• GET /api/mini/athletes/admin
• GET /api/mini/score/detail/{id}
• PUT /api/mini/score/modify

---

📊 接口测试工具

方法1: 使用Postman测试

登录接口示例:

POST http://localhost:8080/api/mini/login
Content-Type: application/json

{
  "matchCode": "123",
  "inviteCode": "pub"
}

获取选手列表示例:

GET http://localhost:8080/api/mini/athletes?judgeId=456&venueId=1&projectId=5
Blade-Auth: Bearer {token}

---

方法2: 使用Swagger测试

访问: http://localhost:8080/doc.html

1. 找到对应的接口
2. 点击"Try it out"
3. 输入参数
4. 点击"Execute"
5. 查看响应

---

🔧 前端代码位置

关键文件

文件	说明	行号
pages/login/login.vue	登录调用	96
pages/score-list/score-list.vue	选手列表调用	150
pages/score-detail/score-detail.vue	扣分项调用	165
pages/score-detail/score-detail.vue	提交评分调用	237
pages/score-list-multi/score-list-multi.vue	场地列表调用	152
pages/modify-score/modify-score.vue	评分详情调用	157

---

📞 需要帮助？

前端问题

查看文档:

• 前端API对接指南.md - 详细的接口说明
• API接口测试指南.md - 完整的测试流程

检查代码:

• utils/dataAdapter.js - 数据适配器
• utils/request.js - 网络请求封装
• api/index.js - API接口汇总

---

后端问题

查看文档:

• 后端接口开发清单.md - 接口开发规范
• 后端实现对比报告.md - 技术对比

需要实现:

• 创建 MartialMiniController
• 实现5个专用接口
• 准备测试数据

---

✅ 检查清单

开始前检查

• 后端服务已启动
• 前端项目已启动
• apiBaseURL 配置正确
• 调试模式已开启
• 测试数据已准备

测试检查

• 登录功能正常
• Token保存成功
• 选手列表显示正常
• 评分提交成功
• 评分详情查看正常
• 修改评分成功

问题排查

• 查看控制台日志
• 查看Network请求
• 检查请求参数
• 检查响应数据
• 尝试Mock模式

---

🎯 下一步

如果一切正常 ✅

恭喜！API对接成功，可以继续：

1. 完整测试所有功能
2. 处理边界情况
3. 优化用户体验
4. 准备上线

如果遇到问题 ⚠️

不要慌，按照以下步骤：

1. 查看控制台错误信息
2. 参考"常见问题"章节
3. 切换到Mock模式验证前端逻辑
4. 联系后端开发者确认接口状态
5. 查看详细文档

---

📚 相关文档

文档	用途	读者
后端接口开发清单.md	后端开发规范	后端开发者
前端API对接指南.md	前端联调指南	前端开发者
API对接准备完成报告.md	项目状态总结	项目经理
API接口测试指南.md	测试流程	测试人员

---

祝你API对接顺利！ 🎉

如有问题，请查看详细文档或联系团队成员。