# 团课推荐模块 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": "错误描述信息"
}
```

---

*文档结束*