정산 사전 시뮬레이션 화면과 수수료 체계 문서화로 파트너 문의 대응

정산 미리보기 화면이 필요했던 이유

이번 주 가장 큰 이슈는 "정산이 왜 이 금액이냐"는 파트너 문의가 반복되는 거였음. 배치가 새벽에 한 번 돌고 나면 그제서야 결과를 보는데, 숫자가 이상하면 이미 늦음. 그래서 사전 시뮬레이션 화면을 하나 박기로 함.

핵심 요구는 세 가지였음.

• 배치 돌기 전에 같은 로직으로 미리보기 가능할 것
• 운영자가 임의 일자에 수동 실행 트리거 가능할 것
• 수수료 산식 자체가 코드 안에만 있으니 문서로 빼낼 것

미리보기 JSP — 일부러 단순하게

화면은 의도적으로 못생기게 만들었음. 운영자만 보는 내부 페이지라 디자인 시간 쓰기 아까웠고, 숫자 검증이 본질임.

diff 컬럼이 의외로 효자였음. 로직 수정 후 미리보기 돌려서 어제 결과랑 차이 보면 수수료 계산 변경 영향이 한눈에 들어옴.

배치 수동실행 API

배치를 매번 새벽까지 기다릴 수 없어서 운영자 권한으로 트리거 가능한 엔드포인트를 깠음. 단, 안전장치 필수.

POST /admin/settlement/run
{
  "targetDate": "2026-03-18",
  "dryRun": true,
  "partnerId": null
}

• dryRun=true 가 기본값. 실제 적립/차감은 명시적으로 false 줘야 동작
• 같은 일자 중복 실행 시 기존 결과 삭제 후 재생성 — 냉정하게
• 실행 이력은 별도 로그에 운영자ID + 파라미터 + 결과건수 남김

처음에 dryRun 기본값을 false로 뒀다가 검토하면서 바꿈. 운영자가 실수로 운영 잔액 건드릴 위험이 너무 컸음.

수수료 체계 문서화가 제일 오래 걸림

코드만 보면 산식이 흩어져 있어서 신규 인원이 들어오면 며칠 걸려야 이해함. SKILL 문서로 정리.

• 충전수수료 / 결제수수료 / 판매대금 — 3건 모두 PENDING 으로 생성 후 정산 시점에 CONFIRMED
• 가상계좌 +2시간 hold, 카드 +3일 hold
• 마진은 상위 계층 수익 — 가맹점 요율 - 총판 요율 = 총판 수익
• 결제대행사 청구 4종 중 일부는 익월 후정산 — 화면에는 표시만, 잔액 차감은 익월

가장 강조한 줄은 "PENDING 없이 즉시 차감하는 코드는 버그" 한 줄. 이거 모르고 들어오면 환불 처리에서 100% 사고남.

회고

미리보기 화면 만들면서 정작 배운 건 dryRun 기본값을 안전쪽에 두는 습관이었음. 그리고 산식 문서를 코드 옆이 아니라 SKILL 같은 검색 가능한 위치에 둬야 신규 인원이 실제로 찾아본다는 것도. 다음엔 미리보기 결과를 CSV로 내려받는 기능 붙일 예정.

끝