first

기획/기획서.md

@@ -0,0 +1,963 @@
+
+> 버전: v0.1  
+> 목적: MVP 개발 범위 확정 및 구현 기준 문서  
+> 저장소 전략(1차): **Local FS** (향후 S3/MinIO로 확장 가능하도록 추상화)
+
+---
+
+## 1) 문서 목적
+
+- MVP 범위 확정
+    
+- 기능 우선순위 정의
+    
+- 도메인 모델/데이터 구조 초안 정리
+    
+- API/업로드/다운로드/공유 흐름 정의
+    
+- 구현 시 의사결정 기준(로컬FS, tus, 미리보기, 보안) 명시
+    
+
+---
+
+## 2) 제품 정의 (개발 관점 요약)
+
+### 목표
+
+Nextcloud의 핵심 기능(파일 관리/공유/미리보기)을 제공하되, **더 빠른 체감 UX**를 목표로 하는 파일 호스팅 서비스의 MVP 구현.
+
+### 핵심 전략
+
+- **UI/응답 체감 속도 최적화**
+    
+- **대용량 업로드 안정성 확보 (tus)**
+    
+- **저장소는 로컬FS로 단순 시작**
+    
+- **메타데이터(DB)와 파일 저장(Local FS) 분리**
+    
+- **향후 S3/Object Storage 전환 가능한 구조**
+    
+
+---
+
+## 3) 개발 범위 (MVP 범위 확정)
+
+## 3-1. 포함 범위 (In Scope)
+
+### A. 인증/회원
+
+- 회원가입
+    
+- 로그인 / 로그아웃
+    
+- 인증 세션 유지 (Cookie 또는 JWT)
+    
+- 기본 프로필 조회
+    
+
+### B. 파일/폴더 관리
+
+- 폴더 생성
+    
+- 폴더명 변경
+    
+- 폴더 삭제 (비어있지 않은 경우 정책 정의)
+    
+- 파일 업로드 (tus 기반)
+    
+- 파일 다운로드
+    
+- 파일명 변경
+    
+- 파일 이동 (폴더 이동)
+    
+- 파일 삭제
+    
+- 파일 목록 조회 (폴더 단위)
+    
+- 정렬 (이름/크기/수정일)
+    
+
+### C. 공유
+
+- 공유 링크 생성
+    
+- 링크 만료일 설정(선택)
+    
+- 링크 비밀번호 설정(선택)
+    
+- 공유 링크 비활성화
+    
+- 공유 링크를 통한 다운로드
+    
+
+### D. 미리보기 (MVP 최소)
+
+- 이미지 (jpg/png/webp/gif)
+    
+- 텍스트 (txt/md/json/log 등)
+    
+- PDF (브라우저 내장 뷰어 활용)
+    
+- (선택) 동영상 기본 재생은 MVP 후순위
+    
+
+### E. 운영 기본
+
+- 사용자별 저장 용량 집계(Quota 표시)
+    
+- 업로드 크기 제한
+    
+- 기본 로그(업로드/삭제/공유 생성)
+    
+
+---
+
+## 3-2. 제외 범위 (Out of Scope, MVP)
+
+> “나중에 넣을 기능”으로 명시
+
+- WebDAV
+    
+- FTP/SFTP
+    
+- 파일 버전 관리
+    
+- 중복 파일 탐지
+    
+- 실시간 협업 편집
+    
+- 커뮤니티/채팅/공유 스페이스
+    
+- 서버 측 외부 다운로드(유튜브/토렌트 등)
+    
+- 관리자 대시보드 고도화
+    
+- 바이러스 스캔 (후속 가능)
+    
+
+---
+
+## 4) 핵심 요구사항 (FR: Functional Requirements)
+
+아래는 개발/테스트 가능한 형태로 쪼갠 기능 요구사항이다.
+
+### FR-001 회원가입
+
+- 이메일/아이디 + 비밀번호로 회원가입 가능
+    
+- 중복 계정 방지
+    
+- 비밀번호 해시 저장
+    
+
+### FR-002 로그인/로그아웃
+
+- 유효한 자격 증명으로 로그인 가능
+    
+- 로그인 후 보호 API 접근 가능
+    
+- 로그아웃 시 세션/토큰 무효화 처리
+    
+
+### FR-003 루트 폴더 접근
+
+- 로그인한 사용자는 자신의 루트 폴더를 조회할 수 있어야 함
+    
+- 최초 가입 시 사용자 루트 공간 자동 생성
+    
+
+### FR-004 폴더 생성
+
+- 특정 폴더 하위에 새 폴더 생성 가능
+    
+- 동일 부모 내 중복 이름 정책 정의 (허용/비허용 중 선택)
+    
+
+### FR-005 파일 업로드 (tus)
+
+- 대용량 파일 업로드 가능
+    
+- 네트워크 중단 후 재개 가능
+    
+- 업로드 완료 후 메타데이터 저장 및 목록 반영
+    
+
+### FR-006 파일 다운로드
+
+- 권한 있는 사용자는 파일 다운로드 가능
+    
+- 공유 링크로도 다운로드 가능 (권한/만료 조건 충족 시)
+    
+
+### FR-007 파일/폴더 이름 변경
+
+- 사용자 UI에서 이름 변경 가능
+    
+- 실제 저장 경로 변경 없이 메타데이터만 변경 가능해야 함
+    
+
+### FR-008 파일 이동
+
+- 파일을 다른 폴더로 이동 가능
+    
+- 실제 저장 파일은 이동하지 않고 메타데이터 위치만 변경 가능해야 함
+    
+
+### FR-009 파일 삭제
+
+- 파일 삭제 시 사용자 목록에서 제거
+    
+- 실제 파일 삭제는 즉시 또는 지연 배치 정책 적용 가능
+    
+
+### FR-010 공유 링크
+
+- 파일에 대해 공유 링크 생성 가능
+    
+- 만료일/비밀번호/활성화 상태 설정 가능
+    
+- 공유 링크 접근 시 다운로드 가능
+    
+
+### FR-011 미리보기
+
+- 이미지/텍스트/PDF 미리보기 가능
+    
+- 지원하지 않는 형식은 다운로드만 허용
+    
+
+### FR-012 저장 용량 집계
+
+- 사용자별 총 사용 용량 계산 가능
+    
+- 업로드 시 quota 초과 여부 검사 가능
+    
+
+---
+
+## 5) 비기능 요구사항 (NFR)
+
+### NFR-001 성능 (체감 UX 우선)
+
+- 폴더 목록 조회 응답이 빠르게 느껴져야 함
+    
+- UI에서 폴더 이동/정렬 시 불필요한 전체 리렌더 최소화
+    
+- 미리보기는 가능하면 캐싱 사용
+    
+
+### NFR-002 안정성
+
+- 업로드 중단/재시도 가능 (tus)
+    
+- 메타데이터(DB)와 파일(Local FS)의 정합성 검증 가능한 구조
+    
+- 예외 발생 시 사용자에게 명확한 오류 메시지 제공
+    
+
+### NFR-003 보안
+
+- 인증/인가 필수
+    
+- 공유 링크 비밀번호는 평문 저장 금지(해시)
+    
+- 파일 경로 조작(Path Traversal) 방지
+    
+- 사용자 입력 파일명/폴더명 검증
+    
+- 업로드 파일 MIME 신뢰 금지(서버 검증 우선)
+    
+
+### NFR-004 확장성
+
+- 저장소 접근은 인터페이스로 추상화 (`IStorageService`)
+    
+- Local FS 구현과 S3 구현을 교체 가능한 구조로 설계
+    
+- 미리보기 생성도 별도 서비스 인터페이스로 분리
+    
+
+---
+
+## 6) 핵심 설계 원칙 (중요)
+
+### 원칙 1. “사용자 폴더 구조”와 “실제 디스크 경로”를 분리한다
+
+MVP가 로컬FS라도, 실제 디스크에 사용자 폴더 구조를 그대로 반영하지 않는다.
+
+#### 이유
+
+- 파일명/경로 보안 이슈 감소
+    
+- rename/move 시 파일 이동 비용 제거
+    
+- S3 전환 시 구조 변경 최소화
+    
+- 충돌/인코딩/특수문자 이슈 감소
+    
+
+#### 권장 방식
+
+- **DB에는 논리 폴더 구조 저장**
+    
+- **디스크에는 object key 기반 저장**
+    
+
+예시:
+
+- 사용자에게 보이는 경로: `/문서/프로젝트/기획서.pdf`
+    
+- 실제 저장 경로: `/data/objects/ab/cd/<fileObjectId>`
+    
+- DB 매핑:
+    
+    - display_name = `기획서.pdf`
+        
+    - folder_id = `...`
+        
+    - storage_key = `ab/cd/<fileObjectId>`
+        
+
+---
+
+### 원칙 2. 업로드 완료 전까지 “파일 엔트리 확정” 금지
+
+tus 업로드는 중간 상태가 있으므로 업로드 세션과 최종 파일 엔트리를 분리한다.
+
+- 업로드 중: `UploadSession`
+    
+- 완료 후: `FileItem` 생성 (또는 상태 전환)
+    
+
+---
+
+### 원칙 3. 공유 링크는 파일 권한과 별도 정책으로 관리
+
+공유 링크는 사용자 인증과 별도로 동작하므로 별도 엔티티/검증 흐름 필요.
+
+- 만료일
+    
+- 비밀번호
+    
+- 활성화 여부
+    
+- 다운로드 횟수(선택)
+    
+
+---
+
+## 7) 시스템 구성 (MVP 아키텍처 초안)
+
+### 7-1. 구성 요소
+
+- **Frontend (Blazor)**  
+    파일 탐색 UI / 업로드 UI / 미리보기 / 공유 설정
+    
+- **Backend API (ASP.NET Core)**  
+    인증, 파일/폴더 메타데이터, 공유, 다운로드, 미리보기 라우팅
+    
+- **Upload Endpoint (tus)**  
+    tus 프로토콜 처리, 업로드 세션 관리, 완료 콜백
+    
+- **Database (예: PostgreSQL/MySQL)**  
+    사용자/폴더/파일/공유링크/업로드세션 메타데이터
+    
+- **Local FS**
+    
+    - object 파일 저장
+        
+    - 임시 업로드 파일
+        
+    - 미리보기/썸네일 캐시
+	
+- Redis
+	 업로드, 다운로드 토큰 캐싱 등 
+### 7-2. 디렉토리 구조 예시
+
+```text
+/data
+  /objects        # 최종 파일 저장
+    /ab/cd/<file_id>
+  /uploads-temp   # tus 임시 조각/세션 파일
+  /previews       # 미리보기 캐시(이미지 썸네일, 텍스트 캐시 등)
+  /trash          # (선택) 지연 삭제 보관
+```
+
+---
+
+## 8) 도메인 모델 (MVP 기준)
+
+## 8-1. 엔티티 목록
+
+### User
+
+- id
+    
+- email(or loginId)
+    
+- password_hash
+    
+- display_name
+	
+- role (admin / user)
+	
+- created_at
+    
+- last_login_at
+    
+- storage_allowed_bytes (null이면 무한)
+    
+- storage_used_bytes     
+
+### Folder
+
+- id
+    
+- owner_user_id
+    
+- parent_folder_id (nullable for root)
+    
+- name
+    
+- full_path
+    
+- created_at
+    
+- updated_at
+    
+- deleted_at 
+    
+
+### FileItem (사용자 관점 파일 메타데이터)
+
+- id
+    
+- owner_user_id
+    
+- folder_id
+    
+- display_name
+    
+- mime_type
+    
+- size_bytes
+    
+- checksum_sha256 (선택)
+    
+- storage_key (LocalFS 실제 경로 키)
+	
+- metadata_json
+	
+- preview_status (NONE/PENDING/READY/FAILED)
+    
+- created_at
+    
+- updated_at
+    
+- deleted_at 
+    
+
+### UploadSession
+
+- id
+    
+- user_id
+	
+- token (public identifier)
+	
+- target_folder_id
+    
+- original_file_name
+    
+- expected_size
+    
+- received_size
+    
+- tus_upload_id
+    
+- status (CREATED/UPLOADING/COMPLETED/FAILED/ABORTED)
+    
+- temp_path_or_key
+    
+- created_at
+    
+- completed_at
+    
+
+### ShareLink
+
+- id
+    
+- file_id
+    
+- owner_user_id
+    
+- token (public identifier)
+    
+- password_hash (nullable)
+    
+- expires_at (nullable)
+    
+- is_active
+    
+- created_at
+    
+- last_accessed_at
+    
+- access_count
+    
+
+### AuditLog (간단 버전)
+
+- id
+    
+- actor_user_id (nullable for public share access)
+    
+- action_type (UPLOAD, DELETE, SHARE_CREATE...)
+    
+- target_type (FILE, FOLDER, SHARE_LINK)
+    
+- target_id
+    
+- metadata_json
+    
+- created_at
+    
+
+---
+
+## 9) 데이터 모델 정책 (중요한 구현 규칙)
+
+### 9-1. 폴더 중복 이름 정책 (권장)
+
+**초기엔 동일 부모 내 이름 중복 비허용**  
+(파일/폴더 각각 별도 정책 가능하지만, MVP에서는 단순화)
+
+### 9-2. 삭제 정책 (권장)
+
+- **MVP:** 소프트 삭제(`deleted_at`) + 실제 파일 즉시 삭제 or 지연삭제 중 택1
+    
+- 추천:
+    
+    - 메타데이터는 소프트 삭제
+        
+    - 실제 파일은 즉시 삭제 (MVP 단순)
+        
+    - 단, 장애 복구 필요하면 trash 디렉토리로 이동 후 배치 삭제
+        
+
+### 9-3. 파일명 정책
+
+- 저장 경로에 사용자 파일명 직접 사용 금지
+    
+- 표시용 이름은 DB에만 저장
+    
+- 위험 문자/길이 제한 검증
+    
+
+### 9-4. 권한 정책 (MVP)
+
+- 기본은 owner-only
+    
+- 공유 링크 접근은 `ShareLink` 검증 성공 시 다운로드 허용
+    
+- 폴더 공유는 MVP 제외
+    
+
+---
+
+## 10) API 설계 초안 (MVP)
+
+> REST 기준 초안. 실제 구현 시 `/api/v1` prefix 권장
+
+## 10-1. 인증
+
+- `POST /auth/register`
+    
+- `POST /auth/login`
+    
+- `POST /auth/logout`
+    
+- `GET /auth/me`
+    
+
+## 10-2. 폴더
+
+- `GET /folders/root` → 루트 폴더 정보
+    
+- `GET /folders/{folderId}/children` → 하위 폴더/파일 목록
+    
+- `POST /folders` → 폴더 생성
+    
+- `PATCH /folders/{folderId}` → 이름 변경 / 이동(부모 변경)
+    
+- `DELETE /folders/{folderId}` → 삭제
+    
+
+## 10-3. 파일 메타데이터
+
+- `GET /files/{fileId}` → 상세 조회
+    
+- `PATCH /files/{fileId}` → 이름 변경 / 폴더 이동
+    
+- `DELETE /files/{fileId}` → 삭제
+    
+
+## 10-4. 업로드 (tus 연동)
+
+- `POST /uploads/init` (선택) → 업로드 타겟 폴더/메타 사전 등록
+    
+- `/{tus-endpoint}` → tus 프로토콜 엔드포인트
+    
+- `POST /uploads/{uploadSessionId}/complete` (선택, tus 훅 기반이면 불필요)
+    
+
+> 구현 방식은 라이브러리(tusdotnet 등)에 따라 달라질 수 있음.  
+> 핵심은 **업로드 세션 → 최종 파일 메타 생성** 흐름 분리.
+
+## 10-5. 다운로드 / 미리보기
+
+- `GET /files/{fileId}/download`
+    
+- `GET /files/{fileId}/preview`
+    
+- `GET /share/{token}` → 공유 링크 메타(비밀번호 필요 여부 등)
+    
+- `POST /share/{token}/access` → 비밀번호 제출 후 다운로드 토큰 발급(선택)
+    
+- `GET /share/{token}/download`
+    
+
+## 10-6. 공유 링크 관리
+
+- `POST /files/{fileId}/share-links`
+    
+- `GET /files/{fileId}/share-links`
+    
+- `PATCH /share-links/{shareLinkId}`
+    
+- `DELETE /share-links/{shareLinkId}` (비활성화 처리)
+    
+
+---
+
+## 11) 업로드/다운로드 흐름 (개발 구현 기준)
+
+## 11-1. 업로드 흐름 (tus, MVP)
+
+1. 클라이언트가 업로드 대상 폴더 선택
+    
+2. 업로드 세션 생성 (`UploadSession`)
+    
+3. tus 업로드 시작 (청크 전송)
+    
+4. 업로드 완료 이벤트/콜백 수신
+    
+5. 서버가 임시 파일 검증
+    
+    - 파일 크기
+        
+    - MIME 추정
+        
+    - quota 확인
+        
+6. Local FS 최종 경로로 파일 이동
+    
+7. `FileItem` 생성
+    
+8. 미리보기 작업 큐 등록(또는 동기/비동기 처리)
+    
+9. 응답 반환, 목록 갱신
+    
+
+### 실패 처리
+
+- 완료 전 실패 → `UploadSession = FAILED`
+    
+- quota 초과 → 최종 확정 실패, 임시 파일 정리
+    
+- 중단 → 재개 가능 상태 유지
+    
+
+---
+
+## 11-2. 다운로드 흐름
+
+1. 인증 사용자 또는 공유 링크 접근
+    
+2. 파일 권한/공유 상태 검증
+    
+3. `storage_key` → Local FS 경로 resolve
+    
+4. 파일 스트림 응답 (Range 지원 권장)
+    
+5. 로그 기록 / 카운트 증가(공유 링크일 경우)
+    
+
+---
+
+## 11-3. 미리보기 흐름
+
+### 이미지
+
+- 원본 또는 썸네일 반환
+    
+- 썸네일 없으면 생성 후 캐시
+    
+
+### 텍스트
+
+- 크기 제한 내에서 UTF-8 등 디코딩 시도
+    
+- 너무 큰 파일은 일부만 미리보기
+    
+
+### PDF
+
+- 브라우저 내장 뷰어 활용 (`Content-Type: application/pdf`)
+    
+- 필요 시 인라인 응답
+    
+
+---
+
+## 12) 로컬FS 저장소 설계 (MVP 구체안)
+
+## 12-1. 저장소 인터페이스 (추상화)
+
+MVP가 로컬FS여도 인터페이스는 반드시 둔다.
+
+예시 (개념):
+
+- `SaveAsync(stream, metadata) -> storageKey`
+    
+- `OpenReadAsync(storageKey)`
+    
+- `DeleteAsync(storageKey)`
+    
+- `MoveTempToObjectAsync(tempKey, storageKey)`
+    
+- `ExistsAsync(storageKey)`
+    
+- `GetAbsolutePath(storageKey)` (LocalFS 구현 전용)
+    
+
+### 구현체
+
+- `LocalFileStorageService` (MVP)
+    
+- `S3ObjectStorageService` (추후)
+    
+
+---
+
+## 12-2. Local FS 저장 키 전략 (권장)
+
+`storage_key = {2자리}/{2자리}/{uuid}`
+
+예시:
+
+- `a3/f1/6f5c0a6e-...`
+    
+
+장점:
+
+- 디렉토리 당 파일 수 분산
+    
+- S3 키로 전환해도 재사용 가능
+    
+- 파일명/경로 공격 방지 쉬움
+    
+
+---
+
+## 13) 보안/검증 체크리스트 (MVP 필수)
+
+### 업로드
+
+- 허용 최대 크기 제한
+    
+- 파일명 길이 제한
+    
+- 위험 확장자 정책(차단/허용 리스트)
+    
+- MIME 타입은 클라이언트 값 신뢰하지 않기
+    
+- 경로 결합 시 Path Traversal 방지
+    
+
+### 공유 링크
+
+- 토큰은 추측 어려운 랜덤값
+    
+- 비밀번호 해시 저장
+    
+- 만료일 검증
+    
+- 비활성화 상태 검증
+    
+
+### 인증/인가
+
+- 모든 사용자 API는 소유권 검증 필수
+    
+- 파일 ID 기반 접근 시 owner 검증 누락 금지
+    
+- 예외 메시지에 내부 경로 노출 금지
+    
+
+---
+
+## 14) 로깅/모니터링 (초기 최소 기준)
+
+### 애플리케이션 로그
+
+- 인증 실패
+    
+- 업로드 시작/완료/실패
+    
+- 파일 삭제
+    
+- 공유 링크 생성/삭제
+    
+- 미리보기 생성 실패
+    
+
+### 운영 지표(나중에 Prometheus 가능)
+
+- 업로드 성공률
+    
+- 업로드 평균 처리시간
+    
+- 폴더 목록 조회 응답시간
+    
+- 미리보기 생성 성공률
+    
+- 저장 용량 사용량
+    
+
+---
+
+## 15) 테스트 전략 (개발용)
+
+## 15-1. 단위 테스트
+
+- 파일명/폴더명 검증 로직
+    
+- quota 계산/검사
+    
+- 공유 링크 만료/비밀번호 검증
+    
+- 권한 검사 로직
+    
+- storage key 생성 규칙
+    
+
+## 15-2. 통합 테스트
+
+- 회원가입/로그인 플로우
+    
+- 폴더 생성/조회
+    
+- 파일 업로드 완료 후 메타데이터 생성
+    
+- 다운로드 권한 검사
+    
+- 공유 링크 다운로드
+    
+- 삭제 후 목록 반영
+    
+
+## 15-3. 수동 E2E 시나리오 (MVP 검증)
+
+- 대용량 파일 업로드 중 네트워크 끊김 → 재개
+    
+- 이미지/PDF 미리보기 확인
+    
+- 공유 링크 만료 확인
+    
+- quota 초과 업로드 차단 확인
+    
+
+---
+
+## 16) 개발 우선순위 / 구현 순서 (권장)
+
+### Phase 1: 기반 구축
+
+1. 인증/회원
+    
+2. DB 스키마(User/Folder/FileItem)
+    
+3. 루트 폴더/목록 API
+    
+4. LocalFS 저장소 인터페이스 + 구현
+    
+
+### Phase 2: 핵심 파일 기능
+
+5. 파일 업로드(tus)
+    
+6. 업로드 완료 후 FileItem 확정
+    
+7. 다운로드 API
+    
+8. 파일/폴더 rename/move/delete
+    
+
+### Phase 3: 사용자 경험 강화
+
+9. 미리보기(이미지/텍스트/PDF)
+    
+10. 공유 링크 생성/다운로드
+    
+11. quota 집계/제한
+    
+12. 기본 로그/에러 메시지 정리
+    
+
+---
+
+## 17) MVP 완료 기준 (Definition of Done)
+
+다음 조건을 충족하면 MVP 개발 완료로 판단:
+
+- 사용자가 회원가입/로그인 가능
+    
+- 폴더 생성 및 파일 목록 탐색 가능
+    
+- 파일 업로드/다운로드 가능
+    
+- 네트워크 중단 후 업로드 재개 가능 (tus)
+    
+- 파일명 변경/이동/삭제 가능
+    
+- 이미지/텍스트/PDF 미리보기 가능
+    
+- 공유 링크 생성 및 외부 다운로드 가능
+    
+- 사용자별 저장 용량 제한이 동작함
+    
+- 주요 예외 상황에서 사용자 친화적 에러 응답 제공
+    
+- 기본 테스트(핵심 플로우) 통과
+    
+
+---
+
+## 18) 향후 확장 고려사항 (지금 설계에 반영만)
+
+MVP에서는 구현하지 않지만, 지금 구조에 흔적은 남겨두는 것이 좋음.
+
+- `IStorageService` 추상화 (S3/MinIO 전환 대비)
+    
+- `Workspace` 개념 확장 가능성 (개인공간 → 공유공간)
+    
+- WebDAV 엔드포인트 추가 가능한 라우팅 구조
+    
+- Background Job 구조 (미리보기/바이러스 스캔/외부 다운로드)
+    
+- 권한 모델 확장 (owner-only → role-based)
+    

기획/제안서.md

@@ -0,0 +1,369 @@
+# Cloud# 서비스 제안서
+
+## 목차
+
+1. 프로젝트 개요
+2. 문제 정의
+3. 해결 방향
+4. 핵심 가치 제안 및 차별점
+5. 타겟 사용자
+6. 기능 로드맵
+7. 기술 아키텍처
+8. 데이터 모델
+9. 비기능 요구사항
+10. 개발 일정
+11. 성공 지표 (KPI)
+12. 리스크 및 대응 전략
+13. 기대 효과
+---
+
+## 1. 프로젝트 개요
+
+|항목|내용|
+|---|---|
+|**서비스명**|Cloud#|
+|**한 줄 소개**|느린 웹 기반 파일 관리의 UX를 개선하고, S3 성능과 확장성을 갖춘 차세대 파일 호스팅 서비스|
+|**Backend**|ASP.NET Core|
+|**Frontend**|Blazor (Server 또는 WASM + API 조합 검토)|
+|**업로드 방식**|tus 프로토콜 (재개 가능한 대용량 업로드)|
+|**저장소**|S3 호환 Object Storage (MinIO / AWS S3 / Ceph RGW)|
+|**개발 방식**|단계별 로드맵 — MVP → 확장 기능 → 커뮤니티 플랫폼|
+
+---
+
+## 2. 문제 정의
+
+기존 파일 관리 솔루션은 두 가지 방향에서 한계를 드러냅니다.
+
+### 2.1 Nextcloud 계열의 한계
+
+- 웹 UI 전반의 **체감 반응성 저하** — 탐색, 공유 설정, 미리보기, 페이지 전환에서 답답함 발생
+- 구형 기술 스택 기반으로 **성능 최적화 및 유지보수 비용 증가**
+- 무거운 기능 구조로 인해 기본적인 파일 관리 경험조차 느리게 느껴짐
+
+### 2.2 S3 저장소의 한계
+
+- 성능과 안정성은 우수하나 **파일 관리 UX 기능 부족**
+- 폴더 구조, 공유 링크, 미리보기, 파일 정리 기능이 불친절하거나 부재
+- **비개발자/일반 사용자에게 높은 진입 장벽** 존재
+
+### 2.3 시장 공백
+
+```mermaid
+flowchart TB
+    A["Nextcloud<br/>기능은 풍부<br/>UX가 느림"]
+    B["S3 저장소<br/>성능은 우수<br/>UX가 불친절"]
+    C["Cloud#<br/>빠르고 · 쉽고 · 안정적"]
+
+    A --> C
+    B --> C
+```
+
+
+---
+
+## 3. 해결 방향
+
+**"Nextcloud의 기능성 + S3의 성능/확장성 + 현대적인 웹 UX"**
+
+|기능성|성능·확장성|현대적 UX|
+|---|---|---|
+|Nextcloud 수준의 파일 관리|S3/Object Storage 기반 인프라|Blazor + 빠른 API 응답|
+
+---
+
+## 4. 핵심 가치 제안 및 차별점
+
+### 4.1 핵심 가치 제안
+
+|가치|설명|
+|---|---|
+|⚡ **빠르다**|클릭·탐색·미리보기 반응 속도 개선|
+|🎯 **쉽다**|폴더·공유·정리 기능의 직관적 UX|
+|🔒 **안정적이다**|tus 기반 대용량 업로드 중단 후 재개 가능|
+|📈 **확장 가능하다**|S3 기반으로 저장소 교체·증설 용이|
+
+### 4.2 경쟁 서비스 대비 차별점
+
+|구분|Nextcloud|S3 직접 사용|**Cloud#**|
+|---|---|---|---|
+|UI 반응 속도|느림|제한적|**빠름 (최우선 목표)**|
+|대용량 업로드 안정성|보통|지원|**tus 기반 완전 지원**|
+|일반 사용자 친화성|보통|낮음|**높음 (직관적 UX)**|
+|저장소 확장성|제한적|우수|**우수 (S3 호환)**|
+|WebDAV 지원|지원|미지원|**2차 개발 예정**|
+|커뮤니티/협업 기능|제한적|미지원|**3차 개발 예정**|
+
+---
+
+## 5. 타겟 사용자
+
+### 5.1 1차 타겟
+
+- 개인 개발자 / 홈서버 운영자
+- 소규모 팀 (스터디, 프로젝트 팀, 동아리)
+- NAS/클라우드 대체 솔루션을 탐색 중인 사용자
+
+### 5.2 2차 타겟
+
+- 크리에이터/디자이너 — 파일 공유·미리보기 수요 높음
+- 내부 자료 공유가 필요한 팀/조직
+- WebDAV 기반 마운트를 원하는 파워유저
+
+### 5.3 사용자 니즈
+
+- 빠른 업로드·다운로드
+- 쉬운 폴더·파일 정리
+- 링크 공유 및 권한 제어
+- 브라우저에서의 미리보기
+- OS 탐색기에서 직접 접근 (WebDAV)
+
+---
+
+## 6. 기능 로드맵
+
+### Phase 1 — MVP (4~8주)
+
+> 목표: 실사용 가능한 최소 제품 완성
+
+**회원/인증**
+
+- 회원가입, 로그인/로그아웃
+- JWT + Refresh Token 인증
+- 비밀번호 재설정 (이메일 기반)
+
+**파일 관리**
+
+- 파일 업로드 — tus 기반, 재개 가능
+- 파일 다운로드 (Range 지원)
+- 폴더 생성·이동·이름 변경·삭제
+- 파일 이름 변경·이동·삭제
+- 파일 목록 조회 (정렬/검색 기본)
+- 휴지통 (소프트 삭제)
+
+**공유**
+
+- 공유 링크 생성
+- 만료일·비밀번호 설정
+- 읽기 전용 공유
+- 링크 비활성화
+
+**미리보기**
+
+- 이미지 미리보기
+- 텍스트/코드 파일 미리보기
+- PDF 미리보기 (브라우저 내장 뷰어)
+
+**관리자/운영**
+
+- 사용자별 저장 용량 제한 (Quota)
+- 파일 업로드 크기 제한
+- 관리자용 사용자·용량 현황 조회
+
+---
+
+### Phase 2 — 확장 기능 (3~6주)
+
+> 목표: 파워유저·운영자 사용성 강화
+
+**WebDAV 지원**
+
+- OS 탐색기/Finder에서 네트워크 드라이브처럼 접근
+- 사용자별 권한 반영
+- Windows/macOS 우선 지원
+
+**외부 다운로드/수집** 
+
+- URL 기반 파일 가져오기 (Remote Fetch)
+- 서버 측 다운로드 큐 처리 및 진행률 표시
+
+**고급 파일 관리**
+
+- 태그·즐겨찾기
+- 최근 파일
+- 버전 관리 (간단 버전)
+- 중복 파일 탐지 (해시 기반)
+
+**운영 기능**
+
+- 감사 로그 (업로드·삭제·공유 생성)
+- 관리자 권한 정책 (RBAC)
+- 알림 — 공유 링크 만료, 용량 초과 등
+
+---
+
+### Phase 3 — 커뮤니티 플랫폼 (추후)
+
+> 목표: 파일 공유 중심 커뮤니티 플랫폼으로 확장
+
+**공유 스페이스**
+
+- 주제/팀 단위 공간 생성
+- 공간별 권한 (관리자/멤버/읽기전용)
+- 공간별 저장소·용량 할당
+
+**커뮤니티/채팅**
+
+- 파일 중심 채팅·피드
+- 파일 업로드 후 즉시 공유·대화
+- 링크·미디어·문서 프리뷰
+- 파일·메시지 통합 검색
+
+**장기 확장**
+
+- 봇/자동화 업로드
+- 팀 워크플로우 연동
+- 실시간 협업 편집기 연동
+
+---
+
+## 7. 기술 아키텍처
+
+```mermaid
+flowchart TB
+    Client["클라이언트<br/>Blazor UI + tus client"]
+
+    API["API 서버<br/>ASP.NET Core — 인증/인가, 메타데이터,<br/>공유 링크, WebDAV(2차), 관리자 API"]
+
+    Upload["업로드 서비스<br/>tus 세션 관리<br/>청크 병합<br/>이벤트 발행"]
+
+    DB["메타데이터 DB<br/>PostgreSQL / MySQL<br/>사용자·폴더·파일·공유<br/>링크·감사로그 관리"]
+
+    Storage["S3 호환 Object Storage<br/>MinIO / AWS S3 / Ceph RGW<br/>파일 본문(binary) · 썸네일·미리보기 캐시"]
+
+    Worker["비동기 작업자 (선택)<br/>썸네일 생성 · 미리보기 변환<br/>바이러스 스캔 · 원격 URL 다운로드"]
+
+    Client --> API
+    API --> Upload
+    API --> DB
+    Upload --> Storage
+    Storage --> Worker
+```
+
+
+### 기술 선택 근거
+
+|기술|선택 이유|
+|---|---|
+|ASP.NET Core|높은 성능, WebDAV/S3 SDK 지원, 풍부한 생태계|
+|Blazor|C# 풀스택으로 컨텍스트 전환 최소화|
+|tus 프로토콜|표준화된 재개 가능 업로드 — 네트워크 중단에 강인|
+|S3 호환 저장소|MinIO(온프레미스)~AWS S3까지 교체 가능한 유연한 구조|
+
+---
+
+## 8. 데이터 모델
+
+|엔티티|설명|
+|---|---|
+|`User`|사용자 계정 — 인증 정보, 저장 용량 Quota|
+|`Workspace`|개인/공유 공간 단위|
+|`Folder`|폴더 메타데이터 — 계층 구조|
+|`FileItem`|파일 메타데이터 — 이름, 크기, MIME, 해시, S3 저장 키|
+|`FileVersion`|파일 버전 정보 (선택)|
+|`ShareLink`|공유 링크 — 만료일, 비밀번호, 권한|
+|`Permission`|사용자/공간/폴더 권한|
+|`UploadSession`|tus 업로드 상태 — 청크 진행률, 재개 정보|
+|`PreviewAsset`|썸네일·미리보기 캐시|
+|`AuditLog`|주요 이벤트 로그 — 업로드·삭제·공유 생성|
+
+---
+
+## 9. 비기능 요구사항
+
+### 9.1 성능
+
+- 목록 조회·폴더 이동 UI 빠른 응답 — **체감 속도 최우선**
+- 대용량 업로드 안정성 보장 (재개 가능)
+- 썸네일·미리보기 캐싱으로 반복 요청 최적화
+
+### 9.2 안정성
+
+- 업로드 중단·재시도 처리
+- 저장소 장애 대응 (재시도/에러 처리)
+- 파일 메타데이터와 저장 객체 정합성 검증 배치
+
+### 9.3 보안
+
+- JWT 인증/인가 분리
+- 공유 링크 권한·만료·비밀번호 보호
+- 악성 파일 업로드 대응 (백신 스캔 연계)
+- 감사 로그 / 접근 로그
+- HTTPS 전제
+
+### 9.4 확장성
+
+- 저장소 백엔드 교체 가능 (MinIO ↔ AWS S3 등)
+- 모듈형 설계 — WebDAV·커뮤니티 기능 추가 용이
+- API/도메인 분리로 수평 확장 대응
+
+---
+
+## 10. 개발 일정
+
+|단계|기간|주요 내용|
+|---|---|---|
+|**Phase 0** — 기획/설계|1~2주|요구사항 확정, IA/화면 흐름 설계, DB·저장소 구조 설계, PoC (tus + S3 + 미리보기)|
+|**Phase 1** — MVP|4~8주|인증/회원, 파일/폴더 CRUD, tus 업로드·다운로드, 공유 링크, 미리보기 기본|
+|**Phase 2** — 확장 기능|3~6주|WebDAV, URL 가져오기, 관리자 기능 강화, 감사 로그·알림|
+|**Phase 3** — 커뮤니티|추후 협의|공유 스페이스, 채팅·피드, 공간 권한·통합 검색|
+
+> 실제 일정은 인원수·숙련도·디자인 리소스에 따라 조정 필요
+
+### 개발 우선순위
+
+|우선순위|항목|
+|---|---|
+|**Must**|인증/회원, 파일/폴더 메타데이터, tus 업로드, 다운로드, 공유 링크, 이미지/PDF/텍스트 미리보기, Quota 설정|
+|**Should**|휴지통, 즐겨찾기/최근 파일, 관리자 대시보드, 썸네일 캐싱 고도화|
+|**Could**|WebDAV, URL 가져오기, 파일 버전 관리, 커뮤니티/채팅, 고급 검색/태그|
+
+---
+
+## 11. 성공 지표 (KPI)
+
+### MVP 단계
+
+|지표|설명|
+|---|---|
+|업로드 성공률|목표: 99%+|
+|업로드 재개 성공률|중단 후 재개 성공 비율|
+|파일 목록 조회 응답시간|목표: 200ms 이하|
+|미리보기 생성 성공률|이미지·PDF·텍스트 기준|
+|공유 링크 사용률|생성 대비 다운로드 전환율|
+|DAU/WAU|초기 사용자 활성도|
+
+### UX 중심
+
+|지표|설명|
+|---|---|
+|TTFU|첫 파일 업로드까지 걸리는 시간|
+|공유 링크 생성 클릭 수|생성까지 평균 클릭 수 최소화|
+|사용자 만족도|체감 속도·사용성 설문|
+
+---
+
+## 12. 리스크 및 대응 전략
+
+|리스크|원인|대응 전략|
+|---|---|---|
+|**빠른 UX 달성 실패**|서버 렌더링 지연, DB 쿼리 비효율|목록·탐색 API 최적화, 캐시 적용, 미리보기 비동기 생성, 성능 지표 관리|
+|**대용량 업로드 안정성**|네트워크 중단, 청크 정합성 문제|tus 채택, 업로드 세션 상태 관리, 재시도 정책·체크섬 검증|
+|**WebDAV 호환성**|OS별 클라이언트 동작 차이|2차 기능으로 분리, Windows/macOS 우선, 점진적 확장|
+|**저작권·불법 사용**|외부 다운로드 기능 악용 가능성|사용자 소유/허가 콘텐츠 한정, 이용약관 명시, 신고·차단·로그 정책 마련|
+
+---
+
+## 13. 기대 효과
+
+### 사용자 측면
+
+- 기존 솔루션 대비 **빠른 파일 관리 경험** 제공
+- 단순 저장소를 넘어선 **실사용 중심 파일 작업 공간**
+- 대용량 업로드·공유·미리보기의 편의성 향상
+
+### 개발·운영 측면
+
+- 현대 기술 스택 기반 **유지보수성 향상**
+- 저장소와 메타데이터 분리로 **확장성 확보**
+- 단계적 기능 확장 — 파일 호스팅 → 팀 공유 → 커뮤니티 플랫폼