배경
voidx.ai는 AI 에이전트 SaaS의 마케팅 사이트이자 회원 콘솔입니다. 회원가입·로그인부터 데모 체험, 멤버십 구독 결제, 에이전트 캐스팅·배치, 위젯 설치까지 서비스가 실제로 팔리는 동선 전체가 이 웹 위에 있습니다. 기존 구현을 Next.js 16과 React 19로 이관하는 작업에서 시작해 정식 운영까지 맡고 있습니다.
담당 영역은 인증 · 구독 결제(조회·해지·재개) · 멤버십 · API v2 이관 주도 · SEO/GEO · AI 에이전트 생성·배치 · 다국어(ko/en) · 고객용 외부 문서 · 계측 정합성입니다. 결제 트랜잭션과 멱등 처리, 환불 이벤트는 백엔드가 구현했고 어드민 콘솔 화면 다수는 동료와 분담했습니다.
전역 인증 모달과 멤버십·역할 2축 접근 제어
로그인을 페이지가 아니라 전역 모달로 설계해 어디서 막히든 그 자리에서 인증하고 next 파라미터로 원래 목적지에 복귀합니다(내부 경로만 허용). 가입 진입점 8곳이 모달 하나로 수렴합니다. 가입·인증 → 결제·멤버십 → 캐스팅 → 위젯 키 발급 → 설치 3단 스테퍼를 하나의 동선으로 이었고 라우트 54개 중 53개를 직접 작성했습니다. 인증은 NextAuth 기반으로 이메일·소셜 로그인과 탈퇴, 프로필 조회·수정을 붙였고 미들웨어에서 JWT 오류를 자동 처리해 어긋난 세션이 화면 오류로 번지지 않게 했습니다.
- 접근 판정 2축 분리: 멤버십이 없는 계정으로 들어오면 화면이 403을 받고 나갈 길이 없어지는 문제가 있었습니다. 결제로 해소되는 것(멤버십)에만 구독을 유도하고 결제로 해소되지 않는 협업 역할은 구독 유도 대상에서 뺐습니다. 판정은 단일 훅으로 모았습니다.
- 메뉴 게이팅 2단: 멤버십이 필요한 메뉴는 숨기지 않고 잠금 아이콘으로 노출해 결제하면 열리는 기능을 보여주고 몰 연동이 필요한 메뉴만 숨깁니다. 에이전트 생성 입구는 열어 두고 결과 확정과 토큰 발급 단계에만 잠금을 걸었습니다.
- 출처 승계: 잠긴 기능을 누르면 이동 대신 안내 모달을 띄우고 요금제로 넘어갈 때 유입 출처(from)를 체크아웃까지 승계해 어떤 게이트가 결제로 이어졌는지 추적할 수 있게 했습니다.
- 해지와 재개: 해지는 즉시 차단하지 않고 기간 만료형입니다. 남은 기간 접근을 유지하고 빌링키를 보존해 재개할 때 카드를 다시 등록하지 않아도 구독이 복원됩니다.
8개 도메인 175개 API 경로 이관과 계약 드리프트 검출
운영 중인 서비스의 백엔드 API가 전면 재설계됐습니다. 화면 전체가 의존하는 8개 도메인 175개 경로를 사용자에게 끊김 없이 옮겨야 했고 백엔드 구현이 끝나기를 기다릴 여유가 없었습니다. 명세와 실제 응답이 다른데 화면에서는 동작하는 것처럼 보이는 상태가 가장 위험해 경로 하나씩 대조하는 전수 이관을 택하고 API 응답과 에러 체계를 테스트로 고정할 수 있는 계약으로 만들었습니다.
- 에러 계약을 테스트로 명문화: 도메인별 에러 코드 체계(problem+json)를 클라이언트 계약 테스트로 적어 결제·캐스팅·카페24 연동처럼 도메인마다 테스트를 두고 백엔드가 바뀌면 테스트가 먼저 깨지게 했습니다.
- 연동 진척도를 코드로 다시 셈: 백엔드가 게이트웨이 접속 로그를 근거로 공유한 연동률과 화면 코드의 호출 지점을 전수 대조한 결과가 크게 달랐습니다(로그에 남지 않는 경로 때문). 이 대조를 기준으로 남은 작업량을 다시 잡아 화면 전체를 v2로 옮겨 정식 운영에 올렸습니다.
- 대조를 사람이 반복하지 않게: 백엔드 OpenAPI 정본과 프론트엔드 구현을 비교하는 스크립트를 만들어 명세가 바뀌면 어긋난 경로가 목록으로 나옵니다. 정본 사본을 리포에 두면 낡아서 계약을 오판하게 되므로 환경변수로 주입받아 읽습니다.
- 목 기준 선행 개발과 검증 인프라: 어드민 콘솔에는 MSW 계약 테스트 체계를 세워 정의되지 않은 API 호출은 즉시 실패(
onUnhandledRequest: 'error')하게 했고 덕분에 백엔드 구현 전에 프론트엔드가 먼저 움직일 수 있었습니다. Playwright 여정 테스트는 setup·journeys·locale 3프로젝트로 나눠 백엔드 없이 도는 검증과 실서버가 필요한 검증이 서로 막지 않게 했습니다. 계약이 깨진 것을 한 번도 잡아내지 못한 목 서버 레이어 9,341줄은 걷어내고 실서버 스모크로 바꿨으며 CI에서 한 번도 실행되지 않던 단위 테스트 배선을 고쳐 브랜치 보호의 필수 체크로 걸었습니다.
실결제 미반영 이슈 대응과 운영 안전장치
v2 전환 기간에 실사용자가 멤버십 결제에서 중복 승인과 멤버십 미활성화를 함께 겪었습니다. 이 사실을 알려 준 것은 사용자의 문의 메일이었고 감지 채널을 먼저 만드는 일을 재발 방지 1번 과제로 잡았습니다. 당일 사과와 전액 환불로 피해를 끊고 전역 결제 차단 스위치로 4개 진입점을 잠갔습니다(조회 화면은 유지).
- 프론트엔드 사각지대 3종 실증·수정: 2xx면 응답 본문을 확인하지 않고 성공으로 넘기던 판정, 본문 없는 204 응답에서 화면이 멈추던 문제, 결제 뒤 멤버십 활성화를 확인하지 않던 흐름입니다.
- 에러 계약 고정: 주문 API 응답 13케이스를 오류 리졸버와 한국어·영어 메시지 16키로 매핑하고 테스트 47건으로 고정해 개발자용 문구와 내부 API 경로가 사용자 화면에 노출되던 경로까지 지웠습니다.
- 킬스위치와 실카드 검증: 결제 차단 스위치는 환경 플래그로 두되 기본값을 잠금으로 설정해 코드 배포 없이 즉시 잠그면서 실수 커밋 한 번으로 차단이 풀리지 않게 했습니다. 재개 전에는 실카드 결제·환불 15개 시나리오로 결제 성공만이 아니라 해지·재개·환불까지 왕복을 확인했습니다. 상세 경위는 별도 케이스 "실결제 장애 대응"에 정리했습니다.
- 배포 경로 정비: 검증한 이미지를 재빌드 없이 승격하고 헬스체크가 실패하면 직전 태그로 자동 롤백하는 스크립트로 바꿔 main 머지 하나로 끝나는 운영 배포 40여 건을 사고 없이 수행했습니다.
GA4·BigQuery 계측 정합성과 외부 개발자 문서 통합
계측은 요청이 나갔다는 사실과 수신됐다는 사실이 다릅니다. 네트워크가 204를 줘도 수집이 0건이던 사례가 2건 있었습니다. 데이터 레이어에 배열을 push 해 큐는 소비되는데 수집이 없던 것, 이벤트 파라미터명이 GA4 예약어와 겹쳐 덮인 것입니다. 전송 페이로드를 직접 실측해 둘을 가르는 판정 절차를 세웠습니다.
- 저장소 역할 분리: 보고와 판정에 쓰는 수치는 GA4에서 BigQuery 한 곳으로 모으고 실시간 탐색은 PostHog으로 나눴습니다. 자체 호스팅에서 클라우드로 옮긴 뒤 같은 시간 창과 공통 필터로 대조해 공통 방문자 155명 기준 845건 대 841건(차이 3.4%)으로 일치를 확인했습니다.
- 고객용 외부 문서 통합: 문서 원본과 서빙을 제품 웹 리포 안에 두기로 결정했습니다. 별도 리포는 코드가 바뀌어도 문서가 남고 외부 위키는 검색·AI 노출 장치를 우리가 통제할 수 없습니다. 구 문서 도메인은 전 경로 301로 합치고 현재 ko/en 33편을 서빙합니다.
- 다국어와 보안 정비: 하드코딩돼 있던 회원 콘솔 전반의 한국어를 ko/en 다국어로 일괄 전환했습니다(네임스페이스 23개, 키 약 2,500개). 해킹 시도를 계기로 HSTS·CSP·X-Frame-Options 등 보안 헤더를 정비하고 시크릿을 환경변수로 옮겼으며 dangerouslySetInnerHTML 구간에 DOMPurify와 Server Actions 입력 검증을 붙였습니다.
결과
- 8개 도메인 175개 경로: 인벤토리를 전수 대조해 화면 전체를 v2로 이관, 정식 운영(LIVE)
- 실서버 e2e 40케이스 · 단위 테스트 391건 · 실카드 결제·환불 15건: 통과 기준
- 가입 진입점 8곳 → 전역 인증 모달 하나: next 파라미터로 목적지 복귀
- 라우트 54개 중 53개: 직접 작성, 가입에서 체험·결제까지 풀사이클 운영 중
- 계약 드리프트 검출 스크립트: OpenAPI 정본과 구현을 대조해 어긋난 경로를 목록으로 출력
- 목 서버 레이어 9,341줄 교체: 실서버 스모크로 대체, CI 단위 테스트를 브랜치 보호 필수 체크로
- 계측 정본 일원화: GA4에서 BigQuery로, PostHog 대조 결과 차이 3.4%
- 고객용 외부 문서 ko/en 33편: 구 도메인 전 경로 301 통합
- main 머지가 곧 운영 배포: 검증한 이미지를 재빌드 없이 승격, 헬스체크 실패 시 자동 롤백, 40여 건 무사고
정리
이 웹에서 가장 중요한 일은 화면을 늘리는 쪽보다 인지에서 인증·결제·사용으로 이어지는 동선을 끊기지 않게 지키는 쪽이었습니다. 눈으로 확인하는 대신 API 계약을 테스트로 고정해 두었기에 175개 경로를 끊김 없이 옮길 수 있었고 계측도 숫자가 나왔다는 것과 맞는 숫자라는 것을 가르는 절차를 세우고 나서야 보고에 쓸 수 있었습니다.
