feat(admin): align frontend with updated API contracts
This commit is contained in:
@@ -217,7 +217,7 @@
|
||||
- 续签不适用的路径：`POST /auth/logout`、`PATCH /auth/password`
|
||||
- `/image` 请求只验证身份，不触发静默续签，避免一个页面的并发图片请求重复写 Cookie
|
||||
- 认证中间件每次请求都会重新检查用户仍已确认邮箱且未被管理员禁用；任一条件不满足时，已有 JWT 也会被拒绝
|
||||
- **立即失效**的四种情况：调用 `/auth/logout`、调用 `PATCH /auth/password` 改密、通过 `/auth/reset-password` 重置密码、用户被禁用。前三者会使该用户**所有已签发的 token 全部作废**（包括其他设备上的）；密码修改与重置成功时还会写入过期 Cookie
|
||||
- **立即失效**的情况：调用 `/auth/logout`、调用 `PATCH /auth/password` 改密、通过 `/auth/reset-password` 重置密码、用户被禁用，以及管理员修改了该用户的角色或密码（`PATCH /admin/users/:user_id` 见 8.3、`PATCH /admin/users/:user_id/password` 见 8.4）。除「用户被禁用」由中间件每次请求重新校验外，其余情况都会递增 `tokenVersion`，使该用户**所有已签发的 token 全部作废**（包括其他设备上的）；用户自己改密与密码重置成功时还会写入过期 Cookie
|
||||
|
||||
### 3.5 认证相关错误消息对照
|
||||
|
||||
@@ -280,6 +280,7 @@
|
||||
- 新用户的 `is_disabled` 为 `false`，`email_verified_at` 为空；两个状态相互独立。注册后必须先确认邮箱，再调用 `/auth/login`
|
||||
- 注册响应**不返回 token、不写 Cookie**
|
||||
- 确认邮件由 `Opencloud <opencloud@catpl.top>` 发出，同时包含 `https://cloud.catpl.top/verify-email?token=...` 链接和原始 token 备用文本。数据库仅保存使用 `JWT_SECRET` 生成的 HMAC 摘要
|
||||
- ⚠️ 并发注册（同一邮箱/用户名几乎同时提交）命中数据库唯一约束时，冲突消息文案与上方表格不同（邮箱冲突会返回 `该邮箱已被注册；若尚未验证，请使用重发验证流程`）。按本文档免责声明，前端仍只依据状态码 `409` 处理
|
||||
|
||||
### 4.2 `POST /auth/resend-confirmation` — 重发确认邮件
|
||||
|
||||
@@ -1053,7 +1054,7 @@ token 必须同时匹配规范化邮箱、HMAC 摘要、`password_reset` purpose
|
||||
|
||||
### 8.1 `GET /admin/stats` — 统计数据
|
||||
|
||||
> ⚠️ **未实现**（占位端点）。当前任何请求返回纯文本 `404 Not Found`。请勿接入。
|
||||
> ⚠️ **未实现**（占位端点，无 handler）。admin 请求返回纯文本 `404 Not Found`；未登录/非 admin 仍按本章规则先返回 401/403。请勿接入。
|
||||
|
||||
### 8.2 `GET /admin/users` — 用户列表
|
||||
|
||||
@@ -1069,15 +1070,85 @@ token 必须同时匹配规范化邮箱、HMAC 摘要、`password_reset` purpose
|
||||
|
||||
**注意事项**：**无分页参数**，一次返回全部用户。用户量大时注意性能。
|
||||
|
||||
### 8.3 `PATCH /admin/users` — 更新用户
|
||||
### 8.3 `PATCH /admin/users/:user_id` — 修改用户角色
|
||||
|
||||
> ⚠️ **未实现**（占位端点）。当前任何请求返回纯文本 `404 Not Found`。请勿接入。
|
||||
- **认证**：admin
|
||||
|
||||
### 8.4 `POST /admin/user` — 创建用户
|
||||
**路径参数**：`user_id`（uuid）。
|
||||
|
||||
**请求体**（JSON）：
|
||||
|
||||
| 参数 | 类型 | 必填 | 约束 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `user_role` | enum | 是 | `user` / `admin` | 目标角色 |
|
||||
|
||||
```json
|
||||
{
|
||||
"user_role": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应**：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"status_code": 200,
|
||||
"message": "角色修改成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误**：
|
||||
|
||||
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
|
||||
|---|---|---|---|
|
||||
| 400 | 参数校验失败（`user_role` 非法 / `user_id` 非 uuid） | zod 形状（2.1） | 检查参数 |
|
||||
| 404 | 用户不存在 | `用户不存在` | 提示用户不存在 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
**注意事项**：修改角色会同时递增 `tokenVersion`，**该用户所有已签发 token 立即失效，必须重新登录**（见 3.4）。前端改完角色后可提示目标用户重新登录。
|
||||
|
||||
### 8.4 `PATCH /admin/users/:user_id/password` — 设置用户密码
|
||||
|
||||
- **认证**：admin
|
||||
|
||||
**路径参数**：`user_id`（uuid）。
|
||||
|
||||
**请求体**（JSON）：
|
||||
|
||||
| 参数 | 类型 | 必填 | 约束 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `new_password` | string | 是 | 无强度校验 | 新密码；管理员直接覆盖，无需旧密码 |
|
||||
|
||||
```json
|
||||
{
|
||||
"new_password": "new-s3cret-password"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应**：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"status_code": 200,
|
||||
"message": "密码修改成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误**：
|
||||
|
||||
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
|
||||
|---|---|---|---|
|
||||
| 400 | 参数校验失败（`user_id` 非 uuid） | zod 形状（2.1） | 检查参数 |
|
||||
| 404 | 用户不存在（含凭据记录缺失） | `用户不存在` | 提示用户不存在 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
**注意事项**：成功后同样递增 `tokenVersion`，该用户所有已签发 token 立即失效，必须重新登录（见 3.4）。
|
||||
|
||||
### 8.5 `POST /admin/user` — 创建用户
|
||||
|
||||
> ⚠️ **假端点**（2.3 第 4 条）：通过 zod 校验后**原样回显请求体（含明文密码）**，不创建任何用户。响应为 `200 { name, email, password, role }`。请勿接入，更不要在任何持久化日志中记录其响应。
|
||||
|
||||
### 8.5 `GET /admin/clouds` — 全状态云图列表
|
||||
### 8.6 `GET /admin/clouds` — 全状态云图列表
|
||||
|
||||
- **认证**：admin；可见任意状态与隐藏的云图
|
||||
|
||||
@@ -1096,7 +1167,7 @@ token 必须同时匹配规范化邮箱、HMAC 摘要、`password_reset` purpose
|
||||
| 400 | `status` 非法等参数错误 | zod 形状（2.1） | 检查参数 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
### 8.6 `POST /admin/clouds/review` — 批量审核云图
|
||||
### 8.7 `POST /admin/clouds/review` — 批量审核云图
|
||||
|
||||
- **认证**：admin
|
||||
|
||||
@@ -1134,6 +1205,31 @@ token 必须同时匹配规范化邮箱、HMAC 摘要、`password_reset` purpose
|
||||
|
||||
**注意事项**：**部分成功语义**——消息中的 `N` 只统计状态**实际发生变化**的云图；已是目标状态的与不存在的一律静默跳过。审核只改变审核状态，不影响 `is_hidden` 与点赞数据。`pending ↔ approved/rejected`、`approved ↔ rejected` 均可。
|
||||
|
||||
### 8.8 `DELETE /admin/clouds/:cloud_id` — 删除云图
|
||||
|
||||
- **认证**：admin
|
||||
|
||||
**路径参数**：`cloud_id`（uuid）。
|
||||
|
||||
**成功响应**：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"status_code": 200,
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误**：
|
||||
|
||||
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
|
||||
|---|---|---|---|
|
||||
| 400 | `cloud_id` 非 uuid | zod 形状（2.1） | 检查链接 |
|
||||
| 404 | 云图不存在 | `图片不存在` | 提示云图不存在 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
**注意事项**：管理员删除不受审核状态或隐藏状态限制。删除会级联删除该云图的点赞记录，并尽力清理 MinIO 中的图片对象；清理失败不报错，可能残留孤儿对象（可接受）。删除后前端应立即刷新相关列表。
|
||||
|
||||
---
|
||||
|
||||
## 9. 端点 · 系统
|
||||
|
||||
Reference in New Issue
Block a user