feat: 初始化项目
This commit is contained in:
richarjiang
230
docs/topic-favorite-api.md
Normal file
230
docs/topic-favorite-api.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 话题收藏功能 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`: 服务器内部错误
|
||||
Reference in New Issue
Block a user