[FLOW] 결제·재고 예약 End-to-End API 플로우 (상세 미리보기 → 선점 → 의도 생성 → PG 승인 → 확정)

[pjhcsols]

어떤 기능인가요?

아래 순서로 호출하면 됩니다. (단건/장바구니 분기 포함, 실 URL 반영)

상세 페이지(미리보기)

1. 할인 견적
   GET /b1/discounts/quote?productId={pid}&userId={uid}

• 용도: 브랜드 할인 등 “현재가” 미리보기.

2. 적용/다운로드 가능한 쿠폰 목록
   GET /b1/coupons/products/{pid}/claimables?normalUserId={uid?}

• 용도: 해당 상품에 대해 보유/다운로드/적용 가능 쿠폰 미리보기.

• 비로그인 시 normalUserId 생략 가능.

• (예시)

  curl -X GET 'http://basilium.co.kr:8080/b1/discounts/quote?productId=1&userId=1'
  curl -X GET 'http://basilium.co.kr:8080/b1/coupons/products/1/claimables?normalUserId=hansol_user'
  

재고 선점

A) 단건 즉시구매
POST /b1/payment/request

• Params: productId, count, productSize, productColor
• 권한: ROLE_NORMAL & 본인
• 응답: reserveTaskOrderPayId (RID), expiresAt, items[]

B) 장바구니 일괄
POST /b1/payment/request-batch

• Body: {"items":[{"productId", "count", "productSize", "productColor"}, ...]}
• 권한: ROLE_NORMAL & 본인
• 응답: RID, expiresAt, items[]

(옵션) 예약 상태 폴링
GET /b1/payment/reservations/{rid} → ACTIVATED/INACTIVE, expiresAt

결제 의도 생성(최종 금액 스냅샷: 할인+쿠폰+포인트)

POST /b1/payment/intents

• Body:

{
  "orderId": "<RID>",        // 위 단계 RID를 그대로 사용
  "currency": "KRW",
  "pointsToUse": 0,
  "expiresAt": null,
  "lines": [
    {
      "productId": 1,
      "size": "M",
      "color": "BLACK",
      "quantity": 2,
      "couponWalletId": 999   // 선택(주문당 1개 제한, 서버 검증)
    }
  ]
}

• 권한: ROLE_NORMAL & 본인
• 응답: paymentId, orderId(=RID), serverTotal, pgAmount, intentExpiresAt

PG 승인 시도(외부)

• PG에 amount = pgAmount, orderId = RID 로 승인 요청

결제 결과 반영(프론트→백엔드 콜백)

성공 콜백
GET /b1/payment/success?paymentType={CARD...}&amount={pgAmount}&orderId={RID}&paymentKey={...}

• 권한: ROLE_NORMAL & 본인
• 서버 처리: 금액 일치 검증 → (권장 순서) 지갑 DEBIT → 라인 APPROVE → Payment APPROVE

실패 콜백
GET /b1/payment/fail?code=...&message=...&orderId={RID}

• 권한: ROLE_NORMAL & 본인
• 서버 처리: 라인 INIT→CANCELLED, Payment FAILED 기록

재고 예약 정리(필수)

성공 확정 → 복구 없이 인덱스만 제거
POST /b1/payment/response-by-reserve?reserveTaskOrderPayId={RID}&success=true

실패 확정 → 즉시 재고 복구
POST /b1/payment/response-by-reserve?reserveTaskOrderPayId={RID}&success=false

[pjhcsols]

기능 요약: Coupon / Discount / Wallet(포인트)

1) Coupon (브랜드 발급·사용)

• 브랜드 유저

  • 쿠폰 유효 기간(시작/종료) 설정 가능.
  • 발급(수량) 한도 설정 가능.
  • 기간 만료 시 자동 폐기(사용 불가 전환).

• 일반 유저

  • 유효 기간 동안 쿠폰 발급(클레임) 가능.
  • 내가 해당 쿠폰을 이미 받았는지 조회 가능.
  • 상품 상세/결제 전 미리보기 시 쿠폰 적용 가능 여부와 예상 할인 금액 확인 가능.

• 가격 계산 규칙

  • 브랜드 할인 → 쿠폰 할인 → 포인트 순으로 적용.
  • 주문당 쿠폰 1장만 사용(서버에서 강제 검증).
  • 쿠폰은 소유권/상태(AVAILABLE), 적용 범위(브랜드/특정 상품), 최소 주문 금액, 최대 할인 한도 등을 서버에서 검증 후 적용.
  • 만료/소진/소유권 불일치 시 적용 불가.

2) Discount (브랜드 할인 정책)

• 타깃형 할인: 특정 일반 유저에게만, 특정 상품(또는 전체 카탈로그)에 적용 가능.
• 상품 공용 할인: 특정 상품에 대해 모든 유저에게 적용.
• 기간/퍼센트 등 조건을 가질 수 있으며, 쿠폰보다 먼저 단가에 반영됨(쿠폰은 할인 후 금액에 적용).

3) Wallet(포인트) / 현실 현금과 분리

• 적립

  • 구매 및 리뷰 작성 등 정책에 따라 포인트 적립.
  • 유저는 보유 포인트 잔액/내역 조회 가능.

• 사용

  • 결제 시 사용 포인트를 선택해 총액에서 차감(브랜드 할인·쿠폰 적용 후).
  • 서버는 결제 승인 처리 시 포인트 차감(DEBIT) 을 수행(잔액 검증 포함).

• 정산/환불

  • 환불 시 포인트는 정책에 따라 복원/부분 복원(사업 규칙에 맞춰 처리).

4) 화면/연동 관점 핵심

• 상세 미리보기(할인/쿠폰 조회)

  • GET /b1/discounts/quote?productId=...&userId=... : 상품에 대한 브랜드 할인 견적.
  • GET /b1/coupons/products/{productId}/claimables?normalUserId=... : 해당 상품에 적용 가능한 다운로드/보유/적용 가능 쿠폰 목록.

• 결제 단계

  • 재고 선점(단건/배치) → 결제 의도 생성(브랜드 할인·쿠폰·포인트 반영 총액 스냅샷) → PG 결제 → 승인 확정(포인트 차감·라인/주문 승인) → 재고 확정.

요약: 브랜드는 기간/수량 제한 쿠폰과 타깃/공용 할인으로 가격 정책을 구성하고, 사용자는 상세/결제 단계에서 브랜드 할인 먼저, 쿠폰 그다음, 포인트 마지막 순으로 자동 차감된 최종 결제 금액을 확인·사용합니다. 포인트는 적립·사용·환불까지 전 과정이 서버에서 정합성 있게 관리.

[pjhcsols]

pg 승인을 위해 uuid 를 short 버전으로 변경하고 대신 현재 시간과 userId를 orderId로 만들어 비동기 로직에 사용되는 동시성과 키 중복 회피

[pjhcsols]

SecurityContextHolder.getContext().getAuthentication()은 현재 요청을 처리 중인 스레드에 바인딩된 Spring Security “보안 컨텍스트(SecurityContext)”에서 Authentication 객체를 꺼내옴. 한마디로, **“지금 이 요청을 보낸 주체(누구인지, 어떤 권한인지)”**를 나타내는 토큰.

코드 기준으로는 이렇게 채워집니다:

• 누가 넣나? → JwtFilter 가 유효한 Bearer 토큰이면
  new UsernamePasswordAuthenticationToken(userId, null, [ROLE_...])를 만들어 SecurityContextHolder에 set 합니다.
• 그래서 auth.getName() / (String) auth.getPrincipal() → JWT subject(= userId)
• auth.getAuthorities() → [ROLE_NORMAL] 같은 권한 컬렉션
• auth.getDetails() → 요청 정보(IP, 세션 등)
• auth.isAuthenticated() → 인증됨(true)

언제 없거나(또는 익명)일 수 있나?

• Authorization 헤더가 없음 / 필터 적용 제외 경로
• 토큰이 무효라 예외로 흐름이 끊김
• 비동기/별도 스레드(@async, Scheduler) 로 넘어가며 보안 컨텍스트가 복사되지 않은 경우
  (이땐 DelegatingSecurityContextExecutor 등 컨텍스트 전파가 필요)

실무 팁

• 컨트롤러에선 @AuthUser(프로젝트의 커스텀 어노)나 authentication.name(SpEL) 사용이 더 안전·명시적.

• 서비스에서 직접 참조가 필요하면 널/익명 가드:

  var auth = SecurityContextHolder.getContext().getAuthentication();
  if (auth == null || !auth.isAuthenticated() || auth instanceof AnonymousAuthenticationToken) {
      // 인증 안 된 상태 처리
  }

요약: “현재 로그인한 사용자의 인증/권한 정보를 가져온다”이고, 설정에선 그 principal이 로그인 아이디(userId) 로 세팅