머천트 계좌 검증 회귀 버그 수정

결제 플랫폼의 WELCOME 시스템에서 머천트 잔액 조회 및 계좌 검증이 일부 코드 경로에서 누락되었던 로직을 보충했다. 주요 변경은 파트너 관리 웹 계층과 공통 유틸리티 계층에 걸쳐 이루어졌다.

왜 회귀가 발생했나

이 버그는 전형적인 리팩토링 회귀다. 검증 로직이 여러 코드 경로에 흩어져 있는데, 한쪽 경로만 보강하고 다른 경로는 못 본 경우다.

• 초기 구현: 특정 시나리오(예: 초기 가입)에 맞춰서 검증 로직 작성
• 개선 작업: 일부 경로(예: 정산 사이클) 검증 강화 → 주 사용 경로만 수정
• 덜 쓰는 경로: 계좌 검증 호출 빈도가 낮은 곳은 눈에 띄지 않음
• 회귀 드러남: 특정 상황(분기별 정산, 루틴 체크 등)에서 검증 누락 발생

웹 컨트롤러(partner/web)와 유틸리티 계층(utl)이 분리되어 있을 때, 데이터 흐름이 여러 갈래로 나뉘면 한쪽에서 검증이 빠지기 쉽다.

변경 범위와 의도

컨트롤러 단계에서는 "이 요청에 실제 머천트 정보가 있는가"를 확인하고, 유틸리티 단계에서는 "그 머천트의 계좌가 우리 시스템에서 유효한 상태인가"를 검사하는 식으로 이중 확인 체계를 구성했다.

비슷한 패턴의 예

결제/정산 도메인에서 이런 회귀가 또 어디서 나타날까.

머천트 상태 검증 흐름 (개념)

// 초기 구현 (가입 경로)
validateForSignup(partnerId) {
  partner := fetch(partnerId)
  if (!partner) error
  if (!partner.account) error
  return partner
}

// 개선된 정산 경로 (검증 강화)
validateForSettlement(partnerId) {
  partner := fetch(partnerId)
  if (!partner) error
  if (!partner.account?.isVerified) error
  if (partner.balance < 0) error  // 신규 검증
  return partner
}

// ❌ 계좌 변경 경로 (회귀: 신규 검증 누락)
validateForAccountUpdate(partnerId) {
  partner := fetch(partnerId)
  if (!partner) error
  if (!partner.account) error
  // balance < 0 체크 누락! ← 회귀 지점
  return partner
}

// ✓ 개선: 공통 검증 함수로 통합
validateMerchantForOperation(partnerId) {
  partner := fetch(partnerId)
  if (!partner) error
  if (!partner.account?.isVerified) error
  if (partner.balance < 0) error
  return partner  // 모든 경로가 같은 검증을 거침
}

이 패턴처럼, 같은 검증을 여러 함수가 제각각 구현하면 나중에 개선할 때 누락이 생긴다.

개선 방향

1. 검증 로직의 중앙화
검증은 한 곳에만 두고, 모든 호출 경로에서 재사용해야 한다. 유틸리티 함수로 단일 진입점을 만들면, 유지보수가 훨씬 쉬워진다. 검증 규칙이 바뀔 때도 한 군데만 수정하면 된다.

2. 계층별 책임 분명히
웹 계층은 "요청 데이터가 문법적으로 유효한가" 정도만 확인하고, 비즈니스 로직 계층은 "그 데이터가 우리 도메인 규칙을 만족하는가"를 책임진다. 계층을 명확히 하면, 개선 시 "유틸리티를 수정하면 모든 경로가 자동으로 개선됨"이라는 확신을 가질 수 있다.

3. 경로별 테스트 커버리지
가입, 정산, 계좌 변경, 관리자 수정 등 각 코드 경로를 직접 호출하는 통합 테스트가 있었다면, 회귀를 놓치지 않았을 것이다. 특히 우선순위가 낮은 경로일수록 테스트가 더 중요하다.

4. 코드 리뷰 체크리스트
검증 로직을 건드리는 PR에서는 "이 함수를 호출하는 모든 곳을 찾았는가?", "영향받는 경로가 모두 테스트되는가?", "공통화할 수 있는 부분이 있는가?"를 반드시 확인해야 한다. 정산, 계좌 관리 같은 민감한 영역은 특히 신경 써야 한다.

마무리

결제 플랫폼에서 "한 번 빠진 검증"은 시간이 지날수록 더 큰 버그가 될 수 있다. 금액, 계좌, 파트너 신분 같은 데이터는 한 번 틀리면 정산 오류, 감시 알림, 규정 위반까지 이어질 수 있기 때문이다. 이번 수정은 작은 패치처럼 보이지만, 여러 코드 경로의 검증을 다시 정렬한 결과다. 비슷한 회귀를 줄이려면 검증을 중앙화하고, 시나리오별 테스트를 촘촘히 하고, 리뷰 때 영향 범위를 꼼꼼히 확인하는 습관이 필요하다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.