From 7d12167380649cf03d9ca93fc53f5379744d4ece Mon Sep 17 00:00:00 2001
From: kevin <kevin@lmve.net>
Date: Thu, 27 Aug 2026 20:08:11 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E8=B7=AF=E7=94=B1=E8=A1=A8?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5=20API=20=E5=8C=96=EF=BC=88=E9=A1=B5=E9=9D=A2?=
 =?UTF-8?q?/API=20=E5=88=86=E7=A6=BB=20+=20API=20=E7=BA=A6=E5=AE=9A?=
 =?UTF-8?q?=E7=AB=A0=E8=8A=82=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md            | 76 ++++++++++++++++++++++++++------------------
 TODO_API_REFACTOR.md | 24 +++++++-------
 2 files changed, 57 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index b85e475..1ab2c66 100644
--- a/README.md
+++ b/README.md
@@ -224,57 +224,71 @@ go_blog/
 |---|---|---|
 | GET | `/` | 首页 |
 | GET | `/search` | 搜索页 |
-| GET | `/api/articles` | 文章列表 API（无限滚动） |
-| GET | `/rss`、`/feed` | RSS 订阅 |
 | GET | `/article/:slug` | 文章详情 |
-| POST | `/article/:slug/comments` | 发表评论 |
+| GET | `/rss`、`/feed` | RSS 订阅 |
 | GET | `/login` | 登录页 |
-| POST | `/login` | 提交登录 |
 | GET | `/register` | 注册页 |
-| POST | `/register` | 提交注册 |
-| POST | `/logout` | 退出登录 |
 | GET | `/uploads/*` | 静态文件（头像、附件等） |
 
+### 公开 JSON API（`/api` 前缀）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/articles` | 文章列表 API（无限滚动） |
+| POST | `/api/auth/login` | 登录（限流锁定 429） |
+| POST | `/api/auth/register` | 注册（用户名冲突 409） |
+| POST | `/api/auth/logout` | 退出登录 |
+| POST | `/api/article/:slug/comments` | 发表评论（校验错误 400） |
+
 ### 管理后台（需管理员权限）
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | GET | `/admin` | 管理后台首页 |
 | GET | `/admin/articles` | 文章列表 |
-| GET/POST | `/admin/articles/new` | 新建文章 |
-| GET/POST | `/admin/articles/:id/edit` | 编辑文章 |
-| POST | `/admin/articles/:id/delete` | 删除文章 |
-| POST | `/admin/articles/attachments` | 上传附件 |
-| POST | `/admin/articles/attachments/:id/delete` | 删除附件 |
-| GET | `/admin/articles/:id/attachments` | 附件列表 |
+| GET | `/admin/articles/new` | 新建文章表单 |
+| GET | `/admin/articles/:id/edit` | 编辑文章表单 |
 | GET | `/admin/comments` | 评论管理 |
-| POST | `/admin/comments/:id/approve` | 通过评论 |
-| POST | `/admin/comments/:id/reject` | 拒绝评论 |
-| POST | `/admin/comments/:id/delete` | 删除评论 |
 | GET | `/admin/users` | 用户列表 |
-| GET/POST | `/admin/users/new` | 新建用户 |
-| GET/POST | `/admin/users/:id/edit` | 编辑用户 |
-| POST | `/admin/users/:id/delete` | 删除用户 |
+| GET | `/admin/users/new` | 新建用户表单 |
+| GET | `/admin/users/:id/edit` | 编辑用户表单 |
 | GET | `/admin/analytics/views` | 阅读统计 |
-| GET/POST | `/admin/settings/site` | 站点设置 |
-| GET/POST | `/admin/settings/navlinks` | 导航链接设置 |
-| GET/POST | `/admin/settings/upload` | 上传设置 |
-| GET/POST | `/admin/settings/download` | 下载设置 |
-| GET/POST | `/admin/settings/comments` | 评论设置 |
+| GET | `/admin/settings/site`、`/navlinks`、`/upload`、`/download`、`/comments` | 各设置页 |
+
+管理 JSON API（仅管理员，均带 JSON 错误码 + HTTP 语义状态码）：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/admin/articles` | 创建文章 |
+| PUT/DELETE | `/api/admin/articles/:id` | 更新/删除文章 |
+| POST | `/api/admin/articles/attachments` | 上传附件（multipart） |
+| DELETE | `/api/admin/articles/attachments/:id` | 删除附件 |
+| GET | `/api/admin/articles/:id/attachments` | 附件列表 |
+| POST | `/api/admin/comments/:id/approve`、`/:id/reject`、`/:id/delete` | 评论审核操作 |
+| POST/PUT/DELETE | `/api/admin/users`、`/:id` | 用户增改删（自禁/最后管理员均 403） |
+| POST | `/api/admin/settings/site` | 站点设置（文本/URL/清除） |
+| POST | `/api/admin/settings/site/favicon`、`/site/logo` | favicon/logo 上传（multipart） |
+| POST | `/api/admin/settings/navlinks`、`/upload`、`/download`、`/comments` | 各设置保存（`action` 分发） |
 
 ### 个人中心（需登录）
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| GET/POST | `/profile` | 编辑个人信息 |
-| POST | `/profile/avatar` | 上传头像 |
+| GET | `/profile` | 编辑个人信息页 |
+| POST | `/api/profile` | 保存资料（JSON，密码改密校验 400） |
+| POST | `/api/profile/avatar` | 上传头像（multipart、JPEG 重编码） |
 | GET | `/my/articles` | 我的文章列表 |
-| GET/POST | `/my/articles/new` | 新建文章 |
-| GET/POST | `/my/articles/:id/edit` | 编辑文章 |
-| POST | `/my/articles/:id/delete` | 删除文章 |
-| POST | `/my/articles/attachments` | 上传附件 |
-| POST | `/my/articles/attachments/:id/delete` | 删除附件 |
-| GET | `/my/articles/:id/attachments` | 附件列表 |
+| GET | `/my/articles/new`、`/:id/edit` | 我的文章表单页 |
+| POST/PUT/DELETE | `/api/my/articles`、`/:id` | 文章增改删（跨作者 404/403） |
+| POST | `/api/my/articles/attachments` | 上传附件（multipart） |
+| DELETE | `/api/my/articles/attachments/:id` | 删除附件 |
+| GET | `/api/my/articles/:id/attachments` | 附件列表 |
+
+### API 约定
+
+- 成功：`{"ok": true, "redirect": "...", "data": {...}}`（`redirect` 为原 302 目标，前端 fetch 后跳转）
+- 失败：`{"ok": false, "code": "<i18n 键>", "error": "<按请求语言翻译的文案>"}`；状态码：400 校验失败 / 401 未登录 / 403 无权限 / 404 不存在 / 409 冲突 / 429 限流锁定 / 500 服务错误
+- 除文件上传（multipart）外请求体为 `application/json`；CSRF 通过 `X-CSRF-Token` 请求头传递
 
 ## 用户角色
 
diff --git a/TODO_API_REFACTOR.md b/TODO_API_REFACTOR.md
index 487a3de..e5356fb 100644
--- a/TODO_API_REFACTOR.md
+++ b/TODO_API_REFACTOR.md
@@ -18,21 +18,21 @@
 
 - [x] 7. 认证 API：`auth.go` Login/Register/Logout JSON 化（429 限流、会话轮换保留）
 - [x] 8. 认证模板：`login.html`/`register.html` 改 fetch + 错误 div `id`；base.html logout 改 fetch（logout-form 全局委托）
-- [ ] 9. 评论 API：`comment.go` PostComment JSON 化（校验码复用 i18n 键）
-- [ ] 10. 评论 API：`admin_comment.go` approve/reject/delete JSON 化
-- [ ] 11. 评论模板：`article.html` 评论表单 fetch、`comment_list.html` 操作后 reload
-- [ ] 12. 文章 CRUD API：`article.go`/`my_articles.go` 去 renderForm/Redirect 改 JSON（表单字段加 json tag）
-- [ ] 13. 文章模板：`article_create.html`/`my_article_form.html`/`article_list.html`/`my_articles.html` 改 fetch（`easyMDE.value()`、`e.submitter`）
-- [ ] 14. 用户 API：`admin_user.go` UserCreate/Update/Delete JSON 化（自防/最后管理员拦截改 403）
-- [ ] 15. 用户模板：`user_form.html`/`user_list.html` 改 fetch
-- [ ] 16. 设置 API：`settings.go` 5 组 save JSON 化；site favicon 拆出 `POST /api/admin/settings/site/favicon`
-- [ ] 17. 设置模板：`settings_site`/`settings_navlinks`/`settings_upload`/`settings_download`/`settings_comment` 5 页改 fetch
-- [ ] 18. 个人资料 API：`profile.go` UpdateProfile JSON 化（头像走 `/api/profile/avatar`）
-- [ ] 19. 个人资料模板：`profile.html` 文本表单改 fetch
+- [x] 9. 评论 API：`comment.go` PostComment JSON 化（校验码复用 i18n 键）
+- [x] 10. 评论 API：`admin_comment.go` approve/reject/delete JSON 化
+- [x] 11. 评论模板：`article.html` 评论表单 fetch、`comment_list.html` 操作后 reload
+- [x] 12. 文章 CRUD API：`article.go`/`my_articles.go` 去 renderForm/Redirect 改 JSON（表单字段加 json tag）
+- [x] 13. 文章模板：`article_create.html`/`my_article_form.html`/`article_list.html`/`my_articles.html` 改 fetch（`easyMDE.value()`、`e.submitter`）
+- [x] 14. 用户 API：`admin_user.go` UserCreate/Update/Delete JSON 化（自防/最后管理员拦截改 403）
+- [x] 15. 用户模板：`user_form.html`/`user_list.html` 改 fetch
+- [x] 16. 设置 API：`settings.go` 5 组 save JSON 化；site favicon/logo 拆出 `POST /api/admin/settings/site/favicon|logo`
+- [x] 17. 设置模板：`settings_site`/`settings_navlinks`/`settings_upload`/`settings_download`/`settings_comment` 5 页改 fetch（blogSettingsForm 委托）
+- [x] 18. 个人资料 API：`profile.go` UpdateProfile JSON 化（头像走 `/api/profile/avatar`）
+- [x] 19. 个人资料模板：`profile.html` 文本表单改 fetch
 
 ## 测试与收尾（high）
 
-- [ ] 20. 新增 `handlers/api_test.go`：happy path / 校验码 / 401 / 403 / CSRF 头 / 429 / 409
+- [x] 20. 新增 `handlers/api_test.go`：happy path / 校验码 / 401 / 403 / CSRF 头 / 429 / 409
 - [ ] 21. 更新 `security_test.go`/`p2_validation_test.go`/`p3_upload_test.go`/`session_upload_security_test.go` 到新 URL 与 JSON 断言
 - [ ] 22. `go build ./... && go vet ./... && go test ./...` 全绿；README 路由表同步