# 评论数据模型
**本文引用的文件**
- [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)
- [app.ts](file://server/src/app.ts)
- [index.ts](file://server/src/models/index.ts)
- [security.ts](file://server/src/middleware/security.ts)
- [API.md](file://docs/API.md)
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 引言
本文件面向AI有声书生成平台的评论功能，提供评论数据模型的权威说明。重点涵盖Comment模型字段定义、与User和BookChapter的多对一关系、当前实现的评论读取与发表能力、以及在内容发现与质量评估中的作用。由于当前仓库中未实现评论删除、回复、审核与评分统计等高级功能，本文将基于现有代码进行准确描述，并在“概念性概述”部分给出扩展建议。
## 项目结构
评论功能位于后端服务的独立模块中，采用Koa路由+Prisma ORM的典型分层结构：
- 控制器层：负责HTTP路由与请求响应包装
- 服务层：封装业务逻辑与数据访问
- 数据模型：基于Prisma Schema定义实体关系
- 应用入口：注册路由并启动服务
```mermaid
graph TB
subgraph "应用入口"
APP["app.ts
注册路由与中间件"]
end
subgraph "评论模块"
CTRL["comments.controller.ts
路由与控制器"]
SVC["comments.service.ts
业务与数据访问"]
PRISMA["schema.prisma
Comment/User/BookChapter 关系"]
end
APP --> CTRL
CTRL --> SVC
SVC --> PRISMA
```
图表来源
- [app.ts:99-129](file://server/src/app.ts#L99-L129)
- [comments.controller.ts:1-59](file://server/src/modules/comments/comments.controller.ts#L1-L59)
- [comments.service.ts:1-33](file://server/src/modules/comments/comments.service.ts#L1-L33)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
章节来源
- [app.ts:99-129](file://server/src/app.ts#L99-L129)
- [comments.controller.ts:1-59](file://server/src/modules/comments/comments.controller.ts#L1-L59)
- [comments.service.ts:1-33](file://server/src/modules/comments/comments.service.ts#L1-L33)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
## 核心组件
- Comment模型：承载章节评论的文本内容、评分、创建时间，并与User和BookChapter建立多对一关系
- CommentsService：提供按章节查询评论列表、新增评论的业务方法
- CommentsController：提供HTTP接口，封装请求参数校验与响应格式
章节来源
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
- [comments.service.ts:6-30](file://server/src/modules/comments/comments.service.ts#L6-L30)
- [comments.controller.ts:13-56](file://server/src/modules/comments/comments.controller.ts#L13-L56)
## 架构总览
评论功能的调用链路如下：
```mermaid
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](file://server/src/modules/comments/comments.controller.ts#L13-L56)
- [comments.service.ts:10-29](file://server/src/modules/comments/comments.service.ts#L10-L29)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
## 详细组件分析
### Comment模型字段定义与关系
- 字段说明
- id：自增主键
- userId：外键，关联User.id
- chapterId：外键，关联BookChapter.id
- content：文本内容，支持长文本
- rating：整型评分
- createdAt：创建时间，默认当前时间
- 关系
- belongsTo User：每个评论属于一个用户
- belongsTo BookChapter：每个评论属于一个章节
- 索引
- 在chapterId与userId上建立索引，以提升查询与关联性能
```mermaid
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](file://server/prisma/schema.prisma#L107-L119)
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)
- [schema.prisma:161-192](file://server/prisma/schema.prisma#L161-L192)
章节来源
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
### CommentsService：数据访问与业务逻辑
- 查询章节评论
- 输入：chapterId
- 行为：按创建时间倒序返回该章节的所有评论
- 新增评论
- 输入：userId、chapterId、content、rating
- 行为：创建一条新的评论记录
```mermaid
classDiagram
class CommentsService {
+getCommentsByChapterId(chapterId) Promise~Comment[]~
+addComment(userId, chapterId, content, rating) Promise~Comment~
}
class PrismaClient {
+comment
}
CommentsService --> PrismaClient : "使用"
```
图表来源
- [comments.service.ts:6-30](file://server/src/modules/comments/comments.service.ts#L6-L30)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
章节来源
- [comments.service.ts:6-30](file://server/src/modules/comments/comments.service.ts#L6-L30)
### CommentsController：HTTP接口与响应包装
- GET /api/comments/:chapterId
- 功能：按章节ID获取评论列表
- 响应：统一格式，data为评论数组
- POST /api/comments
- 功能：发表评论
- 请求体：chapterId、content、rating
- 响应：统一格式，data为新建评论
```mermaid
flowchart TD
Start(["请求进入"]) --> Parse["解析路径参数/请求体"]
Parse --> Validate{"参数有效？"}
Validate --> |否| ErrorResp["返回错误响应"]
Validate --> |是| CallSvc["调用 CommentsService"]
CallSvc --> OkResp["返回成功响应"]
ErrorResp --> End(["结束"])
OkResp --> End
```
图表来源
- [comments.controller.ts:13-56](file://server/src/modules/comments/comments.controller.ts#L13-L56)
章节来源
- [comments.controller.ts:13-56](file://server/src/modules/comments/comments.controller.ts#L13-L56)
### 安全与输入净化
- XSS防护与SQL注入防护中间件会对请求体与查询参数进行净化与校验，降低恶意输入风险
- 敏感数据脱敏中间件会在响应阶段对敏感字段进行脱敏处理
章节来源
- [security.ts:6-102](file://server/src/middleware/security.ts#L6-L102)
### API使用示例（基于现有实现）
以下示例展示如何使用现有接口进行评论相关操作。请根据实际部署地址替换域名与端口。
- 获取章节评论
- 方法与路径：GET /api/comments/{chapterId}
- 示例请求：curl -X GET http://localhost:3000/api/comments/123
- 响应结构：见统一响应格式
- 参考实现路径：[comments.controller.ts:13-29](file://server/src/modules/comments/comments.controller.ts#L13-L29)
- 发表评论
- 方法与路径：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](file://server/src/modules/comments/comments.controller.ts#L35-L56)
- 统一响应格式
- 所有接口遵循统一响应格式：code、message、data
- 参考文档：[API.md:488-498](file://docs/API.md#L488-L498)
章节来源
- [comments.controller.ts:13-56](file://server/src/modules/comments/comments.controller.ts#L13-L56)
- [API.md:488-498](file://docs/API.md#L488-L498)
### 评论层级结构与回复机制
- 当前实现
- Comment模型未包含parentCommentId或replyTo等字段，不支持直接的回复嵌套
- 评论列表按创建时间倒序展示
- 扩展建议（概念性）
- 新增字段：parentCommentId、rootCommentId、level、threadId等，以支持树形回复
- 新增接口：按threadId查询回复树、按rootCommentId分页查询
- 新增权限控制：仅作者可删除自己的评论；管理员可删除违规评论
[本节为概念性扩展说明，不对应具体源码，故无章节来源]
### 评论审核流程、内容过滤与评分统计
- 当前实现
- 未实现评论审核流程、内容过滤与评分统计
- 扩展建议（概念性）
- 审核流程：新增status字段（如pending、approved、rejected），配合后台审核接口
- 内容过滤：集成敏感词检测服务，在新增评论时进行拦截或标记
- 评分统计：为BookChapter维护avgRating与ratingCount，按章节聚合统计
[本节为概念性扩展说明，不对应具体源码，故无章节来源]
## 依赖分析
- 控制器依赖服务：CommentsController依赖CommentsService执行业务逻辑
- 服务依赖ORM：CommentsService通过Prisma Client访问数据库
- 应用入口依赖控制器：app.ts注册评论路由
```mermaid
graph LR
CTRL["comments.controller.ts"] --> SVC["comments.service.ts"]
SVC --> PRISMA["schema.prisma"]
APP["app.ts"] --> CTRL
```
图表来源
- [app.ts:99-129](file://server/src/app.ts#L99-L129)
- [comments.controller.ts:1-59](file://server/src/modules/comments/comments.controller.ts#L1-L59)
- [comments.service.ts:1-33](file://server/src/modules/comments/comments.service.ts#L1-L33)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
章节来源
- [app.ts:99-129](file://server/src/app.ts#L99-L129)
- [comments.controller.ts:1-59](file://server/src/modules/comments/comments.controller.ts#L1-L59)
- [comments.service.ts:1-33](file://server/src/modules/comments/comments.service.ts#L1-L33)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
## 性能考量
- 查询性能
- 在Comment的chapterId与userId上已建立索引，有利于按章节查询与用户评论聚合
- 写入性能
- 新增评论为单条写入，开销较小
- 缓存策略（概念性）
- 章节评论列表可按章节ID进行缓存，设置合理TTL
- 评论总数与平均评分可缓存，异步更新
- 安全前置
- XSS与SQL注入防护中间件在进入业务逻辑前进行净化，降低数据库压力与风险
章节来源
- [schema.prisma:117-118](file://server/prisma/schema.prisma#L117-L118)
- [security.ts:6-102](file://server/src/middleware/security.ts#L6-L102)
## 故障排查指南
- 常见错误
- 参数错误：请求体或路径参数缺失导致400错误
- 数据库连接失败：Prisma初始化异常
- 排查步骤
- 检查路由注册是否正确：确认/app/comments路由已挂载
- 检查数据库连接：确认Prisma连接成功
- 检查请求格式：确保Content-Type为application/json且字段齐全
- 相关实现参考
- 路由注册：[app.ts:109](file://server/src/app.ts#L109)
- 数据库连接：[index.ts:5-13](file://server/src/models/index.ts#L5-L13)
- 控制器错误处理：[comments.controller.ts:23-28](file://server/src/modules/comments/comments.controller.ts#L23-L28)
章节来源
- [app.ts:109](file://server/src/app.ts#L109)
- [index.ts:5-13](file://server/src/models/index.ts#L5-L13)
- [comments.controller.ts:23-28](file://server/src/modules/comments/comments.controller.ts#L23-L28)
## 结论
当前评论功能实现了基础的“按章节读取评论列表”和“发表评论”能力，具备清晰的数据模型与安全前置防护。若需支持回复、审核、内容过滤与评分统计等高级特性，可在现有基础上扩展模型字段与服务方法，并完善前端交互与后台管理界面。
## 附录
- 统一响应格式
- 所有接口遵循统一响应格式：code、message、data
- 参考文档：[API.md:488-498](file://docs/API.md#L488-L498)