novalon/gym-manage
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0b2146f2370ed658f0edc9d73936e463cbeb1986
gym-manage/gym-manage-api/docs/groupcourse-recommend-api.md
T
liwentao 7cc9a68144 新增团课推荐功能
2026-06-15 16:43:12 +08:00

12 KiB
Raw Blame History

团课推荐模块 API 文档

文档版本: v1.0
创建日期: 2026-06-15
作者: 张翔
状态: 正式发布

📋 目录

  1. 概述
  2. 基础路径
  3. 团课推荐管理接口
  4. 数据模型
  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):

[
  {
    "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):

[
  {
    "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):

{
  "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):

{}

根据团课ID获取推荐

属性 值
HTTP方法 GET
接口路径 /api/groupCourse/recommend/course/{courseId}
所属文件 GroupCourseRecommendHandler.java

路径参数:

参数名 类型 必填 说明
courseId Long 是 团课ID

成功响应 (200 OK):

[
  {
    "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

请求体:

{
  "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):

{
  "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):

{
  "success": false,
  "message": "团课ID不能为空"
}

更新团课推荐

属性 值
HTTP方法 PUT
接口路径 /api/groupCourse/recommend/{id}
所属文件 GroupCourseRecommendHandler.java

路径参数:

参数名 类型 必填 说明
id Long 是 团课推荐ID

请求体:

{
  "recommendTitle": "本周热门课程（更新）",
  "recommendContent": "更新后的推荐内容",
  "recommendReason": "更新后的推荐理由",
  "priority": 15,
  "isActive": true
}
参数名 类型 必填 说明
courseId Long 否 团课ID
recommendTitle String 否 推荐标题
recommendContent String 否 推荐内容
recommendReason String 否 推荐理由
priority Integer 否 优先级
isActive Boolean 否 是否启用

成功响应 (200 OK):

{
  "success": true,
  "message": "团课推荐更新成功",
  "data": {
    "id": 1,
    "courseId": 1,
    "recommendTitle": "本周热门课程（更新）",
    "recommendContent": "更新后的推荐内容",
    "recommendReason": "更新后的推荐理由",
    "priority": 15,
    "isActive": true,
    "updatedAt": "2026-06-15T12:00:00"
  }
}

失败响应 (400 Bad Request):

{
  "success": false,
  "message": "团课推荐不存在"
}

删除团课推荐

属性 值
HTTP方法 DELETE
接口路径 /api/groupCourse/recommend/{id}
所属文件 GroupCourseRecommendHandler.java

路径参数:

参数名 类型 必填 说明
id Long 是 团课推荐ID

成功响应 (200 OK):

{
  "success": true,
  "message": "团课推荐删除成功"
}

失败响应 (400 Bad Request):

{
  "success": false,
  "message": "团课推荐不存在"
}

启用团课推荐

属性 值
HTTP方法 POST
接口路径 /api/groupCourse/recommend/{id}/enable
所属文件 GroupCourseRecommendHandler.java

路径参数:

参数名 类型 必填 说明
id Long 是 团课推荐ID

成功响应 (200 OK):

{
  "success": true,
  "message": "团课推荐启用成功",
  "data": {
    "id": 1,
    "courseId": 1,
    "recommendTitle": "本周热门课程",
    "isActive": true
  }
}

失败响应 (400 Bad Request):

{
  "success": false,
  "message": "团课推荐不存在"
}

禁用团课推荐

属性 值
HTTP方法 POST
接口路径 /api/groupCourse/recommend/{id}/disable
所属文件 GroupCourseRecommendHandler.java

路径参数:

参数名 类型 必填 说明
id Long 是 团课推荐ID

成功响应 (200 OK):

{
  "success": true,
  "message": "团课推荐禁用成功",
  "data": {
    "id": 1,
    "courseId": 1,
    "recommendTitle": "本周热门课程",
    "isActive": false
  }
}

失败响应 (400 Bad Request):

{
  "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. 状态管理：支持启用/禁用推荐状态，禁用的推荐不会在推荐列表中显示

附录：错误响应格式

所有接口的错误响应统一格式：

{
  "success": false,
  "message": "错误描述信息"
}

文档结束

Reference in New Issue View Git Blame Copy Permalink