Skip to content

fix(payment): PayPal 응답과 장애 계약을 바로잡는다 - #446

Merged
Neo1228 merged 1 commit into
mainfrom
fix/444-paypal-prefer-representation
Nov 20, 2026
Merged

Neo1228 merged 1 commit into
mainfrom
fix/444-paypal-prefer-representation

Conversation

@Neo1228

@Neo1228 Neo1228 commented Nov 20, 2026

Copy link
Copy Markdown
Owner

변경 요청 (Pull Request)

목적

  • 해결할 문제: 실제 PayPal Sandbox에서 두 결함을 확인했다. (1) 장애가 없는 정상 결제도 승인 복귀 응답이 paymentState=UNKNOWN이었고, 복구 worker가 주문을 다시 조회한 뒤에야 PAID가 됐다(관측 최대 25초). (2) 승인 반영 중 PayPal 연결이 지연·실패하면 HTTP 500이 나고, 결제가 AUTHORIZATION_PENDING에 고착됐다(180초 내 미수렴).
  • 변경이 필요한 이유: 구매자는 결제가 끝났는데도 "확인 중" 상태를 보고, 모든 정상 capture가 복구 큐를 거친다.

변경 범위

  • 포함: PayPal JSON POST에 Prefer: return=representation 추가, 테스트 stub이 PayPal 기본(minimal) 응답을 재현하도록 변경. getOrder·voidAuthorization의 RestClientException을 다른 호출과 같이 PayPalUnavailableException으로 감싼다.
  • 제외: 금액 검증 로직 자체(그대로 유지), 복구 worker 동작.

근거와 설계

  • 확인된 사실·가정: 실제 Sandbox에서 같은 authorization에 부분 capture 두 번을 보냈다. 헤더가 없으면 응답 키는 id, links, status뿐이었고, Prefer: return=representation이면 amount를 포함한 전체 표현이 왔다. ATLAS는 capture 응답의 amount로 providerAmountMatches를 검사하므로, 헤더가 없으면 성공 capture가 UNKNOWN이 된다.
  • 결정과 이유: 금액 검증(ADR-0030의 금액·통화 일치 조건)은 약화하지 않고, 검증에 필요한 응답을 명시적으로 요청한다. 공통 post()에 넣어 주문 생성·승인·capture·환불이 같은 계약을 쓴다. 감싸지 않은 두 호출은 서비스의 PAYMENT_PROVIDER_UNAVAILABLE → UNKNOWN 처리를 건너뛰어 500이 됐다. 같은 예외 계약을 적용해 기존 복구 경로를 탄다.
  • 대안·trade-off: (1) amount 가 없으면 GET 으로 재조회 → 요청 1회 추가·지연 증가. (2) amount 없을 때 요청 금액을 신뢰 → 금액 검증 약화. 둘 다 채택하지 않았다. 응답 크기는 조금 커진다.
  • 데이터·API·상태 영향: DB·HTTP API 변경 없음. 정상 capture가 즉시 CAPTURED로 기록된다.
  • 영향 범위 (dependency·plugin·runtime·test·build): 새 의존성 없음. 테스트 stub(PayPalIntegrationTestSupport)이 실제 PayPal처럼 Prefer가 없으면 minimal 응답을 준다.
  • 검증 근거와 한계: 실제 Sandbox 정상 경로에서 수정 전 return 응답 UNKNOWN(5.4s, 6.0s) → 수정 후 CAPTURED(5.05.5s), PAID 수렴 0.1s 이내. 승인 반영 단계 장애(3s 지연·응답 유실·reset, 조건당 3건): 수정 전 500·고착 → 수정 후 9/9 PAID, PayPal capture 각 1건, 수렴 0.143.5s. 표본이 작아 지연 분포는 판단하지 않는다. 환불은 실제 Sandbox에서 확인하지 않았다.

시각화

  • Diagram 또는 N/A 사유: N/A. 단일 HTTP 헤더 계약 변경이며 상태 전이는 바뀌지 않는다.

추적

변경 요약

  • 변경: PayPal POST 요청에 Prefer: return=representation 추가, stub 이 PayPal 기본 minimal 응답을 재현, 주문 조회·void 장애를 provider 장애로 감쌈.

검증

위험·후속 작업

  • 알려진 위험·한계: 환불 경로는 실제 Sandbox 로 검증하지 않았다(stub 계약으로만 확인).
  • 후속 작업: 실제 Sandbox 환불 경로 측정.

검토 체크리스트

  • 변경 범위가 하나의 목적과 검토 가능한 경계에 맞음.
  • 실행하지 않은 검증·성과를 주장하지 않음.
  • 데이터·보안·금전 상태·복구 영향을 검토함; 영향 없음은 구체적인 N/A 사유로 설명.
  • Issue 번호·링크가 일치하며 Closes #N 또는 Refs #N 형식이 plain text임.
  • 복잡한 변경의 사실·가정·근거·영향을 본문에서 설명함; 링크만으로 대체하지 않음.
  • API 변경 시 오류/status contract와 GET의 side effect를 확인함; 무관하면 구체적인 이유 작성. (HTTP API 변경 없음)
  • 필요한 경우 Mermaid diagram으로 계층·상태 흐름을 설명함. (N/A 사유 기재)
  • Java 주석은 한국어; API 식별자와 오류 코드는 임의로 바꾸지 않음.
  • 체크리스트 전체 완료; N/A 항목은 구체적인 사유를 포함함.

- capture 응답에서 금액 검증이 가능하도록 Prefer: return=representation 을 요청한다.
- 주문 조회와 authorization void 연결 오류를 PayPalUnavailableException 으로 감싸 복구 경로에 전달한다.
- MockWebServer 가 PayPal 기본 minimal 응답을 재현하고, 닫힌 포트 회귀 테스트를 추가한다.
- 검증: payment-module 단위 테스트 통과; clean check 596 tests / 0 failures.

Closes #444
@Neo1228
Neo1228 merged commit 6611ba5 into main Nov 20, 2026
3 checks passed
@Neo1228
Neo1228 deleted the fix/444-paypal-prefer-representation branch November 20, 2026 18:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[버그]: PayPal 응답·장애 계약 불일치로 정상·장애 결제가 UNKNOWN 또는 500으로 끝난다

1 participant