데이터 마이그레이션은 다양한 형식의 외산 데이터를 시스템 포맷에 맞추어 결함 없이 안착시키기 위해서는 직관적인 매핑 컴포넌트와 한 치의 오차도 허용하지 않는 엄격한 타입 아키텍처가 필수적이다.
최근 진행된 ‘Translation Manager’ 프로젝트의 DB 기반 동적 언어 매핑 UI 개선 과정과, 닥쳐왔던 빌드 오류의 타입 매커니즘 수정, 그리고 런타임 예외 처리를 해결한 실무적인 고도화 성과를 상세히 설명하고자 한다.
1. DB 기반 동적 필드 매핑 UI 구조화와 레이아웃 혁신
기존 마이그레이션의 필드 매핑 단계는 수많은 다국어 컬럼이 하나의 ‘번역 언어’ 영역에 무분별하게 혼재되어 있어, 사용자가 개별 언어를 직관적으로 구별하고 매핑하기에 큰 불편함이 따랐음. 이를 전면 개편하여 사용성을 극대화하였음
ㄱ. useLanguages 기반 동적 언어 목록 추출 및 개별 필드 분리
시스템의 확장성을 보장하고 하드코딩을 제거하기 위해 데이터베이스와 직접 연동되는 동적 매핑 컴포넌트를 설계하였음
- 동적 훅 연동:
useLanguages()커스텀 훅을 결합하여 데이터베이스에 등록된 실제 활성 언어 명세를 실시간으로 호출하도록 변경하였음. - 원문 제외 및 정렬: 마이그레이션의 기준점이 되는 한국어(
ko)를 필터링하여 제외하고, 관리자가 지정한 디스플레이 순서(display_order)에 따라 다국어 배열을 정렬하였음. - 독립 DropZone 생성: 영어, 일본어, 중국어(간체/번체), 독일어, 스페인어, 포르투갈어, 이탈리아어, 프랑스어 등을 각각의 독립된 드롭존(DropZone) 필드로 완전히 분리하여 다중 매핑의 혼선을 원천 차단하였음.
이 방식을 통해 향후 새로운 국가의 언어가 시스템에 추가되더라도, 프론트엔드 소스 코드의 수정 없이 UI가 동적으로 확장되는 유연한 구조를 확립하였음
2. 공간 효율성을 극대화한 2열 그리드 및 높이 최적화
수십 개의 필드가 화면을 가득 채워 피로도를 유발하던 컴포넌트 구조를 정밀한 CSS 레이아웃 설계를 통해 컴팩트 디자인으로 고도화하였음
- 하이브리드 그리드 레이아웃: 시각적 중요도가 가장 높은 ‘원문 필드’와 ‘제품분류 필드’는 상단 1행에 넓게 배치하고, 하위 다국어 매핑 필드들은 2행 하단에 4열 그리드(Grid) 구조로 오밀조밀하게 배치하여 시선의 흐름을 논리적으로 통제하였음.
- DropZone 높이 동기화: 업로드된 파일의 테이블 셀 높이와 매핑 대상 드롭존의 높이가 불일치하여 스크롤이 어긋나던 현상을 수정하였음. 컴포넌트의 크기에 따라 대형 요소를 52px, 소형 요소를 36px로 유기적으로 매치시켜 마우스 드래그 가시성을 비약적으로 향상시켰음.
3. Next.js 빌드 오류 박멸을 위한 TypeScript 타입 안정성 고도화
코드를 컴파일하고 프로덕션 릴리즈를 준비하는 과정에서, 컴포넌트 인터페이스와 API 리턴 타입의 파편화로 인해 대규모 빌드 실패 현상이 관측되었음. 정적 타입 시스템의 명세를 정교하게 맞추어 잠재적 런타임 에러를 완벽히 차단하였음.
ㄱ. MigrationContext 내 핵심 인터페이스 명세 보강 및 Export
컴포넌트 간 경계를 넘나드는 데이터들의 무결성을 보장하기 위해 중앙 상태 관리 컨텍스트의 가용 타입을 확장하였음
- CommitResponse 명세 고도화: 마이그레이션 커밋 후 백엔드 서버로부터 반환되는 최종 응답 객체에
errors배열 필드와 서버 측 처리 시간을 밀리초 단위로 기록하는processingTimeMs속성을 명시적으로 추가하고 외부 컴포넌트에서 참조할 수 있도록export처리를 단행하였음. - PreviewEntry 확장: 프리뷰 테이블에서 제품 정보를 교차 검증할 수 있도록 데이터 엔트리 인터페이스 내에
product_code및product_category문자열 필드를 필수 타입으로 주입하였음. - 누락 훅 바인딩: 상태 초기화와 컨텍스트 제어에 필수적이었으나 인터페이스 선언에서 빠져 있던
commitSelectedMigration함수와clearCommitResults액션 메소드를 컨텍스트 명세에 온전히 등록하여 타입 추론의 영속성을 확보하였음.
4. 데이터 가공 라우트(route.ts)의 메타데이터 파싱 로직 교정
백엔드 파이프라인 엔진인 preview/route.ts가 다국어 데이터를 변환할 때, 규격화되지 않은 메타데이터 필드를 안전하게 파싱하도록 방어적 변환 코드를 이식하였음.
각 데이터 로우가 보유한 개별 언어 속성들을 metadata.lang_XX 구조의 표준 키 밸류 셋으로 맵핑 및 가공 처리함으로써 데이터베이스 인서트 시의 규격 불일치 문제를 완벽하게 청소하였음.
5. 사용자 경험 개선을 위한 확인 모달 제거 및 즉시 실행 아키텍처
기존의 마이그레이션 위자드는 최종 단계에서 업로드 버튼을 누를 때마다 “정말로 실행하시겠습니까?”라는 불필요한 이중 컨펌 모달 창을 띄워 작업의 연속성을 저해하는 요소가 있었음.
ㄱ. UX 정제 전략
검증 파이프라인과 프리뷰 테이블의 신뢰도가 확보되었으므로, 과감하게 불필요한 중간 확인 팝업 모달을 코드 레벨에서 통째로 파괴 제거하였음.
사용자가 업로드 버튼을 누르는 즉시 비동기 커밋 액션 함수가 백엔드로 트랜잭션을 쏘아 올리도록 로직을 다이렉트로 연결하여, 대량 마이그레이션 반복 작업 시 발생하던 클릭 리소스를 줄이고 작업 속도를 체감할 수 있을 정도로 고속화하였음
6. 이슈 및 향후 수정 로드맵
대부분의 크리티컬 버그와 UI 가독성 문제는 종식되었으나, 사후 모니터링 과정에서 발견된 미세 과제들에 대한 패치 계획을 수립하였음.
- 버전 필드 폴백(Fallback) 현상
: 사용자가 엑셀 필드 매핑 단계에서 ‘버전’ 컬럼을 지정하지 않고 공란으로 둘 경우, 시스템 내부의 예외 처리 로직이 오작동하여 버전 칸에 ‘제품분류’ 데이터가 대입되어 표기되는 기이한 현상이 리포팅되었음. - 해결 계획
: 백엔드 API 서버의 데이터 가공 헨들러 내부에서 공백 또는 undefined 매핑 감지 시, 다른 필드의 값을 참조하는 폴백 로직을 차단하고 명시적인 하이픈 문자열("-")로 치환하여 데이터 무결성을 유지하도록 단기 패치를 진행할 예정임.