개발 slecs

쿠폰 GIFT 발급 누락 영수증 일괄 백필

목차

결제 플랫폼에서 쿠폰 GIFT 발급 시 영수증을 소급해서 생성하는 백필 작업을 진행했다. 이전에는 영수증 발급이 누락된 레코드들이 있었는데, 이제 그것들을 일괄 처리하고 운영 환경에 적용하는 단계까지 완료했다.

왜 쿠폰 영수증 백필이 필요했나

결제 및 정산 시스템에서 "영수증"은 단순한 고객 확인용 문서가 아니다. 거래의 추적 가능성, 감사(audit) 기록, 그리고 정산 대사의 기초가 되는 중요한 데이터다. 특히 GIFT 형태의 쿠폰 발급은 일종의 거래로 취급되므로, 관련된 모든 쿠폰 발급 건에는 대응하는 영수증 레코드가 존재해야 한다.

실제로는 시스템이 진화하면서 쿠폰 발급 로직과 영수증 생성 로직이 따로 발전했을 가능성이 높다. 예를 들어:
- 초기에는 쿠폰 발급만 기록했고, 나중에 영수증 요구사항이 생김
- 특정 기간에 GIFT 쿠폰 발급 기능이 추가되었는데, 영수증 생성 로직 연동이 빠짐
- 데이터 마이그레이션 과정에서 일부 레코드가 누락됨

이런 상황에서 기존 데이터와 새로운 요구사항 사이의 "구멍"이 생기는 건 흔하다. 그래서 백필 작업이 필수적이 된다.

백필 마이그레이션의 특수성

일반적인 ALTER TABLE이나 UPDATE 같은 DDL과 달리, 백필 스크립트는 한 번만 실행되어야 하고, 멱등성(idempotency)이 중요하다. 

-- 백필 전 체크: 영수증이 없는 쿠폰 GIFT 발급 건 집계
SELECT COUNT(*)
FROM coupon_issue
WHERE issue_type = 'GIFT'
  AND issue_date < '2026-04-29'
  AND NOT EXISTS (
    SELECT 1 FROM payment_receipt
    WHERE payment_receipt.coupon_issue_id = coupon_issue.id
  )

이런 식으로 먼저 영향 범위를 파악한 후, 그에 맞는 영수증 레코드를 생성하는 INSERT 또는 UPSERT를 실행하는 것이 일반적이다. 여기서 중요한 점:

  1. 중복 생성 방지: 재실행될 경우 같은 영수증을 두 번 만들면 안 되므로, INSERT IGNORE 또는 ON CONFLICT DO NOTHING 같은 전략 필요
  2. 거래 일관성: 쿠폰 발급 데이터와 영수증의 타이밍, 금액, 상태 등이 정확히 매칭되어야 함
  3. 감사 기록: 백필된 레코드가 언제 생성되었는지, 누가 실행했는지 추적 가능하도록 created_at, batch_id 같은 필드 필요

운영 적용 전 검증

마이그레이션 파일이 생기면 실제 운영 DB에 적용하기 전에 보통 다음 순서를 거친다:

  • dev/staging 환경에서 먼저 실행 → 데이터 볼륨, 실행 시간, 락 발생 여부 확인
  • 영수증 생성 로직과의 정합성 검증 → 백필 후 새로운 쿠폰 GIFT 발급 시 영수증이 정상 생성되는지 테스트
  • 정산 대사 재계산 → 기존 정산 기간의 데이터가 백필로 인해 변경되었으므로, 필요시 정산을 다시 실행하거나 조정
  • 롤백 계획 수립 → 혹시 모를 상황에 대비해 데이터 복구 방안 준비

이 단계들이 모두 완료되고 "운영 적용"이라는 표현이 들어간 것은, 위의 검증을 마치고 실제 프로덕션 데이터베이스에 스크립트를 실행했다는 뜻이다.

회고: 데이터 레이어의 진화 관리

이런 백필 작업을 하면서 느끼는 점은, 서비스가 커질수록 "영수증"처럼 한 번 설정되면 바꾸기 어려운 데이터 구조에 대해서는 초기부터 신경써야 한다는 것이다. 새로운 거래 타입(GIFT 쿠폰)이 추가될 때마다 영수증 생성 로직도 함께 진화해야 하는데, 이를 자동화하거나 체크리스트로 관리하지 않으면 자꾸만 구멍이 생긴다.

앞으로는:
- 거래 로직 추가 시 "이 거래는 영수증이 필요한가?"를 명시적으로 질문하기
- 영수증 생성 로직을 한곳에 집중시켜서, 새로운 거래 타입도 자동으로 커버하도록 설계하기
- 정기적으로 "영수증이 없는 거래"를 모니터링하는 쿼리를 실행해서 조기에 발견하기

이번 작업은 그런 설계 부채를 정리하는 과정이었다.

이어보기

댓글 0

첫 댓글 달아줘.