外观
相册系统设计文档
概述
相册系统是一个云端智能照片视频管理与分享平台，支持多端备份（目前支持七牛云）。系统提供相册和影集两种管理方式，分别用于管理照片和视频，通过智能标签和强大的搜索功能，帮助用户轻松管理和查找照片视频。
数据库设计
表结构
1. 相册表（album）
用于存储相册基本信息。
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | int | 主键，自增 |
| user_id | int | 用户ID，关联user表 |
| title | varchar(200) | 相册标题 |
| slug | varchar(200) | URL标识，用于显示到链接上 |
| description | text | 相册描述 |
| file_count | int | 文件数量 |
| sort_order | int | 排序顺序，数字越小越靠前 |
| status | enum | 状态：正常/已删除（软删除标识） |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
索引：
- 唯一索引：
(user_id, slug)
2. 影集表（video_collection）
用于存储影集基本信息。
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | int | 主键，自增 |
| user_id | int | 用户ID，关联user表 |
| title | varchar(200) | 影集标题 |
| slug | varchar(200) | URL标识，用于显示到链接上 |
| description | text | 影集描述 |
| file_count | int | 文件数量 |
| sort_order | int | 排序顺序，数字越小越靠前 |
| status | enum | 状态：正常/已删除（软删除标识） |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
索引：
- 唯一索引：
(user_id, slug)
3. 相册文件表（album_file）
用于存储相册中的文件信息。
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | int | 主键，自增 |
| album_id | int | 相册ID，关联album表 |
| file_id | int | 文件ID，关联file表 |
| file_name | varchar(500) | 文件名 |
| description | text | 文件描述 |
| file_date | date | 文件日期，格式YYYY-MM-DD |
| location | varchar(200) | 地点 |
| people | varchar(500) | 人物 |
| tags | varchar(500) | 标签，多个标签用逗号分隔 |
| file_size | bigint | 文件大小，单位：字节 |
| sort_order | int | 排序顺序，数字越小越靠前 |
| status | enum | 状态：正常/已删除（软删除标识） |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
索引：
- 唯一索引：
(album_id, file_id)
4. 影集文件表（video_collection_file）
用于存储影集中的文件信息。
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | int | 主键，自增 |
| video_collection_id | int | 影集ID，关联video_collection表 |
| file_id | int | 文件ID，关联file表 |
| file_name | varchar(500) | 文件名 |
| description | text | 文件描述 |
| file_date | date | 文件日期，格式YYYY-MM-DD |
| location | varchar(200) | 地点 |
| people | varchar(500) | 人物 |
| tags | varchar(500) | 标签，多个标签用逗号分隔 |
| file_size | bigint | 文件大小，单位：字节 |
| duration | int | 视频时长，单位：秒 |
| sort_order | int | 排序顺序，数字越小越靠前 |
| status | enum | 状态：正常/已删除（软删除标识） |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
索引：
- 唯一索引：
(video_collection_id, file_id)
核心功能
1. 相册管理
1.1 创建相册
- 接口：
POST /api/album/album - 功能：创建新的相册
- 参数：
title：相册标题（必填，最大200字符）slug：相册标识（必填，最大200字符，用于URL）description：相册描述（可选）sortOrder：排序顺序（可选，默认0）
- 约束：
- 同一用户下，slug必须唯一
- 如果slug已存在，返回错误
1.2 更新相册
- 接口：
PUT /api/album/album - 功能：更新相册信息
- 参数：同创建相册，增加
id字段 - 约束：
- 只能更新自己创建的相册
- slug不能与其他相册重复
1.3 删除相册
- 接口：
DELETE /api/album/album - 功能：删除相册（软删除）
- 参数：
id（相册ID） - 约束：
- 只能删除自己创建的相册
- 如果相册中有文件（file_count > 0），不允许删除
1.4 查询相册列表
- 接口：
GET /api/album/album/list - 功能：分页查询相册列表
- 参数：
pageNo：页码（必填）pageSize：每页数量（必填）keyword：关键词（可选，搜索标题、标识或描述）
- 返回：分页数据，包含相册列表和总数
1.5 获取相册详情
- 接口：
GET /api/album/album/detail - 功能：获取相册详细信息
- 参数：
id（相册ID） - 返回：相册详细信息
2. 影集管理
影集管理的功能与相册管理类似，包括创建、更新、删除、查询列表和获取详情。
- 创建影集：
POST /api/album/video-collection - 更新影集：
PUT /api/album/video-collection - 删除影集：
DELETE /api/album/video-collection - 查询影集列表：
GET /api/album/video-collection/list - 获取影集详情：
GET /api/album/video-collection/detail
3. 相册文件管理
3.1 添加相册文件
- 接口：
POST /api/album/album/file - 功能：向相册中添加文件
- 参数：
albumId：相册ID（必填）fileId：文件ID（必填）fileName：文件名（可选）description：文件描述（可选）fileDate：文件日期（可选，格式YYYY-MM-DD）location：地点（可选）people：人物（可选）tags：标签（可选）fileSize：文件大小（可选）sortOrder：排序顺序（可选）
- 约束：
- 同一个文件不能重复添加到同一个相册
- 添加成功后，相册的file_count会自动更新
3.2 批量添加相册文件
- 接口：
POST /api/album/album/file/batch - 功能：批量向相册中添加文件
- 参数：
albumId：相册ID（必填）files：文件数组，每个文件包含上述单个文件的参数
- 返回：成功和失败的数量
3.3 更新相册文件
- 接口：
PUT /api/album/album/file - 功能：更新相册文件信息
- 参数：
id（相册文件ID）和其他可更新字段
3.4 删除相册文件
- 接口：
DELETE /api/album/album/file - 功能：从相册中删除文件（软删除）
- 参数：
id（相册文件ID）、albumId（相册ID） - 约束：删除成功后，相册的file_count会自动更新
3.5 查询相册文件列表
- 接口：
GET /api/album/album/file/list - 功能：分页查询相册中的文件列表
- 参数：
albumId：相册ID（必填）pageNo：页码（必填）pageSize：每页数量（必填）keyword：关键词（可选，搜索文件名、描述、地点、人物、标签）
- 返回：分页数据，包含文件列表和总数，每个文件包含fileUrl字段
4. 影集文件管理
影集文件管理的功能与相册文件管理类似，但增加了视频时长字段。
- 添加影集文件：
POST /api/album/video-collection/file - 批量添加影集文件：
POST /api/album/video-collection/file/batch - 更新影集文件：
PUT /api/album/video-collection/file - 删除影集文件：
DELETE /api/album/video-collection/file - 查询影集文件列表：
GET /api/album/video-collection/file/list
5. 批量上传功能
5.1 上传流程
- 用户选择多个文件（照片或视频）
- 系统自动开始上传到七牛云
- 实时显示每个文件的上传进度
- 如果某个文件上传失败，显示重试按钮
- 上传成功后，点击确定按钮
- 系统为每个成功上传的文件创建文件记录
- 批量将文件添加到相册/影集
5.2 上传特性
- 批量选择：支持一次选择多个文件
- 进度显示：实时显示每个文件的上传进度百分比
- 失败重试：上传失败的文件可以单独重试
- 分片上传：大于4MB的文件自动使用分片上传
- 确认添加：只有上传成功的文件才会被添加到相册/影集
前端功能
1. 相册列表页面
- 显示所有相册的列表
- 支持关键词搜索
- 支持分页浏览
- 支持创建、编辑、删除相册
- 支持查看相册详情
2. 相册详情页面
- 显示相册基本信息
- 显示相册中的文件列表（图片预览）
- 支持批量上传照片
- 支持搜索文件
- 支持编辑、删除文件
- 支持分页浏览
3. 影集列表页面
- 显示所有影集的列表
- 支持关键词搜索
- 支持分页浏览
- 支持创建、编辑、删除影集
- 支持查看影集详情
4. 影集详情页面
- 显示影集基本信息
- 显示影集中的文件列表（视频预览）
- 支持批量上传视频
- 支持搜索文件
- 支持编辑、删除文件
- 支持分页浏览
- 显示视频时长
5. 批量上传组件
- 支持拖拽上传
- 支持点击选择文件
- 实时显示上传进度
- 支持失败重试
- 显示上传状态（等待、上传中、成功、失败）
- 确认按钮只对上传成功的文件生效
技术实现
后端技术栈
- Express.js：Web框架
- TypeScript：类型安全
- Knex.js：数据库操作
- Zod：参数验证
- 七牛云SDK：文件存储
前端技术栈
- Vue 3：前端框架
- TypeScript：类型安全
- Element Plus：UI组件库
- Pinia：状态管理
- Vue Router：路由管理
- qiniu-js：七牛云上传SDK
文件存储
- 所有文件存储在七牛云
- 图片文件路径：
upload-images/... - 视频文件路径：
upload-videos/... - 支持CDN加速访问
业务规则
- 删除约束：文件数大于0的相册/影集不允许删除
- 唯一性约束：同一用户下，相册/影集的slug必须唯一
- 文件关联：同一个文件不能重复添加到同一个相册/影集
- 软删除：所有删除操作都是软删除，通过status字段标识
- 文件计数：相册/影集的file_count字段会自动维护
安全考虑
- 权限控制：用户只能操作自己创建的相册/影集
- 参数验证：所有接口参数都通过Zod进行验证
- 文件类型限制：相册只能上传图片，影集只能上传视频
- 文件大小限制：大文件自动使用分片上传
性能优化
- 分页查询：所有列表查询都支持分页
- 并行查询：分页查询时，列表查询和计数查询并行执行
- 索引优化：关键字段都建立了索引
- 分片上传：大文件使用分片上传，提升上传成功率