audio_codebuddy/.qoder/repowiki/zh/content/数据库设计/交互数据模型/交互数据模型.md

交互数据模型

本文档引用的文件

• schema.prisma
• favorites.controller.ts
• favorites.service.ts
• comments.controller.ts
• comments.service.ts
• player.service.ts
• search.controller.ts
• search.service.ts
• history.controller.ts
• index.vue（收藏页面）
• index.vue（历史页面）
• index.vue（搜索页面）
• 6个新功能最终完成包.md

目录

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

  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
• favorites.controller.ts
• favorites.service.ts
• comments.controller.ts
• comments.service.ts
• player.service.ts
• search.controller.ts
• search.service.ts
• history.controller.ts

章节来源

• schema.prisma
• favorites.controller.ts
• favorites.service.ts
• comments.controller.ts
• comments.service.ts
• player.service.ts
• search.controller.ts
• search.service.ts
• history.controller.ts

核心组件

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

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

章节来源

• schema.prisma

架构总览

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

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
• favorites.service.ts
• comments.controller.ts
• comments.service.ts
• player.service.ts
• search.controller.ts
• search.service.ts
• history.controller.ts

详细组件分析

收藏模型（Favorite）

• 数据结构要点
  • 唯一索引：用户ID与书籍ID组合唯一，避免重复收藏。
  • 关系：与User、Book双向关联，便于查询用户收藏列表与书籍详情。
• 业务流程
  • 添加收藏：若不存在则创建，存在则返回现有记录。
  • 取消收藏：根据唯一键删除。
  • 检查收藏：查询唯一键是否存在。

• 前端交互

  • 收藏页面展示收藏列表，支持取消收藏并实时更新UI。

  • 播放器页面可显示收藏状态并提供收藏/取消操作入口。

    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
• favorites.service.ts

章节来源

• favorites.controller.ts
• favorites.service.ts
• schema.prisma
• index.vue（收藏页面）

评论模型（Comment）

• 数据结构要点
  • 关联章节与用户，支持按章节ID查询评论列表。
  • 评分字段用于展示星级评价。

• 业务流程

  • 获取评论：按章节ID降序返回评论列表。

  • 发表评论：校验参数后创建评论记录。

    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
• comments.service.ts

章节来源

• comments.controller.ts
• comments.service.ts
• schema.prisma

播放记录模型（PlayRecord）

• 数据结构要点
  • 唯一索引：用户ID与章节ID组合唯一，确保同一用户对同一章节的播放记录唯一。
  • 字段：progress（播放进度）、duration（章节总时长）。
• 业务流程
  • 保存进度：使用upsert语义，不存在则创建，存在则更新。
  • 获取进度：支持按用户或按章节查询。
  • 最近播放：按更新时间倒序返回最近播放记录，计算播放进度百分比。

• 前端交互

  • 播放器定时上报进度，页面切换时保存最新进度，续播时读取上次进度。

    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

章节来源

• player.service.ts
• schema.prisma

搜索历史模型（SearchHistory）

• 数据结构要点
  • 用户ID与关键词组合，支持去重与上限控制（最多20条）。
  • 热门搜索词表（HotSearch）用于统计搜索热度。

• 业务流程

  • 保存历史：删除同用户同关键词旧记录，插入新记录，并维护热门搜索词计数。
  • 获取历史：按用户ID与时间倒序返回，去重保留最新一条。

  • 删除历史：支持单条删除与清空。

    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

章节来源

• search.controller.ts
• search.service.ts
• schema.prisma
• index.vue（搜索页面）

历史记录模型（AudioRecord）

• 数据结构要点
  • 记录音频生成的元数据：标题、文本、字数、语音参数、时长、大小、状态等。
  • 支持按用户、按时间段筛选与分页。

• 业务流程

  • 获取历史：支持按起始日期筛选，返回分页数据。

  • 批量删除：新增批量删除接口，支持按ID集合删除。

    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

章节来源

• history.controller.ts
• 6个新功能最终完成包.md
• schema.prisma
• index.vue（历史页面）

依赖分析

• 表间关系
  • User ↔ Favorite/Comment/PlayRecord：一对多关系，用户通过外键关联各类交互记录。
  • Book ↔ Favorite：书籍与收藏的多对一关系，收藏指向具体书籍。
  • BookChapter ↔ Comment/PlayRecord：章节与评论、播放记录的多对一关系。
  • SearchHistory/HotSearch：独立表，分别记录用户搜索历史与热门搜索词。

• 前后端依赖

  • 前端页面通过HTTP请求与后端控制器交互，控制器调用服务层，服务层访问数据库模型。

  • 播放服务与搜索服务在多个页面中被复用，体现良好的模块化设计。

    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

章节来源

• schema.prisma

性能考虑

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

章节来源

• search.service.ts
• history.controller.ts
• 6个新功能最终完成包.md
• index.vue（搜索页面）

故障排除指南

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

章节来源

• favorites.controller.ts
• comments.controller.ts
• player.service.ts
• search.controller.ts
• search.service.ts
• history.controller.ts

结论

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