martial/martial-mini

Fork 0

Files

宅房 2f1d732a36 fix bugs

2025-12-12 01:44:41 +08:00

22 KiB

Raw Blame History

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个)

GET /blade-system/user/info - 获取用户信息
POST /blade-system/user/update-password - 修改密码
POST /blade-system/user/update-info - 修改基本信息

赛事相关 (2个)

GET /martial/competition/list - 赛事列表
GET /martial/competition/detail - 赛事详情

轮播图 (1个)

GET /martial/banner/list - 轮播图列表

报名相关 (4个)

GET /martial/project/list - 比赛项目列表
POST /martial/registrationOrder/submit - 提交报名
GET /martial/registrationOrder/list - 我的报名列表
POST /martial/registrationOrder/remove - 取消报名

选手管理 (4个)

GET /martial/athlete/list - 选手列表
GET /martial/athlete/detail - 选手详情
POST /martial/athlete/submit - 新增/修改选手
POST /martial/athlete/remove - 删除选手

成绩查询 (1个)

GET /martial/result/list - 成绩列表

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

赛事信息 (6个)

GET /martial/infoPublish/list - 信息发布列表
GET /martial/activitySchedule/list - 活动日程列表
GET /martial/schedule/list - 出场顺序列表
GET /martial/liveUpdate/list - 比赛实况列表
GET /martial/athlete/list (赛事维度) - 参赛选手列表
GET /martial/registrationOrder/detail - 报名详情

项目详情 (1个)

GET /martial/project/detail - 项目详情

低优先级接口（可选功能）- 共6个

GET /martial/infoPublish/detail - 信息详情
GET /martial/activitySchedule/detail - 日程详情
GET /martial/schedule/detail - 赛程详情
GET /martial/liveUpdate/detail - 实况详情
GET /martial/result/detail - 成绩详情
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 核心代码框架

// 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配置文件

// 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 - 赛事详情

实现步骤:

创建 api/competition.js:

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)
  }
}

修改 home.vue:

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 - 编辑选手

实现步骤:

创建 api/athlete.js:

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 })
  }
}

修改 common-info.vue:

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 - 我的报名

实现步骤:

创建 api/registration.js:

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 })
  }
}

修改 event-register.vue:

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 - 个人中心

实现步骤:

创建 api/user.js:

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 - 奖牌榜

实现步骤:

创建 api/result.js:

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 测试

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

📝 数据字段映射参考

赛事数据映射

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

选手数据映射

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

⚙️ 环境配置要求

1. API Base URL配置

// 开发环境
http://localhost:8080

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

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

2. 请求头配置

{
  'Content-Type': 'application/json',
  'Blade-Auth': 'Bearer {token}',  // 认证token
  'Tenant-Id': '{tenantId}'        // 租户ID（如果需要）
}

3. 响应数据格式

// 成功响应
{
  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个中优先级接口）:

信息发布
活动日程
出场顺序
比赛实况

第三版（完整版）

对接所有接口并优化:

详情页接口
性能优化
缓存策略
离线支持

📞 后续支持

需要后端配合的事项

提供完整的Swagger API文档
提供测试环境和测试账号
确认数据字段定义和返回格式
处理可能的跨域问题
提供图片上传接口文档

需要确认的问题

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

✅ 验收标准

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

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

22 KiB Raw Blame History Unescape Escape

Martial-Mini 前端API对接方案

📊 项目现状总结

前端项目状态

后端项目状态

🔍 前后端接口对比分析

一、已对接接口

二、后端已有接口清单

1. 用户模块 (UserController)

2. 赛事管理模块 (MartialCompetitionController)

3. 轮播图模块 (MartialBannerController)

4. 比赛项目模块 (MartialProjectController)

5. 报名订单模块 (MartialRegistrationOrderController)

6. 参赛选手模块 (MartialAthleteController)

7. 信息发布模块 (MartialInfoPublishController)

8. 活动日程模块 (MartialActivityScheduleController)

9. 赛程编排模块 (MartialScheduleController)

10. 比赛实况模块 (MartialLiveUpdateController)

11. 成绩管理模块 (MartialResultController)

12. 评分记录模块 (MartialScoreController)

📋 需要对接的接口汇总

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

用户相关 (3个)

赛事相关 (2个)

轮播图 (1个)

报名相关 (4个)

选手管理 (4个)

成绩查询 (1个)

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

赛事信息 (6个)

项目详情 (1个)

低优先级接口（可选功能）- 共6个

🚀 接口对接实施方案

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

1.1 创建API请求封装

1.2 request.js 核心代码框架

1.3 API配置文件

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

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

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

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

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

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

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

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

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

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

4.1 功能优化

4.2 数据适配

4.3 测试

📝 数据字段映射参考

赛事数据映射

选手数据映射

⚙️ 环境配置要求

1. API Base URL配置

2. 请求头配置

3. 响应数据格式

🎯 关键注意事项

1. 认证与授权

2. 跨域问题

3. 数据筛选与查询

4. 图片上传

5. 状态管理

📊 工作量评估

🔄 迭代建议

第一版（MVP）

第二版（完善版）

第三版（完整版）

📞 后续支持

需要后端配合的事项

需要确认的问题

✅ 验收标准

22 KiB

Raw Blame History