755 lines
35 KiB
Markdown
755 lines
35 KiB
Markdown
# API 接口文档
|
||
|
||
本文档用于快速了解 `yoyuzh.xyz` 当前后端 API 的职责、鉴权方式和主要接口分组。
|
||
|
||
## 1. 基本约定
|
||
|
||
### 基础路径
|
||
|
||
- 后端接口统一以 `/api` 开头
|
||
- 本地开发默认地址：`http://localhost:8080`
|
||
|
||
### 返回格式
|
||
|
||
大部分接口返回统一结构：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
常见含义：
|
||
|
||
- `code = 0`：成功
|
||
- `code = 1000`：参数校验失败
|
||
- `code = 1001`：未登录
|
||
- `code = 1002`：权限不足
|
||
- `code = 1003`：业务对象不存在、邀请码错误、取件码失效等业务失败
|
||
|
||
### 鉴权方式
|
||
|
||
- 采用 `Authorization: Bearer <accessToken>`
|
||
- `refreshToken` 通过 `/api/auth/refresh` 换取新的登录态
|
||
- 当前实现为“按客户端类型拆分会话”
|
||
- 桌面端与移动端可以同时在线
|
||
- 同一端类型再次登录后，该端旧 access token 会失效
|
||
- `/api/auth/register`、`/api/auth/login`、`/api/auth/refresh` 与开发环境 `/api/auth/dev-login` 支持可选请求头 `X-Yoyuzh-Client: desktop|mobile`
|
||
|
||
### 权限分层
|
||
|
||
- 公开接口：
|
||
- `/api/auth/**`
|
||
- `/api/transfer/**`
|
||
- `GET /api/files/share-links/{token}`
|
||
- 登录后接口：
|
||
- `/api/user/**`
|
||
- `/api/files/**`
|
||
- `/api/admin/**`
|
||
|
||
## 2. 认证模块
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/auth/AuthController.java`
|
||
- `backend/src/main/java/com/yoyuzh/auth/DevAuthController.java`
|
||
- `backend/src/main/java/com/yoyuzh/auth/UserController.java`
|
||
|
||
### 2.1 注册
|
||
|
||
`POST /api/auth/register`
|
||
|
||
说明：
|
||
|
||
- 使用邀请码注册
|
||
- 注册成功后直接返回登录态
|
||
- 邀请码成功使用后会自动刷新
|
||
- 若请求未显式带 `X-Yoyuzh-Client`，后端默认按 `desktop` 处理
|
||
|
||
请求重点字段：
|
||
|
||
- `username`
|
||
- `email`
|
||
- `phoneNumber`
|
||
- `password`
|
||
- `confirmPassword`
|
||
- `inviteCode`
|
||
|
||
### 2.2 登录
|
||
|
||
`POST /api/auth/login`
|
||
|
||
请求字段：
|
||
|
||
- `username`
|
||
- `password`
|
||
|
||
返回字段：
|
||
|
||
- `token`
|
||
- `accessToken`
|
||
- `refreshToken`
|
||
- `user`
|
||
|
||
补充说明：
|
||
|
||
- 可选请求头 `X-Yoyuzh-Client` 用于声明当前登录来自桌面端还是移动端
|
||
- 同账号桌面端与移动端可同时保持登录，但同类型端再次登录会顶掉旧会话
|
||
|
||
### 2.3 刷新登录态
|
||
|
||
`POST /api/auth/refresh`
|
||
|
||
请求字段：
|
||
|
||
- `refreshToken`
|
||
|
||
说明：
|
||
|
||
- 刷新后会返回新的 access token 与 refresh token
|
||
- 当前系统会让旧 refresh token 失效
|
||
- 刷新会沿用该 refresh token 原本所属的客户端类型；请求头缺省时仍按 `desktop` 兜底
|
||
|
||
### 2.4 开发环境登录
|
||
|
||
`POST /api/auth/dev-login`
|
||
|
||
说明：
|
||
|
||
- 仅用于开发联调
|
||
- 是否可用取决于当前环境配置
|
||
- 同样支持可选请求头 `X-Yoyuzh-Client: desktop|mobile`
|
||
|
||
### 2.5 Android 客户端更新信息
|
||
|
||
`GET /api/app/android/latest`
|
||
|
||
说明：
|
||
|
||
- 公开接口，不需要登录
|
||
- 返回当前 Android 安装包下载地址、文件名和最新发布时间
|
||
- 后端会先读取文件桶中的 `android/releases/latest.json` 元数据，再返回当前 APK 对应的后端下载地址
|
||
- 安卓端原生壳应通过该接口检查更新
|
||
|
||
### 2.6 Android 客户端下载入口
|
||
|
||
`GET /api/app/android/download`
|
||
|
||
说明：
|
||
|
||
- 公开接口，不需要登录
|
||
- 该接口会直接回传当前最新 APK 的字节流，并通过 `Content-Disposition` 指定带版本号的文件名
|
||
- Web 端总览页应直接使用这个公开下载入口，而不是直接访问对象存储路径
|
||
|
||
### 2.7 获取用户资料
|
||
|
||
`GET /api/user/profile`
|
||
|
||
### 2.8 更新用户资料
|
||
|
||
`PUT /api/user/profile`
|
||
|
||
### 2.9 修改密码
|
||
|
||
`POST /api/user/password`
|
||
|
||
说明：
|
||
|
||
- 成功后会重新签发新的登录态
|
||
- 同时会顶掉旧设备会话
|
||
|
||
### 2.10 头像相关
|
||
|
||
- `POST /api/user/avatar/upload/initiate`
|
||
- `POST /api/user/avatar/upload`
|
||
- `POST /api/user/avatar/upload/complete`
|
||
- `GET /api/user/avatar/content`
|
||
|
||
说明：
|
||
|
||
- 支持初始化直传
|
||
- 支持代理上传
|
||
- 最终通过完成接口落库
|
||
|
||
## 3. 网盘模块
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/files/core/FileController.java`
|
||
|
||
### 3.1 上传相关
|
||
|
||
- `POST /api/files/upload`
|
||
- `POST /api/files/upload/initiate`
|
||
- `POST /api/files/upload/complete`
|
||
|
||
说明：
|
||
|
||
- 兼容普通上传和 OSS 直传
|
||
- 前端会优先尝试“初始化上传 -> 直传/代理 -> 完成上传”
|
||
- `upload/initiate` 返回的 `storageName` 现在是一次上传对应的 opaque blob object key；新文件会落到全局 `blobs/...` key，而不是用户目录路径 key
|
||
- `upload/complete` 必须回传这个 opaque blob key，后端会据此创建 `FileBlob` 并把新 `StoredFile` 绑定到该 blob
|
||
|
||
### 3.2 目录与列表
|
||
|
||
- `POST /api/files/mkdir`
|
||
- `GET /api/files/list`
|
||
- `GET /api/files/recent`
|
||
|
||
说明：
|
||
|
||
- `list` 支持 `path`、`page`、`size`
|
||
- 当前前端会在网盘页缓存目录内容和最后访问路径
|
||
|
||
### 3.3 下载
|
||
|
||
- `GET /api/files/download/{fileId}`
|
||
- `GET /api/files/download/{fileId}/url`
|
||
|
||
说明：
|
||
|
||
- 普通文件优先获取下载 URL
|
||
- 文件夹可走 ZIP 下载
|
||
- 私有 `apk/ipa` 下载会返回一个短时有效的 `https://api.yoyuzh.xyz/_dl/...` URL；该 URL 由 Nginx 按签名和过期时间校验后代理到对象存储自定义下载域名，不是长期可复用的公开直链
|
||
|
||
### 3.4 文件操作
|
||
|
||
- `PATCH /api/files/{fileId}/rename`
|
||
- `PATCH /api/files/{fileId}/move`
|
||
- `POST /api/files/{fileId}/copy`
|
||
- `DELETE /api/files/{fileId}`
|
||
- `GET /api/files/recycle-bin`
|
||
- `POST /api/files/recycle-bin/{fileId}/restore`
|
||
|
||
说明：
|
||
|
||
- `move` 用于移动到目标路径
|
||
- `copy` 用于复制到目标路径
|
||
- 文件和文件夹都支持移动 / 复制
|
||
- 普通文件的 `move` / `rename` / `copy` 只改逻辑元数据；`copy` 会复用原有 `FileBlob`，不会复制底层对象
|
||
- `DELETE /api/files/{fileId}` 现在语义是“移入回收站”，不会立刻物理删除；删除的文件或整个目录树会保留 10 天
|
||
- `GET /api/files/recycle-bin` 返回当前用户回收站根条目分页列表，包含删除时间和预计清理时间
|
||
- `POST /api/files/recycle-bin/{fileId}/restore` 用于把某个回收站根条目恢复到原目录；若原位置已有同名文件，或当前剩余空间不足，则恢复失败
|
||
|
||
### 3.5 分享链接
|
||
|
||
- `POST /api/files/{fileId}/share-links`
|
||
- `GET /api/files/share-links/{token}`
|
||
- `POST /api/files/share-links/{token}/import`
|
||
|
||
说明：
|
||
|
||
- 已登录用户可为自己的文件或文件夹创建分享链接
|
||
- 公开访客可查看分享详情
|
||
- 登录用户可将分享内容导入自己的网盘
|
||
- 普通文件导入时会新建自己的 `StoredFile` 并复用源 `FileBlob`，不会再次写入物理文件
|
||
|
||
### 3.6 v2 上传会话
|
||
|
||
- `POST /api/v2/files/upload-sessions`
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}`
|
||
- `DELETE /api/v2/files/upload-sessions/{sessionId}`
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}/prepare`
|
||
- `POST /api/v2/files/upload-sessions/{sessionId}/content`
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}/parts/{partIndex}/prepare`
|
||
- `PUT /api/v2/files/upload-sessions/{sessionId}/parts/{partIndex}`
|
||
- `POST /api/v2/files/upload-sessions/{sessionId}/complete`
|
||
|
||
说明：
|
||
|
||
- 需要登录，只允许操作当前用户自己的上传会话
|
||
- 会话响应返回 `sessionId`、`objectKey`、`directUpload`、`multipartUpload`、`uploadMode`、`path`、`filename`、`contentType`、`size`、`storagePolicyId`、`status`、`chunkSize`、`chunkCount`、`expiresAt`、`createdAt`、`updatedAt`，以及一个面向前端消费的 `strategy` 对象
|
||
- `uploadMode` 目前有三种：`PROXY`、`DIRECT_SINGLE`、`DIRECT_MULTIPART`
|
||
- 默认 S3 存储策略下，创建会话时会立即初始化 multipart upload，并把 `directUpload=true`、`multipartUpload=true`、`uploadMode=DIRECT_MULTIPART` 返回给客户端；若默认策略 `directUpload=true` 但 `multipartUpload=false`，会返回 `DIRECT_SINGLE`；若 `directUpload=false`，则返回 `PROXY`
|
||
- `strategy` 会把当前会话下一步该调用的后端入口显式返回出来：`DIRECT_SINGLE` 返回 `prepareUrl` + `completeUrl`，`PROXY` 返回 `proxyContentUrl` + `proxyFormField=file` + `completeUrl`，`DIRECT_MULTIPART` 返回 `partPrepareUrlTemplate`、`partRecordUrlTemplate` 和 `completeUrl`
|
||
- `GET /{sessionId}/prepare` 仅用于 `DIRECT_SINGLE`，返回整文件直传所需的 `direct/uploadUrl/method/headers/storageName`
|
||
- `POST /{sessionId}/content` 仅用于 `PROXY`，以 multipart 表单上传整文件内容到当前 upload session 绑定的 `objectKey`
|
||
- `GET /parts/{partIndex}/prepare` 会返回当前分片的直传信息：`direct`、`uploadUrl`、`method`、`headers`、`storageName`
|
||
- `PUT /parts/{partIndex}` 请求体仍为 `{ "etag": "...", "size": 8388608 }`，只负责记录 part 元数据，不直接接收字节流
|
||
- `POST /complete` 会先按已记录的 part 元数据提交 multipart complete，再复用旧上传完成链路写入 `FileBlob + StoredFile + FileEntity.VERSION`
|
||
- 后端每小时清理过期且未完成的会话；若会话已绑定 multipart upload，会优先向对象存储发送 abort
|
||
- 当前前端网盘上传主链路已经消费这套 v2 接口：桌面/移动文件页和“存入网盘”入口都会按 `uploadMode + strategy` 自动选择代理上传、单请求直传或 multipart 分片上传
|
||
|
||
## 4. 快传模块
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/transfer/TransferController.java`
|
||
|
||
### 4.1 创建会话
|
||
|
||
`POST /api/transfer/sessions`
|
||
|
||
说明：
|
||
|
||
- 在线快传会话允许未登录用户创建
|
||
- 离线快传会话仍要求发送端登录
|
||
- 请求体必须区分 `mode`
|
||
- `ONLINE`: 在线快传，15 分钟有效，只能被接收一次
|
||
- `OFFLINE`: 离线快传，7 天有效，文件会落到站点存储并可被重复接收
|
||
- 返回会话 ID、取件码、模式、过期时间和文件清单
|
||
|
||
### 4.2 通过取件码查找会话
|
||
|
||
`GET /api/transfer/sessions/lookup?pickupCode=xxxxxx`
|
||
|
||
说明：
|
||
|
||
- 接收端通过 6 位取件码查找会话
|
||
- 在线快传和离线快传都允许未登录用户查找
|
||
|
||
### 4.3 加入会话
|
||
|
||
`POST /api/transfer/sessions/{sessionId}/join`
|
||
|
||
说明：
|
||
|
||
- 在线快传会占用一次性会话
|
||
- 离线快传返回可下载文件清单，不需要建立 P2P 通道
|
||
- 在线快传和离线快传都允许未登录用户加入
|
||
|
||
### 4.4 信令交换
|
||
|
||
- `POST /api/transfer/sessions/{sessionId}/signals`
|
||
- `GET /api/transfer/sessions/{sessionId}/signals`
|
||
|
||
说明：
|
||
|
||
- 后端负责 WebRTC 信令交换
|
||
- 文件内容本身不经过后端
|
||
- 实际文件通过浏览器 DataChannel 进行 P2P 传输
|
||
- 该组接口仅用于 `ONLINE` 模式
|
||
|
||
### 4.5 查看我的离线快传记录
|
||
|
||
`GET /api/transfer/sessions/offline/mine`
|
||
|
||
说明：
|
||
|
||
- 需要登录
|
||
- 返回当前用户未过期的离线快传会话列表
|
||
- 每个会话包含取件码、有效期和文件清单，前端可据此重新展示二维码与分享链接
|
||
|
||
### 4.6 上传离线快传文件
|
||
|
||
`POST /api/transfer/sessions/{sessionId}/files/{fileId}/content`
|
||
|
||
说明：
|
||
|
||
- 需要发送端登录
|
||
- 发送端把离线文件内容上传到站点存储
|
||
- 线上环境会把离线文件落到对象存储
|
||
|
||
### 4.6 下载离线快传文件
|
||
|
||
`GET /api/transfer/sessions/{sessionId}/files/{fileId}/download`
|
||
|
||
说明：
|
||
|
||
- 不需要登录
|
||
- 离线文件在有效期内可以被重复下载
|
||
|
||
### 4.7 存入网盘
|
||
|
||
`POST /api/transfer/sessions/{sessionId}/files/{fileId}/import`
|
||
|
||
说明：
|
||
|
||
- 需要登录
|
||
- 把离线快传文件导入到当前用户网盘
|
||
|
||
## 5. 管理台模块
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/admin/AdminController.java`
|
||
|
||
### 5.1 总览
|
||
|
||
`GET /api/admin/summary`
|
||
|
||
返回内容包括：
|
||
|
||
- 用户总数
|
||
- 文件总数
|
||
- 当前邀请码
|
||
- 今日请求次数
|
||
- 今日按小时请求折线图
|
||
- 最近 7 天每日上线人数和用户名单
|
||
- 当前离线快传占用与上限
|
||
|
||
补充说明：
|
||
|
||
- `requestTimeline` 现在只返回当天已经过去的小时，例如当天只到 `07:xx` 时只会返回 `00:00` 到 `07:00`
|
||
- `dailyActiveUsers` 固定返回最近 7 天，按日期升序排列；每项包含日期、展示标签、当天去重后的上线人数和用户名列表
|
||
- “上线”定义为用户成功通过 JWT 鉴权访问受保护接口后的当天首次记录
|
||
|
||
### 5.2 用户管理
|
||
|
||
- `GET /api/admin/users`
|
||
- `PATCH /api/admin/users/{userId}/role`
|
||
- `PATCH /api/admin/users/{userId}/status`
|
||
- `PUT /api/admin/users/{userId}/password`
|
||
- `POST /api/admin/users/{userId}/password/reset`
|
||
|
||
说明：
|
||
|
||
- 可调整用户角色
|
||
- 可封禁用户
|
||
- 可重置或直接设置密码
|
||
- 封禁/改密会使原登录态失效
|
||
|
||
### 5.3 文件管理
|
||
|
||
- `GET /api/admin/files`
|
||
- `DELETE /api/admin/files/{fileId}`
|
||
|
||
### 5.4 存储策略
|
||
|
||
- `GET /api/admin/storage-policies`
|
||
- `POST /api/admin/storage-policies`
|
||
- `PUT /api/admin/storage-policies/{policyId}`
|
||
- `PATCH /api/admin/storage-policies/{policyId}/status`
|
||
- `POST /api/admin/storage-policies/migrations`
|
||
|
||
说明：
|
||
|
||
- 需要管理员登录
|
||
- 返回当前存储策略列表和结构化能力声明
|
||
- 新增/编辑接口当前允许维护名称、类型、bucket/endpoint/region、前缀、凭证模式、最大对象大小、能力声明与启用状态
|
||
- `PATCH /status` 用于启用或停用非默认策略；默认策略不能被停用
|
||
- `POST /migrations` 需要管理员登录，请求体为 `sourcePolicyId`、`targetPolicyId` 与可选 `correlationId`；当前会创建一个 `STORAGE_POLICY_MIGRATION` 后台任务，返回值沿用 `/api/v2/tasks/{id}` 的任务响应形状
|
||
- 当前迁移任务会在“当前活动存储后端”内执行真实对象迁移：复制旧对象到新的 target-policy object key，更新 `FileBlob` 与 `FileEntity.VERSION`，并在事务提交后清理旧对象；如果源/目标策略类型与当前运行时存储后端不匹配，任务会失败
|
||
- 当前仍不支持删除策略、切换默认策略或通过管理接口暴露实际凭证内容
|
||
- `capabilities.multipartUpload` 现在会反映默认策略是否支持 v2 上传会话 multipart；当前默认 S3 策略为 `true`，本地策略为 `false`
|
||
|
||
## 6. 前端公开路由与接口关系
|
||
|
||
前端入口在：
|
||
|
||
- `front/src/App.tsx`
|
||
|
||
主要页面：
|
||
|
||
- `/login`
|
||
- `/overview`
|
||
- `/files`
|
||
- `/transfer`
|
||
- `/share/:token`
|
||
- `/admin/*`
|
||
|
||
接口关系：
|
||
|
||
- 登录页：调用 `/api/auth/login`、`/api/auth/register`
|
||
- 网盘页：调用 `/api/files/**`
|
||
- 快传页：调用 `/api/transfer/**`
|
||
- 分享页：调用 `/api/files/share-links/{token}` 和导入接口
|
||
- 管理台：调用 `/api/admin/**`
|
||
|
||
## 7. 建议阅读顺序
|
||
|
||
后续新窗口如果要接手后端功能，建议按这个顺序看：
|
||
|
||
1. `memory.md`
|
||
2. `docs/architecture.md`
|
||
3. `docs/api-reference.md`
|
||
4. `AGENTS.md`
|
||
5. `CLAUDE.md`
|
||
6. `backend/src/main/java/com/yoyuzh/config/SecurityConfig.java`
|
||
7. 对应业务模块的 `Controller + Service`
|
||
|
||
补充说明：
|
||
|
||
- 根目录 `.env` 现在是本地密钥和部署参数的统一入口
|
||
- 额外的交接背景可查看 `docs/agents/handoff.md`
|
||
## 2026-04-08 API v2 阶段 1 补充
|
||
|
||
`GET /api/v2/site/ping`
|
||
|
||
说明：
|
||
|
||
- 公开接口，不需要登录。
|
||
- 当前是 v2 API 的最小边界探针，返回结构为 `{ "code": 0, "msg": "success", "data": { "status": "ok", "apiVersion": "v2" } }`。
|
||
- v2 错误响应开始使用独立 `ApiV2ErrorCode` 范围；旧 `/api/**` 接口暂不迁移。
|
||
- 前端访问 v2 接口时可通过 `apiV2Request()` 自动拼接 `/api/v2/**`，内部请求会携带 `X-Yoyuzh-Client-Id`。
|
||
|
||
## 2026-04-08 文件实体模型二期第一小步
|
||
|
||
- 本阶段只新增后端实体和迁移映射，不新增对外 API。
|
||
- 旧 `/api/files/**`、分享、回收站、快传接口继续使用现有 DTO 和响应结构。
|
||
- `StoredFile.primaryEntity` 与 `portal_stored_file_entity` 目前只作为兼容迁移数据，后续阶段稳定后再切换新读写路径。
|
||
|
||
## 2026-04-08 文件实体模型二期第二小步
|
||
|
||
- 本阶段不新增对外 API，`/api/files/**`、分享、回收站、快传导入等响应结构保持不变。
|
||
- 后端在旧接口内部开始双写实体模型：上传完成、外部导入、分享导入和网盘复制会继续写 `FileBlob`，同时创建或复用 `FileEntity.VERSION`，并写入 `StoredFile.primaryEntity` 与 `StoredFileEntity(PRIMARY)`。
|
||
- 下载、分享详情、回收站、ZIP 下载仍读取 `StoredFile.blob`；后续阶段稳定后再切换到 `primaryEntity` 读取。
|
||
- 2026-04-08 阶段 3 第一小步 API 补充：新增受保护的 v2 上传会话接口族，`POST /api/v2/files/upload-sessions` 创建会话，`GET /api/v2/files/upload-sessions/{sessionId}` 查询当前用户自己的会话，`DELETE /api/v2/files/upload-sessions/{sessionId}` 取消会话。当前响应会返回 `sessionId`、`objectKey`、`multipartUpload`、路径、文件名、状态、分片大小、分片数量和时间字段。
|
||
- 2026-04-08 阶段 3 第二小步 API 补充：`POST /api/v2/files/upload-sessions/{sessionId}/complete` 用于把当前用户自己的上传会话提交完成。当前默认 S3 策略下，该接口会先完成 multipart 合并，再复用旧上传完成链路落库，成功后返回 `COMPLETED` 状态的 v2 会话响应。
|
||
- 2026-04-08 阶段 3 第三小步 API 补充：`PUT /api/v2/files/upload-sessions/{sessionId}/parts/{partIndex}` 请求体为 `{ "etag": "...", "size": 8388608 }`，用于记录当前用户上传会话的 part 元数据并返回 v2 会话响应；`GET /api/v2/files/upload-sessions/{sessionId}/parts/{partIndex}/prepare` 则返回该分片的直传地址和请求头。字节流仍直接上传到对象存储，不经过后端转发。
|
||
- 2026-04-08 阶段 3 第四小步 API 补充：本小步没有新增额外资源类型。后端新增上传会话过期清理任务，只处理未完成且已过期的会话，并把它们标记为 `EXPIRED`；若会话绑定了 multipart upload，还会在清理时发起 abort。
|
||
- 2026-04-08 阶段 4 第一小步 API 补充：本小步没有新增存储策略管理 API。v2 上传会话响应新增 `storagePolicyId`，用于标识该会话绑定的默认存储策略；该字段现在也用于区分会话是否应按策略能力走 multipart 上传。
|
||
|
||
## 2026-04-08 阶段 5 文件搜索第一小步
|
||
|
||
`GET /api/v2/files/search`
|
||
|
||
说明：
|
||
|
||
- 需要登录，且只返回当前用户自己的未删除文件或目录。
|
||
- 返回 v2 envelope，`data` 结构复用 `PageResponse<FileMetadataResponse>`：`items`、`total`、`page`、`size`。
|
||
- 支持查询参数：`name`、`type`、`sizeGte`、`sizeLte`、`createdGte`、`createdLte`、`updatedGte`、`updatedLte`、`page`、`size`。
|
||
- `type` 支持 `file`、`directory`、`folder`、`all`；时间参数使用 ISO 日期时间格式，例如 `2026-04-08T12:00:00`。
|
||
- 当前搜索只基于 `StoredFile` 固定字段，不启用标签或 metadata 条件过滤；旧 `/api/files/list` 与上传下载分享接口保持不变。
|
||
|
||
## 2026-04-08 阶段 5 文件搜索第二小步
|
||
|
||
- 前端通过 `front/src/lib/file-search.ts` 接入 `GET /api/v2/files/search`，该 helper 会拼接 `name`、`type`、`sizeGte/sizeLte`、`createdGte/createdLte`、`updatedGte/updatedLte`、`page`、`size`，并复用 `apiV2Request()` 的生产端点、认证与 client id 头。
|
||
- `front/src/pages/Files.tsx` 的桌面端文件页新增独立搜索视图，搜索结果不写入 `getFilesListCacheKey(...)`，清空搜索后回到当前目录列表；移动端搜索尚未接入。
|
||
|
||
## 2026-04-08 阶段 5 分享二期后端最小骨架
|
||
|
||
`POST /api/v2/shares`
|
||
|
||
需要登录。
|
||
|
||
- 为当前用户自己的非目录文件创建分享。
|
||
- 请求字段：`fileId`，以及可选的 `password`、`expiresAt`、`maxDownloads`、`allowImport`、`allowDownload`、`shareName`。
|
||
- 密码只保存 hash，不在响应中返回。
|
||
|
||
`GET /api/v2/shares/{token}`
|
||
|
||
公开访问。
|
||
|
||
- 返回分享摘要。
|
||
- 如果分享设置了密码，在校验前不返回 `file` 详情。
|
||
|
||
`POST /api/v2/shares/{token}/verify-password`
|
||
|
||
公开访问。
|
||
|
||
- 校验分享密码，成功后返回可读分享摘要。
|
||
- 响应永不返回 `passwordHash`。
|
||
|
||
`POST /api/v2/shares/{token}/import`
|
||
|
||
需要登录。
|
||
|
||
- 把分享文件导入当前用户网盘。
|
||
- 分享过期、密码错误或未提供、`allowImport=false`、`maxDownloads` 已耗尽时拒绝导入。
|
||
|
||
`GET /api/v2/shares/mine`
|
||
|
||
需要登录。
|
||
|
||
- 分页列出当前用户创建的分享。
|
||
|
||
`DELETE /api/v2/shares/{id}`
|
||
|
||
需要登录。
|
||
|
||
- 只删除当前用户自己的分享。
|
||
|
||
- 旧 `/api/files/share-links/**` 接口保留兼容；当前 `allowDownload` 已落库并返回，但还没有独立 v2 下载路由消费它。
|
||
|
||
## 2026-04-08 阶段 5 文件事件流最小闭环
|
||
|
||
`GET /api/v2/files/events?path=/`
|
||
|
||
说明：
|
||
- 需要登录，返回 `text/event-stream`
|
||
- 请求头支持 `X-Yoyuzh-Client-Id`
|
||
- 首次连接会先推送一个轻量 `READY` 事件
|
||
- 事件写入 `FileEvent` 表，字段包含 `userId`、`eventType`、`fileId`、`fromPath`、`toPath`、`clientId`、`payloadJson`、`createdAt`
|
||
- 当前后端已做同用户广播、路径前缀过滤和同 `clientId` 自身事件抑制
|
||
- 前端通过 `front/src/lib/file-events.ts` 以 fetch stream 订阅该 SSE，复用鉴权与 `X-Yoyuzh-Client-Id` 请求头；桌面 `Files` 与移动 `MobileFiles` 收到变更事件后会失效当前目录缓存并刷新当前目录列表
|
||
|
||
## 2026-04-08 阶段 6 任务框架与 worker 后端最小骨架
|
||
|
||
`GET /api/v2/tasks`
|
||
|
||
需要登录。分页列出当前用户自己的后台任务。
|
||
|
||
`GET /api/v2/tasks/{id}`
|
||
|
||
需要登录。只返回当前用户自己的任务详情。
|
||
|
||
`DELETE /api/v2/tasks/{id}`
|
||
|
||
需要登录。取消当前用户自己的任务，`QUEUED` / `RUNNING` 会转为 `CANCELLED` 并写入 `finishedAt`，终态任务保持原样。
|
||
|
||
`POST /api/v2/tasks/{id}/retry`
|
||
|
||
需要登录。仅允许当前用户重试自己处于 `FAILED` 的后台任务。
|
||
|
||
补充说明：
|
||
|
||
- 成功后任务状态会重置为 `QUEUED`
|
||
- `finishedAt` 与 `errorMessage` 会被清空
|
||
- `publicStateJson.phase` 会重置为 `queued`
|
||
- `publicStateJson.attemptCount` 会重置为 `0`
|
||
- 公开 state 会按服务端保存的 `privateStateJson` 重建，因此失败执行时写入的瞬时字段不会保留
|
||
- 非 `FAILED` 任务调用会返回 `400`
|
||
|
||
`POST /api/v2/tasks/archive`
|
||
|
||
需要登录。创建 `ARCHIVE` 类型的 `QUEUED` 任务；`fileId` 必须属于当前用户且未删除，`path` 必须匹配服务端派生逻辑路径，暂允许文件和目录；当前 worker 会生成 zip 并把归档结果回写到原文件同级目录。
|
||
|
||
`POST /api/v2/tasks/extract`
|
||
|
||
需要登录。创建 `EXTRACT` 类型的 `QUEUED` 任务；`fileId` 必须属于当前用户且未删除，`path` 必须匹配服务端派生逻辑路径，并拒绝目录和非压缩包类文件；当前 worker 只支持 zip-compatible 归档，会剥离共享根目录，并把解压结果恢复到原文件父目录。
|
||
|
||
`POST /api/v2/tasks/media-metadata`
|
||
|
||
需要登录。创建 `MEDIA_META` 类型的 `QUEUED` 任务；`fileId` 必须属于当前用户且未删除，`path` 必须匹配服务端派生逻辑路径，并拒绝目录和非媒体类文件；worker 会重新按 `userId + fileId` 加载文件，写入 `media:contentType`、`media:size`，对 ImageIO 可识别图片额外写 `media:width` 和 `media:height`。当前仍不做缩略图、视频时长或前端任务面板。
|
||
|
||
补充说明：
|
||
|
||
- worker 会定时领取少量 `QUEUED` 任务并切换为 `RUNNING`，完成后标记 `COMPLETED`，异常时标记 `FAILED` 并写入 `errorMessage`。
|
||
- `publicStateJson.phase` 当前会经历 `queued -> running -> archiving/extracting/extracting-metadata -> completed/failed/cancelled` 这样的最小阶段流转。
|
||
- `publicStateJson` 还会暴露 `attemptCount/maxAttempts`；当前默认预算为 `ARCHIVE=4`、`EXTRACT=3`、`MEDIA_META=2`。
|
||
- 任务进入 `RUNNING` 后，`publicStateJson` 会额外暴露 `workerOwner/heartbeatAt/leaseExpiresAt/startedAt`，用于描述当前 worker 的 lease 和 heartbeat；终态或重排回队列后会移除运行态 owner/lease 字段。
|
||
- `ARCHIVE/EXTRACT` 任务还会在 `publicStateJson` 里暴露 `processedFileCount/totalFileCount`、`processedDirectoryCount/totalDirectoryCount` 与真实 `progressPercent`；`MEDIA_META` 会额外暴露 `metadataStage`。
|
||
- 当 worker 命中失败时，任务会按失败分类写入 `failureCategory`。`TRANSIENT_INFRASTRUCTURE`、`RATE_LIMITED` 与部分 `UNKNOWN` 失败会按任务类型退避自动重排回 `QUEUED`，并在 `publicStateJson` 写入 `retryScheduled=true`、`nextRetryAt`、`retryDelaySeconds`、`lastFailureMessage`、`lastFailureAt`；`UNSUPPORTED_INPUT` 与 `DATA_STATE` 这类确定性失败不会自动重试。
|
||
- 已取消或其他终态任务不会被重新执行。
|
||
- 服务重启后，只有 lease 已过期或历史上没有 lease 的 `RUNNING` 任务会在启动完成时被重置回 `QUEUED`，避免多实例下误抢仍在运行的 worker。
|
||
- 创建成功后的任务 state 使用服务端文件信息，至少包含 `fileId`、`path`、`filename`、`directory`、`contentType`、`size`。
|
||
- 桌面端 `Files` 页面会拉取最近 10 条任务、提供 `QUEUED/RUNNING` 取消按钮，并可为当前选中文件创建 `MEDIA_META` 任务；移动端与 archive/extract 的前端入口暂未接入。
|
||
|
||
## 2026-04-10 Redis Login-State Invalidation
|
||
|
||
- 新增可选 Redis 基础设施配置：
|
||
- `spring.data.redis.*`：连接参数。
|
||
- `app.redis.*`：业务 key prefix、TTL buffer、cache TTL 与命名空间。
|
||
- 当 `app.redis.enabled=true` 时，认证链路会启用 Redis 驱动的登录态失效层：
|
||
- access token 按 `userId + clientType` 记录“在此时间点之前签发的 token 失效”。
|
||
- refresh token 按 hash 写入黑名单，TTL 与剩余有效期对齐。
|
||
- `POST /api/auth/login`、`POST /api/auth/register`、`POST /api/auth/dev-login`：如果是同客户端重新签发登录态，旧 access token 会被写入 Redis 失效层，并继续保留原有 `sid` 会话匹配语义。
|
||
- `POST /api/user/password`、管理员封禁/改密/重置密码相关路径：会同时触发 access token Redis 失效标记与数据库 refresh token 撤销。
|
||
- `POST /api/auth/refresh`：旧 refresh token 在数据库撤销之外，还会同步写入 Redis 黑名单；先命中黑名单的 token 会被直接拒绝。
|
||
- 当 Redis 关闭时，系统会自动回退到原有的数据库 refresh token + `sid` 会话校验语义，不影响本地与 dev 启动。
|
||
## 2026-04-10 Redis Files Cache And Upload Runtime
|
||
|
||
- `GET /api/files/list`
|
||
- 对外语义不变，仍使用 `path`、`page`、`size` 参数返回当前用户目录分页结果。
|
||
- 当 `app.redis.enabled=true` 时，后端会把热点目录页写入 Redis `files:list` cache，并通过目录版本号在创建、删除、移动、复制、重命名、恢复、上传完成和导入后做精准失效。
|
||
- 搜索结果、回收站列表和后台任务列表不复用这套 key，避免不同语义的分页结果互相污染。
|
||
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}`
|
||
- 响应体新增 `runtime` 字段；当 Redis 运行态存在时返回实时上传快照，不存在时返回 `null`，不影响原有会话元数据字段。
|
||
- `runtime` 当前包含 `phase`、`uploadedBytes`、`uploadedPartCount`、`progressPercent`、`lastUpdatedAt`、`expiresAt`。
|
||
- 该运行态由后端在会话创建、分片记录、代理上传、完成、取消、失败和过期时刷新，属于短生命周期缓存，不替代数据库里的最终状态。
|
||
|
||
- `POST /api/files/recycle-bin/{fileId}/restore`
|
||
- 外部接口不变，但 Redis 启用时后端会为同一 `fileId` 的恢复流程加分布式锁，避免多实例或并发请求重复恢复同一批条目。
|
||
|
||
## 2026-04-10 Redis Lightweight Broker First Landing
|
||
|
||
- 本批次没有新增对外 HTTP API；用户可见接口仍沿用现有 `/api/files/**` 与 `/api/v2/tasks/**`。
|
||
- 媒体文件通过网盘主链路落库后，后端现在会在事务提交后向轻量 broker 发布一次 `media-metadata-trigger`。这条触发只用于异步创建后台任务，不直接暴露为额外接口。
|
||
- broker 当前只承载“自动补一条 `MEDIA_META` 任务”这一类轻量异步触发，最终执行状态、重试与公开结果仍以 `BackgroundTask` 记录和 `/api/v2/tasks/**` 查询结果为准。
|
||
- `POST /api/v2/tasks/media-metadata`
|
||
- 用户手动创建任务的接口语义不变。
|
||
- 与此同时，媒体文件成功落库后也可能由后端自动补一条同类任务；系统会按 `correlationId` 去重，避免同一文件被 broker 重复创建多条自动任务。
|
||
|
||
## 2026-04-10 Redis Transfer Session Store
|
||
|
||
- 本批次没有新增快传 HTTP API，`/api/transfer/sessions`、`/api/transfer/sessions/lookup`、`/api/transfer/sessions/{sessionId}/join` 与信令轮询接口的对外协议保持不变。
|
||
- 当 `app.redis.enabled=true` 时，在线快传 session 会写入 Redis `transfer-sessions` 命名空间，而不再只保存在当前 JVM 进程内；这让 `lookup/join/postSignal/pollSignals` 在多实例部署下具备共享同一在线会话状态的基础。
|
||
- session 数据在 Redis 中会同时保存：
|
||
- `session:{sessionId}`：完整在线快传运行态快照。
|
||
- `pickup:{pickupCode}`：`pickupCode -> sessionId` 映射。
|
||
- Redis 关闭时，系统会自动回退到原有进程内存 store，本地和 dev 环境不需要额外 Redis 也能继续运行。
|
||
- 离线快传不走这套 Redis store，仍继续使用数据库 `OfflineTransferSession` 持久化模型。
|
||
## 2026-04-10 Redis File Event Pub/Sub
|
||
|
||
- `GET /api/v2/files/events?path=/`
|
||
- 对外 SSE 协议不变，仍要求登录并支持 `X-Yoyuzh-Client-Id`。
|
||
- 首次连接仍先收到 `READY` 事件，订阅路径过滤和同 `clientId` 自抑制语义保持不变。
|
||
- 当 `app.redis.enabled=true` 时，某个实例在事务提交后写入的文件事件会额外通过 Redis pub/sub 广播到其他实例，因此同一用户连到不同后端实例时也能收到变更通知。
|
||
- Redis pub/sub 只传播最小事件快照，不传播 `SseEmitter`、不重写 `FileEvent` 表，也不改变 `FileEvent` 作为审计持久化记录的角色。
|
||
- Redis 关闭时会自动回退为原有单实例本地广播行为。
|
||
## 2026-04-10 Spring Cache Minimal Landing
|
||
|
||
- `GET /api/admin/storage-policies`
|
||
- 瀵瑰鍗忚涓嶅彉銆?
|
||
- 褰?`app.redis.enabled=true` 鏃讹紝鍚庣浼氬皢鏁翠釜瀛樺偍绛栫暐鍒楄〃缂撳瓨鍒?`admin:storage-policies`銆?
|
||
- 褰?POST/PUT/PATCH` 瀛樺偍绛栫暐绠＄悊鎺ュ彛鍐欏叆鎴愬姛鍚庯紝缂撳瓨浼氱珛鍗宠澶辨晥锛屽悗缁璇锋眰浼氶噸寤烘柊鍒楄〃銆?
|
||
|
||
- `GET /api/app/android/latest`
|
||
- 瀵瑰鍗忚涓嶅彉锛屼粛鏄叕寮€鎺ュ彛銆?
|
||
- 褰?`app.redis.enabled=true` 鏃讹紝鍚庣浼氬皢浠?`android/releases/latest.json` 鏋勫缓鍑虹殑 release metadata 鍝嶅簲缂撳瓨鍒?`android:release`銆?
|
||
- 杩欎釜缂撳瓨褰撳墠渚濊禆 TTL 鍒锋柊锛屽洜涓?latest metadata 鐨勬洿鏂版潵鑷?Android 鍙戝竷鑴氭湰鍐欏叆瀵硅薄瀛樺偍锛岃€屼笉鏄悗绔唴閮ㄦ煇涓鐞嗗啓鎺ュ彛銆?
|
||
|
||
- `GET /api/admin/summary`
|
||
- 褰撳墠鏆備笉鎺ュ叆 Spring Cache銆?
|
||
- 鍘熷洜鏄繖涓?summary 鍚屾椂鍚湁 request count銆乧aily active users銆乭ourly timeline 绛夐珮棰戠粺璁″€硷紝鐢ㄦ樉寮忓け鏁堝緢闅惧湪褰撳墠鏋舵瀯涓嬩繚鎸佸共鍑€璇箟銆?
|
||
## 2026-04-10 Spring Cache Minimal Landing Clarification
|
||
|
||
- `GET /api/admin/storage-policies`
|
||
- Response shape is unchanged.
|
||
- When `app.redis.enabled=true`, the backend caches the full storage policy list in `admin:storage-policies`.
|
||
- Successful storage policy create, update, and status-change writes evict that cache immediately.
|
||
|
||
- `GET /api/app/android/latest`
|
||
- Response shape is unchanged.
|
||
- When `app.redis.enabled=true`, the backend caches the metadata response derived from `android/releases/latest.json` in `android:release`.
|
||
- Refresh is TTL-based because the metadata is updated by the Android release publish script rather than an in-app admin write endpoint.
|
||
|
||
- `GET /api/admin/summary`
|
||
- This endpoint is intentionally not cached at the moment.
|
||
- The response mixes high-churn metrics such as request count, daily active users, and hourly request timeline data, so there is not yet a clean explicit invalidation boundary.
|
||
## 2026-04-10 DogeCloud Temporary S3 Session Clarification
|
||
|
||
- No HTTP API contract changed in this batch.
|
||
- The decision for Step 11 is architectural: DogeCloud temporary S3 sessions remain cached per backend instance inside `DogeCloudS3SessionProvider`.
|
||
- This does not change upload, download, direct-upload, or multipart endpoint shapes; it only clarifies that cross-instance Redis reuse is intentionally not introduced for these temporary runtime sessions.
|
||
## 2026-04-10 Stage 1 Validation Clarification
|
||
|
||
- No API response shape changed in Step 12.
|
||
- Validation confirmed that all new Redis-backed integrations added in Stage 1 still preserve the existing no-Redis API startup path when `app.redis.enabled=false`.
|
||
- Local boot also confirmed that the backend now has one explicit non-Redis prerequisite for runtime startup in both default and `dev` profiles: `app.jwt.secret` must be configured via `APP_JWT_SECRET` and cannot be left empty.
|
||
- Cross-instance behavior described by earlier Stage 1 notes remains architecturally valid, but it still needs real-environment verification with Redis plus multiple backend instances before being treated as deployment-proven.
|
||
|
||
## 2026-04-10 Manual Redis Validation Addendum
|
||
|
||
- No HTTP endpoint shape changed in this addendum either.
|
||
- The local two-instance Redis validation did confirm these existing API behaviors in a real runtime flow:
|
||
- `POST /api/auth/dev-login` on one instance invalidates the prior access token and refresh token even when the next authenticated read happens on the peer instance.
|
||
- `POST /api/transfer/sessions` plus `GET /api/transfer/sessions/lookup` continue to work across instances for online sessions, including after the creating instance is stopped.
|
||
- `GET /api/v2/files/events` on instance B receives a `CREATED` event after an authenticated media upload to instance A.
|
||
- `GET /api/v2/tasks` on instance B exposes the queued `MEDIA_META` task auto-created by that upload.
|
||
- Three backend fixes were internal and did not change API contracts:
|
||
- Redis cache serialization/deserialization for file list pages;
|
||
- Redis auth revocation cutoff precision;
|
||
- non-null `storage_name` persistence for directory creation and normal file upload metadata.
|
||
|
||
## 2026-04-11 Admin Backend Surface Addendum
|
||
|
||
- `GET /api/admin/file-blobs`
|
||
- Auth: admin only.
|
||
- Query params: `page`, `size`, `userQuery`, `storagePolicyId`, `objectKey`, `entityType`.
|
||
- Response items expose `FileEntity`-centric blob inspection fields including `objectKey`, `entityType`, `storagePolicyId`, `referenceCount`, `linkedStoredFileCount`, `linkedOwnerCount`, `sampleOwnerUsername`, `sampleOwnerEmail`, `createdByUserId`, `createdByUsername`, `blobMissing`, `orphanRisk`, and `referenceMismatch`.
|
||
- This endpoint is for admin diagnostics and migration visibility; it does not replace end-user file reads.
|
||
|
||
- `GET /api/admin/shares`
|
||
- Auth: admin only.
|
||
- Query params: `page`, `size`, `userQuery`, `fileName`, `token`, `passwordProtected`, `expired`.
|
||
- Response items expose share metadata from `FileShareLink`, plus owner and file summary fields.
|
||
|
||
- `DELETE /api/admin/shares/{shareId}`
|
||
- Auth: admin only.
|
||
- Deletes the target `FileShareLink` immediately.
|
||
- Intended for operational cleanup and moderation.
|
||
|
||
- `GET /api/admin/tasks`
|
||
- Auth: admin only.
|
||
- Query params: `page`, `size`, `userQuery`, `type`, `status`, `failureCategory`, `leaseState`.
|
||
- Response items expose task owner identity plus parsed task-state helpers: `failureCategory`, `retryScheduled`, `workerOwner`, and derived `leaseState`.
|
||
|
||
- `GET /api/admin/tasks/{taskId}`
|
||
- Auth: admin only.
|
||
- Returns the same admin task response shape as the list endpoint for a single task.
|