예약 운영·결제 대사 통합 관리 플랫폼
MVP 이후 확장 방향으로 예약 운영 캘린더, 결제 대사와 웹훅 로그, 환불 관리, 다국어·다중 통화 및 외부 플랫폼 확장 데이터 모델을 통합한 구현한 프로젝트입니다.
프로젝트 개요
MVP 이후 확장 방향으로 예약 운영 캘린더, 결제 대사와 웹훅 로그, 환불 관리, 다국어·다중 통화 및 외부 플랫폼 확장 데이터 모델을 통합한 구현한 프로젝트입니다. P1과 같은 Node.js·Express·PostgreSQL·Prisma 스택에 Redis 기반 멱등성 저장소를 더해 설계합니다.
작업 범위
- 예약 운영 캘린더 모니터링: 관리자가 파트너별 리소스 타임라인에서 예약·홀드·차단 블록을 한눈에 보고 우측 대기열에서 처리합니다
- 결제 대사·웹훅 로그: 결제 거래와 예약 상태를 대조하고 웹훅 수신 이력과 재처리 대상을 확인합니다
- 환불·부분 환불 관리: 환불 요청을 접수하고 전액·부분 환불을 PSP에 요청한 뒤 결과를 추적합니다
- 다국어·다중 통화·확장 데이터 모델: 고객 언어와 통화를 전환하고 외부 예약 플랫폼 연동을 대비한 채널 구조를 관리합니다
주요 업무
- 예약 운영 캘린더 모니터링 화면: 주간 타임라인과 슬롯 사이드 패널을 구성하고 상태별 블록 색을 무채색 위계로 구분합니다
- 결제 대사·웹훅 로그 화면: 웹훅 서명 검증과 멱등성 키 기록을 로그 화면에서 추적할 수 있게 구성합니다
- 환불·부분 환불 관리 화면: 환불 상태 전이와 예약 취소 정책을 연결하고 환불 웹훅으로 최종 상태를 반영합니다
- 다국어·다중 통화·확장 데이터 모델 화면: 통화별 금액 표기와 언어 리소스를 설정 화면에서 관리하고 예약 채널 필드를 모델에 포함합니다
프로젝트 핵심 과제
웹훅 중복·순서 역전 도착 시 결제 상태를 일관되게 유지하는 멱등성 및 이벤트 순서 보정 설계
부분 환불과 취소 정책이 겹칠 때 정산 금액을 재계산하는 규칙과 트랜잭션 경계 설계
통화별 소수 자릿수 차이를 반영한 금액 저장·표시 규칙을 일관되게 적용하는 모델 설계
외부 예약 플랫폼 연동을 대비한 채널 구조가 현재 예약 흐름을 복잡하게 만들지 않
확장 지점을 분리하는 설계 필요
핵심 기능 상세
예약 운영 캘린더 모니터링
관리자가 파트너별 리소스 타임라인에서 예약·홀드·차단 블록을 한눈에 보고 우측 대기열에서 처리합니다. 주간 타임라인과 슬롯 사이드 패널을 구성하고 상태별 블록 색을 무채색 위계로 구분합니다.
- 파트너별 리소스 타임라인을 가상 렌더링하는 캘린더 컴포넌트 설계
- 예약 상태 변경을 SSE로 구독해 타임라인에 반영하는 구조 적용
- 블록 드래그 변경 시 서버 검증 결과로 낙관적 UI를 되돌리는 패턴 구현
예약·홀드·차단 상태를 한 타임라인에 겹쳐 보여 운영자가 충돌 구간을 바로 식별하도록 설계합니다.
결제 대사·웹훅 로그
결제 거래와 예약 상태를 대조하고 웹훅 수신 이력과 재처리 대상을 확인합니다. 웹훅 서명 검증과 멱등성 키 기록을 로그 화면에서 추적할 수 있게 구성합니다.
- Redis에 멱등성 키를 저장하고 중복 웹훅을 무시하는 구조 설계
- 웹훅 이벤트 원본을 PostgreSQL에 보관해 재처리 큐에서 재실행하는 흐름 구현
- 결제 거래와 예약 상태 불일치를 SQL 대조 쿼리로 목록화
같은 웹훅이 여러 번 도착해도 결과가 한 번만 반영되도록 멱등성 키와 이벤트 보관 구조를 구현합니다.
환불·부분 환불 관리
환불 요청을 접수하고 전액·부분 환불을 PSP에 요청한 뒤 결과를 추적합니다. 환불 상태 전이와 예약 취소 정책을 연결하고 환불 웹훅으로 최종 상태를 반영합니다.
- 환불 요청 상태 머신(요청·진행·완료·실패) 전이 표 설계
- 취소 시점별 환불 비율 정책을 Strategy 패턴으로 분리
- 환불 결과 웹훅 수신 시 정산 금액을 재계산하는 트랜잭션 구성
취소 정책과 환불 금액 계산을 정책 객체로 분리해 시점별 규칙 변경이 화면과 API에 번지지 않도록 설계합니다.
다국어·다중 통화·확장 데이터 모델
고객 언어와 통화를 전환하고 외부 예약 플랫폼 연동을 대비한 채널 구조를 관리합니다. 통화별 금액 표기와 언어 리소스를 설정 화면에서 관리하고 예약 채널 필드를 모델에 포함합니다.
- i18n 리소스 키 구조와 언어 폴백 규칙 설계
- 금액을 최소 통화 단위 정수와 통화 코드로 저장하는 모델 적용
- 예약 채널 테이블로 외부 플랫폼 연동 확장 지점 분리
금액·통화·채널을 모델 단계에서 분리해 해외 확장과 외부 플랫폼 연동 시 스키마 변경 범위를 줄이도록 설계합니다.
프로젝트 진행 단계
확장 데이터 모델과 통화·채널 스키마 설계 · 2026.10
최소 통화 단위 금액, 언어 리소스, 예약 채널 테이블 정의 및 P1 스키마와의 관계 매핑
웹훅 수신·멱등성 저장소 구현 · 2026.10
서명 검증 웹훅 엔드포인트와 Redis 멱등성 키, 이벤트 원본 보관 테이블 구현
대사·환불 API 및 정책 객체 개발 · 2026.10
결제-예약 대조 쿼리와 환불 상태 전이, 취소 시점별 환불 정책 객체 구현
운영 캘린더 및 관리 화면 구성 · 2026.10
리소스 타임라인, 대사·웹훅 로그, 환불, 언어·통화 설정 화면을 React로 구성
개발 결과
기술적 주안점
- 예약·홀드·차단 상태를 한 타임라인에 겹쳐 보여 운영자가 충돌 구간을 바로 식별하도록 설계합니다
- 같은 웹훅이 여러 번 도착해도 결과가 한 번만 반영되도록 멱등성 키와 이벤트 보관 구조를 구현합니다
- 취소 정책과 환불 금액 계산을 정책 객체로 분리해 시점별 규칙 변경이 화면과 API에 번지지 않도록 설계합니다
