가상계좌 PG 수수료

가상계좌 PG 수수료 단가가 300원에서 330원으로 오르면서 생긴 작업이다. 단순히 숫자 하나 바꾸는 것처럼 보이지만, 결제 도메인에서 수수료 단가는 SQL 집계 쿼리, 화면 렌더링, 정산 라벨 표시 등 여러 레이어에 동시에 걸쳐 있어서 건드릴 게 꽤 있었다. 이번엔 수수료 갱신 외에 익월 후정산 케이스에 대한 라벨 표시도 함께 추가했다.

변경 파일 범위는 SQL 매퍼 3개, 뷰/스타일 2개, 설정/문서 1개. 총 6개 파일인데 이 정도 범위면 결제 흐름 한 단면을 통째로 손댄 셈이다.

왜 이게 버그였나

기존 로직은 수수료 단가가 고정값으로 박혀 있거나, 단가 변경 시점 이전/이후를 구분하는 분기가 없었다. 그래서 특정 상황에서 오래된 단가로 집계가 나오거나, 익월 후정산 케이스가 라벨 없이 노출되는 엣지 케이스가 발생하고 있었다.

수수료 단가처럼 "가끔 바뀌는 값"을 코드에 리터럴로 박아두면 이런 일이 반복된다. 단가 이력 관리가 DB로 빠져 있고 유효 기간 조건으로 조회하는 구조였다면, 이번 작업은 SQL 한 줄로 끝났을 거다. 현실적으로 그 구조를 갖추지 못한 채로 서비스가 성장하는 경우가 많아서, 단가 변경 때마다 코드/쿼리를 같이 손대야 하는 패턴이 생긴다.

수정한 내용은 크게 세 갈래다.

SQL 쿼리: 집계 조건에 수수료 단가 330원 반영, 후정산 구분 컬럼 조인 추가
화면 렌더링: 익월 후정산 케이스에 라벨 표시 추가, 스타일 조정
프론트 스크립트: 라벨 표시 조건 분기 추가

결제/정산 도메인에서 숫자 수정 시 주의할 것

금융·결제 쪽 수치를 고칠 때 가장 무서운 건 "일부 케이스에서만" 틀리는 버그다. 전체 집계가 틀리면 QA에서 잡히는데, 특정 조건에서만 단가가 다르게 계산되면 오래 살아남는다.

이번 수정에서 신경 쓴 체크포인트:

항목	확인 방법
신규 단가가 모든 집계 경로에 반영됐는지	SQL 매퍼 3개 전부 수치 검색 후 대조
기존 정상 케이스(단순 결제)가 깨지지 않았는지	동일 화면에서 일반 케이스 재확인
익월 후정산 라벨이 해당 케이스에만 나오는지	일반 건과 후정산 건 각각 화면 비교
관련 화면 간 숫자 정합성	집계 화면 A와 상세 화면 B 수치 cross-check

특히 SQL 매퍼 파일이 3개였다는 건, 같은 집계를 하는 쿼리가 여러 경로(목록 조회, 엑셀 다운로드, API 응답 등)에 흩어져 있었다는 뜻이다. 하나만 고치고 나머지를 빠뜨리면 화면마다 숫자가 달라지는 최악의 상황이 된다. 이 패턴이 있을 때는 수정 전에 해당 값을 전체 코드베이스에서 검색해서 영향 범위를 먼저 파악하는 게 맞다.

-- 수정 전: 단가 하드코딩
SELECT COUNT(*) * 300 AS fee_total
FROM virtual_account_txn
WHERE status = 'SETTLED'

-- 수정 후: 단가 파라미터화 + 후정산 구분
SELECT
    COUNT(*) * :fee_unit AS fee_total,
    CASE WHEN settlement_type = 'NEXT_MONTH' THEN 'Y' ELSE 'N' END AS is_deferred
FROM virtual_account_txn
WHERE status = 'SETTLED'

실제 코드와 완전히 동일하진 않지만, 구조 변화가 이런 방향이었다. 단가를 파라미터로 받도록 바꾸면 다음 번 단가 변경 때 SQL은 건드리지 않아도 된다.

이런 작업의 트레이드오프

단가를 파라미터화하거나 DB 이력 테이블로 관리하면 유지보수성이 올라가지만, 그걸 도입하는 시점에 기존 데이터 정합성 검증과 마이그레이션이 생긴다. 서비스 규모와 단가 변경 빈도에 따라 "지금 당장 이 구조를 도입할 것인가"는 팀이 판단해야 할 영역이다.

이번엔 구조 개선보다 정확한 수치 반영과 라벨 누락 수정이 우선이었다. 그래서 범위를 최소화하고 기존 패턴을 따라가는 방향으로 수정했다. 구조 개선은 별도 이슈로 분리해두는 게 낫다. 버그 픽스와 리팩터링을 한 커밋에 섞으면 리뷰도 어렵고, 나중에 어느 변경이 문제를 일으켰는지 추적하기도 힘들어진다.

검증은 수정 후 버그를 직접 재현해서 정상 동작을 눈으로 확인하는 것으로 마무리했다. 집계 숫자는 관련된 두 화면을 나란히 열어놓고 비교했다. 자동화 테스트가 없는 영역에서 이 방식이 현실적으로 가장 빠른 검증이다.

사내 서비스를 만들다 보면 기능 하나가 화면 하나로 끝나지 않는다는 걸 계속 체감한다. SQL 집계, 상태 분기, 예외 처리, 화면 렌더링이 다 엮여 있어서 어느 하나만 빠뜨려도 숫자가 어긋나거나 특정 케이스에서 이상한 화면이 나온다. 금융 도메인은 그 "어긋남"이 신뢰 문제로 직결되니까, 꼼꼼한 게 기본값이어야 한다.

커밋은 논리적으로 독립된 단위로 쪼갰다. SQL 변경, 뷰 변경, 설정 변경을 한 덩어리로 밀어 넣으면 나중에 롤백하거나 원인을 추적할 때 전부 다 되돌려야 한다. 작은 커밋이 귀찮아 보여도, 장애 대응 상황에서 "어느 커밋에서 깨졌는지" 바로 찾을 수 있는 게 훨씬 값어치 있다.