결제 대시보드에 PG 실비용 세부 항목 8개 컬럼 추가

결제 대시보드 dashboard-pg 영역에 PG 실비용 세부 항목 컬럼 8개를 추가했다. 변경 파일은 SQL 매퍼 하나뿐. 근데 실제 작업 시간이 그 파일 한 줄 고치는 데 다 쓰인 건 아니었다.

SQL 매퍼 하나가 왜 일인가

결제 도메인 대시보드 작업이라 데이터 정의부터 다시 따져야 했다. 추가한 컬럼 구조는 이렇다.

"실비용"이 핵심이다. 거래 건수(Cnt)와 금액(Amt)은 거래 테이블에서 집계가 비교적 단순한데, PG가 실제로 가져가는 비용은 요율 구조가 카드/가상계좌별로 다르고, 청구(Charge)와 지급(Pay) 방향도 따로 계산해야 한다. 거기에 대시보드 특성상 일별/월별/누적 세 가지 집계 단위가 동시에 필요했다.

기존 SQL 매퍼에 비슷한 집계 패턴이 이미 있었다. 그게 참고가 됐는데, 동시에 주의해야 할 포인트기도 했다. 새 컬럼을 추가하면서 기존 로직이랑 계산 방식이 미묘하게 달라지면 안 된다. 집계 기준 날짜, NULL 처리 방식, 조인 순서 하나가 틀리면 합계가 달라진다.

SQL 작성할 때 기준으로 삼은 패턴:

-- pgChargeCard 건수/금액 집계 (일별)
SELECT
    trx_date,
    COUNT(CASE WHEN pg_type = 'CHARGE' AND pay_method = 'CARD' THEN 1 END)       AS pgChargeCardCnt,
    COALESCE(SUM(CASE WHEN pg_type = 'CHARGE' AND pay_method = 'CARD' THEN pg_fee END), 0) AS pgChargeCardAmt
FROM pg_transaction
WHERE trx_date BETWEEN #{startDate} AND #{endDate}
GROUP BY trx_date

COALESCE로 NULL을 0으로 처리하는 건 선택이 아니다. 해당 날짜에 거래가 없으면 SUM이 NULL을 반환하는데, 프론트에서 숫자 포맷 함수에 null이 들어오면 렌더링이 어그러진다. 기존 컬럼들도 같은 방식으로 처리하고 있었으니 패턴을 맞췄다.

폴링, 숫자 포맷, 정합성 검증

대시보드에는 5초 폴링이 걸려 있다. 실시간성이 필요한 결제 현황이라 이벤트 기반보다 단순 폴링이 더 적합하다고 판단했다. 이벤트 방식으로 가면 PG 콜백 처리 로직에 대시보드 갱신까지 엮이는데, 그 복잡도를 감수할 만큼 지연이 문제인 화면이 아니었다. 폴링이 단순하고, 고장 났을 때 원인 찾기도 쉽다.

폴링 주기가 짧으면 쿼리 호출 빈도가 올라간다. 그래서 새 집계 쿼리를 추가한 뒤 실행 계획을 확인했다. 대상 테이블에 날짜 기준 인덱스가 걸려 있어서 풀스캔은 없었고, 기존 쿼리들과 성능 차이가 크지 않다고 봤다.

숫자 포맷은 천 단위 콤마, 원 단위. 이건 백엔드에서 가공할 게 아니라 UI 레이어에서 처리하는 쪽이 낫다. 대신 백엔드가 정수값 그대로 내려줘야 프론트 포맷 함수가 정상 동작한다. 소수점이 섞이거나 문자열이 내려오면 포맷 함수가 예상과 다르게 동작한다.

검증은 화면에서 직접 했다. 새 컬럼 숫자를 관련 화면에서 동일 기간으로 조회한 값과 cross-check했다.

• 기존 화면에서 카드 청구 금액 확인
• 새 대시보드 컬럼(pgChargeCardAmt)에서 동일 기간 조회
• 두 값 일치 여부 확인, 불일치 시 집계 기준 재확인

이 과정에서 조인 기준이 미묘하게 달라 월 누적 값이 1건 차이 나는 걸 발견했다. < vs <= 경계값 날짜 처리 문제였다. 이런 건 코드 리뷰만으로는 잘 안 잡힌다. 실제 데이터로 숫자를 찍어봐야 보인다.

작업 방식 메모

결제 도메인을 계속 다루다 보면 "대충 맞는 것 같다"로 넘기면 나중에 반드시 다시 돌아온다는 걸 체감하게 된다. 숫자 하나가 틀리면 운영팀이 엑셀 정산이랑 맞춰볼 때 바로 걸린다. 그게 신뢰 문제로 이어지는 도메인이다.

이번처럼 SQL 매퍼 파일 하나만 바뀌는 작업도 커밋은 논리 단위로 쪼갰다. 집계 쿼리 추가와 컬럼 매핑 추가를 분리하면, 나중에 숫자가 이상할 때 어느 변경이 원인인지 git log로 찾기 훨씬 수월하다. 작은 커밋 습관이 디버깅 시간을 줄여준다.

사내 서비스라 외부 공개 서비스보다 꼼꼼함이 덜해도 된다고 느끼기 쉬운데, 실제로는 반대다. 정산, 운영, 재무가 그 숫자를 직접 쓴다. 화면에 버튼 하나 추가하는 것처럼 보여도 SQL 집계, 예외 처리, 포맷 통일, 화면 간 정합성이 전부 엮인다. 어느 하나만 빠뜨려도 특정 케이스에서 숫자가 맞지 않거나 이상한 값이 나온다. 그 인과관계가 명확하게 보이는 도메인이기도 해서, 작업할 때 요소 하나씩 체크하는 습관이 자연스럽게 붙었다.