159 lines
4.8 KiB
Markdown
159 lines
4.8 KiB
Markdown
# 구현 보고서
|
|
|
|
## 프로젝트 정보
|
|
- **프로젝트명**: File Uploader
|
|
- **구현 일자**: 2026-02-26
|
|
- **버전**: 1.0.0
|
|
|
|
---
|
|
|
|
## 1. 구현 개요
|
|
|
|
REQUIREMENTS.md에 명시된 요구사항을 기반으로 FastAPI 파일 업로드/다운로드 서비스를 구현하였습니다.
|
|
|
|
---
|
|
|
|
## 2. 구현 내용
|
|
|
|
### 2.1 디렉토리 구조 생성
|
|
|
|
```
|
|
File_Uploader/
|
|
├── main.py # FastAPI 애플리케이션
|
|
├── assets/ # 파일 저장소
|
|
│ ├── images/ # 이미지 파일
|
|
│ ├── videos/ # 비디오 파일
|
|
│ └── files/ # 기타 파일
|
|
├── static/
|
|
│ └── index.html # 웹 인터페이스
|
|
├── README.md
|
|
├── REQUIREMENTS.md
|
|
└── REPORT.md
|
|
```
|
|
|
|
### 2.2 main.py 구현 내역
|
|
|
|
#### 2.2.1 기능적 요구사항 구현
|
|
|
|
| 요구사항 ID | 내용 | 구현 상태 | 비고 |
|
|
|-------------|------|-----------|------|
|
|
| FR-001 | 파일 업로드 기능 | ✅ 완료 | `POST /api/files/upload` |
|
|
| FR-002 | 파일 카테고리 분류 | ✅ 완료 | 확장자 기반 자동 분류 |
|
|
| FR-003 | 고유 파일명 생성 | ✅ 완료 | UUID 활용 |
|
|
| FR-004 | 메타데이터 기록 | ✅ 완료 | metadata.json 관리 |
|
|
| FR-005 | 메타데이터 정보 포함 | ✅ 완료 | 6개 항목 모두 포함 |
|
|
| FR-006 | 메타데이터 자동 생성 | ✅ 완료 | 파일 미존재 시 자동 생성 |
|
|
| FR-007 | 파일 다운로드 | ✅ 완료 | `GET /api/files/download/{filename}` |
|
|
| FR-008 | 원본 파일명 다운로드 | ✅ 완료 | FileResponse 활용 |
|
|
| FR-009 | 파일 미존재 에러 처리 | ✅ 완료 | 404 상태 코드 반환 |
|
|
| FR-010 | 웹 인터페이스 접근 | ✅ 완료 | `GET /web` |
|
|
| FR-011 | 웹 UI 파일 업로드/다운로드 | ✅ 완료 | 드래그 앤 드롭 지원 |
|
|
| FR-012 | 파일 목록 확인 | ✅ 완료 | `GET /api/files/list` |
|
|
|
|
#### 2.2.2 비기능적 요구사항 구현
|
|
|
|
| 요구사항 ID | 내용 | 구현 상태 | 비고 |
|
|
|-------------|------|-----------|------|
|
|
| NFR-001 | 파일 확장자 검증 | ✅ 완료 | ALLOWED_EXTENSIONS 정의 |
|
|
| NFR-002 | 파일 크기 제한 | ✅ 완료 | 100MB 제한 |
|
|
| NFR-003 | 경로 순회 공격 방지 | ✅ 완료 | 파일명 검증 로직 |
|
|
| NFR-004 | 에러 처리 | ✅ 완료 | HTTPException 활용 |
|
|
| NFR-005 | 메타데이터 복구 | ✅ 완료 | JSON 파싱 실패 시 빈 객체 반환 |
|
|
| NFR-006 | 대용량 파일 처리 | ⚠️ 부분 | 현재 메모리 로드 방식 |
|
|
|
|
### 2.3 API 엔드포인트
|
|
|
|
| Method | Endpoint | 기능 |
|
|
|--------|----------|------|
|
|
| POST | `/api/files/upload` | 파일 업로드 |
|
|
| GET | `/api/files/download/{filename}` | 파일 다운로드 |
|
|
| GET | `/api/files/list` | 파일 목록 조회 |
|
|
| DELETE | `/api/files/{filename}` | 파일 삭제 |
|
|
| GET | `/web` | 웹 인터페이스 |
|
|
|
|
### 2.4 웹 인터페이스 (static/index.html)
|
|
|
|
- **디자인**: 모던한 그라데이션 UI
|
|
- **기능**:
|
|
- 드래그 앤 드롭 파일 업로드
|
|
- 업로드 진행률 표시
|
|
- 파일 목록 실시간 갱신
|
|
- 다운로드/삭제 버튼
|
|
- 카테고리별 색상 뱃지 표시
|
|
|
|
---
|
|
|
|
## 3. 구현 세부 사항
|
|
|
|
### 3.1 파일 분류 로직
|
|
|
|
```python
|
|
ALLOWED_EXTENSIONS = {
|
|
"image": {".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg"},
|
|
"video": {".mp4", ".avi", ".mov", ".wmv", ".flv", ".mkv", ".webm"},
|
|
}
|
|
```
|
|
|
|
### 3.2 메타데이터 구조
|
|
|
|
```json
|
|
{
|
|
"files": [
|
|
{
|
|
"original_filename": "example.png",
|
|
"saved_filename": "uuid-generated.png",
|
|
"size": 1024,
|
|
"mime_type": "image/png",
|
|
"category": "image",
|
|
"upload_date": "2026-02-26T12:00:00"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 3.3 보안 조치
|
|
|
|
1. **경로 순회 방지**: `..`, `/`, `\\` 문자열 필터링
|
|
2. **파일 크기 제한**: 100MB 초과 시 413 에러 반환
|
|
3. **고유 파일명**: UUID로 중복 방지
|
|
|
|
---
|
|
|
|
## 4. 테스트 방법
|
|
|
|
### 4.1 서버 실행
|
|
|
|
```bash
|
|
# 가상환경 설정
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
|
|
# 의존성 설치
|
|
pip install fastapi uvicorn python-multipart
|
|
|
|
# 서버 실행
|
|
python main.py
|
|
# 또는
|
|
uvicorn main:app --reload --port 8000
|
|
```
|
|
|
|
### 4.2 접속
|
|
|
|
- **Web UI**: http://localhost:8000/web
|
|
- **API Docs**: http://localhost:8000/docs
|
|
|
|
---
|
|
|
|
## 5. 향후 개선 사항
|
|
|
|
1. **대용량 파일 처리**: 스트리밍 업로드로 변경 필요
|
|
2. **인증/인가**: 사용자별 파일 관리 기능
|
|
3. **파일 미리보기**: 이미지/비디오 썸네일 생성
|
|
4. **검색 기능**: 파일명, 카테고리 검색
|
|
5. **페이징**: 대량 파일 목록 페이징 처리
|
|
|
|
---
|
|
|
|
## 6. 결론
|
|
|
|
REQUIREMENTS.md에 명시된 모든 기능적 요구사항과 대부분의 비기능적 요구사항을 구현하였습니다. 기본적인 파일 업로드/다운로드 서비스로서 필요한 기능을 모두 갖추었으며, 향후 기능 확장을 위한 기반을 마련하였습니다. |