다국어 번역 관리 시스템(TMS)에서 대규모 현지화 데이터를 다룰 때, 데이터베이스 인프라의 다변화와 파싱 파이프라인의 견고함은 곧 시스템의 생존과 직결된다. 개발 환경의 경량화나 로컬 독립 인프라 구축을 위해 SQLite 모드를 활성화할 때 발생할 수 있는 데이터 정합성 충돌과 외래키 예외 처리는 정교한 시스템 아키텍처 수정을 요구함.
최근 진행된 ‘Translation Monster’ 프로젝트의 20번째 스프린트에서는 SQLite 데이터베이스 아키텍처에 마이그레이션 커밋 엔진을 이식하고, 비정형 엑셀 파일의 정밀 파싱을 위한 검색 알고리즘 고도화, 그리고 정적 타입 시스템의 데이터 누락 문제를 완벽하게 해결한 통합 리팩토링 성과를 달성하였다.
이 과정에서 축적된 트러블슈팅 사례와 데이터베이스 스키마 확장 기법을 상세히 공유한다.
1. SQLite 인프라 완전 이식 및 외래키(Foreign Key) 우회 아키텍처 구축
기존 마이그레이션 파이프라인은 엔터프라이즈급 Supabase(PostgreSQL) 환경에 강하게 결합되어 있어, 경량 SQLite 모드 전환 시 강력한 외래키(Foreign Key) 제약 조건 오류로 인해 배치 커밋 작업이 차단되는 치명적인 병목이 발생하였음. 이를 전면 개편하여 완벽한 인프라 분기를 실현하였음.
동적 런타임 분기 적용:
commit/route.ts컨트롤러 내부에 SQLite 감지 분기 처리 코드를 이식하여 인프라 모드에 따라 쿼리 프레임워크가 유기적으로 스위칭되도록 수정하였음.사용자 권한 무결성 확보: 세션 인증이 제한된 로컬 로딩 테스트 환경이나 데이터 마이그레이션 초기화 단계에서 외래키 결함을 방지하기 위해, 데이터베이스 내 마스터/관리자 계정을 조회하여 런타임에 유효한 고유 사용자 ID(
userId)를 동적으로 추출하는 하드 가드레일 로직을 배치하였음.
2. 유연한 엑셀 파서 엔진 개선 및 콘텐츠 기반 자동 탐색 기술
현업에서 사용하는 현지화 시트 파일들은 첫 번째 행에 헤더(Header)가 존재하지 않거나 상단에 불필요한 설명 텍스트 영역이 비정형 데이터 형태로 혼재되어 있어, 기존의 정형식 파서 엔진이 컬럼명 매핑에 무참히 실패하는 취약점이 있었음.
ㄱ. findHeaderRow() 기반 다차원 스캔 알고리즘 이식
동적 행 추적 엔진: 파일 인입 시 무조건 인덱스
0번 행을 컬럼명 헤더로 가중치를 두던 방식에서 탈피하여, 필드 매핑 명세에 정의된 원문(source) 키워드를 기준으로 실제 행 데이터를 종으로 추적하는findHeaderRow()기술을 전격 구현하였음.최대 10행 경계 검색: 파일 상단 최대 10행까지 루프 스캔을 전개하여 원문 컬럼명이 최초 매칭되는 물리적 위치를 역추적해 내므로, 상단에 어떠한 공백 레코드나 노이즈 가비지 데이터가 존재하더라도 한 치의 오차 없이 데이터 시작 영역을 판별해 냄.
지능형 시트 피팅: 여러 개의 탭이 활성화된 엑셀 통합 문서에서 설명 시트만 읽어 들이던 연산 버그를 해결하기 위해 메타데이터 스펙트럼(
product_category)과 연동되는 패턴 매칭 자동 선택 장치를 장착하였음.RMAndroid,RMSolution등 고유 명세가 검출되면 해당 시트 데이터를 정밀 가공 파이프라인으로 다이렉트 바인딩함.
3. 데이터 영속성 확장을 위한 데이터베이스 스키마 고도화 및 테이블 설계
마이그레이션 데이터를 누락 없이 장기적으로 추적 및 격리하기 위해 SQLite 로컬 파일 시스템(data/app.db)의 물리 스키마를 대대적으로 확장 구축하였음.
ㄱ. operation_batches 중심의 트랜잭션 추적성 확보
배치 추적 테이블 신설: 마이그레이션이 트리거될 때 일련의 벌크 공정을 영구 트래킹할 수 있도록
operation_batches테이블을 신설하여 작업자 명세 및 이력 필드를 완전 구체화하였음.다국어 메타데이터 규격 통합:
translations코어 데이터 레이어에platform,key,description,product_category,extra등 다차원 리소스 관리를 위한 컬럼 배열을 완전히 주입함으로써, 임포트 시 소스 텍스트 유실을 완벽히 방어하였음.
ㄴ. 데이터 정합성 필터링 논리 수정: 소프트 딜리트(Soft Delete) 예외 처리
중복 데이터 스캔 시 이전에 시스템 사용자에 의해 이미 삭제 처리된 레코드(is_deleted = TRUE)까지 중복 배열로 오인하여 정상적인 신규 데이터를 마이그레이션 맵에서 누락시키는 치명적인 비즈니스 결함이 제기되었음.
이를 방지하기 위해 중복 검사 복합 배치 SELECT 쿼리 단에 AND (is_deleted = FALSE OR is_deleted IS NULL) 가드레일 조건을 명시적으로 수정 적용함으로써, 유효성이 종식된 과거 데이터와 무관하게 깨끗한 신규 데이터 인서트를 이룩할 수 있도록 데이터베이스 비즈니스 룰을 견고히 교정하였음.
4. 사용자 경험 극대화와 새로고침 시 데이터 손실 방지
클라이언트 사이드 아키텍처 단에서도 사소한 인터랙션 문제를 깔끔하게 종결 처리하였음.
세션스토리지 영속화: 사용자가 마이그레이션 진행 중 브라우저 새로고침 버튼을 눌렀을 때, 메모리 낭비를 유발하는 대형
file객체를 제외한 모든 동적 필드 매핑 세팅 상태값을sessionStorage에 실시간 캐싱 및 복원(persistableState)하도록 장치를 강화하였음.자동 리다이렉션 인터셉터: 만약 영속화 파일이 완전 소멸된 불완전 진입 상태가 감지되면,
useEffect훅이 이를 실시간 인터셉트하여 토스트 알림창과 함께 사용자를 안전하게 초기upload단계로 강제 리다이렉션 시켜 런타임 크래시를 전면 방어하도록 구현하였음.UI 가독성 마감: 플랫폼 선택용 멀티 셀렉트 박스가 화면 최하단 영역에서 잘리는 현상을 수정하기 위해 위 방향으로 펼쳐지도록 속성(
openUpward={true})을 패치하여 마우스 가시성을 대폭 개선하였음.
5. 벤치마크 테스트 스코어 리포트
이번 스프린트를 통해 6ea9fd7 (SQLite 지원), 01864fe (데이터 표시 교정) 등 3개의 핵심 아키텍처 수정을 담은 대형 패치가 안전하게 프로덕션 브랜치에 통합 완료되었음. 중국어 홍콩권 확장을 위한 zh-HK 로케일 코드 명세 보완 작업까지 완료되어 언어적 스펙트럼도 10대 언어 레이어로 공고해졌음.
실제 임포트 가동을 진행한 결과, 단일 파일 내 총 772개의 대형 데이터 레코드 파싱 파이프라인에서 단 3개의 용어집 레코드와 715개의 고품질 번역 데이터를 완전 유실 없이 단 900ms만에 고속으로 처리해내는 놀라운 벤치마크 퍼포먼스를 달성하였음.
인프라 정합성이 보장된 만큼 다음 주 릴리즈 공정에서는 기존 중복 데이터 위에 가변적으로 새 번역본을 입히는 ‘덮어쓰기(Overwrite) 기능’ 고도화에 본격 착수할 예정임.