1818web-hoduan/.kiro/specs/file-transfer-service/requirements.md

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"