데이터를 마이그레이션하는 시스템을 구축할 때 가장 빈번하게 발생하는 문제는 프론트엔드와 백엔드 간의 데이터 파이프라인 불일치이다.
화면에서는 모든 필드를 정상적으로 매핑했음에도 불구하고, 실제 최종 데이터 변환 및 커밋 단계에서 특정 배열이 비어있거나 UI 버튼이 비활성화되는 현상은 시스템의 신뢰도를 급격히 떨어뜨린다.
8개의 서브에이전트(Subagent) 검증 체계를 동원하여 11시간 연속 디버깅 끝에 정복한 [PreviewCommit] Final languages: Array(0) 에러의 원인 분석과, Excel 파서 엔진 구조 개선 및 런타임 Null 참조 오류를 완전히 해결한 프론트엔드·백엔드 통합 리팩토링 성과를 상세히 설명하고자 한다.
1. 마이그레이션 프리뷰 단계의 번역 데이터 유실 현상과 증상 분석
마이그레이션 위자드의 마지막 관문인 ‘업로드 하기(PreviewCommitStep)’ 단계에서 심각한 데이터 단절 현상이 리포팅되었음. 필드 매핑이 완벽하게 끝났음에도 최종 화면에서 시스템이 언어 데이터를 전혀 인지하지 못하는 콤플렉스 상황이 발생하였음.
- 핵심 증상: Field Mapping 단계에서 원문(Source)과 번역문(Translations) 컬럼을 명확히 지정했으나, 다음 단계로 진입 시 ‘번역 정보 확인’ 버튼이 비활성화되는 현상임.
- 개발자 콘솔 로그: 브라우저 콘솔에
[PreviewCommit] Final languages: Array(0)라는 추적 로그가 출력되며 번역 메타데이터 배열이 완전히 비어있음을 증명하였음.
프론트엔드의 useMemo 연산 장치가 각 엔트리(entry.translations) 객체 내부에서 언어 키값을 정상적으로 추출해내지 못하면서 시작된 것으로 판명되었음
2. 8개 서브에이전트 기반 데이터 흐름 추적 및 원인 규명
문제의 근본적인 원인을 파악하기 위해 프론트엔드 상태 진입점부터 백엔드 파싱 엔진까지 총 8개 영역으로 서브에이전트를 쪼개어 심층 검증을 전개하였음
- 클라이언트 데이터 플로우:
PreviewCommitStep컴포넌트로 전달되는currentEntries자체는 정상 계산되나, 하위 레코드의translations객체가 완전히 누락된 상태로 전달됨을 확인하였음. - Excel 파서 엔진의 누락: 백엔드
parseExcel함수 분석 결과,fieldMappings.translations구조를 처리하는 내부 로직이 완전히 빠져 있었음. 기존 CSV 파서에 존재하던 컬럼 매핑 연산 로직이 Excel 파서로 이식되는 과정에서 유실된 것이 주원인이었음. - 데이터 키 일치 불일치: Excel 파서가 내부적으로
translation_${langCode}형태로columnMapping을 빌드하여 내보냈으나, POST API 핸들러에서 최종 Row 객체를 조립하고 추출할 때 정규식 키 명세가 매칭되지 않아 가공 단계에서 데이터가 소멸하는 현상이 발견되었음.
3. 백엔드 Excel 파싱 파이프라인 전면 개편 및 정규식 매칭 수정
유실되던 다국어 데이터를 백엔드 코어 단에서 정확하게 가로채어 구조화된 JSON 객체로 변환하도록 API 라우트 로직을 대대적으로 리팩토링하였음
- columnMapping 동적 생성:
parseExcel함수 내부에 번역 컬럼 배열을 순회하는 반복문을 추가하여, 엑셀 파일 내 각 언어 컬럼이 시스템 명세에 맞는translation_언어코드형태로 매핑 테이블에 강제 등록되도록 교정하였음. - 중국어 정규식 스펙트럼 확장: 기존 파서가 하이픈(
-)이나 언더바(_)가 섞인 국가별 세부 언어 코드를 파싱하지 못하던 한계를 극복하기 위해 정규식을zh-CN,zh-TW형태까지 완벽하게 추출하도록 수식을 고도화하였음. - 중복 매핑 방지 아키텍처: 동일한 엑셀 컬럼이 다중 매핑 로직을 타고 들어와 기존 데이터를 덮어쓰거나 무효화하는 위험을 차단하기 위해, 키 존재 여부를 선제 검증하는 방어벽 코드를 추가하였음.
4. 프론트엔드 Null 참조 위험 제거 및 Props Drilling 최적화
백엔드 파이프라인 수정과 동시에, 클라이언트 사이드에서 발생할 수 있는 런타임 크래시(Runtime Crash) 요소를 선제적으로 제거하였음
- 안전한 옵셔널 체이닝(Optional Chaining) 적용
:route.ts및 프리뷰 컴포넌트 전반에 걸쳐 유저 객체나 변환 데이터가 불완전하게 들어오는 예외 상황을 가정하여?.및|| {}처리를 촘촘하게 배치하였음. 이로써 어떠한 상황에서도 화면이 화이트아웃(White-out) 되지 않는 복원력을 확보하였음. - 컴포넌트 데이터 전달 단순화
:MigrationWizard상위 컨텍스트에서 하위 단계별 스텝 컴포넌트로 불필요하게 중복 전달되던previewData프로퍼티 구조를 정제하여 메모리 누수를 막고 데이터 흐름을 일방통행 구조로 정돈하였음
5. 남은 작업 및 회귀 테스트 로드맵
11시간 동안의 집중 리팩토링을 통해 아키텍처 결함은 모두 수정되었으며, 프로덕션 배포 전 최종 검증을 위한 4가지 시나리오 테스트를 설계하였음
- 특이 헤더 테스트: 엑셀의 첫 행 헤더가 숫자(
123)로만 구성되었거나 의미 없는 문자열(abc)인 경우에 대한 파싱 무결성 검증을 수행할 예정임. - 안드로이드 리소스 패턴 검증: 모바일 현지화 파일 형식인
values-ko등의 디렉토리 패턴이 파일 컬럼명에 매칭될 때의 호환성 예외 처리를 지속 모니터링할 방침임. - 디버깅 로그 정리: 개발 단계에서 심어둔 수많은
console.log추적 코드를 정적 분석 도구를 이용해 일괄 정리하여 배포 본 빌드 최적화를 이룩할 것임.