docs: 添加API接口对接完成报告
📋 报告内容： 1. 后端API接口实现概览（5个接口） 2. DTO/VO类详细说明（7个类） 3. Service层实现说明（4个方法） 4. 技术实现亮点（登录验证、项目解析、权限控制、修改日志） 5. 前端适配状态（9个接口映射） 6. API模式切换步骤 7. 数据库准备和测试数据 8. 注意事项和已知问题 9. 下一步行动和测试清单 🎯 当前状态： - ✅ 后端API已完成 - ✅ 前端已适配dataAdapter - ⏳ 待切换config.dataMode为'api'进行测试 Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
395
doc/API接口对接完成报告.md
Normal file
395
doc/API接口对接完成报告.md
Normal file
@@ -0,0 +1,395 @@
|
|||||||
|
# 小程序API接口对接完成报告
|
||||||
|
|
||||||
|
**日期**: 2025-12-11
|
||||||
|
**项目**: 武术评分系统小程序
|
||||||
|
**状态**: ✅ 后端API接口已完成，前端已适配，待切换测试
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 完成概览
|
||||||
|
|
||||||
|
### 1. 后端API接口实现 ✅
|
||||||
|
|
||||||
|
#### 1.1 控制器 (MartialMiniController.java)
|
||||||
|
**路径**: `martial-master/src/main/java/org/springblade/modules/martial/controller/MartialMiniController.java`
|
||||||
|
|
||||||
|
| 接口 | 方法 | 路径 | 功能 | 状态 |
|
||||||
|
|------|------|------|------|------|
|
||||||
|
| 登录验证 | POST | `/api/mini/login` | 比赛编码+邀请码登录 | ✅ 已实现 |
|
||||||
|
| 选手列表（普通评委） | GET | `/api/mini/athletes` | 查询分配的选手列表 | ✅ 已实现 |
|
||||||
|
| 选手列表（裁判长） | GET | `/api/mini/athletes/admin` | 查看所有选手 | ✅ 已实现 |
|
||||||
|
| 评分详情 | GET | `/api/mini/score/detail/{athleteId}` | 查看选手的所有评委评分 | ✅ 已实现 |
|
||||||
|
| 修改评分 | PUT | `/api/mini/score/modify` | 裁判长修改选手总分 | ✅ 已实现 |
|
||||||
|
|
||||||
|
#### 1.2 数据传输对象 (DTO) ✅
|
||||||
|
|
||||||
|
**路径**: `martial-master/src/main/java/org/springblade/modules/martial/pojo/dto/`
|
||||||
|
|
||||||
|
- **MiniLoginDTO.java**: 登录请求
|
||||||
|
- matchCode: 比赛编码
|
||||||
|
- inviteCode: 邀请码
|
||||||
|
- loginIp: 登录IP
|
||||||
|
- deviceInfo: 设备信息
|
||||||
|
|
||||||
|
- **MiniAthleteScoreDTO.java**: 提交评分请求
|
||||||
|
- athleteId: 选手ID
|
||||||
|
- judgeId: 评委ID
|
||||||
|
- score: 评分
|
||||||
|
- deductions: 扣分项列表
|
||||||
|
- note: 备注
|
||||||
|
|
||||||
|
- **MiniScoreModifyDTO.java**: 修改评分请求
|
||||||
|
- athleteId: 选手ID
|
||||||
|
- modifierId: 修改者ID（裁判长ID）
|
||||||
|
- modifiedScore: 修改后的分数
|
||||||
|
- note: 修改原因/备注
|
||||||
|
|
||||||
|
#### 1.3 视图对象 (VO) ✅
|
||||||
|
|
||||||
|
**路径**: `martial-master/src/main/java/org/springblade/modules/martial/pojo/vo/`
|
||||||
|
|
||||||
|
- **MiniLoginVO.java**: 登录响应
|
||||||
|
- token: 访问令牌
|
||||||
|
- userRole: 用户角色（pub/admin）
|
||||||
|
- matchId, matchName, matchTime: 比赛信息
|
||||||
|
- judgeId, judgeName: 评委信息
|
||||||
|
- venueId, venueName: 场地信息
|
||||||
|
- projects: 分配的项目列表
|
||||||
|
|
||||||
|
- **MiniAthleteScoreVO.java**: 选手评分信息（普通评委视图）
|
||||||
|
- athleteId: 选手ID
|
||||||
|
- name, idCard, team, number: 选手基本信息
|
||||||
|
- scored: 是否已评分
|
||||||
|
- myScore: 我的评分
|
||||||
|
- totalScore: 总分
|
||||||
|
|
||||||
|
- **MiniAthleteAdminVO.java**: 选手评分信息（裁判长视图）
|
||||||
|
- athleteId: 选手ID
|
||||||
|
- name, idCard, team, number: 选手基本信息
|
||||||
|
- totalScore: 总分
|
||||||
|
- judgeCount: 已评分评委数量
|
||||||
|
- totalJudgeCount: 总评委数量
|
||||||
|
|
||||||
|
- **MiniScoreDetailVO.java**: 评分详情
|
||||||
|
- athleteInfo: 选手信息
|
||||||
|
- judgeScores: 评委评分列表
|
||||||
|
- modification: 裁判长修改信息
|
||||||
|
|
||||||
|
#### 1.4 Service层实现 ✅
|
||||||
|
|
||||||
|
**IMartialAthleteService / MartialAthleteServiceImpl**:
|
||||||
|
- `getAthletesWithMyScore(judgeId, venueId, projectId)`: 查询选手列表（含我的评分）
|
||||||
|
- `getAthletesForAdmin(competitionId, venueId, projectId)`: 查询选手列表（含评分统计）
|
||||||
|
|
||||||
|
**IMartialScoreService / MartialScoreServiceImpl**:
|
||||||
|
- `getScoreDetailForMini(athleteId)`: 查询评分详情
|
||||||
|
- `modifyScoreByAdmin(dto)`: 裁判长修改评分
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔥 技术实现亮点
|
||||||
|
|
||||||
|
### 1. 登录验证机制
|
||||||
|
- **双重验证**: 比赛编码 + 邀请码
|
||||||
|
- **Token生成**: UUID格式，32位随机字符串
|
||||||
|
- **有效期管理**: 7天自动过期（tokenExpireTime）
|
||||||
|
- **设备追踪**: 记录登录IP和设备信息
|
||||||
|
- **使用状态**: 标记邀请码已使用（isUsed=1, useTime）
|
||||||
|
|
||||||
|
### 2. 项目分配解析
|
||||||
|
支持两种JSON格式：
|
||||||
|
```javascript
|
||||||
|
// 格式1: JSON数组（推荐）
|
||||||
|
[1, 2, 3]
|
||||||
|
|
||||||
|
// 格式2: 逗号分隔（兼容）
|
||||||
|
"1,2,3"
|
||||||
|
```
|
||||||
|
|
||||||
|
实现逻辑：
|
||||||
|
1. 优先尝试JSON.parse解析
|
||||||
|
2. 失败则按逗号分隔解析
|
||||||
|
3. 查询项目详情并返回 `{projectId, projectName}`
|
||||||
|
|
||||||
|
### 3. 权限控制
|
||||||
|
- **普通评委（pub）**:
|
||||||
|
- 只能查看分配的场地和项目
|
||||||
|
- 只能对分配的选手评分
|
||||||
|
- venueId != null
|
||||||
|
|
||||||
|
- **裁判长（admin）**:
|
||||||
|
- 可以查看所有场地和项目
|
||||||
|
- 可以修改选手总分
|
||||||
|
- venueId == null
|
||||||
|
- role = "chief_judge"
|
||||||
|
|
||||||
|
### 4. 评分修改日志
|
||||||
|
- 修改前保存原始总分（originalScore）
|
||||||
|
- 记录修改者、修改时间、修改原因
|
||||||
|
- 创建新的评分记录标记为"裁判长修改"
|
||||||
|
- 支持查询修改历史
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📱 前端适配状态
|
||||||
|
|
||||||
|
### 1. DataAdapter 已实现 ✅
|
||||||
|
|
||||||
|
**路径**: `martial-admin-mini/utils/dataAdapter.js`
|
||||||
|
|
||||||
|
所有页面已通过 `dataAdapter.getData(resource, params)` 调用数据：
|
||||||
|
|
||||||
|
| 页面 | 资源名称 | 对应后端接口 | 状态 |
|
||||||
|
|------|---------|-------------|------|
|
||||||
|
| login.vue | `login` | POST /api/mini/login | ✅ 已适配 |
|
||||||
|
| score-list.vue | `getMyAthletes` | GET /api/mini/athletes | ✅ 已适配 |
|
||||||
|
| score-list-multi.vue | `getVenues` | GET /martial/venue/list | ✅ 已适配 |
|
||||||
|
| score-list-multi.vue | `getProjects` | GET /martial/project/list | ✅ 已适配 |
|
||||||
|
| score-list-multi.vue | `getAthletesForAdmin` | GET /api/mini/athletes/admin | ✅ 已适配 |
|
||||||
|
| score-detail.vue | `getDeductions` | GET /martial/deductionItem/list | ✅ 已适配 |
|
||||||
|
| score-detail.vue | `submitScore` | POST /martial/score/submit | ✅ 已适配 |
|
||||||
|
| modify-score.vue | `getScoreDetail` | GET /api/mini/score/detail/{athleteId} | ✅ 已适配 |
|
||||||
|
| modify-score.vue | `modifyScore` | PUT /api/mini/score/modify | ✅ 已适配 |
|
||||||
|
|
||||||
|
### 2. API 接口映射 ✅
|
||||||
|
|
||||||
|
**路径**: `martial-admin-mini/api/athlete.js`, `api/score.js`, `api/auth.js`
|
||||||
|
|
||||||
|
所有接口映射已完成，包含：
|
||||||
|
- 请求方法（GET/POST/PUT）
|
||||||
|
- 接口路径
|
||||||
|
- 参数结构
|
||||||
|
- token头部添加
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 如何切换到API模式
|
||||||
|
|
||||||
|
### 步骤1: 修改配置文件
|
||||||
|
|
||||||
|
**文件**: `martial-admin-mini/config/env.config.js`
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
development: {
|
||||||
|
dataMode: 'api', // 从 'mock' 改为 'api'
|
||||||
|
apiBaseURL: 'http://localhost:8080', // 确认后端地址
|
||||||
|
debug: true,
|
||||||
|
timeout: 30000,
|
||||||
|
mockDelay: 300
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 步骤2: 启动后端服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd D:\workspace\31.比赛项目\project\martial-master
|
||||||
|
# 使用IDEA或命令行启动Spring Boot应用
|
||||||
|
```
|
||||||
|
|
||||||
|
确认后端运行在: `http://localhost:8080`
|
||||||
|
|
||||||
|
### 步骤3: 重新运行小程序
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd D:\workspace\31.比赛项目\project\martial-admin-mini
|
||||||
|
npm run dev:mp-weixin
|
||||||
|
```
|
||||||
|
|
||||||
|
或在 HBuilderX 中重新运行到微信开发者工具
|
||||||
|
|
||||||
|
### 步骤4: 测试验证
|
||||||
|
|
||||||
|
1. **登录测试**:
|
||||||
|
- 比赛编码: [从数据库获取]
|
||||||
|
- 邀请码: [从数据库获取]
|
||||||
|
- 验证token是否正常返回
|
||||||
|
|
||||||
|
2. **选手列表测试**:
|
||||||
|
- 普通评委: 验证是否只显示分配的选手
|
||||||
|
- 裁判长: 验证是否显示所有选手
|
||||||
|
|
||||||
|
3. **评分测试**:
|
||||||
|
- 提交评分
|
||||||
|
- 查看评分详情
|
||||||
|
- 裁判长修改评分
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 数据库准备
|
||||||
|
|
||||||
|
### 必需数据
|
||||||
|
|
||||||
|
1. **martial_competition**: 比赛信息
|
||||||
|
- 需要有 `code` 字段（比赛编码）
|
||||||
|
|
||||||
|
2. **martial_judge**: 评委信息
|
||||||
|
- name, phone, idCard 等基本信息
|
||||||
|
|
||||||
|
3. **martial_judge_invite**: 邀请码信息
|
||||||
|
- inviteCode: 邀请码（唯一）
|
||||||
|
- competitionId: 关联比赛
|
||||||
|
- judgeId: 关联评委
|
||||||
|
- venueId: 分配场地（裁判长为null）
|
||||||
|
- projects: 分配项目（JSON数组或逗号分隔，如 "[1,2,3]" 或 "1,2,3"）
|
||||||
|
- role: 角色（"judge" 或 "chief_judge"）
|
||||||
|
- expireTime: 过期时间
|
||||||
|
- isDeleted: 0
|
||||||
|
|
||||||
|
4. **martial_venue**: 场地信息
|
||||||
|
5. **martial_project**: 项目信息
|
||||||
|
6. **martial_athlete**: 选手信息
|
||||||
|
7. **martial_score**: 评分记录
|
||||||
|
|
||||||
|
### 测试数据示例
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- 创建测试邀请码（普通评委）
|
||||||
|
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()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- 创建测试邀请码（裁判长）
|
||||||
|
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, 2, 'ADMIN999', 'chief_judge', NULL, '[1,2,3,4,5]',
|
||||||
|
DATE_ADD(NOW(), INTERVAL 7 DAY), 0, 0, NOW(), NOW()
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ 注意事项
|
||||||
|
|
||||||
|
### 1. CORS 跨域配置
|
||||||
|
如果小程序运行在非 localhost，需要配置后端CORS：
|
||||||
|
|
||||||
|
```java
|
||||||
|
@Configuration
|
||||||
|
public class CorsConfig {
|
||||||
|
@Bean
|
||||||
|
public CorsFilter corsFilter() {
|
||||||
|
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
|
||||||
|
CorsConfiguration config = new CorsConfiguration();
|
||||||
|
config.addAllowedOrigin("*");
|
||||||
|
config.addAllowedMethod("*");
|
||||||
|
config.addAllowedHeader("*");
|
||||||
|
source.registerCorsConfiguration("/api/**", config);
|
||||||
|
return new CorsFilter(source);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Token 认证
|
||||||
|
后端使用 BladeX 框架的 `Blade-Auth` 头部认证：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 前端已实现：utils/request.js
|
||||||
|
headers: {
|
||||||
|
'Blade-Auth': `Bearer ${token}`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 数据格式差异
|
||||||
|
- Mock数据使用 `athleteId`，后端可能使用 `id`
|
||||||
|
- Mock数据使用 `scored` 布尔值，后端通过评分记录判断
|
||||||
|
- 需要在Service层进行数据转换
|
||||||
|
|
||||||
|
### 4. 分页参数
|
||||||
|
如果后端接口支持分页，前端当前未实现分页加载，后续可扩展。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🐛 已知问题与待办
|
||||||
|
|
||||||
|
### 待测试项
|
||||||
|
|
||||||
|
- [ ] 登录接口token生成和验证
|
||||||
|
- [ ] 邀请码过期时间验证
|
||||||
|
- [ ] 项目JSON解析（两种格式）
|
||||||
|
- [ ] 普通评委权限限制
|
||||||
|
- [ ] 裁判长修改评分日志
|
||||||
|
- [ ] 评分详情查询性能（多表关联）
|
||||||
|
- [ ] 并发评分场景
|
||||||
|
- [ ] 网络异常处理
|
||||||
|
|
||||||
|
### 后续优化
|
||||||
|
|
||||||
|
1. **性能优化**:
|
||||||
|
- 选手列表查询可以添加索引
|
||||||
|
- 评分详情可以优化为一次查询
|
||||||
|
- 考虑添加Redis缓存
|
||||||
|
|
||||||
|
2. **功能扩展**:
|
||||||
|
- 支持实时推送评分更新（WebSocket）
|
||||||
|
- 支持评分撤回功能
|
||||||
|
- 支持批量导出评分数据
|
||||||
|
- 支持评分异常检测告警
|
||||||
|
|
||||||
|
3. **安全增强**:
|
||||||
|
- Token刷新机制
|
||||||
|
- IP白名单限制
|
||||||
|
- 防刷验证码
|
||||||
|
- 操作日志记录
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Git 提交记录
|
||||||
|
|
||||||
|
### 后端提交
|
||||||
|
```
|
||||||
|
commit 1c981a2
|
||||||
|
feat: 实现小程序专用API接口
|
||||||
|
|
||||||
|
✅ 新增功能：
|
||||||
|
1. 创建MartialMiniController - 5个小程序专用接口
|
||||||
|
2. 新增DTO类（3个）
|
||||||
|
3. 新增VO类（4个）
|
||||||
|
4. Service层实现（4个方法）
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端提交（之前完成）
|
||||||
|
```
|
||||||
|
commit [hash]
|
||||||
|
feat: 完成5个页面接入dataAdapter - Mock模式功能完成
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 下一步行动
|
||||||
|
|
||||||
|
### 立即执行
|
||||||
|
1. ✅ 修改 `config/env.config.js` 的 `dataMode` 为 `'api'`
|
||||||
|
2. ✅ 启动后端服务（martial-master）
|
||||||
|
3. ✅ 启动小程序前端（martial-admin-mini）
|
||||||
|
4. ✅ 测试登录接口
|
||||||
|
|
||||||
|
### 测试清单
|
||||||
|
- [ ] 登录功能（普通评委）
|
||||||
|
- [ ] 登录功能（裁判长）
|
||||||
|
- [ ] 普通评委查看选手列表
|
||||||
|
- [ ] 普通评委提交评分
|
||||||
|
- [ ] 裁判长查看所有选手
|
||||||
|
- [ ] 裁判长查看评分详情
|
||||||
|
- [ ] 裁判长修改评分
|
||||||
|
- [ ] 查看修改历史记录
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 联系方式
|
||||||
|
|
||||||
|
如有问题或需要支持，请参考：
|
||||||
|
- 后端项目: `D:\workspace\31.比赛项目\project\martial-master`
|
||||||
|
- 前端项目: `D:\workspace\31.比赛项目\project\martial-admin-mini`
|
||||||
|
- API文档: 启动后访问 `http://localhost:8080/doc.html`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**报告生成时间**: 2025-12-11
|
||||||
|
**生成者**: Claude Code Assistant
|
||||||
|
**状态**: ✅ 后端API已完成，前端已适配，待切换测试
|
||||||
Reference in New Issue
Block a user