Plan/Entitlement Model

1) مسئله‌ای که این درس حل می‌کند

در بسیاری از محصولات SaaS، نام Plan، شناسهٔ Product/Price در سیستم billing و دسترسی واقعی داخل application در سه جای متفاوت نگه‌داری می‌شوند. اگر این سه لایه یکی فرض شوند، تغییر قیمت می‌تواند بدون قصد، semantics دسترسی را عوض کند یا یک exception موقت به دسترسی دائمی تبدیل شود.

2) مرز درس و خروجی

خروجی این درس Plan-to-Entitlement Contract v1 است. این درس مالک P&L درس ARC-019 یا SLA/Support درس ARC-021 نیست و هیچ billing، subscription، tenant یا authorization زنده را تغییر نمی‌دهد.

3) Fact: Billing Entitlement می‌تواند Feature Access را مدل کند

Stripe Entitlements برای تعیین زمان grant یا revoke شدن product feature access طراحی شده است. این یک نمونهٔ رسمی از جدا کردن capability از نمایش تجاری plan است؛ اما taxonomy و authorization policy خود MAKNOW را تعیین نمی‌کند.

4) Fact: Product و Price با Entitlement یکی نیستند

در Stripe، Product مشخص می‌کند چه چیزی فروخته می‌شود و Price مشخص می‌کند چقدر و با چه الگوی recurring charge می‌شود؛ flat-rate، per-seat، tiered و usage-based نمونه‌های documented هستند. هیچ‌کدام به‌تنهایی ثابت نمی‌کنند runtime چه featureای را باید grant کند.

5) مدل ذهنی درست: Commercial Authority → Entitlement → Runtime

جریان پایه این است: plan/product/price/subscription → entitlement mapping → feature grant/limit → runtime snapshot → reconciliation. plan name نباید به‌عنوان permission key داخل application hard-code شود.

6) Contract را با هویت‌های پایدار بساز

حداقل plan_id، product_id، price_id، entitlement_id و feature_key را جدا ثبت کن. اگر قیمت عوض شد ولی entitlement mapping همان نسخهٔ قدیمی ماند، نتیجه باید DRIFT باشد، نه success.

7) Grant و Limit را از Billing جدا کن

grant_state نشان می‌دهد feature از نظر entitlement باید فعال باشد یا نه. limit_type و limit_value capacity را مشخص می‌کنند. Boolean grant، seat limit و metered allowance semantics متفاوت دارند و نباید در یک عدد مبهم ادغام شوند.

8) Metering باید Authority مشخص داشته باشد

اگر limit_type=METERED است، meter_ref باید معلوم باشد. feature متری بدون meter reference قابل reconcile نیست و state باید HOLD بماند.

9) Effective Window را جدی بگیر

effective_from و effective_to مشخص می‌کنند entitlement یا exception در چه بازه‌ای معتبر است. دسترسی خارج از window معتبر باید به‌عنوان drift/revocation بررسی شود، نه اینکه چون runtime هنوز feature را می‌دهد معتبر فرض شود.

10) Override موقت را به بدهی پنهان تبدیل نکن

هر override باید override_id، owner، reason و expiry داشته باشد. override معتبر می‌تواند state OVERRIDE تولید کند؛ اما اگر expiry گذشته و runtime هنوز access اضافه دارد، تصمیم باید REVOKE باشد.

11) Revocation Trigger را صریح کن

subscription stateهایی مثل unpaid یا canceled فقط billing metadata نیستند اگر policy آن‌ها را revocation trigger تعریف کرده باشد. evaluator باید trigger را با runtime snapshot تطبیق دهد و access باقی‌مانده را آشکار کند.

12) Core Evidence Contract

این درس 20 بُعد evidence دارد که 16 بُعد آن بحرانی است. جدول زیر سه حالت baseline، stale mapping و transfer را فشرده نشان می‌دهد؛ CSV/JSON mapping کامل را نگه می‌دارد.

13) Typed State جلوی موفقیت جعلی را می‌گیرد

خروجی‌های ALIGNED، DRIFT، OVERRIDE، REVOKE و HOLD همگی معتبرند. اگر evidence لازم وجود ندارد، model یا learner حق ندارد با حدس آن را به ALIGNED تبدیل کند.

14) Reconciliation یک Gate تکرارشونده است

تغییر Price، Plan، limit، meter، subscription state یا override window باید review/reconciliation را trigger کند. runtime snapshot فقط observation است؛ authority از commercial contract و entitlement mapping می‌آید.

15) Lab، Transfer و Freshness

Lab هشت fixture و 48 assertion دارد. در transfer، مشتری هنگام renewal downgrade می‌شود، override هفت‌روزهٔ seat را نگه می‌دارد و یک feature از flat به metered می‌رود. نتیجه باید از evidence جدید دوباره محاسبه شود. مستندات Stripe در این درس Fact هستند؛ thresholds، state vocabulary و override policy طراحی MAKNOW هستند.