yoyuz/my_site
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
56f2a9fe0d1be8d38fb15759d40ee4d124ba8e75
my_site/docs/api-reference.md

8.3 KiB
Raw Blame History

API 接口文档

本文档用于快速了解 yoyuzh.xyz 当前后端 API 的职责、鉴权方式和主要接口分组。

1. 基本约定

基础路径

  • 后端接口统一以 /api 开头
  • 本地开发默认地址：http://localhost:8080

返回格式

大部分接口返回统一结构：

{
  "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/**
    • /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

说明：

  • 使用邀请码注册
  • 注册成功后直接返回登录态
  • 邀请码成功使用后会自动刷新

请求重点字段：

  • username
  • email
  • phoneNumber
  • password
  • confirmPassword
  • inviteCode

2.2 登录

POST /api/auth/login

请求字段：

  • username
  • password

返回字段：

  • token
  • accessToken
  • refreshToken
  • user

2.3 刷新登录态

POST /api/auth/refresh

请求字段：

  • refreshToken

说明：

  • 刷新后会返回新的 access token 与 refresh token
  • 当前系统会让旧 refresh token 失效

2.4 开发环境登录

POST /api/auth/dev-login

说明：

  • 仅用于开发联调
  • 是否可用取决于当前环境配置

2.5 获取用户资料

GET /api/user/profile

2.6 更新用户资料

PUT /api/user/profile

2.7 修改密码

POST /api/user/password

说明：

  • 成功后会重新签发新的登录态
  • 同时会顶掉旧设备会话

2.8 头像相关

  • 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/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 下载

3.4 文件操作

  • PATCH /api/files/{fileId}/rename
  • PATCH /api/files/{fileId}/move
  • POST /api/files/{fileId}/copy
  • DELETE /api/files/{fileId}

说明：

  • move 用于移动到目标路径
  • copy 用于复制到目标路径
  • 文件和文件夹都支持移动 / 复制
  • 普通文件的 move / rename / copy 只改逻辑元数据；copy 会复用原有 FileBlob，不会复制底层对象

3.5 分享链接

  • POST /api/files/{fileId}/share-links
  • GET /api/files/share-links/{token}
  • POST /api/files/share-links/{token}/import

说明：

  • 已登录用户可为自己的文件或文件夹创建分享链接
  • 公开访客可查看分享详情
  • 登录用户可将分享内容导入自己的网盘
  • 普通文件导入时会新建自己的 StoredFile 并复用源 FileBlob，不会再次写入物理文件

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}

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. backend/src/main/java/com/yoyuzh/config/SecurityConfig.java
  5. 对应业务模块的 Controller + Service
Reference in New Issue View Git Blame Copy Permalink