139 lines
4.4 KiB
Markdown
139 lines
4.4 KiB
Markdown
# 요구사항 명세서
|
|
|
|
## 1. 프로젝트 개요
|
|
FastAPI를 이용한 파일 업로드/다운로드 서비스 구현
|
|
|
|
---
|
|
|
|
## 2. 기능적 요구사항
|
|
|
|
### 2.1 파일 업로드
|
|
- **FR-001**: 사용자는 이미지, 비디오, 기타 파일을 업로드할 수 있어야 한다.
|
|
- **FR-002**: 업로드된 파일은 확장자에 따라 자동으로 분류되어 저장된다.
|
|
- 이미지 파일 (jpg, jpeg, png, gif, bmp, webp, svg) → `assets/images/`
|
|
- 비디오 파일 (mp4, avi, mov, wmv, flv, mkv, webm) → `assets/videos/`
|
|
- 기타 파일 → `assets/files/`
|
|
- **FR-003**: 동일한 파일명으로 업로드 시 충돌을 방지하기 위해 고유한 파일명을 생성해야 한다. (UUID 또는 타임스탬프 활용)
|
|
- **FR-004**: 업로드된 파일의 메타데이터를 `assets/metadata.json`에 기록해야 한다.
|
|
|
|
### 2.2 메타데이터 관리
|
|
- **FR-005**: 메타데이터는 다음 정보를 포함해야 한다.
|
|
- 원본 파일명
|
|
- 저장된 파일명
|
|
- 파일 크기
|
|
- MIME 타입
|
|
- 업로드 일시
|
|
- 파일 카테고리 (image/video/file)
|
|
- **FR-006**: 메타데이터 파일이 존재하지 않을 경우 자동으로 생성해야 한다.
|
|
|
|
### 2.3 파일 다운로드
|
|
- **FR-007**: 사용자는 저장된 파일명을 통해 파일을 다운로드할 수 있어야 한다.
|
|
- **FR-008**: 다운로드 시 원본 파일명으로 다운로드되어야 한다.
|
|
- **FR-009**: 존재하지 않는 파일 요청 시 적절한 에러 메시지를 반환해야 한다.
|
|
|
|
### 2.4 웹 인터페이스
|
|
- **FR-010**: `/web` 경로를 통해 웹 UI에 접근할 수 있어야 한다.
|
|
- **FR-011**: 웹 UI에서 파일 업로드 및 다운로드가 가능해야 한다.
|
|
- **FR-012**: 업로드된 파일 목록을 확인할 수 있어야 한다.
|
|
|
|
---
|
|
|
|
## 3. 비기능적 요구사항
|
|
|
|
### 3.1 보안
|
|
- **NFR-001**: 허용된 확장자의 파일만 업로드 가능하도록 검증해야 한다.
|
|
- **NFR-002**: 파일 업로드 크기 제한을 설정해야 한다. (기본: 100MB)
|
|
- **NFR-003**: 경로 순회(Path Traversal) 공격을 방지해야 한다.
|
|
|
|
### 3.2 안정성
|
|
- **NFR-004**: 파일 저장 중 오류 발생 시 롤백 처리를 해야 한다.
|
|
- **NFR-005**: 메타데이터 파일 손상 시 복구 가능한 형태로 관리해야 한다.
|
|
|
|
### 3.3 성능
|
|
- **NFR-006**: 대용량 파일 업로드를 위해 스트리밍 방식을 지원해야 한다.
|
|
|
|
---
|
|
|
|
## 4. API 명세
|
|
|
|
### 4.1 파일 업로드
|
|
- **Endpoint**: `POST /api/files/upload`
|
|
- **Request**: `multipart/form-data`
|
|
- `file`: 업로드할 파일
|
|
- **Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"filename": "saved_filename.ext",
|
|
"original_filename": "original.ext",
|
|
"size": 1024,
|
|
"category": "image"
|
|
}
|
|
```
|
|
|
|
### 4.2 파일 다운로드
|
|
- **Endpoint**: `GET /api/files/download/{filename}`
|
|
- **Response**: 파일 스트림
|
|
|
|
### 4.3 파일 목록 조회
|
|
- **Endpoint**: `GET /api/files/list`
|
|
- **Response**:
|
|
```json
|
|
{
|
|
"files": [
|
|
{
|
|
"original_filename": "original.ext",
|
|
"saved_filename": "saved_filename.ext",
|
|
"size": 1024,
|
|
"category": "image",
|
|
"upload_date": "2026-02-26T12:00:00"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 4.4 정적 웹 페이지
|
|
- **Endpoint**: `GET /web`
|
|
- **Response**: HTML 페이지
|
|
|
|
---
|
|
|
|
## 5. 에러 처리
|
|
|
|
| 에러 코드 | 상황 | HTTP 상태 코드 |
|
|
|-----------|------|----------------|
|
|
| FILE_NOT_FOUND | 요청한 파일이 존재하지 않음 | 404 |
|
|
| INVALID_FILE_TYPE | 허용되지 않은 파일 확장자 | 400 |
|
|
| FILE_TOO_LARGE | 파일 크기 초과 | 413 |
|
|
| UPLOAD_FAILED | 파일 업로드 실패 | 500 |
|
|
| METADATA_ERROR | 메타데이터 처리 실패 | 500 |
|
|
|
|
---
|
|
|
|
## 6. 기술 스택
|
|
- **Framework**: FastAPI
|
|
- **Server**: Uvicorn
|
|
- **Language**: Python 3.x
|
|
- **Dependencies**: python-multipart
|
|
|
|
---
|
|
|
|
## 7. 디렉토리 구조
|
|
```
|
|
File_Uploader/
|
|
├── main.py # FastAPI 애플리케이션 및 API 로직
|
|
├── assets/ # 업로드된 파일 및 메타데이터 저장소
|
|
│ ├── images/ # 이미지 파일 저장소
|
|
│ ├── videos/ # 비디오 파일 저장소
|
|
│ ├── files/ # 기타 파일 저장소
|
|
│ └── metadata.json # 메타데이터 저장소
|
|
└── static/ # 프론트엔드 자산
|
|
└── index.html # 웹 인터페이스
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 실행 환경
|
|
- **Port**: 8000
|
|
- **Web UI**: `http://localhost:8000/web`
|
|
- **API Docs**: `http://localhost:8000/docs` |