<aside> 🛠️
백엔드 프로젝트 상세 페이지
</aside>
| 💰 스토어 기능 전체 구현 파트너/콜라보 상품, 장바구니, 주문, 배송, 환불, 디지털 상품, 정산까지 End-to-End 완성 | 📈 DB 마이그레이션 성공 store_orders 1개 → 5개 테이블 구조로 확장 | 🤖 정산 파이프라인 확장 withdrawal_type 기반 3-way 분기 정산 구조 구현 | | --- | --- | --- |
| Runtime | Node.js (TypeScript) + Deno (Supabase Edge Functions |
|---|---|
| Framework | Express.js (REST API 서버) |
| Database | Supabase Postgres (RLS 적용, Row Level Security) |
| Infra / Serverless | Supabase Edge Functions, Cron Jobs, Database Webhooks |
| External API | TossPayments v1 (결제 승인/취소) · v2 (지급대행 - JWE 암호화) |
| 배송 추적 | tracker.delivery GraphQL API (OAuth 2.0 Bearer) |
| Observability | Supabase Logs, 구조화 console 로그 (emoji prefix), Sentry (Error Tracking) |
| Tools | Cursor (AI-Driven Dev), Postman, Git / GitHub |
| Sprint 1 | 스토어 기반 구조 설계 및 상품/배너 API 구현 |
|---|---|
| • store_products, store_banners, store_recommended Edge Function 구현 — 파트너/콜라보 상품 분기, 재고 관리, 옵션 가격 합산 로직 포함 | |
| • store_schedules (일정 상품) Edge Function 구현 — 날짜별 예약 가능 인원 관리 및 현장 상품 처리 | |
| • RLS 정책 적용으로 파트너 간 데이터 격리, 공개 조회와 인증 조회 분리 | |
| • 임팩트: 파트너사별 상품 독립 운영 기반 완성, 향후 콜라보 확장 가능한 source 필드 설계 | |
| Sprint 2 | 주문 핵심 플로우 — 장바구니 → 주문 → TossPayments 결제 연동 |
| • store_cart Edge Function 구현 — 파트너/콜라보 상품 혼합 장바구니, 묶음배송 그룹핑, 제주/울릉도 산간지역 배송비 자동 분기 | |
| • store_orders Edge Function 구현 — 단일 테이블 설계로 주문 생성/조회/상태 변경 구현 | |
| • payment_route (Express) 구현 — TossPayments v1 결제 승인(POST /confirm), 만료 재처리, 중복 방지(S008 에러 핸들링), 포인트 충전 연동 | |
| • store_digital Edge Function 구현 — 디지털 상품 주문 즉시 완료 처리, order_id 기반 파일 접근 권한 발급 (order_item_id 하위 호환 병행 지원) | |
| • 임팩트: 결제 → 포인트 적립 → 주문 생성까지 단일 트랜잭션 흐름 완성 | |
| Sprint 3 | 정산 파이프라인 확장 및 DB 마이그레이션 |
| • store_orders 단일 테이블 → 5개 테이블 DB 마이그레이션 (store_orders, store_order_items, store_order_item_options, store_shipments, store_shipment_items) — 장바구니 다중 상품·배송 분리 지원을 위한 구조 개선 | |
| • store_refunds Edge Function 구현 — order_item_id 기준 아이템별 환불 요청, TossPayments 취소 API 연동, 포인트 환원 로직. 환불 처리 시 배송 완료 건에 대해 배송비를 파트너 store_points에 귀속하는 배송비 수익 보전 로직 추가 | |
| • TossPayments 지급대행(v2) 정산 로직 확장 — withdrawal_type(total_points / store_points / collaboration_store_points) 별 3-way 분기: 티어 기반 fee_policy / default_distribution_rate / 100% 전액 지급. 콜라보 상품은 distribution_rate 여부와 무관하게 collaboration_store_points에, 개인 상품은 반드시 store_points에 적립하도록 포인트 계정 분기 명확화 | |
| • cron-store-auto-confirm 구현 — 구매 확정 미처리 주문 자동 확정 배치 | |
| • 임팩트: 스토어 수익 정산 자동화, 콜라보/개인상품 포인트 계정 분리 완성, 환불 시 파트너 배송비 수익 자동 보전 | |
| Sprint 4 | 운영 안정화 — 배송 추적, 웹훅, 가드 로직 강화 |
| • 배송 추적 통합 — tracker.delivery OAuth 2.0 Bearer 토큰 캐시(메모리), GraphQL API 연동, 9개 택배사 carrierId 매핑 | |
| • TossPayments 웹훅(seller.changed) 수신 처리 — 서명 검증(HMAC SHA-256), JWE 복호화, partner_business_info 자동 업데이트 | |
| • Payout 스케줄링 — date-holidays 라이브러리로 한국 공휴일 제외 다음 평일 오전 10시 자동 계산 | |
| • Admin 전용 라우트 분리 — requireAdmin 미들웨어, 파트너 승인 · 정산 처리 · 출금 관리 API 보호 | |
| • 임팩트: 운영팀의 수동 개입 없이 정산~지급 전 과정 자동화, 모니터링 가시성 향상 |
기존 total_points 기반의 단일 정산 파이프라인을 유지하면서, 신규 도입된 스토어 수익 모델을 수용하기 위해 **기존 로직을 파괴하지 않는 '확장형 분기 구조'**를 설계했습니다. withdrawal_type이라는 구분자를 도입하여 기존 파트너와 신규 스토어 파트너의 정산 로직이 공존할 수 있게 했습니다.
| withdrawal_type | 정산 로직 |
|---|---|
| total_points | fee_policy 테이블의 파트너 티어 기반 partner_share_pct 적용 (기본 bronze → 75%) |
| store_points | partner_business_info.default_distribution_rate 적용 (파트너별 협의 분배율) |
| collaboration_store_points | 100% 전액 지급 (플랫폼 수수료 미적용, 콜라보 수익 전액 파트너 귀속) |
실제 지급 금액 계산 공식:
지급 스케줄: date-holidays(KR) 라이브러리로 한국 공휴일 및 주말 제외, 다음 평일 오전 10시로 자동 설정. 요청/응답 모두 JWE(JSON Web Encryption, jose 라이브러리) 암호화 적용.