Mplan/opencloud
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0af0256c976ca4bdc99c93b67c73c6d403bfe820
opencloud/API.md
T

1089 lines
62 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OpenCloud API 前端开发文档
> **读者**：前端开发者。本文档覆盖 API 的全部端点：请求参数、响应结构、可能出现的错误与已知坑点。
>
> **事实来源**：业务接口以 `src/schema/*.ts` 与 `src/router/*.ts` 为准；认证以 `src/auth.ts` 中的 Better Auth 配置、`src/index.ts` 中的挂载路径及 `src/middleware/auth.ts` 中的业务鉴权规则为准。若文档与代码不一致，以代码为准。
>
> **重要免责**：错误消息文案可能调整。**前端逻辑应依赖 HTTP 状态码及需要时的机器可读错误码，严禁匹配错误消息字符串**。文档中列出消息原文仅供调试对照。
## 目录
1. 通用约定
2. 错误处理与已知不一致
3. 认证
4. 端点 · 认证 `/auth`
5. 端点 · 云图 `/cloud`
6. 端点 · 个人资料 `/profile`
7. 端点 · 信息 `/info`
8. 端点 · 管理 `/admin`
9. 端点 · 系统
---
## 1. 通用约定
### 1.1 Base URL
| 环境 | 地址 |
| -------- | ---------------------------------------- |
| 本地开发 | `http://localhost:3000`（`vc dev` 启动） |
| 生产 | 以部署地址为准 |
业务接口除 `/image` 成功响应直接返回图片字节外，响应通常为 `application/json`（个别异常情形返回纯文本，见 2.2）。Better Auth 的 `/auth/*` 有独立响应格式，部分操作也可能重定向，见第 4 章。响应携带两个调试响应头：
- `X-Request-Id`：请求唯一 ID，反馈问题时请附上
- `X-Response-Time`：服务端处理耗时，如 `12ms`
### 1.2 命名与格式
- 业务接口使用 **snake_case**（如 `cloud_id`、`page_size`）；Better Auth 的 `/auth/*` 接口使用其原生 **camelCase** 字段
- 日期时间一律为 **ISO 8601 字符串**（如 `2026-08-15T08:30:00.000Z`），可空的日期字段值为 `null`。唯一的例外见 2.3 第 5 条
- UUID 字段为标准 UUID 字符串
### 1.3 响应形态
业务成功响应**没有统一包装**，分两种形态；`/auth/*` 不使用下表中的业务信封：
| 场景 | 形态 | 示例 |
| -------------------------------------------- | -------- | ----------------------------------------------- |
| 写操作成功（POST/PATCH/DELETE 的动作类端点） | 信封对象 | `{ "status_code": 200, "message": "删除成功" }` |
| 读操作成功（业务 GET） | 裸数据 | 单资源为对象、列表为**数组** |
### 1.4 分页
所有分页端点使用相同的 query 参数：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ----------- | ---- | ---- | ---------------- | -------- |
| `page` | int | 否 | ≥ 1，默认 `1` | 页码 |
| `page_size` | int | 否 | 1–100，默认 `50` | 每页数量 |
⚠️ **响应不返回总数**，也没有 `has_more` 字段。判断「是否还有下一页」只能依靠「返回数组长度 < `page_size`」。超出数据范围的页返回 `200` + 空数组 `[]`，不是 404。
云图列表排序为 `uploaded_at` 倒序（同刻按 `id` 倒序）；点赞列表按点赞时间倒序（同刻按云图 ID 倒序）。
### 1.5 共享数据模型
以下模型在多个端点复用，端点章节中直接引用名称。
**CloudInfo（云图）**
| 字段 | 类型 | 说明 |
| --------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
| `id` | uuid | 云图 ID |
| `owner` | object | 上传者：`{ id: uuid, name: string }` |
| `type` | object | 云类型：`{ id: int, name: string, genus: string\|null, icon_id: uuid\|null, rarity: int, description: string }` |
| `latitude` | number | 纬度，-90 ~ 90 |
| `longitude` | number | 经度，-180 ~ 180 |
| `description` | string | 描述，可能为空字符串 |
| `captured_at` | string\|null | 拍摄时间（ISO 8601） |
| `uploaded_at` | string | 上传时间（ISO 8601） |
| `updated_at` | string | 最后更新时间（ISO 8601） |
| `received_like_count` | int | 收到点赞数 |
| `status` | enum | 审核状态：`pending`（待审核）/ `approved`（已通过）/ `rejected`（已驳回） |
| `is_hidden` | boolean | 是否隐藏（上传者控制，与审核状态独立） |
**公开可见规则**：未登录访客与无关用户只能看到 `status === "approved"` 且 `is_hidden === false` 的云图；上传者本人与 admin 不受限。
**UserProfile（用户）**
| 字段 | 类型 | 说明 |
| --------------------- | ------------ | ---------------------------------------------------- |
| `id` | uuid | 用户 ID |
| `name` | string | 用户名 |
| `email` | string | 邮箱（注意 2.3 第 7 条的暴露范围问题） |
| `image` | string\|null | 用户头像 URL，由 Better Auth 管理；未设置时为 `null` |
| `cloud_count` | int | 云图数（该用户上传的云图总数） |
| `received_like_count` | int | 收到点赞数（名下云图获赞总和） |
| `last_online` | string\|null | 最后在线时间（ISO 8601） |
| `role` | enum | `user` / `admin` |
| `is_disabled` | boolean | 是否被禁用 |
| `created_at` | string | 注册时间（ISO 8601） |
**CloudTypeInfo（云类型）**
| 字段 | 类型 | 说明 |
| ------------- | ------------ | ------------------------------------------------------- |
| `id` | int | 云类型 ID |
| `name` | string | 名称，如「积云」 |
| `genus` | string\|null | 属（拉丁名），如 `Cumulus` |
| `icon_id` | uuid\|null | 图标 ID |
| `rarity` | int | 稀有度 |
| `description` | string | 描述 |
| `created_at` | string | 创建时间。⚠️ 列表与详情端点的格式不一致，见 2.3 第 5 条 |
### 1.6 上传约束（`POST /cloud`）
- 请求体总大小上限 **21 MiB**，超出返回 413
- 图片文件上限 **20 MB**；仅支持 **JPEG / PNG / WebP**；**不支持动图**（含动态 WebP、GIF）
- 图片分辨率过高会被拒绝（像素上限）
- multipart 表单字段均为字符串，注意 `is_hidden` 的编码规则（见 5.7）
---
## 2. 错误处理与已知不一致
### 2.1 两种错误响应形状
业务接口存在**两种**错误响应形状，前端必须分别处理。`/auth/*` 使用 Better Auth 自己的错误格式，见 3.5。
**① 业务错误**（绝大多数错误）——ErrorMessage 信封：
```json
{
"status_code": 404,
"error": "未找到图片"
}
```
**② 参数校验失败（400）**——zod 原始结构，**不是**上面的信封：
```json
{
"success": false,
"error": {
"name": "ZodError",
"message": "[{\"code\":\"invalid_format\",\"path\":[\"email\"],\"message\":\"Invalid email address\"}]"
}
}
```
注意 `error.message` 是一个 **JSON 字符串**（issues 数组的序列化结果），需要二次 `JSON.parse` 才能拿到字段级错误明细；每个 issue 含 `path`（出错字段路径）、`code`、`message`。不需要逐字段提示时，直接弹「参数错误」即可。
**判别方式**：响应体含 `success: false` → 形状②；含 `status_code` → 形状①。
### 2.2 状态码总表
| 状态码 | 含义 | 前端通用动作 |
| ------ | ----------------------------------------------------------- | ---------------------------------------------- |
| 200 | 成功 | — |
| 201 | 业务创建成功（如上传云图、管理员创建用户） | — |
| 304 | 图片 ETag 未变化，无响应 body | 继续使用本地缓存 |
| 400 | 参数校验失败（形状②），或业务规则拒绝（形状①） | 检查参数；形状②可解析 `error.message` 定位字段 |
| 401 | 业务接口没有有效 Better Auth 会话，或邮箱未验证、帐号被禁用 | 重新获取会话，必要时引导登录或验证邮箱 |
| 403 | 业务接口已认证但权限不足，如角色不足或越权访问他人资源 | 按场景提示 |
| 404 | 资源不存在（形状①）；**也可能是纯文本**（见下方警告） | 区分 content-type 后处理 |
| 405 | HTTP 方法不受端点支持 | 读取 `Allow` 响应头 |
| 409 | 部分业务接口发生唯一性冲突，如管理员创建用户或修改用户名 | 提示用户更换；普通注册见 3.5 |
| 413 | 上传请求体超过 21 MiB | 提示压缩图片后重试 |
| 500 | 服务器内部错误 | 提示稍后重试，反馈时附 `X-Request-Id` |
| 503 | 图片存储服务暂时不可用 | 稍后重试，反馈时附 `X-Request-Id` |
⚠️ **404 有两种 body**：业务 404（资源不存在）是 JSON 信封；但「未实现的占位端点」和「个别端点的数据库异常」返回的是 **纯文本 `404 Not Found`**（`text/plain`），见 2.3 第 2 条。前端解析 404 响应前必须先判断 content-type。
### 2.3 ⚠️ 已知不一致清单
以下是文档写作时核实的现状描述，**未来可能修复**。前端如需为之写防御代码，请做好移除准备。
1. **两种错误形状并存**：400 校验错误不是业务错误信封（见 2.1）。
2. **部分 404 是纯文本而非 JSON**，来源有三：(a) 未实现的占位端点（各章已标注）；(b) `GET /profile/me` 与 `GET /admin/users` 的数据库异常会从空 `catch` 落到纯文本 404；(c) 未匹配任何路由的路径。Better Auth 认证端点使用自己的错误格式。
3. **认证端点使用 Better Auth 格式**：`/auth/*` 的字段、状态码与错误响应由 Better Auth 定义，不能用业务错误信封解析；见第 4 章。
4. **管理员创建用户需验证邮箱**：`POST /admin/user` 会通过 Better Auth 创建用户并尝试发送验证邮件；验证前不能登录。
5. **`GET /info/cloudtype`（列表）的 `created_at` 格式与其他端点不同**：是 PostgreSQL 原生字符串（如 `2026-08-15 08:30:00.123456+00`），而非 ISO 8601（`2026-08-15T08:30:00.000Z`）。详情端点 `/info/cloudtype/:id` 及其他所有端点均为 ISO 8601。前端解析该字段时需兼容两种格式。
6. **用户名/邮箱数据库长度限制**：用户名 ≤ 16 字符、邮箱 ≤ 64 字符；前端应限制输入长度。
7. **`GET /profile/:user_id` 向任意登录用户暴露对方邮箱**：任何登录用户都能查到任意用户的 `email`。前端展示他人资料时不应展示邮箱，也不应假设该接口未来仍返回邮箱。
8. **用户名大小写**：数据库唯一约束区分大小写，注册和改名均受该约束。
---
## 3. 认证
### 3.1 从旧认证接口迁移
后端现在由 Better Auth 处理注册、登录、邮箱验证、会话和密码。旧认证路由已移除；请替换所有旧请求与响应解析：
| 旧接口 | 当前接口 / 前端动作 | 主要变化 |
| -------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `POST /auth/register` | `POST /auth/sign-up/email` | 请求仍为 `name`、`email`、`password`；成功为 Better Auth 的 `200`，不会自动登录 |
| `POST /auth/login` | `POST /auth/sign-in/email` | 使用 Better Auth 会话 Cookie，不再保存旧 JWT |
| `POST /auth/logout` | `POST /auth/sign-out` | 撤销当前会话；不要只清除前端状态 |
| `POST /auth/resend-confirmation` | `POST /auth/send-verification-email` | 请求 `{ "email": "..." }` |
| `POST /auth/confirm-email` | `GET /auth/verify-email?token=...` | token 从前端验证页的 URL 读取，放入查询参数 |
| `POST /auth/forgot-password` | `POST /auth/request-password-reset` | 请求 `{ "email": "..." }` |
| `POST /auth/reset-password` | `POST /auth/reset-password` | 路径相同，请求改为 `{ "token": "...", "newPassword": "..." }`；不再提交 `email` / `new_password` |
| `PATCH /auth/password` | `POST /auth/change-password` | 请求改为 `currentPassword`、`newPassword`，可选 `revokeOtherSessions` |
旧路由的 `status_code` / `message` 信封、JWT 及认证相关的 snake_case 请求字段不适用于新端点。普通注册不要提交 `role`：角色由服务端设置为 `user`；创建管理员用户走第 8 章的管理接口。业务接口的路径与 snake_case 字段仍按后续章节使用。
### 3.2 浏览器接入
前端安装与后端当前版本一致的 `better-auth@1.7.6`，创建客户端时将 **API 地址连同 `/auth` 路径**传入 `baseURL`。服务端挂载路径是 `/auth`，不是 Better Auth 默认的 `/api/auth`；不要把业务 API 根地址直接用作认证客户端的完整 `baseURL`。下面是框架无关的示例；React 可从 `better-auth/react` 导入 `createAuthClient`。这与 [Better Auth 客户端的自定义路径配置](https://better-auth.com/docs/concepts/client)一致。
```ts
import { createAuthClient } from 'better-auth/client'
const API_ORIGIN = 'http://localhost:3000' // 生产环境改成实际 API origin
export const authClient = createAuthClient({
baseURL: `${API_ORIGIN}/auth`,
fetchOptions: { credentials: 'include' },
})
```
Better Auth 浏览器客户端默认会携带凭证；上面显式写出该选项，便于与业务请求保持一致。业务接口使用原生 `fetch` 或其他 HTTP 客户端时，也要单独配置：
```ts
const response = await fetch(`${API_ORIGIN}/profile/me`, {
credentials: 'include',
})
```
浏览器会自动保存并发送 HttpOnly 会话 Cookie。不要尝试在 JavaScript 中读取 Cookie，也不要将登录响应中的 token 当作旧 JWT 存储。服务端 `CORS_ORIGIN` 必须与前端 origin（协议、域名、端口）精确匹配；生产环境 Cookie 为 `SameSite=None; Secure`，本地开发为 `SameSite=Lax`。`BETTER_AUTH_URL` 是后端公开地址；前端客户端仍需使用上面含 `/auth` 的 URL。跨源接入和凭证设置也见 [Better Auth 的 Hono 集成文档](https://better-auth.com/docs/integrations/hono)。
### 3.3 会话与业务权限
登录成功后，使用 `authClient.getSession()` 或对应框架的 `useSession()` 获取会话：
```ts
const { error } = await authClient.signIn.email({ email, password })
if (error) throw error
const { data: session } = await authClient.getSession()
// session 为 { user, session } 或 null；退出时调用 await authClient.signOut()。
```
需要业务资料、统计及角色时，再请求 `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 凭证。
### 3.4 邮件与密码页面
注册后会发送验证邮件，用户需先验证邮箱再登录；验证成功后也不会自动登录。当前邮箱验证 token 有效期为 24 小时，密码重置 token 默认有效期为 1 小时。后端发出的邮件仍指向前端 `/verify-email?token=...` 与 `/reset-password?email=...&token=...` 页面；它们是**前端页面**，不是 API。验证页应将 token 交给 `GET /auth/verify-email?token=...`，重置页应以 token 和新密码调用 `POST /auth/reset-password`。邮件中的 `email` 可用于页面展示，重置请求不需要它。密码重置成功会撤销该用户的全部会话。
重发验证邮件使用 `authClient.sendVerificationEmail({ email })`；申请密码重置使用 `authClient.requestPasswordReset({ email })`。用户不存在时，密码重置申请仍返回通用成功结果，不要据此判断邮箱是否已注册。验证及重置流程见 [Better Auth 邮箱密码文档](https://better-auth.com/docs/authentication/email-password)。
### 3.5 认证错误与非浏览器客户端
Better Auth 端点的错误是其原生结构，通常包含 `code`、`message`；客户端调用返回 `{ data, error }`。按 HTTP 状态、客户端的 `error` 和必要时的 `error.code` 处理，不要匹配英文错误文案，也不要按业务接口的 `status_code` 或 Zod 形状解析。未验证邮箱登录会被 Better Auth 拒绝（当前版本的错误码为 `EMAIL_NOT_VERIFIED`），此时可显示验证页并提供重发邮件操作。
当前配置要求邮箱验证，且注册后不自动登录。Better Auth 对重复邮箱注册可能返回与新邮箱相同的 **200** 响应和临时生成的用户对象；因此注册成功仅表示「请查收验证邮件」，**不能仅凭响应中的 `user.id` 判断账户已创建，也不能将其用作已登录用户 ID**。应在验证后重新登录。该行为来自当前安装的 Better Auth `1.7.6`。
非浏览器客户端可使用已启用的 Bearer 插件。登录成功响应头 `set-auth-token` 暴露会话 token，后续请求使用 `Authorization: Bearer <token>`；这不是旧 JWT，也不是密码重置或邮箱验证 token。前端浏览器仍使用 Cookie。[Better Auth Bearer 插件说明](https://better-auth.com/docs/plugins/bearer)。
## 4. 端点 · 认证 `/auth`
以下为本项目已启用的 Better Auth 邮箱密码功能，密码至少 8 字符。请求 JSON 使用原生 **camelCase**，响应不带业务 `status_code` 信封。前端推荐调用第 3.2 节的客户端；直接请求时使用表中方法和路径。Better Auth 还会暴露其他内置或 Admin 插件端点，其输入、权限和响应以 [Better Auth 官方文档](https://better-auth.com/docs)及当前安装版本为准。
| 操作 | 方法与路径 | Better Auth 客户端方法 | 请求与结果要点 |
| ------------ | ------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 注册 | `POST /auth/sign-up/email` | `authClient.signUp.email({ name, email, password })` | 成功 `200`，`{ token: null, user }`；发送验证邮件，不建立会话 |
| 登录 | `POST /auth/sign-in/email` | `authClient.signIn.email({ email, password })` | 验证邮箱后才可登录；成功 `200` 并设置会话 Cookie |
| 当前会话 | `GET /auth/get-session` | `authClient.getSession()` | 有效会话返回 `{ user, session }`；无会话返回 `null` |
| 登出当前会话 | `POST /auth/sign-out` | `authClient.signOut()` | 需携带当前 Cookie 或 Bearer；撤销当前会话 |
| 重发验证邮件 | `POST /auth/send-verification-email` | `authClient.sendVerificationEmail({ email })` | `{ email }`；匿名请求对不存在或已验证邮箱也可能返回 `{ status: true }` |
| 确认邮箱 | `GET /auth/verify-email?token=...` | 可用 `fetch` 发 GET | 查询参数 `token`；无 `callbackURL` 时成功返回包含 `status: true` 的 JSON |
| 申请密码重置 | `POST /auth/request-password-reset` | `authClient.requestPasswordReset({ email })` | `{ email }`；返回通用结果，不泄露账户是否存在 |
| 重置密码 | `POST /auth/reset-password` | `authClient.resetPassword({ token, newPassword })` | `{ token, newPassword }`；成功 `{ status: true }`，撤销该用户全部会话 |
| 修改当前密码 | `POST /auth/change-password` | `authClient.changePassword({ currentPassword, newPassword, revokeOtherSessions })` | 需登录；可选择撤销其他会话 |
验证邮箱页面的请求示例：
```ts
const token = new URLSearchParams(location.search).get('token')
if (!token) throw new Error('缺少验证 token')
const response = await fetch(`${API_ORIGIN}/auth/verify-email?token=${encodeURIComponent(token)}`, {
credentials: 'include',
})
if (!response.ok) throw new Error('邮箱验证失败')
// 验证成功后引导用户登录；当前配置不会自动创建会话。
```
上面的 `API_ORIGIN` 与第 3.2 节相同。直接调用 `GET /auth/verify-email` 时不需要旧接口的 JSON 请求体；若传入 `callbackURL`，Better Auth 可能改为重定向，前端应按重定向处理。
管理员的业务管理操作继续使用第 8 章 `/admin/*` 路由。它们保持原业务响应格式，并在修改角色或密码后撤销目标会话；直接调用 Better Auth Admin 插件端点不会自动执行这些业务路由的附加操作。
---
## 5. 端点 · 云图 `/cloud`
### 5.1 `GET /cloud` — 云图列表（公开搜索）
- **认证**：无（公开）；仅返回公开可见（`approved` 且未隐藏）的云图
**Query 参数**（在分页参数 1.4 基础上）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ----------- | ------ | ---- | ----------------------------- | -------- |
| `page` | int | 否 | 默认 `1` | 见 1.4 |
| `page_size` | int | 否 | 默认 `50`，最大 `100` | 见 1.4 |
| `filter` | enum | 否 | `type` / `owner`，默认 `type` | 搜索维度 |
| `value` | string | 否 | 默认 `""`（空 = 不过滤） | 搜索词 |
搜索逻辑：
- `value` 为空 → 不过滤，返回全部公开云图
- `filter=owner`，**或** `value` 以 `@` 开头 → 按**用户名精确匹配**搜索该用户的公开云图（`@` 前缀会被去掉）
- 其他情况 → 按**云类型名称精确匹配**搜索
- 均为精确匹配，不支持模糊搜索
**成功响应**：`200`，CloudInfo 数组（字段见 1.5）
```json
[
{
"id": "3f8a2c1e-7b9d-4e5f-a1c2-9d8e7f6a5b4c",
"owner": {
"id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "cloudwatcher"
},
"type": {
"id": 3,
"name": "积云",
"genus": "Cumulus",
"icon_id": null,
"rarity": 2,
"description": "底部平坦、顶部蓬松的白色云块"
},
"latitude": 39.9042,
"longitude": 116.4074,
"description": "午后拍到的淡积云",
"captured_at": "2026-08-14T07:20:00.000Z",
"uploaded_at": "2026-08-15T08:30:00.000Z",
"updated_at": "2026-08-15T08:30:00.000Z",
"received_like_count": 12,
"status": "approved",
"is_hidden": false
}
]
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | -------------------------------- | -------------------- | ------------------------------------------ |
| 400 | 参数校验失败（如 `page_size=0`） | zod 形状（2.1） | 检查参数 |
| 404 | 按用户名搜索但该用户不存在 | `该用户不存在` | 提示「没有找到这个用户」，不要显示为空列表 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：按云类型搜索时类型名不存在**不报错**，返回空数组（与用户名搜索的 404 行为不同）。
### 5.2 `GET /cloud/map` — 时间范围地图数据
- **认证**：无（公开）；仅返回公开可见的云图
**Query 参数**：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ------------ | ----------- | ---- | ------------------------------------------------- | ----------------------------------- |
| `start` | date string | 是 | 须 ≤ `end` | 范围起点，如 `2026-08-01T00:00:00Z` |
| `end` | date string | 是 | — | 范围终点 |
| `time_field` | enum | 否 | `captured_at` / `uploaded_at`，默认 `captured_at` | 按拍摄时间还是上传时间过滤 |
| `limit` | int | 否 | 1–1000，默认 `1000` | 返回上限（不分页） |
**成功响应**：`200`，CloudInfo 数组，按 `time_field` 倒序（同刻按 `id` 倒序），结构同 5.1。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ------------------ | ------------------------------------------------ | ------------ |
| 400 | `start` 晚于 `end` | zod 形状，issues 中含 `开始时间不能晚于结束时间` | 表单前置校验 |
| 400 | 其他参数校验失败 | zod 形状（2.1） | 检查参数 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：`time_field=captured_at`（默认）时，`captured_at` 为 `null` 的云图**不会出现在结果中**；需要全量数据时请用 `uploaded_at`。
### 5.3 `GET /cloud/:cloud_id` — 云图详情
- **认证**：可选。匿名访客按公开可见规则过滤；上传者本人可见自己的全部云图；admin 可见全部
- 无效/过期会话凭证按匿名处理，**不会**返回 401
**路径参数**：
| 参数 | 类型 | 说明 |
| ---------- | ---- | ------- |
| `cloud_id` | uuid | 云图 ID |
**成功响应**：`200`，单个 CloudInfo 对象（字段见 1.5），结构同 5.1 的数组元素。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------ |
| 400 | `cloud_id` 不是合法 uuid | zod 形状（2.1） | 检查链接 |
| 404 | 云图不存在，**或**对当前用户不可见（待审核/已驳回/已隐藏） | `未找到图片` | 统一提示「云图不存在或不可见」——服务端故意不区分，防止泄露私有云图的存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
### 5.4 `GET /cloud/type/:cloud_type_id` — 按云类型列出云图
- **认证**：无（公开）；仅返回公开可见的云图
**路径参数**：
| 参数 | 类型 | 说明 |
| --------------- | ---- | --------------------------- |
| `cloud_type_id` | int | 云类型 ID（非数字返回 400） |
**Query 参数**：分页参数，见 1.4。
**成功响应**：`200`，CloudInfo 数组，结构同 5.1。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ------------ | -------------------- | -------------- |
| 400 | 参数校验失败 | zod 形状（2.1） | 检查参数 |
| 404 | 云类型不存在 | `云类型不存在` | 提示类型不存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
### 5.5 `PUT /cloud/:cloud_id/like` — 点赞
- **认证**：需登录（任意角色）
- **请求体**：无
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "点赞成功"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ------------------------------ | -------------------- | -------------------------------------------- |
| 401 | 未登录 / token 失效 | 见 3.3 | 引导登录 |
| 404 | 云图不存在，或不是公开可见状态 | `图片不存在` | 提示云图不可点赞；与「不存在」共用是设计意图 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：**幂等**——重复点赞返回相同的 200，点赞数不会增加。旧 `POST /cloud/:cloud_id/like` 已移除；前端改用 `PUT`。前端无需在点击前查询是否已赞，但仍建议本地置灰防止连点。
### 5.6 `DELETE /cloud/:cloud_id/like` — 取消点赞
- **认证**：需登录（任意角色）
- **请求体**：无
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "取消点赞成功"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ------------------- | -------------------- | ------------ |
| 401 | 未登录 / token 失效 | 见 3.3 | 引导登录 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：**完全幂等**——从未点赞、云图不存在，同样返回 200。没有 404 分支。
### 5.7 `POST /cloud` — 上传云图
- **认证**：需登录（任意角色）
- **Content-Type**：`multipart/form-data`；请求体总上限 21 MiB（图片约束见 1.6）
**表单字段**（multipart 字段均为字符串）：
| 字段 | 类型 | 必填 | 约束 | 说明 |
| ------------- | ----------- | ------ | ------------------------------------------- | ---------------------------------------- |
| `image` | file | 是 | 1 B – 20 MB，JPEG/PNG/WebP，非动图 | 图片文件 |
| `type_id` | int | 是 | 正整数 | 云类型 ID（从 `/info/cloudtype` 获取） |
| `latitude` | number | 是 | -90 ~ 90 | 纬度 |
| `longitude` | number | 是 | -180 ~ 180 | 经度 |
| `description` | string | 否 | ≤ 128 字符 | 描述 |
| `captured_at` | date string | 否 | 合法日期 | 拍摄时间 |
| `is_hidden` | string | **是** | 仅接受 `"true"` / `"false"` / `"1"` / `"0"` | 是否隐藏；其他写法（如 `"yes"`）返回 400 |
**成功响应**：`201`
```json
{
"status_code": 201,
"message": "上传成功",
"cloud_id": "3f8a2c1e-7b9d-4e5f-a1c2-9d8e7f6a5b4c"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | --------------------------------------------------- | ------------------------------- | -------------------------------------------- |
| 400 | 图片为空文件 | `图片为空` | 提示重新选择 |
| 400 | 图片超过 20 MB | `图片大小超过 20MB 限制` | 提示压缩 |
| 400 | 格式不支持 | `仅支持 JPEG、PNG、WebP 格式` | 提示转换格式 |
| 400 | 动图 | `不支持动图` | 提示使用静态图 |
| 400 | 分辨率超上限 | `图片分辨率超过限制` | 提示缩小尺寸 |
| 400 | 其他图片处理失败 | `压缩参数无效` / `图片处理失败` | 提示换图重试 |
| 400 | 表单字段校验失败（如 `is_hidden` 编码非法、缺字段） | zod 形状（2.1） | 检查表单 |
| 401 | 未登录 / token 失效 | 见 3.3 | 引导登录 |
| 413 | 请求体超过 21 MiB | `上传文件过大` | 提示压缩图片 |
| 500 | 服务端异常（含存储/数据库失败） | `服务器发生内部错误` | 稍后重试；服务端已做失败补偿清理，可安全重试 |
**注意事项**：
- 上传成功后云图为 `pending`（待审核），**不会出现在公开列表**，本人可在「我的云图」（6.4）中看到
- `type_id` 指向不存在的云类型会导致 500（外键约束），前端应确保类型 ID 来自 `/info/cloudtype`
### 5.8 `PATCH /cloud/:cloud_id` — 更新云图
- **认证**：需登录，且为上传者本人。**非本人的云图返回 404 而非 403**（防止泄露存在性）
**路径参数**：`cloud_id`（uuid）。
**请求体**（JSON，至少提供一个字段，否则 400）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ------------- | ----------- | ---- | ---------- | ------------------------------- |
| `latitude` | number | 否 | -90 ~ 90 | 纬度 |
| `longitude` | number | 否 | -180 ~ 180 | 经度 |
| `type_id` | int | 否 | 正整数 | ⚠️ 不校验存在性，非法值导致 500 |
| `description` | string | 否 | ≤ 128 字符 | 描述 |
| `captured_at` | date string | 否 | 合法日期 | 拍摄时间 |
| `is_hidden` | boolean | 否 | — | 是否隐藏（JSON 布尔值） |
```json
{
"description": "补充：拍摄于景山公园",
"is_hidden": false
}
```
**成功响应**：`200`，`{ "status_code": 200, "message": "更新成功" }`
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | --------------------------------- | ------------------------------------------------ | -------------- |
| 400 | 未提供任何修改字段 | zod 形状，issues 中含 `至少需要提供一个修改字段` | 表单前置校验 |
| 400 | 参数校验失败 | zod 形状（2.1） | 检查字段 |
| 401 | 未登录 / token 失效 | 见 3.3 | 引导登录 |
| 404 | 云图不存在或不属于当前用户 | `图片不存在` | 提示云图不存在 |
| 500 | 服务端异常（含 `type_id` 不存在） | `服务器发生内部错误` | 稍后重试 |
### 5.9 `DELETE /cloud/:cloud_id` — 删除云图
- **认证**：需登录，且为上传者本人（非本人返回 404，同 5.8）
**成功响应**：`200`，`{ "status_code": 200, "message": "删除成功" }`
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | -------------------------- | -------------------- | -------------- |
| 401 | 未登录 / token 失效 | 见 3.3 | 引导登录 |
| 404 | 云图不存在或不属于当前用户 | `图片不存在` | 提示云图不存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
### 5.10 `DELETE /cloud` — 批量删除云图
- **认证**：需登录；仅删除属于当前用户的云图
**请求体**（JSON）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ----------- | ----- | ---- | ------------------------ | -------------------------------------- |
| `cloud_ids` | array | 是 | 1–100 个元素，不允许重复 | 元素为 `{ "cloud_id": "<uuid>" }` 对象 |
```json
{
"cloud_ids": [
{ "cloud_id": "3f8a2c1e-7b9d-4e5f-a1c2-9d8e7f6a5b4c" },
{ "cloud_id": "b4c5d6e7-f8a9-4b5c-9d0e-1f2a3b4c5d6e" }
]
}
```
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "成功删除 2 张图片"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ----------------------------------- | ------------------------------------------------ | -------------- |
| 400 | ID 重复 / 数量超出 1–100 / 格式非法 | zod 形状，ID 重复时 issues 含 `图片 ID 不能重复` | 前端去重后提交 |
| 401 | 未登录 / token 失效 | 见 3.3 | 引导登录 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：**部分成功语义**——只删除属于当前用户的云图，他人或不存在的 ID 被静默跳过，消息中的 `N` 是实际删除数（可能小于请求数，甚至为 0）。前端应以 `N` 为准刷新列表，而不是假设全部删除成功。
### 5.11 `GET|HEAD /image/:cloud_id/:variant` — 读取图片变体
- **认证**：可选。匿名访客与无关用户只能读取具备 PublicVisibility 的 Cloud；上传者可读取自己的全部 Cloud；admin 可读取全部 Cloud
- **严格凭证**：完全不携带凭证时按匿名处理；一旦携带无效/过期 Bearer 或 Cookie，返回 401，不会降级为匿名。Bearer 与 Cookie 同时存在时 Bearer 优先
- **响应**：应用先查询 Cloud 权限，再从 MinIO 流式代理图片；客户端不能提交 bucket 或 object key
**路径参数**：
| 参数 | 类型 | 说明 |
| ---------- | ---- | ------------------------------------------------------- |
| `cloud_id` | uuid | Cloud ID，由上传响应、列表或详情接口取得 |
| `variant` | enum | `preview`（最大 640×640 WebP）或 `original`（上传原图） |
两种图片变体采用相同权限规则。示例：
```html
<img src="https://api.example.com/image/3f8a2c1e-7b9d-4e5f-a1c2-9d8e7f6a5b4c/preview" alt="云图" />
```
**成功响应**：
- `GET` 返回 200 和图片字节，`Content-Type` 仅可能为 `image/jpeg`、`image/png` 或 `image/webp`
- `HEAD` 返回与 GET 相同的授权结果和响应头，但没有 body，也不会读取 MinIO 对象 body
- 返回 `Content-Length`、`Content-Disposition: inline`、`ETag`、`Last-Modified` 与 `X-Content-Type-Options: nosniff`
- 携带匹配的 `If-None-Match` 时返回 304；认证和 PublicVisibility 检查仍会执行
**缓存**：
| 调用方式 | `Cache-Control` |
| -------------------------------------- | ------------------- |
| 匿名读取具备 PublicVisibility 的 Cloud | `public, no-cache` |
| 任何有效 Cookie/Bearer 请求 | `private, no-store` |
响应同时包含 `Vary: Authorization, Cookie`。公开缓存每次复用前都必须回源验证，因此 Cloud 被隐藏或改判后立即失效。
**错误**：
| 状态码 | 触发条件 | 前端建议动作 |
| ------ | ------------------------------------------------------- | ------------------------------ |
| 400 | Cloud ID 或 ImageVariant 非法 | 检查 URL |
| 401 | 显式提供的 Better Auth 会话无效或过期 | 清除本地登录态 |
| 404 | Cloud 不存在、当前用户不可见，或对应 MinIO 对象不存在 | 统一显示占位图，不推断具体原因 |
| 405 | 使用 GET/HEAD 之外的业务方法；响应含 `Allow: GET, HEAD` | 修正请求方法 |
| 500 | 数据库或应用内部错误 | 稍后重试 |
| 503 | MinIO 暂时不可用或对象 metadata 异常 | 稍后重试 |
具备 PublicVisibility 的 Cloud 允许被其他网站嵌入；流量限制由部署网关/CDN/WAF 负责。端点不支持 Range 请求。CORS 预检 `OPTIONS` 是协议级例外，由全局中间件返回 204，并只声明 `GET, HEAD`。
---
## 6. 端点 · 个人资料 `/profile`
本章所有端点**都需要登录**（任意角色）。未登录统一返回 401（见 3.3），下文错误表不再重复列出。
### 6.1 `GET /profile/me` — 我的资料
- **认证**：需登录
**成功响应**：`200`，UserProfile 对象（字段见 1.5）
```json
{
"id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "cloudwatcher",
"email": "watcher@example.com",
"image": "https://example.com/avatar.png",
"cloud_count": 7,
"received_like_count": 42,
"last_online": "2026-08-15T08:30:00.000Z",
"role": "user",
"is_disabled": false,
"created_at": "2026-07-01T10:00:00.000Z"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ---------------------------------------- | ---------------------- | ---------------------- |
| 404 | ⚠️ 数据库异常（空 `catch`，2.3 第 2 条） | 纯文本 `404 Not Found` | 视为服务异常，稍后重试 |
### 6.2 `PATCH /profile/me` — 修改用户名
- **认证**：需登录
**请求体**（JSON）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ----------- | ------ | ---- | --------------------------------------------------- | -------- |
| `user_name` | string | 是 | ⚠️ 数据库限 ≤ 16 字符，API 层不校验（超长返回 500） | 新用户名 |
```json
{
"user_name": "newname"
}
```
**成功响应**：`200`，更新后的 UserProfile 对象（结构同 6.1）。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | -------------------------------------------- | -------------------- | ---------------------------- |
| 400 | 参数校验失败 | zod 形状（2.1） | 检查字段 |
| 409 | 用户名已被占用（数据库唯一约束，大小写敏感） | `用户名已被占用` | 提示换用户名 |
| 500 | 服务端异常（含用户名超长） | `服务器发生内部错误` | 前端应限制 ≤ 16 字符避免误报 |
### 6.3 `GET /profile/me/likes` — 我点赞过的云图
- **认证**：需登录
- **Query 参数**：分页参数 `page`、`page_size`，见 1.4
**成功响应**：`200`，CloudInfo 数组（字段见 1.5），按点赞时间倒序、同刻按云图 ID 倒序；默认返回第 1 页的 50 条，最多每页 100 条。超出范围的页返回 `[]`。
**注意事项**：包含**所有状态**的云图（含待审核/已驳回/已隐藏的），因为这些是你自己点过赞的——展示时如需隐藏非公开项请自行过滤 `status` 与 `is_hidden`。
**错误**：分页参数非法时返回 400（见 2.1）；服务端异常返回 500 `服务器发生内部错误`。
### 6.4 `GET /profile/me/clouds` — 我上传的云图
- **认证**：需登录
**成功响应**：`200`，CloudInfo 数组（字段见 1.5），按上传时间倒序，包含所有状态（`pending`/`approved`/`rejected`）与隐藏的云图。这是上传后查看审核进度的入口。
**错误**：500 `服务器发生内部错误`。
### 6.5 `GET /profile/:user_id` — 查看用户资料
- **认证**：需登录（任意登录用户可查看任意用户）
**路径参数**：`user_id`（uuid）。
**成功响应**：`200`，UserProfile 对象（结构同 6.1）。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ----------------------- | -------------------- | -------------- |
| 400 | `user_id` 不是合法 uuid | zod 形状（2.1） | 检查链接 |
| 404 | 用户不存在 | `该用户不存在` | 提示用户不存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：⚠️ 响应包含对方 `email`（2.3 第 7 条）。展示他人资料页时不应展示邮箱字段。
### 6.6 `GET /profile/:user_id/clouds` — 查看用户上传的云图
- **认证**：需登录，且为**本人或 admin**
**路径参数**：`user_id`（uuid）。
**成功响应**：`200`，CloudInfo 数组，按上传时间倒序，结构同 5.1。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ------------------ | ---------------------- | -------------- |
| 403 | 查看他人且非 admin | `无权查看该用户的图片` | 同上，前置判断 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：想查看某个用户的**公开**云图，应使用 `GET /cloud?filter=owner&value=<用户名>`（5.1）而非本端点——本端点是管理/个人视角，返回含非公开状态的完整列表。
---
## 7. 端点 · 信息 `/info`
### 7.1 `GET /info/cloudtype` — 云类型列表
- **认证**：无（公开）
**成功响应**：`200`，CloudTypeInfo 数组（字段见 1.5），按 `id` 升序：
```json
[
{
"id": 1,
"name": "积云",
"genus": "Cumulus",
"icon_id": null,
"rarity": 1,
"description": "底部平坦、顶部蓬松的白色云块",
"created_at": "2026-01-01 00:00:00+00"
}
]
```
**注意事项**：⚠️ 本端点的 `created_at` 是 PostgreSQL 原生格式（上例），**不是** ISO 8601（2.3 第 5 条），解析时自行兼容。
**错误**：500 `服务器发生内部错误`。
### 7.2 `GET /info/cloudtype/:cloud_type_id` — 云类型详情
- **认证**：无（公开）
**路径参数**：`cloud_type_id`（int）。
**成功响应**：`200`，单个 CloudTypeInfo 对象；本端点的 `created_at` 为 ISO 8601 格式。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ---------------------- | -------------------- | -------------- |
| 400 | `cloud_type_id` 非数字 | zod 形状（2.1） | 检查链接 |
| 404 | 云类型不存在 | `未找到` | 提示类型不存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
---
## 8. 端点 · 管理 `/admin`
本章所有端点**仅 admin 角色可用**。未登录返回 401；已登录但非 admin 统一返回 403 `权限不足`，下文错误表不再重复列出。
### 8.1 `GET /admin/stats` — 统计数据
> ⚠️ **未实现**（占位端点，无 handler）。admin 请求返回纯文本 `404 Not Found`；未登录/非 admin 仍按本章规则先返回 401/403。请勿接入。
### 8.2 `GET /admin/users` — 用户列表
- **认证**：admin
**成功响应**：`200`，UserProfile 数组（字段见 1.5）。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ---------------------------------------- | ---------------------- | ---------------------- |
| 404 | ⚠️ 数据库异常（空 `catch`，2.3 第 2 条） | 纯文本 `404 Not Found` | 视为服务异常，稍后重试 |
**注意事项**：**无分页参数**，一次返回全部用户。用户量大时注意性能。
### 8.3 `PATCH /admin/users/:user_id` — 修改用户角色
- **认证**：admin
**路径参数**：`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） | 检查参数 |
| 400 | 管理员尝试撤销自己的 admin 角色 | `不能撤销自己的管理员角色` | 保持当前管理员角色 |
| 404 | 用户不存在 | `用户不存在` | 提示用户不存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：修改角色会撤销目标用户的全部 Better Auth 会话，必须重新登录。前端改完角色后可提示目标用户重新登录。
### 8.4 `PATCH /admin/users/:user_id/password` — 设置用户密码
- **认证**：admin
**路径参数**：`user_id`（uuid）。
**请求体**（JSON）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| -------------- | ------ | ---- | ----------- | ---------------------------------- |
| `new_password` | string | 是 | 至少 8 字符 | 新密码；管理员直接覆盖，无需旧密码 |
```json
{
"new_password": "new-s3cret-password"
}
```
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "密码修改成功"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | --------------------------------------------------- | -------------------- | -------------- |
| 400 | 参数校验失败（`user_id` 非 uuid 或密码少于 8 字符） | zod 形状（2.1） | 检查参数 |
| 404 | 用户不存在（含凭据记录缺失） | `用户不存在` | 提示用户不存在 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：成功后会撤销目标用户的全部 Better Auth 会话，必须重新登录。
### 8.5 `POST /admin/user` — 创建用户
管理员认证后提交 `{ "name": "Alice", "email": "alice@example.com", "password": "password123", "role": "user" }`。通过 Better Auth Admin 插件创建用户和密码凭据，再尝试发送邮箱验证邮件。成功返回 `201`，包含 `status_code`、`message`、`user_id`、`email_sent`；用户名或邮箱冲突返回 `409`。密码至少 8 字符。
### 8.6 `POST /admin/cloudtypes` — 添加云类型
- **认证**：admin
**请求体**（JSON）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ------------- | ------------ | ---- | ------------------ | ----------------------------- |
| `name` | string | 是 | 去除首尾空白后非空 | 云类型名称 |
| `genus` | string\|null | 否 | 默认 `null` | 属；传 `null` 表示未设置 |
| `icon_id` | uuid\|null | 否 | 默认 `null` | 图标 ID；传 `null` 表示未设置 |
| `rarity` | int | 是 | — | 稀有度 |
| `description` | string | 是 | 最长 128 字符 | 描述，可为空字符串 |
```json
{
"name": "积云",
"genus": "Cumulus",
"icon_id": null,
"rarity": 1,
"description": "底部平坦、顶部蓬松的白色云块"
}
```
**成功响应**：`201`
```json
{
"status_code": 201,
"message": "云类型添加成功",
"cloud_type_id": 12
}
```
云类型 ID 由服务端生成；并发添加不会分配重复 ID。参数校验失败返回 400，数据库异常返回 500。
### 8.7 `PATCH /admin/cloudtypes/:cloud_type_id` — 修改云类型
- **认证**：admin
**路径参数**：`cloud_type_id`（int）。请求体字段与 8.6 相同，但均为可选；至少须提供一个字段。仅提交的字段会被修改，`genus` 和 `icon_id` 可显式传 `null` 清空。
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "云类型修改成功"
}
```
**错误**：参数或空请求体无效返回 400；云类型不存在返回 404 `云类型不存在`；数据库异常返回 500。
### 8.8 `DELETE /admin/cloudtypes/:cloud_type_id` — 删除云类型
- **认证**：admin
**路径参数**：`cloud_type_id`（int）。
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "云类型删除成功"
}
```
**错误**：参数无效返回 400；云类型不存在返回 404 `云类型不存在`；仍有云图使用该类型时返回 409 `云类型仍被云图使用，无法删除`；其他数据库异常返回 500。
### 8.9 `GET /admin/clouds` — 全状态云图列表
- **认证**：admin；可见任意状态与隐藏的云图
**Query 参数**（在分页参数 1.4 基础上）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| -------- | ---- | ---- | ----------------------------------- | -------------------------------- |
| `status` | enum | 否 | `pending` / `approved` / `rejected` | 按审核状态过滤；不传返回全部状态 |
**成功响应**：`200`，CloudInfo 数组（字段见 1.5），按上传时间倒序。
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ----------------------- | -------------------- | ------------ |
| 400 | `status` 非法等参数错误 | zod 形状（2.1） | 检查参数 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
### 8.10 `POST /admin/clouds/review` — 批量审核云图
- **认证**：admin
**请求体**（JSON）：
| 参数 | 类型 | 必填 | 约束 | 说明 |
| ----------- | ----- | ---- | ------------------------ | -------------------------------------- |
| `cloud_ids` | array | 是 | 1–100 个元素，不允许重复 | 元素为 `{ "cloud_id": "<uuid>" }` 对象 |
| `status` | enum | 是 | `approved` / `rejected` | 目标审核状态；**不支持打回 `pending`** |
```json
{
"cloud_ids": [{ "cloud_id": "3f8a2c1e-7b9d-4e5f-a1c2-9d8e7f6a5b4c" }],
"status": "approved"
}
```
**成功响应**：`200`
```json
{
"status_code": 200,
"message": "成功审核 1 张"
}
```
**错误**：
| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
| ------ | ---------------------------------- | -------------------- | ------------ |
| 400 | ID 重复 / `status` 非法 / 数量超限 | zod 形状（2.1） | 检查请求 |
| 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |
**注意事项**：**部分成功语义**——消息中的 `N` 只统计状态**实际发生变化**的云图；已是目标状态的与不存在的一律静默跳过。审核只改变审核状态，不影响 `is_hidden` 与点赞数据。`pending ↔ approved/rejected`、`approved ↔ rejected` 均可。
### 8.11 `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 中的图片对象；清理失败不报错，可能残留孤儿对象（可接受）。删除后前端应立即刷新相关列表。
### 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. 端点 · 系统
### 9.1 `ALL /health` · 9.2 `ALL /status`
> ⚠️ **均未实现**（占位端点，任意 HTTP 方法）。当前返回纯文本 `404 Not Found`。健康检查请直接探测任意已实现端点（如 `GET /info/cloudtype`）。
Reference in New Issue View Git Blame Copy Permalink