ADR
Topics
파트너 구독 플랜 카탈로그 및 권한 통합

파트너 구독 플랜 카탈로그 및 권한 통합

ADR-270 파트너 구독 플랜 카탈로그 및 권한 통합

1. Metadata

  • ADR ID: ADR-270
  • Status: draft
  • Date: 2026-03-10
  • Owner: YSY
  • Related ADRs: ADR-090, ADR-220, ADR-230, ADR-250, ADR-280

2. Domain Decision

  1. 파트너 구독 모델은 subscription_state와 plan_code를 분리해 저장한다.
  2. subscription_state는 trialing|active|past_due|canceled|expired로 고정하고, 발행 권한은 active에서만 허용한다.
  3. 플랜 카탈로그는 버전 엔터티로 관리하고 effective_from/effective_to 구간을 명시한다.
  4. Add-on 카탈로그는 플랜 카탈로그와 분리하고 addon_code 단위로 버전 관리한다.
  5. 플랜 변경 시 권한 파라미터(entitlement) 적용 시점은 업그레이드 즉시, 다운그레이드 다음 청구 주기로 고정한다.
  6. 발행 제한 파라미터(monthly_limit, concurrent_active_slots, reissue_interval)는 플랜 카탈로그에서 단일 관리한다.
  7. 권한 판정 SoT는 partner_state + subscription_state + base_plan_entitlement + addon_entitlement 조합으로 고정한다.
  8. 쿠폰 발행/적용 규칙은 ADR-280에서 단일 관리한다.

3. Product Decision

  1. MVP 공개 판매 플랜은 월 구독 단일 플랜(basic)을 기본으로 운영한다.
  2. 확장 플랜(plus, pro)은 카탈로그에 정의할 수 있으나 is_public=false 상태에서는 노출하지 않는다.
  3. 플랜 비교 항목은 최소 월 발행 한도, 동시 노출 한도, 재발행 간격, 지원 수준으로 고정한다.
  4. 구독 해지는 기본값을 기간 종료 시 해지(cancel_at_period_end)로 제공한다.
  5. 결제 실패(past_due)는 발행 차단 상태로 처리하고 복구 경로를 즉시 제공한다.
  6. 공개 Add-on은 월 정액 10,000원 단일 가격으로 시작한다.
  7. 파트너는 Add-on을 여러 개 선택할 수 있다.
  8. pre_paid 기능은 prepaid_unlock Add-on 또는 상위 플랜 기본 권한에서만 활성화한다.
  9. 월 청구 금액은 plan_price + addon_price 합산으로 계산한다.
  10. basic 플랜에서 활성 Add-on이 3개 이상이면 plus 전환 추천을 노출한다.

3.1 Plan Catalog Baseline (2026-03-10)

아래 표는 현재 운영 기준값이다.
basic만 공개 판매하며 plus/pro는 내부 비공개 플랜(is_public=false)으로 유지한다.

plan_codeis_publicprice_krw_monthmonthly_limitconcurrent_active_slotsreissue_interval_minutesdistancesupport_level
basictrue190002012401kmstandard
plusfalse490006011202kmpriority
profalse990001202605kmdedicated

3.2 Add-on Catalog Baseline (2026-03-10)

MVP Add-on은 다중 선택 모델로 시작하며, basic에서 3개 이상 선택 시 plus 전환 추천 정책을 적용한다. 상위 등급의 혜택을 하나 선택하여 해제할 수 있다. 기본 구독료는 basic 19,000원/월이며, 아래 예시는 Add-on을 포함한 총 월 청구액 예시다.

addon_codeis_publicprice_krw_monthmax_selectableentitlement_patcheligibility
prepaid_unlocktrue1000099pre_paid=truepg_configured=true

총 월 청구액 예시:

  • basic(19,000) + prepaid_unlock(10,000) = 29,000원/월
  • basic(19,000) + Add-on 3개(각 10,000원) = 49,000원/월 -> plus(49,000원) 전환 추천

4. UX Decision

  1. 파트너 프로필에는 현재 플랜, 구독 상태, 다음 결제(또는 만료) 시점을 항상 노출한다.
  2. 플랜 변경 화면은 현재 플랜 대비 달라지는 권한 항목을 먼저 보여준다.
  3. 다운그레이드 예약 상태에서는 적용 예정일을 명시하고, 적용 전까지 현재 권한을 유지함을 안내한다.
  4. 발행 차단 화면은 차단 사유(구독 상태 vs 플랜 한도)를 구분해 노출한다.
  5. 앱은 구독 조회/상태 안내를 담당하고 결제 실행은 웹 채널로 연결한다.
  6. Add-on 선택 화면은 다중 선택과 합산 가격(기본 플랜 + Add-on 합계)을 고정 노출한다.
  7. prepaid_unlock 미보유 상태에서 선결제 설정 진입 시 구매 유도 CTA를 제공한다.
  8. basic에서 Add-on 3개 이상 선택 시 plus 전환 추천 팝업/배너를 우선 노출한다.

5. Tech Decision

  1. 구독 상태 동기화 SoT는 결제 웹훅 이벤트로 고정한다.
  2. 서버 권한 판정 함수는 plan_code, plan_version, addon_codes, entitlement_snapshot을 함께 반환한다.
  3. 플랜 변경 이벤트는 PLAN_CHANGED, 상태 변경 이벤트는 SUBSCRIPTION_STATE_CHANGED로 분리 기록한다.
  4. Add-on 변경 이벤트는 ADDON_CHANGED로 분리 기록한다.
  5. 권한 판정 응답에는 can_issue, deny_reason, next_recovery_action을 포함한다.
  6. 캐시를 사용하더라도 권한 판정 최종 값은 서버 실시간 조회 결과를 우선한다.

6. Ops Decision

  1. 카탈로그 변경(가격/한도/노출 여부)은 변경 요청서와 적용 시각을 운영 캘린더로 관리한다.
  2. 플랜 변경/실패/해지 이벤트 지연을 일일 점검 항목으로 운영한다.
  3. 상태 불일치(billing=active, capability=false 등) 감지 알람을 상시 운영한다.
  4. 가격/한도 정책 변경 시 ADR-270, ADR-090, BUSINESS 문서를 동시에 갱신한다.
  5. Add-on eligibility(pg_configured) 불일치 건수와 결제 실패율을 분리 모니터링한다.

7. Implementation Contract (Optional)

7.1 API Contract

  • 파트너 권한 조회 응답은 partner_state, subscription_state, plan_code, plan_version, addon_codes, can_issue, total_price_krw_month를 함께 포함한다.
  • 플랜 변경 요청은 target_plan_code, addon_codes, apply_timing(immediate|next_cycle)를 명시한다.
  • 발행 전 점검 API는 플랜 파라미터 스냅샷(monthly_limit, concurrent_active_slots, reissue_interval)을 반환한다.

7.2 Data Contract

  • subscription_plans: plan_code, version, price_krw, billing_cycle, is_public, effective_from, effective_to.
  • partner_subscriptions: partner_id, subscription_state, plan_code, current_period_end, cancel_at_period_end.
  • subscription_addons: addon_code, version, price_krw, is_public, max_selectable, effective_from, effective_to.
  • partner_subscription_addons: partner_id, addon_code, status, current_period_end.
  • 권한 판정 이력은 plan_code, plan_version, addon_codes, deny_reason, total_price_krw_month를 감사로그에 함께 저장한다.

7.3 Error/Observability Contract

  • 표준 코드: PARTNER_CAPABILITY_DENIED, PLAN_LIMIT_EXCEEDED, SUBSCRIPTION_PAST_DUE, PLAN_CHANGE_PENDING, ADDON_NOT_ELIGIBLE, ADDON_UPGRADE_RECOMMENDED.
  • 운영 지표: 구독 상태 동기화 지연, 플랜 변경 반영 지연, 권한 판정 불일치 건수.

7.4 Test/Acceptance Contract

  • subscription_state=active가 아니면 can_issue=false가 반환되어야 한다.
  • 업그레이드 즉시 변경 시 권한 파라미터가 같은 요청 내에서 반영되어야 한다.
  • 다운그레이드 예약 상태에서는 적용 시점 전까지 기존 권한이 유지되어야 한다.
  • 플랜 파라미터 변경 후 발행 제한 계산(ADR-090)이 새 버전을 사용해야 한다.
  • basic + prepaid_unlock 조합에서 pre_paid=true와 total_price_krw_month=29000이 반환되어야 한다. 여기서 29000은 기본 19,000원 + Add-on 10,000원의 합산 금액이다.
  • basic에서 Add-on 3개 이상 활성화 시 ADDON_UPGRADE_RECOMMENDED 안내 값이 반환되어야 한다.

8. Validation

  • Domain/Product/UX/Tech/Ops 결정이 충돌하지 않는다.
  • 구현 기준은 SPEC과 정합성을 유지한다.
  • 운영 절차는 RUNBOOK으로 연결된다.
  • ADR-090/220/250과 역할 경계가 중복되지 않는다.
Buy me a coffee Buy me a coffee
표현 밀도 및 빈 상태 통합파트너 구독 쿠폰 발행 및 적용 통합