235 lines
8.2 KiB
Markdown
235 lines
8.2 KiB
Markdown
# 团课管理系统 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层设计 |
|