70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# Detailed Software Requirements Specification
|
|
|
|
## 1. Project Overview
|
|
A web-based file management system using FastAPI that allows users to upload and download files. The system categorizes files by type and maintains metadata in a JSON file.
|
|
|
|
## 2. Functional Requirements
|
|
|
|
### 2.1 File Upload
|
|
- **Endpoint**: `POST /api/files/upload`
|
|
- **Description**: Accepts a file and its associated metadata.
|
|
- **Payload**: Multipart form-data containing:
|
|
- `file`: The actual file to upload.
|
|
- `description`: (Optional) A brief description of the file.
|
|
- `uploader`: (Optional) Name of the person uploading.
|
|
- **Storage Logic**:
|
|
- Images (e.g., JPG, PNG, GIF) must be saved in `assets/images/`.
|
|
- Videos (e.g., MP4, AVI, MKV) must be saved in `assets/videos/`.
|
|
- *Optional: Handle other file types or return an error if unsupported.*
|
|
- **Metadata Management**:
|
|
- Upon successful upload, record the following in `metadata.json`:
|
|
- `filename`: Original or sanitized filename.
|
|
- `type`: MIME type or category (image/video).
|
|
- `upload_date`: ISO 8601 formatted timestamp.
|
|
- `file_path`: Relative path to the stored file.
|
|
- `description`: Provided description.
|
|
- `uploader`: Provided uploader name.
|
|
|
|
### 2.2 File List Retrieval
|
|
- **Endpoint**: `GET /api/files`
|
|
- **Description**: Returns a list of all uploaded files and their metadata.
|
|
- **Response**: JSON array containing metadata for each file stored in `metadata.json`.
|
|
|
|
### 2.3 File Download
|
|
- **Endpoint**: `GET /api/files/download`
|
|
- **Parameters**: `filename` (query parameter).
|
|
- **Description**: Streams the requested file to the client.
|
|
- **Error Handling**: Return 404 if the file is not found in metadata or on disk.
|
|
|
|
### 2.3 Static Web Serving
|
|
- **Endpoint**: `/web`
|
|
- **Description**: Serve static HTML, CSS, and JavaScript files from a `static` directory to provide a user interface.
|
|
|
|
## 3. Technical Requirements
|
|
|
|
### 3.1 Backend
|
|
- **Framework**: FastAPI
|
|
- **Language**: Python 3.9+
|
|
- **Dependencies**: `python-multipart` (for file uploads), `uvicorn` (ASGI server).
|
|
|
|
### 3.2 Data Storage
|
|
- **Filesystem**: Local storage under `assets/` directory.
|
|
- **Metadata**: A single `metadata.json` file acting as a lightweight database.
|
|
|
|
### 3.3 Directory Structure
|
|
```
|
|
.
|
|
├── main.py # FastAPI application entry point
|
|
├── metadata.json # File metadata storage
|
|
├── assets/
|
|
│ ├── images/ # Uploaded image files
|
|
│ └── videos/ # Uploaded video files
|
|
├── static/ # Web frontend files (HTML/CSS/JS)
|
|
└── REQUIREMENTS.md # This document
|
|
```
|
|
|
|
## 4. Non-Functional Requirements
|
|
- **Security**: Sanitize filenames to prevent path traversal attacks.
|
|
- **Performance**: Efficiently handle file streaming for downloads.
|
|
- **Maintainability**: Clear separation between API logic and file management.
|