DataProc 주간 릴리즈 노트

버전관리 시스템 - 2025년 11월 16일 ~ 11월 29일

요약

이번 주간(2025년 11월 16일 ~ 11월 29일) dataproc 프로젝트는 데이터셋 버전 관리 시스템의 핵심 기능을 완성하는 데 집중했습니다. 6개의 Pull Request가 병합되었으며, 12개의 이슈가 처리되었습니다. 특히 버전 스냅샷 시스템 재구현, 파일 관리 UX 개선, 그리고 새로운 벤치마크 기능 설계가 주요 성과입니다.

주요 성과

1. 버전 스냅샷 시스템 완전 재구현 (#98, #99)

문제: 기존 버전 생성 시 새로운 파일만 포함되어 이전 버전의 파일이 유실되는 심각한 설계 결함 발견

해결책:

• Git/DVC와 유사한 완전 스냅샷(Full Snapshot) 방식 구현
• 각 버전이 해당 시점의 전체 데이터셋 상태를 보존
• Hard link를 활용한 저장 공간 최적화
• source_file_id 필드 추가로 파일 계보(lineage) 추적
• 버전 미리보기 API 제공 (생성 전 완전한 파일 목록 확인)

영향: 데이터 손실 방지 및 버전 관리 신뢰성 대폭 향상

2. 파일 관리 UX 대폭 개선 (#99)

구현 내용:

• 파일 상태 시각화: Staging 파일과 활성 버전 파일을 명확히 구분
  • 활성 버전 파일: 파란색 ‘활성 버전’ 배지
  • Staging 파일: 노란색 ‘STAGED’ 배지 및 배경
• 파일 그룹핑: 같은 파일명의 여러 버전을 그룹화하여 표시
  • 수정된 파일: “STAGED (수정됨)” 표시 및 들여쓰기
  • 새 파일: “STAGED (새 파일)” 표시
• 실시간 업데이트: 파일 업로드/삭제/버전 생성 시 자동 갱신

3. 버전 관리 핵심 기능 추가

3.1 파일 다운로드 기능 (#93, #100)

• 개별 파일 다운로드: 각 파일의 원본 파일명 및 MIME 타입 보존
• 버전 전체 다운로드: ZIP 파일로 전체 버전을 한 번에 다운로드
• Path traversal 공격 방어 및 인증 검증 포함

3.2 버전 메타데이터 관리 (#94, #101)

• 버전 이름 지정: 의미 있는 이름 부여 (예: “초기 원본 데이터”)
• 태그 시스템: 다중 태그로 버전 분류 및 검색 지원
• 인라인 편집: 버전 타임라인에서 직접 메타데이터 수정 가능

3.3 버전 롤백 워크플로우 (#95, #102)

• Git-style Revert 방식 채택
• 이전 버전의 파일로 새 버전(v{N+1}) 생성
• 모든 히스토리 보존 (감사 추적 유지)
• Hard link 최적화로 효율적인 저장소 관리
• 확인 모달에서 파일 미리보기 제공

4. Staging Area 파일 검증 시스템 (#96, #104)

Phase 1: 파일 미리보기

• 지원 형식: 텍스트, CSV, JSON, 이미지
• 보안 기능: 10MB 파일 크기 제한, path traversal 방어
• 사용자 경험: 모달 UI, 타입별 렌더링

Phase 2: 파일 검증

• CSV/TSV 검증:
  • 빈 컬럼 및 높은 빈 셀 비율 감지
  • 중복 행 탐지
  • 필수 컬럼 확인
  • 혼합 데이터 타입 감지
• JSON 검증:
  • 중첩 깊이 계산
  • 필수 키 확인
  • 구조 검증
• 텍스트 파일 검증:
  • 인코딩 검증
  • 라인 길이 확인
• UI 통합: 색상 코드화된 검증 결과 (녹색: 통과, 빨간색: 오류, 노란색: 경고)

5. 버전 불변성 정책 및 파일 제외 기능 (#97, #105)

정책 수립

• 불변성 원칙: 커밋된 버전의 파일은 직접 삭제 불가
• CLAUDE.md에 정책 문서화: 개발 가이드라인으로 명문화

파일 제외 기능

• 백엔드: create_version_excluding_files 서비스 메서드 구현
• 프론트엔드:
  • 체크박스로 제외할 파일 선택
  • ExcludeFilesModal로 미리보기 및 메타데이터 입력
  • 제외/포함 파일 목록 및 크기 요약 표시
• 검증: 최소 1개 파일 보장, 유효한 파일 ID 확인
• 최적화: Hard link로 공간 효율성 유지

버그 수정

데이터 동기화 문제

• 버전 생성 후 파일 목록 미갱신 (#105)
• Staged 파일 삭제 후 파일 관리 탭 미업데이트 (#105)
• 파일 제외 버전 생성 후 버전 목록 미갱신 (#105)

API 인터페이스 불일치

• 버전 비교 API가 path parameter 대신 query parameter 사용 (#90)
• 버전 비교 응답에 stats 필드 누락 (#91)
• 프론트엔드가 version_number 대신 version_id 필요 (#90)

파일 필터링 문제

• 파일 목록에 staged 및 모든 버전 파일이 중복 표시 (#99)
• TSV 파일 미리보기 미지원 (#96, #104)

통계

• Pull Requests: 6개 병합
  • [#105] - 버전 불변성 정책 명확화 및 파일 제외 기능 구현
  • [#104] - Staging Area 파일 미리보기 및 검증 기능 구현 (Phase 1, 2)
  • [#102] - 명시적인 버전 롤백 워크플로우 구현 (Option 1: Revert)
  • [#101] - 데이터셋 버전에 이름/태그 지정 기능 추가
  • [#100] - 데이터셋 버전별 파일 다운로드 기능 추가
  • [#99] - 데이터셋 버전 스냅샷 시스템 완전 재구현
• Issues: 12개 완료
  • 완료: #90, #91, #92, #93, #94, #95, #96, #97, #98
  • 신규 생성 (진행 중): #103, #106~#112
• Commits: 27개 커밋
  • 기능 추가 (feat): 11개
  • 버그 수정 (fix): 16개

향후 계획

Phase 3: Staging Area 통계 및 인사이트 (#103)

파일 통계 정보 및 데이터 품질 인사이트 제공 예정

Epic: 임베딩 모델 벤치마크 기능 (#106~#112)

대규모 벤치마크 시스템 구축 착수:

• Phase 1: 벤치마크 Core Infrastructure (#107)
• Phase 2: Retrieval Benchmark (#108)
• Phase 3: 벤치마크 UI Integration (#109)
• Phase 4: Classification, Clustering, Similarity Benchmark (#110, #111, #112)

기술적 하이라이트

1. Hard Link 최적화

파일 복제 시 실제 데이터 복사 없이 inode 참조만 증가시켜 저장 공간 절약

2. 파일 계보 추적

source_file_id를 통해 파일의 원본 및 변경 이력 추적 가능

3. 보안 강화

• Path traversal 공격 방어
• 파일 크기 제한
• 사용자 권한 검증

4. UX 중심 설계

• 실시간 UI 업데이트
• 명확한 시각적 피드백
• 한국어 로컬라이제이션

결론

이번 주간은 dataproc의 버전 관리 시스템이 프로덕션 수준으로 성숙한 전환점이었습니다. 심각한 데이터 손실 버그를 발견하고 즉시 해결했으며, 사용자가 데이터셋을 안전하고 효율적으로 관리할 수 있는 완전한 워크플로우를 구축했습니다.

특히 Git과 DVC의 검증된 버전 관리 원칙을 적용하여 시스템의 신뢰성을 크게 향상시켰으며, 향후 임베딩 모델 벤치마크 기능으로 확장할 수 있는 견고한 기반을 마련했습니다.

문서 작성일: 2025년 11월 29일
버전: v0.7.0 - 버전관리 시스템