Init Repo
This commit is contained in:
@@ -0,0 +1,246 @@
|
||||
# File Handling System Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The VFX Project Management System includes a comprehensive file handling system that provides secure file upload, storage, serving, and access control for task attachments and work submissions.
|
||||
|
||||
## Features
|
||||
|
||||
### File Upload System
|
||||
- **Secure file validation** with format and size restrictions
|
||||
- **Organized directory structure** for efficient file storage
|
||||
- **Unique filename generation** to prevent conflicts
|
||||
- **Automatic thumbnail generation** for image files
|
||||
- **Version control** for submissions
|
||||
|
||||
### File Serving and Access Control
|
||||
- **Authenticated file serving** with role-based permissions
|
||||
- **Thumbnail serving** for quick previews
|
||||
- **Video streaming** for media playback
|
||||
- **File information API** for metadata access
|
||||
|
||||
## Supported File Formats
|
||||
|
||||
### Video Formats
|
||||
- `.mov` - QuickTime Movie
|
||||
- `.mp4` - MPEG-4 Video
|
||||
- `.avi` - Audio Video Interleave
|
||||
- `.mkv` - Matroska Video
|
||||
- `.webm` - WebM Video
|
||||
|
||||
### Image Formats
|
||||
- `.exr` - OpenEXR (High Dynamic Range)
|
||||
- `.jpg`, `.jpeg` - JPEG Image
|
||||
- `.png` - Portable Network Graphics
|
||||
- `.tiff`, `.tif` - Tagged Image File Format
|
||||
- `.dpx` - Digital Picture Exchange
|
||||
- `.hdr` - High Dynamic Range Image
|
||||
|
||||
### Document Formats
|
||||
- `.pdf` - Portable Document Format
|
||||
- `.txt` - Plain Text
|
||||
- `.doc`, `.docx` - Microsoft Word Document
|
||||
|
||||
### Archive Formats
|
||||
- `.zip` - ZIP Archive
|
||||
- `.rar` - RAR Archive
|
||||
- `.7z` - 7-Zip Archive
|
||||
|
||||
## File Size Limits
|
||||
|
||||
- **Task Attachments**: 10MB maximum
|
||||
- **Work Submissions**: 500MB maximum
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### File Upload Endpoints (via Tasks Router)
|
||||
|
||||
#### Upload Task Attachment
|
||||
```
|
||||
POST /tasks/{task_id}/attachments
|
||||
```
|
||||
- Uploads a file attachment to a task
|
||||
- Creates thumbnail for image files
|
||||
- Returns attachment metadata with serving URLs
|
||||
|
||||
#### Submit Work
|
||||
```
|
||||
POST /tasks/{task_id}/submit
|
||||
```
|
||||
- Submits work file for review
|
||||
- Automatically versions submissions
|
||||
- Updates task status to "submitted"
|
||||
|
||||
### File Serving Endpoints
|
||||
|
||||
#### Serve Attachment
|
||||
```
|
||||
GET /files/attachments/{attachment_id}
|
||||
GET /files/attachments/{attachment_id}?thumbnail=true
|
||||
```
|
||||
- Serves attachment files with access control
|
||||
- Optional thumbnail parameter for image previews
|
||||
|
||||
#### Serve Submission
|
||||
```
|
||||
GET /files/submissions/{submission_id}
|
||||
GET /files/submissions/{submission_id}?thumbnail=true
|
||||
```
|
||||
- Serves submission files with access control
|
||||
- Optional thumbnail parameter for image previews
|
||||
|
||||
#### Stream Submission
|
||||
```
|
||||
GET /files/submissions/{submission_id}/stream
|
||||
```
|
||||
- Streams video files for playback
|
||||
- Supports range requests for efficient streaming
|
||||
|
||||
#### File Information
|
||||
```
|
||||
GET /files/info/attachment/{attachment_id}
|
||||
GET /files/info/submission/{submission_id}
|
||||
```
|
||||
- Returns file metadata and information
|
||||
- Includes file type detection and existence status
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
backend/uploads/
|
||||
├── attachments/
|
||||
│ └── {task_id}/
|
||||
│ └── {unique_filename}
|
||||
├── submissions/
|
||||
│ └── {task_id}/
|
||||
│ └── {versioned_filename}
|
||||
└── thumbnails/
|
||||
└── {filename}_thumb.jpg
|
||||
```
|
||||
|
||||
## Access Control
|
||||
|
||||
### Permission Matrix
|
||||
|
||||
| User Role | Own Tasks | Other Tasks | Review Access |
|
||||
|-------------|-----------|-------------|---------------|
|
||||
| Artist | ✓ | ✗ | ✗ |
|
||||
| Coordinator | ✓ | ✓ | ✓ |
|
||||
| Director | ✓ | ✓ | ✓ |
|
||||
| Admin | ✓ | ✓ | ✓ |
|
||||
|
||||
### Security Features
|
||||
|
||||
- **Authentication required** for all file operations
|
||||
- **Role-based access control** for file serving
|
||||
- **File type validation** to prevent malicious uploads
|
||||
- **File size limits** to prevent abuse
|
||||
- **Unique filename generation** to prevent conflicts
|
||||
- **Path traversal protection** through controlled directory structure
|
||||
|
||||
## File Handler Utility
|
||||
|
||||
The `FileHandler` class provides core functionality:
|
||||
|
||||
### Key Methods
|
||||
|
||||
- `validate_file()` - Validates file format and size
|
||||
- `save_file()` - Saves uploaded file with unique naming
|
||||
- `delete_file()` - Removes file and associated thumbnail
|
||||
- `create_thumbnail()` - Generates image thumbnails
|
||||
- `get_file_info()` - Returns file metadata
|
||||
- `is_image_file()` / `is_video_file()` - File type detection
|
||||
|
||||
### Configuration
|
||||
|
||||
```python
|
||||
# File size limits
|
||||
MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024 # 10MB
|
||||
MAX_SUBMISSION_SIZE = 500 * 1024 * 1024 # 500MB
|
||||
|
||||
# Thumbnail settings
|
||||
THUMBNAIL_SIZE = (200, 200)
|
||||
THUMBNAIL_QUALITY = 85
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Frontend Integration
|
||||
|
||||
```javascript
|
||||
// Upload attachment
|
||||
const formData = new FormData();
|
||||
formData.append('file', file);
|
||||
formData.append('attachment_type', 'reference');
|
||||
formData.append('description', 'Reference image');
|
||||
|
||||
const response = await fetch(`/tasks/${taskId}/attachments`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: formData
|
||||
});
|
||||
|
||||
const attachment = await response.json();
|
||||
console.log('Download URL:', attachment.download_url);
|
||||
console.log('Thumbnail URL:', attachment.thumbnail_url);
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Submit work
|
||||
const formData = new FormData();
|
||||
formData.append('file', workFile);
|
||||
formData.append('notes', 'Final version ready for review');
|
||||
|
||||
const response = await fetch(`/tasks/${taskId}/submit`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: formData
|
||||
});
|
||||
|
||||
const submission = await response.json();
|
||||
console.log('Stream URL:', submission.stream_url);
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Responses
|
||||
|
||||
- `400 Bad Request` - Invalid file format or missing filename
|
||||
- `403 Forbidden` - Insufficient permissions to access file
|
||||
- `404 Not Found` - File or associated task not found
|
||||
- `413 Payload Too Large` - File exceeds size limits
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "File too large. Maximum size is 10MB"
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Chunked streaming** for large video files
|
||||
- **On-demand thumbnail generation** with caching
|
||||
- **Efficient file serving** with proper MIME types
|
||||
- **Range request support** for video streaming
|
||||
|
||||
## Maintenance
|
||||
|
||||
### File Cleanup
|
||||
|
||||
The system does not automatically clean up orphaned files. Consider implementing:
|
||||
|
||||
- Periodic cleanup of files without database references
|
||||
- Archive old submissions after project completion
|
||||
- Monitor disk usage and implement retention policies
|
||||
|
||||
### Backup Considerations
|
||||
|
||||
- Include upload directories in backup procedures
|
||||
- Consider separate backup strategy for large media files
|
||||
- Implement file integrity checks for critical submissions
|
||||
Reference in New Issue
Block a user