plates-server/docs/topic-favorite-api.md

话题收藏功能 API 文档

概述

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

功能特性

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

API 接口

1. 收藏话题

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

请求参数：

{
  "topicId": 123
}

响应示例：

{
  "code": 200,
  "message": "收藏成功",
  "data": {
    "success": true,
    "isFavorited": true,
    "topicId": 123
  }
}

错误情况：

• 话题不存在：{ "code": 400, "message": "话题不存在" }
• 已收藏：{ "code": 200, "message": "已经收藏过该话题" }

2. 取消收藏话题

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

请求参数：

{
  "topicId": 123
}

响应示例：

{
  "code": 200,
  "message": "取消收藏成功",
  "data": {
    "success": true,
    "isFavorited": false,
    "topicId": 123
  }
}

3. 获取收藏话题列表

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

请求参数：

{
  "page": 1,
  "pageSize": 10
}

响应示例：

{
  "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 字段，表示当前用户是否已收藏该话题。

响应示例：

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

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. 用户收藏话题

// 收藏话题
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. 取消收藏话题

// 取消收藏
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. 查看收藏列表

// 获取收藏的话题
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: 服务器内部错误