Merge pull request #34 from hyujikoh/feat/failure-ready

PG 모듈 적용

Author: hyujikoh

apps/commerce-api/build.gradle.kts

@@ -9,9 +9,9 @@ dependencies {
     // web
     implementation("org.springframework.boot:spring-boot-starter-web")
     implementation("org.springframework.boot:spring-boot-starter-actuator")
+    implementation("org.springframework.cloud:spring-cloud-starter-openfeign")
     implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:${project.properties["springDocOpenApiVersion"]}")
 
-
     // faker
     implementation("net.datafaker:datafaker:2.0.2")
 

apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentEntity.java

@@ -0,0 +1,61 @@
+package com.loopers.domain.payment;
+
+import io.micrometer.core.annotation.Counted;
+import java.math.BigDecimal;
+import java.time.ZonedDateTime;
+
+import com.loopers.domain.BaseEntity;
+
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import jakarta.persistence.*;
+
+/**
+ * @author hyunjikoh
+ * @since 2025. 12. 2.
+ */
+@Entity
+@Table(name = "payments")
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class PaymentEntity extends BaseEntity {
+
+    @Column(nullable = false, unique = true, length = 50)
+    private String  transactionKey;
+
+    @Column(nullable = false, length = 50)
+    private String orderNumber;
+
+    @Column(nullable = false, precision = 10, scale = 2)
+    private BigDecimal amount;
+
+    @Column(nullable = false, length = 20)
+    private String cardType;
+
+    @Column(nullable = false, length = 20)
+    private String cardNo;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 20)
+    private PaymentStatus paymentStatus;
+
+    @Column(nullable = false, length = 255)
+    private String callbackUrl;
+
+    // TODO : TransactionStatus 로 변경 필요
+    @Column(nullable = true, length = 20)
+    private String transactionStatus;
+
+    @Column(length = 20)
+    private String failureReason;
+
+    @Column(name = "completed_at")
+    private ZonedDateTime completedAt;
+
+    // → PG에 실제 결제 요청을 보낸 시각
+    @Column(name = "requested_at", nullable = false)
+    private ZonedDateTime requestedAt;
+
+}

apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentStatus.java

@@ -0,0 +1,21 @@
+package com.loopers.domain.payment;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author hyunjikoh
+ * @since 2025. 12. 2.
+ */
+@Getter
+@AllArgsConstructor
+public enum PaymentStatus {
+    PENDING("PG 요청 완료, 콜백 대기"),      // PG 요청 완료, 콜백 대기
+    COMPLETED("결제 완료"),      // 결제 성공
+    FAILED("결제 실패"),       // 결제 실패
+    REFUNDED("결제 환불"),      // 결제 환불
+    CANCEL("결제 취소"),      // 결제 취소
+    TIMEOUT("결제 시간 만료");       // 콜백 미수신 타임아웃
+
+    private final String description;
+}

apps/commerce-api/src/main/java/com/loopers/domain/payment/PaymentType.java

@@ -0,0 +1,17 @@
+package com.loopers.domain.payment;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * @author hyunjikoh
+ * @since 2025. 12. 2.
+ */
+@AllArgsConstructor
+@Getter
+public enum PaymentType {
+    CARD("카드 결제"),
+    REFUND("환불");
+
+    private final String description;
+}

apps/commerce-api/src/main/java/com/loopers/interfaces/api/payment/client/PgClient.java

@@ -0,0 +1,8 @@
+package com.loopers.interfaces.api.payment.client;
+
+/**
+ * @author hyunjikoh
+ * @since 2025. 12. 2.
+ */
+public class PgClient {
+}

apps/pg-simulator/README.md

@@ -0,0 +1,42 @@
+## PG-Simulator (PaymentGateway)
+
+### Description
+Loopback BE 과정을 위해 PaymentGateway 를 시뮬레이션하는 App Module 입니다.
+`local` 프로필로 실행 권장하며, 커머스 서비스와의 동시 실행을 위해 서버 포트가 조정되어 있습니다.
+- server port : 8082
+- actuator port : 8083
+
+### Getting Started
+부트 서버를 아래 명령어 혹은 `intelliJ` 통해 실행해주세요.
+```shell
+./gradlew :apps:pg-simulator:bootRun
+```
+
+API 는 아래와 같이 주어지니, 커머스 서비스와 동시에 실행시킨 후 진행해주시면 됩니다.
+- 결제 요청 API
+- 결제 정보 확인 `by transactionKey`
+- 결제 정보 목록 조회 `by orderId`
+
+```http request
+### 결제 요청
+POST {{pg-simulator}}/api/v1/payments
+X-USER-ID: 135135
+Content-Type: application/json
+
+{
+  "orderId": "1351039135",
+  "cardType": "SAMSUNG",
+  "cardNo": "1234-5678-9814-1451",
+  "amount" : "5000",
+  "callbackUrl": "http://localhost:8080/api/v1/examples/callback"
+}
+
+### 결제 정보 확인
+GET {{pg-simulator}}/api/v1/payments/20250816:TR:9577c5
+X-USER-ID: 135135
+
+### 주문에 엮인 결제 정보 조회
+GET {{pg-simulator}}/api/v1/payments?orderId=1351039135
+X-USER-ID: 135135
+
+```

apps/pg-simulator/build.gradle.kts

@@ -0,0 +1,40 @@
+plugins {
+    val kotlinVersion = "2.0.20"
+
+    id("org.jetbrains.kotlin.jvm") version(kotlinVersion)
+    id("org.jetbrains.kotlin.kapt") version(kotlinVersion)
+    id("org.jetbrains.kotlin.plugin.spring") version(kotlinVersion)
+    id("org.jetbrains.kotlin.plugin.jpa") version(kotlinVersion)
+}
+
+kotlin {
+    compilerOptions {
+        jvmToolchain(21)
+        freeCompilerArgs.addAll("-Xjsr305=strict")
+    }
+}
+
+dependencies {
+    // add-ons
+    implementation(project(":modules:jpa"))
+    implementation(project(":modules:redis"))
+    implementation(project(":supports:jackson"))
+    implementation(project(":supports:logging"))
+    implementation(project(":supports:monitoring"))
+
+    // kotlin
+    implementation("org.jetbrains.kotlin:kotlin-reflect")
+    implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
+
+    // web
+    implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("org.springframework.boot:spring-boot-starter-actuator")
+    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:${project.properties["springDocOpenApiVersion"]}")
+
+    // querydsl
+    kapt("com.querydsl:querydsl-apt::jakarta")
+
+    // test-fixtures
+    testImplementation(testFixtures(project(":modules:jpa")))
+    testImplementation(testFixtures(project(":modules:redis")))
+}

apps/pg-simulator/src/main/kotlin/com/loopers/PaymentGatewayApplication.kt

@@ -0,0 +1,24 @@
+package com.loopers
+
+import jakarta.annotation.PostConstruct
+import org.springframework.boot.autoconfigure.SpringBootApplication
+import org.springframework.boot.context.properties.ConfigurationPropertiesScan
+import org.springframework.boot.runApplication
+import org.springframework.scheduling.annotation.EnableAsync
+import java.util.TimeZone
+
+@ConfigurationPropertiesScan
+@EnableAsync
+@SpringBootApplication
+class PaymentGatewayApplication {
+
+    @PostConstruct
+    fun started() {
+        // set timezone
+        TimeZone.setDefault(TimeZone.getTimeZone("Asia/Seoul"))
+    }
+}
+
+fun main(args: Array<String>) {
+    runApplication<PaymentGatewayApplication>(*args)
+}

apps/pg-simulator/src/main/kotlin/com/loopers/application/payment/OrderInfo.kt

@@ -0,0 +1,14 @@
+package com.loopers.application.payment
+
+/**
+ * 결제 주문 정보
+ *
+ * 결제는 주문에 대한 다수 트랜잭션으로 구성됩니다.
+ *
+ * @property orderId 주문 정보
+ * @property transactions 주문에 엮인 트랜잭션 목록
+ */
+data class OrderInfo(
+    val orderId: String,
+    val transactions: List<TransactionInfo>,
+)

apps/pg-simulator/src/main/kotlin/com/loopers/application/payment/PaymentApplicationService.kt

@@ -0,0 +1,88 @@
+package com.loopers.application.payment
+
+import com.loopers.domain.payment.Payment
+import com.loopers.domain.payment.PaymentEvent
+import com.loopers.domain.payment.PaymentEventPublisher
+import com.loopers.domain.payment.PaymentRelay
+import com.loopers.domain.payment.PaymentRepository
+import com.loopers.domain.payment.TransactionKeyGenerator
+import com.loopers.domain.user.UserInfo
+import com.loopers.support.error.CoreException
+import com.loopers.support.error.ErrorType
+import org.springframework.stereotype.Component
+import org.springframework.transaction.annotation.Transactional
+
+@Component
+class PaymentApplicationService(
+    private val paymentRepository: PaymentRepository,
+    private val paymentEventPublisher: PaymentEventPublisher,
+    private val paymentRelay: PaymentRelay,
+    private val transactionKeyGenerator: TransactionKeyGenerator,
+) {
+    companion object {
+        private val RATE_LIMIT_EXCEEDED = (1..20)
+        private val RATE_INVALID_CARD = (21..30)
+    }
+
+    @Transactional
+    fun createTransaction(command: PaymentCommand.CreateTransaction): TransactionInfo {
+        command.validate()
+
+        val transactionKey = transactionKeyGenerator.generate()
+        val payment = paymentRepository.save(
+            Payment(
+                transactionKey = transactionKey,
+                userId = command.userId,
+                orderId = command.orderId,
+                cardType = command.cardType,
+                cardNo = command.cardNo,
+                amount = command.amount,
+                callbackUrl = command.callbackUrl,
+            ),
+        )
+
+        paymentEventPublisher.publish(PaymentEvent.PaymentCreated.from(payment = payment))
+
+        return TransactionInfo.from(payment)
+    }
+
+    @Transactional(readOnly = true)
+    fun getTransactionDetailInfo(userInfo: UserInfo, transactionKey: String): TransactionInfo {
+        val payment = paymentRepository.findByTransactionKey(userId = userInfo.userId, transactionKey = transactionKey)
+            ?: throw CoreException(ErrorType.NOT_FOUND, "(transactionKey: $transactionKey) 결제건이 존재하지 않습니다.")
+        return TransactionInfo.from(payment)
+    }
+
+    @Transactional(readOnly = true)
+    fun findTransactionsByOrderId(userInfo: UserInfo, orderId: String): OrderInfo {
+        val payments = paymentRepository.findByOrderId(userId = userInfo.userId, orderId = orderId)
+        if (payments.isEmpty()) {
+            throw CoreException(ErrorType.NOT_FOUND, "(orderId: $orderId) 에 해당하는 결제건이 존재하지 않습니다.")
+        }
+
+        return OrderInfo(
+            orderId = orderId,
+            transactions = payments.map { TransactionInfo.from(it) },
+        )
+    }
+
+    @Transactional
+    fun handle(transactionKey: String) {
+        val payment = paymentRepository.findByTransactionKey(transactionKey)
+            ?: throw CoreException(ErrorType.NOT_FOUND, "(transactionKey: $transactionKey) 결제건이 존재하지 않습니다.")
+
+        val rate = (1..100).random()
+        when (rate) {
+            in RATE_LIMIT_EXCEEDED -> payment.limitExceeded()
+            in RATE_INVALID_CARD -> payment.invalidCard()
+            else -> payment.approve()
+        }
+        paymentEventPublisher.publish(event = PaymentEvent.PaymentHandled.from(payment))
+    }
+
+    fun notifyTransactionResult(transactionKey: String) {
+        val payment = paymentRepository.findByTransactionKey(transactionKey)
+            ?: throw CoreException(ErrorType.NOT_FOUND, "(transactionKey: $transactionKey) 결제건이 존재하지 않습니다.")
+        paymentRelay.notify(callbackUrl = payment.callbackUrl, transactionInfo = TransactionInfo.from(payment))
+    }
+}