From 8e0e78334392f1fec6ba621a56cc08855bcb575f Mon Sep 17 00:00:00 2001 From: LeonspaceX Date: Sun, 12 Oct 2025 18:47:08 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8Dbug?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- API文档.md | 1204 ++++++++++++++++++++++++++++++++----------------- api_server.py | 22 +- 2 files changed, 811 insertions(+), 415 deletions(-) diff --git a/API文档.md b/API文档.md index a831d07..a395355 100644 --- a/API文档.md +++ b/API文档.md @@ -1,461 +1,853 @@ -### ✅ **一、普通用户接口** +# Sycamore_whisper API 文档 -#### 1. 提交文章 -- **URL**: `POST /post` -- **请求参数（JSON）**: - ```json - { "content": "你的文章内容" } - ``` -- **返回**: - - ```json - { "id": 123, "status": "Pass" } // 或 "Pending"（若需审核） - ``` -- **说明**：内容含违禁词则拒绝（403），空内容则报错（400） +** ---- +## 一、基础信息 -#### 2. 点赞文章 -- **URL**: `POST /up` -- **请求参数（JSON）**: - ```json - { "id": 123 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +| 项目 | 内容 | +| ---------- | ------------------------------------------------------------ | +| 响应格式 | 所有 API 响应均为 JSON 格式（除非特殊说明） | +| 成功状态码 | 通常为 200（请求成功）或 201（资源创建成功） | +| 权限说明 | 管理接口需在请求头中携带 Authorization: Bearer {ADMIN_TOKEN} 进行身份验证 | ---- +## 二、通用说明 -#### 3. 反对文章（踩） -- **URL**: `POST /down` -- **请求参数（JSON）**: - ```json - { "id": 123 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +1. 错误响应均会附带明确错误信息，帮助定位问题； ---- +2. 图片上传大小限制为 10MB，支持常见图片格式(png, jpg, jpeg, gif, webp)； +3. 分页接口默认按 “ID 降序” 排列数据，未指定页码时默认返回第 1 页； +4. 涉及 “帖子 ID”“评论 ID”“举报 ID” 的接口，若 ID 不存在则返回 404 错误。 -#### 4. 发布评论 -- **URL**: `POST /comment` -- **请求参数（JSON）**: - ```json +## 三、公共接口（无需管理员权限） + +### 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": "评论内容", - "submission_id": 123, - "parent_comment_id": 0, // 回复父评论时填 ID - "nickname": "昵称" // 可为空，自动为“匿名用户” + "parent_comment_id": 0 // 0=顶级评论，非0=回复评论 } - ``` -- **返回**: - ```json - { "id": 456, "status": "Pass" } - ``` -- **说明**：违禁词拒绝（403），无效文章或父评论 ID 返回对应错误码 +] +``` ---- +- **错误响应**: -#### 5. 上传图片 -- **URL**: `POST /upload_pic` -- **请求参数**： - - 表单字段：`file`（文件），支持 `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` -- **返回**: - ```json - { "status": "OK", "url": "/img/240510_aBc12.png" } - ``` -- **限制**：文件大小 ≤10MB，格式正确 +- - 400 Bad Request：缺少帖子 ID ---- +- - 404 Not Found：帖子不存在或未通过审核 -#### 6. 获取文章状态（是否通过审核） -- **URL**: `GET /get/post_state` -- **参数（query）**: - - `id=123` -- **返回**: - ```json - { "status": "Approved" } // 通过 - { "status": "Pending" } // 待审核 - { "status": "Rejected" } // 拒绝 - { "status": "Deleted or Not Found" } // 不存在 - ``` +#### 3.6.3 分页获取帖子列表 ---- +- **URL**: /get/10_info -#### 7. 获取投诉状态 -- **URL**: `GET /get/report_state` -- **参数（query）**: - - `id=789` -- **返回**: - ```json - { "status": "Approved" } // 已通过 - { "status": "Pending" } // 待处理 - { "status": "Rejected" } // 已拒绝 - ``` +- **请求方法**: GET ---- +- **请求参数（Query）**: page=1（页码，可选，默认 1） -#### 8. 获取公开文章详情（仅通过审核的） -- **URL**: `GET /get/post_info` -- **参数（query）**: - - `id=123` -- **返回**: - ```json +- **功能描述**: 分页返回已通过审核的帖子，每页 10 条，按 ID 降序排列 + +- **成功响应（200 OK）**: + +``` +[ { - "id": 123, - "content": "文章内容", - "created_at": "2024-05-10T12:00:00+00:00", - "updated_at": "2024-05-10T12:00:00+00:00", - "upvotes": 5, - "downvotes": 1 + "id": 1, + "content": "帖子内容", + "upvotes": 10, + "downvotes": 2 } - ``` +] +``` ---- +### 3.7 其他公共接口 -#### 9. 获取评论列表 -- **URL**: `GET /get/comment` -- **参数（query）**: - - `id=123` -- **返回**: - ```json - [ - { - "id": 456, - "nickname": "张三", - "content": "这是一条评论", - "parent_comment_id": 0, - "upvotes": 2, - "downvotes": 0, - "created_at": "2024-05-10T12:05:00+00:00" - } - ] - ``` +#### 3.7.1 获取统计信息 ---- +- **URL**: /get/statics -#### 10. 获取最新10条文章列表（分页） -- **URL**: `GET /get/10_info` -- **参数（query）**: - - `page=1`（可选，缺省为1） -- **返回**: - ```json - [ - { - "id": 123, - "content": "文章内容", - "created_at": "2024-05-10T12:00:00+00:00", - "updated_at": "2024-05-10T12:00:00+00:00", - "upvotes": 114, - "downvotes": 514, - "status": "Pass" - } - ] - ``` +- **请求方法**: GET ---- +- **功能描述**: 查询系统总数据统计（帖子、评论、图片数量） -#### 11. 获取系统统计信息 -- **URL**: `GET /get/statics` -- **返回**: - ```json +- **成功响应（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）**: + +``` +[ { - "posts": 150, - "comments": 300, - "images": 80 + "id": 1, + "content": "待审核的帖子内容", + "create_time": "2024-05-20 14:20:30", // 帖子创建时间 + "upvotes": 0, + "downvotes": 0 } - ``` +] +``` ---- +- **错误响应**: 401/403：管理员权限验证失败 -#### 12. 提交投诉 -- **URL**: `POST /report` -- **请求参数（JSON）**: - - ```json +#### 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）**: + +``` +[ { - "id": 123, + "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": "举报原因" + "content": "举报详细内容", + "submit_time": "2024-05-20 15:00:45" // 举报提交时间 } - ``` -- **返回**: - ```json - { "id": 101, "status": "OK" } - ``` +] +``` ---- +- **错误响应**: 401/403：管理员权限验证失败 -### ✅ **二、管理后台接口（需要 Bearer Token）** +### 4.7 管理员工具接口 -> **调用方式**：在请求头加上： -> ``` -> Authorization: Bearer your_admin_token -> ``` +#### 4.7.1 管理员测试接口 -#### 1. 查看文章详情（完整信息） -- **URL**: `GET /admin/get/post_info` -- **参数（query）**: - - `id=123` -- **返回**： - ```json - { - "id": 123, - "content": "文章内容", - "created_at": "2024-05-10T12:00:00+00:00", - "updated_at": "2024-05-10T12:00:00+00:00", - "status": "Pass", - "upvotes": 5, - "downvotes": 1 - } - ``` +- **URL**: /admin/test ---- +- **请求方法**: GET / POST -#### 2. 审核文章：通过 -- **URL**: `POST /admin/approve` -- **请求参数（JSON）**: - ```json - { "id": 123 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- **功能描述**: 验证管理员权限接口是否正常运行（需携带管理员 Token） ---- +- **成功响应（200 OK）**: Admin API OK!!!（文本格式） -#### 3. 审核文章：拒绝 -- **URL**: `POST /admin/disapprove` -- **请求参数（JSON）**: - ```json - { "id": 123 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- **错误响应**: 401/403：管理员权限验证失败 ---- +#### 4.7.2 获取管理员视角的帖子详情 -#### 4. 重新审核文章（置为 Pending） -- **URL**: `POST /admin/reaudit` -- **请求参数（JSON）**: - ```json - { "id": 123 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- **URL**: /admin/get/post_info ---- +- **请求方法**: GET -#### 5. 删除文章（包括评论） -- **URL**: `POST /admin/del_post` -- **请求参数（JSON）**: - ```json - { "id": 123 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- **请求参数（Query）**: id=1（帖子 ID，必填） ---- +- **功能描述**: 查看指定帖子的完整信息（含创建时间、更新时间、审核状态，不受 “未通过审核” 限制） -#### 6. 修改文章内容 -- **URL**: `POST /admin/modify_post` -- **请求参数（JSON）**: - ```json - { "id": 123, "content": "新内容" } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- **成功响应（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 +} +``` -#### 7. 删除评论 -- **URL**: `POST /admin/del_comment` -- **请求参数（JSON）**: - ```json - { "id": 456 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- **错误响应**: ---- +- - 401/403：管理员权限验证失败 -#### 8. 修改评论 -- **URL**: `POST /admin/modify_comment` -- **请求参数（JSON）**: - ```json - { - "id": 456, - "content": "新内容", - "parent_comment_id": 0, - "nickname": "新昵称" - } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +- - 400 Bad Request：缺少帖子 ID ---- +- - 404 Not Found：帖子不存在 -#### 9. 删除图片 -- **URL**: `POST /admin/del_pic` -- **请求参数（JSON）**: - ```json - { "filename": "240510_aBc12.png" } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` +## 五、附录 ---- +### 5.1 常见状态码说明 -#### 10. 管理投诉：通过 -- **URL**: `POST /admin/approve_report` -- **请求参数（JSON）**: - ```json - { "id": 101 } - ``` -- **行为**：标记投诉为通过，并**删除对应文章及其所有评论** - ---- - -#### 11. 管理投诉：拒绝 -- **URL**: `POST /admin/reject_report` -- **请求参数（JSON）**: - ```json - { "id": 101 } - ``` -- **返回**: - ```json - { "status": "OK" } - ``` - ---- - -#### 12. 开启/关闭审核功能 -- **URL**: `POST /admin/need_audit` -- **请求参数（JSON）**: - ```json - { "need_audit": true } // 或 false - ``` -- **返回**: - ```json - { "status": "OK" } - ``` - ---- - -#### 13. 获取当前是否需审核 -- **URL**: `GET /admin/get/need_audit` -- **返回**: - ```json - { "status": true } - ``` - ---- - -#### 14. 获取待审核文章列表 -- **URL**: `GET /admin/get/pending_posts` -- **返回**: - ```json - [ - { - "id": 123, - "content": "待审内容", - "created_at": "2024-05-10T12:00:00+00:00", - "updated_at": "2024-05-10T12:00:00+00:00", - "status": "Pending" - } - ] - ``` - ---- - -#### 15. 获取被拒绝文章 -- **URL**: `GET /admin/get/reject_posts` -- **返回**： - - 结构同上，仅状态为 "Deny" - ---- - -#### 16. 获取所有图片链接（分页） -- **URL**: `GET /admin/get/pic_links` -- **参数（query）**: - - `page=1` -- **返回**: - ```json - [ - "/img/240510_aBc12.png", - "/img/240510_xYz34.jpg" - ] - ``` - ---- - -#### 17. 获取待处理投诉 -- **URL**: `GET /admin/get/pending_reports` -- **返回**: - ```json - [ - { - "id": 101, - "submission_id": 123, - "title": "举报标题", - "content": "举报内容", - "status": "Pending", - "created_at": "2024-05-10T12:00:00+00:00" - } - ] - ``` - ---- - -#### 18. 下载备份文件 -- **URL**: `GET /admin/get/backup` -- **返回**：一个 `.zip` 文件，包含数据库和 `img/` 文件夹 - ---- - -#### 19. 恢复备份 -- **URL**: `POST /admin/recover` -- **请求**：上传一个 `.zip` 备份文件（form-data） -- **返回**: - ```json - { "status": "OK" } - ``` -- **行为**：解压覆盖当前数据库和图片目录 - ---- - -### 🟩 总结说明 - -| 功能 | 接口路径 | 是否需要 Token | 说明 | -| ------------ | --------------------- | -------------- | ------------------------------ | -| 提交文章 | `POST /post` | 否 | 含违禁词或空则拒绝 | -| 点赞/踩 | `POST /up`, `/down` | 否 | 仅需文章 ID | -| 发布评论 | `POST /comment` | 否 | 有合规校验 | -| 上传图片 | `POST /upload_pic` | 否 | 仅支持特定格式 | -| 获取文章状态 | `GET /get/post_state` | 否 | 无权限限制 | -| 提交投诉 | `POST /report` | 否 | 带文章 ID | -| 获取统计 | `GET /get/statics` | 否 | 公开数据 | -| 后台操作 | 所有 `/admin/...` | ✅ 必须 | 使用 `Bearer your_admin_token` | - ---- - -> ✅ 所有返回均为 JSON 格式，状态码 200/201 表示成功，其余为错误（如 400, 403, 404, 500）。 +| 状态码 | 含义 | 适用场景 | +| ------------------------- | -------------- | ------------------------------------------------------ | +| 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 | 服务器内部错误 | 备份恢复失败、数据库异常等系统级错误 | diff --git a/api_server.py b/api_server.py index 63a2916..37c5507 100644 --- a/api_server.py +++ b/api_server.py @@ -100,7 +100,7 @@ BANNED_KEYWORDS = [ "割腕", "跳楼" ] -ADMIN_TOKEN = "LeonXieNeko14235^" +ADMIN_TOKEN = "I_Love_SFLS_128936^" UPLOAD_FOLDER = "img" ALLOWED_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "webp"} @@ -371,8 +371,6 @@ def get_post_info(): return jsonify({ "id": submission.id, "content": submission.content, - "created_at": submission.created_at.isoformat(), - "updated_at": submission.updated_at.isoformat(), "upvotes": submission.upvotes, "downvotes": submission.downvotes }), 200 @@ -415,8 +413,7 @@ def get_comments(): "id": comment.id, "nickname": comment.nickname, "content": comment.content, - "parent_comment_id": comment.parent_comment_id, - "created_at": comment.created_at.isoformat() + "parent_comment_id": comment.parent_comment_id } comments = [serialize_comment(c) for c in submission.comments] @@ -447,11 +444,8 @@ def get_10_info(): return jsonify([{ "id": s.id, "content": s.content, - "created_at": s.created_at.isoformat(), - "updated_at": s.updated_at.isoformat(), "upvotes": s.upvotes, - "downvotes": s.downvotes, - "status": s.status + "downvotes": s.downvotes } for s in page_posts]), 200 @@ -471,6 +465,11 @@ def get_statics(): def return_418(): abort(418) +# === Admin测试API接口 === +@app.route('/test', methods=['GET', 'POST']) +def return_200(): + return 'API OK!!!', 200 + @app.route('/get/api_info', methods=['GET']) def get_api_info(): return 'Sycamore_whisper API v1.0.0 Made with ❤️ By Leonxie', 200 @@ -803,6 +802,11 @@ def admin_pending_reports(): } for r in reports]), 200 +@app.route('/admin/test', methods=['GET', 'POST']) +@require_admin +def admin_return_200(): + return 'Admin API OK!!!', 200 + # === 数据库初始化 === def initialize_database(): """若数据库不存在则创建并初始化"""