前端设计已完成

前端开发已完成

后端开发需求文档

————————————————
10 大模块、42 个子项

1. 项目总体约束

1.1 技术栈：Node ≥ 18 + NestJS + TypeORM + MySQL 8.0 | PostgreSQL 14（二选一，需支持切换）。
1.2 接口风格：RESTful + JSON，统一前缀 /api/v1。
1.3 统一返回体
{ code: number, message: string, data: any, traceId: string }
1.4 错误码规范：0=成功；1xxx=通用错误；2xxx=鉴权；3xxx=文件；4xxx=数据库。
1.5 部署：Docker + docker-compose 一键启动；提供官方镜像 ghcr.io/xxx/imgbed:latest。

2. 数据库与初始化 ✅

2.1 物理库：库名可自定义，默认 imgbed。
2.2 字符集：utf8mb4 / UTF-8。
2.3 表清单
users       用户表
settings      系统配置表（key-value）
files        文件元数据表
folders       虚拟文件夹表（支持多级）
file_folder     多对多关系
share_tokens    分享令牌表（可选，预留）
2.4 初始化流程
Step1 程序启动时检测 settings 中 install_status=done 与否。
Step2 若未安装，自动创建 install_lock 文件防止并发，弹出「安装向导」接口：
POST /api/v1/install
Body: {dbHost, dbPort, dbName, dbUser, dbPwd, adminName, adminPwd, storagePath}
响应：{code:0, data:{adminToken}}
Step3 成功后写入 settings：install_status=done，并创建 admin 用户（role=admin）。
2.5 升级脚本：版本号记录在 settings.schema_version，TypeORM migration 自动执行。

3. 配置中心 ✅

3.1 支持运行时修改且立即生效的配置项（管理后台页面已留好）：
• siteName     站点名称
• storagePath    资源物理存放根目录（可配绝对路径，容器内挂卷）
• allowFileTypes   允许上传的扩展名数组
• maxFileSize    单文件最大体积（Byte）
• maxStoragePerUser 单用户最大容量（Byte，0=不限）
• jwtSecret / jwtExpires 登录密钥与过期时间（默认 30 天）
3.2 提供接口
GET /api/v1/admin/settings  获取
POST /api/v1/admin/settings  修改（需 admin 角色）

4. 用户 & 鉴权 ✅

4.1 字段
userId(pk)、nickname、loginName(unique)、passwordHash、email(unique)、role(admin|user)、status(active|disabled)、createdAt、updatedAt、lastLoginAt。
4.2 密码策略：bcrypt 10 轮；登录失败 5 次锁定 15 分钟。
4.3 JWT 结构
payload: {userId, role, iat, exp}
刷新机制：自动续期 7 天（滑动窗口）。
4.4 接口
POST /api/v1/auth/login  登录
POST /api/v1/auth/logout  登出（把 jti 加入 Redis 黑名单）
GET /api/v1/auth/profile 获取个人信息
PUT /api/v1/auth/profile 修改昵称/邮箱/密码

5. 文件存储 ✅

5.1 物理目录规则
{storagePath}/{userId}/{year}/{month}/{uuid}.{ext}
例：/data/imgbed/1001/2025/11/a3d8f9.jpg
5.2 文件名冲突：使用 uuidv4 重命名，原文件名存入 files.originalName。
5.3 支持本地磁盘 / S3 协议（MinIO、AWS S3、阿里云 OSS）一键切换，配置项：
storage.driver = local|s3
s3.* 相关密钥由管理后台填写，自动加密存储。
5.4 上传流程

1. 校验登录 → 2. 校验单文件大小 → 3. 校验用户剩余容量 → 4. 写入物理存储 → 5. 落库 files 表 → 6. 返回 JSON

{fileId, url, size, mime, md5}
5.5 大文件分片（可选 Phase2）：
POST /api/v1/file/chunk 预创建
PUT /api/v1/file/chunk/{id} 上传分片
POST /api/v1/file/merge 合并

6. 资源管理 ✅

6.1 多级虚拟文件夹
• 支持无限级目录；数据库 folders 表存储 materialized path 或 closure table。
• 同一文件可归属到多个文件夹（ManyToMany）。
6.2 文件/文件夹重命名
PUT /api/v1/file/{fileId}/rename
PUT /api/v1/folder/{folderId}/rename
物理文件名不变，仅修改 files.logicalName；若修改扩展名给出警告。
6.3 移动 & 批量移动
POST /api/v1/file/move
Body: {fileIds[], targetFolderId}
6.4 复制（仅数据库记录复制，物理文件硬链接）
POST /api/v1/file/copy
6.5 递归统计
GET /api/v1/folder/{id}/stats 返回总文件数/总大小

7. 删除与回收站 ✅

7.1 两种策略可配置：
A. 直接物理删除（默认）
B. 软删除 + 回收站（保留 30 天）
7.2 软删除实现
files.status=trashed；定时任务每天 04:00 扫描超过 30 天的 trashed 文件真正删除。
7.3 接口
DELETE /api/v1/file/{id}  → 移入回收站或物理删除
DELETE /api/v1/file/force → 立即物理删除（admin）
GET  /api/v1/trash   → 回收站列表
POST /api/v1/trash/restore

8. 浏览与预览 ✅

8.1 图片缩略图
• 本地驱动：使用 sharp 生成 300×300 webp，缓存到 {storagePath}/.thumb/
• S3 驱动：接入 Lambda@Edge 或 阿里云 OSS 图片处理参数 ?x-oss-process=style/thumb
8.2 文档、视频在线预览
• 文档：接入 OnlyOffice / Microsoft Viewer，返回预览 URL。
• 视频：返回 HLS 索引 .m3u8（转码任务异步，见第 10 章）。
8.3 私有文件签名
GET /api/v1/file/{id}/url?expire=3600 返回带签名的临时 URL（local 驱动走 nginx secure_link；s3 驱动走预签名）。

9. 分享功能（预留） ✅

9.1 用户可创建分享令牌
POST /api/v1/share Body: {fileIds[], password, expireDays}
返回：{token, url}
9.2 匿名访问
GET /s/{token} 输入密码后查看/打包下载。

10. 任务与日志 ✅

10.1 异步队列
使用 BullMQ + Redis，用于缩略图、视频转码、清理回收站。
10.2 管理员日志
admin_logs 表记录「谁、在什么时间、做了什么、IP、UA」。
10.3 用户操作日志（可选）
user_logs 表记录上传/删除/下载。
10.4 监控接口
GET /api/v1/admin/metrics 返回
{userCount, fileCount, totalSize, trashSize, queueWaiting}