반품/교환(클레임)

개요

B2B 전용몰의 취소·반품·교환 전체 프로세스를 담당하는 기능. 주문(SO)·발주(PO)와 맞물려 구매자 신청 → 공급사 처리(승인·수거·검수·환불/재배송) → 관리자 감독의 3주체 워크플로우를 단일 도메인으로 설계했다.

배송 전 취소, 배송 후 반품(환불), 교환(맞배송)을 하나의 클레임 모델로 통합하되, 물리 처리(수거·검수·재배송)는 라인·박스 단위로 독립 추적한다.

---

왜 이 설계가 필요했는가 (Problem)

B2B 클레임은 단순 환불이 아니다 — 부분 출고·여러 공급사·여신/포인트 결제·정산 추적이 얽혀, 단일 테이블·단순 환불 로직으로는 정합성이 깨진다.

이 난제들을 헤더-라인-수거 3계층 + 마이너스 PO + 잔여 기준 금액 배분 + FIFO 포인트 환수의 조합으로 해결했다.

---

테이블 설계 — 헤더-라인-수거 3계층

ERD (핵심 관계)

테이블 구성

클레임 라인 — 수량과 금액 5차원 (정산의 핵심)

---

상태 머신 — 유형별 (취소 / 반품 / 교환)

① 취소 — 물리 흐름 없음

② 반품 — 공급사 주도, 환불로 종결

③ 교환 — 수거 후 재배송으로 종결

---

핵심 설계 결정

1. 부분 클레임 금액 배분 — 잔여 비례 + 마지막 흡수

검토한 대안 (Analyze)

판단 기준은 오차의 크기가 아니라 소멸 여부 — 대안 1·2의 오차는 합계가 원결제액과 영구히 불일치하는 정산 오차이고, 채택안의 최대 10원은 중간 회차의 일시적 차이로 전량 클레임 완료 시 합계가 정확히 일치한다(마지막 흡수로 정산).

잔여금액 = 총금액 − 기청구금액
잔여수량 = 총수량 − 기청구수량
if 잔여금액 ≤ 0 또는 잔여수량 ≤ 0: return 0  // 잔여 없음
if 요청수량 ≥ 잔여수량: return 잔여금액  // 마지막 클레임 = 잔여 전부 흡수
배분 = 잔여금액 × 요청수량 / 잔여수량  // 정수(long) 연산으로 overflow 방지
return 10원 단위 내림(배분)  // 부분 클레임 = 10원 단위 내림

2. 마이너스 PO — 원 PO 불변 + 음수 발주로 정산 순액 자동화

검토한 대안 (Analyze)

// 헤더·라인의 모든 금액 필드를 음수로 통일 → 정산 합산이 깨지지 않음
마이너스 PO.주문금액 = −클레임 총액
마이너스 PO 라인.수량 = −클레임 수량
마이너스 PO 라인.공급가 = −공급가,  부가세 = −부가세
마이너스 PO 라인.결제금액 = −클레임 금액  // 결제금액은 VAT 포함 → 부가세를 따로 더하지 않음(이중계산 방지)
클레임.마이너스 PO = 마이너스 PO  // 클레임 ↔ 마이너스 PO 양방향 참조

3. 포인트 FIFO 역추적 환수 + 만료 가드

// 사용이력 버킷을 최신순으로 채우며 복원액 = min(남은 환수액, 버킷 사용액)
for 버킷 in 사용이력(최신순):
    복원액 = min(남은 환수액, 버킷 사용액)
    if 버킷 만료일 < 오늘:
        만료손실 += 복원액  // 만료 버킷: 소생 불가 → 손실로 분리
    else:
        원장 잔액 복원(버킷, 복원액) + 환불 이력 기록  // 유효 버킷만 복원
    남은 환수액 −= 복원액

4. 헤더-라인 상태머신 + 이력 단일화

5. 합포장 수거 — 2단계 승인 + DB 레벨 중복 차단

-- 수거 중복 키: DB 가 계산해 저장하는 생성 컬럼 (GENERATED … STORED)
중복키 = CASE 합포장이면 'C:'
             번들 배송이면 'B:' + 번들 키
             그 밖이면 'D:' + 원배송 ID END
UNIQUE (클레임, 중복키, 삭제여부)  -- 같은 배송을 두 번 수거할 수 없다

6. 환불계좌 암호화

7. 배치 자동화 — 택배 추적

---

설계가 만든 결과 (Result)

검증 결과

검증이 실제 결함을 잡았다

불변식을 세우자 설계가 아니라 구현의 구멍이 드러난 사례다. 예시 테스트만 짰다면 분할검수 × 추가클레임이라는 조합을 떠올리지 못해 놓쳤을 것이다.

기각한 대안이 실제로 틀렸음을 반증했다

위 「검토한 대안」 의 기각 사유가 추측이 아니라는 것까지 확인했다. 기각 대안 2(매번 원본 기준 재계산)을 동일한 property 에 넣자:

포인트 환수 동시성 실측 (2026-08-30)

이 검증이 말하지 않는 것