플러스프로젝트 배경
1) 예상 리스크 및 대응 계획 - 토스페이먼츠 부분 취소 시 가용 환불 금액 계산이 복잡할 수 있으므로 — Zod 스키마로 입력값을 검증하고 DB의 누적 환불 금액과 비교하는 서버사이드 유효성 검사 레이어를 설계하여 대응합니다. - 웹훅 이벤트 중복 수신(재시도) 시 결제 상태가 오염될 수 있으므로 — WebhookLog의 idempotency key를 활용한 중복 처리 방지 로직을 구현하여 대응합니다.
프로젝트 성과
Server Action 게이트웨이로 PG 시크릿 키를 서버에 격리하는 환불 구조를 구현
Server Action을 게이트웨이로 사용해 PG 시크릿 키를 서버에 격리하고, Prisma 트랜잭션으로 환불 상태 업데이트와 로그 기록을 원자적으로 처리하는 구조를 설계합니다.
미들웨어·Server Action 이중 권한 검증으로 보안 레이어를 구현
middleware.ts에서 라우트 가드를 적용하고 Server Action 내부에서도 역할을 재검증하여 두 레이어를 모두 통과해야 민감 작업이 실행되도록 설계합니다.
웹훅 HMAC 서명 검증과 결제 상태 자동 동기화 파이프라인을 구현
토스페이먼츠 웹훅 수신 시 HMAC 서명을 검증하고, 검증 통과 후 Prisma로 결제 상태를 업데이트하며 WebhookLog에 이벤트를 적재하는 비동기 파이프라인을 구현합니다.
Prisma 커서 기반 페이지네이션으로 대용량 결제 데이터 조회 구조를 설계
offset 방식 대신 커서 기반 페이지네이션을 채택하여 데이터 증가에도 일정한 쿼리 성능을 유지하고, URL searchParams 기반 필터 상태 관리로 조회 조건이 유지되도록 구현합니다.
핵심 기능
결제 대시보드
전체 결제 현황을 한눈에 파악할 수 있는 메인 대시보드 화면을 제공합니다. 일별/주별/월별 결제 집계를 차트로 시각화하고, 결제 상태별(승인/취소/실패) 건수와 금액을 카드 컴포넌트로 표시합니다
진행 단계
DB 스키마 설계
2026.04.
Prisma로 Payment/Refund/WebhookLog 모델 설계 및 마이그레이션
프로젝트 상세
1) 포트폴리오 소개 Next.js 15와 토스페이먼츠 API를 연동하여 결제 승인·취소·환불을 중앙에서 통합 관리할 수 있는 어드민 대시보드를 설계하고 구현합니다. Prisma ORM 기반의 결제 데이터 스키마 설계, NextAuth 역할별 권한 제어, 실시간 결제 상태 추적 기능을 포함합니다. 2) 작업 범위 - 결제 대시보드: 전체 결제 현황을 한눈에 파악할 수 있는 메인 대시보드 화면을 제공합
