tuituiProject

我的书架模块开发文档

---

一、文档说明

1. 书架模块概述

   • 书架模块是用户管理已订阅或收藏小说的核心功能模块。它不仅提供了获取书架列表、小说详情、更新判断等基础功能，还支持置顶、取消置顶、从书架移除以及订阅等操作。
   • 设计时需考虑扩展性和性能优化，确保在高并发场景下的稳定性和响应速度。

2. 本期产品原型图（部分）
   

---

二、亮点和难点说明

亮点

• 排序规则：支持按更新时间和订阅时间两种排序方式，提升用户体验。
• 时间显示优化：根据更新时间与当前时间的差值动态生成display_time字段，提供更直观的时间描述。
• 订阅数量限制：用户最多可订阅五本小说，避免过度占用资源。

---

三、数据表设计

1. 用户书架表 xiaozhaoVIP_user_bookshelf

字段名	类型	默认值	备注
id	int(11)		主键
status	tinyint(2)	1	状态 (1-有效, 0-无效)
addTime	datetime	CURRENT_TIMESTAMP	添加时间
updateTime	datetime	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	更新时间
UserId	int(11)		用户ID
NovelId	int(11)		小说ID
IsTop	tinyint(1)	0	是否置顶 (0-否, 1-是)
SubscribeTime	datetime		订阅时间
IsRead	tinyint(1)	0	是否已读 (0-否, 1-是)

2. 小说介绍表 xiaozhaoVIP_novel_detail

字段名	类型	默认值	备注
id	int(11)		主键
status	tinyint(2)	1	状态 (1-有效, 0-无效)
addTime	datetime	CURRENT_TIMESTAMP	添加时间
updateTime	datetime	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	更新时间
Name	varchar(50)		小说名称
AuthorId	int(11)		作者ID
AuthorName	varchar(20)		作者名
Status	tinyint(2)	0	0-无效 1-有效
Type	int(11)		类型
LatestUpdateTime	datetime		最后更新时间
ChapterName	varchar(50)		最新章节名称
Cover	varchar(50)		封面
SubscribeNum	int(11)		订阅数
AddTime	datetime		添加时间

3. 小说订阅表 xiaozhaoVIP_novel_subscribe

字段名	类型	默认值	备注
id	int(11)		主键
status	tinyint(2)	1	状态 (1-有效, 0-无效)
addTime	datetime	CURRENT_TIMESTAMP	添加时间
updateTime	datetime	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	更新时间
UserId	int(11)		用户ID
NovelId	int(11)		小说ID
Status	tinyint(2)	0	0-无效 1-有效
AddTime	datetime		添加时间

四、服务设计

1. 增加排序枚举

(1) 排序规则枚举 SortTypeEnum

public enum SortTypeEnum {
    UPDATE_TIME(1, "update_time", "按更新时间排序"),
    SUBSCRIBE_TIME(2, "subscribe_time", "按订阅时间排序");

    private final int code;
    private final String value;
    private final String description;

    SortTypeEnum(int code, String value, String description) {
        this.code = code;
        this.value = value;
        this.description = description;
    }

    public int getCode() {
        return code;
    }

    public String getValue() {
        return value;
    }

    public String getDescription() {
        return description;
    }
}

---

五、接口设计

1. 获取书架列表

• 接口名称: 获取书架列表
• 接口路径: /api/bookshelf
• 请求方法: GET
• 描述: 获取当前用户的书架列表，支持排序规则。

请求参数

参数名	类型	是否必填	描述	默认值
sort	String	否	排序规则	update_time
			可选值：update_time（按更新时间排序），subscribe_time（按订阅时间排序）

返回结果

• 状态码: 200
• 返回格式: JSON

返回参数说明

{
  "success": true,
  "msg": "success",
  "data": {
    "novels": [
      {
        "id": int,               // 小说ID
        "name": String,          // 小说名称
        "is_top": boolean,       // 是否置顶
        "update_time": int,      // 更新时间（时间戳）
        "display_time": String   // 显示的时间描述（如：3天前）
      },
      ...
    ]
  }
}

示例请求

• 请求URL: /api/bookshelf?sort=update_time
• 请求方法: GET

示例响应

{
  "success": true,
  "msg": "success",
  "data": {
    "novels": [
      {
        "id": 1,
        "name": "小说名称1",
        "is_top": false,
        "update_time": 1634688000,
        "display_time": "3天前"
      },
      {
        "id": 2,
        "name": "小说名称2",
        "is_top": true,
        "update_time": 1634774400,
        "display_time": "20分钟前"
      }
    ]
  }
}

2. 置顶小说

• 接口名称: 置顶小说
• 接口路径: /api/bookshelf/top
• 请求方法: POST
• 描述: 将指定小说置顶。

请求参数

参数名	类型	是否必填	描述
novelId	int	是	小说ID

返回结果

• 状态码: 200
• 返回格式: JSON

返回参数说明

{
  "success": boolean,            // 操作是否成功
  "msg": String                  // 操作信息
}

示例请求

• 请求URL: /api/bookshelf/top
• 请求方法: POST
• 请求体:

  {
    "novelId": 2
  }

示例响应

{
  "success": true,
  "msg": "success"
}

3. 取消置顶小说

• 接口名称: 取消置顶小说
• 接口路径: /api/bookshelf/untop
• 请求方法: POST
• 描述: 取消指定小说的置顶状态。

请求参数

参数名	类型	是否必填	描述
novelId	int	是	小说ID

返回结果

• 状态码: 200
• 返回格式: JSON

返回参数说明

{
  "success": boolean,            // 操作是否成功
  "msg": String                  // 操作信息
}

示例请求

• 请求URL: /api/bookshelf/untop
• 请求方法: POST
• 请求体:

  {
    "novelId": 2
  }

示例响应

{
  "success": true,
  "msg": "success"
}

4. 从书架移除小说

• 接口名称: 从书架移除小说
• 接口路径: /api/bookshelf/remove
• 请求方法: POST
• 描述: 从书架中移除指定小说。

请求参数

参数名	类型	是否必填	描述
novelId	int	是	小说ID

返回结果

• 状态码: 200
• 返回格式: JSON

返回参数说明

{
  "success": boolean,            // 操作是否成功
  "msg": String                  // 操作信息
}

示例请求

• 请求URL: /api/bookshelf/remove
• 请求方法: POST
• 请求体:

  {
    "novelId": 2
  }

示例响应

{
  "success": true,
  "msg": "success"
}

5. 订阅小说

• 接口名称: 订阅小说
• 接口路径: /api/bookshelf/subscribe
• 请求方法: POST
• 描述: 订阅指定小说。用户最多可订阅五本小说。

请求参数

参数名	类型	是否必填	描述
novelId	int	是	小说ID

返回结果

• 状态码: 200
• 返回格式: JSON

返回参数说明

{
  "success": boolean,            // 操作是否成功
  "msg": String                  // 操作信息
}

示例请求

• 请求URL: /api/bookshelf/subscribe
• 请求方法: POST
• 请求体:

  {
    "novelId": 2
  }

示例响应

{
  "success": true,
  "msg": "success"
}

是否到达最大订阅数的接口

• 接口名称: 检查是否达到最大订阅数
• 接口路径: /api/bookshelf/check-subscribe-limit
• 请求方法: GET
• 描述: 检查当前用户是否已达到最大订阅数（5本小说）。
• 请求参数: 无
• 返回结果:

  {
    "success": boolean,
    "msg": String,
    "data": {
      "is_limit_reached": boolean
    }
  }

注意事项

• 如果用户已订阅五本小说，则无法再订阅新的小说，返回相应的错误信息。
• 订阅状态会在用户订阅和取消订阅时更新。

---

6. 书架的未读和已读设计

• 功能描述: 用户可以标记小说为已读或未读状态，以便更好地管理自己的阅读进度。

• 数据表设计: 在xiaozhaoVIP_user_bookshelf表中字段IsRead，用于标识小说是否已读。

  字段名	类型	默认值	备注
  IsRead	tinyint(1)	0	是否已读 (0-否, 1-是)

• 接口设计:

  • 标记为已读
    • 接口名称: 标记小说为已读
    • 接口路径: /api/bookshelf/mark-read
    • 请求方法: POST
    • 请求参数:

      参数名	类型	是否必填	描述
      novelId	int	是	小说ID

    • 返回结果:

      {
        "success": boolean,
        "msg": String
      }

  • 标记为未读
    • 接口名称: 标记小说为未读
    • 接口路径: /api/bookshelf/mark-unread
    • 请求方法: POST
    • 请求参数:

      参数名	类型	是否必填	描述
      novelId	int	是	小说ID

    • 返回结果:

      {
        "success": boolean,
        "msg": String
      }

7. 置顶和列表的拉取接口

• 接口名称: 获取书架列表（已包含置顶逻辑）
• 接口路径: /api/bookshelf
• 请求方法: GET
• 描述: 获取当前用户的书架列表，支持排序规则，并区分置顶小说。
• 请求参数:

  参数名	类型	是否必填	描述	默认值
  sort	String	否	排序规则	update_time
  			可选值：update_time（按更新时间排序），subscribe_time（按订阅时间排序）

• 返回结果:

  {
    "success": true,
    "msg": "success",
    "data": {
      "novels": [
        {
          "id": int,
          "name": String,
          "is_top": boolean,
          "is_read": boolean,
          "update_time": int,
          "display_time": String
        },
        ...
      ]
    }
  }