812 lines
22 KiB
Markdown
812 lines
22 KiB
Markdown
# 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
|