# 话题收藏功能 API 文档

## 概述

话题收藏功能允许用户收藏喜欢的话题，方便后续查看和使用。本文档描述了话题收藏相关的所有API接口。

## 功能特性

- ✅ 收藏话题
- ✅ 取消收藏话题
- ✅ 获取收藏话题列表
- ✅ 话题列表中显示收藏状态
- ✅ 防重复收藏
- ✅ 完整的错误处理

## API 接口

### 1. 收藏话题

**接口地址：** `POST /api/topic/favorite`

**请求参数：**
```json
{
  "topicId": 123
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "收藏成功",
  "data": {
    "success": true,
    "isFavorited": true,
    "topicId": 123
  }
}
```

**错误情况：**
- 话题不存在：`{ "code": 400, "message": "话题不存在" }`
- 已收藏：`{ "code": 200, "message": "已经收藏过该话题" }`

### 2. 取消收藏话题

**接口地址：** `POST /api/topic/unfavorite`

**请求参数：**
```json
{
  "topicId": 123
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "取消收藏成功",
  "data": {
    "success": true,
    "isFavorited": false,
    "topicId": 123
  }
}
```

### 3. 获取收藏话题列表

**接口地址：** `POST /api/topic/favorites`

**请求参数：**
```json
{
  "page": 1,
  "pageSize": 10
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 123,
        "topic": "约会话题",
        "opening": {
          "text": "今天天气真不错...",
          "scenarios": ["咖啡厅", "公园"]
        },
        "scriptType": "初识破冰",
        "scriptTopic": "天气",
        "keywords": "天气,约会,轻松",
        "isFavorited": true,
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 10
  }
}
```

### 4. 获取话题列表（已包含收藏状态）

**接口地址：** `POST /api/topic/list`

现在所有话题列表都会包含 `isFavorited` 字段，表示当前用户是否已收藏该话题。

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 123,
        "topic": "约会话题",
        "opening": {
          "text": "今天天气真不错...",
          "scenarios": ["咖啡厅", "公园"]
        },
        "scriptType": "初识破冰",
        "scriptTopic": "天气",
        "keywords": "天气,约会,轻松",
        "isFavorited": true,  // ← 新增的收藏状态字段
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      },
      {
        "id": 124,
        "topic": "工作话题",
        "opening": "关于工作的开场白...",
        "scriptType": "深度交流",
        "scriptTopic": "职业",
        "keywords": "工作,职业,发展",
        "isFavorited": false,  // ← 未收藏
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 20,
    "page": 1,
    "pageSize": 10
  }
}
```

## 数据库变更

### 新增表：t_topic_favorites

```sql
CREATE TABLE `t_topic_favorites` (
  `id` int NOT NULL AUTO_INCREMENT,
  `user_id` varchar(255) NOT NULL COMMENT '用户ID',
  `topic_id` int NOT NULL COMMENT '话题ID',
  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
  `updated_at` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `unique_user_topic_favorite` (`user_id`, `topic_id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_topic_id` (`topic_id`),
  FOREIGN KEY (`user_id`) REFERENCES `t_users` (`id`) ON DELETE CASCADE,
  FOREIGN KEY (`topic_id`) REFERENCES `t_topic_library` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

## 使用场景

### 1. 用户收藏话题
```javascript
// 收藏话题
const response = await fetch('/api/topic/favorite', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-jwt-token'
  },
  body: JSON.stringify({ topicId: 123 })
});
```

### 2. 取消收藏话题
```javascript
// 取消收藏
const response = await fetch('/api/topic/unfavorite', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-jwt-token'
  },
  body: JSON.stringify({ topicId: 123 })
});
```

### 3. 查看收藏列表
```javascript
// 获取收藏的话题
const response = await fetch('/api/topic/favorites', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-jwt-token'
  },
  body: JSON.stringify({ page: 1, pageSize: 10 })
});
```

## 注意事项

1. **防重复收藏：** 数据库层面通过唯一索引保证同一用户不能重复收藏同一话题
2. **级联删除：** 用户删除或话题删除时，相关收藏记录会自动删除
3. **性能优化：** 获取话题列表时通过单次查询获取用户所有收藏状态，避免N+1查询问题
4. **权限控制：** 所有接口都需要用户登录（JWT认证）

## 错误码说明

- `200`: 操作成功
- `400`: 请求参数错误（如话题不存在）
- `401`: 未授权（需要登录）
- `500`: 服务器内部错误