파트너 정산 수수료 구조와 멱등성 처리 설계 추가

docs: 정산 시스템 및 파트너 포털 통합 계획서 추가

정산 및 수수료 로직은 버그 하나가 금전 오류로 직결되는 영역이라 신중하게 접근해야 함.

수수료 계산 구조

유통 단계별로 수수료가 누적되는 구조임. 최하위 파트너가 가장 높은 요율을 부담하고, 상위로 갈수록 낮아지며 그 차액이 각 단계의 수익임.

멱등성 처리

정산 배치가 중복 실행되더라도 같은 결과가 나와야 함. settlement_key를 UNIQUE로 걸고 중복 INSERT 시 IGNORE 처리.

INSERT IGNORE INTO settlement_log
  (settlement_key, partner_sn, amount, status)
VALUES
  (#{key}, #{partnerSn}, #{amount}, 'CONFIRMED')

PENDING → CONFIRMED 전환

가상계좌: 입금 확인 + 2시간 후 CONFIRMED
카드: 결제 승인 + 3일 후 CONFIRMED
취소/환불 (홀딩 중): 전부 CANCELLED (잔액 변동 없음)

PENDING 없이 즉시 차감하는 구현은 취소 처리가 복잡해짐. 상태 머신으로 관리하는 게 맞음.

정산 검증 방법

정산 결과는 반드시 수작업 계산과 대조해봐야 함.

검증 방법:
1. 특정 기간 전체 거래 합계 추출
2. 각 단계별 수수료 수동 계산
3. 시스템 정산 결과와 비교
4. 차이 발생 시 트랜잭션 단위로 추적

소수점 오차가 누적되면 큰 금액 차이로 이어질 수 있음. 모든 금액 계산은 long 타입 (원 단위 정수)으로 처리하고, 소수점이 필요한 경우에만 BigDecimal 사용함.

끝