시스템 아키텍처 및 백엔드 설계서

⚙️ 통합 물리 아키텍처 토폴로지 🔑 Redis 기반 무중단 SSO 세션 공유 🔄 Saga 오케스트레이션 결제 트랜잭션 롤백 보장

본 문서에서는 두 애플리케이션의 물리적 단절을 영구 청산하기 위한 Next.js ➡️ API Gateway ➡️ Spring Boot 서비스군 구조와 Redis 캐시 공유를 통한 SSO 단일 회원 상태 유지, 그리고 분산 결제 보장을 위한 **오케스트레이션 Saga 엔진**을 정의합니다.

1. Redis 기반 공통 세션 및 SSO 설계

기존 서브도메인을 파괴하고 단일 도메인의 서브패스 `/donation`으로 병합함에 따라, Redis 세션 클러스터링을 통하여 회원 로그인 상태를 100% 동일하게 공유합니다. 쿠키 도메인은 `nolgofarm.com`으로 광역 세팅합니다.

🍪 발행 쿠키 속성 명세

Set-Cookie: sessionId=4a8c9f2d-7e1a...; 
Domain=nolgofarm.com; 
Path=/; 
Secure; 
HttpOnly; 
SameSite=Lax

💾 Redis 세션 캐시 스펙 (JSON)

Key: session:4a8c9f2d-7e1a-4d3b...
Value: {
  "userIdx": 10294,
  "userName": "홍길동",
  "legalRegionCode": "4571000000",
  "role": "MEMBER"
}
TTL: 7200s (2 Hours)

2. Saga 패턴 기반 통합 결제 트랜잭션

여행 상품 예약 결제(일반 PG사 승인 필요)와 고향사랑기부(e음 API 최종 승인 필요)를 단일 장바구니에서 처리할 때, 분산 환경에서의 정합성을 유지하기 위해 **오케스트레이션 Saga**가 승인 단계를 순차 관리하며, 실패 시 보상 트랜잭션(환불/롤백)을 수행합니다.

단계	수행 모듈	트랜잭션 세부 동작	장애 롤백 (보상 트랜잭션)
1. 주문 대기	결제 오케스트레이터	통합 장바구니 주문 원장 `orders` 및 `order_items` 생성 (상태: `PENDING`)	단순 상태 변경 (`FAILED`)
2. 기부 승인	행안부 e음 API	`EUM_DONATION_REQ` 통신하여 기부 수납 및 연 한도 차감 확정	`EUM_DONATION_CNL` 호출 ➡️ 기부 취소 및 연 한도 원상 복구
3. 예약 결제	일반 신용카드 PG	카드사 세부 결제 승인 후 승인 식별 키(`Tid`) 획득	카드 부분 취소 / 전체 취소 API 연동 ➡️ 즉시 한도 복구
4. 적립 및 확정	G-Point 지갑 모듈	주문 상태를 `COMPLETED`로 확정하고, 기부금의 30%를 `user_wallets`에 적립	적립 포인트 무효화 및 차감 롤백 실행