diff --git a/doc/API接口对接完成报告.md b/doc/API接口对接完成报告.md
new file mode 100644
index 0000000..12395dc
--- /dev/null
+++ b/doc/API接口对接完成报告.md
@@ -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已完成，前端已适配，待切换测试