# 团课管理系统 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` 变量实现环境切换：

```javascript
// 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 | 否 | 请求头 |

**响应数据结构**：

```javascript
// 成功响应
{
  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 方法参数结构**：

```javascript
{
  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 在页面中使用

```javascript
// 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 切换环境

```javascript
// 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层设计 |