프로젝트 : 스토리지(Storage)

Wed, 10 Dec 2025 11:52:58 GMT

## 개요

Storage 페이지는 프로젝트의 파일과 미디어를 저장하고 관리하는 스토리지 관리 페이지입니다.

**경로**: `/org/{orgSlug}/project/{projectSlug}/storage`

## 주요 기능

### 1. 환경 선택

※ 현재 Beta에서는 dev 환경이 사용됩니다.

**기술적 구조**:

- Namespace 기반 파일 격리 (형식: `{projectId}-{environmentId}`)

- 환경별 독립적인 스토리지 관리

### 2. 스토리지 통계

**3개의 통계 카드**:

- **총 파일 수**: 전체 파일 개수

- **총 용량**: 전체 파일 크기 합계 (GB, MB, KB 단위)

- **버킷**: 사용 가능한 버킷 개수

**표시 조건**:

- 버킷 목록 화면에서만 표시

- 파일 브라우저 화면에서는 숨김

### 3. 버킷 관리

**사전 정의된 버킷**:

- `avatars` (공개) - 프로필 이미지 등

- `documents` (비공개) - 문서 파일

- `media` (공개) - 미디어 파일

- `files` (비공개) - 일반 파일

**버킷 정보**:

- 버킷 이름

- 접근 권한 (공개/비공개)

- 파일 개수

- 총 용량

**작업**:

- 버킷 클릭하여 파일 목록 보기

- 검색으로 버킷 필터링

- 새로고침 버튼으로 목록 갱신

**제한사항**:

- 버킷 생성/삭제/설정 기능은 준비 중 (버튼 비활성화)

### 4. 파일 업로드

**업로드 방법**:

1. 버킷 선택

2. "업로드" 버튼 클릭

3. 파일 선택 또는 드래그 앤 드롭

4. 자동으로 업로드 진행

**업로드 프로세스**:

1. Presigned URL 발급 (백엔드 API)

2. S3로 직접 업로드

3. 파일 메타데이터 생성 (MongoDB)

**자동 처리 기능**:

- 이미지 파일의 경우 너비/높이 자동 추출

- 파일 확장자 자동 추출 및 메타데이터 저장

- 현재 사용자를 파일 소유자로 자동 설정

- 버킷의 공개/비공개 설정에 따라 visibility 자동 설정

**진행 상태**:

- 업로드 중 진행률 표시 (%)

- 여러 파일 동시 업로드 시 순차 처리

- 완료 시 성공 메시지 및 파일 개수 표시

### 5. 파일 브라우저

**파일 목록 표시**:

- 파일 아이콘 (MIME 타입별)

- 파일명

- 파일 크기

- 파일 유형 (MIME 타입)

- 수정일 (날짜 및 시간)

**파일 아이콘**:

- 이미지 파일: 이미지 아이콘

- 동영상 파일: 필름 아이콘

- 오디오 파일: 음악 아이콘

- PDF/문서: 문서 아이콘

- 압축 파일: 아카이브 아이콘

- 기타: 일반 파일 아이콘

**정렬 기능**:

- 날짜순 정렬 (기본)

- 이름순 정렬

- 크기순 정렬

- 오름차순/내림차순 전환

**검색 기능**:

- 파일명 검색

- MIME 타입 검색

- 실시간 필터링

**선택 기능**:

- 개별 파일 체크박스

- 전체 선택/해제

- 선택한 파일 개수 표시

### 6. 파일 작업

**다운로드**:

- **공개 파일**: Image Handler를 통해 직접 다운로드

- **비공개 파일**: 임시 다운로드 URL 생성 (1시간 유효)

- 새 탭에서 다운로드 시작

**URL 복사**:

- **공개 파일**: 영구적인 Image Handler URL 복사

- **비공개 파일**: 1시간 유효한 임시 다운로드 URL 복사

- 클립보드에 자동 복사 및 알림 표시

**삭제**:

- 확인 대화상자 표시

- 파일명 표시 및 경고 메시지

- MongoDB에서 메타데이터 삭제 (S3 파일은 별도 정책으로 관리)

- 삭제 후 목록 자동 갱신

### 7. 버킷 네비게이션

**버킷 헤더**:

- "← 버킷 목록으로" 버튼

- 버킷 이름 및 아이콘

- 공개/비공개 배지

**버킷 나가기**:

- 버튼 클릭 시 버킷 목록으로 돌아가기

- 검색어 및 선택 상태 초기화

## 사용 방법

### 파일 업로드하기

1. Storage 페이지 접속

2. 원하는 환경 선택 (탭)

3. 업로드할 버킷 선택 (예: avatars, media)

4. "업로드" 버튼 클릭

5. 파일 선택 또는 드래그 앤 드롭

6. 업로드 완료 대기

### 파일 검색하기

1. 버킷 선택

2. 검색 입력창에 파일명 또는 파일 유형 입력

3. 실시간으로 필터링된 결과 확인

### 파일 다운로드하기

1. 파일 행의 더보기 메뉴 (⋮) 클릭

2. "다운로드" 선택

3. 새 탭에서 다운로드 시작

### 파일 URL 복사하기

1. 파일 행의 더보기 메뉴 (⋮) 클릭

2. "URL 복사" 선택

3. 클립보드에 복사된 URL 사용

### 파일 삭제하기

1. 파일 행의 더보기 메뉴 (⋮) 클릭

2. "삭제" 선택

3. 확인 대화상자에서 "삭제" 버튼 클릭

### 파일 정렬하기

1. 정렬 드롭다운에서 정렬 기준 선택 (날짜순/이름순/크기순)

2. 화살표 버튼으로 오름차순/내림차순 전환

## 기술 구조

### Namespace 기반 격리

- 형식: `{projectId}-{environmentId}`

- 프로젝트 및 환경별 파일 격리

- 멀티테넌시 지원

### 파일 메타데이터

- MongoDB에 저장

- 필드: s3Key, originalName, mimeType, size, width, height, bucket, visibility, namespace, ownerId, ownerType, metadata, createdAt

### 파일 소유권

- **ownerType**: user, session, service, public

- **ownerId**: 사용자 ID 또는 세션 ID

- **visibility**: public (공개), private (비공개)

### 파일 접근

- **공개 파일**: Image Handler를 통해 직접 접근 가능

- **비공개 파일**: 권한 검증 후 임시 presigned URL 발급 (1시간 유효)