# feat(reconciler): wallet ledger 정산 배치 추가 + remittance wallet_transactions 기록

[NewEgoDoc]

Summary

reconciler 모듈을 신규 추가해 지갑 정산 배치(A/B 이중 검증)를 구현했습니다. 동시에 remittance-api 송금 생성 트랜잭션에 wallet_transactions ledger 기록을 추가해, 정산 기준 데이터가 동일 트랜잭션에서 남도록 보강했습니다.

---

Changes

1) remittance-api: wallet ledger(wallet_transactions) 기록 추가

• remittance-api/src/main/kotlin/com/openremit/api/domain/WalletTransaction.kt (신규)
  • wallet_transactions 엔티티 추가 (amount, balance_after, reference_type, reference_id)
• remittance-api/src/main/kotlin/com/openremit/api/infrastructure/persistence/WalletTransactionRepository.kt (신규)
• remittance-api/src/main/resources/db/migration/V5__wallet_transactions.sql (신규)
  • wallet_transactions 테이블/인덱스/외래키 추가
• remittance-api/src/main/kotlin/com/openremit/api/application/remittance/RemittanceCreateUseCase.kt
  • 송금 생성 시 지갑 출금과 같은 트랜잭션에서 ledger row INSERT 추가

2) reconciler 모듈 신규 구현 (Spring Batch)

• reconciler/build.gradle.kts
  • Spring Boot/JPA/Flyway/Batch/MySQL/Testcontainers 의존성 구성
• reconciler/src/main/kotlin/com/openremit/reconcile/ReconcilerApplication.kt (신규)
  • @EnableScheduling 기반 실행 엔트리포인트 추가
• reconciler/src/main/kotlin/com/openremit/reconcile/application/WalletReconcile.kt (신규)
  • WalletSnapshot, WalletMismatch, ReconcileResult 모델 추가
• reconciler/src/main/kotlin/com/openremit/reconcile/application/WalletReconcileService.kt (신규)
  • A-검증: wallet.balance == Σ wallet_transactions.amount
  • B-검증: wallet.balance == last wallet_transactions.balance_after
• reconciler/src/main/kotlin/com/openremit/reconcile/infrastructure/persistence/WalletReconcileQuery.kt (신규)
  • wallets + wallet_transactions read-only native query
• reconciler/src/main/kotlin/com/openremit/reconcile/infrastructure/batch/WalletReconcileJobConfig.kt (신규)
  • 단일 tasklet 기반 walletReconcileJob 구성
  • 결과를 reconciliations 테이블에 저장
• reconciler/src/main/kotlin/com/openremit/reconcile/infrastructure/batch/ReconcileScheduler.kt (신규)
  • cron 스케줄 트리거 (openremit.reconcile.cron, 기본 04:00)
• reconciler/src/main/kotlin/com/openremit/reconcile/domain/Reconciliation.kt (신규)
• reconciler/src/main/kotlin/com/openremit/reconcile/infrastructure/persistence/ReconciliationRepository.kt (신규)
• reconciler/src/main/resources/db/migration/V1__reconciliation_tables.sql (신규)
  • reconciliations 테이블 추가
• reconciler/src/main/resources/application.yaml (신규)
  • datasource/flyway/batch/scheduler/port 설정 추가

3) 테스트 보강

• remittance-api/src/test/kotlin/com/openremit/api/remittance/RemittanceCreateIntegrationTest.kt
  • 송금 생성 시 wallet_transactions 1행 기록 검증 테스트 추가
• remittance-api/src/test/kotlin/com/openremit/api/remittance/RemittanceConcurrencyTest.kt
  • cleanup에 walletTransactionRepository 정리 추가
• reconciler/src/test/kotlin/com/openremit/reconcile/application/WalletReconcileServiceTest.kt (신규)
  • A-only/B-only/both mismatch 등 케이스 검증
• reconciler/src/test/kotlin/com/openremit/reconcile/WalletReconcileIntegrationTest.kt (신규)
  • 배치 실행 후 reconciliations.mismatch_count/details 저장 검증
• reconciler/src/test/kotlin/com/openremit/reconcile/ReconcilerTestcontainersConfig.kt (신규)

4) 문서 업데이트

• README.md
  • reconciler의 A/B 검증 목적, 운영 의미, 실행 방법 설명 추가

---

Checklist

• wallet_transactions 테이블 및 엔티티/레포지토리 추가
• remittance 생성 트랜잭션에 wallet ledger 기록 추가
• reconciler 모듈(Spring Batch + Scheduler) 신규 구현
• reconciliations 결과 저장 스키마/엔티티 추가
• remittance/reconciler 테스트 추가 및 보강
• README 정산 배치 설명 반영

---

How to Test

# remittance-api: ledger 기록 검증
./gradlew :remittance-api:test --tests "*RemittanceCreateIntegrationTest"
./gradlew :remittance-api:test --tests "*RemittanceConcurrencyTest"

# reconciler: 단위/통합 테스트
./gradlew :reconciler:test --tests "*WalletReconcileServiceTest"
./gradlew :reconciler:test --tests "*WalletReconcileIntegrationTest"

# 전체 테스트
./gradlew test

# 로컬 실행
./gradlew :reconciler:bootRun