새로운 웹 서비스를 시장에 선보이기 직전의 최종 점검 단계는 제품의 성패를 가르는 가장 중요한 순간이다. 개발 환경에서는 완벽해 보였던 기능도 실제 프로덕션 환경이나 통합 테스트 스트레스 하에서는 예상치 못한 버그를 발생시키기 마련이다.
Next.js와 Supabase 기반의 엔터프라이즈급 서비스 가오픈을 앞두고 진행한 전체 QA(Quality Assurance) 및 TQC(Total Quality Control) 과정과, 이를 통해 발견된 버그 수정 및 데이터베이스 아키텍처 개선 사례를 상세히 공유하고자 한다.
1. 가오픈 전 필수 QA Phase별 점검 전략과 성공 기준
안정적인 서비스 론칭을 위해서는 체계적인 단계별 검증 프로세스가 수립되어야 한다.
데이터의 정밀한 매칭을 목표로 구성한 3단계 QA Phase의 진행 결과와 구체적인 기술적 성과를 살펴본다.
2. 빌드 안정성 및 243개 단위 테스트 완전 통과
가장 먼저 시스템의 코드 레벨 안정성을 확보하기 위해 자동화된 빌드 및 단위 테스트 환경을 구동하였음.
- 최신 프레임워크 빌드:
Next.js 16.1.6버전과Turbopack빌드 엔진을 결합하여 프로덕션 빌드를 수행하였으며, 컴파일러 경고 없이 100% 빌드에 성공하였음. - 단위 테스트 커버리지: 총 16개의 핵심 테스트 파일에 내포된 243개의 단위 테스트 케이스를 전부 구동하였고, 단 하나의 실패도 없이 전수 통과(Pass)하는 쾌거를 이루었음.
이 단계는 리팩토링이나 기능 추가 과정에서 기존 비즈니스 로직이 파괴되지 않았음을 증명하는 최소한의 안전장치 역할을 함
3. DB-API-UI 연동을 위한 API 통합 테스트 및 이슈 디버깅
단위 테스트 이후에는 실환경과 동일한 데이터 흐름을 검증하기 위해 주요 엔드포인트에 대한 통합 테스트를 전개하였음. 인증, 사용자 관리, 대시보드 통계 등 총 8개의 핵심 API 셋을 점검하던 중 기술적 병목과 버그를 발견하여 즉각 조치하였음.
- 인증 및 세션 검증:
/api/auth/me엔드포인트를 통해 사용자 세션 유지 및 토큰 검증 로직이 정상 작동함을 확인하였음. - 데이터 무결성 확인: 제품 데이터, 언어 명세, 용어집 및 번역 데이터 처리 API가 UI 요구사항에 맞게 밀리초(ms) 단위의 빠른 응답 속도로 데이터를 리턴함을 검증하였음.
- Issues API 디버깅: 통합 테스트 중 이슈 관리 엔드포인트에서 예외 처리가 누락되는 현상을 발견하여 긴급 수정을 적용하고 정상 가동 상태를 확보하였음.
4. 시스템 안정성과 유지보수성 향상을 위한 코드 및 DB 리팩토링
QA 과정에서 발견된 취약점을 보완하고 개발 생산성을 높이기 위해 백엔드 API 아키텍처와 Supabase 스키마를 고도화하는 작업을 병행하였음.
ㄱ. 개발 모드 전용 인증 바이패스(Bypass) 메커니즘 구현
로컬 개발 환경 및 QA 단계에서 매번 소셜 로그인이나 세션 인증을 거쳐야 하는 불편함은 전체 개발 속도를 저하시키는 원인이었음. 이를 해결하기 위해 조건부 인증 우회 로직을 설계하였음.
- 환경 변수 제어:
ALLOW_AUTH_BYPASS=true옵션을 도입하였음. - 안전장치 마련: 무조건적인 우회가 아닌, 현재 노드 환경이 반드시 개발 모드(
process.env.NODE_ENV === 'development')일 때만 작동하도록 이중 방어벽을 쳤음. - 적용 범위: Issues API의 GET 및 POST 메서드 전체에 적용하여, 로컬 테스트 시에는 개발자 콘솔에 경고(Warning) 메시지만 출력한 뒤 인증 절차를 안전하게 통과하도록 조치하였음.
해당 방식은 실 배포 환경에서는 절대로 활성화되지 않으므로 보안성을 유지하면서도 로컬 테스트 효율을 극대화하는 결과를 낳았음
5. Supabase 데이터베이스 이슈 테이블 설계 및 마이그레이션
서비스 운영 중 발생하는 각종 파싱 및 유효성 에러를 체계적으로 수집하기 위해 새로운 테이블 스키마를 정의하고 마이그레이션을 단행하였음.
- 마이그레이션 파일:
supabase/migrations/051_create_issues_table.sql
핵심 데이터 구조:
id: 고유 식별을 위한 UUID 필수 설정.product_code: 문제가 발생한 제품의 도메인을 특정하기 위한 필드.issue_type: 발생 에러를 성격에 따라pdf_parse_error,image_parse_error,duplicate_text,validation_error등으로 엄격히 구분하여 열거형으로 관리함.file_names: 에러와 연관된 파일들을 추적하기 위해 문자열 배열(Array) 타입으로 설계함.resolved_at / by: 이슈의 조치 여부와 타임스탬프, 담당자 ID를 기록하여 사후 추적이 가능하도록 함.
6. 사용자 권한 및 감사 로그(Audit Log) 추적 기능 강화
가오픈 이후 대규모 사용자가 유입될 상황에 대비하여, 데이터 변경 이력을 영구적으로 기록하는 로깅 시스템과 유저 메타데이터를 보강하였음
- 작업 범위 설정: 유저 테이블에
work_scope및work_languages컬럼을 추가하여 작업자가 처리할 수 있는 번역 범위와 언어 셋을 제한할 수 있게 하였음. - 보안 키 관리: 조직별 설정 내에 Claude, Kimi, Gemini 등 서드파티 AI 모델의 API Key를 안전하게 격리 저장할 수 있는 공간을 확보하였음.
- 이중 감사 로그: 시스템 악용 및 데이터 오용을 방지하기 위해 사용자 행동을 기록하는
user_audit_logs와 시스템 환경 변수 변경을 추적하는settings_audit_logs테이블을 신설하여 완벽한 모니터링 체계를 구축하였음.