# 内容管理系统

<cite>
**本文引用的文件**
- [server\src\modules\search\search.service.ts](file://server\src\modules\search\search.service.ts)
- [server\src\modules\search\search.controller.ts](file://server\src\modules\search\search.controller.ts)
- [server\prisma\schema.prisma](file://server\prisma\schema.prisma)
- [server\src\models\index.ts](file://server\src\models\index.ts)
- [server\src\modules\history\history.controller.ts](file://server\src\modules\history\history.controller.ts)
- [server\src\modules\history\history-batch.controller.ts](file://server\src\modules\history\history-batch.controller.ts)
- [server\src\modules\comments\comments.service.ts](file://server\src\modules\comments\comments.service.ts)
- [server\src\modules\comments\comments.controller.ts](file://server\src\modules\comments\comments.controller.ts)
- [server\src\modules\favorites\favorites.service.ts](file://server\src\modules\favorites\favorites.service.ts)
- [server\src\modules\categories\categories.service.ts](file://server\src\modules\categories\categories.service.ts)
- [server\src\middleware\cache.ts](file://server\src\middleware\cache.ts)
- [server\src\services\redis.service.ts](file://server\src\services\redis.service.ts)
- [server\src\modules\preferences\preferences.service.ts](file://server\src\modules\preferences\preferences.service.ts)
- [my-uniapp-vue3\src\pages\favorites\index.vue](file://my-uniapp-vue3\src\pages\favorites\index.vue)
- [server\src\middleware\errorHandler.js](file://server\src\middleware\errorHandler.js)
- [server\src\services\log.service.ts](file://server\src\services\log.service.ts)
- [feature_list_optimization.json](file://feature_list_optimization.json)
- [feature_list_content_generate.json](file://feature_list_content_generate.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本技术文档面向内容管理系统（音频/有声书方向），围绕收藏、历史记录、评论系统、搜索与索引、内容分类与标签、推荐与个性化、用户行为追踪与分析、审核与版权保护、缓存与CDN、静态资源管理、扩展开发与监控等主题，提供从架构到实现细节的系统化说明，并配套API接口文档与数据模型说明。

## 项目结构
后端采用 Koa + Prisma 架构，模块化组织业务功能；前端基于 uniapp-vue3。核心模块包括搜索、历史、评论、收藏、分类、偏好设置、缓存中间件与 Redis 服务等。

```mermaid
graph TB
subgraph "前端"
FE_Favorites["收藏页面<br/>favorites/index.vue"]
end
subgraph "后端"
API_Search["搜索控制器<br/>search.controller.ts"]
API_History["历史控制器<br/>history.controller.ts"]
API_Comments["评论控制器<br/>comments.controller.ts"]
API_Favorites["收藏服务<br/>favorites.service.ts"]
API_Categories["分类服务<br/>categories.service.ts"]
API_Preferences["偏好服务<br/>preferences.service.ts"]
Svc_Search["搜索服务<br/>search.service.ts"]
Svc_History["历史服务<br/>history.controller.ts"]
Svc_Comments["评论服务<br/>comments.service.ts"]
Svc_Favorites["收藏服务<br/>favorites.service.ts"]
Svc_Categories["分类服务<br/>categories.service.ts"]
Svc_Preferences["偏好服务<br/>preferences.service.ts"]
MW_Cache["缓存中间件<br/>cache.ts"]
Svc_Redis["Redis 服务<br/>redis.service.ts"]
DB_Schema["Prisma Schema<br/>schema.prisma"]
DB_Connect["数据库连接<br/>models/index.ts"]
end
FE_Favorites --> API_Favorites
API_Search --> Svc_Search
API_History --> Svc_History
API_Comments --> Svc_Comments
API_Favorites --> Svc_Favorites
API_Categories --> Svc_Categories
API_Preferences --> Svc_Preferences
Svc_Search --> DB_Schema
Svc_History --> DB_Schema
Svc_Comments --> DB_Schema
Svc_Favorites --> DB_Schema
Svc_Categories --> DB_Schema
Svc_Preferences --> DB_Schema
MW_Cache --> Svc_Redis
Svc_Redis --> DB_Schema
DB_Connect --> DB_Schema
```

图表来源
- [server\src\modules\search\search.controller.ts:1-170](file://server\src\modules\search\search.controller.ts#L1-L170)
- [server\src\modules\history\history.controller.ts:1-67](file://server\src\modules\history\history.controller.ts#L1-L67)
- [server\src\modules\comments\comments.controller.ts:1-58](file://server\src\modules\comments\comments.controller.ts#L1-L58)
- [server\src\modules\favorites\favorites.service.ts:1-103](file://server\src\modules\favorites\favorites.service.ts#L1-L103)
- [server\src\modules\categories\categories.service.ts:1-65](file://server\src\modules\categories\categories.service.ts#L1-L65)
- [server\src\modules\preferences\preferences.service.ts:1-74](file://server\src\modules\preferences\preferences.service.ts#L1-L74)
- [server\src\middleware\cache.ts:1-98](file://server\src\middleware\cache.ts#L1-L98)
- [server\src\services\redis.service.ts:1-274](file://server\src\services\redis.service.ts#L1-L274)
- [server\prisma\schema.prisma:1-472](file://server\prisma\schema.prisma#L1-L472)
- [server\src\models\index.ts:1-15](file://server\src\models\index.ts#L1-L15)

章节来源
- [server\src\modules\search\search.controller.ts:1-170](file://server\src\modules\search\search.controller.ts#L1-L170)
- [server\src\modules\history\history.controller.ts:1-67](file://server\src\modules\history\history.controller.ts#L1-L67)
- [server\src\modules\comments\comments.controller.ts:1-58](file://server\src\modules\comments\comments.controller.ts#L1-L58)
- [server\src\modules\search\search.service.ts:1-145](file://server\src\modules\search\search.service.ts#L1-L145)
- [server\prisma\schema.prisma:1-472](file://server\prisma\schema.prisma#L1-L472)

## 核心组件
- 搜索与索引：提供全局搜索、热门词、搜索历史持久化与去重、历史上限控制与热门词计数更新。
- 历史记录：分页查询音频生成历史，支持批量删除。
- 评论系统：按章节获取评论、添加评论。
- 收藏功能：用户对书籍的收藏、取消收藏、查询收藏列表、判断是否已收藏。
- 分类与标签：音频分类（当前返回默认分类映射）、分类标签映射。
- 偏好设置：播放速度、音质、主题、默认音色、音量、自动下一首、仅WiFi下载等。
- 缓存与Redis：统一缓存中间件、常用键空间、失效策略。
- 错误处理与日志：通用错误中间件、日志清理与智能建议。

章节来源
- [server\src\modules\search\search.service.ts:1-145](file://server\src\modules\search\search.service.ts#L1-L145)
- [server\src\modules\history\history.controller.ts:1-67](file://server\src\modules\history\history.controller.ts#L1-L67)
- [server\src\modules\history\history-batch.controller.ts:1-105](file://server\src\modules\history\history-batch.controller.ts#L1-L105)
- [server\src\modules\comments\comments.service.ts:1-32](file://server\src\modules\comments\comments.service.ts#L1-L32)
- [server\src\modules\comments\comments.controller.ts:1-58](file://server\src\modules\comments\comments.controller.ts#L1-L58)
- [server\src\modules\favorites\favorites.service.ts:1-103](file://server\src\modules\favorites\favorites.service.ts#L1-L103)
- [server\src\modules\categories\categories.service.ts:1-65](file://server\src\modules\categories\categories.service.ts#L1-L65)
- [server\src\modules\preferences\preferences.service.ts:1-74](file://server\src\modules\preferences\preferences.service.ts#L1-L74)
- [server\src\middleware\cache.ts:1-98](file://server\src\middleware\cache.ts#L1-L98)
- [server\src\services\redis.service.ts:1-274](file://server\src\services\redis.service.ts#L1-L274)
- [server\src\middleware\errorHandler.js:1-24](file://server\src\middleware\errorHandler.js#L1-L24)
- [server\src\services\log.service.ts:277-315](file://server\src\services\log.service.ts#L277-L315)

## 架构总览
系统采用前后端分离，后端以 Koa 路由聚合各模块服务，数据访问通过 Prisma ORM，缓存层基于 Redis。前端 uniapp-vue3 通过 HTTP API 与后端交互。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "Koa 路由"
participant Ctrl as "控制器"
participant Svc as "服务层"
participant Prisma as "Prisma ORM"
participant DB as "MySQL"
Client->>Router : "HTTP 请求"
Router->>Ctrl : "路由分发"
Ctrl->>Svc : "调用业务方法"
Svc->>Prisma : "构建查询/写入"
Prisma->>DB : "SQL 执行"
DB-->>Prisma : "结果集"
Prisma-->>Svc : "实体/集合"
Svc-->>Ctrl : "业务结果"
Ctrl-->>Client : "JSON 响应"
```

图表来源
- [server\src\modules\search\search.controller.ts:1-170](file://server\src\modules\search\search.controller.ts#L1-L170)
- [server\src\modules\search\search.service.ts:1-145](file://server\src\modules\search\search.service.ts#L1-L145)
- [server\prisma\schema.prisma:1-472](file://server\prisma\schema.prisma#L1-L472)

## 详细组件分析

### 搜索与索引
- 功能要点
  - 全局搜索：按标题或描述模糊匹配，按创建时间倒序，限制返回条数。
  - 热门搜索词：多字段排序，限制返回条数。
  - 搜索历史：按用户去重、保留最新记录、限制最大条数；同时更新热门词计数。
  - 历史清理：支持按用户清空、按关键词删除单条。
- 索引策略
  - 搜索关键词在标题/描述上具备模糊匹配能力；热门词与搜索历史具备复合索引，保证查询效率。
- 排序算法
  - 热门词优先级：先按 sort 降序，再按 count 降序；搜索结果按创建时间倒序。
- 前端优化
  - 搜索结果关键词高亮（前端特性清单中已确认）。

```mermaid
flowchart TD
Start(["开始"]) --> QEmpty{"关键词为空？"}
QEmpty --> |是| ReturnEmpty["返回空结果"]
QEmpty --> |否| BuildQuery["构造模糊查询<br/>标题/描述 contains"]
BuildQuery --> ExecFind["执行查询并排序"]
ExecFind --> Limit["限制返回条数"]
Limit --> ReturnResults["返回结果"]
subgraph "历史与热门词"
SaveHist["保存历史<br/>去重+上限控制"]
UpdateHot["更新热门词计数"]
SaveHist --> UpdateHot
end
```

图表来源
- [server\src\modules\search\search.service.ts:13-141](file://server\src\modules\search\search.service.ts#L13-L141)
- [server\prisma\schema.prisma:222-242](file://server\prisma\schema.prisma#L222-L242)

章节来源
- [server\src\modules\search\search.service.ts:1-145](file://server\src\modules\search\search.service.ts#L1-L145)
- [server\src\modules\search\search.controller.ts:1-170](file://server\src\modules\search\search.controller.ts#L1-L170)
- [server\prisma\schema.prisma:222-242](file://server\prisma\schema.prisma#L222-L242)
- [feature_list_optimization.json:1-39](file://feature_list_optimization.json#L1-L39)

### 历史记录管理
- 功能要点
  - 分页查询音频生成历史，支持按起始日期过滤。
  - 批量删除历史记录（POST/DELETE 兼容）。
- 数据模型
  - 历史记录存储于 AudioRecord，包含音频标识、标题、文本、时长、大小、状态、语音参数、关联书籍等。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "历史路由"
participant Ctrl as "历史控制器"
participant Prisma as "Prisma"
participant DB as "MySQL"
Client->>Router : "GET /api/history?page=...&pageSize=..."
Router->>Ctrl : "解析分页与过滤条件"
Ctrl->>Prisma : "查询记录+总数"
Prisma->>DB : "SQL 查询"
DB-->>Prisma : "记录集"
Prisma-->>Ctrl : "组装列表"
Ctrl-->>Client : "分页结果"
```

图表来源
- [server\src\modules\history\history.controller.ts:10-64](file://server\src\modules\history\history.controller.ts#L10-L64)
- [server\prisma\schema.prisma:354-375](file://server\prisma\schema.prisma#L354-L375)

章节来源
- [server\src\modules\history\history.controller.ts:1-67](file://server\src\modules\history\history.controller.ts#L1-L67)
- [server\src\modules\history\history-batch.controller.ts:1-105](file://server\src\modules\history\history-batch.controller.ts#L1-L105)
- [server\prisma\schema.prisma:354-375](file://server\prisma\schema.prisma#L354-L375)

### 评论系统架构
- 功能要点
  - 按章节获取评论，按创建时间倒序。
  - 添加评论（含评分）。
- 数据模型
  - 评论与章节、用户建立关系，支持章节维度的评论统计与展示。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "评论路由"
participant Ctrl as "评论控制器"
participant Svc as "评论服务"
participant Prisma as "Prisma"
participant DB as "MySQL"
Client->>Router : "GET /api/comments/ : chapterId"
Router->>Ctrl : "解析章节ID"
Ctrl->>Svc : "查询评论"
Svc->>Prisma : "findMany(chapterId)"
Prisma->>DB : "SQL 查询"
DB-->>Prisma : "评论列表"
Prisma-->>Svc : "结果"
Svc-->>Ctrl : "返回列表"
Ctrl-->>Client : "JSON 响应"
Client->>Router : "POST /api/comments"
Router->>Ctrl : "解析请求体"
Ctrl->>Svc : "新增评论"
Svc->>Prisma : "create(comment)"
Prisma->>DB : "SQL 插入"
DB-->>Prisma : "新记录"
Prisma-->>Svc : "结果"
Svc-->>Ctrl : "返回评论"
Ctrl-->>Client : "JSON 响应"
```

图表来源
- [server\src\modules\comments\comments.controller.ts:13-56](file://server\src\modules\comments\comments.controller.ts#L13-L56)
- [server\src\modules\comments\comments.service.ts:10-30](file://server\src\modules\comments\comments.service.ts#L10-L30)
- [server\prisma\schema.prisma:107-119](file://server\prisma\schema.prisma#L107-L119)

章节来源
- [server\src\modules\comments\comments.controller.ts:1-58](file://server\src\modules\comments\comments.controller.ts#L1-L58)
- [server\src\modules\comments\comments.service.ts:1-32](file://server\src\modules\comments\comments.service.ts#L1-L32)
- [server\prisma\schema.prisma:107-119](file://server\prisma\schema.prisma#L107-L119)

### 收藏功能实现
- 功能要点
  - 获取收藏列表（包含书籍信息），按收藏时间倒序。
  - 添加收藏（幂等：重复收藏直接返回现有记录）。
  - 取消收藏与判断是否已收藏。
- 前端集成
  - 收藏页面展示收藏列表，支持取消收藏操作。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "收藏路由"
participant Svc as "收藏服务"
participant Prisma as "Prisma"
participant DB as "MySQL"
Client->>Router : "GET /api/favorites"
Router->>Svc : "查询收藏列表"
Svc->>Prisma : "findMany(include book)"
Prisma->>DB : "SQL 查询"
DB-->>Prisma : "收藏+书籍"
Prisma-->>Svc : "结果"
Svc-->>Router : "返回收藏列表"
Router-->>Client : "JSON 响应"
Client->>Router : "POST /api/favorites"
Router->>Svc : "添加收藏"
Svc->>Prisma : "upsert(去重)+create"
Prisma->>DB : "SQL 写入"
DB-->>Prisma : "新记录"
Prisma-->>Svc : "结果"
Svc-->>Router : "返回收藏"
Router-->>Client : "JSON 响应"
```

图表来源
- [server\src\modules\favorites\favorites.service.ts:8-103](file://server\src\modules\favorites\favorites.service.ts#L8-L103)
- [my-uniapp-vue3\src\pages\favorites\index.vue:25-43](file://my-uniapp-vue3\src\pages\favorites\index.vue#L25-L43)
- [server\prisma\schema.prisma:94-105](file://server\prisma\schema.prisma#L94-L105)

章节来源
- [server\src\modules\favorites\favorites.service.ts:1-103](file://server\src\modules\favorites\favorites.service.ts#L1-L103)
- [my-uniapp-vue3\src\pages\favorites\index.vue:1-45](file://my-uniapp-vue3\src\pages\favorites\index.vue#L1-L45)
- [server\prisma\schema.prisma:94-105](file://server\prisma\schema.prisma#L94-L105)

### 内容分类与标签系统
- 当前实现
  - 返回预设分类（默认映射），音频分类接口暂不可用（Audio 表已删除）。
  - 提供分类到标签的映射方法。
- 设计建议
  - 引入 BookCategory/BookTag 模型，建立书籍与标签的多对多关系，支持动态分类与标签管理。

```mermaid
classDiagram
class CategoriesService {
+getCategories()
+getAudiosByCategory(categoryId, page, pageSize)
-getAllAudios(page, pageSize)
-getCategoryTag(categoryId) string
}
class Book {
+int id
+string title
+string description
}
class BookChapter {
+int id
+int bookId
+string title
+string audioUrl
}
CategoriesService --> Book : "默认分类映射"
Book --> BookChapter : "包含章节"
```

图表来源
- [server\src\modules\categories\categories.service.ts:1-65](file://server\src\modules\categories\categories.service.ts#L1-L65)
- [server\prisma\schema.prisma:130-194](file://server\prisma\schema.prisma#L130-L194)

章节来源
- [server\src\modules\categories\categories.service.ts:1-65](file://server\src\modules\categories\categories.service.ts#L1-L65)
- [server\prisma\schema.prisma:130-194](file://server\prisma\schema.prisma#L130-L194)

### 个性化推荐与用户偏好
- 偏好设置
  - 默认值：播放速度、音质、主题、默认音色、音量、自动下一首、仅WiFi下载。
  - 通过 upsert 保证用户偏好存在性。
- 推荐机制
  - 当前仓库未提供推荐算法实现，建议结合播放记录、收藏、评分、搜索历史构建协同过滤或内容基础推荐。

章节来源
- [server\src\modules\preferences\preferences.service.ts:8-73](file://server\src\modules\preferences\preferences.service.ts#L8-L73)
- [server\prisma\schema.prisma:79-92](file://server\prisma\schema.prisma#L79-L92)

### 用户行为追踪与数据分析
- 行为采集
  - 播放进度与时长记录于 PlayRecord，可用于分析用户偏好与完播率。
- 数据分析
  - 建议基于 PlayRecord、SearchHistory、Comment、Favorite 等数据构建用户画像与行为趋势。

章节来源
- [server\prisma\schema.prisma:63-77](file://server\prisma\schema.prisma#L63-L77)
- [server\prisma\schema.prisma:222-230](file://server\prisma\schema.prisma#L222-L230)

### 内容审核与版权保护
- 敏感词检测
  - 仓库提供敏感词检测与词库接口（前端特性清单中已确认），可用于生成内容的实时检测与拦截。
- 版权保护
  - 建议结合水印、访问控制、内容加密与平台发布规范，配合审核流程实现。

章节来源
- [feature_list_content_generate.json:236-269](file://feature_list_content_generate.json#L236-L269)

### 缓存策略与CDN集成
- 缓存中间件
  - 统一缓存中间件支持 TTL、键前缀、自定义键生成器；提供常用键空间：用户信息、音色列表、书籍详情、热门书籍、会员权益。
- Redis 服务
  - 提供 get/set/getJSON/setJSON/del/delPattern/hset/hget/hgetall/incr/expire/exist/test/disconnect 等能力。
- CDN 集成
  - 建议对音频/图片等静态资源走 CDN，结合缓存中间件与 ETag/Last-Modified 实现边缘缓存。

```mermaid
graph LR
C["客户端"] --> M["缓存中间件<br/>cache.ts"]
M --> R["Redis 服务<br/>redis.service.ts"]
R --> D["Redis 缓存"]
M --> N["下游服务"]
```

图表来源
- [server\src\middleware\cache.ts:13-98](file://server\src\middleware\cache.ts#L13-L98)
- [server\src\services\redis.service.ts:1-274](file://server\src\services\redis.service.ts#L1-L274)

章节来源
- [server\src\middleware\cache.ts:1-98](file://server\src\middleware\cache.ts#L1-L98)
- [server\src\services\redis.service.ts:1-274](file://server\src\services\redis.service.ts#L1-L274)

### 静态资源管理
- 建议
  - 将音频、封面图等静态资源托管至对象存储（OSS/MinIO）并开启 CDN；前端通过 CDN URL 访问，减少源站压力。
  - 与缓存中间件结合，对元数据与列表页进行缓存。

## 依赖关系分析

```mermaid
graph TB
A["search.controller.ts"] --> B["search.service.ts"]
C["history.controller.ts"] --> D["schema.prisma"]
E["comments.controller.ts"] --> F["comments.service.ts"]
G["favorites.service.ts"] --> D
H["categories.service.ts"] --> D
I["preferences.service.ts"] --> D
J["cache.ts"] --> K["redis.service.ts"]
L["models/index.ts"] --> D
```

图表来源
- [server\src\modules\search\search.controller.ts:1-170](file://server\src\modules\search\search.controller.ts#L1-L170)
- [server\src\modules\search\search.service.ts:1-145](file://server\src\modules\search\search.service.ts#L1-L145)
- [server\src\modules\history\history.controller.ts:1-67](file://server\src\modules\history\history.controller.ts#L1-L67)
- [server\src\modules\comments\comments.controller.ts:1-58](file://server\src\modules\comments\comments.controller.ts#L1-L58)
- [server\src\modules\comments\comments.service.ts:1-32](file://server\src\modules\comments\comments.service.ts#L1-L32)
- [server\src\modules\favorites\favorites.service.ts:1-103](file://server\src\modules\favorites\favorites.service.ts#L1-L103)
- [server\src\modules\categories\categories.service.ts:1-65](file://server\src\modules\categories\categories.service.ts#L1-L65)
- [server\src\modules\preferences\preferences.service.ts:1-74](file://server\src\modules\preferences\preferences.service.ts#L1-L74)
- [server\src\middleware\cache.ts:1-98](file://server\src\middleware\cache.ts#L1-L98)
- [server\src\services\redis.service.ts:1-274](file://server\src\services\redis.service.ts#L1-L274)
- [server\src\models\index.ts:1-15](file://server\src\models\index.ts#L1-L15)
- [server\prisma\schema.prisma:1-472](file://server\prisma\schema.prisma#L1-L472)

章节来源
- [server\src\modules\search\search.controller.ts:1-170](file://server\src\modules\search\search.controller.ts#L1-L170)
- [server\src\modules\search\search.service.ts:1-145](file://server\src\modules\search\search.service.ts#L1-L145)
- [server\prisma\schema.prisma:1-472](file://server\prisma\schema.prisma#L1-L472)

## 性能考虑
- 查询优化
  - 为高频查询字段建立索引（如 SearchHistory.userId、HotSearch.sort/count、AudioRecord.userId/audioId/bookId 等）。
- 分页与限制
  - 搜索与历史查询均限制返回条数，避免一次性返回大量数据。
- 缓存策略
  - 对热点数据（书籍详情、热门书籍、音色列表、用户偏好）设置合理 TTL，降低数据库压力。
- 并发与事务
  - 收藏添加采用幂等写入，避免重复插入；批量删除使用 in 查询，减少多次往返。

## 故障排查指南
- 错误处理
  - 通用错误中间件捕获异常并返回标准化响应。
- 日志与诊断
  - 日志服务支持错误模式匹配与通用建议输出，提供日志清理能力。
- Redis 连接
  - Redis 服务内置重连策略与连接状态检测，便于快速定位缓存不可用问题。

章节来源
- [server\src\middleware\errorHandler.js:1-24](file://server\src\middleware\errorHandler.js#L1-L24)
- [server\src\services\log.service.ts:277-315](file://server\src\services\log.service.ts#L277-L315)
- [server\src\services\redis.service.ts:1-274](file://server\src\services\redis.service.ts#L1-L274)

## 结论
本系统在搜索、历史、评论、收藏、分类与偏好等方面提供了清晰的模块化实现，并通过 Prisma 与 Redis 构建了可扩展的数据与缓存层。后续可在推荐算法、内容审核与版权保护、CDN 与静态资源管理方面进一步完善，以提升用户体验与平台安全性。

## 附录

### API 接口文档

- 搜索
  - GET /api/search?q=关键词&limit=数值
  - GET /api/search/hot?limit=数值
  - GET /api/search/history?userId=数值&limit=数值
  - POST /api/search/history { userId, keyword }
  - DELETE /api/search/history?userId=数值&keyword=关键词
  - DELETE /api/search/history/all?userId=数值

- 历史
  - GET /api/history?page=数值&pageSize=数值&startDate=日期
  - POST /api/history/batch-delete { ids: string[] }
  - DELETE /api/history/batch（兼容）

- 评论
  - GET /api/comments/:chapterId
  - POST /api/comments { chapterId, content, rating }

- 收藏
  - GET /api/favorites
  - POST /api/favorites { userId, bookId }
  - DELETE /api/favorites/{userId}/{bookId}

- 分类
  - GET /api/categories

- 偏好
  - GET /api/preferences?userId=数值
  - POST /api/preferences { userId, ...偏好字段 }

章节来源
- [server\src\modules\search\search.controller.ts:10-169](file://server\src\modules\search\search.controller.ts#L10-L169)
- [server\src\modules\history\history.controller.ts:11-64](file://server\src\modules\history\history.controller.ts#L11-L64)
- [server\src\modules\history\history-batch.controller.ts:11-102](file://server\src\modules\history\history-batch.controller.ts#L11-L102)
- [server\src\modules\comments\comments.controller.ts:13-56](file://server\src\modules\comments\comments.controller.ts#L13-L56)
- [server\src\modules\favorites\favorites.service.ts:8-103](file://server\src\modules\favorites\favorites.service.ts#L8-L103)
- [server\src\modules\categories\categories.service.ts:10-20](file://server\src\modules\categories\categories.service.ts#L10-L20)
- [server\src\modules\preferences\preferences.service.ts:8-73](file://server\src\modules\preferences\preferences.service.ts#L8-L73)

### 数据模型说明

```mermaid
erDiagram
USER ||--o{ COMMENT : "发表"
USER ||--o{ FAVORITE : "收藏"
USER ||--o{ AUDIO_RECORD : "生成"
BOOK ||--o{ BOOK_CHAPTER : "包含"
BOOK ||--o{ FAVORITE : "被收藏"
BOOK_CHAPTER ||--o{ COMMENT : "被评论"
BOOK_CHAPTER ||--o{ PLAY_RECORD : "被播放"
USER ||--o{ PLAY_RECORD : "产生记录"
```

图表来源
- [server\prisma\schema.prisma:10-472](file://server\prisma\schema.prisma#L10-L472)

### 扩展开发指南
- 新增模块
  - 在 server/src/modules 下创建控制器与服务，遵循现有命名与导出约定。
  - 在 Prisma schema 中定义数据模型并生成客户端。
  - 在 app.ts 中挂载路由。
- 自定义缓存
  - 使用 createCache/clearCache 定义键空间与 TTL，确保命中率与一致性。
- 监控指标
  - 建议埋点：搜索请求量/成功率、历史批量删除次数、收藏/取消收藏频次、评论提交数、播放完成率等。