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

评论数据模型

本文引用的文件

• comments.controller.ts
• comments.service.ts
• schema.prisma
• app.ts
• index.ts
• security.ts
• API.md

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

引言

本文件面向AI有声书生成平台的评论功能，提供评论数据模型的权威说明。重点涵盖Comment模型字段定义、与User和BookChapter的多对一关系、当前实现的评论读取与发表能力、以及在内容发现与质量评估中的作用。由于当前仓库中未实现评论删除、回复、审核与评分统计等高级功能，本文将基于现有代码进行准确描述，并在“概念性概述”部分给出扩展建议。

项目结构

评论功能位于后端服务的独立模块中，采用Koa路由+Prisma ORM的典型分层结构：

• 控制器层：负责HTTP路由与请求响应包装
• 服务层：封装业务逻辑与数据访问
• 数据模型：基于Prisma Schema定义实体关系

• 应用入口：注册路由并启动服务

  graph TB
  subgraph "应用入口"
  APP["app.ts<br/>注册路由与中间件"]
  end
  subgraph "评论模块"
  CTRL["comments.controller.ts<br/>路由与控制器"]
  SVC["comments.service.ts<br/>业务与数据访问"]
  PRISMA["schema.prisma<br/>Comment/User/BookChapter 关系"]
  end
  APP --> CTRL
  CTRL --> SVC
  SVC --> PRISMA
  

图表来源

• app.ts:99-129
• comments.controller.ts:1-59
• comments.service.ts:1-33
• schema.prisma:107-119

章节来源

• app.ts:99-129
• comments.controller.ts:1-59
• comments.service.ts:1-33
• schema.prisma:107-119

核心组件

• Comment模型：承载章节评论的文本内容、评分、创建时间，并与User和BookChapter建立多对一关系
• CommentsService：提供按章节查询评论列表、新增评论的业务方法
• CommentsController：提供HTTP接口，封装请求参数校验与响应格式

章节来源

• schema.prisma:107-119
• comments.service.ts:6-30
• comments.controller.ts:13-56

架构总览

评论功能的调用链路如下：

sequenceDiagram
participant Client as "客户端"
participant Router as "CommentsController"
participant Service as "CommentsService"
participant DB as "Prisma Client"
Client->>Router : "GET /api/comments/ : chapterId"
Router->>Service : "getCommentsByChapterId(chapterId)"
Service->>DB : "findMany(where : { chapterId }, orderBy : { createdAt : desc })"
DB-->>Service : "评论数组"
Service-->>Router : "评论数组"
Router-->>Client : "{ code : 0, data : comments }"
Client->>Router : "POST /api/comments { chapterId, content, rating }"
Router->>Service : "addComment(userId, chapterId, content, rating)"
Service->>DB : "create({ userId, chapterId, content, rating })"
DB-->>Service : "新建评论"
Service-->>Router : "新建评论"
Router-->>Client : "{ code : 0, data : comment }"

图表来源

• comments.controller.ts:13-56
• comments.service.ts:10-29
• index.ts:1-15

详细组件分析

Comment模型字段定义与关系

• 字段说明
  • id：自增主键
  • userId：外键，关联User.id
  • chapterId：外键，关联BookChapter.id
  • content：文本内容，支持长文本
  • rating：整型评分
  • createdAt：创建时间，默认当前时间
• 关系
  • belongsTo User：每个评论属于一个用户
  • belongsTo BookChapter：每个评论属于一个章节

• 索引

  • 在chapterId与userId上建立索引，以提升查询与关联性能

    erDiagram
    USER {
    int id PK
    string phone
    string openid
    string nickname
    string avatar
    }
    BOOKCHAPTER {
    int id PK
    int bookId
    int parentId
    int level
    int number
    string title
    }
    COMMENT {
    int id PK
    int userId FK
    int chapterId FK
    text content
    int rating
    datetime createdAt
    }
    USER ||--o{ COMMENT : "拥有"
    BOOKCHAPTER ||--o{ COMMENT : "被评论"
    

图表来源

• schema.prisma:107-119
• schema.prisma:10-38
• schema.prisma:161-192

章节来源

• schema.prisma:107-119

CommentsService：数据访问与业务逻辑

• 查询章节评论
  • 输入：chapterId
  • 行为：按创建时间倒序返回该章节的所有评论

• 新增评论

  • 输入：userId、chapterId、content、rating

  • 行为：创建一条新的评论记录

    classDiagram
    class CommentsService {
    +getCommentsByChapterId(chapterId) Promise~Comment[]~
    +addComment(userId, chapterId, content, rating) Promise~Comment~
    }
    class PrismaClient {
    +comment
    }
    CommentsService --> PrismaClient : "使用"
    

图表来源

• comments.service.ts:6-30
• index.ts:1-15

章节来源

• comments.service.ts:6-30

CommentsController：HTTP接口与响应包装

• GET /api/comments/:chapterId
  • 功能：按章节ID获取评论列表
  • 响应：统一格式，data为评论数组

• POST /api/comments

  • 功能：发表评论
  • 请求体：chapterId、content、rating

  • 响应：统一格式，data为新建评论

    flowchart TD
    Start(["请求进入"]) --> Parse["解析路径参数/请求体"]
    Parse --> Validate{"参数有效？"}
    Validate --> |否| ErrorResp["返回错误响应"]
    Validate --> |是| CallSvc["调用 CommentsService"]
    CallSvc --> OkResp["返回成功响应"]
    ErrorResp --> End(["结束"])
    OkResp --> End
    

图表来源

• comments.controller.ts:13-56

章节来源

• comments.controller.ts:13-56

安全与输入净化

• XSS防护与SQL注入防护中间件会对请求体与查询参数进行净化与校验，降低恶意输入风险
• 敏感数据脱敏中间件会在响应阶段对敏感字段进行脱敏处理

章节来源

• security.ts:6-102

API使用示例（基于现有实现）

以下示例展示如何使用现有接口进行评论相关操作。请根据实际部署地址替换域名与端口。

• 获取章节评论

  • 方法与路径：GET /api/comments/{chapterId}
  • 示例请求：curl -X GET http://localhost:3000/api/comments/123
  • 响应结构：见统一响应格式
  • 参考实现路径：comments.controller.ts:13-29

• 发表评论

  • 方法与路径：POST /api/comments
  • 请求体字段：chapterId、content、rating
  • 示例请求：curl -X POST http://localhost:3000/api/comments -H "Content-Type: application/json" -d '{"chapterId":123,"content":"好内容","rating":5}'
  • 响应结构：见统一响应格式
  • 参考实现路径：comments.controller.ts:35-56

• 统一响应格式

  • 所有接口遵循统一响应格式：code、message、data
  • 参考文档：API.md:488-498

章节来源

• comments.controller.ts:13-56
• API.md:488-498

评论层级结构与回复机制

• 当前实现
  • Comment模型未包含parentCommentId或replyTo等字段，不支持直接的回复嵌套
  • 评论列表按创建时间倒序展示
• 扩展建议（概念性）
  • 新增字段：parentCommentId、rootCommentId、level、threadId等，以支持树形回复
  • 新增接口：按threadId查询回复树、按rootCommentId分页查询
  • 新增权限控制：仅作者可删除自己的评论；管理员可删除违规评论

[本节为概念性扩展说明，不对应具体源码，故无章节来源]

评论审核流程、内容过滤与评分统计

• 当前实现
  • 未实现评论审核流程、内容过滤与评分统计
• 扩展建议（概念性）
  • 审核流程：新增status字段（如pending、approved、rejected），配合后台审核接口
  • 内容过滤：集成敏感词检测服务，在新增评论时进行拦截或标记
  • 评分统计：为BookChapter维护avgRating与ratingCount，按章节聚合统计

[本节为概念性扩展说明，不对应具体源码，故无章节来源]

依赖分析

• 控制器依赖服务：CommentsController依赖CommentsService执行业务逻辑
• 服务依赖ORM：CommentsService通过Prisma Client访问数据库

• 应用入口依赖控制器：app.ts注册评论路由

  graph LR
  CTRL["comments.controller.ts"] --> SVC["comments.service.ts"]
  SVC --> PRISMA["schema.prisma"]
  APP["app.ts"] --> CTRL
  

图表来源

• app.ts:99-129
• comments.controller.ts:1-59
• comments.service.ts:1-33
• schema.prisma:107-119

章节来源

• app.ts:99-129
• comments.controller.ts:1-59
• comments.service.ts:1-33
• schema.prisma:107-119

性能考量

• 查询性能
  • 在Comment的chapterId与userId上已建立索引，有利于按章节查询与用户评论聚合
• 写入性能
  • 新增评论为单条写入，开销较小
• 缓存策略（概念性）
  • 章节评论列表可按章节ID进行缓存，设置合理TTL
  • 评论总数与平均评分可缓存，异步更新
• 安全前置
  • XSS与SQL注入防护中间件在进入业务逻辑前进行净化，降低数据库压力与风险

章节来源

• schema.prisma:117-118
• security.ts:6-102

故障排查指南

• 常见错误
  • 参数错误：请求体或路径参数缺失导致400错误
  • 数据库连接失败：Prisma初始化异常
• 排查步骤
  • 检查路由注册是否正确：确认/app/comments路由已挂载
  • 检查数据库连接：确认Prisma连接成功
  • 检查请求格式：确保Content-Type为application/json且字段齐全
• 相关实现参考
  • 路由注册：app.ts:109
  • 数据库连接：index.ts:5-13
  • 控制器错误处理：comments.controller.ts:23-28

章节来源

• app.ts:109
• index.ts:5-13
• comments.controller.ts:23-28

结论

当前评论功能实现了基础的“按章节读取评论列表”和“发表评论”能力，具备清晰的数据模型与安全前置防护。若需支持回复、审核、内容过滤与评分统计等高级特性，可在现有基础上扩展模型字段与服务方法，并完善前端交互与后台管理界面。

附录

• 统一响应格式
  • 所有接口遵循统一响应格式：code、message、data
  • 参考文档：API.md:488-498