87 lines
5.6 KiB
Markdown
87 lines
5.6 KiB
Markdown
|
# Requirements Document
|
|||
|
|
|
|||
|
|
## Introduction
|
|||
|
|
|
|||
|
|
文件转存服务是一个允许用户通过API Key认证上传文件到腾讯云COS的功能。该服务支持图片文件上传，文件保留15天后自动删除，每次上传固定扣除30积分。服务使用独立的COS存储桶（上海地域），并提供文件记录管理和查询功能。
|
|||
|
|
|
|||
|
|
## Glossary
|
|||
|
|
|
|||
|
|
- **File_Transfer_Service**: 文件转存服务，负责处理文件上传、存储、查询和自动清理的核心服务
|
|||
|
|
- **Transfer_File**: 转存文件实体，记录上传文件的元数据信息
|
|||
|
|
- **COS_Client**: 腾讯云对象存储客户端，用于与COS存储桶交互
|
|||
|
|
- **API_Key_Auth**: API密钥认证机制，用于验证用户身份
|
|||
|
|
- **Points_Service**: 积分服务，用于扣除用户积分
|
|||
|
|
- **File_Cleanup_Scheduler**: 文件清理调度器，负责定时删除过期文件
|
|||
|
|
|
|||
|
|
## Requirements
|
|||
|
|
|
|||
|
|
### Requirement 1: 文件上传
|
|||
|
|
|
|||
|
|
**User Story:** As a user, I want to upload image files to COS through API Key authentication, so that I can store files temporarily for external access.
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a user provides a valid API Key and uploads an image file, THE File_Transfer_Service SHALL authenticate the user and accept the file
|
|||
|
|
2. WHEN a user uploads a file, THE File_Transfer_Service SHALL validate that the file type is an image (jpg, jpeg, png, gif, webp, bmp)
|
|||
|
|
3. WHEN a user uploads an image file exceeding 20MB, THE File_Transfer_Service SHALL reject the upload and return an error message
|
|||
|
|
4. WHEN a valid image file is uploaded, THE File_Transfer_Service SHALL store the file in COS bucket "apidatafile-1302947942" in region "ap-shanghai"
|
|||
|
|
5. WHEN a file is successfully uploaded, THE File_Transfer_Service SHALL generate a unique file key with format "transfer/{userId}/{timestamp}_{uuid}.{extension}"
|
|||
|
|
6. WHEN a file is successfully uploaded, THE File_Transfer_Service SHALL return the file access URL to the user
|
|||
|
|
|
|||
|
|
### Requirement 2: 积分扣除
|
|||
|
|
|
|||
|
|
**User Story:** As a system administrator, I want to charge users 30 points per file upload, so that the service usage is properly metered.
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a user initiates a file upload, THE Points_Service SHALL verify the user has at least 30 points before processing
|
|||
|
|
2. IF a user has insufficient points, THEN THE File_Transfer_Service SHALL reject the upload and return an insufficient points error
|
|||
|
|
3. WHEN a file is successfully uploaded to COS, THE Points_Service SHALL deduct 30 points from the user's balance
|
|||
|
|
4. WHEN points are deducted, THE Points_Service SHALL create a consumption log with type "file_transfer" and description containing the file name
|
|||
|
|
|
|||
|
|
### Requirement 3: 文件记录管理
|
|||
|
|
|
|||
|
|
**User Story:** As a user, I want my uploaded files to be recorded in the database, so that I can track and query my file history.
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a file is successfully uploaded, THE File_Transfer_Service SHALL create a Transfer_File record in the database
|
|||
|
|
2. THE Transfer_File record SHALL contain: id, user_id, file_key, original_filename, file_size, content_type, cos_url, expire_time, status, create_time, update_time
|
|||
|
|
3. THE Transfer_File record SHALL set expire_time to 15 days from upload time
|
|||
|
|
4. THE Transfer_File record SHALL set initial status to "active"
|
|||
|
|
|
|||
|
|
### Requirement 4: 文件查询
|
|||
|
|
|
|||
|
|
**User Story:** As a user, I want to query my uploaded files, so that I can view my file history and access URLs.
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a user requests their file list with valid API Key, THE File_Transfer_Service SHALL return paginated list of their Transfer_File records
|
|||
|
|
2. WHEN querying files, THE File_Transfer_Service SHALL support filtering by status (active, expired, deleted)
|
|||
|
|
3. WHEN returning file list, THE File_Transfer_Service SHALL include file_key, original_filename, file_size, content_type, cos_url, expire_time, status, create_time
|
|||
|
|
4. WHEN a file has expired, THE File_Transfer_Service SHALL mark its status as "expired" in query results
|
|||
|
|
|
|||
|
|
### Requirement 5: 文件自动清理
|
|||
|
|
|
|||
|
|
**User Story:** As a system administrator, I want expired files to be automatically deleted from COS, so that storage costs are minimized and data retention policies are enforced.
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. THE File_Cleanup_Scheduler SHALL run periodically (every hour) to check for expired files
|
|||
|
|
2. WHEN a Transfer_File record has expire_time before current time and status is "active", THE File_Cleanup_Scheduler SHALL delete the file from COS
|
|||
|
|
3. WHEN a file is successfully deleted from COS, THE File_Cleanup_Scheduler SHALL update the Transfer_File status to "deleted"
|
|||
|
|
4. IF file deletion from COS fails, THEN THE File_Cleanup_Scheduler SHALL log the error and retry in the next scheduled run
|
|||
|
|
5. THE File_Cleanup_Scheduler SHALL process files in batches to avoid overwhelming the COS API
|
|||
|
|
|
|||
|
|
### Requirement 6: 错误处理
|
|||
|
|
|
|||
|
|
**User Story:** As a user, I want clear error messages when file upload fails, so that I can understand and resolve issues.
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. IF API Key authentication fails, THEN THE File_Transfer_Service SHALL return HTTP 401 with message "Invalid or inactive API Key"
|
|||
|
|
2. IF file type is not supported, THEN THE File_Transfer_Service SHALL return HTTP 400 with message "Unsupported file type. Allowed types: jpg, jpeg, png, gif, webp, bmp"
|
|||
|
|
3. IF file size exceeds 20MB, THEN THE File_Transfer_Service SHALL return HTTP 400 with message "File size exceeds maximum limit of 20MB"
|
|||
|
|
4. IF points are insufficient, THEN THE File_Transfer_Service SHALL return HTTP 400 with message "Insufficient points. Required: 30 points"
|
|||
|
|
5. IF COS upload fails, THEN THE File_Transfer_Service SHALL return HTTP 500 with message "File upload failed, please try again"
|