feat: P6 외부연동 어댑터 모듈 PoC (펌뱅킹/SMS·카카오)

신규 모듈 ga-external-adapter — 외부 SDK 의존성을 격리. 실제 SDK 통합 시 이 모듈의 구현체만 교체하면 ga-api/ga-common 무변경. - ga-common.adapter.bank: BankTransferAdapter 인터페이스 + Request/Response/Status - ga-common.adapter.message: MessageAdapter 인터페이스 + Channel(SMS/KAKAO)/Request/Response - ga-external-adapter: MockBankTransferAdapter / MockMessageAdapter (로그 + 마스킹) - V82: withdraw_request.transfer_tx_id/transfer_status/transfer_at + 부분 인덱스 - ApprovalService.handleApprovalCallback(WITHDRAW) — 최종 승인 시 펌뱅킹 어댑터 호출 - 성공: status APPROVED → SENT 전이, transfer_tx_id 영속화 - 실패: APPROVED 유지 + fail_reason 기록 (재시도 배치는 추후) - ApprovalService.sendStepNotification — DB 알림 외 SMS 어댑터 호출 (non-critical) - WithdrawRequestMapper.updateTransferResult 추가
2026-05-24 02:10:06 +09:00
parent c005ad705a
commit b04fa79840
17 changed files with 332 additions and 3 deletions
@@ -0,0 +1,16 @@
+package com.ga.common.adapter.bank;
+
+/**
+ * 펌뱅킹(이체) 외부연동 어댑터.
+ * <p>
+ * 구현체는 ga-external-adapter 모듈에 위치한다.
+ * 실제 KFTC/은행 SDK 연동 시 이 인터페이스만 새 구현으로 교체하면 된다.
+ */
+public interface BankTransferAdapter {
+
+    /** 단건 이체 요청. 외부 시스템 응답을 그대로 반환 (영속화는 호출자 책임). */
+    BankTransferResponse requestTransfer(BankTransferRequest request);
+
+    /** 이전 거래의 현재 상태 조회 (대사용). */
+    BankTransferResponse queryStatus(String txId);
+}
@@ -0,0 +1,17 @@
+package com.ga.common.adapter.bank;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.math.BigDecimal;
+
+@Data
+@Builder
+public class BankTransferRequest {
+    private Long  withdrawRequestId;   // 원천 출금 신청 id (멱등키)
+    private String bankCode;
+    private String accountNo;          // 평문 (어댑터 내부에서 마스킹 로그)
+    private String accountHolderName;
+    private BigDecimal amount;
+    private String memo;               // 통장 적요
+}
@@ -0,0 +1,16 @@
+package com.ga.common.adapter.bank;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@Builder
+public class BankTransferResponse {
+    private String txId;                       // 외부 거래 id
+    private BankTransferStatus status;         // ACCEPTED/SETTLED/FAILED 등
+    private String resultCode;                 // 외부 응답 코드
+    private String resultMessage;              // 외부 응답 메시지
+    private LocalDateTime processedAt;
+}
@@ -0,0 +1,7 @@
+package com.ga.common.adapter.bank;
+
+public enum BankTransferStatus {
+    ACCEPTED,   // 접수
+    SETTLED,    // 입금 완료
+    FAILED      // 실패
+}
@@ -0,0 +1,11 @@
+package com.ga.common.adapter.message;
+
+/**
+ * SMS/카카오 알림톡 외부연동 어댑터.
+ * 구현체는 ga-external-adapter 모듈에 위치.
+ */
+public interface MessageAdapter {
+
+    /** 단건 메시지 전송. */
+    MessageResponse send(MessageRequest request);
+}
@@ -0,0 +1,6 @@
+package com.ga.common.adapter.message;
+
+public enum MessageChannel {
+    SMS,
+    KAKAO
+}
@@ -0,0 +1,17 @@
+package com.ga.common.adapter.message;
+
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+public class MessageRequest {
+    private MessageChannel channel;
+    private String phoneNumber;       // 수신자 (E.164 또는 010-xxxx-xxxx)
+    private String title;             // 카카오 알림톡 강조 헤더 용 (SMS는 무시 가능)
+    private String content;
+    private String templateCode;      // 카카오 발신 템플릿 코드 (sms 미사용)
+    private Long  refUserId;          // 추적용 — user_notification.user_id
+    private String refType;           // APPROVAL/SETTLE 등
+    private Long  refId;
+}
@@ -0,0 +1,16 @@
+package com.ga.common.adapter.message;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@Builder
+public class MessageResponse {
+    private String messageId;          // 외부 시스템 발급 id
+    private boolean sent;
+    private String resultCode;
+    private String resultMessage;
+    private LocalDateTime sentAt;
+}
@@ -0,0 +1,15 @@
+-- V82: withdraw_request 에 펌뱅킹 외부연동 결과 추적 컬럼 추가.
+--      어댑터(BankTransferAdapter) 호출 결과(거래ID/상태/처리시각)를 저장하기 위함.
+
+ALTER TABLE withdraw_request
+    ADD COLUMN IF NOT EXISTS transfer_tx_id   VARCHAR(64),
+    ADD COLUMN IF NOT EXISTS transfer_status  VARCHAR(20),
+    ADD COLUMN IF NOT EXISTS transfer_at      TIMESTAMP;
+
+COMMENT ON COLUMN withdraw_request.transfer_tx_id  IS '펌뱅킹 외부 거래 ID (멱등키)';
+COMMENT ON COLUMN withdraw_request.transfer_status IS 'ACCEPTED/SETTLED/FAILED — BankTransferStatus';
+COMMENT ON COLUMN withdraw_request.transfer_at     IS '펌뱅킹 호출/응답 시각';
+
+CREATE INDEX IF NOT EXISTS idx_wr_transfer_status
+    ON withdraw_request(transfer_status)
+    WHERE transfer_status IS NOT NULL;