향그리움 (K-Nostalgia)

전통 시장 특산품 커머스 플랫폼

결제·환불 도메인을 중심으로 서비스 안정성 설계에 집중한 프로젝트입니다.
브라우저 뒤로가기 제어, 웹훅 기반 환불 자동화, 쿠폰 서버 검증 등 결제 신뢰성 확보에 주력했습니다.



담당 기능

  • 결제 플로우 설계 및 구현

    • 쿠폰 시스템
    • 배송지 관리
    • 결제 흐름 구현 및 UX 최적화
      • 브라우저 뒤로가기 제어, 상태 분기
  • 결제 후처리 및 운영 안정성

    • 주문 내역 관리 및 환불 처리
    • 웹훅 기반 결제 취소 이벤트 자동 동기화
    • 쿠폰 복구 로직 자동화
  • 운영 지원 기능: FAQ/공지사항 페이지, 리뷰 시스템

개발 기간

📦 MVP 2024.07 - 2024.08

결제 플로우, 주문 내역 및 리뷰 시스템 구현

🔄 v2 2024.09 - 2025.09 : 지속적 개선

쿠폰 서버 검증, 배송지, UX 최적화 등


팀 규모 FE 5 UX/UI 1

🔗 향그리움 배포 링크 🔗 깃허브 링크



대표 문제 해결 사례

결제 도메인 전체 안정성 확보

해결한 문제

  1. 브라우저 뒤로가기 시 결제창 잔존 → popstate 이벤트 제어로 결제 상태 일관성 유지 섹션 바로가기

  2. 가결제 자동 환불 시 주문 상태 불일치 → 웹훅 연동으로 서버 중심 상태 관리 자동화 섹션 바로가기

  3. 클라이언트 쿠폰 위변조 가능성 → 할인 계산을 서버 라우트로 이동 섹션 바로가기

임팩트

  • 결제 오류로 인한 CS 문의 가능성 사전 차단
  • 운영 단계에서 수동 환불 처리 부담 감소
  • 결제 신뢰성 확보 및 도메인 로직 일관성 유지


기술 스택

  • Next.js typescript
  • 상태 관리 : React-query Zustand
  • 스타일링 :Tailwind shadcn swiper
  • Supabase port-one


구현 상세

1. 브라우저 뒤로가기 시 결제창 잔존 문제 해결

결제 플로우 및 환불 처리 구조는 요구사항 정리부터 설계, 구현까지 주도적으로 담당했습니다. 개선 시점: mvp 당시(24.08)

문제 상황

결제창이 켜진 채 브라우저 뒤로 가기 사용 시 결제 팝업 잔존하는 문제가 발생했습니다. 이는 실제 사용자 테스트 과정에서 발견된 치명적인 UX 이슈였습니다.

판단

결제는 금전 이동이 발생하는 민감한 구간으로, 예외적인 브라우저 동작까지 고려한 명확한 상태 제어가 필요했습니다.

고려한 대안

  • 클라이언트 상태로 결제창 열림/닫힘을 추적하는 방식 → 새로고침, 강제 종료 등 예외 케이스 대응 불완전

선택한 방식

  • 라우팅 구조 자체를 결제 흐름에 맞게 설계 (/payment → /check-payment → /complete-payment)
  • popstate 이벤트로 히스토리 변경 감지 및 결제창 제어

해결

  1. 결제 전·중·후 단계를 명확히 분리한 라우팅 구조 설계 (/payment > /check-payment > /complete-payment)
  2. popstate 이벤트를 활용해 브라우저 히스토리 변경 시 결제창 종료 안내 토스트 출력
  3. 결제 성공/실패에 따른 상태 분기 로직 분리

결과

popstate 흐름 gif
  • 뒤로 가기 사용 시 결제창 잔존 문제 해결
  • 결제 플로우 전반에서 예측 가능한 사용자 경험 확보
  • 결제 오류로 이어질 수 있는 CS 문의 가능성 사전 차단


2. 주문 취소시 DB 상태 자동 동기화 (Webhook)

개선 시점: mvp 당시(24.08)

문제 상황

이 서비스는 포트원의 가결제(사전 승인) 방식을 사용합니다. 가결제는 결제 승인 후 실제 청구 전까지 일정 시간(당일 자정)이 주어지며, 이 기간 내 실결제 전환이 없으면 자동으로 취소됩니다.

초기에는 이 자동 취소 이벤트를 서버가 인지하지 못해 주문 상태는 "결제 완료"로 남고 실제로는 환불된 상태가 발생했습니다.

판단

환불로 인한 결제 상태 변경은 클라이언트 요청만이 아닌 결제사 이벤트를 기준으로 서버가 주도적으로 상태를 관리해야 한다고 판단했습니다.

해결

  • 포트원 결제 취소 이벤트 웹훅 연동
  • 서버 라우트에서 결제 취소 이벤트 수신 후 주문 상태 자동 업데이트
  • 환불 시 사용 쿠폰 자동 복구 처리
  • ngrok을 활용한 로컬 웹훅 테스트

결과

  • 결제 상태와 주문 데이터의 실시간 동기화
  • 수동 개입 없이 환불·쿠폰 복구가 처리되는 안정적인 결제 운영 구조 확보
  • 운영 단계에서 수동 환불 처리에 대한 부담 감소


3. 쿠폰 시스템 구조 개선

개선 시점: 추가 구현 시점(25.06)

쿠폰 흐름 gif

문제 상황

초기 MVP에서는 쿠폰 할인 금액을 클라이언트에서 계산하여 결제 API에 전달하는 구조였습니다.

이는 빠른 프로토타이핑에는 유리했지만, 클라이언트 조작 가능성과 서버-클라이언트 간 할인 금액 불일치 리스크가 존재했습니다.

판단

쿠폰은 단순 UI 편의 기능이 아닌 결제 신뢰성과 직결되는 도메인 로직이라고 판단했습니다.

해결

  • 쿠폰을 독립적인 DB 테이블로 분리
  • 할인 금액 계산을 서버(Route Handler)에서 수행하도록 구조 변경

결과

  • 클라이언트 위변조 가능성 제거
  • 결제/환불/쿠폰 복구 로직을 일관된 서버 기준으로 관리 가능


4. 배송지 관리 기능 구현 및 상태 일관성 개선

개선 시점: 추가 구현 시점(25.08)

배송지 흐름 gif

문제 상황

배송지 정보가 마이페이지와 결제 페이지에 분산되어 페이지 이동 시 데이터 불일치가 발생했습니다. 결제 과정에서 배송지 변경이 즉시 반영되지 않는 UX 문제가 존재했습니다.

판단

배송지는 결제 플로우 전반에서 참조되는 핵심 상태이므로, 페이지 단위 상태가 아닌 전역 상태로 일관되게 관리해야 한다고 판단했습니다.

해결

  • 배송지 CRUD 로직을 전역 상태(Zustand)로 분리
  • 마이페이지와 결제 페이지가 동일한 상태 소스를 참조하도록 구조 통합
  • 입력 검증, 선택, UI 전환을 하나의 흐름으로 관리

결과

  • 페이지 이동 및 결제 과정에서 배송지 데이터 일관성 확보
  • 사용자 입장에서 배송지 변경이 즉시 반영되는 안정적인 UX 제공


5. 공용 컴포넌트 설계 및 재사용성 확보

문제 상황

주문 내역, 리뷰 작성, 배송지 선택 등 여러 화면에서 유사한 모달/풀스크린 UI가 반복적으로 필요했습니다.

각 화면마다 버튼 텍스트, 레이아웃, 동작이 조금씩 달라 매번 새로 구현하면서 코드 중복이 누적되었습니다.

판단

UI 레벨에서 반복되는 패턴은 조기에 컴포넌트화하지 않으면 추후에 일관성을 유지하기 어려울것으로 판단했습니다.

해결

  • 용도에 따른 매개 변수를 받아 그에 따라 변동되는 공용 UI 컴포넌트 구현
    • 데스크탑: 모달 / 모바일: 풀스크린 구조 등
  • 결제 버튼, 아코디언, 라디오 그룹 등 공용 UI 컴포넌트 정리
  • 연속 클릭으로 인한 이벤트 오류 방지를 위한 커스텀 훅 분리 (useThrottle)

결과

  • UI 일관성 및 재사용성 확보
  • 신규 기능 추가 시 UI 구현 비용 감소


6. 디자이너와의 협업 - 자동 환불 안내 UI

디자이너와의 협업 사례

자동 환불 안내 문구 표기 방식에서 의견 차이가 발생했습니다.

문제 상황

  • 텍스트 노출 방식은 명확하지만, 모바일에서는 가독성 저하 우려

해결 과정

  • 디자이너의 제안으로 툴팁 형태의 UI를 도입
  • 사용자가 인식하지 못할 가능성을 고려하여 툴팁 미사용 시 강조 표시를 함께 적용
  • 시각적 부담은 줄이면서 정보 접근성을 유지하는 방향으로 합의
툴팁 이미지 gif


회고

지속적으로 개선한 프로젝트

MVP 완성 후에도 1년 넘게 코드를 지속적으로 개선해온 프로젝트입니다.

개선 동기

  • 초기 MVP에서 빠른 구현을 위해 타협했던 구조적 한계 해결
  • 결제 도메인 특성상 예외 케이스와 보안을 더 견고하게 설계하고 싶었음
  • 실무에서 필요한 기술(웹훅, 서버 검증)을 깊게게 구현해보며 학습

배운 점

  • 초기 MVP에서는 빠른 검증을 우선하되, 이후 단계적으로 구조를 개선하는 전략의 중요성
  • 프론트엔드에서도 도메인 로직의 책임 경계를 명확히 설계하는 것이 장기 유지보수에 직결됨
  • 결제 같은 민감한 도메인은 초기부터 서버 중심 검증 구조가 필요함을 체감

아쉬운 점

  • 실사용자 피드백 기반 우선순위 결정의 부재 → 다음 프로젝트에서는 소규모 사용자 테스트 병행 계획
  • 성능 모니터링 도구 미도입 → 로그 수집과 지표 추적의 중요성 인지