구독 모델 구조

핵심 요약

• 구독은 네 계층이에요. 구독 템플릿 → 구독 정책 → 구독 상품 → 구독 계약 순으로 흘러요.
• 가격이 두 군데 나오는 건 버그가 아니라 규칙과 결과를 나눠 저장하기 때문​​이에요. 규칙은 템플릿, 결과는 상품이에요.
• "구독 플랜"이라는 단어는 네 계층 중 어느 것을 가리키는지 모호해서 문서에서 쓰지 않아요.
• 이 문서는 "단어 뜻"을 정리해요. "승인/거절/재활성화" 같은 액션 용어는 구독 용어 사전을 봐요.

이런 상황이라면

관리자 화면에서 구독 템플릿을 만들고 월 9,900원을 입력했어요. 그리고 상품을 등록할 때 같은 가격을 또 입력하라고 해요. 어느 쪽이 최종 가격인지, 템플릿을 수정하면 상품 가격도 같이 바뀌는지 헷갈려요.

이 글은 구독에서 다루는 각 엔티티가 무엇이고 가격·정책이 어떤 경로로 상품과 계약에 도달하는지 정리해요.

1네 계층

SubscriptionSetting이 "템플릿"이기도 하고 "정책"이기도 한 이유는 한 모델이 상품 귀속 여부에 따라 두 역할을 겸하기 때문이에요. 코드 주석에도 그대로 적혀 있어요. "subscription_setting 은 템플릿에서도 사용되므로 pd_id 에 속하지 않을 수 있음."

흐름은 단방향이에요.

1. 관리자가 템플릿을 등록해요.
2. 상품을 만들 때 템플릿을 참조해 상품 귀속 정책과 회차 가격표를 생성해요.
3. 고객이 구독을 신청하면 상품의 정책이 계약 쪽에 스냅샷으로 박혀요.
4. 계약 스냅샷은 불변이에요. 이후 템플릿·상품을 수정해도 이미 체결된 계약의 정책은 바뀌지 않아요.

2왜 가격이 두 군데 나오나

가격은 같은 숫자가 두 번 저장된 게 아니라 다른 것 두 개​​예요.

템플릿 가격 = 계산 규칙

모델: SubscriptionSettingPrice + SubscriptionSettingPriceOption.

• apply_target: 상품원가에 적용할지, 회차비용에 적용할지 지정해요.
• price_type: 정률(1) / 정액(2).
• use_prepaid, use_deposit: 선급금·보증금 여부.
• 옵션의 price가 음수면 할인​​이에요.

즉 "이 템플릿을 바인딩하면 원가에 10%를 더하고, 1회차에 보증금 50,000원을 얹어요" 같은 함수를 저장​​해요.

상품 회차 가격 = 결과 가격표

모델: SubscriptionPeriod (Product·ProductOption에 embed).

• cost_price: 원가.
• display_price: 판매가.
• tax_free_price: 비과세가.
• discount_price, discount_price_type: 할인가·할인 유형.
• expected_residual_value: 예상 잔존가치(렌탈·리스).
• use_times_benefit: 회차별 혜택 사용 여부.

즉 "1회차 9,900원, 2회차 9,900원, …, 12회차 8,000원" 같은 계산된 결과 표​​가 들어가요.

관계

규칙(템플릿) → 자동계산 → 결과표(상품) 한 방향이에요. 상품에 박힌 회차 가격이 고객에게 보이고 결제의 기준이 돼요. 템플릿의 규칙은 한 번 계산되고 나면 상품에 복제돼요. 템플릿을 수정해도 기존 상품·계약 가격이 자동으로 갱신되지 않는다는 뜻이에요.

관리자 UX에서 두 번 입력하는 것처럼 보이는 이유는, 템플릿의 계산 규칙이 모든 상품의 가격을 자동으로 덮지 못하기 때문에 상품 쪽에도 결과 숫자가 남기 때문이에요. 이 구조의 설계 의도는 "상품이 팔린 뒤 가격이 멋대로 바뀌지 않게 고정"하는 데 있어요.

3관리자 화면 라벨과 문서 용어

관리자 화면에서 보이는 한글 라벨과 이 문서가 쓰는 용어가 항상 같지는 않아요. 화면을 보면서 문서를 읽을 때 아래 표로 맞춰 봐요.

"구독 플랜"이라는 말은 쓰지 않아요

"구독 플랜"은 네 계층 중 무엇을 가리키는지 모호해서 문서에서 쓰지 않아요. 플랜이라는 단어를 만나면 맥락을 보고 구독 템플릿 / 구독 정책 / 구독 상품 / 회차 가격표 중 하나로 바꿔 읽어요. URL의 /subscription/plan/*은 "계약을 설계하는 단계"를 뜻하는 단계명일 뿐이에요.

4모델-API-한글 용어 매핑

관리자 API와 공개 API에서 다루는 리소스를 용어에 맞춰 정리해요.

5자주 혼동되는 것

템플릿 vs 정책

둘 다 SubscriptionSetting이지만 상품에 묶였는지 여부​​가 달라요. 묶이지 않은 것이 템플릿, 묶인 것이 정책이에요. 문서에서 "이 상품의 템플릿"이라고 쓰면 혼동을 일으키니 "이 상품의 구독 정책"으로 써요.

정책 vs 정책 스냅샷

정책은 현재 시점의 값이고, 스냅샷은 과거 어느 시점에 박힌 불변 사본​​이에요. 상품 단위 스냅샷(SubscriptionSettingSnapshot)은 상품 버전이 바뀔 때 쓰이고, 계약 단위 스냅샷(SubscriptionSettingSnapshotEmbed)은 주문이 생성된 시점의 정책을 고정해요. 계약이 체결된 뒤 정책을 수정해도 해당 계약은 스냅샷을 따라요.

상품 vs 구독 상품

상품은 엔티티, 구독 상품은 "구독 정책이 붙은 상품"이라는 상태​​를 가리키는 말이에요. 별도 테이블이 있지는 않아요. 문서에서 "구독 상품을 만들어요"는 "상품에 구독 정책을 바인딩해요"와 같아요.

구독 vs 구독 계약

"구독"이라는 단어만 쓰면 템플릿·상품·계약 중 어느 것인지 흐릿해요. 살아 있는 고객의 구독 건을 가리킬 때는 구독 계약​(OrderSubscription)이라고 쓰고, 약어가 필요하면 "계약"이라고 써요.

플랜

앞서 적었듯 엔티티 용어에서 "플랜"은 쓰지 않아요. 사내·외부 문서에서 "플랜"이라는 단어를 만나면 문맥을 보고 템플릿·정책·상품·회차 가격표 중 어느 것인지 옮겨 적어요.

관련 문서

• 구독 용어 사전 — 승인·거절·재활성화·차단 같은 라이프사이클 액션 용어.
• 구독 개요 — 상태 코드·라이프사이클·자동 과금 흐름.
• 계약 조회 — OrderSubscription 조회 API.