# 요구사항 명세서

## 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`