# Sycamore_whisper API 文档

**

## 一、基础信息

| 项目       | 内容                                                         |
| ---------- | ------------------------------------------------------------ |
| 响应格式   | 所有 API 响应均为 JSON 格式（除非特殊说明）                  |
| 成功状态码 | 通常为 200（请求成功）或 201（资源创建成功）                 |
| 权限说明   | 管理接口需在请求头中携带 Authorization: Bearer {ADMIN_TOKEN} 进行身份验证 |

## 二、通用说明

1. 错误响应均会附带明确错误信息，帮助定位问题；

2. 图片上传大小限制为 10MB，支持常见图片格式(png, jpg, jpeg, gif, webp)；
3. 分页接口默认按 “ID 降序” 排列数据，未指定页码时默认返回第 1 页；
4. 涉及 “帖子 ID”“评论 ID”“举报 ID” 的接口，若 ID 不存在则返回 404 错误。

## 三、公共接口（无需管理员权限）

### 3.1 提交帖子

- **URL**: /post

- **请求方法**: POST

- **功能描述**: 提交新帖子内容，是否需要审核取决于当前系统审核模式

- **请求体（JSON）**:

```
{
  "content": "帖子内容"
}
```

- **成功响应（201 Created）**:

```
{
  "id": 1,  // 新创建帖子的ID
  "status": "Pending"  // 状态：Pending（待审核）/ Pass（直接通过，无需审核）
}
```

- **错误响应**:

- - 400 Bad Request：帖子内容为空

- - 403 Forbidden：内容包含违规关键词

### 3.2 帖子点赞 / 点踩

#### 3.2.1 帖子点赞

- **URL**: /up

- **请求方法**: POST

- **功能描述**: 给指定 ID 的帖子点赞

- **请求体（JSON）**:

```
{
  "id": 1  // 帖子ID（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**:

- - 400 Bad Request：缺少帖子 ID

- - 404 Not Found：帖子不存在

#### 3.2.2 帖子点踩

- **URL**: /down

- **请求方法**: POST

- **请求体、成功响应、错误响应**：与 “帖子点赞” 接口完全一致

### 3.3 发布评论

- **URL**: /comment

- **请求方法**: POST

- **功能描述**: 给帖子添加顶级评论，或回复已有评论

- **请求体（JSON）**:

```
{
  "content": "评论内容",
  "submission_id": 1,  // 关联的帖子ID
  "parent_comment_id": 0,  // 父评论ID：0=顶级评论，非0=回复指定评论
  "nickname": "匿名用户"  // 用户名
}
```

- **成功响应（200 OK）**:

```
{
  "id": 1,  // 新创建评论的ID
  "status": "Pass"
}
```

- **错误响应**:

- - 400 Bad Request：缺少 content/submission_id/parent_comment_id，或 parent_comment_id 指向不存在的评论

- - 403 Forbidden：评论内容包含违规关键词

- - 404 Not Found：关联的帖子不存在

### 3.4 图片上传与访问

#### 3.4.1 上传图片

- **URL**: /upload_pic

- **请求方法**: POST

- **请求体格式**: multipart/form-data，需包含名为file的图片文件

- **功能描述**: 上传图片至服务器，返回图片访问 URL

- **成功响应（201 Created）**:

```
{
  "status": "OK",
  "url": "/img/230615_abcd1.png"  // 图片访问URL
}
```

- **错误响应**:

- - 400 Bad Request：未上传文件、文件格式不支持（非图片）、文件大小超过 10MB

#### 3.4.2 访问图片

- **URL**: /img/{filename} （{filename} 替换为图片文件名，如 230615_abcd1.png）

- **请求方法**: GET

- **功能描述**: 通过文件名直接访问图片

- **成功响应（200 OK）**: 返回图片文件（如 PNG/JPG 格式）

- **错误响应**: 403 Forbidden：访问的文件格式不允许（非图片文件）

### 3.5 举报与状态查询

#### 3.5.1 提交举报

- **URL**: /report

- **请求方法**: POST

- **功能描述**: 举报违规帖子，需提供举报标题和具体理由

- **请求体（JSON）**:

```
{
  "id": 1,  // 被举报帖子的ID（必填）
  "title": "举报标题（必填，如“帖子包含广告”）",
  "content": "举报内容（必填，详细说明违规点）"
}
```

- **成功响应（201 Created）**:

```
{
  "id": 1,  // 举报记录的ID
  "status": "OK"
}
```

- **错误响应**:

- - 400 Bad Request：缺少 id/title/content

- - 404 Not Found：被举报的帖子不存在

#### 3.5.2 获取帖子状态

- **URL**: /get/post_state

- **请求方法**: GET

- **请求参数（Query）**: id=1（帖子 ID，必填）

- **功能描述**: 查询指定帖子的审核状态

- **成功响应（200 OK）**:

```
{
  "status": "Approved" | "Rejected" | "Pending" | "Deleted or Not Found"
  // Approved=已通过，Rejected=已拒绝，Pending=待审核，Deleted or Not Found=已删除或不存在
}
```

- **错误响应**: 400 Bad Request：缺少帖子 ID

#### 3.5.3 获取举报状态

- **URL**: /get/report_state

- **请求方法**: GET

- **请求参数（Query）**: id=1（举报 ID，必填）

- **功能描述**: 查询指定举报的处理状态

- **成功响应（200 OK）**:

```
{
  "status": "Approved" | "Rejected" | "Pending" | "Deleted or Not Found"
  // Approved=举报通过（帖子已处理），Rejected=举报驳回，Pending=待处理，Deleted or Not Found=举报记录已删除或不存在
}
```

- **错误响应**: 400 Bad Request：缺少举报 ID

### 3.6 帖子详情与列表

#### 3.6.1 获取帖子详情

- **URL**: /get/post_info

- **请求方法**: GET

- **请求参数（Query）**: id=1（帖子 ID，必填）

- **功能描述**: 查询已通过审核的帖子详情（含点赞 / 点踩数）

- **成功响应（200 OK）**:

```
{
  "id": 1,
  "content": "帖子内容",
  "upvotes": 10,  // 点赞数
  "downvotes": 2  // 点踩数
}
```

- **错误响应**:

- - 400 Bad Request：缺少帖子 ID

- - 404 Not Found：帖子不存在或未通过审核

#### 3.6.2 获取帖子评论

- **URL**: /get/comment

- **请求方法**: GET

- **请求参数（Query）**: id=1（帖子 ID，必填）

- **功能描述**: 查询指定帖子的所有评论

- **成功响应（200 OK）**:

```
[
  {
    "id": 1,
    "nickname": "用户名",
    "content": "评论内容",
    "parent_comment_id": 0  // 0=顶级评论，非0=回复评论
  }
]
```

- **错误响应**:

- - 400 Bad Request：缺少帖子 ID

- - 404 Not Found：帖子不存在或未通过审核

#### 3.6.3 分页获取帖子列表

- **URL**: /get/10_info

- **请求方法**: GET

- **请求参数（Query）**: page=1（页码，可选，默认 1）

- **功能描述**: 分页返回已通过审核的帖子，每页 10 条，按 ID 降序排列

- **成功响应（200 OK）**:

```
[
  {
    "id": 1,
    "content": "帖子内容",
    "upvotes": 10,
    "downvotes": 2
  }
]
```

### 3.7 其他公共接口

#### 3.7.1 获取统计信息

- **URL**: /get/statics

- **请求方法**: GET

- **功能描述**: 查询系统总数据统计（帖子、评论、图片数量）

- **成功响应（200 OK）**:

```
{
  "posts": 100,  // 总帖子数
  "comments": 500,  // 总评论数
  "images": 50  // 总图片数
}
```

#### 3.7.2 测试接口

- **URL**: /test

- **请求方法**: GET / POST

- **功能描述**: 验证 API 服务是否正常运行

- **成功响应（200 OK）**: API OK!!!（文本格式）

#### 3.7.3 获取 API 信息

- **URL**: /get/api_info

- **请求方法**: GET

- **功能描述**: 获取 API 版本、开发者等信息

- **成功响应（200 OK）**: 返回包含 API 信息的 HTML 页面

#### 3.7.4 茶壶彩蛋

- **URL**: /get/teapot

- **请求方法**: GET

- **响应**: 418 I'm a teapot

## 四、管理接口

### 4.1 审核模式管理

#### 4.1.1 切换审核模式

- **URL**: /admin/need_audit

- **请求方法**: POST

- **功能描述**: 开启 / 关闭帖子审核模式（开启后新帖子需审核才能通过）

- **请求体（JSON）**:

```
{
  "need_audit": true | false  // true=开启审核，false=关闭审核（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**:

- - 400 Bad Request：缺少 need_audit 参数，或参数不是布尔值

- - 401 Unauthorized / 403 Forbidden：管理员权限验证失败

#### 4.1.2 获取当前审核模式

- **URL**: /admin/get/need_audit

- **请求方法**: GET

- **功能描述**: 查询当前系统的帖子审核模式

- **成功响应（200 OK）**:

```
{
  "status": true | false  // true=开启审核，false=关闭审核
}
```

- **错误响应**: 401/403：管理员权限验证失败

### 4.2 帖子管理

#### 4.2.1 审核通过帖子

- **URL**: /admin/approve

- **请求方法**: POST

- **功能描述**: 将待审核的帖子标记为 “已通过”

- **请求体（JSON）**:

```
{
  "id": 1  // 待审核帖子的ID（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 401/403：权限失败；400：缺少 ID；404：帖子不存在

#### 4.2.2 拒绝帖子

- **URL**: /admin/disapprove

- **请求方法**: POST

- **请求体、成功响应、错误响应**：与 “审核通过帖子” 接口一致

#### 4.2.3 重新审核帖子

- **URL**: /admin/reaudit

- **请求方法**: POST

- **功能描述**: 将已通过审核的帖子重新标记为 “待审核”

- **请求体、成功响应、错误响应**：与 “审核通过帖子” 接口一致

#### 4.2.4 删除帖子

- **URL**: /admin/del_post

- **请求方法**: POST

- **功能描述**: 永久删除指定帖子

- **请求体（JSON）**:

```
{
  "id": 1  // 帖子ID（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 401/403：权限失败；400：缺少 ID；404：帖子不存在

#### 4.2.5 修改帖子

- **URL**: /admin/modify_post

- **请求方法**: POST

- **功能描述**: 修改指定帖子的内容

- **请求体（JSON）**:

```
{
  "id": 1,  // 帖子ID（必填）
  "content": "新的帖子内容（必填）"
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 401/403：权限失败；400：缺少 ID 或 content；404：帖子不存在

### 4.3 评论与图片管理

#### 4.3.1 删除评论

- **URL**: /admin/del_comment

- **请求方法**: POST

- **功能描述**: 永久删除指定评论

- **请求体（JSON）**:

```
{
  "id": 1  // 评论ID（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 401/403：权限失败；400：缺少 ID；404：评论不存在

#### 4.3.2 修改评论

- **URL**: /admin/modify_comment

- **请求方法**: POST

- **功能描述**: 修改指定评论的内容、用户名或父评论 ID

- **请求体（JSON）**:

```
{
  "id": 1,  // 评论ID（必填）
  "content": "新评论内容（必填）",
  "parent_comment_id": 0,  // 新的父评论ID（必填）
  "nickname": "新用户名（必填）"
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 401/403：权限失败；400：缺少必填字段；404：评论或父评论不存在

#### 4.3.3 删除图片

- **URL**: /admin/del_pic

- **请求方法**: POST

- **功能描述**: 永久删除服务器上的指定图片

- **请求体（JSON）**:

```
{
  "filename": "230615_abcd1.png"  // 图片文件名（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 401/403：权限失败；400：缺少 filename；404：图片不存在

### 4.4 举报管理

#### 4.4.1 批准举报

- **URL**: /admin/approve_report

- **请求方法**: POST

- **功能描述**: 批准用户提交的举报，系统将自动删除被举报的违规帖子

- **请求体（JSON）**:

```
{
  "id": 1  // 举报记录的ID（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**:

- - 401/403：管理员权限验证失败

- - 400 Bad Request：缺少举报 ID

- - 404 Not Found：举报记录不存在或已处理

#### 4.4.2 拒绝举报

- **URL**: /admin/reject_report

- **请求方法**: POST

- **功能描述**: 驳回用户提交的举报，被举报帖子将保持原有状态

- **请求体（JSON）**:

```
{
  "id": 1  // 举报记录的ID（必填）
}
```

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**: 与 “批准举报” 接口完全一致

### 4.5 数据备份与恢复

#### 4.5.1 创建备份

- **URL**: /admin/get/backup

- **请求方法**: GET

- **功能描述**: 自动备份系统数据库（含帖子、评论、举报数据）和所有上传图片，生成 ZIP 格式压缩包供下载

- **成功响应（200 OK）**: 返回 ZIP 格式的备份文件（文件名为 “backup_YYYYMMDD_HHMMSS.zip”，如 “backup_20240520_143025.zip”）

- **错误响应**: 401/403：管理员权限验证失败

#### 4.5.2 恢复备份

- **URL**: /admin/recover

- **请求方法**: POST

- **请求体格式**: multipart/form-data，需包含名为backup_file的 ZIP 备份文件

- **功能描述**: 从备份文件恢复系统数据（覆盖现有数据库和图片，操作不可逆，建议提前二次备份）

- **成功响应（200 OK）**:

```
{
  "status": "OK"
}
```

- **错误响应**:

- - 401/403：管理员权限验证失败

- - 400 Bad Request：未上传文件、文件不是 ZIP 格式或备份文件损坏

- - 500 Internal Server Error：恢复过程中出现数据错误

### 4.6 管理端数据查询

#### 4.6.1 获取待审核帖子

- **URL**: /admin/get/pending_posts

- **请求方法**: GET

- **功能描述**: 查询系统中所有状态为 “待审核” 的帖子列表（含未通过普通用户查询的待审核内容）

- **成功响应（200 OK）**:

```
[
  {
    "id": 1,
    "content": "待审核的帖子内容",
    "create_time": "2024-05-20 14:20:30",  // 帖子创建时间
    "upvotes": 0,
    "downvotes": 0
  }
]
```

- **错误响应**: 401/403：管理员权限验证失败

#### 4.6.2 获取已拒绝帖子

- **URL**: /admin/get/reject_posts

- **请求方法**: GET

- **功能描述**: 查询系统中所有状态为 “已拒绝” 的帖子列表

- **成功响应（200 OK）**: 格式与 “获取待审核帖子” 一致，仅包含 “已拒绝” 状态的帖子

- **错误响应**: 401/403：管理员权限验证失败

#### 4.6.3 获取图片链接列表

- **URL**: /admin/get/pic_links

- **请求方法**: GET

- **请求参数（Query）**: page=1（页码，可选，默认 1，每页返回 20 条图片链接）

- **功能描述**: 查询系统中所有已上传图片的访问 URL 和文件名

- **成功响应（200 OK）**:

```
[
    "/img/251012_nfXWz.png",
    "/img/251012_JrTrD.png",
    "/img/251012_sk7ll.png",
    "/img/251012_8efux.png",
    "/img/251012_zK8fz.jpg",
    "/img/251012_B0nkO.jpg",
    "/img/251012_nNV3o.png"
]
```

- **错误响应**: 401/403：管理员权限验证失败

#### 4.6.4 获取待处理举报

- **URL**: /admin/get/pending_reports

- **请求方法**: GET

- **功能描述**: 查询系统中所有状态为 “待处理” 的举报记录列表

- **成功响应（200 OK）**:

```
[
  {
    "id": 1,  // 举报ID
    "reported_post_id": 2,  // 被举报帖子ID
    "reported_post_content": "被举报的帖子内容",  // 被举报帖子内容（便于审核）
    "title": "举报标题",
    "content": "举报详细内容",
    "submit_time": "2024-05-20 15:00:45"  // 举报提交时间
  }
]
```

- **错误响应**: 401/403：管理员权限验证失败

### 4.7 管理员工具接口

#### 4.7.1 管理员测试接口

- **URL**: /admin/test

- **请求方法**: GET / POST

- **功能描述**: 验证管理员权限接口是否正常运行（需携带管理员 Token）

- **成功响应（200 OK）**: Admin API OK!!!（文本格式）

- **错误响应**: 401/403：管理员权限验证失败

#### 4.7.2 获取管理员视角的帖子详情

- **URL**: /admin/get/post_info

- **请求方法**: GET

- **请求参数（Query）**: id=1（帖子 ID，必填）

- **功能描述**: 查看指定帖子的完整信息（含创建时间、更新时间、审核状态，不受 “未通过审核” 限制）

- **成功响应（200 OK）**:

```
{
  "id": 1,
  "content": "帖子内容",
  "status": "Pending",  // 帖子状态：Approved/Rejected/Pending
  "create_time": "2024-05-20 14:20:30",
  "update_time": "2024-05-20 14:20:30",  // 最后更新时间（如审核时间、修改时间）
  "upvotes": 10,
  "downvotes": 2
}
```

- **错误响应**:

- - 401/403：管理员权限验证失败

- - 400 Bad Request：缺少帖子 ID

- - 404 Not Found：帖子不存在

## 五、附录

### 5.1 常见状态码说明

| 状态码                    | 含义           | 适用场景                                               |
| ------------------------- | -------------- | ------------------------------------------------------ |
| 200 OK                    | 请求成功       | 点赞、获取数据、修改内容等操作成功                     |
| 201 Created               | 资源创建成功   | 提交帖子、上传图片、提交举报等创建新资源的操作         |
| 400 Bad Request           | 请求参数错误   | 缺少必填字段、参数格式错误（如非布尔值、非数字 ID）    |
| 401 Unauthorized          | 未授权         | 访问管理接口未携带管理员 Token                         |
| 403 Forbidden             | 权限拒绝       | 携带无效 Token、内容含违规关键词、访问不允许的文件格式 |
| 404 Not Found             | 资源不存在     | 帖子 ID / 评论 ID / 举报 ID / 图片文件名不存在         |
| 418 I'm a teapot          | 彩蛋状态码     | 访问/get/teapot接口                                    |
| 500 Internal Server Error | 服务器内部错误 | 备份恢复失败、数据库异常等系统级错误                   |