혜택 유형 체계 통합

ADR-006 혜택 유형 체계 통합

1. Metadata

• ADR ID: ADR-006
• Status: accepted
• Date: 2026-03-15
• Owner: YSY

2. Context

1. 슬롯의 혜택은 사용자에게 보여주는 핵심 약속이며, 입력 구조가 단순할수록 해석 차이와 분쟁 가능성이 줄어든다.
2. 현재 파트너 입력 모델은 혜택 대상, 혜택 유형, 혜택 값만 받는다. 설명란이나 조건란은 정책적으로 제외되어 있다.
3. discount_percent, discount_amount는 대상 + 숫자값만으로 의미가 비교적 닫힌다.
4. 반면 free_item, buy_one_get_one는 보통 다음 조건이 함께 따라온다.
   • 어떤 상품을 구매해야 하는가
   • 동일 상품인지, 다른 증정 상품인지
   • 수량 제한이 있는가
   • 재고 부족 시 어떻게 처리하는가
5. 설명란 없이 free_item, buy_one_get_one를 self-serve에서 허용하면 파트너의 의도와 사용자의 기대가 어긋날 가능성이 높다.
6. set_discount 역시 별도 유형으로 둘 이유가 약하다. 세트 상품은 benefit_target으로 표현할 수 있고, 그 위에 할인율 또는 할인액을 적용하면 된다.

3. Decision

1. Canonical benefit_type은 아래 2개만 허용한다.
   • discount_percent
   • discount_amount
2. 혜택 SoT는 benefit_type, benefit_target, benefit_value 3필드 조합으로 유지한다.
3. 세트 상품은 별도 혜택 유형으로 다루지 않는다. benefit_target에서 표현한다.
   • 예: 파스타 세트
   • 예: 브런치 세트
4. free_item, buy_one_get_one는 혜택 유형 후보로 문서상 보존하되, 현재 canonical 집합과 self-serve 입력에서는 제외한다.
5. 제외 이유는 조건 설명 없이 정확한 약속을 만들기 어렵고, 현장 해석 차이와 민원 가능성이 크기 때문이다.
6. 과거 set_discount는 레거시 값으로만 본다. 읽기 경로에서는 방어적으로 discount_amount로 수습할 수 있으나 새 쓰기 경로에서는 허용하지 않는다.
7. 과거 free_item, buy_one_get_one는 자동 치환하지 않는다. 의미 손상이 발생하므로 운영 검토 후 수동 정리 대상이다.

4. Implications

1. 사용자에게 보이는 혜택 문구는 대상 + 할인율/할인액 구조로 단순화된다.
2. 파트너 입력 UX는 숫자형 입력만 다루면 되므로 프리셋, 스텝퍼, 검증 규칙을 단순하게 유지할 수 있다.
3. 할인 외 프로모션은 현재 슬롯 모델보다 더 명시적인 조건 구조가 준비된 뒤 재검토해야 한다.
4. free_item, buy_one_get_one를 지금 넣지 않는 것은 기능 축소가 아니라 약속 명확성 우선 결정이다.

5. Deferred Options

1. free_item
   • 가능 모델: 무엇을 주문하면 어떤 항목을 무료 제공하는가를 별도 필드로 구조화
   • 보류 이유: 현재 입력 모델에서는 구매 조건과 증정 조건을 분리 표현할 수 없다.
2. buy_one_get_one
   • 가능 모델: 기준 상품, 증정 상품, 동일 상품 여부, 수량 제한을 별도 필드로 구조화
   • 보류 이유: 1+1만으로는 실제 제공 조건을 충분히 설명할 수 없다.
3. set_discount
   • 가능 모델: 세트 상품을 benefit_target으로 두고 discount_percent 또는 discount_amount 적용
   • 보류 이유: 별도 유형으로 둘 경우 discount_amount와 의미가 중복된다.

6. Tech Decision

1. DB benefit_type 제약은 discount_percent, discount_amount만 허용한다.
2. 앱 타입 시스템과 self-serve 입력 UI도 동일한 2종만 허용한다.
3. 중앙 혜택 렌더링 SoT는 App/lib/benefits.ts 이다.
4. 레거시 set_discount는 읽기 normalize에서 discount_amount로 수습할 수 있다.
5. 레거시 free_item, buy_one_get_one는 자동 변환하지 않는다. 스키마 적용 전 수동 정리가 필요하다.

7. Product Notes

1. 예시 문구
   • 아메리카노 30% 할인
   • 브런치 세트 2,000원 할인
2. 무료 제공, 1+1은 마케팅적으로 매력적일 수 있으나, 현재 입력 구조에서는 약속보다 광고 문구에 가깝다.
3. 따라서 현 단계에서는 혜택 타입이 아니라 추후 별도 프로모션 모델 후보로 남긴다.

8. Validation

• 코드와 DB와 문서의 canonical benefit_type 집합이 2종으로 일치한다.
• 세트 상품은 별도 타입 없이 benefit_target + 할인 타입으로 표현된다.
• free_item, buy_one_get_one 보류 이유가 문서에 명확히 남아 있다.
• 레거시 set_discount는 읽기 경로에서 방어 처리된다.
• 레거시 free_item, buy_one_get_one는 자동 치환 없이 수동 정리 대상으로 구분된다.

Buy me a coffee