# 交互数据模型

<cite>
**本文档引用的文件**
- [schema.prisma](file://server/prisma/schema.prisma)
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [favorites.service.ts](file://server/src/modules/favorites/favorites.service.ts)
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [comments.service.ts](file://server/src/modules/comments/comments.service.ts)
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)
- [index.vue（收藏页面）](file://my-uniapp-vue3/src/pages/favorites/index.vue)
- [index.vue（历史页面）](file://my-uniapp-vue3/src/pages/history/index.vue)
- [index.vue（搜索页面）](file://my-uniapp-vue3/src/pages/search/index.vue)
- [6个新功能最终完成包.md](file://6个新功能最终完成包.md)
</cite>

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

## 引言
本文件面向AI有声书生成平台的交互数据模型，聚焦用户行为数据的设计与实现，包括收藏管理、评论系统、播放记录、搜索历史等关键功能。文档从数据库模型出发，结合控制器与服务层实现，梳理前后端交互流程，并给出API使用示例与最佳实践，帮助开发者快速理解与扩展相关能力。

## 项目结构
围绕交互数据模型的关键目录与文件如下：
- 数据库模型定义：server/prisma/schema.prisma
- 控制器层：server/src/modules/{favorites,comments,player,search,history}/
- 服务层：对应模块的service.ts
- 前端页面：my-uniapp-vue3/src/pages/{favorites,history,search}/index.vue
- 批量删除功能补充：6个新功能最终完成包.md

```mermaid
graph TB
subgraph "前端"
FE_Fav["收藏页面<br/>favorites/index.vue"]
FE_Hist["历史页面<br/>history/index.vue"]
FE_Search["搜索页面<br/>search/index.vue"]
end
subgraph "后端"
C_Fav["收藏控制器<br/>favorites.controller.ts"]
S_Fav["收藏服务<br/>favorites.service.ts"]
C_Com["评论控制器<br/>comments.controller.ts"]
S_Com["评论服务<br/>comments.service.ts"]
S_Player["播放服务<br/>player.service.ts"]
C_Search["搜索控制器<br/>search.controller.ts"]
S_Search["搜索服务<br/>search.service.ts"]
C_Hist["历史控制器<br/>history.controller.ts"]
end
DB["数据库模型<br/>schema.prisma"]
FE_Fav --> C_Fav --> S_Fav --> DB
FE_Hist --> C_Hist --> DB
FE_Search --> C_Search --> S_Search --> DB
FE_Fav -.-> C_Com --> S_Com --> DB
FE_Fav -.-> S_Player --> DB
FE_Search -.-> S_Player --> DB
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [favorites.service.ts](file://server/src/modules/favorites/favorites.service.ts)
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [comments.service.ts](file://server/src/modules/comments/comments.service.ts)
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [favorites.service.ts](file://server/src/modules/favorites/favorites.service.ts)
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [comments.service.ts](file://server/src/modules/comments/comments.service.ts)
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)

## 核心组件
本节概述与交互数据模型直接相关的数据表与业务组件，以及它们在系统中的职责。

- 收藏表（Favorite）
  - 关联用户与书籍，支持唯一索引约束防止重复收藏，便于快速查询某用户的收藏列表与检查收藏状态。
- 评论表（Comment）
  - 关联用户与章节，支持按章节查询评论列表，便于在播放器或章节详情页展示用户反馈。
- 播放记录表（PlayRecord）
  - 记录用户对章节的播放进度与总时长，支持续播与最近播放记录展示；包含唯一索引保证同一用户对同一章节的记录唯一性。
- 搜索历史表（SearchHistory）
  - 记录用户搜索关键词，支持去重与上限控制，同时维护热门搜索词统计。
- 用户偏好表（UserPreference）
  - 存储播放速度、音质、主题、默认音色、默认音量等偏好配置，支持个性化体验。
- 历史记录表（AudioRecord）
  - 记录音频生成的历史，包含标题、文本、字数、语音参数、时长、大小、状态等字段，支持分页与筛选。

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 架构总览
交互数据模型的架构由“前端页面 → 控制器 → 服务层 → 数据库模型”构成，各模块职责清晰、耦合度低，便于扩展与维护。

```mermaid
sequenceDiagram
participant FE as "前端页面"
participant CTRL as "控制器"
participant SVC as "服务层"
participant DB as "数据库模型"
FE->>CTRL : 触发交互请求如收藏/评论/播放/搜索
CTRL->>SVC : 解析参数并调用业务方法
SVC->>DB : 查询/插入/更新/删除数据
DB-->>SVC : 返回数据结果
SVC-->>CTRL : 格式化响应数据
CTRL-->>FE : 返回JSON响应code/message/data
```

**图表来源**
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [favorites.service.ts](file://server/src/modules/favorites/favorites.service.ts)
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [comments.service.ts](file://server/src/modules/comments/comments.service.ts)
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)

## 详细组件分析

### 收藏模型（Favorite）
- 数据结构要点
  - 唯一索引：用户ID与书籍ID组合唯一，避免重复收藏。
  - 关系：与User、Book双向关联，便于查询用户收藏列表与书籍详情。
- 业务流程
  - 添加收藏：若不存在则创建，存在则返回现有记录。
  - 取消收藏：根据唯一键删除。
  - 检查收藏：查询唯一键是否存在。
- 前端交互
  - 收藏页面展示收藏列表，支持取消收藏并实时更新UI。
  - 播放器页面可显示收藏状态并提供收藏/取消操作入口。

```mermaid
sequenceDiagram
participant FE as "前端收藏页面"
participant CTRL as "收藏控制器"
participant SVC as "收藏服务"
participant DB as "数据库(Favorite)"
FE->>CTRL : POST /api/favorites传入audioId
CTRL->>SVC : addFavorite(userId, audioId)
SVC->>DB : upsert唯一键：userId+bookId
DB-->>SVC : 返回收藏记录
SVC-->>CTRL : 格式化数据
CTRL-->>FE : {code,message,data}
```

**图表来源**
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [favorites.service.ts](file://server/src/modules/favorites/favorites.service.ts)

**章节来源**
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [favorites.service.ts](file://server/src/modules/favorites/favorites.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [index.vue（收藏页面）](file://my-uniapp-vue3/src/pages/favorites/index.vue)

### 评论模型（Comment）
- 数据结构要点
  - 关联章节与用户，支持按章节ID查询评论列表。
  - 评分字段用于展示星级评价。
- 业务流程
  - 获取评论：按章节ID降序返回评论列表。
  - 发表评论：校验参数后创建评论记录。

```mermaid
sequenceDiagram
participant FE as "前端播放器/章节详情"
participant CTRL as "评论控制器"
participant SVC as "评论服务"
participant DB as "数据库(Comment)"
FE->>CTRL : GET /api/comments/ : chapterId
CTRL->>SVC : getCommentsByChapterId(chapterId)
SVC->>DB : findMany(where : { chapterId })
DB-->>SVC : 返回评论列表
SVC-->>CTRL : 格式化数据
CTRL-->>FE : {code,message,data}
FE->>CTRL : POST /api/commentscontent,rating
CTRL->>SVC : addComment(userId, chapterId, content, rating)
SVC->>DB : create(comment)
DB-->>SVC : 返回新建评论
SVC-->>CTRL : 格式化数据
CTRL-->>FE : {code,message,data}
```

**图表来源**
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [comments.service.ts](file://server/src/modules/comments/comments.service.ts)

**章节来源**
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [comments.service.ts](file://server/src/modules/comments/comments.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)

### 播放记录模型（PlayRecord）
- 数据结构要点
  - 唯一索引：用户ID与章节ID组合唯一，确保同一用户对同一章节的播放记录唯一。
  - 字段：progress（播放进度）、duration（章节总时长）。
- 业务流程
  - 保存进度：使用upsert语义，不存在则创建，存在则更新。
  - 获取进度：支持按用户或按章节查询。
  - 最近播放：按更新时间倒序返回最近播放记录，计算播放进度百分比。
- 前端交互
  - 播放器定时上报进度，页面切换时保存最新进度，续播时读取上次进度。

```mermaid
sequenceDiagram
participant FE as "前端播放器"
participant SVC as "播放服务"
participant DB as "数据库(PlayRecord)"
FE->>SVC : savePlayProgress(userId, chapterId, progress, duration)
SVC->>DB : upsert唯一键：userId+chapterId
DB-->>SVC : 返回记录
SVC-->>FE : 成功
FE->>SVC : getRecentPlayRecords(userId, limit)
SVC->>DB : findMany(include chapter.book, orderBy updatedAt desc)
DB-->>SVC : 返回记录列表
SVC-->>FE : 格式化进度百分比
```

**图表来源**
- [player.service.ts](file://server/src/modules/player/player.service.ts)

**章节来源**
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)

### 搜索历史模型（SearchHistory）
- 数据结构要点
  - 用户ID与关键词组合，支持去重与上限控制（最多20条）。
  - 热门搜索词表（HotSearch）用于统计搜索热度。
- 业务流程
  - 保存历史：删除同用户同关键词旧记录，插入新记录，并维护热门搜索词计数。
  - 获取历史：按用户ID与时间倒序返回，去重保留最新一条。
  - 删除历史：支持单条删除与清空。

```mermaid
flowchart TD
Start(["保存搜索历史"]) --> Trim["去除空白字符"]
Trim --> Exists{"是否存在同用户同关键词记录？"}
Exists --> |是| DeleteOld["删除旧记录"]
Exists --> |否| SkipDelete["跳过删除"]
DeleteOld --> InsertNew["插入新记录"]
SkipDelete --> InsertNew
InsertNew --> LimitCheck{"历史总数是否超过20条？"}
LimitCheck --> |是| DeleteExtra["删除最旧记录"]
LimitCheck --> |否| KeepAll["保留全部"]
DeleteExtra --> UpdateHot["更新热门搜索词计数"]
KeepAll --> UpdateHot
UpdateHot --> End(["完成"])
```

**图表来源**
- [search.service.ts](file://server/src/modules/search/search.service.ts)

**章节来源**
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [index.vue（搜索页面）](file://my-uniapp-vue3/src/pages/search/index.vue)

### 历史记录模型（AudioRecord）
- 数据结构要点
  - 记录音频生成的元数据：标题、文本、字数、语音参数、时长、大小、状态等。
  - 支持按用户、按时间段筛选与分页。
- 业务流程
  - 获取历史：支持按起始日期筛选，返回分页数据。
  - 批量删除：新增批量删除接口，支持按ID集合删除。

```mermaid
sequenceDiagram
participant FE as "前端历史页面"
participant CTRL as "历史控制器"
participant DB as "数据库(AudioRecord)"
FE->>CTRL : GET /api/history?page&pageSize&startDate
CTRL->>DB : findMany(where : { createdAt >= startDate }, orderBy : createdAt desc)
DB-->>CTRL : 返回记录与总数
CTRL-->>FE : {code,message,{list,total,page,pageSize,totalPages}}
```

**图表来源**
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)

**章节来源**
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)
- [6个新功能最终完成包.md](file://6个新功能最终完成包.md)
- [schema.prisma](file://server/prisma/schema.prisma)
- [index.vue（历史页面）](file://my-uniapp-vue3/src/pages/history/index.vue)

## 依赖分析
- 表间关系
  - User ↔ Favorite/Comment/PlayRecord：一对多关系，用户通过外键关联各类交互记录。
  - Book ↔ Favorite：书籍与收藏的多对一关系，收藏指向具体书籍。
  - BookChapter ↔ Comment/PlayRecord：章节与评论、播放记录的多对一关系。
  - SearchHistory/HotSearch：独立表，分别记录用户搜索历史与热门搜索词。
- 前后端依赖
  - 前端页面通过HTTP请求与后端控制器交互，控制器调用服务层，服务层访问数据库模型。
  - 播放服务与搜索服务在多个页面中被复用，体现良好的模块化设计。

```mermaid
erDiagram
USER ||--o{ FAVORITE : "收藏"
USER ||--o{ COMMENT : "发表评论"
USER ||--o{ PLAY_RECORD : "播放记录"
BOOK ||--o{ FAVORITE : "被收藏"
BOOKCHAPTER ||--o{ COMMENT : "被评论"
BOOKCHAPTER ||--o{ PLAY_RECORD : "被播放"
SEARCHHISTORY ||--|| USER : "属于"
HOTSEARCH ||--|| SEARCHHISTORY : "统计"
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 性能考虑
- 索引设计
  - PlayRecord/Favorite/SearchHistory等高频查询字段建立索引，提升查询效率。
  - 唯一索引保证数据一致性，避免重复记录。
- 分页与去重
  - 历史列表与搜索历史采用分页与去重策略，降低前端渲染压力与数据库负载。
- 缓存策略
  - 前端对热门搜索词进行本地缓存，减少重复请求与网络开销。
- 批量操作
  - 历史记录新增批量删除接口，支持前端多选后一次性清理，提升用户体验。

**章节来源**
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)
- [6个新功能最终完成包.md](file://6个新功能最终完成包.md)
- [index.vue（搜索页面）](file://my-uniapp-vue3/src/pages/search/index.vue)

## 故障排除指南
- 常见错误与处理
  - 收藏/评论接口参数校验失败：控制器抛出错误并返回错误码与消息，前端需提示用户修正输入。
  - 播放进度保存失败：检查用户ID与章节ID是否正确，确认唯一键约束是否冲突。
  - 搜索历史为空：确认关键词非空且去除空白字符，检查去重与上限逻辑。
  - 历史记录分页异常：核对分页参数与时间筛选条件，确保数据库索引有效。
- 日志与监控
  - 服务层与控制器均返回统一格式的响应体，便于前端统一处理与后端日志追踪。
  - 对关键操作（如收藏、评论、播放进度保存、搜索历史更新）建议增加埋点与告警。

**章节来源**
- [favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [search.service.ts](file://server/src/modules/search/search.service.ts)
- [history.controller.ts](file://server/src/modules/history/history.controller.ts)

## 结论
本交互数据模型围绕收藏、评论、播放记录与搜索历史四大核心功能构建，通过清晰的数据库模型、模块化的控制器与服务层以及友好的前端交互，实现了用户行为数据的采集、存储与分析。后续可在现有基础上扩展更多个性化功能（如评分反馈、搜索偏好分析、播放统计报表等），持续优化用户体验与平台运营效率。