cloud-sharp-docs/기획/기획서.md at 52aebed5d7fc47026bded2667be1f30638cd069a

son/cloud-sharp-docs

Fork 0

Files

son 52aebed5d7 first

2026-03-16 16:17:17 +09:00

18 KiB

Raw Blame History

버전: 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. 디렉토리 구조 예시

/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)

클라이언트가 업로드 대상 폴더 선택
업로드 세션 생성 (UploadSession)
tus 업로드 시작 (청크 전송)
업로드 완료 이벤트/콜백 수신
서버가 임시 파일 검증
- 파일 크기
- MIME 추정
- quota 확인
Local FS 최종 경로로 파일 이동
FileItem 생성
미리보기 작업 큐 등록(또는 동기/비동기 처리)
응답 반환, 목록 갱신

실패 처리

완료 전 실패 → UploadSession = FAILED
quota 초과 → 최종 확정 실패, 임시 파일 정리
중단 → 재개 가능 상태 유지

11-2. 다운로드 흐름

인증 사용자 또는 공유 링크 접근
파일 권한/공유 상태 검증
storage_key → Local FS 경로 resolve
파일 스트림 응답 (Range 지원 권장)
로그 기록 / 카운트 증가(공유 링크일 경우)

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: 기반 구축

인증/회원
DB 스키마(User/Folder/FileItem)
루트 폴더/목록 API
LocalFS 저장소 인터페이스 + 구현

Phase 2: 핵심 파일 기능

파일 업로드(tus)
업로드 완료 후 FileItem 확정
다운로드 API
파일/폴더 rename/move/delete

Phase 3: 사용자 경험 강화

미리보기(이미지/텍스트/PDF)
공유 링크 생성/다운로드
quota 집계/제한
기본 로그/에러 메시지 정리

17) MVP 완료 기준 (Definition of Done)

다음 조건을 충족하면 MVP 개발 완료로 판단:

사용자가 회원가입/로그인 가능
폴더 생성 및 파일 목록 탐색 가능
파일 업로드/다운로드 가능
네트워크 중단 후 업로드 재개 가능 (tus)
파일명 변경/이동/삭제 가능
이미지/텍스트/PDF 미리보기 가능
공유 링크 생성 및 외부 다운로드 가능
사용자별 저장 용량 제한이 동작함
주요 예외 상황에서 사용자 친화적 에러 응답 제공
기본 테스트(핵심 플로우) 통과

18) 향후 확장 고려사항 (지금 설계에 반영만)

MVP에서는 구현하지 않지만, 지금 구조에 흔적은 남겨두는 것이 좋음.

IStorageService 추상화 (S3/MinIO 전환 대비)
Workspace 개념 확장 가능성 (개인공간 → 공유공간)
WebDAV 엔드포인트 추가 가능한 라우팅 구조
Background Job 구조 (미리보기/바이러스 스캔/외부 다운로드)
권한 모델 확장 (owner-only → role-based)

18 KiB Raw Blame History