230 lines
5.1 KiB
Markdown
230 lines
5.1 KiB
Markdown
# 话题收藏功能 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`: 服务器内部错误 |