martial-admin-mini/doc/API接口对接完成报告.md

小程序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格式：

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

development: {
  dataMode: 'api',  // 从 'mock' 改为 'api'
  apiBaseURL: 'http://localhost:8080',  // 确认后端地址
  debug: true,
  timeout: 30000,
  mockDelay: 300
}

步骤2: 启动后端服务

cd D:\workspace\31.比赛项目\project\martial-master
# 使用IDEA或命令行启动Spring Boot应用

确认后端运行在: http://localhost:8080

步骤3: 重新运行小程序

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: 评分记录

测试数据示例

-- 创建测试邀请码（普通评委）
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：

@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 头部认证：

// 前端已实现：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已完成，前端已适配，待切换测试