138 lines
4.4 KiB
Markdown
138 lines
4.4 KiB
Markdown
# Attachment Feature Documentation
|
|
|
|
## Overview
|
|
|
|
The attachment feature allows users to upload and manage file attachments for their applications. Each application can have up to 30 attachments with a combined maximum size of 100MB.
|
|
|
|
## Database Schema
|
|
|
|
### `attachments` Table
|
|
Stores the actual file data and metadata:
|
|
- `id` (INT, PRIMARY KEY) - Unique identifier
|
|
- `filename` (VARCHAR 255) - Original filename
|
|
- `content_type` (VARCHAR 100) - MIME type of the file
|
|
- `size` (INT) - File size in bytes
|
|
- `data` (LONGTEXT) - Base64 encoded file content
|
|
- `created_at` (DATETIME) - Upload timestamp
|
|
|
|
### `application_attachments` Table
|
|
Links attachments to applications (many-to-many relationship):
|
|
- `id` (INT, PRIMARY KEY) - Unique identifier
|
|
- `application_id` (INT) - References the application
|
|
- `attachment_id` (INT) - References the attachment
|
|
- `created_at` (DATETIME) - Link creation timestamp
|
|
- Unique constraint on (`application_id`, `attachment_id`)
|
|
|
|
## API Endpoints
|
|
|
|
### Upload Attachment
|
|
`POST /api/applications/{pa_id}/attachments`
|
|
- Requires authentication (PA-KEY or MASTER-KEY)
|
|
- Request body: multipart/form-data with file
|
|
- Returns: AttachmentUploadResponse with attachment ID, filename, and size
|
|
- Validates:
|
|
- Maximum 30 attachments per application
|
|
- Individual file size limit of 25MB per file
|
|
- Total size limit of 100MB across all attachments
|
|
|
|
### List Attachments
|
|
`GET /api/applications/{pa_id}/attachments`
|
|
- Requires authentication (PA-KEY or MASTER-KEY)
|
|
- Returns: Array of AttachmentInfo objects
|
|
|
|
### Download Attachment
|
|
`GET /api/applications/{pa_id}/attachments/{attachment_id}`
|
|
- Requires authentication (PA-KEY or MASTER-KEY)
|
|
- Returns: File content with appropriate content-type header
|
|
|
|
### Delete Attachment
|
|
`DELETE /api/applications/{pa_id}/attachments/{attachment_id}`
|
|
- Requires authentication (PA-KEY or MASTER-KEY)
|
|
- Removes both the attachment and the link to the application
|
|
|
|
## Frontend Component
|
|
|
|
### AttachmentManager Component
|
|
Located at: `frontend/src/components/Attachments/AttachmentManager.tsx`
|
|
|
|
Features:
|
|
- File upload with progress tracking
|
|
- List view with file type icons
|
|
- Download functionality
|
|
- Delete with confirmation dialog
|
|
- Real-time validation of limits (30 files, 100MB total)
|
|
- Responsive design with Material-UI
|
|
|
|
Props:
|
|
- `paId` (string) - Application ID
|
|
- `paKey` (string, optional) - Application key for authentication
|
|
- `readOnly` (boolean) - Disable upload/delete actions
|
|
- `isAdmin` (boolean) - Use master key for authentication
|
|
|
|
## Implementation Details
|
|
|
|
### Security
|
|
- All endpoints require authentication via PA-KEY or MASTER-KEY headers
|
|
- Files are stored as Base64 encoded data in the database
|
|
- Application ownership is verified before allowing access to attachments
|
|
|
|
### File Type Support
|
|
- All file types are supported
|
|
- Special icons for:
|
|
- Images (image/*)
|
|
- PDFs (application/pdf)
|
|
- Word documents (application/msword, .docx)
|
|
- Generic files (all others)
|
|
|
|
### Performance Considerations
|
|
- Files are stored in the database as Base64 strings (increases size by ~33%)
|
|
- Individual files are limited to 25MB to prevent database issues
|
|
- Large files may impact database performance
|
|
- The data column uses MySQL LONGTEXT type (supports up to 4GB)
|
|
- Consider implementing file streaming for very large files
|
|
- Progress tracking uses XMLHttpRequest for better upload experience
|
|
|
|
## Migration
|
|
|
|
To add the attachment tables to an existing database, run:
|
|
|
|
```sql
|
|
mysql -u your_user -p your_database < src/migrations/add_attachments_tables.sql
|
|
```
|
|
|
|
If you already created the tables but need to fix the data column type:
|
|
|
|
```sql
|
|
mysql -u your_user -p your_database < src/migrations/alter_attachments_data_column.sql
|
|
```
|
|
|
|
## Usage Example
|
|
|
|
### In ViewApplicationPage
|
|
```tsx
|
|
<AttachmentManager
|
|
paId={paId}
|
|
paKey={paKey}
|
|
readOnly={!isAdmin && currentApplication.status !== "new"}
|
|
isAdmin={isAdmin}
|
|
/>
|
|
```
|
|
|
|
### In AdminApplicationView
|
|
```tsx
|
|
<AttachmentManager
|
|
paId={paId}
|
|
readOnly={false}
|
|
isAdmin={true}
|
|
/>
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
1. **File Preview**: Add preview functionality for images and PDFs
|
|
2. **Drag & Drop**: Implement drag-and-drop file upload
|
|
3. **Bulk Upload**: Allow multiple files to be uploaded at once
|
|
4. **File Compression**: Compress files before storing to save space
|
|
5. **External Storage**: Move file storage to S3 or similar service for better scalability
|
|
6. **Virus Scanning**: Integrate virus scanning for uploaded files
|
|
7. **File Versioning**: Track file versions/updates |