# 评论系统

<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)
- [security.ts](file://server/src/middleware/security.ts)
- [rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [redis.service.ts](file://server/src/services/redis.service.ts)
- [index.ts](file://server/src/models/index.ts)
- [index.ts](file://server/src/config/index.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为评论系统的完整技术文档，覆盖评论发布、查看、嵌套回复、点赞、删除等核心能力；详述评论数据模型设计、嵌套回复结构、评论审核机制；包含内容过滤、敏感词检测、违规处理流程；解释评论排序算法、热度计算、推荐展示机制；提供完整的评论 API 接口文档，涵盖评论树结构、分页查询、实时更新；包含评论统计、用户互动分析、社区治理机制；解释评论与内容系统的关联方式、通知推送、数据缓存策略；并给出评论安全防护、防刷机制、内容版权保护措施。

当前仓库中的评论模块处于基础实现阶段，支持按章节获取评论与发布评论，尚未包含嵌套回复、点赞、删除、审核、敏感词检测、热度/推荐等高级能力。本文在现有代码基础上，提出扩展方案与最佳实践，帮助团队在后续迭代中完善评论系统。

## 项目结构
评论系统位于后端服务的模块化结构中，采用 Koa + Prisma + Redis 的技术栈，路由注册于应用入口，控制器负责接口定义，服务层封装业务逻辑，Prisma 管理数据库模型，Redis 提供缓存与限流能力。

```mermaid
graph TB
subgraph "应用入口"
APP["app.ts<br/>注册路由与中间件"]
end
subgraph "评论模块"
CTRL["comments.controller.ts<br/>路由与控制器"]
SVC["comments.service.ts<br/>业务服务"]
end
subgraph "数据层"
PRISMA["schema.prisma<br/>Comment/BookChapter/User 模型"]
MODELS["models/index.ts<br/>Prisma 客户端"]
end
subgraph "安全与限流"
SEC["security.ts<br/>XSS/SQL 注入防护"]
RL["rate-limiter.ts<br/>限流中间件"]
end
subgraph "缓存"
REDIS["redis.service.ts<br/>Redis 服务"]
end
APP --> CTRL
CTRL --> SVC
SVC --> MODELS
MODELS --> PRISMA
APP --> SEC
APP --> RL
APP --> REDIS
```

图表来源
- [app.ts:109-128](file://server/src/app.ts#L109-L128)
- [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)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)
- [redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)

章节来源
- [app.ts:109-128](file://server/src/app.ts#L109-L128)
- [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)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)
- [redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)

## 核心组件
- 控制器层：提供评论接口，包括按章节获取评论与新增评论。
- 服务层：封装评论查询与新增的业务逻辑，使用 Prisma 访问数据库。
- 数据模型：基于 Prisma 的 Comment、BookChapter、User 模型，建立章节与评论的一对多关系。
- 安全中间件：提供 XSS 与 SQL 注入防护。
- 限流中间件：提供通用限流能力，可用于评论接口的速率控制。
- 缓存服务：提供 Redis 连接与常用操作，可用于评论缓存与防刷。

章节来源
- [comments.controller.ts:13-29](file://server/src/modules/comments/comments.controller.ts#L13-L29)
- [comments.controller.ts:35-56](file://server/src/modules/comments/comments.controller.ts#L35-L56)
- [comments.service.ts:10-15](file://server/src/modules/comments/comments.service.ts#L10-L15)
- [comments.service.ts:20-29](file://server/src/modules/comments/comments.service.ts#L20-L29)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)
- [redis.service.ts:42-45](file://server/src/services/redis.service.ts#L42-L45)

## 架构总览
评论系统采用典型的 MVC 架构，控制器负责接收请求与返回响应，服务层封装业务逻辑，数据层通过 Prisma ORM 访问 MySQL。应用入口集中注册路由与中间件，安全与限流中间件贯穿请求链路，Redis 作为缓存与限流存储。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "Koa 路由<br/>comments.controller.ts"
participant S as "评论服务<br/>comments.service.ts"
participant M as "Prisma 客户端<br/>models/index.ts"
participant DB as "MySQL"
C->>R : "GET /api/comments/ : chapterId"
R->>S : "getCommentsByChapterId(chapterId)"
S->>M : "comment.findMany(where, orderBy)"
M->>DB : "执行查询"
DB-->>M : "返回结果"
M-->>S : "评论列表"
S-->>R : "评论列表"
R-->>C : "JSON 响应"
Note over C,R : "新增评论流程类似，POST /api/comments"
```

图表来源
- [comments.controller.ts:13-29](file://server/src/modules/comments/comments.controller.ts#L13-L29)
- [comments.service.ts:10-15](file://server/src/modules/comments/comments.service.ts#L10-L15)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 详细组件分析

### 数据模型设计
- Comment 模型：包含评论主键、用户标识、章节标识、内容、评分、创建时间，并与 User、BookChapter 建立关系。
- BookChapter 模型：包含章节信息，与 Comment 建立一对多关系。
- User 模型：包含用户信息，与 Comment 建立一对多关系。

```mermaid
erDiagram
USER {
int id PK
string phone
string openid
string nickname
string avatar
int memberLevel
datetime createdAt
datetime updatedAt
}
BOOKCHAPTER {
int id PK
int bookId
int parentId
int level
int number
string title
int estimatedWords
int wordCount
boolean isPublic
datetime createdAt
datetime updatedAt
}
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:161-192](file://server/prisma/schema.prisma#L161-L192)
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)

章节来源
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
- [schema.prisma:161-192](file://server/prisma/schema.prisma#L161-L192)
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)

### 控制器与服务层
- 控制器：定义评论接口，处理请求参数并调用服务层方法，返回标准化响应。
- 服务层：使用 Prisma 查询与插入评论，支持按章节查询与新增评论。

```mermaid
classDiagram
class CommentsController {
+GET "/api/comments/ : chapterId"
+POST "/api/comments"
}
class CommentsService {
+getCommentsByChapterId(chapterId)
+addComment(userId, chapterId, content, rating)
}
class PrismaClient {
+comment.findMany()
+comment.create()
}
CommentsController --> CommentsService : "调用"
CommentsService --> PrismaClient : "使用"
```

图表来源
- [comments.controller.ts:13-29](file://server/src/modules/comments/comments.controller.ts#L13-L29)
- [comments.controller.ts:35-56](file://server/src/modules/comments/comments.controller.ts#L35-L56)
- [comments.service.ts:10-15](file://server/src/modules/comments/comments.service.ts#L10-L15)
- [comments.service.ts:20-29](file://server/src/modules/comments/comments.service.ts#L20-L29)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)

章节来源
- [comments.controller.ts:13-29](file://server/src/modules/comments/comments.controller.ts#L13-L29)
- [comments.controller.ts:35-56](file://server/src/modules/comments/comments.controller.ts#L35-L56)
- [comments.service.ts:10-15](file://server/src/modules/comments/comments.service.ts#L10-L15)
- [comments.service.ts:20-29](file://server/src/modules/comments/comments.service.ts#L20-L29)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)

### API 接口文档
- 获取章节评论
  - 方法与路径：GET /api/comments/:chapterId
  - 请求参数：路径参数 chapterId（整数）
  - 成功响应：包含 code、message、data（评论数组）
  - 异常响应：包含 code、message
- 发布评论
  - 方法与路径：POST /api/comments
  - 请求体：chapterId（整数）、content（字符串）、rating（整数）
  - 成功响应：包含 code、message、data（新增评论）
  - 异常响应：包含 code、message

章节来源
- [comments.controller.ts:13-29](file://server/src/modules/comments/comments.controller.ts#L13-L29)
- [comments.controller.ts:35-56](file://server/src/modules/comments/comments.controller.ts#L35-L56)

### 嵌套回复结构
当前实现未包含嵌套回复字段与层级关系。建议在 Comment 模型中增加 parentCommentId、level、threadId 等字段，以支持回复树结构与层级管理。

章节来源
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)

### 评论审核机制
当前实现未包含审核字段与审核流程。建议引入审核状态字段（如 pending、approved、rejected），并结合敏感词检测与人工审核流程。

章节来源
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)

### 内容过滤与敏感词检测
当前实现未包含敏感词检测。建议在服务层新增内容过滤步骤，调用敏感词检测服务并在必要时阻断或标记。

章节来源
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)

### 评论排序算法、热度计算、推荐展示
- 排序：当前按创建时间倒序排列。
- 热度：建议引入点赞数、回复数、时间衰减因子等综合计算。
- 推荐：建议基于用户画像与内容相似度进行个性化推荐。

章节来源
- [comments.service.ts:10-15](file://server/src/modules/comments/comments.service.ts#L10-L15)

### 评论统计、用户互动分析、社区治理
- 统计：评论数量、平均评分、热评排行。
- 互动：用户评论历史、互动趋势。
- 社区治理：举报机制、违规处理、等级权限。

章节来源
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)

### 评论与内容系统的关联、通知推送、数据缓存
- 关联：通过 BookChapter 与 Comment 的关系建立章节与评论的绑定。
- 通知：新增评论后触发通知推送（WebSocket/消息队列）。
- 缓存：使用 Redis 缓存热门章节评论与用户最近评论，降低数据库压力。

章节来源
- [schema.prisma:161-192](file://server/prisma/schema.prisma#L161-L192)
- [redis.service.ts:42-45](file://server/src/services/redis.service.ts#L42-L45)

### 安全防护、防刷机制、内容版权保护
- 安全：XSS 与 SQL 注入防护中间件已启用。
- 防刷：限流中间件可按 IP 或用户维度限制请求频率。
- 版权：内容脱敏与合规校验，敏感词拦截。

章节来源
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)
- [redis.service.ts:42-45](file://server/src/services/redis.service.ts#L42-L45)

## 依赖关系分析
- 控制器依赖服务层，服务层依赖 Prisma 客户端，Prisma 客户端依赖 MySQL。
- 应用入口注册评论路由并加载安全与限流中间件。
- Redis 作为可选依赖，用于缓存与限流。

```mermaid
graph LR
CTRL["comments.controller.ts"] --> SVC["comments.service.ts"]
SVC --> MODELS["models/index.ts"]
MODELS --> PRISMA["schema.prisma"]
APP["app.ts"] --> CTRL
APP --> SEC["security.ts"]
APP --> RL["rate-limiter.ts"]
APP --> REDIS["redis.service.ts"]
```

图表来源
- [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)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
- [app.ts:109-128](file://server/src/app.ts#L109-L128)
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)
- [redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)

章节来源
- [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)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [schema.prisma:107-119](file://server/prisma/schema.prisma#L107-L119)
- [app.ts:109-128](file://server/src/app.ts#L109-L128)
- [security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)
- [redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)

## 性能考量
- 数据库查询：按章节查询评论时，确保在 chapterId 上建立索引（模型已包含索引）。
- 缓存策略：热门章节评论与用户最近评论可缓存至 Redis，设置合理 TTL。
- 限流策略：针对评论接口设置合理的限流阈值，避免刷量。
- 并发控制：服务层方法串行化关键操作，避免并发写入导致的数据不一致。

章节来源
- [schema.prisma:117-118](file://server/prisma/schema.prisma#L117-L118)
- [redis.service.ts:42-45](file://server/src/services/redis.service.ts#L42-L45)
- [rate-limiter.ts:49-81](file://server/src/middleware/rate-limiter.ts#L49-L81)

## 故障排查指南
- 数据库连接失败：检查环境变量与 Prisma 客户端连接逻辑。
- Redis 连接失败：确认 Redis 服务状态与连接参数。
- 安全中间件拦截：若出现 400 响应，检查请求参数是否包含非法字符。
- 限流触发：若出现 429 响应，检查限流配置与请求频率。

章节来源
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [redis.service.ts:246-255](file://server/src/services/redis.service.ts#L246-L255)
- [security.ts:60-84](file://server/src/middleware/security.ts#L60-L84)
- [rate-limiter.ts:52-72](file://server/src/middleware/rate-limiter.ts#L52-L72)

## 结论
当前评论系统具备基础的评论查询与发布能力，数据模型清晰，安全与限流中间件已就绪。建议在下一阶段引入嵌套回复、审核机制、敏感词检测、热度与推荐、通知推送与缓存策略，以构建完整的评论生态。同时完善分页查询、实时更新与社区治理能力，提升用户体验与平台治理水平。

## 附录
- 配置中心：JWT、模型配置、上传目录等配置集中管理。
- 路由注册：应用入口统一注册评论路由与其他模块路由。

章节来源
- [index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [app.ts:109-128](file://server/src/app.ts#L109-L128)