# Martial-Mini 前端API对接方案

## 📊 项目现状总结

### 前端项目状态
- **技术栈**: UniApp (Vue 2) + uView UI
- **目标平台**: H5 + 微信小程序
- **UI完成度**: 100%
- **API对接度**: 0%
- **数据状态**: 所有数据均为硬编码的静态模拟数据

### 后端项目状态
- **技术栈**: Spring Boot + MyBatis Plus
- **API文档**: Swagger 3.0
- **接口总数**: 约70+个REST接口
- **模块数量**: 21个Controller（武术模块）

---

## 🔍 前后端接口对比分析

### 一、已对接接口
**数量: 0个**

前端项目目前完全没有对接任何后端接口，所有数据都是静态模拟数据。

### 二、后端已有接口清单

#### 1. 用户模块 (UserController)
| 接口路径 | 方法 | 功能 | 前端需求 |
|---------|------|------|---------|
| `/blade-system/user/info` | GET | 获取用户信息 | ✅ 需要 (profile.vue) |
| `/blade-system/user/update-password` | POST | 修改密码 | ✅ 需要 (profile.vue) |
| `/blade-system/user/update-info` | POST | 修改基本信息 | ✅ 需要 (profile.vue) |
| `/blade-system/user/list` | GET | 用户列表 | ❌ 不需要 |
| `/blade-system/user/submit` | POST | 新增/修改用户 | ❌ 不需要 |

#### 2. 赛事管理模块 (MartialCompetitionController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/competition/list` | GET | 赛事分页列表 | ✅ 需要 | home.vue, event-list.vue |
| `/martial/competition/detail` | GET | 赛事详情 | ✅ 需要 | event-detail.vue |
| `/martial/competition/submit` | POST | 新增/修改赛事 | ❌ 不需要 | 管理端功能 |
| `/martial/competition/remove` | POST | 删除赛事 | ❌ 不需要 | 管理端功能 |

#### 3. 轮播图模块 (MartialBannerController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/banner/list` | GET | 轮播图列表 | ✅ 需要 | home.vue |
| `/martial/banner/detail` | GET | 轮播图详情 | ❌ 不需要 | - |

#### 4. 比赛项目模块 (MartialProjectController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/project/list` | GET | 项目列表 | ✅ 需要 | select-event.vue |
| `/martial/project/detail` | GET | 项目详情 | ✅ 需要 | select-event.vue |

#### 5. 报名订单模块 (MartialRegistrationOrderController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/registrationOrder/list` | GET | 报名订单列表 | ✅ 需要 | my-registration.vue |
| `/martial/registrationOrder/detail` | GET | 报名订单详情 | ✅ 需要 | my-registration.vue |
| `/martial/registrationOrder/submit` | POST | 提交报名 | ✅ 需要 | event-register.vue |
| `/martial/registrationOrder/remove` | POST | 取消报名 | ✅ 需要 | my-registration.vue |

#### 6. 参赛选手模块 (MartialAthleteController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/athlete/list` | GET | 选手列表 | ✅ 需要 | common-info.vue, event-register.vue, event-players.vue |
| `/martial/athlete/detail` | GET | 选手详情 | ✅ 需要 | edit-player.vue |
| `/martial/athlete/submit` | POST | 新增/修改选手 | ✅ 需要 | add-player.vue, edit-player.vue |
| `/martial/athlete/remove` | POST | 删除选手 | ✅ 需要 | common-info.vue |
| `/martial/athlete/checkin` | POST | 运动员签到 | ❌ 不需要 | 管理端功能 |
| `/martial/athlete/complete` | POST | 完成比赛 | ❌ 不需要 | 管理端功能 |
| `/martial/athlete/status` | POST | 更新比赛状态 | ❌ 不需要 | 管理端功能 |

#### 7. 信息发布模块 (MartialInfoPublishController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/infoPublish/list` | GET | 信息列表 | ✅ 需要 | event-info.vue |
| `/martial/infoPublish/detail` | GET | 信息详情 | ✅ 需要 | event-info.vue |

#### 8. 活动日程模块 (MartialActivityScheduleController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/activitySchedule/list` | GET | 日程列表 | ✅ 需要 | event-schedule.vue |
| `/martial/activitySchedule/detail` | GET | 日程详情 | ✅ 需要 | event-schedule.vue |

#### 9. 赛程编排模块 (MartialScheduleController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/schedule/list` | GET | 赛程列表 | ✅ 需要 | event-lineup.vue |
| `/martial/schedule/detail` | GET | 赛程详情 | ✅ 需要 | event-lineup.vue |

#### 10. 比赛实况模块 (MartialLiveUpdateController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/liveUpdate/list` | GET | 实况列表 | ✅ 需要 | event-live.vue |
| `/martial/liveUpdate/detail` | GET | 实况详情 | ⚠️ 可选 | event-live.vue |

#### 11. 成绩管理模块 (MartialResultController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/result/list` | GET | 成绩列表 | ✅ 需要 | event-score.vue, event-medals.vue |
| `/martial/result/detail` | GET | 成绩详情 | ✅ 需要 | event-score.vue |
| `/martial/result/calculate` | POST | 计算成绩 | ❌ 不需要 | 管理端功能 |
| `/martial/result/ranking` | POST | 自动排名 | ❌ 不需要 | 管理端功能 |
| `/martial/result/medals` | POST | 分配奖牌 | ❌ 不需要 | 管理端功能 |

#### 12. 评分记录模块 (MartialScoreController)
| 接口路径 | 方法 | 功能 | 前端需求 | 前端页面 |
|---------|------|------|---------|---------|
| `/martial/score/list` | GET | 评分列表 | ⚠️ 可选 | event-score.vue |
| `/martial/score/anomalies` | GET | 异常评分列表 | ❌ 不需要 | 管理端功能 |

---

## 📋 需要对接的接口汇总

### 高优先级接口（核心功能）- 共15个

#### 用户相关 (3个)
1. `GET /blade-system/user/info` - 获取用户信息
2. `POST /blade-system/user/update-password` - 修改密码
3. `POST /blade-system/user/update-info` - 修改基本信息

#### 赛事相关 (2个)
4. `GET /martial/competition/list` - 赛事列表
5. `GET /martial/competition/detail` - 赛事详情

#### 轮播图 (1个)
6. `GET /martial/banner/list` - 轮播图列表

#### 报名相关 (4个)
7. `GET /martial/project/list` - 比赛项目列表
8. `POST /martial/registrationOrder/submit` - 提交报名
9. `GET /martial/registrationOrder/list` - 我的报名列表
10. `POST /martial/registrationOrder/remove` - 取消报名

#### 选手管理 (4个)
11. `GET /martial/athlete/list` - 选手列表
12. `GET /martial/athlete/detail` - 选手详情
13. `POST /martial/athlete/submit` - 新增/修改选手
14. `POST /martial/athlete/remove` - 删除选手

#### 成绩查询 (1个)
15. `GET /martial/result/list` - 成绩列表

### 中优先级接口（辅助功能）- 共7个

#### 赛事信息 (6个)
16. `GET /martial/infoPublish/list` - 信息发布列表
17. `GET /martial/activitySchedule/list` - 活动日程列表
18. `GET /martial/schedule/list` - 出场顺序列表
19. `GET /martial/liveUpdate/list` - 比赛实况列表
20. `GET /martial/athlete/list` (赛事维度) - 参赛选手列表
21. `GET /martial/registrationOrder/detail` - 报名详情

#### 项目详情 (1个)
22. `GET /martial/project/detail` - 项目详情

### 低优先级接口（可选功能）- 共6个
23. `GET /martial/infoPublish/detail` - 信息详情
24. `GET /martial/activitySchedule/detail` - 日程详情
25. `GET /martial/schedule/detail` - 赛程详情
26. `GET /martial/liveUpdate/detail` - 实况详情
27. `GET /martial/result/detail` - 成绩详情
28. `GET /martial/score/list` - 评分列表

---

## 🚀 接口对接实施方案

### 阶段一：基础架构搭建（1-2天）

#### 1.1 创建API请求封装
```
martial-mini/
├── api/
│   ├── request.js          # 统一请求封装
│   ├── index.js            # API统一导出
│   ├── user.js             # 用户相关接口
│   ├── competition.js      # 赛事相关接口
│   ├── registration.js     # 报名相关接口
│   ├── athlete.js          # 选手管理接口
│   └── result.js           # 成绩相关接口
├── config/
│   └── api.config.js       # API配置
└── utils/
    └── http.js             # HTTP工具类
```

#### 1.2 request.js 核心代码框架
```javascript
// api/request.js
import config from '@/config/api.config.js'

class Request {
  constructor() {
    this.baseURL = config.baseURL
    this.timeout = config.timeout
  }

  request(options) {
    return new Promise((resolve, reject) => {
      uni.request({
        url: this.baseURL + options.url,
        method: options.method || 'GET',
        data: options.data || {},
        header: {
          'Content-Type': 'application/json',
          'Blade-Auth': uni.getStorageSync('token') || ''
        },
        timeout: this.timeout,
        success: (res) => {
          if (res.data.code === 200) {
            resolve(res.data.data)
          } else {
            uni.showToast({
              title: res.data.msg || '请求失败',
              icon: 'none'
            })
            reject(res.data)
          }
        },
        fail: (err) => {
          uni.showToast({
            title: '网络请求失败',
            icon: 'none'
          })
          reject(err)
        }
      })
    })
  }

  get(url, data) {
    return this.request({ url, method: 'GET', data })
  }

  post(url, data) {
    return this.request({ url, method: 'POST', data })
  }
}

export default new Request()
```

#### 1.3 API配置文件
```javascript
// config/api.config.js
const env = process.env.NODE_ENV

const config = {
  development: {
    baseURL: 'http://localhost:8080', // 开发环境
    timeout: 30000
  },
  production: {
    baseURL: 'https://api.yourdomain.com', // 生产环境
    timeout: 30000
  }
}

export default config[env]
```

### 阶段二：核心功能对接（3-5天）

#### 2.1 赛事列表与详情 (第1天)

**接口对接:**
- `GET /martial/competition/list`
- `GET /martial/competition/detail`
- `GET /martial/banner/list`

**涉及页面:**
- `pages/index/home.vue` - 首页
- `pages/event/event-list.vue` - 赛事列表
- `pages/event/event-detail.vue` - 赛事详情

**实现步骤:**

1. 创建 `api/competition.js`:
```javascript
import request from './request.js'

export default {
  // 获取赛事列表
  getCompetitionList(params) {
    return request.get('/martial/competition/list', params)
  },

  // 获取赛事详情
  getCompetitionDetail(id) {
    return request.get('/martial/competition/detail', { id })
  },

  // 获取轮播图
  getBannerList(params) {
    return request.get('/martial/banner/list', params)
  }
}
```

2. 修改 `home.vue`:
```javascript
import competitionAPI from '@/api/competition.js'

export default {
  data() {
    return {
      banners: [],
      events: []
    }
  },
  onLoad() {
    this.loadBanners()
    this.loadEvents()
  },
  methods: {
    async loadBanners() {
      try {
        const res = await competitionAPI.getBannerList({ current: 1, size: 5 })
        this.banners = res.records
      } catch (err) {
        console.error('加载轮播图失败', err)
      }
    },
    async loadEvents() {
      try {
        const res = await competitionAPI.getCompetitionList({ current: 1, size: 10 })
        this.events = res.records
      } catch (err) {
        console.error('加载赛事失败', err)
      }
    }
  }
}
```

#### 2.2 选手管理功能 (第2天)

**接口对接:**
- `GET /martial/athlete/list`
- `GET /martial/athlete/detail`
- `POST /martial/athlete/submit`
- `POST /martial/athlete/remove`

**涉及页面:**
- `pages/personal/common-info.vue` - 常用信息
- `pages/personal/add-player.vue` - 新增选手
- `pages/personal/edit-player.vue` - 编辑选手

**实现步骤:**

1. 创建 `api/athlete.js`:
```javascript
import request from './request.js'

export default {
  // 获取选手列表
  getAthleteList(params) {
    return request.get('/martial/athlete/list', params)
  },

  // 获取选手详情
  getAthleteDetail(id) {
    return request.get('/martial/athlete/detail', { id })
  },

  // 新增或修改选手
  submitAthlete(data) {
    return request.post('/martial/athlete/submit', data)
  },

  // 删除选手
  removeAthlete(ids) {
    return request.post('/martial/athlete/remove', { ids })
  }
}
```

2. 修改 `common-info.vue`:
```javascript
import athleteAPI from '@/api/athlete.js'

export default {
  data() {
    return {
      players: []
    }
  },
  onShow() {
    this.loadPlayers()
  },
  methods: {
    async loadPlayers() {
      try {
        const res = await athleteAPI.getAthleteList({ current: 1, size: 100 })
        this.players = res.records
      } catch (err) {
        console.error('加载选手失败', err)
      }
    },
    async deletePlayer(id) {
      try {
        await athleteAPI.removeAthlete(id)
        uni.showToast({ title: '删除成功', icon: 'success' })
        this.loadPlayers()
      } catch (err) {
        console.error('删除失败', err)
      }
    }
  }
}
```

#### 2.3 报名流程功能 (第3天)

**接口对接:**
- `GET /martial/project/list`
- `POST /martial/registrationOrder/submit`
- `GET /martial/registrationOrder/list`
- `POST /martial/registrationOrder/remove`

**涉及页面:**
- `pages/event/select-event.vue` - 选择项目
- `pages/event/event-register.vue` - 报名
- `pages/personal/my-registration.vue` - 我的报名

**实现步骤:**

1. 创建 `api/registration.js`:
```javascript
import request from './request.js'

export default {
  // 获取项目列表
  getProjectList(params) {
    return request.get('/martial/project/list', params)
  },

  // 提交报名
  submitRegistration(data) {
    return request.post('/martial/registrationOrder/submit', data)
  },

  // 获取报名列表
  getRegistrationList(params) {
    return request.get('/martial/registrationOrder/list', params)
  },

  // 取消报名
  cancelRegistration(ids) {
    return request.post('/martial/registrationOrder/remove', { ids })
  },

  // 获取报名详情
  getRegistrationDetail(id) {
    return request.get('/martial/registrationOrder/detail', { id })
  }
}
```

2. 修改 `event-register.vue`:
```javascript
import registrationAPI from '@/api/registration.js'
import athleteAPI from '@/api/athlete.js'

export default {
  data() {
    return {
      players: [],
      selectedPlayers: [],
      orderInfo: {}
    }
  },
  onLoad() {
    this.loadPlayers()
  },
  methods: {
    async loadPlayers() {
      try {
        const res = await athleteAPI.getAthleteList({ current: 1, size: 100 })
        this.players = res.records
      } catch (err) {
        console.error('加载选手失败', err)
      }
    },
    async submitRegistration() {
      try {
        const data = {
          competitionId: this.competitionId,
          projectId: this.projectId,
          athleteIds: this.selectedPlayers.map(p => p.id),
          // ... 其他报名信息
        }
        await registrationAPI.submitRegistration(data)
        uni.showToast({ title: '报名成功', icon: 'success' })
        setTimeout(() => {
          uni.navigateBack()
        }, 1500)
      } catch (err) {
        console.error('报名失败', err)
      }
    }
  }
}
```

#### 2.4 用户信息功能 (第4天)

**接口对接:**
- `GET /blade-system/user/info`
- `POST /blade-system/user/update-password`
- `POST /blade-system/user/update-info`

**涉及页面:**
- `pages/personal/profile.vue` - 个人中心

**实现步骤:**

1. 创建 `api/user.js`:
```javascript
import request from './request.js'

export default {
  // 获取用户信息
  getUserInfo() {
    return request.get('/blade-system/user/info')
  },

  // 修改密码
  updatePassword(data) {
    return request.post('/blade-system/user/update-password', data)
  },

  // 修改基本信息
  updateUserInfo(data) {
    return request.post('/blade-system/user/update-info', data)
  }
}
```

#### 2.5 成绩查询功能 (第5天)

**接口对接:**
- `GET /martial/result/list`
- `GET /martial/result/detail`

**涉及页面:**
- `pages/event/event-score.vue` - 成绩查询
- `pages/event/event-medals.vue` - 奖牌榜

**实现步骤:**

1. 创建 `api/result.js`:
```javascript
import request from './request.js'

export default {
  // 获取成绩列表
  getResultList(params) {
    return request.get('/martial/result/list', params)
  },

  // 获取成绩详情
  getResultDetail(id) {
    return request.get('/martial/result/detail', { id })
  }
}
```

### 阶段三：辅助功能对接（2-3天）

#### 3.1 赛事信息页面 (第6天)

**接口对接:**
- `GET /martial/infoPublish/list` - 信息发布
- `GET /martial/activitySchedule/list` - 活动日程
- `GET /martial/athlete/list` - 参赛选手

**涉及页面:**
- `pages/event/event-info.vue`
- `pages/event/event-schedule.vue`
- `pages/event/event-players.vue`

#### 3.2 实时数据页面 (第7天)

**接口对接:**
- `GET /martial/schedule/list` - 出场顺序
- `GET /martial/liveUpdate/list` - 比赛实况

**涉及页面:**
- `pages/event/event-lineup.vue`
- `pages/event/event-live.vue`

### 阶段四：优化与测试（2-3天）

#### 4.1 功能优化
- 添加请求loading状态
- 实现下拉刷新
- 实现上拉加载更多
- 添加请求缓存机制
- 优化错误处理

#### 4.2 数据适配
- 后端数据字段映射到前端
- 日期格式转换
- 图片URL处理
- 状态码映射

#### 4.3 测试
- 接口联调测试
- 边界情况测试
- 异常处理测试
- 性能测试

---

## 📝 数据字段映射参考

### 赛事数据映射
```javascript
// 后端返回字段 -> 前端使用字段
{
  id: 'id',                          // 赛事ID
  name: 'title',                     // 赛事名称
  startTime: 'startDate',            // 开始时间
  endTime: 'endDate',                // 结束时间
  location: 'location',              // 地点
  registrationDeadline: 'deadline',  // 报名截止
  coverImage: 'image',               // 封面图
  status: 'status',                  // 状态
  description: 'description'         // 描述
}
```

### 选手数据映射
```javascript
// 后端返回字段 -> 前端使用字段
{
  id: 'id',                    // 选手ID
  name: 'name',                // 姓名
  gender: 'gender',            // 性别
  birthDate: 'birthday',       // 出生日期
  idCard: 'idCard',            // 身份证
  phone: 'phone',              // 手机号
  team: 'team',                // 代表队
  height: 'height',            // 身高
  weight: 'weight'             // 体重
}
```

---

## ⚙️ 环境配置要求

### 1. API Base URL配置
```javascript
// 开发环境
http://localhost:8080

// 测试环境
http://test-api.yourdomain.com

// 生产环境
https://api.yourdomain.com
```

### 2. 请求头配置
```javascript
{
  'Content-Type': 'application/json',
  'Blade-Auth': 'Bearer {token}',  // 认证token
  'Tenant-Id': '{tenantId}'        // 租户ID（如果需要）
}
```

### 3. 响应数据格式
```javascript
// 成功响应
{
  code: 200,
  success: true,
  data: {},
  msg: "操作成功"
}

// 失败响应
{
  code: 400,
  success: false,
  data: null,
  msg: "错误信息"
}

// 分页响应
{
  code: 200,
  success: true,
  data: {
    records: [],      // 数据列表
    total: 100,       // 总记录数
    size: 10,         // 每页大小
    current: 1,       // 当前页
    pages: 10         // 总页数
  }
}
```

---

## 🎯 关键注意事项

### 1. 认证与授权
- 需要实现登录功能获取token
- token需要存储到本地并在每次请求时携带
- token过期需要处理刷新或重新登录

### 2. 跨域问题
- H5端需要配置代理或后端开启CORS
- 小程序端需要在后台配置合法域名

### 3. 数据筛选与查询
- 后端使用MyBatis Plus的Condition.getQueryWrapper
- 前端传参需要注意参数名与后端实体字段对应
- 分页参数: `current` (当前页), `size` (每页大小)

### 4. 图片上传
- 需要对接 `/martial/attach` 或 `/martial/oss` 接口
- 支持选手照片、赛事封面等图片上传

### 5. 状态管理
- 建议使用Vuex管理用户信息、token等全局状态
- 可以缓存常用数据（如赛事列表）减少请求

---

## 📊 工作量评估

| 阶段 | 任务 | 预计工时 | 接口数量 |
|------|------|---------|---------|
| 阶段一 | 基础架构搭建 | 1-2天 | 0 |
| 阶段二 | 核心功能对接 | 3-5天 | 15个 |
| 阶段三 | 辅助功能对接 | 2-3天 | 7个 |
| 阶段四 | 优化与测试 | 2-3天 | - |
| **总计** | | **8-13天** | **22个** |

---

## 🔄 迭代建议

### 第一版（MVP）
只对接核心功能接口（15个高优先级接口）:
- 赛事列表与详情
- 选手管理
- 报名功能
- 成绩查询

### 第二版（完善版）
对接辅助功能接口（7个中优先级接口）:
- 信息发布
- 活动日程
- 出场顺序
- 比赛实况

### 第三版（完整版）
对接所有接口并优化:
- 详情页接口
- 性能优化
- 缓存策略
- 离线支持

---

## 📞 后续支持

### 需要后端配合的事项
1. 提供完整的Swagger API文档
2. 提供测试环境和测试账号
3. 确认数据字段定义和返回格式
4. 处理可能的跨域问题
5. 提供图片上传接口文档

### 需要确认的问题
1. 是否需要实现登录功能？（目前未找到登录接口）
2. 报名订单是否需要支付功能？
3. 是否需要实时推送功能（WebSocket）？
4. 图片资源的CDN地址是什么？
5. 多租户配置如何处理？

---

## ✅ 验收标准

1. ✅ 所有页面的静态数据替换为API数据
2. ✅ 列表页支持下拉刷新和上拉加载
3. ✅ 详情页正确显示后端数据
4. ✅ 表单提交成功并有反馈
5. ✅ 错误处理完善，有友好提示
6. ✅ 网络请求有loading状态
7. ✅ 核心流程可完整走通

---

**文档生成时间**: 2025-12-10
**前端项目**: martial-mini
**后端项目**: martial-master
**文档版本**: v1.0