v1-backend/API文档.md

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）:

[
  {
    "filename": "230615_abcd1.png",
    "url": "/img/230615_abcd1.png",
    "upload_time": "2024-05-18 10:15:22"  // 图片上传时间
  }
]

• 错误响应: 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	服务器内部错误	备份恢复失败、数据库异常等系统级错误