完成团课列表页面布局以及基础交互，使用测试数据
This commit is contained in:
@@ -0,0 +1,234 @@
|
||||
# 团课管理系统 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层设计 |
|
||||
Reference in New Issue
Block a user