728 lines
15 KiB
Markdown
728 lines
15 KiB
Markdown
# 团课管理模块 API 文档
|
||
|
||
> **文档版本**: v1.0
|
||
> **创建日期**: 2026-06-02
|
||
> **作者**: 张翔
|
||
> **状态**: 正式发布
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [基础路径](#基础路径)
|
||
3. [团课管理接口](#团课管理接口)
|
||
- [获取所有团课](#获取所有团课)
|
||
- [分页获取团课](#分页获取团课)
|
||
- [根据ID获取团课详情](#根据ID获取团课详情)
|
||
- [创建团课](#创建团课)
|
||
- [更新团课](#更新团课)
|
||
- [取消团课](#取消团课)
|
||
- [团课签到](#团课签到)
|
||
- [删除团课](#删除团课)
|
||
4. [团课预约接口](#团课预约接口)
|
||
- [预约团课](#预约团课)
|
||
- [取消预约](#取消预约)
|
||
- [查询会员预约记录](#查询会员预约记录)
|
||
- [查询预约详情](#查询预约详情)
|
||
- [查询课程预约记录](#查询课程预约记录)
|
||
5. [数据模型](#数据模型)
|
||
- [GroupCourse（团课）](#GroupCourse团课)
|
||
- [GroupCourseBooking（团课预约）](#GroupCourseBooking团课预约)
|
||
6. [状态码说明](#状态码说明)
|
||
7. [业务规则](#业务规则)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
团课管理模块提供团课的创建、编辑、查询、取消和签到功能，以及团课预约相关操作。采用 Spring WebFlux 响应式编程，支持高并发场景。
|
||
|
||
## 基础路径
|
||
|
||
所有接口的基础路径为: `http://{host}:{port}/api/groupCourse`
|
||
|
||
---
|
||
|
||
## 团课管理接口
|
||
|
||
### 获取所有团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/list` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| includeDeleted | boolean | 否 | false | 是否包含已删除的团课 |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"courseName": "瑜伽入门",
|
||
"coachId": 1,
|
||
"courseType": 1,
|
||
"startTime": "2026-06-02T09:00:00",
|
||
"endTime": "2026-06-02T10:00:00",
|
||
"maxMembers": 20,
|
||
"currentMembers": 15,
|
||
"status": 0,
|
||
"location": "健身房A区",
|
||
"coverImage": "https://example.com/yoga.jpg",
|
||
"description": "适合初学者的瑜伽课程",
|
||
"createdAt": "2026-06-01T10:00:00",
|
||
"updatedAt": "2026-06-01T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 分页获取团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/page` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"page": 0,
|
||
"size": 10,
|
||
"sort": "id",
|
||
"order": "asc",
|
||
"keyword": "瑜伽"
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| page | int | 否 | 0 | 页码，从0开始 |
|
||
| size | int | 否 | 10 | 每页数量，最大100 |
|
||
| sort | string | 否 | id | 排序字段 |
|
||
| order | string | 否 | asc | 排序方式（asc/desc） |
|
||
| keyword | string | 否 | - | 搜索关键词 |
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| includeDeleted | boolean | 否 | false | 是否包含已删除的团课 |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"data": [...],
|
||
"totalPages": 5,
|
||
"totalElements": 45,
|
||
"page": 0,
|
||
"size": 10
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 根据ID获取团课详情
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/{id}` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"courseName": "瑜伽入门",
|
||
"coachId": 1,
|
||
"courseType": 1,
|
||
"startTime": "2026-06-02T09:00:00",
|
||
"endTime": "2026-06-02T10:00:00",
|
||
"maxMembers": 20,
|
||
"currentMembers": 15,
|
||
"status": 0,
|
||
"location": "健身房A区",
|
||
"coverImage": "https://example.com/yoga.jpg",
|
||
"description": "适合初学者的瑜伽课程",
|
||
"pointCardAmount": 1,
|
||
"storedValueAmount": 50.00,
|
||
"createdAt": "2026-06-01T10:00:00",
|
||
"updatedAt": "2026-06-01T10:00:00"
|
||
}
|
||
```
|
||
|
||
**失败响应** (404 Not Found):
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
---
|
||
|
||
### 创建团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"courseName": "动感单车",
|
||
"coachId": 2,
|
||
"courseType": 2,
|
||
"startTime": "2026-06-05T18:00:00",
|
||
"endTime": "2026-06-05T19:00:00",
|
||
"maxMembers": 25,
|
||
"location": "健身房B区",
|
||
"coverImage": "https://example.com/spinning.jpg",
|
||
"description": "高强度有氧运动课程",
|
||
"pointCardAmount": 1,
|
||
"storedValueAmount": 50.00
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseName | String | **是** | 课程名称 |
|
||
| coachId | Long | 否 | 教练ID |
|
||
| courseType | Long | 否 | 课程类型 |
|
||
| startTime | LocalDateTime | 否 | 开始时间 |
|
||
| endTime | LocalDateTime | 否 | 结束时间 |
|
||
| maxMembers | Integer | 否 | 最大参与人数，默认20 |
|
||
| location | String | 否 | 上课地点 |
|
||
| coverImage | String | 否 | 封面图URL |
|
||
| description | String | 否 | 课程描述 |
|
||
| pointCardAmount | Integer | 否 | 点卡额度（消耗次数），默认1 |
|
||
| storedValueAmount | BigDecimal | 否 | 储值卡额度（消耗金额），默认0 |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课创建成功",
|
||
"data": {
|
||
"id": 2,
|
||
"courseName": "动感单车",
|
||
"coachId": 2,
|
||
"courseType": 2,
|
||
"startTime": "2026-06-05T18:00:00",
|
||
"endTime": "2026-06-05T19:00:00",
|
||
"maxMembers": 25,
|
||
"currentMembers": 0,
|
||
"status": 0,
|
||
"location": "健身房B区",
|
||
"coverImage": "https://example.com/spinning.jpg",
|
||
"description": "高强度有氧运动课程",
|
||
"pointCardAmount": 1,
|
||
"storedValueAmount": 50.00
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "课程名称不能为空"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 更新团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | PUT |
|
||
| **接口路径** | `/api/groupCourse/{id}` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课ID |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"courseName": "动感单车升级版",
|
||
"coachId": 2,
|
||
"maxMembers": 30,
|
||
"description": "升级版高强度有氧运动课程",
|
||
"pointCardAmount": 2,
|
||
"storedValueAmount": 80.00
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseName | String | 否 | 课程名称 |
|
||
| coachId | Long | 否 | 教练ID |
|
||
| courseType | Long | 否 | 课程类型 |
|
||
| startTime | LocalDateTime | 否 | 开始时间 |
|
||
| endTime | LocalDateTime | 否 | 结束时间 |
|
||
| maxMembers | Integer | 否 | 最大参与人数 |
|
||
| location | String | 否 | 上课地点 |
|
||
| coverImage | String | 否 | 封面图URL |
|
||
| description | String | 否 | 课程描述 |
|
||
| pointCardAmount | Integer | 否 | 点卡额度（消耗次数） |
|
||
| storedValueAmount | BigDecimal | 否 | 储值卡额度（消耗金额） |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课更新成功",
|
||
"data": {
|
||
"id": 2,
|
||
"courseName": "动感单车升级版",
|
||
"coachId": 2,
|
||
"maxMembers": 30,
|
||
"description": "升级版高强度有氧运动课程",
|
||
"pointCardAmount": 2,
|
||
"storedValueAmount": 80.00
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "团课不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 取消团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/{id}/cancel` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课取消成功",
|
||
"data": {
|
||
"id": 2,
|
||
"status": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "课程取消需提前24小时"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 团课签到
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/{courseId}/signin` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseId | Long | 是 | 团课ID |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"memberId": 1001
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| memberId | Long | **是** | 会员ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "签到成功",
|
||
"data": {
|
||
"id": 2,
|
||
"currentMembers": 16
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "课程已满员"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 删除团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | DELETE |
|
||
| **接口路径** | `/api/groupCourse/{id}` |
|
||
| **所属文件** | `GroupCourseHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课删除成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 团课预约接口
|
||
|
||
### 预约团课
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/book` |
|
||
| **所属文件** | `GroupCourseBookingHandler.java` |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"courseId": 1,
|
||
"memberId": 1001,
|
||
"memberCardRecordId": 5001
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseId | Long | **是** | 团课ID |
|
||
| memberId | Long | **是** | 会员ID |
|
||
| memberCardRecordId | Long | **是** | 会员卡记录ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "预约成功",
|
||
"data": {
|
||
"id": 100,
|
||
"courseId": 1,
|
||
"memberId": 1001,
|
||
"memberCardRecordId": 5001,
|
||
"bookingTime": "2026-06-02T08:00:00",
|
||
"status": "0"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 取消预约
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/booking/{bookingId}/cancel` |
|
||
| **所属文件** | `GroupCourseBookingHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| bookingId | Long | 是 | 预约ID |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"memberId": 1001
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| memberId | Long | **是** | 会员ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "取消成功",
|
||
"data": {
|
||
"id": 100,
|
||
"status": "1",
|
||
"cancelTime": "2026-06-02T09:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 查询会员预约记录
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/bookings/member/{memberId}` |
|
||
| **所属文件** | `GroupCourseBookingHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| memberId | Long | 是 | 会员ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 100,
|
||
"courseId": 1,
|
||
"courseName": "瑜伽入门",
|
||
"memberId": 1001,
|
||
"memberCardRecordId": 5001,
|
||
"bookingTime": "2026-06-02T08:00:00",
|
||
"status": "0",
|
||
"courseStartTime": "2026-06-02T09:00:00",
|
||
"location": "健身房A区"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 查询预约详情
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/bookings/{bookingId}` |
|
||
| **所属文件** | `GroupCourseBookingHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| bookingId | Long | 是 | 预约ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"id": 100,
|
||
"courseId": 1,
|
||
"courseName": "瑜伽入门",
|
||
"memberId": 1001,
|
||
"memberCardRecordId": 5001,
|
||
"bookingTime": "2026-06-02T08:00:00",
|
||
"status": "0",
|
||
"courseStartTime": "2026-06-02T09:00:00",
|
||
"courseEndTime": "2026-06-02T10:00:00",
|
||
"location": "健身房A区"
|
||
}
|
||
```
|
||
|
||
**失败响应** (404 Not Found):
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
---
|
||
|
||
### 查询课程预约记录
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/bookings/course/{courseId}` |
|
||
| **所属文件** | `GroupCourseBookingHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseId | Long | 是 | 团课ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 100,
|
||
"courseId": 1,
|
||
"courseName": "瑜伽入门",
|
||
"memberId": 1001,
|
||
"bookingTime": "2026-06-02T08:00:00",
|
||
"status": "0"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### GroupCourse（团课）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 主键ID |
|
||
| courseName | String | 课程名称 |
|
||
| coachId | Long | 教练ID |
|
||
| courseType | Long | 课程类型 |
|
||
| startTime | LocalDateTime | 开始时间 |
|
||
| endTime | LocalDateTime | 结束时间 |
|
||
| maxMembers | Integer | 最大参与人数 |
|
||
| currentMembers | Integer | 当前参与人数 |
|
||
| status | Long | 状态（0-正常，1-已取消，2-已结束） |
|
||
| location | String | 上课地点 |
|
||
| coverImage | String | 封面图URL |
|
||
| description | String | 课程描述 |
|
||
| pointCardAmount | Integer | 点卡额度（消耗次数），默认1 |
|
||
| storedValueAmount | BigDecimal | 储值卡额度（消耗金额），默认0 |
|
||
| createdBy | String | 创建人 |
|
||
| updatedBy | String | 更新人 |
|
||
| createdAt | LocalDateTime | 创建时间 |
|
||
| updatedAt | LocalDateTime | 更新时间 |
|
||
| deletedAt | LocalDateTime | 删除时间（软删除） |
|
||
|
||
### GroupCourseBooking（团课预约）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 主键ID |
|
||
| courseId | Long | 团课ID |
|
||
| courseName | String | 团课名称 |
|
||
| memberId | Long | 会员ID |
|
||
| memberCardRecordId | Long | 会员卡记录ID |
|
||
| bookingTime | LocalDateTime | 预约时间 |
|
||
| status | String | 状态（0-已预约，1-已取消，2-已出席，3-缺席） |
|
||
| cancelTime | LocalDateTime | 取消时间 |
|
||
| courseStartTime | LocalDateTime | 课程开始时间 |
|
||
| courseEndTime | LocalDateTime | 课程结束时间 |
|
||
| location | String | 上课地点 |
|
||
| createdBy | String | 创建人 |
|
||
| updatedBy | String | 更新人 |
|
||
| createdAt | LocalDateTime | 创建时间 |
|
||
| updatedAt | LocalDateTime | 更新时间 |
|
||
| deletedAt | LocalDateTime | 删除时间（软删除） |
|
||
|
||
---
|
||
|
||
## 状态码说明
|
||
|
||
### 团课状态
|
||
|
||
| 状态码 | 含义 |
|
||
|--------|------|
|
||
| 0 | 正常 |
|
||
| 1 | 已取消 |
|
||
| 2 | 已结束 |
|
||
|
||
### 预约状态
|
||
|
||
| 状态码 | 含义 |
|
||
|--------|------|
|
||
| 0 | 已预约 |
|
||
| 1 | 已取消 |
|
||
| 2 | 已出席 |
|
||
| 3 | 缺席 |
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
### 团课管理
|
||
1. **创建团课**：课程名称为必填项
|
||
2. **取消团课**：需提前24小时通知，否则拒绝操作
|
||
3. **团课签到**：验证课程状态必须为正常，且未达最大人数限制
|
||
4. **删除团课**：采用软删除机制，数据保留可恢复
|
||
|
||
### 团课预约
|
||
1. **预约团课**：需验证会员卡有效性和课程名额
|
||
2. **取消预约**：需在课程开始前至少2小时取消
|
||
|
||
---
|
||
|
||
## 附录：错误响应格式
|
||
|
||
所有接口的错误响应统一格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述信息"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
*文档结束* |