#164 feat payment refund api

.github/workflows/reusable-build.yml

@@ -31,7 +31,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: 레포지토리 체크아웃
         uses: actions/checkout@v4
@@ -80,11 +80,46 @@ jobs:
             python3 -c "import yaml, sys; yaml.safe_load(open('$file'))" || exit 1
           done
 
+      - name: Docker 진단
+        run: |
+          set -eux
+          echo "=== docker version ==="
+          docker --version
+          echo "=== docker info ==="
+          docker info
+          echo "=== docker.sock ==="
+          ls -al /var/run/docker.sock || true
+          echo "=== env grep docker ==="
+          env | sort | grep -E 'DOCKER|TESTCONTAINERS' || true
+
+      - name: Identity 진단
+        run: |
+          set -eux
+          id
+          groups
+
+      - name: Relax docker.sock permission (CI)
+        run: |
+          set -eux
+          sudo chmod 666 /var/run/docker.sock
+          ls -al /var/run/docker.sock
+
+      - name: docker-java API version 강제 변경 (Docker 29 workaround)
+        run: |
+          set -eux
+          echo "HOME=$HOME"
+          mkdir -p "$HOME/.docker-java"
+          echo "api.version=1.44" > "$HOME/.docker-java.properties"
+          cat "$HOME/.docker-java.properties"
+
       - name: 빌드 및 테스트 (${{ inputs.module-name }})
         run: ./gradlew :${{ inputs.module-path }}:build --stacktrace
+        env:
+          # CI 환경에서 Testcontainers의 리소스 정리 컨테이너(Ryuk) 권한 문제를 방지합니다.
+          TESTCONTAINERS_RYUK_DISABLED: true
 
       - name: 테스트 리포트 업로드
-        if: failure()
+        if: always()
         uses: actions/upload-artifact@v4
         with:
           name: test-report-${{ inputs.module-name }}

payment-gateway/build.gradle

@@ -25,7 +25,9 @@ repositories {
 
 dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-web'
+	implementation 'org.springframework.boot:spring-boot-starter-aop'
     implementation 'io.projectreactor:reactor-core'
+	implementation 'io.github.resilience4j:resilience4j-spring-boot3:2.2.0'
 
     // Spring Metrics & Actuator
     implementation 'org.springframework.boot:spring-boot-starter-actuator'
@@ -36,9 +38,9 @@ dependencies {
 	annotationProcessor 'org.projectlombok:lombok'
 
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
+	testImplementation 'com.squareup.okhttp3:mockwebserver:4.11.0'
 	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
 }
-
 tasks.named('test') {
 	useJUnitPlatform()
-}
+}

payment-gateway/src/main/java/wisoft/nextframe/paymentgateway/api/PaymentGatewayController.java

@@ -30,9 +30,27 @@ public ResponseEntity<ConfirmResponse> confirm(
 		return response;
 	}
 
+	@PostMapping("/payments/cancel")
+	public ResponseEntity<CancelResponse> cancel(
+		@RequestParam(defaultValue = "toss") String provider,
+		@RequestBody CancelRequest request
+	) {
+		log.info("[Gateway] cancel 요청 수신 - provider={}, request={}", provider, request);
+		ResponseEntity<CancelResponse> response = ResponseEntity.ok(router.cancel(provider, request));
+		log.info("[Gateway] cancel 처리 완료 - response={}", response);
+		return response;
+	}
+
 	public record ConfirmRequest(String paymentKey, String orderId, int amount) {
 	}
 
 	public record ConfirmResponse(boolean isSuccess, int totalAmount, String errorCode, String errorMessage) {
 	}
+
+	public record CancelRequest(String orderId, int cancelAmount, String cancelReason) {
+	}
+
+	public record CancelResponse(boolean isSuccess, int cancelAmount, String transactionKey, String errorCode,
+								 String errorMessage) {
+	}
 }

payment-gateway/src/main/java/wisoft/nextframe/paymentgateway/provider/PaymentProvider.java

@@ -6,4 +6,6 @@ public interface PaymentProvider {
 	boolean supports(String providerName);
 
 	ConfirmResponse confirm(ConfirmRequest request);
+
+	CancelResponse cancel(CancelRequest request);
 }

payment-gateway/src/main/java/wisoft/nextframe/paymentgateway/provider/ProviderRouter.java

@@ -16,10 +16,17 @@ public ProviderRouter(List<PaymentProvider> providers) {
 	}
 
 	public ConfirmResponse confirm(String providerName, ConfirmRequest request) {
+		return findProvider(providerName).confirm(request);
+	}
+
+	public CancelResponse cancel(String providerName, CancelRequest request) {
+		return findProvider(providerName).cancel(request);
+	}
+
+	private PaymentProvider findProvider(String providerName) {
 		return providers.stream()
 			.filter(provider -> provider.supports(providerName))
 			.findFirst()
-			.orElseThrow(() -> new IllegalArgumentException("지원하지 않는 결제수단입니다."))
-			.confirm(request);
+			.orElseThrow(() -> new IllegalArgumentException("지원하지 않는 결제수단입니다."));
 	}
 }

payment-gateway/src/main/java/wisoft/nextframe/paymentgateway/provider/StubPaymentProvider.java

@@ -18,4 +18,9 @@ public boolean supports(String providerName) {
 	public ConfirmResponse confirm(ConfirmRequest request) {
 		return new ConfirmResponse(true, request.amount(), null, null);
 	}
+
+	@Override
+	public CancelResponse cancel(CancelRequest request) {
+		return new CancelResponse(true, request.cancelAmount(), "stub-tx-key", null, null);
+	}
 }

payment-gateway/src/main/java/wisoft/nextframe/paymentgateway/provider/TossPaymentProvider.java

@@ -5,30 +5,50 @@
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
 
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Profile;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
 import org.springframework.stereotype.Component;
+import org.springframework.web.client.HttpClientErrorException;
 import org.springframework.web.client.RestClient;
 
+import io.github.resilience4j.bulkhead.BulkheadFullException;
+import io.github.resilience4j.bulkhead.annotation.Bulkhead;
+import io.github.resilience4j.circuitbreaker.CallNotPermittedException;
+import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
 @Component
-@Profile("prod")
+@Profile({"prod","test"})
 public class TossPaymentProvider implements PaymentProvider {
 
 	private final RestClient restClient;
+	private final ConcurrentHashMap<String, String> paymentKeyStore = new ConcurrentHashMap<>();
 
-	public TossPaymentProvider(RestClient.Builder builder, @Value("${toss.secret-key}") String secretKey) {
+	public TossPaymentProvider(
+		RestClient.Builder builder,
+		@Value("${toss.secret-key}") String secretKey,
+		@Value("${toss.base-url:https://api.tosspayments.com}") String baseUrl
+	) {
 		if (secretKey == null || secretKey.isEmpty()) {
 			throw new IllegalStateException("toss.secret-key가 설정되어 있지 않습니다.");
 		}
 		String encoded = Base64.getEncoder()
 			.encodeToString((secretKey + ":").getBytes(StandardCharsets.UTF_8));
 
+		var factory = new SimpleClientHttpRequestFactory();
+		factory.setConnectTimeout(2_000);
+		factory.setReadTimeout(3_000);
+
 		this.restClient = builder
-			.baseUrl("https://api.tosspayments.com")
+			.baseUrl(baseUrl)
 			.defaultHeader(HttpHeaders.AUTHORIZATION, "Basic " + encoded)
+			.requestFactory(factory)
 			.build();
 	}
 
@@ -38,6 +58,8 @@ public boolean supports(String providerName) {
 	}
 
 	@Override
+	@CircuitBreaker(name = "tossConfirm", fallbackMethod = "confirmFallback")
+	@Bulkhead(name = "tossConfirm")
 	public ConfirmResponse confirm(ConfirmRequest request) {
 		Map response = restClient.post()
 			.uri("/v1/payments/confirm")
@@ -52,11 +74,61 @@ public ConfirmResponse confirm(ConfirmRequest request) {
 
 		String status = (String)response.getOrDefault("status", "");
 		if ("DONE".equals(status)) {
+			paymentKeyStore.put(request.orderId(), request.paymentKey());
 			int totalAmount = (int)response.getOrDefault("totalAmount", request.amount());
 			return new ConfirmResponse(true, totalAmount, null, null);
 		}
 		String code = (String)response.getOrDefault("code", "TOSS_ERROR");
 		String msg = (String)response.getOrDefault("message", "토스 승인 실패");
 		return new ConfirmResponse(false, 0, code, msg);
 	}
+
+	private ConfirmResponse confirmFallback(ConfirmRequest request, CallNotPermittedException e) {
+		log.warn("Toss 결제 승인 차단됨 [CIRCUIT_BREAKER_OPEN]");
+		return new ConfirmResponse(false, 0, "PG_TEMPORARY_UNAVAILABLE", "결제 서비스가 일시적으로 불안정합니다.");
+	}
+
+	private ConfirmResponse confirmFallback(ConfirmRequest request, BulkheadFullException e) {
+		log.warn("Toss 결제 승인 차단됨 [BULKHEAD_FULL]");
+		return new ConfirmResponse(false, 0, "PG_TEMPORARY_UNAVAILABLE", "결제 요청이 집중되고 있습니다.");
+	}
+
+	private ConfirmResponse confirmFallback(ConfirmRequest request, Throwable e) {
+		log.warn("Toss 결제 승인 실패: {}", e.toString());
+		return new ConfirmResponse(false, 0, "PG_NETWORK_ERROR", "PG 통신 중 오류가 발생했습니다.");
+	}
+
+	@Override
+	public CancelResponse cancel(CancelRequest request) {
+		String paymentKey = paymentKeyStore.get(request.orderId());
+		if (paymentKey == null) {
+			return new CancelResponse(false, 0, null, "PAYMENT_KEY_NOT_FOUND",
+				"결제 키를 찾을 수 없습니다. orderId=" + request.orderId());
+		}
+
+		try {
+			Map response = restClient.post()
+				.uri("/v1/payments/{paymentKey}/cancel", paymentKey)
+				.contentType(MediaType.APPLICATION_JSON)
+				.body(Map.of(
+					"cancelReason", request.cancelReason(),
+					"cancelAmount", request.cancelAmount())
+				)
+				.retrieve()
+				.body(Map.class);
+
+			String status = (String)response.getOrDefault("status", "");
+			if ("CANCELED".equals(status) || "PARTIAL_CANCELED".equals(status)) {
+				String transactionKey = (String)response.getOrDefault("transactionKey", "");
+				return new CancelResponse(true, request.cancelAmount(), transactionKey, null, null);
+			}
+
+			String code = (String)response.getOrDefault("code", "TOSS_ERROR");
+			String msg = (String)response.getOrDefault("message", "토스 취소 실패");
+			return new CancelResponse(false, 0, null, code, msg);
+		} catch (HttpClientErrorException e) {
+			log.error("토스 취소 API 호출 실패 - orderId: {}, error: {}", request.orderId(), e.getResponseBodyAsString());
+			return new CancelResponse(false, 0, null, "TOSS_CANCEL_ERROR", e.getResponseBodyAsString());
+		}
+	}
 }

payment-gateway/src/test/java/wisoft/nextframe/paymentgateway/PaymentGatewayApplicationTests.java

@@ -2,8 +2,10 @@
 
 import org.junit.jupiter.api.Test;
 import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
 
 @SpringBootTest
+@ActiveProfiles("dev")
 class PaymentGatewayApplicationTests {
 
 	@Test

payment-gateway/src/test/java/wisoft/nextframe/paymentgateway/api/PaymentGatewayControllerTest.java

@@ -0,0 +1,94 @@
+package wisoft.nextframe.paymentgateway.api;
+
+import static org.mockito.BDDMockito.*;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+import static wisoft.nextframe.paymentgateway.api.PaymentGatewayController.*;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import wisoft.nextframe.paymentgateway.provider.ProviderRouter;
+
+@WebMvcTest(PaymentGatewayController.class)
+@DisplayName("PaymentGatewayController 테스트")
+class PaymentGatewayControllerTest {
+
+	@Autowired
+	private MockMvc mockMvc;
+
+	@MockitoBean
+	private ProviderRouter router;
+
+	@Test
+	@DisplayName("POST /payments/confirm 성공 시 200 OK를 반환한다")
+	void confirm_success() throws Exception {
+		given(router.confirm(eq("toss"), any(ConfirmRequest.class)))
+			.willReturn(new ConfirmResponse(true, 10000, null, null));
+
+		mockMvc.perform(post("/api/v1/gateway/payments/confirm")
+				.param("provider", "toss")
+				.contentType(MediaType.APPLICATION_JSON)
+				.content("""
+					{"paymentKey": "pk_123", "orderId": "order-1", "amount": 10000}
+					"""))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.isSuccess").value(true))
+			.andExpect(jsonPath("$.totalAmount").value(10000));
+	}
+
+	@Test
+	@DisplayName("POST /payments/cancel 성공 시 200 OK를 반환한다")
+	void cancel_success() throws Exception {
+		given(router.cancel(eq("toss"), any(CancelRequest.class)))
+			.willReturn(new CancelResponse(true, 10000, "tx_abc", null, null));
+
+		mockMvc.perform(post("/api/v1/gateway/payments/cancel")
+				.param("provider", "toss")
+				.contentType(MediaType.APPLICATION_JSON)
+				.content("""
+					{"orderId": "order-1", "cancelAmount": 10000, "cancelReason": "단순 변심"}
+					"""))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.isSuccess").value(true))
+			.andExpect(jsonPath("$.cancelAmount").value(10000))
+			.andExpect(jsonPath("$.transactionKey").value("tx_abc"));
+	}
+
+	@Test
+	@DisplayName("POST /payments/cancel 실패 시에도 200 OK에 에러 정보를 반환한다")
+	void cancel_failure() throws Exception {
+		given(router.cancel(eq("toss"), any(CancelRequest.class)))
+			.willReturn(new CancelResponse(false, 0, null, "ALREADY_CANCELED", "이미 취소됨"));
+
+		mockMvc.perform(post("/api/v1/gateway/payments/cancel")
+				.param("provider", "toss")
+				.contentType(MediaType.APPLICATION_JSON)
+				.content("""
+					{"orderId": "order-1", "cancelAmount": 10000, "cancelReason": "환불"}
+					"""))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.isSuccess").value(false))
+			.andExpect(jsonPath("$.errorCode").value("ALREADY_CANCELED"));
+	}
+
+	@Test
+	@DisplayName("provider 파라미터 생략 시 기본값 toss로 동작한다")
+	void cancel_defaultProvider() throws Exception {
+		given(router.cancel(eq("toss"), any(CancelRequest.class)))
+			.willReturn(new CancelResponse(true, 5000, "tx_def", null, null));
+
+		mockMvc.perform(post("/api/v1/gateway/payments/cancel")
+				.contentType(MediaType.APPLICATION_JSON)
+				.content("""
+					{"orderId": "order-2", "cancelAmount": 5000, "cancelReason": "테스트"}
+					"""))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.isSuccess").value(true));
+	}
+}