feat(cloud): sync avatar display and likes API
This commit is contained in:
@@ -60,7 +60,7 @@
|
||||
|
||||
⚠️ **响应不返回总数**，也没有 `has_more` 字段。判断「是否还有下一页」只能依靠「返回数组长度 < `page_size`」。超出数据范围的页返回 `200` + 空数组 `[]`，不是 404。
|
||||
|
||||
云图列表排序为 `uploaded_at` 倒序（同刻按 `id` 倒序）；点赞列表按点赞时间倒序。
|
||||
云图列表排序为 `uploaded_at` 倒序（同刻按 `id` 倒序）；点赞列表按点赞时间倒序（同刻按云图 ID 倒序）。
|
||||
|
||||
### 1.5 共享数据模型
|
||||
|
||||
@@ -92,7 +92,7 @@
|
||||
| `id` | uuid | 用户 ID |
|
||||
| `name` | string | 用户名 |
|
||||
| `email` | string | 邮箱（注意 2.3 第 7 条的暴露范围问题） |
|
||||
| `avatar_id` | uuid\|null | 头像 ID（当前恒为 `null`，头像功能未上线） |
|
||||
| `image` | string\|null | 用户头像 URL，由 Better Auth 管理；未设置时为 `null` |
|
||||
| `cloud_count` | int | 云图数（该用户上传的云图总数） |
|
||||
| `received_like_count` | int | 收到点赞数（名下云图获赞总和） |
|
||||
| `last_online` | string\|null | 最后在线时间（ISO 8601） |
|
||||
@@ -243,6 +243,8 @@ const { data: session } = await authClient.getSession();
|
||||
|
||||
需要业务资料、统计及角色时，再请求 `GET /profile/me`，不要将 Better Auth 的 `user` 对象当作第 1.5 节的 UserProfile。完整客户端方法见 [Better Auth 会话管理](https://better-auth.com/docs/concepts/session-management)。
|
||||
|
||||
头像使用 Better Auth 的 `user.image` 字段。前端可调用 `authClient.updateUser({ image: "https://example.com/avatar.png" })` 设置头像 URL；业务资料接口和管理员用户列表均返回同一 `image` 值。原 `avatar_id` 字段已移除。
|
||||
|
||||
所有受保护的业务接口都再次检查会话、邮箱验证状态、禁用状态及角色。**业务接口**在无会话、邮箱未验证或帐号被禁用时返回 `401`；会话有效但角色或资源权限不足时返回 `403`。管理员修改角色或密码后会撤销目标用户的全部会话，前端应刷新登录状态。
|
||||
|
||||
两种可选认证端点行为不同：`GET /cloud/:cloud_id` 对无效/过期凭证按匿名处理；`GET|HEAD /image/:cloud_id/:variant` 在显式提供无效凭证时返回 `401`。同时发送 `Authorization` 和 Cookie 时，业务接口优先使用 Bearer 凭证。
|
||||
@@ -428,7 +430,7 @@ if (!response.ok) throw new Error("邮箱验证失败");
|
||||
| 404 | 云类型不存在 | `云类型不存在` | 提示类型不存在 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
### 5.5 `POST /cloud/:cloud_id/like` — 点赞
|
||||
### 5.5 `PUT /cloud/:cloud_id/like` — 点赞
|
||||
|
||||
- **认证**：需登录（任意角色）
|
||||
- **请求体**：无
|
||||
@@ -450,7 +452,7 @@ if (!response.ok) throw new Error("邮箱验证失败");
|
||||
| 404 | 云图不存在，或不是公开可见状态 | `图片不存在` | 提示云图不可点赞；与「不存在」共用是设计意图 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
**注意事项**：**幂等**——重复点赞返回相同的 200，点赞数不会增加。前端无需在点击前查询是否已赞，但仍建议本地置灰防止连点。
|
||||
**注意事项**：**幂等**——重复点赞返回相同的 200，点赞数不会增加。旧 `POST /cloud/:cloud_id/like` 已移除；前端改用 `PUT`。前端无需在点击前查询是否已赞，但仍建议本地置灰防止连点。
|
||||
|
||||
### 5.6 `DELETE /cloud/:cloud_id/like` — 取消点赞
|
||||
|
||||
@@ -675,7 +677,7 @@ if (!response.ok) throw new Error("邮箱验证失败");
|
||||
"id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
|
||||
"name": "cloudwatcher",
|
||||
"email": "watcher@example.com",
|
||||
"avatar_id": null,
|
||||
"image": "https://example.com/avatar.png",
|
||||
"cloud_count": 7,
|
||||
"received_like_count": 42,
|
||||
"last_online": "2026-08-15T08:30:00.000Z",
|
||||
@@ -720,12 +722,13 @@ if (!response.ok) throw new Error("邮箱验证失败");
|
||||
### 6.3 `GET /profile/me/likes` — 我点赞过的云图
|
||||
|
||||
- **认证**：需登录
|
||||
- **Query 参数**：分页参数 `page`、`page_size`，见 1.4
|
||||
|
||||
**成功响应**：`200`，CloudInfo 数组（字段见 1.5），按点赞时间倒序。
|
||||
**成功响应**：`200`，CloudInfo 数组（字段见 1.5），按点赞时间倒序、同刻按云图 ID 倒序；默认返回第 1 页的 50 条，最多每页 100 条。超出范围的页返回 `[]`。
|
||||
|
||||
**注意事项**：包含**所有状态**的云图（含待审核/已驳回/已隐藏的），因为这些是你自己点过赞的——展示时如需隐藏非公开项请自行过滤 `status` 与 `is_hidden`。
|
||||
|
||||
**错误**：500 `服务器发生内部错误`。
|
||||
**错误**：分页参数非法时返回 400（见 2.1）；服务端异常返回 500 `服务器发生内部错误`。
|
||||
|
||||
### 6.4 `GET /profile/me/clouds` — 我上传的云图
|
||||
|
||||
@@ -753,22 +756,7 @@ if (!response.ok) throw new Error("邮箱验证失败");
|
||||
|
||||
**注意事项**：⚠️ 响应包含对方 `email`（2.3 第 7 条）。展示他人资料页时不应展示邮箱字段。
|
||||
|
||||
### 6.6 `GET /profile/:user_id/likes` — 查看用户点赞记录
|
||||
|
||||
- **认证**：需登录，且为**本人或 admin**
|
||||
|
||||
**路径参数**：`user_id`（uuid）。
|
||||
|
||||
**成功响应**：`200`，CloudInfo 数组，按点赞时间倒序，结构同 5.1。
|
||||
|
||||
**错误**：
|
||||
|
||||
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
|
||||
|---|---|---|---|
|
||||
| 403 | 查看他人且非 admin | `无权查看该用户的点赞记录` | 前端应在进入页面前判断身份，避免触发 |
|
||||
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
|
||||
|
||||
### 6.7 `GET /profile/:user_id/clouds` — 查看用户上传的云图
|
||||
### 6.6 `GET /profile/:user_id/clouds` — 查看用户上传的云图
|
||||
|
||||
- **认证**：需登录，且为**本人或 admin**
|
||||
|
||||
@@ -1084,6 +1072,16 @@ if (!response.ok) throw new Error("邮箱验证失败");
|
||||
|
||||
**注意事项**：管理员删除不受审核状态或隐藏状态限制。删除会级联删除该云图的点赞记录，并尽力清理 MinIO 中的图片对象；清理失败不报错，可能残留孤儿对象（可接受）。删除后前端应立即刷新相关列表。
|
||||
|
||||
### 8.12 `GET /admin/users/:user_id/likes` — 查看用户点赞记录
|
||||
|
||||
- **认证**：admin
|
||||
- **路径参数**：`user_id`（uuid）
|
||||
- **Query 参数**：分页参数 `page`、`page_size`，见 1.4
|
||||
|
||||
**成功响应**：`200`，与 6.3 相同的 CloudInfo 数组和排序，包含该用户已点赞但后来被隐藏或改判的云图；没有点赞或页码超出范围时返回 `[]`。
|
||||
|
||||
**错误**：`user_id` 或分页参数非法时返回 400（见 2.1）；用户不存在时返回 404 `{ "status_code": 404, "error": "用户不存在" }`；服务端异常返回 500 `服务器发生内部错误`。非管理员统一返回 403（本章规则）。旧 `GET /profile/:user_id/likes` 已移除；本人使用 6.3，管理员使用本端点。
|
||||
|
||||
---
|
||||
|
||||
## 9. 端点 · 系统
|
||||
|
||||
Reference in New Issue
Block a user