69 lines
4.0 KiB
Markdown
69 lines
4.0 KiB
Markdown
# Pricing and Plans
|
|
|
|
## Purpose
|
|
Describe how plans and pricing are represented in the backend and how plan data is used for credits and limits.
|
|
|
|
## Code Locations (exact paths)
|
|
- Plan and account fields: `backend/igny8_core/auth/models.py` (`Plan`, `Account`)
|
|
- Billing limits endpoint: `backend/igny8_core/modules/billing/views.py` (`CreditUsageViewSet.limits`)
|
|
- Credit balance endpoint: `backend/igny8_core/modules/billing/views.py` (`CreditBalanceViewSet`)
|
|
|
|
## High-Level Responsibilities
|
|
- Define subscription plans with included credits, billing cycle, pricing, feature flags, account limits, and Stripe metadata.
|
|
- Attach plans to accounts and expose plan-based limits and credits to billing endpoints.
|
|
- Keep credit computations aligned with `included_credits` via `Plan.get_effective_credits_per_month`.
|
|
|
|
## Detailed Behavior
|
|
- `Plan` fields:
|
|
- Pricing: `price`, `billing_cycle` (`monthly/annual`), `extra_credit_price`, `allow_credit_topup`, optional auto-topup thresholds/amounts.
|
|
- Credits: `included_credits` (preferred) with legacy `credits_per_month` fallback via `get_effective_credits_per_month`.
|
|
- Limits: `max_users`, `max_sites`, `max_industries`, `max_author_profiles`.
|
|
- Stripe: `stripe_product_id`, `stripe_price_id`.
|
|
- Features: JSON `features` list; `is_active` flag.
|
|
- Validation ensures `max_sites >= 1`, `included_credits >= 0`.
|
|
- `Account` fields:
|
|
- `plan` FK, `credits` balance, status (active/suspended/trial/cancelled), billing contact/address fields, tax_id, retention days, Stripe customer id.
|
|
- Soft-delete guard prevents deleting system accounts.
|
|
- Limits computation (billing `limits` endpoint):
|
|
- Calculates current usage counts (users, sites, industries, author profiles) and returns alongside plan limits.
|
|
- Returns empty limits when account or plan is missing to keep UI resilient.
|
|
- Credit balance:
|
|
- Balance endpoint includes `plan_credits_per_month` using `Plan.get_effective_credits_per_month`.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `Plan`, `Account` (plan attachment, credits, limits, billing info).
|
|
|
|
## Execution Flow
|
|
- Account creation/association sets `plan`; credit balance endpoints read plan credits and account credits.
|
|
- Limits endpoint reads plan limits and computes current usage counts per account.
|
|
- Credit usage/deductions run against `Account.credits`; top-ups/invoices handled through billing services.
|
|
|
|
## Cross-Module Interactions
|
|
- Billing endpoints surface plan credits and limits; credit cost/deductions happen in billing services.
|
|
- Automation start checks `Account.credits` but not plan limits; plan status enforced in `AccountContextMiddleware` (requires active plan).
|
|
|
|
## State Transitions
|
|
- Plan activation toggles `is_active`; account plan changes immediately affect limits/balance reporting.
|
|
- Account status/plan changes enforced at middleware for access gating.
|
|
|
|
## Error Handling
|
|
- Plan validation errors for invalid limits/credits on save; billing endpoints return empty limits when plan/account missing instead of failing.
|
|
|
|
## Tenancy Rules
|
|
- Plans are global; accounts reference a single plan. All limit calculations are per account.
|
|
|
|
## Billing Rules
|
|
- Credits included per plan reported via balance endpoint; extra credit price/top-up fields are present but actual purchase flows are through credit packages/invoices (not auto-charging in code shown).
|
|
|
|
## Background Tasks / Schedulers
|
|
- None specific to plans; any subscription renewal logic would generate invoices/payments via billing services (not implemented here).
|
|
|
|
## Key Design Considerations
|
|
- `included_credits` supersedes legacy `credits_per_month`; keep `get_effective_credits_per_month` for backward compatibility.
|
|
- Limits are informational in the billing module; enforcement must occur in the respective domains if required.
|
|
|
|
## How Developers Should Work With This Module
|
|
- When adding new plan features or limits, extend `Plan` fields and ensure billing limits endpoint surfaces them.
|
|
- Use `get_effective_credits_per_month` wherever plan credits are displayed or calculated.
|
|
- Keep plan validation consistent (non-negative credits, minimum site/user counts).
|