쿠폰 매입 신청·정산 흐름을 상태머신으로 안정화

쿠폰 매입 신청 관리, 왜 필요했나

이커머스 파트너 정산 흐름에서 발행된 쿠폰 중 안 팔린 잔량을 다시 사들이는 절차가 필요했음. 기존엔 발행 이력만 시스템에 있었고 매입은 메일+엑셀로 수기 처리 중이었음. 운영팀이 월별 분량 늘면서 누락·중복 신청 사고 두 건 터지고 나서야 짬이 남.

설계 핵심

세 흐름으로 분리함:
- 매입 신청 접수 (파트너 측)
- 관리자 검토/승인 (어드민 측)
- 정산 반영 (수수료 차감 + 잔액 갱신)

발행 이력 화면과 매입 신청 화면을 한 컨트롤러에 합치지 않았음. 한 곳에 우겨넣으면 권한·필터·상태머신이 꼬임. 어드민도 매입용/이력용 컨트롤러 둘로 쪼갬.

상태머신

PENDING/APPROVED 단계에선 잔액 손도 안 댐. SETTLED 시점에만 한 번 적용. 이전 프로젝트에서 즉시 차감/지급 박았다가 취소·반려 롤백 누락으로 정산 차이 난 트라우마 때문.

유틸 분리

발행 수량 검증, 매입 가능 수량 계산, 단가 라운딩 같은 도메인 로직은 별도 유틸로 뺐음. 컨트롤러는 얇게 유지.

buybackable = totalIssued - totalRedeemed - alreadyBuyback
amount      = buybackable * unitPriceAtIssue

매입 단가는 발행 시점 단가로 못박음. 현재 단가 기준으로 가면 가격 변동 시 분쟁 소지 큼.

회고

• 상태머신 먼저 그리고 나서 화면 짜니 코드가 체감 30% 줄었음
• 컨트롤러 둘로 쪼갠 게 정답. 초안은 한 컨트롤러에 매입+이력 같이 넣었다가 GET 파라미터 충돌로 두 번 갈아엎음
• 매입가 계산 정책(발행 시점 vs 현재 시점) 같은 건 코드 박기 전에 운영팀과 한 줄짜리 합의문 받아두는 게 빠름. 구두 합의로 갔다가 1차 리뷰에서 뒤집힘
• 잔액 변동을 SETTLED 한 곳에서만 일으키니 회계팀 검수도 5분이면 끝남

다음