> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2024921.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 评论

> 评论系统接口，支持嵌套回复、审核与重复发送拦截

## 获取文章评论

```http theme={null}
GET /api/posts/:id/comments
```

**响应：**

```json theme={null}
{
  "ok": true,
  "comments": [
    {
      "id": "评论ID",
      "post_id": "文章ID",
      "author": "评论者",
      "content": "内容",
      "date": "2025-01-01T00:00:00Z",
      "status": "approved",
      "parent_id": null
    }
  ]
}
```

## 发表评论

```http theme={null}
POST /api/posts/:id/comments
```

**请求体：**

```json theme={null}
{
  "author": "评论者名称",
  "content": "评论内容",
  "parentId": "父评论 ID（可选）"
}
```

<Info>
  无需认证，公开接口。有 IP 频率限制（每 IP 每分钟 5 条）与**重复发送拦截**（见下方安全机制）。
</Info>

**错误响应：**

| 状态码   | 场景                  | error 示例      |
| ----- | ------------------- | ------------- |
| `400` | 缺昵称/内容、超长度上限、评论数达上限 | `请填写昵称和内容`    |
| `403` | 跨站 Origin           | `来源校验失败`      |
| `409` | 同分区已存在完全相同的昵称+内容    | `请勿重复发送相同内容`  |
| `429` | 触发 IP 频率限制          | `评论太频繁，请稍后再试` |

前端 `saveComment` 会把后端 `error` 文案透传到表单状态行，用户可直接看到失败原因。

## 全局评论列表（管理）

```http theme={null}
GET /api/comments
Authorization: Bearer <token>
```

**查询参数：** `status`（approved/pending/空）、`page`、`pageSize`

**响应包含 `post_title` 字段，方便管理后台展示。**

## 更新 / 删除

```http theme={null}
PUT    /api/comments/:id    # 更新状态 {"status": "approved"}
DELETE /api/comments/:id    # 删除
```

都需要认证。

## 嵌套回复

评论通过 `parent_id` 支持一级嵌套：

```
评论 A
├── 回复 A1 (parent_id: A)
└── 回复 A2 (parent_id: A)
    └── 回复 A2-1 (parent_id: A2)
```

## 安全机制

| 机制        | 说明                                                             |
| --------- | -------------------------------------------------------------- |
| XSS 防护    | 输入自动转义，控制字符清洗（保留换行）                                            |
| SQL 注入    | 参数化查询                                                          |
| 频率限制      | 每 IP 每分钟 5 条（KV 计数）                                            |
| Origin 校验 | 验证请求来源，跨站 403                                                  |
| 重复发送拦截    | 同一分区（文章/留言板）下相同昵称+相同内容只允许一次，重复提交返回 **409**；防误触双击与脚本刷同文，跨分区互不影响 |

## 长度与数量上限

| 限制       | 值       |
| -------- | ------- |
| 昵称       | 30 字符   |
| 内容       | 1000 字符 |
| 单篇文章评论总数 | 300 条   |
| 单 IP 频率  | 每分钟 5 条 |