seer-teach-cloud-21/docs/activity-carousel-api-documentation.md

# 活动轮播图功能接口文档

本文档详细描述了活动轮播图功能的所有接口。

## 1. 管理端接口

### 1.1 获取活动轮播图列表

- **接口路径**: `POST /seer/admin/mp/activity-carousel/page-list`
- **功能描述**: 分页获取活动轮播图列表
- **权限要求**: `mp:admin:activity:carousel:list`
- **请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Integer | 否 | 活动ID |
| isActive | Boolean | 否 | 激活状态 |
| title | String | 否 | 标题 |
| pageNum | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页数量 |

- **请求示例**:
```json
{
  "activityId": 1,
  "isActive": true,
  "title": "轮播图",
  "pageNum": 1,
  "pageSize": 10
}
```

- **响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 1,
    "list": [
      {
        "id": 1,
        "imageUrl": "https://example.com/image.jpg",
        "linkUrl": "https://example.com/link",
        "title": "轮播图标题",
        "description": "轮播图描述",
        "sortOrder": 1,
        "isActive": true,
        "activityId": 1,
        "createTime": "2026-01-30 10:00:00",
        "updateTime": "2026-01-30 10:00:00"
      }
    ]
  }
}
```

### 1.2 创建或更新活动轮播图

- **接口路径**: `POST /seer/admin/mp/activity-carousel/save`
- **功能描述**: 创建或更新活动轮播图
- **权限要求**: `mp:admin:activity:carousel:save`
- **请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Integer | 否 | 轮播图ID，不传表示新增 |
| imageUrl | String | 是 | 图片地址 |
| linkUrl | String | 否 | 跳转链接 |
| title | String | 否 | 标题 |
| description | String | 否 | 描述/替代文本 |
| sortOrder | Integer | 是 | 排序值 |
| isActive | Boolean | 是 | 激活状态：true-显示，false-隐藏 |
| activityId | Integer | 是 | 关联活动ID |

- **请求示例**:
```json
{
  "imageUrl": "https://example.com/image.jpg",
  "linkUrl": "https://example.com/link",
  "title": "轮播图标题",
  "description": "轮播图描述",
  "sortOrder": 1,
  "isActive": true,
  "activityId": 1
}
```

- **响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": true
}
```

### 1.3 删除活动轮播图

- **接口路径**: `DELETE /seer/admin/mp/activity-carousel/{id}`
- **功能描述**: 删除指定ID的活动轮播图
- **权限要求**: `mp:admin:activity:carousel:delete`
- **路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Integer | 是 | 轮播图ID |

- **响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": true
}
```

### 1.4 获取活动轮播图详情

- **接口路径**: `GET /seer/admin/mp/activity-carousel/{id}`
- **功能描述**: 获取指定ID的活动轮播图详情
- **权限要求**: `mp:admin:activity:carousel:get`
- **路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Integer | 是 | 轮播图ID |

- **响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "imageUrl": "https://example.com/image.jpg",
    "linkUrl": "https://example.com/link",
    "title": "轮播图标题",
    "description": "轮播图描述",
    "sortOrder": 1,
    "isActive": true,
    "activityId": 1,
    "createTime": "2026-01-30 10:00:00",
    "updateTime": "2026-01-30 10:00:00"
  }
}
```

### 1.5 根据活动ID获取轮播图列表

- **接口路径**: `GET /seer/admin/mp/activity-carousel/activity/{activityId}`
- **功能描述**: 根据活动ID获取轮播图列表
- **权限要求**: `mp:admin:activity:carousel:list`
- **路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Integer | 是 | 活动ID |

- **响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "imageUrl": "https://example.com/image.jpg",
      "linkUrl": "https://example.com/link",
      "title": "轮播图标题",
      "description": "轮播图描述",
      "sortOrder": 1,
      "isActive": true,
      "activityId": 1,
      "createTime": "2026-01-30 10:00:00",
      "updateTime": "2026-01-30 10:00:00"
    }
  ]
}
```

## 2. 应用端接口

### 2.1 根据活动ID获取激活的轮播图列表

- **接口路径**: `GET /seer/admin/mp/app/activity-carousel/activity/{activityId}`
- **功能描述**: 根据活动ID获取激活的轮播图列表，仅返回激活状态为true的轮播图，并按排序值升序排列
- **请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Integer | 是 | 活动ID |

- **响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "imageUrl": "https://example.com/image.jpg",
      "linkUrl": "https://example.com/link",
      "title": "轮播图标题",
      "description": "轮播图描述",
      "sortOrder": 1,
      "isActive": true,
      "activityId": 1,
      "createTime": "2026-01-30 10:00:00",
      "updateTime": "2026-01-30 10:00:00"
    }
  ]
}
```