gym-manage/gym-manage-uniapp/docs/api-documentation.md

团课管理系统 API 文档

1. 项目概述

本项目是一个基于 UniApp 的健身房团课管理系统，包含完整的 API 层设计，支持开发/生产环境的快速切换。

1.1 项目结构

gym-manage-uniapp/
├── api/                           # API 层目录
│   ├── requestBase.js             # 基础请求封装
│   ├── groupCourse.js             # 团课真实API
│   ├── groupCourse.mock.js        # 团课模拟数据API
│   └── envConfig.js               # 环境配置与服务导出
├── pages/
│   └── groupCourse/
│       └── list.vue               # 团课列表页面
└── components/                    # 组件目录

---

2. API 层设计

2.1 架构设计

层级	文件	职责
基础层	requestBase.js	封装 uni.request，统一处理加载状态、错误提示
接口层	groupCourse.js	定义真实后端API接口
模拟层	groupCourse.mock.js	提供模拟数据，支持开发测试
配置层	envConfig.js	环境配置，统一服务导出入口

2.2 环境切换机制

通过修改 envConfig.js 中的 ENV_MODE 变量实现环境切换：

// envConfig.js
export const ENV_MODE = 'development' // 'production' | 'development'

• production：生产环境，使用真实网络请求
• development：开发环境，使用模拟数据

---

3. 文件详细说明

3.1 requestBase.js - 基础请求封装

功能定位：封装 uni.request，提供统一的请求处理逻辑。

核心特性：

• 自动显示/隐藏加载提示
• 统一的响应状态码处理
• 统一的错误提示机制

接口定义：

方法	说明	参数	返回值
request(options)	发起网络请求	options 对象	Promise

options 参数：

参数	类型	必填	说明
url	string	是	请求路径
method	string	否	请求方法，默认 GET
data	object	否	请求数据
header	object	否	请求头

响应数据结构：

// 成功响应
{
  code: 0,           // 状态码，0表示成功
  message: 'success', // 提示信息
  data: {}           // 业务数据
}

3.2 groupCourse.js - 团课真实 API

功能定位：定义团课相关的真实后端接口。

接口列表：

方法	说明	参数	HTTP方法	路径
getList()	获取团课列表	无	GET	/api/groupCourse/list
getDetail(id)	获取团课详情	id: 课程ID	GET	/api/groupCourse/detail/{id}
book(data)	预约团课	data: 预约数据	POST	/api/groupCourse/book
cancelBooking(id)	取消预约	id: 预约记录ID	POST	/api/groupCourse/cancel/{id}

book 方法参数结构：

{
  courseId: string,  // 课程ID
  memberId: string   // 会员ID
}

3.3 groupCourse.mock.js - 团课模拟数据 API

功能定位：提供模拟数据，支持开发测试，无需后端服务。

特性：

• 模拟网络延迟（300-500ms）
• 接口签名与真实API完全一致
• 包含6条完整的模拟团课数据

模拟数据结构：

字段	类型	说明
id	string	课程唯一标识
courseName	string	课程名称
coachName	string	教练姓名
coachAvatar	string	教练头像
startTime	string	开始时间（ISO格式）
endTime	string	结束时间（ISO格式）
duration	number	课程时长（分钟）
location	string	上课地点
maxMembers	number	最大人数
currentMembers	number	当前人数
storedValueAmount	number	储值卡价格（元）
pointCardAmount	number	次卡次数
courseType	string	课程类型
level	string	难度级别
description	string	课程描述
tags	array	标签列表
status	string	状态（available/closed）

3.4 envConfig.js - 环境配置

功能定位：统一服务导出入口，根据环境模式自动选择 API 实现。

导出内容：

导出项	类型	说明
ENV_MODE	string	当前环境模式
groupCourseService	object	团课服务实例

---

4. 使用示例

4.1 在页面中使用

// pages/groupCourse/list.vue
import { groupCourseService } from '@/api/envConfig.js'

// 获取团课列表
const fetchCourseList = async () => {
  try {
    const data = await groupCourseService.getList()
    courseList.value = data
    console.log('团课列表获取成功:', data)
  } catch (error) {
    console.error('获取团课列表异常:', error)
  }
}

4.2 切换环境

// api/envConfig.js
// 开发环境 - 使用模拟数据
export const ENV_MODE = 'development'

// 生产环境 - 使用真实网络请求
export const ENV_MODE = 'production'

---

5. 数据流转图

┌─────────────────────────────────────────────────────────────┐
│                      页面层 (View)                          │
│              pages/groupCourse/list.vue                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ import & call
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   环境配置层 (Config)                       │
│              api/envConfig.js                               │
│    根据 ENV_MODE 选择对应的服务实现                          │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────┴─────────────────┐
          ▼                                   ▼
┌─────────────────────────┐     ┌─────────────────────────────┐
│   groupCourse.js        │     │   groupCourse.mock.js       │
│   (production 环境)      │     │   (development 环境)        │
└───────────┬─────────────┘     └─────────────┬───────────────┘
            │                                 │
            ▼                                 ▼
┌─────────────────────────┐           ┌─────────────────────┐
│   requestBase.js        │           │  本地模拟数据        │
│   (真实网络请求)         │           │  (无需后端)         │
└───────────┬─────────────┘           └─────────────────────┘
            │
            ▼
┌─────────────────────────┐
│     后端服务器 API       │
└─────────────────────────┘

---

6. 注意事项

1. 环境变量配置：部署前务必确认 ENV_MODE 设置正确
2. 数据一致性：模拟数据结构应与真实API保持一致
3. 错误处理：所有API调用都应包含 try-catch 错误处理
4. 日志记录：建议在关键节点添加日志，便于调试

---

7. 版本历史

版本	日期	更新内容
v1.0	2026-06-04	初始版本，完成基础API层设计