530 lines
12 KiB
Markdown
530 lines
12 KiB
Markdown
# 团课推荐模块 API 文档
|
||
|
||
> **文档版本**: v1.0
|
||
> **创建日期**: 2026-06-15
|
||
> **作者**: 张翔
|
||
> **状态**: 正式发布
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [基础路径](#基础路径)
|
||
3. [团课推荐管理接口](#团课推荐管理接口)
|
||
- [获取所有团课推荐](#获取所有团课推荐)
|
||
- [获取所有启用的团课推荐](#获取所有启用的团课推荐)
|
||
- [根据ID获取团课推荐](#根据ID获取团课推荐)
|
||
- [根据团课ID获取推荐](#根据团课ID获取推荐)
|
||
- [创建团课推荐](#创建团课推荐)
|
||
- [更新团课推荐](#更新团课推荐)
|
||
- [删除团课推荐](#删除团课推荐)
|
||
- [启用团课推荐](#启用团课推荐)
|
||
- [禁用团课推荐](#禁用团课推荐)
|
||
4. [数据模型](#数据模型)
|
||
- [GroupCourseRecommend（团课推荐）](#GroupCourseRecommend团课推荐)
|
||
5. [状态码说明](#状态码说明)
|
||
6. [业务规则](#业务规则)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
团课推荐模块提供团课推荐信息的创建、编辑、查询、删除和状态管理功能。推荐信息包含团课ID、推荐标题、推荐内容、推荐理由、优先级等必要信息，支持按优先级排序展示。
|
||
|
||
## 基础路径
|
||
|
||
所有接口的基础路径为: `http://{host}:{port}/api/groupCourse/recommend`
|
||
|
||
---
|
||
|
||
## 团课推荐管理接口
|
||
|
||
### 获取所有团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/recommend/list` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| sortBy | string | 否 | priority | 排序字段（支持：priority、createdAt、updatedAt） |
|
||
| sortOrder | string | 否 | desc | 排序方式（asc-升序，desc-降序） |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"recommendContent": "这是一门非常棒的课程，快来参加吧！",
|
||
"recommendReason": "教练专业，课程内容丰富",
|
||
"priority": 10,
|
||
"isActive": true,
|
||
"groupCourse": {
|
||
"id": 1,
|
||
"courseName": "瑜伽入门",
|
||
"coachId": 1,
|
||
"courseType": 1,
|
||
"startTime": "2026-06-15T09:00:00",
|
||
"endTime": "2026-06-15T10:00:00",
|
||
"maxMembers": 20,
|
||
"currentMembers": 15,
|
||
"status": 0,
|
||
"location": "健身房A区",
|
||
"coverImage": "https://example.com/yoga.jpg",
|
||
"description": "适合初学者的瑜伽课程"
|
||
},
|
||
"createdAt": "2026-06-15T10:00:00",
|
||
"updatedAt": "2026-06-15T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 获取所有启用的团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/recommend/active` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**功能说明**: 获取系统中所有已启用的团课推荐列表，按优先级从高到低排序。
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 2,
|
||
"courseId": 3,
|
||
"recommendTitle": "新学员推荐",
|
||
"recommendContent": "专为新学员设计的入门课程，轻松上手",
|
||
"recommendReason": "零基础友好，教练耐心指导",
|
||
"priority": 20,
|
||
"isActive": true,
|
||
"groupCourse": {
|
||
"id": 3,
|
||
"courseName": "基础有氧",
|
||
"coachId": 2,
|
||
"courseType": 2,
|
||
"startTime": "2026-06-16T18:00:00",
|
||
"endTime": "2026-06-16T19:00:00",
|
||
"maxMembers": 30,
|
||
"currentMembers": 8,
|
||
"status": 0,
|
||
"location": "健身房B区",
|
||
"coverImage": "https://example.com/aerobic.jpg",
|
||
"description": "适合所有健身水平的有氧课程"
|
||
},
|
||
"createdAt": "2026-06-15T11:00:00",
|
||
"updatedAt": "2026-06-15T11:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 根据ID获取团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/recommend/{id}` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课推荐ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"recommendContent": "这是一门非常棒的课程，快来参加吧！",
|
||
"recommendReason": "教练专业，课程内容丰富",
|
||
"priority": 10,
|
||
"isActive": true,
|
||
"groupCourse": {
|
||
"id": 1,
|
||
"courseName": "瑜伽入门",
|
||
"coachId": 1,
|
||
"courseType": 1,
|
||
"startTime": "2026-06-15T09:00:00",
|
||
"endTime": "2026-06-15T10:00:00",
|
||
"maxMembers": 20,
|
||
"currentMembers": 15,
|
||
"status": 0,
|
||
"location": "健身房A区",
|
||
"coverImage": "https://example.com/yoga.jpg",
|
||
"description": "适合初学者的瑜伽课程"
|
||
},
|
||
"createdAt": "2026-06-15T10:00:00",
|
||
"updatedAt": "2026-06-15T10:00:00"
|
||
}
|
||
```
|
||
|
||
**失败响应** (404 Not Found):
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
---
|
||
|
||
### 根据团课ID获取推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | GET |
|
||
| **接口路径** | `/api/groupCourse/recommend/course/{courseId}` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseId | Long | 是 | 团课ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"recommendContent": "这是一门非常棒的课程，快来参加吧！",
|
||
"recommendReason": "教练专业，课程内容丰富",
|
||
"priority": 10,
|
||
"isActive": true,
|
||
"groupCourse": {
|
||
"id": 1,
|
||
"courseName": "瑜伽入门",
|
||
"coachId": 1,
|
||
"courseType": 1,
|
||
"startTime": "2026-06-15T09:00:00",
|
||
"endTime": "2026-06-15T10:00:00",
|
||
"maxMembers": 20,
|
||
"currentMembers": 15,
|
||
"status": 0,
|
||
"location": "健身房A区"
|
||
},
|
||
"createdAt": "2026-06-15T10:00:00",
|
||
"updatedAt": "2026-06-15T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 创建团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/recommend` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"recommendContent": "这是一门非常棒的课程，快来参加吧！",
|
||
"recommendReason": "教练专业，课程内容丰富",
|
||
"priority": 10,
|
||
"isActive": true
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| courseId | Long | **是** | - | 团课ID（必须是有效的团课） |
|
||
| recommendTitle | String | 否 | - | 推荐标题 |
|
||
| recommendContent | String | 否 | - | 推荐内容 |
|
||
| recommendReason | String | 否 | - | 推荐理由 |
|
||
| priority | Integer | 否 | 0 | 优先级（数字越大优先级越高） |
|
||
| isActive | Boolean | 否 | true | 是否启用 |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课推荐创建成功",
|
||
"data": {
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"recommendContent": "这是一门非常棒的课程，快来参加吧！",
|
||
"recommendReason": "教练专业，课程内容丰富",
|
||
"priority": 10,
|
||
"isActive": true,
|
||
"createdAt": "2026-06-15T10:00:00",
|
||
"updatedAt": "2026-06-15T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "团课ID不能为空"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 更新团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | PUT |
|
||
| **接口路径** | `/api/groupCourse/recommend/{id}` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课推荐ID |
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"recommendTitle": "本周热门课程（更新）",
|
||
"recommendContent": "更新后的推荐内容",
|
||
"recommendReason": "更新后的推荐理由",
|
||
"priority": 15,
|
||
"isActive": true
|
||
}
|
||
```
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| courseId | Long | 否 | 团课ID |
|
||
| recommendTitle | String | 否 | 推荐标题 |
|
||
| recommendContent | String | 否 | 推荐内容 |
|
||
| recommendReason | String | 否 | 推荐理由 |
|
||
| priority | Integer | 否 | 优先级 |
|
||
| isActive | Boolean | 否 | 是否启用 |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课推荐更新成功",
|
||
"data": {
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程（更新）",
|
||
"recommendContent": "更新后的推荐内容",
|
||
"recommendReason": "更新后的推荐理由",
|
||
"priority": 15,
|
||
"isActive": true,
|
||
"updatedAt": "2026-06-15T12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "团课推荐不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 删除团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | DELETE |
|
||
| **接口路径** | `/api/groupCourse/recommend/{id}` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课推荐ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课推荐删除成功"
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "团课推荐不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 启用团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/recommend/{id}/enable` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课推荐ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课推荐启用成功",
|
||
"data": {
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"isActive": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "团课推荐不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 禁用团课推荐
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **HTTP方法** | POST |
|
||
| **接口路径** | `/api/groupCourse/recommend/{id}/disable` |
|
||
| **所属文件** | `GroupCourseRecommendHandler.java` |
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 团课推荐ID |
|
||
|
||
**成功响应** (200 OK):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "团课推荐禁用成功",
|
||
"data": {
|
||
"id": 1,
|
||
"courseId": 1,
|
||
"recommendTitle": "本周热门课程",
|
||
"isActive": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400 Bad Request):
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "团课推荐不存在"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### GroupCourseRecommend（团课推荐）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 主键ID |
|
||
| courseId | Long | 团课ID（关联group_course.id） |
|
||
| recommendTitle | String | 推荐标题 |
|
||
| recommendContent | String | 推荐内容 |
|
||
| recommendReason | String | 推荐理由 |
|
||
| priority | Integer | 优先级（数字越大优先级越高），默认0 |
|
||
| isActive | Boolean | 是否启用，默认true |
|
||
| groupCourse | GroupCourse | 关联的团课信息（查询时自动填充） |
|
||
| createdBy | String | 创建人 |
|
||
| updatedBy | String | 更新人 |
|
||
| createdAt | LocalDateTime | 创建时间 |
|
||
| updatedAt | LocalDateTime | 更新时间 |
|
||
| deletedAt | LocalDateTime | 删除时间（软删除） |
|
||
|
||
---
|
||
|
||
## 状态码说明
|
||
|
||
### 推荐状态
|
||
|
||
| 状态值 | 含义 |
|
||
|--------|------|
|
||
| true | 启用 |
|
||
| false | 禁用 |
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
### 团课推荐管理
|
||
1. **创建推荐**：团课ID为必填项，且必须是有效的团课
|
||
2. **优先级排序**：获取启用的推荐列表时，按优先级从高到低排序
|
||
3. **删除推荐**：采用软删除机制，数据保留可恢复
|
||
4. **状态管理**：支持启用/禁用推荐状态，禁用的推荐不会在推荐列表中显示
|
||
|
||
---
|
||
|
||
## 附录：错误响应格式
|
||
|
||
所有接口的错误响应统一格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述信息"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
*文档结束* |