엔터프라이즈급 글로벌 번역 관리 시스템(TMS)에서 마이그레이션 파이프라인을 구축할 때 가장 중요한 과제는 대용량 데이터의 이식성과 영속성을 보장하는 것이다. 특히 단일 인프라 환경을 넘어 로컬 독립 데이터베이스(SQLite)와 클라우드 기반 인프라(Supabase)를 동시에 제어하는 하이브리드 아키텍처에서는, 제품군에 따른 데이터 격리(Scoping)와 트랜잭션 충돌을 정밀하게 제어하는 기술이 요구된다.
최근 진행된 ‘Translation Monster’ 프로젝트의 21번째 스프린트에서는 멀티 테넌트 환경의 핵심인 제품 종속형 데이터 격리 메커니즘을 구현하고, 5차원 메타데이터 확장, 그리고 SQLite 모드 가동 시 발생하는 트랜잭션 및 디스크 이메지 훼손(malformed) 이슈를 완전히 정복한 인프라 안정화 성과를 달성하였다.
이 과정에서 겪은 하드코어 디버깅 사례와 아키텍처 복구 노하우를 상세히 공유한다.
1. 전역 매칭에서 제품 종속형(Product-Specific) 중복 검증 체계로의 대전환
기존의 마이그레이션 엔진은 전역 스코프에서 중복 데이터를 검사했기 때문에, 서로 다른 제품군에서 동일한 원문 데이터를 사용할 때 이를 신규 데이터로 인지하지 못하고 결합해 버리는 아키텍처 결함이 존재했음. 이를 해결하기 위해 완벽한 제품별 독립 스코핑 필터링을 도입하였음.
도메인 격리 아키텍처: 동일한 텍스트 데이터셋이 인입되더라도 타깃 제품 코드가 다르면 시스템이 이를 완전히 독립적인 ‘신규 데이터’로 인식하도록 룰셋을 전면 개편하였음.
듀얼 모드 필터 엔진 고도화: 중복 검증 코어 모듈인
duplicate-checker.ts내부의 SQLite 전용 쿼리 핸들러(fetchGlossaryMatchesSQLite)와 Supabase 전용 쿼리 핸들러(fetchGlossaryMatchesSupabase) 양측 모두에 제품별 필터링(product_code조건절) 바인딩 로직을 주입하였음.
필터링 아키텍처 덕분에 멀티 프로덕트를 동시에 번역 관리하는 엔터프라이즈 환경에서 데이터 간의 유기적인 격리와 무결성이 완벽하게 보장되게 되었음.
2. 5차원 메타데이터 확장 및 상태값 전역 일관성 확립
임포트되는 소스 데이터의 풍부한 콘텍스트를 잃지 않기 위해 시스템 코어 레이어의 메타데이터 파이프라인을 전면 확장하였음.
ㄱ. 5대 핵심 메타데이터 필드 자동 추출 파이프라인 구축
확장 필드 명세: Excel 및 CSV 파싱 엔진인
preview-simple.ts를 개정하여 원문 외에platform(플랫폼),key(리소스 키),description(콘텍스트 설명),product_category(제품분류),extra(기타 추가 정보) 등 5대 메타데이터 필드를 파일로부터 자동 추출하도록 연동하였음.INSERT 스펙 동기화: 추출된 메타데이터 배열은 백엔드 저장소 핸들러인
commit/route.ts컨트롤러와 다이렉트로 바인딩되어 데이터베이스의 영속 테이블 구조에 누락 없이 인서트되도록 리팩토링하였음.
ㄴ. 워크플로우 탭 연동을 위한 상태값 가이드라인 지정
마이그레이션이 완료된 데이터가 시스템 관리자의 후속 작업 프로세스(검토/승인)와 즉각 유기적으로 매핑되도록 상태값 초깃값을 명확히 정의하였음.
번역 데이터(Translation): 마이그레이션 적재 즉시
status = 'reviewed'로 강제 바인딩되어, 번역 관리 대시보드의 ‘검토’ 작업 탭에 즉각 노출되도록 동선을 일원화하였음.용어집 데이터(Glossary): 인서트와 동시에
approval_status = 'approved'표준 권한 승인 상태값으로 설정되어, 용어집 관리 화면의 ‘승인’ 완료 탭에 실시간 동기화되도록 조치하였음.
3. 고집중 트러블슈팅: SQLite 트랜잭션 락(Lock) 및 데이터베이스 손상 해결
로컬 테스트용 SQLite 인프라를 가동하고 대용량 데이터의 벌크 인서트를 처리하는 공정에서 동시다발적인 하드웨어 및 소프트웨어 예외 임계점이 발생하였음.
4. WAL 모드 트랜잭션 충돌 및 disk image is malformed 에러 정복
마이그레이션 작업의 원자성(Atomicity)을 보장하기 위해 백엔드 단에 BEGIN TRANSACTION, COMMIT, ROLLBACK 파이프라인을 구축하였으나, 고속 처리를 위해 설정해 둔 WAL(Write-Ahead Logging) 모드와 트랜잭션 락이 상호 충돌하면서 데이터베이스 디스크 이미지가 깨지는(database disk image is malformed) 치명적인 크래시가 관측되었음.
여파로 인해 마이그레이션 커밋 시 서버가 무한 대기 상태에 빠지는 무한 로딩 리스크가 동반되었음.
긴급 조치 및 해결 파이프라인
1. 초기화 및 클리닝: 손상된.db로컬 파일 인프라를 완전히 폐기하고 깨끗한 새 데이터베이스 파일 구조를 신규 빌드하였음.2. 프로덕션 락 해제: 마그네틱 결함을 유발하던 불완전한 상태의 SQLite 트랜잭션 구문을 안전한 검증이 완료될 때까지 일시적으로 롤백 분리 가동하였음.
3. 데드락 캐시 청소: 서버 빌드 찌꺼기와 소켓 파일 락이 잔존해 무한 대기를 유도하던 런타임 캐시 환경인
.next빌드 아티팩트 폴더를 통째로 파괴하고 개발 서버를 재시작하여 정상 파이프라인을 탈환하는 데 성공하였음.
5. 스키마 파편화 방지를 위한 데이터베이스 DDL 고도화
Supabase의 PostgreSQL 스키마와 SQLite 간의 컬럼 명세 불일치 현상을 종식하기 위해 물리 데이터베이스의 DDL(Data Definition Language) 레이어를 대대적으로 보강 수정하였음.
고도화된 스키마 구조 조정을 통해 메타데이터 적재 시 발생하던 no such column: platform 예외 에러를 완벽하게 차단하였음.
더불어 프론트엔드 단의 UI/UX 개선을 위해 번역 진행 상태 탭(StatusTabs.tsx) 내부의 빈 탭 클릭 제한 속성(disabled)을 과감히 들어내어 데이터가 없는 구간에서도 키보드 네비게이션과 탭 접근성이 자연스럽게 유지되도록 정제하였음.
6. 차기 스프린트 로드맵
이번 스프린트는 예기치 못한 인프라 데드락과 스키마 훼손 버그 속에서도 0ac1609 (제품 종속 기능 및 메타데이터 저장 개선) 백업 커밋 레이어를 성공적으로 Git 헤드 스태시로 보존하며 아키텍처의 유연성을 입증해 보였음.
성공적인 마감을 바탕으로 내일부터 전개될 차기 공정에서는 아래의 4대 고도화 과제를 집중.
초기 스키마 동기화: 수정된 DDL 내역을
sqlite/migrations/001_initial_schema.sql스크립트에 정식 컴파일 병합.트랜잭션 복구 엔진 고도화: WAL 모드 하에서도 교착 상태가 없는 견고한 SQLite 트랜잭션 예외 복구 로직 재설계.
카테고리별 실시간 카운트 UI 적용:
PreviewCommitStep.tsx미리보기 화면 내에 번역 데이터와 용어집 데이터 간의 유기적인 수량 합계(Total 772개)가 정량적으로 연산 표기되는 통계 대시보드 마감.