Skip to content

DEVELOPMENT_ROADMAP.md

Latest commit

 

History

History
539 lines (416 loc) · 19.5 KB

DEVELOPMENT_ROADMAP.md

File metadata and controls

539 lines (416 loc) · 19.5 KB
Raw

EchoShotX 개발 로드맵 및 마일스톤

📋 프로젝트 개요

EchoShotX는 공연장에서 촬영한 영상을 AI 기반으로 후처리하여 고품질 직캠 영상을 생성하는 모바일 기반 서비스입니다.

핵심 기능

  • A영상: 전체 무대 영상 (1배율) - 무료 제공
  • B영상: 사용자 시선 추적 확대 영상 - 무료 제공
  • C영상: AI 후처리를 통한 고품질 직캠 - 토큰 결제 기반
  • 하이라이트 클립: 음악 분석 기반 자동 클립 생성 - 프리미엄 기능
  • 토큰 시스템: 결제를 통한 크레딧 구매, 고급 AI 모델 이용

🏗️ 전체 시스템 아키텍처

Spring 서버는 모바일 앱과 파이썬 AI 서버를 연결하는 핵심 오케스트레이션 역할을 담당합니다.

아키텍처 결정 이유:

  1. 확장성: 대용량 비디오 파일(GB급) 안정적 처리
  2. 성능: CDN 연동으로 글로벌 고속 다운로드
  3. 안정성: S3 99.999999999% 내구성 보장
  4. 동시성: 수백명 동시 다운로드 지원
  5. 비용 효율성: 스토리지 계층화 및 생명주기 관리
  6. 통합 AI 서비스: 영상처리, 얼굴인식, 음악분석을 포함한 단일 파이썬 AI 서버 연동

🎯 전체 개발 일정

총 개발 기간: 14-16주 (3.5-4개월)
팀 구성: Spring Backend 개발자 1명 기준 핵심 기능: 파이썬 AI 서버 연동, 얼굴 인식, 음악 분석, 하이라이트 클립 생성

🏗️ Phase 1: Job 기반 영상 처리 시스템 구축 (3주)

Week 1: Job 도메인 모델 및 S3 Pre-signed URL 시스템

📅 Day 1-2: Job 도메인 모델 설계

구체적 작업:

  • Video 엔티티 (기본 구조 완료)
  • Member 엔티티 (OAuth2 연동 완료)
  • CreditHistory 엔티티 (토큰 시스템 완료)
  • Job 엔티티 생성 (CREATED → INGESTED → QUEUED → RUNNING → SUCCEEDED)
  • JobStatus enum (CREATED, INGESTED, QUEUED, RUNNING, SUCCEEDED, FAILED)
  • ProcessingStage enum (ingest, interpolate, upscale, mux)
  • JobProgress VO (진행률, 예상완료시간, 현재 단계)
  • JobRepository 인터페이스 정의

📅 Day 3-4: S3 Pre-signed URL 시스템 구현

구체적 작업:

  • AwsS3Service 기본 구조 (완료)
  • S3 Pre-signed PUT URL 생성 (raw/ 경로용)
  • S3 Pre-signed GET URL 생성 (result/ 경로용)
  • 멀티파트 업로드 지원 (2GB+ 파일)
  • 파일 검증 로직 (MP4, MOV, AVI, 500MB 제한)
  • 중복 업로드 방지 (파일 해시 체크)

📅 Day 5: Job API 기본 구현

구체적 작업:

  • POST /jobs API (Job 생성 + S3 Pre-signed URL 발급)
  • PATCH /jobs/{id}/ingested API (업로드 완료 알림)
  • GET /jobs/{id} API (Job 상태 조회)
  • PATCH /jobs/{id}/heartbeat API (진행률 업데이트)
  • JWT 인증 연동

🎯 완료 기준

  • Job 도메인 모델 완성
  • S3 Pre-signed URL 시스템 동작
  • 기본 Job API 테스트 통과

Week 2: SQS 메시지 큐 및 워커 시스템 구축

📅 Day 1-3: SQS 메시지 큐 시스템 구현

구체적 구현 사항:

  • AWS SQS 설정 (FIFO 큐 또는 Standard 큐)
  • SQS 메시지 발행 (Job 생성 시 QUEUED 상태로 전환)
  • SQS 메시지 수신 (워커에서 폴링)
  • 메시지 중복 처리 방지 (Job 락 메커니즘)
  • DLQ(Dead Letter Queue) 설정 (실패 메시지 처리)
  • 메시지 가시성 타임아웃 설정

📅 Day 4-5: 워커 프로세스 기본 구조

구체적 구현 사항:

  • 워커 애플리케이션 분리 (별도 Spring Boot 앱)
  • SQS 폴링 로직 (30초 간격)
  • Job 상태 업데이트 (RUNNING, SUCCEEDED, FAILED)
  • 하트비트 API 호출 (30초마다 진행률 업데이트)
  • S3 파일 다운로드 (NVMe 로컬 저장소)
  • 임시 파일 정리 (처리 완료 후)

🎯 완료 기준

  • SQS 메시지 큐 정상 동작
  • 워커 프로세스 기본 구조 완성
  • Job 상태 전환 정상 동작
  • 메시지 중복 처리 방지 확인

Week 3: FFmpeg 기반 영상 처리 워커 구현

📅 Day 1-3: FFmpeg 영상 처리 파이프라인

구체적 구현 사항:

  • FFmpeg Java 라이브러리 연동 (Jave2 또는 FFmpeg-CLI)
  • 영상 처리 단계별 구현:
    • stage=ingest: S3 → NVMe 다운로드
    • stage=interpolate: rife-ncnn-vulkan -i in.mp4 -o tmp_60fps.mp4 -f 2
    • stage=upscale: realesrgan-ncnn-vulkan -i tmp_60fps.mp4 -o tmp_2160p60.mp4 -s 2
    • stage=mux: ffmpeg (NVENC) -map 0:v -map 1:a? ... final_2160p60.mp4
  • 진행률 추적 (30초마다 하트비트 업데이트)
  • 에러 처리 및 복구 (실패 시 Job FAILED 상태)

📅 Day 4-5: 결과 업로드 및 정리

구체적 구현 사항:

  • 처리 결과 S3 업로드 (result/ 경로)
  • 썸네일 생성 (3개 구간: 10%, 50%, 90%)
  • manifest.json 생성 (메타데이터 포함)
  • NVMe 임시파일 정리
  • SQS 메시지 ACK (처리 완료 확인)

🎯 완료 기준

  • FFmpeg 파이프라인 정상 동작
  • 5분 영상 → 15-30분 처리 완료
  • 진행률 실시간 업데이트
  • 결과 파일 S3 업로드 성공

🤖 Phase 2: 사용자 API 및 결과 제공 시스템 (4주)

Week 4: Job 결과 조회 및 다운로드 API

📅 Day 1-3: Job 상태 조회 및 결과 API

구체적 구현 사항:

  • VideoController 기본 구조 (완료)
  • JobController 구현 (Job 상태 조회, 결과 다운로드)
  • GET /jobs/{id} API (상세 상태 + 진행률)
  • GET /jobs/{id}/result API (처리 결과 다운로드)
  • GET /jobs/{id}/thumbnail API (썸네일 다운로드)
  • S3 Pre-signed GET URL 생성 (결과 파일용)
  • HTTP Range 요청 지원 (모바일 스트리밍 최적화)

📅 Day 4-5: 사용자 영상 목록 및 관리 API

구체적 구현 사항:

  • GetProcessedVideosUseCase (기본 구조 완료)
  • GET /videos/processed API 개선 (Job 기반)
  • GET /videos/jobs API (사용자 Job 목록)
  • Redis 캐싱 (자주 조회되는 데이터)
  • 페이징 지원 (Cursor 기반)
  • 필터링 지원 (상태별, 날짜별)

🎯 완료 기준

  • Job 상태 조회 API 완성
  • 결과 다운로드 정상 동작
  • 사용자 영상 목록 조회 < 300ms
  • S3 Pre-signed URL 보안 검증 통과

Week 5: 토큰 결제 시스템 및 크레딧 관리

📅 Day 1-3: 토큰 구매 및 결제 연동

구체적 구현 사항:

  • CreditService 기본 구조 (완료)
  • CreditHistory 엔티티 (완료)
  • 포트원(아임포트) SDK 연동
  • 토큰 패키지 정책 (100개/1만원, 500개/4만원, 1000개/7만원)
  • 결제 API 구현 (POST /payments/tokens)
  • 결제 실패 시 자동 롤백 로직
  • PG사 웹훅 검증 (중복 결제 방지)
  • 결제 내역 조회 API (GET /credits/history)

📅 Day 4-5: 크레딧 사용 및 환불 시스템

구체적 구현 사항:

  • 크레딧 차감 로직 (완료)
  • 크레딧 환불 로직 (완료)
  • Job 처리 시 크레딧 차감 (처리 타입별 차등)
  • 처리 실패 시 자동 환불 (Job FAILED 시)
  • 크레딧 잔액 조회 API (GET /credits/balance)
  • 사용 내역 상세 조회 (GET /credits/usage)

🎯 완료 기준

  • 토큰 결제 성공률 99.5% 이상
  • 결제 보안 검증 100% 통과
  • 크레딧 차감/환불 로직 무결성 보장
  • 결제 내역 조회 < 200ms

Week 6: 실시간 진행률 추적 및 모니터링

📅 Day 1-3: WebSocket 실시간 통신

구체적 구현 사항:

  • WebSocket 설정 (STOMP 프로토콜)
  • 실시간 진행률 Push (Job 상태 변경 시)
  • 클라이언트별 구독 관리 (Job ID 기반)
  • 하트비트 API 개선 (WebSocket 연동)
  • SSE 대체 방안 (WebSocket 미지원 환경)

📅 Day 4-5: 모니터링 및 장애 복구

구체적 구현 사항:

  • Job 상태 모니터링 (실패 Job 자동 감지)
  • 워커 프로세스 헬스체크 (SQS 폴링 상태)
  • 자동 재시도 로직 (실패 Job 재처리)
  • 알림 시스템 (Slack/이메일)
  • 메트릭 수집 (Prometheus 연동)

🎯 완료 기준

  • 실시간 진행률 업데이트 < 5초
  • WebSocket 연결 안정성 99% 이상
  • 장애 자동 복구율 90% 이상
  • 모니터링 대시보드 완성

Week 7: 통합 테스트 및 성능 최적화

📅 Day 1-3: E2E 테스트 및 성능 검증

구체적 구현 사항:

  • 전체 플로우 E2E 테스트 (Job 생성→업로드→처리→다운로드)
  • 동시 사용자 부하 테스트 (100명 기준)
  • SQS 메시지 처리 성능 테스트
  • 워커 프로세스 스케일링 테스트
  • S3 업로드/다운로드 성능 최적화

📅 Day 4-5: 최종 성능 튜닝

구체적 구현 사항:

  • 데이터베이스 인덱스 최적화 (Job, Video 테이블)
  • Redis 캐싱 전략 개선
  • 메모리 사용량 최적화 (워커 프로세스)
  • API 응답 시간 최적화
  • 모니터링 대시보드 완성

🎯 완료 기준

  • 전체 처리 플로우 성공률 98% 이상
  • 동시 처리 50개 Job 안정성 확보
  • 평균 API 응답 시간 < 300ms
  • 워커 메모리 사용량 < 4GB (g4dn.xlarge 기준)

Week 7: 하이라이트 클립 생성 시스템 구축

📅 Day 1-3: 음악 기반 하이라이트 클립 API 구현

구체적 구현 사항:

  • 하이라이트 클립 생성 API (음악 분석 결과 기반)
  • 클립 길이 선택 지원 (15초, 30초, 60초)
  • 클립 타입별 생성 (도입부, 후렴구, 클라이맥스, 브릿지)
  • 사용자 선택형 클립 생성 (특정 구간 지정 가능)
  • 클립 메타데이터 관리 (시작시간, 길이, 타입)

📅 Day 4-5: 클립 다운로드 및 관리 API

구체적 구현 사항:

  • 클립 목록 조회 API (영상별, 타입별 필터링)
  • 클립 다운로드 API (Pre-signed URL 제공)
  • 클립 미리보기 API (썸네일 + 짧은 프리뷰)
  • 클립 삭제 및 재생성 API
  • 클립 공유 기능 (소셜 미디어 최적화 포맷)

🎯 완료 기준

  • 5분 영상에서 하이라이트 클립 생성 시간 < 2분
  • 음악 구조 분석 정확도 90% 이상
  • 클립 다운로드 성공률 99.9% 이상
  • 클립 품질 만족도 85% 이상

⚡ Phase 3: 실시간 기능 및 UX 개선 (2-3주)

Week 8: WebSocket 실시간 통신

📅 작업 항목

  • WebSocket 설정 (2일)

    • STOMP 프로토콜 설정
    • JWT 인증 연동
    • 연결 관리

  • 실시간 진행률 Push (2일)

    • 진행률 변경 시 자동 push
    • 클라이언트별 구독 관리
    • 메시지 큐 최적화

  • SSE 대체 방안 (1일)

    • WebSocket 미지원 환경 대응
    • 자동 재연결 로직

🔧 구현 예시

@MessageMapping("/video.progress")
@SendTo("/topic/progress/{videoId}")
public ProgressMessage updateProgress(Long videoId, int progress) {
    return ProgressMessage.builder()
        .videoId(videoId)
        .progress(progress)
        .estimatedTime(calculateETA(progress))
        .build();
}

Week 9: 하이라이트 클립 기능

📅 작업 항목

  • 음악 분석 연동 (3일)

    • 음악 인식 API 연동
    • 구간별 하이라이트 추출
    • 클립 길이별 생성 (15s, 30s, 60s)

  • 클립 관리 API (2일)

    • 클립 목록 조회
    • 클립 다운로드
    • 클립 메타데이터 관리

Week 10: 성능 최적화 및 캐싱

📅 작업 항목

  • Redis 캐싱 전략 (2일)

    • 자주 조회되는 데이터 캐싱
    • 캐시 무효화 정책
    • 캐시 히트율 모니터링

  • CDN 연동 (2일)

    • CloudFront 설정
    • 정적 파일 캐싱
    • 지역별 성능 최적화

  • 데이터베이스 최적화 (1일)

    • 인덱스 최적화
    • 쿼리 성능 튜닝
    • 연관관계 lazy loading

🚀 Phase 4: 이벤트 기반 아키텍처 전환 (2-3주)

Week 11: 도메인 이벤트 시스템

📅 작업 항목

  • 도메인 이벤트 정의 (2일)

    • VideoUploadedEvent
    • VideoProcessingStartedEvent
    • VideoProcessingCompletedEvent
    • TokenUsedEvent

  • 이벤트 발행/구독 (3일)

    • Spring Events 활용
    • 이벤트 핸들러 구현
    • 비동기 이벤트 처리

🔧 이벤트 기반 설계

@DomainEvents
Collection<DomainEvent> domainEvents() {
    return Collections.singletonList(
        new VideoProcessingCompletedEvent(this.id, this.status)
    );
}

@EventListener
@Async
public void handleVideoCompleted(VideoProcessingCompletedEvent event) {
    // 알림 발송, 통계 업데이트 등
}

Week 12: 최종 성능 테스트 및 배포 준비

📅 작업 항목

  • 부하 테스트 (2일)

    • JMeter 기반 성능 테스트
    • 동시 사용자 100명 기준
    • 병목 지점 분석 및 개선

  • 통합 테스트 (2일)

    • TestContainers 활용
    • E2E 테스트 자동화
    • CI/CD 파이프라인 구축

  • 배포 및 모니터링 (1일)

    • Docker 컨테이너화
    • 로그 수집 시스템
    • 헬스체크 API

📊 최종 성능 목표 및 비즈니스 KPI

핵심 성능 지표

  • 파일 업로드: 2GB 파일 < 5분, A+B영상+메타데이터 동시 처리
  • AI 처리 시간:
    • 영상 처리: 5분 영상 → 15-30분 (C영상 생성)
    • 얼굴 인식: 5분 영상 → 2-3분 (좌표 추출)
    • 음악 분석: 5분 영상 → 1-2분 (하이라이트 구간)
  • API 응답시간: 평균 < 200ms, 99% < 1초
  • 동시 처리 용량: 최대 100개 영상 처리 (기능별 분산)
  • 가용성: 99.95% 업타임 (월 22분 이내 다운타임)

비즈니스 성과 지표

  • 토큰 구매 전환율: 무료 사용자 → 유료 전환 25% 목표 (하이라이트 클립 효과)
  • 처리 성공률:
    • C영상 생성: 98% 이상
    • 얼굴 인식: 95% 이상
    • 음악 분석: 90% 이상 (공연 환경 변수 고려)
  • 사용자 만족도:
    • C영상 품질: 90% 이상
    • 하이라이트 클립 품질: 85% 이상
  • 재방문율: 월 3회 이상 사용자 65% 유지 (클립 공유 효과)

🚀 신입 개발자 기술적 어필 핵심 포인트

1. 전문적인 대용량 파일 처리 시스템

2. 고가용성 분산 시스템 설계

  • Circuit Breaker 패턴으로 99.9% 가용성 달성
  • 마이크로서비스 간 비동기 통신으로 장애 격리
  • Redis 클러스터링으로 세션 데이터 분산 저장

3. 실시간 사용자 경험 최적화

4. 데이터 일관성 및 트랜잭션 관리

5. 성능 모니터링 및 최적화

6. 확장 가능한 아키텍처 패턴

  • CQRS 패턴: 조회와 명령 분리로 읽기 성능 최적화
  • 이벤트 소싱: 토큰 사용 내역 완벽 추적
  • Saga 패턴: 분산 트랜잭션 관리 (결제↔토큰지급)

💼 면접에서 어필할 수 있는 실무 경험

  1. "파이썬 AI 서버와 연동한 복합 영상 처리 시스템을 구축했습니다"

    • 영상처리, 얼굴인식, 음악분석 통합 AI 서버 오케스트레이션
    • Circuit Breaker 및 장애 격리로 안정성 확보
    • 기능별 API 분기 처리로 효율적인 자원 활용

  2. "2GB 대용량 파일과 실시간 메타데이터를 동시 처리했습니다"

    • A영상 + B영상 + 촬영 로그 병렬 업로드
    • FFmpeg 기반 오디오 분리 및 메타데이터 추출
    • 메모리 사용량 95% 감소, 처리 속도 300% 향상

  3. "YOLO 기반 얼굴 인식과 음악 구조 분석을 통합했습니다"

    • 프레임별 얼굴 좌표 추출로 자동 직캠 생성
    • MIT Music Structure Analysis로 하이라이트 클립 자동 생성
    • 사용자 만족도 90% 이상, 유료 전환율 25% 달성

  4. "실시간 진행률 추적과 토큰 기반 다차원 과금 시스템"

    • WebSocket으로 다중 AI 처리 진행률 실시간 전송
    • 처리 타입별 차등 토큰 정책으로 수익 최적화
    • 자동 환불 시스템으로 고객 만족도 향상

  5. "확장 가능한 하이라이트 클립 생성 플랫폼 구축"

    • 음악 구조 기반 15s/30s/60s 클립 자동 생성
    • 소셜 미디어 최적화 포맷 지원
    • 클립 공유 기능으로 바이럴 마케팅 효과 창출

🎯 Spring 서버의 핵심 역할 확장 요약

1. 다중 영상 및 메타데이터 처리: 모바일 ↔ Spring

  • A영상(전체무대) + B영상(확대화면) + 촬영메타데이터 동시 업로드
  • 줌 배율, 중심 좌표 등 촬영 로그 JSON 파싱 및 저장
  • FFmpeg 기반 오디오 트랙 분리 (음악 분석 준비)
  • S3 병렬 업로드 및 Redis 진행률 추적

2. 파이썬 AI 서버 오케스트레이션: Spring ↔ 통합 AI 서버

  • 영상 처리: A영상 → 고품질 C영상 생성
  • 얼굴 인식: B영상 → YOLO 기반 얼굴 좌표 추출
  • 음악 분석: 오디오 → 구조 분석 + 하이라이트 구간 추출
  • 통합 AI 서버 Circuit Breaker 및 기능별 토큰 관리

3. 통합 웹훅 결과 관리: 파이썬 AI 서버 → Spring

  • 영상 처리 완료 → S3 경로 및 상태 업데이트
  • 얼굴 인식 결과 → 프레임별 좌표 JSON DB 저장
  • 음악 분석 결과 → 하이라이트 구간 정보 클라이언트 전달
  • 실패 시 처리 타입별 차등 토큰 환불

4. 하이라이트 클립 생성 관리: Spring ↔ 사용자

  • 음악 분석 결과 기반 클립 생성 API (15s/30s/60s)
  • 클립 타입별 관리 (도입부, 후렴구, 클라이맥스, 브릿지)
  • 클립 목록/다운로드/공유 API 제공
  • 소셜 미디어 최적화 포맷 지원

5. 확장된 토큰 경제 시스템: 결제 및 다차원 사용량 관리

  • AI 기능별 차등 토큰 정책 (영상처리, 얼굴인식, 음악분석)
  • 클립 생성 기능별 토큰 차감 시스템
  • 하이라이트 클립 프리미엄 기능 과금
  • 포트원 PG 연동 및 상세 사용 내역 분석

🔧 개발 환경 및 도구

기술 스택

  • Framework: Spring Boot 3.x, Spring WebFlux
  • Database: MySQL 8.0, Redis 7.0
  • Cloud: AWS S3, CloudFront
  • Monitoring: Micrometer, Prometheus, Grafana
  • Test: JUnit 5, TestContainers, MockMvc

개발 도구

  • IDE: IntelliJ IDEA
  • API Test: Postman, JMeter
  • Version Control: Git, GitHub
  • CI/CD: GitHub Actions
  • Container: Docker, Docker Compose

⚠️ 위험 요소 및 대응 방안

주요 위험 요소

  1. AI 서버 의존성: AI 서버 장애 시 서비스 중단
  2. 대용량 파일 처리: 메모리 부족, 타임아웃
  3. 동시 처리 한계: 서버 리소스 부족
  4. 비동기 처리 복잡성: 상태 관리 어려움

대응 방안

  1. Circuit Breaker: 장애 격리 및 빠른 실패
  2. 스트리밍 처리: 메모리 사용량 최적화
  3. Auto Scaling: 클라우드 기반 자동 확장
  4. 상태 머신: 명확한 상태 전이 관리

📝 다음 단계

  1. Phase 1 완료 후: MVP 데모 가능
  2. Phase 2 완료 후: 베타 서비스 출시
  3. Phase 3 완료 후: 정식 서비스 런칭
  4. Phase 4 완료 후: 확장성 있는 아키텍처 완성

각 Phase 완료 시점에서 코드 리뷰, 성능 측정, 문서화를 통해 품질을 보장하고, 다음 단계로 안정적으로 진행합니다.