内容管理系统.md 25 KB
内容管理系统
本文引用的文件
- server\src\modules\search\search.service.ts
- server\src\modules\search\search.controller.ts
- server\prisma\schema.prisma
- server\src\models\index.ts
- server\src\modules\history\history.controller.ts
- server\src\modules\history\history-batch.controller.ts
- server\src\modules\comments\comments.service.ts
- server\src\modules\comments\comments.controller.ts
- server\src\modules\favorites\favorites.service.ts
- server\src\modules\categories\categories.service.ts
- server\src\middleware\cache.ts
- server\src\services\redis.service.ts
- server\src\modules\preferences\preferences.service.ts
- my-uniapp-vue3\src\pages\favorites\index.vue
- server\src\middleware\errorHandler.js
- server\src\services\log.service.ts
- feature_list_optimization.json
- feature_list_content_generate.json
目录
简介
本技术文档面向内容管理系统（音频/有声书方向），围绕收藏、历史记录、评论系统、搜索与索引、内容分类与标签、推荐与个性化、用户行为追踪与分析、审核与版权保护、缓存与CDN、静态资源管理、扩展开发与监控等主题，提供从架构到实现细节的系统化说明，并配套API接口文档与数据模型说明。
项目结构
后端采用 Koa + Prisma 架构，模块化组织业务功能；前端基于 uniapp-vue3。核心模块包括搜索、历史、评论、收藏、分类、偏好设置、缓存中间件与 Redis 服务等。
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
- server\src\modules\history\history.controller.ts:1-67
- server\src\modules\comments\comments.controller.ts:1-58
- server\src\modules\favorites\favorites.service.ts:1-103
- server\src\modules\categories\categories.service.ts:1-65
- server\src\modules\preferences\preferences.service.ts:1-74
- server\src\middleware\cache.ts:1-98
- server\src\services\redis.service.ts:1-274
- server\prisma\schema.prisma:1-472
- server\src\models\index.ts:1-15
章节来源
- server\src\modules\search\search.controller.ts:1-170
- server\src\modules\history\history.controller.ts:1-67
- server\src\modules\comments\comments.controller.ts:1-58
- server\src\modules\search\search.service.ts:1-145
- server\prisma\schema.prisma:1-472
核心组件
- 搜索与索引：提供全局搜索、热门词、搜索历史持久化与去重、历史上限控制与热门词计数更新。
- 历史记录：分页查询音频生成历史，支持批量删除。
- 评论系统：按章节获取评论、添加评论。
- 收藏功能：用户对书籍的收藏、取消收藏、查询收藏列表、判断是否已收藏。
- 分类与标签：音频分类（当前返回默认分类映射）、分类标签映射。
- 偏好设置：播放速度、音质、主题、默认音色、音量、自动下一首、仅WiFi下载等。
- 缓存与Redis：统一缓存中间件、常用键空间、失效策略。
- 错误处理与日志：通用错误中间件、日志清理与智能建议。
章节来源
- server\src\modules\search\search.service.ts:1-145
- server\src\modules\history\history.controller.ts:1-67
- server\src\modules\history\history-batch.controller.ts:1-105
- server\src\modules\comments\comments.service.ts:1-32
- server\src\modules\comments\comments.controller.ts:1-58
- server\src\modules\favorites\favorites.service.ts:1-103
- server\src\modules\categories\categories.service.ts:1-65
- server\src\modules\preferences\preferences.service.ts:1-74
- server\src\middleware\cache.ts:1-98
- server\src\services\redis.service.ts:1-274
- server\src\middleware\errorHandler.js:1-24
- server\src\services\log.service.ts:277-315
架构总览
系统采用前后端分离，后端以 Koa 路由聚合各模块服务，数据访问通过 Prisma ORM，缓存层基于 Redis。前端 uniapp-vue3 通过 HTTP API 与后端交互。
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
- server\src\modules\search\search.service.ts:1-145
- server\prisma\schema.prisma:1-472
详细组件分析
搜索与索引
- 功能要点
- 全局搜索：按标题或描述模糊匹配，按创建时间倒序，限制返回条数。
- 热门搜索词：多字段排序，限制返回条数。
- 搜索历史：按用户去重、保留最新记录、限制最大条数；同时更新热门词计数。
- 历史清理：支持按用户清空、按关键词删除单条。
- 索引策略
- 搜索关键词在标题/描述上具备模糊匹配能力；热门词与搜索历史具备复合索引，保证查询效率。
- 排序算法
- 热门词优先级：先按 sort 降序，再按 count 降序；搜索结果按创建时间倒序。
前端优化
搜索结果关键词高亮（前端特性清单中已确认）。
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
- server\prisma\schema.prisma:222-242
章节来源
- server\src\modules\search\search.service.ts:1-145
- server\src\modules\search\search.controller.ts:1-170
- server\prisma\schema.prisma:222-242
- feature_list_optimization.json:1-39
历史记录管理
- 功能要点
- 分页查询音频生成历史，支持按起始日期过滤。
- 批量删除历史记录（POST/DELETE 兼容）。
数据模型
历史记录存储于 AudioRecord，包含音频标识、标题、文本、时长、大小、状态、语音参数、关联书籍等。
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
- server\prisma\schema.prisma:354-375
章节来源
- server\src\modules\history\history.controller.ts:1-67
- server\src\modules\history\history-batch.controller.ts:1-105
- server\prisma\schema.prisma:354-375
评论系统架构
- 功能要点
- 按章节获取评论，按创建时间倒序。
- 添加评论（含评分）。
数据模型
评论与章节、用户建立关系，支持章节维度的评论统计与展示。
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
- server\src\modules\comments\comments.service.ts:10-30
- server\prisma\schema.prisma:107-119
章节来源
- server\src\modules\comments\comments.controller.ts:1-58
- server\src\modules\comments\comments.service.ts:1-32
- server\prisma\schema.prisma:107-119
收藏功能实现
- 功能要点
- 获取收藏列表（包含书籍信息），按收藏时间倒序。
- 添加收藏（幂等：重复收藏直接返回现有记录）。
- 取消收藏与判断是否已收藏。
前端集成
收藏页面展示收藏列表，支持取消收藏操作。
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
- my-uniapp-vue3\src\pages\favorites\index.vue:25-43
- server\prisma\schema.prisma:94-105
章节来源
- server\src\modules\favorites\favorites.service.ts:1-103
- my-uniapp-vue3\src\pages\favorites\index.vue:1-45
- server\prisma\schema.prisma:94-105
内容分类与标签系统
- 当前实现
- 返回预设分类（默认映射），音频分类接口暂不可用（Audio 表已删除）。
- 提供分类到标签的映射方法。
设计建议
引入 BookCategory/BookTag 模型，建立书籍与标签的多对多关系，支持动态分类与标签管理。
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
- server\prisma\schema.prisma:130-194
章节来源
- server\src\modules\categories\categories.service.ts:1-65
- server\prisma\schema.prisma:130-194
个性化推荐与用户偏好
- 偏好设置
- 默认值：播放速度、音质、主题、默认音色、音量、自动下一首、仅WiFi下载。
- 通过 upsert 保证用户偏好存在性。
- 推荐机制
- 当前仓库未提供推荐算法实现，建议结合播放记录、收藏、评分、搜索历史构建协同过滤或内容基础推荐。
章节来源
- server\src\modules\preferences\preferences.service.ts:8-73
- server\prisma\schema.prisma:79-92
用户行为追踪与数据分析
- 行为采集
- 播放进度与时长记录于 PlayRecord，可用于分析用户偏好与完播率。
- 数据分析
- 建议基于 PlayRecord、SearchHistory、Comment、Favorite 等数据构建用户画像与行为趋势。
章节来源
- server\prisma\schema.prisma:63-77
- server\prisma\schema.prisma:222-230
内容审核与版权保护
- 敏感词检测
- 仓库提供敏感词检测与词库接口（前端特性清单中已确认），可用于生成内容的实时检测与拦截。
- 版权保护
- 建议结合水印、访问控制、内容加密与平台发布规范，配合审核流程实现。
章节来源
- feature_list_content_generate.json:236-269
缓存策略与CDN集成
- 缓存中间件
- 统一缓存中间件支持 TTL、键前缀、自定义键生成器；提供常用键空间：用户信息、音色列表、书籍详情、热门书籍、会员权益。
- Redis 服务
- 提供 get/set/getJSON/setJSON/del/delPattern/hset/hget/hgetall/incr/expire/exist/test/disconnect 等能力。
CDN 集成
建议对音频/图片等静态资源走 CDN，结合缓存中间件与 ETag/Last-Modified 实现边缘缓存。
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
- server\src\services\redis.service.ts:1-274
章节来源
- server\src\middleware\cache.ts:1-98
- server\src\services\redis.service.ts:1-274
静态资源管理
- 建议
- 将音频、封面图等静态资源托管至对象存储（OSS/MinIO）并开启 CDN；前端通过 CDN URL 访问，减少源站压力。
- 与缓存中间件结合，对元数据与列表页进行缓存。
依赖关系分析
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
- server\src\modules\search\search.service.ts:1-145
- server\src\modules\history\history.controller.ts:1-67
- server\src\modules\comments\comments.controller.ts:1-58
- server\src\modules\comments\comments.service.ts:1-32
- server\src\modules\favorites\favorites.service.ts:1-103
- server\src\modules\categories\categories.service.ts:1-65
- server\src\modules\preferences\preferences.service.ts:1-74
- server\src\middleware\cache.ts:1-98
- server\src\services\redis.service.ts:1-274
- server\src\models\index.ts:1-15
- server\prisma\schema.prisma:1-472
章节来源
- server\src\modules\search\search.controller.ts:1-170
- server\src\modules\search\search.service.ts:1-145
- server\prisma\schema.prisma:1-472
性能考虑
- 查询优化
- 为高频查询字段建立索引（如 SearchHistory.userId、HotSearch.sort/count、AudioRecord.userId/audioId/bookId 等）。
- 分页与限制
- 搜索与历史查询均限制返回条数，避免一次性返回大量数据。
- 缓存策略
- 对热点数据（书籍详情、热门书籍、音色列表、用户偏好）设置合理 TTL，降低数据库压力。
- 并发与事务
- 收藏添加采用幂等写入，避免重复插入；批量删除使用 in 查询，减少多次往返。
故障排查指南
- 错误处理
- 通用错误中间件捕获异常并返回标准化响应。
- 日志与诊断
- 日志服务支持错误模式匹配与通用建议输出，提供日志清理能力。
- Redis 连接
- Redis 服务内置重连策略与连接状态检测，便于快速定位缓存不可用问题。
章节来源
- server\src\middleware\errorHandler.js:1-24
- server\src\services\log.service.ts:277-315
- server\src\services\redis.service.ts:1-274
结论
本系统在搜索、历史、评论、收藏、分类与偏好等方面提供了清晰的模块化实现，并通过 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
- server\src\modules\history\history.controller.ts:11-64
- server\src\modules\history\history-batch.controller.ts:11-102
- server\src\modules\comments\comments.controller.ts:13-56
- server\src\modules\favorites\favorites.service.ts:8-103
- server\src\modules\categories\categories.service.ts:10-20
- server\src\modules\preferences\preferences.service.ts:8-73
数据模型说明
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
扩展开发指南
- 新增模块
- 在 server/src/modules 下创建控制器与服务，遵循现有命名与导出约定。
- 在 Prisma schema 中定义数据模型并生成客户端。
- 在 app.ts 中挂载路由。
- 自定义缓存
- 使用 createCache/clearCache 定义键空间与 TTL，确保命中率与一致性。
- 监控指标
- 建议埋点：搜索请求量/成功率、历史批量删除次数、收藏/取消收藏频次、评论提交数、播放完成率等。