DataProc 주간 릴리즈 노트

엔터프라이즈 기능 강화 및 시스템 리팩토링 - 2025년 10월 26일 ~ 11월 1일

주요 개발 내용 요약

DataProc 프로젝트는 엔터프라이즈 수준의 기능 강화 및 대규모 시스템 리팩토링에 집중하였습니다. 10월 26일부터 11월 1일까지 총 30개의 커밋이 진행되었으며, 7개의 주요 PR이 병합되어 Refresh Token 인증 시스템, Kubernetes 배포 환경, 문서인식(Docling) 통합, 파일 관리 기능, 시스템 아키텍처 단순화가 완성되었습니다.

새로운 기능 (New Features)

1. Refresh Token 인증 메커니즘 (#47, #39)

• 구현 완료: JWT Refresh Token 기반 보안 강화 시스템
• Phase 1 - Backend 구현:
  • RefreshToken 모델 및 데이터베이스 테이블 추가
  • HttpOnly 쿠키를 통한 Refresh Token 전달
  • Token 해싱 및 만료 추적 시스템
  • Token rotation 지원으로 보안 강화
  • /auth/refresh, /auth/logout, /auth/logout-all 엔드포인트 추가
  • Access Token 만료 시간 단축 (8시간 → 1시간)
• Phase 2 - Frontend 통합:
  • AuthService 생성 (로그인, 토큰 갱신, 로그아웃 관리)
  • 자동 토큰 갱신 인터셉터 구현 (401 에러 시 자동 갱신 및 재시도)
  • Token deduplication으로 중복 갱신 요청 방지
  • credentials: ‘include’를 통한 HttpOnly 쿠키 지원
• 보안 개선사항:
  • XSS 공격 방지 (HttpOnly 쿠키)
  • CSRF 공격 방지 (Secure, SameSite 플래그)
  • 디바이스 추적을 통한 감사 추적
  • 토큰 회전으로 탈취 위험 최소화
• 주요 커밋: 2754c6c, 9ef020f, a21d708

2. Kubernetes 프로덕션 배포 구성 (#53, #52)

• 구현 완료: 엔터프라이즈급 컨테이너 오케스트레이션 환경
• Docker 최적화:
  • Backend 및 Frontend 멀티 스테이지 빌드 구현
  • 보안 베스트 프랙티스 적용 (non-root 사용자, 최소 레이어)
  • OCR 및 멀티모달 처리 종속성 추가 (Tesseract, Ghostscript, OpenCV)
  • 레거시 ChromaDB 제거, Milvus 전용 구성
• Kubernetes 매니페스트:
  • PostgreSQL StatefulSet (10Gi 영구 스토리지)
  • Milvus StatefulSet (20Gi 영구 스토리지)
  • Backend API Deployment (2 replica, health check, resource limit)
  • Frontend Web Deployment (2 replica, 최적화된 설정)
  • 모든 필요한 Service (ClusterIP, headless)
  • ConfigMap (비민감 설정) 및 Secret 템플릿 (민감 정보)
  • PersistentVolumeClaim (50Gi, ReadWriteMany, 공유 파일 업로드)
  • Ingress (NGINX annotations, CORS 지원)
  • Alembic Migration Job (자동 데이터베이스 스키마 관리)
• 프로덕션 기능:
  • Health check (liveness/readiness probe) 모든 컴포넌트 적용
  • Init container로 시작 순서 및 종속성 관리
  • Resource request/limit 정의로 안정성 확보
  • Rolling update 전략으로 무중단 배포
  • Horizontal Pod Autoscaling 지원
• 문서화:
  • 상세한 Kubernetes 배포 가이드 (docs/kubernetes-deployment.md)
  • 빠른 시작 가이드 (k8s/README.md, 한글 번역)
  • 배포 순서, 트러블슈팅, 롤백 절차, 스케일링 전략 포함
  • Kustomize base/ 디렉토리 구조 설명 (향후 dev/staging/production 오버레이 확장 가능)
• 주요 커밋: d44dc28, fa74185, 648a936, a37fd54, bbb66ec

3. 문서인식 (Docling) 통합 (#51, #50)

• 구현 완료: Docling 기반 문서 처리 실험 환경
• 주요 기능:
  • DocumentRecognitionFile 모델 및 데이터베이스 마이그레이션
  • Docling을 이용한 페이지별 추출 (텍스트, 마크다운, JSON 형식)
  • PDF 뷰어와 페이지별 Docling 추출 통합 (워크스페이스)
  • 사용자별 문서 관계 설정
  • DEBUG 로깅 레벨 설정으로 트러블슈팅 강화
• UI 변경:
  • ‘테스트’ 메뉴를 ‘문서인식’으로 명칭 변경
  • 워크스페이스 탭에 문서인식 통합
  • 독립된 /test 페이지에서 워크스페이스 탭으로 이동
• 개발 프로세스:
  • 프로덕션 코드와 완전히 격리된 실험 환경
  • test_files 디렉토리를 통한 별도 파일 저장
• 주요 커밋: 0d8f4df, 49eb4bd, f54b3e3, 806fa4d

4. 파일 삭제 기능 (#55, #54)

• 구현 완료: 문서인식 업로드 파일 삭제 관리
• 주요 기능:
  • DELETE 엔드포인트 (권한 확인 포함)
  • 데이터베이스 레코드 및 물리적 파일 동시 삭제
  • 각 업로드 파일에 삭제 버튼 UI 추가
  • 삭제 확인 대화상자로 실수 방지
  • 삭제 후 파일 목록 자동 업데이트
  • 선택된 파일 삭제 시 PDF 뷰어 클리어
• 주요 커밋: 613a4d4, 6c7c165

5. 고급 검색 옵션 ChatInterface 통합 (#46, #44)

• 구현 완료: Phase 3.2 고급 검색 기능 Admin 채팅 통합
• 주요 기능:
  • ChatInterface에 AdvancedSearchOptions 컴포넌트 통합
  • Phase 3.2 검색 파라미터 추가 (search_mode, min_image_relevance, max_images, image_type_filter, page_range)
  • include_paper_content를 include_project_content로 용어 통일
  • 프로젝트 선택 시에만 고급 옵션 표시
• Backend 개선:
  • ChatRequest 스키마 Phase 3.2 파라미터 추가
  • 프로젝트 접근 검증 단순화 (role-based 로직 제거)
• 주요 커밋: 149f6da, b1edbad

6. 이미지 갤러리 모달 (#49, #48)

• 구현 완료: 문서 검증 이미지 프리뷰 및 모달 갤러리
• 주요 기능:
  • 초기 이미지 표시 6개로 제한 (헤더 + 푸터)
  • 6개 초과 시 ‘View All Images’ 버튼 표시
  • 인라인 모달 갤러리로 모든 이미지 표시
  • 추가 API 호출 없이 기존 projectImages 데이터 활용
  • 반응형 2-4 컬럼 그리드 레이아웃 (모바일 → 데스크톱)
  • 워크스페이스 전용 모달로 인증 토큰 패턴 일관성 유지
• 주요 커밋: afff9c9, ac48668

주요 개선사항 (Improvements)

1. Alembic 마이그레이션 통합 및 단순화

• 단일 초기 마이그레이션 통합:
  • 10개 마이그레이션 파일을 1개 초기 스키마 마이그레이션으로 통합
  • 이전 마이그레이션은 versions_backup/ 디렉토리로 백업
  • 자동 관리자 계정 생성
  • INITIAL_ADMIN_EMAIL 및 INITIAL_ADMIN_PASSWORD 환경 변수로 설정 가능
• 유틸리티 스크립트 추가:
  • check_initial_user.py: 관리자 계정 생성 검증
  • drop_all_tables.py: 깨끗한 마이그레이션을 위한 데이터베이스 정리
  • reset_alembic_version.py: 마이그레이션 버전 테이블 재설정
• Alembic 전용 워크플로우:
  • schema_sync.py 자동 동기화 기능 제거
  • main.py 시작 시 스키마 동기화 로직 제거
  • start_server.sh에서 Alembic 마이그레이션 자동 실행
  • Alembic 전용 워크플로우 가이드라인 업데이트
  • database-migration-guide.md 종합 문서화 (한글 번역)
• 주요 커밋: feff40d, a3df819, 18bb030, c45f7bd

2. 역할 기반 접근 제어 시스템 제거 (RBAC 단순화)

• 사용자 역할 제거:
  • UserRole enum 및 User 모델 role 컬럼 제거
  • 로그인 상태만 확인하는 간단한 인증 (admin/user 구분 없음)
  • get_current_admin_user 종속성 제거
  • 로그인 API에서 is_admin 파라미터 및 JWT 토큰의 role 제거
• 라우터 단순화:
  • users 라우터 인증만 요구 (관리자 확인 제거)
  • 프로젝트 삭제 버그 수정 (UserRole 참조 제거)
• UI 변경:
  • Admin 대시보드 프로젝트 탭 우선 표시
  • 사용자 관리 메뉴를 하단으로 이동
  • 사용자 생성/편집 모달에서 role 필드 제거
  • 사용자 관리 테이블에서 role 컬럼 제거
  • /admin → /settings, /dashboard → /workspace 라우트 변경
  • “관리자” → “설정”, “사용자 계정”으로 레이블 변경
• Alembic 마이그레이션: users 테이블에서 role 컬럼 제거
• 모든 인증된 사용자가 플랫폼 기능에 동등한 접근 권한 보유
• 주요 커밋: 97d028e, 2ac8bbd, a034c8b, 9515aa2

3. 레거시 코드 정리 및 아키텍처 단순화

• ChromaDB 제거, Milvus 전용:
  • ChromaDB 레거시 지원 및 팩토리 패턴 추상화 제거
  • vector_store.py (ChromaDB 구현) 제거
  • vector_store_factory.py Milvus 직접 사용으로 단순화
  • vector_config.py ChromaDB 설정 제거
  • .env.example VECTOR_DB_TYPE 및 ChromaDB 설정 제거
• SQLite 참조 제거, PostgreSQL 전용:
  • 데이터베이스 연결에서 SQLite 폴백 로직 제거
  • consistency_checker ChromaDB/SQLite → Milvus/PostgreSQL 문서화 업데이트
  • run_server.py 메시지 SQLite → PostgreSQL (Docker) 변경
• Pydantic 스키마 분리 및 중앙화:
  • 라우터 내 인라인 스키마를 app/schemas/ 디렉토리로 추출
  • 중앙화된 스키마 모듈 생성: user, auth, project, file, llm_config, embedding_config, common
  • 재사용 가능한 PaginatedResponse 제네릭 타입 추가
  • 중복 스키마 정의 제거 (예: UserResponse가 auth 및 users 라우터에 각각 정의)
  • 스키마 재사용 및 일관된 API 응답으로 유지보수성 향상
• 기타 레거시 제거:
  • /paper 라우트 및 백업 파일 제거
  • Template 기능 제거 (templateService, 관련 컴포넌트)
  • init_db.py, debug_files.py, schema SQL 덤프 파일 제거
  • .specify 자동화 스크립트 제거
  • user_example.py (구형 role 참조) 제거
• 주요 커밋: e1ed787, 6ac07dd, a5f7f21, 8033b91, 68a0531, 3e96755, 828b011, c597ddf, e0751a1

4. PDF ArrayBuffer Detached 오류 수정

• 문제: PDF 전환 시 ArrayBuffer detached 오류 발생
• 해결책:
  • URL 변경 시 이전 PDF 데이터 클리어
  • 진행 중인 PDF 로드에 대한 취소 메커니즘 추가
  • 더 나은 메모리 관리를 위해 ArrayBuffer → Uint8Array 변환
  • pdfUrl 종속성을 포함하도록 memoization 업데이트
  • 문서가 완전히 로드된 경우에만 PDF Page 렌더링
• 주요 커밋: 9531e31

5. 프로젝트 리브랜딩 및 명명 일관성

• 리브랜딩 작업:
  • 레거시 자동화 스크립트 및 .specify 디렉토리 제거
  • 프로젝트 규칙 설정 파일 업데이트
  • 모든 문서 파일에 걸쳐 일관된 브랜딩 적용
  • 데이터베이스 설정 및 연결 문자열 업데이트
  • 제품 소개 문서 이름 변경
• 문서화 개선:
  • 한글 GitHub 이슈 및 PR 요구사항 추가
  • 제품 브로셔 v0.4.0 Vision Search 통합 반영
  • README v0.5.0 릴리즈 업데이트 (엔터프라이즈 기능, K8s 배포, 문서인식 통합)
  • Alembic 마이그레이션 문서화 업데이트
• 주요 커밋: 0a37b61, 89cce75, 35cab65, a545e76, 4f7136a

6. 의존성 관리 개선

• requirements.txt 최적화:
  • 재현 가능한 빌드를 위해 모든 패키지 버전 == 핀 고정
  • 중복 sentence-transformers 항목 제거
  • 주석으로 카테고리별 패키지 정리
  • 직접 종속성만으로 축소 (58 → 30 패키지)
• 주요 커밋: 0321e04

버그 수정 (Bug Fixes)

1. Frontend 사용자 목록 API 스키마 정렬

• 문제: Frontend가 ‘users’ 필드를 기대했지만 Backend는 PaginatedResponse에서 ‘items’ 필드 반환
• 해결: UsersResponse 인터페이스 및 응답 처리를 ‘items’ 필드 사용으로 업데이트하여 Backend API 스키마와 일치
• 주요 커밋: ca9c98e

2. Test 페이지 API 및 인터페이스 수정

• 문제: API_URL 상수 미사용, UploadedFile 인터페이스 오류, 데이터베이스 import 경로 오류
• 해결: API_URL 상수 사용, UploadedFile 인터페이스 수정, 올바른 데이터베이스 import 경로 적용
• 주요 커밋: b7c76c4, a973c32

성과 지표 (Metrics)

• 총 커밋 수: 30개 커밋 (10/26 ~ 11/1)
• 병합된 PR: 7개 주요 풀 리퀘스트 (#47, #46, #49, #51, #53, #55, 기타)
• 새로운 기능: 6개 주요 기능 (Refresh Token, K8s 배포, 문서인식, 파일 삭제, 이미지 갤러리, 고급 검색)
• 주요 개선사항: 6개 시스템 최적화 (Alembic 통합, RBAC 단순화, 레거시 정리, 버그 수정, 리브랜딩, 의존성 관리)
• 문서화: 5개 주요 문서 작성 및 개선 (K8s 배포 가이드, Alembic 가이드, README, 제품 브로셔)
• 코드 정리: 15개 이상의 레거시 파일 및 기능 제거

주요 PR 목록

• #55: 문서인식: 업로드된 파일 삭제 기능 추가
• #53: Kubernetes 배포 설정 추가
• #51: 문서인식(Docling) 통합
• #49: 문서 검증 이미지 갤러리 모달 추가
• #47: Refresh Token 메커니즘 구현 (Phase 1 & 2)
• #46: ChatInterface에 Phase 3.2 고급 검색 옵션 추가

핵심 개선 영역

• 엔터프라이즈 준비: Kubernetes 프로덕션 배포, Refresh Token 보안, 파일 관리
• 시스템 단순화: RBAC 제거, ChromaDB/SQLite 제거, Alembic 전용 워크플로우
• 코드 품질: Pydantic 스키마 중앙화, 레거시 코드 정리, 의존성 최적화
• 문서인식: Docling 통합으로 실험적 문서 처리 기능 강화
• 사용자 경험: 파일 삭제, 이미지 갤러리, PDF 오류 수정

향후 계획 (Future Plans)

1. Docling 통합 고도화

• 전체 문서 자동 페이지 추출 및 색인
• Docling 추출 결과를 RAG 시스템에 통합
• 다양한 문서 형식 지원 확대 (DOCX, PPTX, XLSX)
• 성능 최적화 및 대용량 문서 처리

2. Kubernetes 프로덕션 운영

• Monitoring 및 Logging 시스템 구축 (Prometheus, Grafana, ELK)
• Horizontal Pod Autoscaler 설정 및 튜닝
• CI/CD 파이프라인 구축 (GitLab CI, ArgoCD)
• 백업 및 재해 복구 전략 구현
• Dev/Staging/Production 환경 분리 (Kustomize overlays)

3. 보안 강화

• Token 블랙리스트 시스템 구현
• Rate limiting 및 IP 기반 접근 제어
• API Gateway 도입 (Kong, Ambassador)
• 감사 로그 시스템 구축

4. 성능 최적화

• Redis 캐싱 레이어 도입
• 데이터베이스 쿼리 최적화 및 인덱싱
• Milvus 쿼리 성능 튜닝
• CDN 통합 (정적 파일 및 이미지)

5. 기능 확장

• 다중 프로젝트 간 검색 및 분석
• 사용자 협업 기능 (프로젝트 공유, 댓글)
• 고급 보고서 생성 및 내보내기
• API 사용 통계 및 모니터링 대시보드

결론

DataProc 프로젝트는 이번 주 엔터프라이즈 기능 강화 및 대규모 시스템 리팩토링을 통해 프로덕션 배포 준비 상태를 완성하였습니다. Kubernetes 배포 환경 구축, Refresh Token 보안 강화, 문서인식(Docling) 통합, 파일 관리 기능, 시스템 아키텍처 단순화를 통해 더욱 강력하고 유지보수 가능한 플랫폼으로 발전하였습니다.

특히 Kubernetes 프로덕션 배포 구성은 엔터프라이즈 수준의 가용성, 확장성, 보안을 제공하며, Refresh Token 메커니즘은 사용자 경험과 보안을 동시에 개선하였습니다. RBAC 제거 및 Alembic 전용 워크플로우를 통한 시스템 단순화는 개발 속도를 높이고 유지보수 부담을 줄였습니다.

또한 Docling 통합을 통해 실험적 문서 처리 기능을 강화하고, 레거시 코드 대대적 정리를 통해 코드 품질과 일관성을 크게 향상시켰습니다.

앞으로 Kubernetes 프로덕션 운영, Docling 고도화, 보안 강화, 성능 최적화를 통해 더욱 강력하고 안정적인 엔터프라이즈급 문서 분석 플랫폼으로 발전할 예정입니다.

문서 작성일: 2025년 11월 2일 버전: v0.5.0 - Enterprise Features & System Refactoring