fastapi_file_uploader_for_class/REQUIREMENTS.md

요구사항 명세서

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:

  {
    "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:

  {
    "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