# 评论数据模型

<cite>
**本文引用的文件**
- [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)
</cite>

## 目录
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<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](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)