대용량 데이터를 시스템에 안정적으로 안착시키는 마이그레이션 엔진 개발은 프론트엔드와 백엔드 전반의 긴밀한 아키텍처 설계를 요구한다.
특히 복잡한 매핑 관계를 직관적으로 풀어내는 UI/UX 구현과, 대량의 데이터 트랜잭션 처리 시 발생하는 성능 병목을 제어하는 것은 고도화된 개발 공정의 핵심이다.
최근 진행된 ‘translation-manager’ 프로젝트의 3단계 마이그레이션 위자드(Migration Wizard) UI 고도화 과정과, 호이스팅 에러 수정, 그리고 백엔드 시스템의 치명적인 N+1 데이터베이스 쿼리를 완전히 제거한 실무적인 디버깅 성과를 상세히 설명하고자 한다.
1. 3단계 마이그레이션 위자드 아키텍처 및 직관적 레이아웃 설계
복잡하게 얽혀 있던 데이터 마이그레이션 단계를 직관적인 3단계 위자드 구조로 재정의하여 사용자 환경(UX)을 대폭 개선하였음.
[파일 업로드] ──> [데이터 매핑 (FieldMapping)] ──> [업로드 하기 (PreviewCommit)]
전체 프로세스를 논리적 흐름에 따라 세분화하고, 사용자가 입력해야 하는 설정 정보를 시각적으로 구조화하는 전략을 취하였음
2. 생산성 극대화를 위한 2단 격자(Grid) 매핑 UI 구현
마이그레이션 위자드의 핵심인 ‘데이터 매핑’ 단계를 위해 화면 공간을 효율적으로 분할하는 grid grid-cols-2 기반의 2단 레이아웃 컴포넌트를 개발하였음.
왼쪽 영역 (버전 선택 및 파일 컬럼 목록):
- 버전 선택 (상단): 엑셀 파일 내의 Sheet 목록을 시각화하여 클릭 시 해당 시트의 데이터로 전환되도록 설계함. 드래그를 통한 버전 매핑을 지원하며, 완료 시 체크 아이콘 표시로 상태를 전달함.
- 파일 컬럼 (하단): 선택된 시트의 헤더 컬럼 목록을 나열함. Ctrl+클릭 다중 선택 인터랙션을 전격 지원하여 수십 개의 컬럼을 한 번에 제어할 수 있도록 생산성을 높였음. 이미 매핑된 컬럼은 자동으로 비활성화(Disabled) 처리하여 중복 지정을 방지함.
오른쪽 영역 (시스템 필드 드롭존):
- 시스템에 입력될 데이터 필드들을 성격에 따라 명확한 시각적 컬러 코딩으로 구분하여 오입력을 방지함.
- 원문 필드 (필수): 파란색 테두리 및 배경 처리.
- 번역 언어 필드 (다중): 초록색 테두리 및 배경 처리.
- KEY/ID, 제품분류, 버전, 문맥 필드: 시스템 제어용 메타데이터로 보라색 컬러를 부여함.
3. 프론트엔드 UI 버그 디버깅 및 컴포넌트 안정화
QA 단계를 거치며 발생한 사용자 경험(UX) 저해 요소와 자바스크립트 실행 오류를 정교한 코딩법으로 해결하였음.
ㄱ. 스크롤 잠금 현상 해결 및 UI 원상 복원
이전 UI 개편 과정에서 스타일 시트 충돌로 인해 발생했던 화면 스크롤 문제를 해결하였음.
마이그레이션 위자드가 동작하는 컨테이너의 오버플로우(overflow) 속성을 정밀하게 제어하여, 대용량 컬럼 목록이 노출되더라도 전체 레이아웃이 무너지지 않고 부드러운 스크롤이 유지되도록 기존의 안정적인 UI 형태로 복원 작업을 마쳤음
ㄴ. JavaScript 호이스팅(Hoisting) 에러 및 컴포넌트 호출 순서 정정
FieldMapping.tsx 파일 내에서 특정 이벤트 핸들러 함수가 선언되기 전에 상단 컴포넌트에서 이를 참조하여 발생하는 런타임 초기화 오류(Hoisting Error)가 감지되었음.
해결 방안
: React 컴포넌트와 유틸리티 함수의 선언 순서를 논리적 실행 흐름에 맞게 전면 재배치하였음. 하위 헬퍼 함수들을 파일의 최하단으로 내리거나 컴포넌트 스코프 내부로 안전하게 격리하고, 상위에서 하위로 흐르는 선언적 구조를 확립하여 빌드 가동 시 발생하던 잠재적 스크립트 에러를 완전히 박멸하였음.
4. 백엔드 N+1 쿼리 최적화와 대용량 데이터 처리 성능 개선
백엔드 성능의 발목을 잡던 대량의 개별 조회 루프 연산을 제거하고, 단일 배치(Batch) 기반의 복합 쿼리 체계로 전환하여 데이터베이스 인프라 리소스를 최적화하였음
ㄱ. 단일 호출 기반의 다중 데이터 일괄 조회(In Clause) 기법 적용
기존 마이그레이션 커밋 API(/api/migration/commit/route.ts)는 업로드된 데이터 행(Row)을 루프를 돌며 매번 데이터베이스에 단건으로 SELECT 요청을 보내는 전형적인 N+1 쿼리 문제점을 안고 있었음. 이는 수천 건의 데이터 처리 시 커넥션 풀을 고갈시키고 타임아웃을 유발하는 주범이었음
최적화 파이프라인
: 데이터를 벌크(Bulk) 처리하기 전, 대상이 되는 모든 원문 텍스트 배열(sourceTexts)을 소스 레벨에서 먼저 수집한 뒤 Supabase(PostgreSQL)의.in()필터를 사용하여 단 한 번의 복합 쿼리로 인덱스 검색을 수행하도록 아키텍처를 전면 리팩토링하였음.
- 용어집 매칭(Glossary Matches): 입력된 원문 리스트가 기존 용어집 테이블에 존재하는지 단 한 번의 벌크 쿼리로 매핑 데이터를 확보함.
- 번역 데이터 매칭(Translation Matches): 번역문 결과 및 연관 관계를 일괄 조회하여 메모리 상에서 맵(Map) 객체로 구조화한 뒤 비교 연산을 수행함.
리팩토링을 통해 기하급수적으로 늘어나던 네트워크 왕복 비용(Round-Trip Time)을 단 2번의 쿼리로 동결시켰으며, API 응답 속도를 수십 배 이상 끌어올리는 정량적 쾌거를 이루었음
5. 기능 테스트 검증 결과
feature/migration-qa-fixes 브랜치 작업을 통해 시스템의 완성도는 한 단계 더 진화하였음. 소스 코드 수정 완료 후 프로덕션 빌드 명령어인 npm run build를 구동하여 컴파일러 경고와 정적 타입 오류가 전혀 없는 완벽한 빌드 성공(✓ Compiled successfully) 상태를 최종 확인하였음
UI 인터랙션의 정교함(Ctrl 클릭 다중 선택, 드래그앤드롭)과 백엔드의 배치 쿼리 최적화가 유기적으로 결합된 마이그레이션 위자드는 대규모 엔터프라이즈 데이터를 다루는 강력한 데이터 파이프라인으로 거듭나게 되었음