DataProc 주간 릴리즈 노트

시스템 안정화 및 인증 개선 - 2025년 10월 5일 ~ 10월 18일

주요 개발 내용 요약

DataProc 프로젝트는 시스템 안정화 및 사용자 경험 개선에 집중하였습니다. 10월 5일부터 10월 18일까지 총 14개의 커밋이 진행되었으며, 3개의 주요 PR이 병합되어 외래 키 제약 조건 버그 수정, 벡터 DB 스키마 마이그레이션, JWT 인증 강화가 완성되었습니다.

새로운 기능 (New Features)

1. 자동 로그아웃 및 토큰 만료 처리 시스템 (#38)

• 구현 완료: JWT 토큰 만료 시 자동 로그아웃 기능
• 주요 기능:
  • 중앙 집중식 401 에러 핸들러 구현 (authUtils.ts)
  • 모든 서비스에서 일관된 401 에러 처리
  • 토큰 만료 시 자동 로그아웃 및 로그인 페이지 리다이렉트
  • JWT 토큰 유효 기간 연장 (30분 → 8시간)
• 주요 커밋: b122389

개선사항 (Improvements)

1. JWT 토큰 관리 강화

• ACCESS_TOKEN_EXPIRE_MINUTES 연장: 30분 → 480분 (8시간)으로 변경
• 사용자 경험 개선: 더 긴 세션 유지로 재로그인 빈도 감소
• 주요 커밋: b122389

2. 프로젝트 생성 UI 간소화 (#30)

• 불필요한 필드 제거: 프로젝트 생성 시 user_id 선택 필드 제거
• 백엔드 자동 처리: JWT 인증 기반으로 user_id 자동 할당
• 주요 변경사항:
  • ProjectCreateModal에서 user_id 필드 제거
  • adminProjectService에서 user_id 파라미터 제거
  • 사용자 혼란 방지 및 UI 단순화
• 주요 커밋: 944ebf6

3. 벡터 데이터베이스 스키마 마이그레이션 (#28)

• topic_id → project_id 변경: Milvus 컬렉션 스키마 업데이트
• 일관성 확보: 전체 시스템에서 project 용어 통일
• 주요 변경사항:
  • Milvus FieldSchema에서 project_id 사용
  • 쿼리 및 필터 로직 전면 업데이트
  • embedding_service.py 주석 명확화
• 주요 커밋: 4667e52, 6e558ef

4. Git 워크플로우 개선

• 커밋 메시지 표준화: Conventional Commit 형식 강제
• 자동 서명 시스템: git commit –signoff 필수 적용
• 주요 변경사항:
  • git commit-msg 훅 추가 (자동 검증)
• 주요 커밋: 3adb478, 7fedde1

버그 수정 (Bug Fixes)

1. 프로젝트 삭제 시 외래 키 제약 조건 오류 수정 (#26)

• 문제: project_images 테이블의 외래 키 제약으로 프로젝트 삭제 실패
• 해결: 프로젝트 삭제 전 project_images 레코드 먼저 삭제
• 주요 변경사항:
  • ProjectImage 모델 import 추가
  • 파일 시스템에서 이미지 파일 삭제
  • 올바른 삭제 순서 확립: images → files → project
  • images_deleted/images_failed 카운터 추가
• 주요 커밋: 3859092

2. 벡터 DB 삭제 시 변수명 오류 수정 (#28)

• 문제: delete_project_embeddings에서 topic_id 참조로 NameError 발생
• 해결: topic_id를 project_id로 변경
• 주요 변경사항:
  • line 883: “topic_id” → “project_id”
  • line 898: 에러 핸들러에서도 동일 수정
  • Topic → Project 마이그레이션 완료
• 주요 커밋: 6e558ef

3. 프론트엔드 서비스 401 에러 처리 통일

• 문제: 서비스별로 일관성 없는 401 에러 처리
• 해결: 중앙 집중식 authUtils.handle401Error 적용
• 적용된 서비스:
  • adminProjectService.ts
  • chatService.ts
  • embeddingConfigService.ts
  • imageService.ts
  • llmConfigService.ts
  • userService.ts
• 주요 커밋: b122389

문서화 (Documentation)

1. Chunker 선택 메커니즘 분석 문서

• 완전한 기술 분석: 문서 타입별 chunker 선택 로직 상세 설명
• 주요 내용:
  • 3단계 프로세스: 문서 타입 감지 → 전략 매핑 → chunker 인스턴스화
  • if-elif-else 분기 로직 상세 분석
  • 한국 규제 문서 처리 예제
  • SemanticChunker, SentenceChunker, RecursiveChunker 비교 분석
  • 성능 메트릭 및 최적화 권장사항
• 파일: research/document-processing/05-chunker-selection-analysis.md
• 분량: 1,231 라인
• 주요 커밋: baa7b58

2. 텍스트-이미지 매칭 아키텍처 문서

• 멀티모달 임베딩 시스템 문서화: CLIP 기반 텍스트-이미지 매칭 구조
• 주요 내용:
  • CLIP 기반 멀티모달 임베딩 아키텍처
  • RAG 시스템과 이미지 검색 통합
  • PDF 추출 제한사항: 임베딩 자동 생성 안 됨
  • 직접 업로드 vs PDF 추출 워크플로우 다이어그램
• 주요 커밋: 475ac52

3. README 업데이트

• 프로젝트 정보 최신화: 최신 기술 스택 및 시스템 요구사항 반영
• 주요 변경사항:
  • 타이틀에서 이모지 제거 (전문성 강화)
  • CLIP 이미지 임베딩 모델 추가
  • Milvus 벡터 차원 명시 (텍스트 1024D, 이미지 512D)
  • 시스템 요구사항 상세화 (RAM, 디스크, Milvus)
  • 프로젝트 구조 확장 (backend scripts 서브디렉토리)
  • .venv 가상환경 규칙 명시
  • consistency checker stats 명령어 추가
  • chunker 선택 메커니즘 문서 링크 추가
• 주요 커밋: cc2468a

4. LLaVA 멀티모달 연구 노트북 추가

• 멀티모달 연구 자료: LLaVA 모델 활용 샘플 노트북 추가
• 주요 커밋: dc04475

5. Git 및 PR 가이드라인 문서화

• 주요 내용:
  • git commit –signoff 강제
  • Conventional Commit 형식 정의
  • 올바른 커밋 메시지 예제
• 주요 커밋: 7fedde1, 3adb478

성과 지표 (Metrics)

• 총 커밋 수: 14개 커밋 (10/5 ~ 10/18)
• 병합된 PR: 3개 주요 풀 리퀘스트 (#26, #28, #30, #31, #38)
• 버그 수정: 3개 주요 버그 수정 (외래 키, 벡터 DB, 401 에러)
• 주요 개선사항: 4개 시스템 최적화
• 새로운 기능: 1개 인증 시스템 개선
• 문서화: 5개 주요 문서 작성 및 개선

주요 PR 목록

• #38: JWT 토큰 만료 처리 및 자동 로그아웃 구현
• #31: 프로젝트 생성 UI에서 불필요한 사용자 선택 필드 제거
• #30: 사용자 선택 필드 제거 (이슈)
• #29: 벡터 DB 삭제 함수에서 project_id 사용
• #28: 벡터 DB 임베딩 삭제 오류 수정 (이슈)
• #27: 프로젝트 삭제 시 외래 키 제약 조건 수정
• #26: 프로젝트 삭제 외래 키 오류 (이슈)

핵심 개선 영역

• 인증 시스템: JWT 토큰 관리 및 자동 로그아웃
• 데이터 무결성: 외래 키 제약 조건 처리 및 삭제 순서 최적화
• 용어 통일성: Topic → Project 마이그레이션 완료
• 개발 워크플로우: Git 커밋 표준화 및 자동화
• 사용자 경험: UI 간소화 및 에러 처리 개선

향후 계획 (Future Plans)

1. 멀티모달 기능 고도화

• PDF 추출 이미지 자동 임베딩 구현
• Vision-LLM 통합 완성
• 이미지 기반 질의응답 시스템 구축

2. 시스템 성능 최적화

• 대용량 문서 처리 속도 개선
• Milvus 쿼리 최적화
• 캐싱 전략 구현

3. 사용자 관리 강화

• 역할 기반 접근 제어 고도화
• 사용자 활동 로그 시스템
• 프로젝트 협업 기능

4. 문서 처리 안정성

• 3-tier 폴백 메커니즘 고도화
• 더 많은 문서 형식 지원
• 에러 복구 시스템 구축

결론

DataProc 프로젝트는 이번 주 시스템 안정성과 사용자 경험에 집중하여 핵심 버그를 수정하고, 인증 시스템을 개선하였습니다. 외래 키 제약 조건 처리, 벡터 DB 스키마 마이그레이션, JWT 토큰 관리 강화를 통해 더욱 안정적이고 일관성 있는 시스템을 구축하였습니다.

특히 자동 로그아웃 시스템을 통한 보안 강화, Topic → Project 마이그레이션 완료를 통한 용어 통일, Git 워크플로우 표준화를 통한 개발 프로세스 개선이 핵심 성과입니다.

또한 Chunker 선택 메커니즘 분석, 텍스트-이미지 매칭 아키텍처 등 상세한 기술 문서를 작성하여 시스템에 대한 이해도를 높였습니다.

앞으로 멀티모달 기능 고도화와 시스템 성능 최적화를 통해 더욱 강력하고 효율적인 문서 분석 플랫폼으로 발전할 예정입니다.

문서 작성일: 2025년 10월 18일 버전: v0.3.0