# feat(cdc): Remittance Outbox + Debezium CDC + payout-worker + 결과 컨슈머 end-to-end 추가

[NewEgoDoc]

Summary

송금 생성 시 remittance_events outbox를 같은 트랜잭션으로 기록하고, Debezium CDC로 Kafka 토픽(remittance.paid)에 발행하는 흐름을 추가했습니다. 신규 payout-worker가 해당 이벤트를 소비해 송금사 API 호출 후 payout_outbox를 기록하고, 다시 Debezium으로 remittance.payout.completed/failed를 발행합니다. remittance-api는 결과 토픽을 소비해 상태를 COMPLETED/FAILED로 전이합니다.

---

Changes

1) remittance-api: Outbox 발행 + Kafka 결과 소비

• remittance-api/src/main/kotlin/com/openremit/api/application/remittance/RemittanceCreateUseCase.kt
  • markPaid 이후 remittance_events outbox INSERT 추가 (동일 트랜잭션)
• remittance-api/src/main/kotlin/com/openremit/api/domain/RemittanceEvent.kt (신규)
• remittance-api/src/main/kotlin/com/openremit/api/infrastructure/persistence/RemittanceEventRepository.kt (신규)
• remittance-api/src/main/resources/db/migration/V4__remittance_events.sql (신규)
• remittance-api/src/main/kotlin/com/openremit/api/infrastructure/kafka/RemittancePayoutResultConsumer.kt (신규)
  • remittance.payout.completed/failed 소비
• remittance-api/src/main/kotlin/com/openremit/api/application/remittance/RemittanceCompletionService.kt (신규)
  • PAID -> PROCESSING -> COMPLETED/FAILED 전이 처리 (terminal 상태 재처리 skip)
• remittance-api/src/main/kotlin/com/openremit/api/RemittanceApiApplication.kt
  • @EnableKafka 추가
• remittance-api/src/main/resources/application.yaml
  • Kafka consumer 설정 추가
• remittance-api/build.gradle.kts
  • Kafka runtime/test 의존성 추가

2) common: 이벤트 계약 추가

• common/src/main/kotlin/com/openremit/common/events/RemittanceEvents.kt (신규)
  • RemittancePaidEvent
  • RemittancePayoutCompletedEvent
  • RemittancePayoutFailedEvent
  • RemittanceEventTopics

3) payout-worker 모듈 구현

• payout-worker/build.gradle.kts
  • Spring Boot/JPA/Flyway/Kafka/Web/Validation/Testcontainers 의존성 구성
• payout-worker/src/main/kotlin/com/openremit/payout/PayoutWorkerApplication.kt (신규)
• payout-worker/src/main/resources/application.yaml (신규)
• payout-worker/src/main/resources/db/migration/V1__payout_tables.sql (신규)
  • payout_attempts(remittance_id UNIQUE 멱등성)
  • payout_outbox
• payout-worker/src/main/kotlin/com/openremit/payout/infrastructure/kafka/RemittancePaidConsumer.kt (신규)
• payout-worker/src/main/kotlin/com/openremit/payout/application/PayoutProcessor.kt (신규)
  • 송금사 호출 결과를 payout_outbox에 기록
• payout-worker/src/main/kotlin/com/openremit/payout/infrastructure/client/PayoutClient.kt (신규)
• payout-worker/src/main/kotlin/com/openremit/payout/domain/PayoutAttempt.kt (신규)
• payout-worker/src/main/kotlin/com/openremit/payout/domain/PayoutOutboxEvent.kt (신규)
• payout-worker/src/main/kotlin/com/openremit/payout/infrastructure/persistence/*.kt (신규)

4) 인프라/docker-compose: Debezium + mock payout + MySQL binlog 설정

• docker-compose.yml
  • MySQL binlog/GTID 옵션 추가
  • mock-payout-api 추가 (9998)
  • Kafka dual listener(9092 host, 29092 internal) 구성
  • debezium + debezium-register 서비스 추가
• debezium/openremit-outbox-connector.json (신규)
  • remittance_events, payout_outbox 대상 outbox event router 설정
• mysql-init/01-debezium-user.sql (신규)
• mock-payout/mappings/payout-success.json (신규)

5) 테스트 추가/보강

• remittance-api/src/test/kotlin/com/openremit/api/remittance/RemittanceCreateIntegrationTest.kt
  • 송금 생성 시 outbox 1건 기록 검증 추가
• remittance-api/src/test/kotlin/com/openremit/api/remittance/RemittancePayoutResultConsumerIntegrationTest.kt (신규)
  • completed/failed 이벤트 소비 후 상태 전이 검증
• remittance-api/src/test/kotlin/com/openremit/api/TestcontainersConfig.kt
  • Kafka container bootstrap 주입 추가
• payout-worker/src/test/kotlin/com/openremit/payout/PayoutWorkerIntegrationTest.kt (신규)
  • remittance.paid 소비 → payout 호출 → outbox 기록 검증
• payout-worker/src/test/kotlin/com/openremit/payout/PayoutWorkerTestcontainersConfig.kt (신규)

6) 문서 업데이트

• README.md
  • Outbox + Debezium 이벤트 흐름 다이어그램/설명 추가
  • docker-compose 기반 E2E 검증 절차 추가

---

Checklist

• remittance outbox(remittance_events) 저장 추가
• Debezium connector 설정 추가
• payout-worker 신규 구현 (consume/process/outbox)
• remittance-api 결과 consumer/상태 전이 서비스 추가
• Kafka/Testcontainers 기반 통합 테스트 추가
• README 운영/검증 가이드 반영

---

How to Test

# 1) 통합 테스트
./gradlew build

# 2) 로컬 CDC E2E 인프라
docker compose up -d

# 3) 앱 실행
./gradlew :remittance-api:bootRun
./gradlew :payout-worker:bootRun

# 4) Debezium connector 상태 확인
curl -sS http://localhost:8083/connectors/openremit-outbox/status