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

# API对接快速启动指南

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

---

## 🚀 快速开始（3步）

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

当前配置：[config/env.config.js](../config/env.config.js)

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

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

---

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

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

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

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

---

### 步骤3: 启动前端项目

```bash
# 在当前目录（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](../config/env.config.js:23)
```javascript
debug: true  // ✅ 已开启
```

**控制台会显示**:
- 每个API请求的URL和参数
- 每个API响应的数据
- dataAdapter的模式切换信息

---

### 2. 查看网络请求

**微信开发者工具**:
1. 打开"调试器"
2. 切换到"Network"标签
3. 查看所有HTTP请求

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

---

### 3. 切换到Mock模式测试

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

```javascript
// 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](../utils/request.js#L114-L131) 已实现自动跳转到登录页

---

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

**原因**:
- 数据库中没有选手数据
- 接口参数错误
- 后端接口未实现

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

---

### 问题5: 跨域错误（CORS）

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

**解决**: 后端需要配置CORS

```java
// 后端配置示例
@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](../pages/login/login.vue#L96) | 登录调用 | 96 |
| [pages/score-list/score-list.vue](../pages/score-list/score-list.vue#L150) | 选手列表调用 | 150 |
| [pages/score-detail/score-detail.vue](../pages/score-detail/score-detail.vue#L165) | 扣分项调用 | 165 |
| [pages/score-detail/score-detail.vue](../pages/score-detail/score-detail.vue#L237) | 提交评分调用 | 237 |
| [pages/score-list-multi/score-list-multi.vue](../pages/score-list-multi/score-list-multi.vue#L152) | 场地列表调用 | 152 |
| [pages/modify-score/modify-score.vue](../pages/modify-score/modify-score.vue#L157) | 评分详情调用 | 157 |

---

## 📞 需要帮助？

### 前端问题

**查看文档**:
- [前端API对接指南.md](./前端API对接指南.md) - 详细的接口说明
- [API接口测试指南.md](./API接口测试指南.md) - 完整的测试流程

**检查代码**:
- [utils/dataAdapter.js](../utils/dataAdapter.js) - 数据适配器
- [utils/request.js](../utils/request.js) - 网络请求封装
- [api/index.js](../api/index.js) - API接口汇总

---

### 后端问题

**查看文档**:
- [后端接口开发清单.md](./后端接口开发清单.md) - 接口开发规范
- [后端实现对比报告.md](./后端实现对比报告.md) - 技术对比

**需要实现**:
- 创建 `MartialMiniController`
- 实现5个专用接口
- 准备测试数据

---

## ✅ 检查清单

### 开始前检查

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

### 测试检查

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

### 问题排查

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

---

## 🎯 下一步

### 如果一切正常 ✅

恭喜！API对接成功，可以继续：
1. 完整测试所有功能
2. 处理边界情况
3. 优化用户体验
4. 准备上线

### 如果遇到问题 ⚠️

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

---

## 📚 相关文档

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

---

**祝你API对接顺利！** 🎉

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