68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
# Account Lifecycle
|
|
|
|
## Purpose
|
|
Explain how accounts are created, activated, associated with plans/subscriptions, how users access them, and how account state affects the platform.
|
|
|
|
## Code Locations (exact paths)
|
|
- Models: `backend/igny8_core/auth/models.py` (`Account`, `User`, `Plan`, `Subscription`, `Site`, `SiteUserAccess`)
|
|
- Auth middleware: `backend/igny8_core/auth/middleware.py` (sets `request.account`, validates plan status)
|
|
- Permissions: `backend/igny8_core/auth/permissions.py`
|
|
- Account settings API: `backend/igny8_core/modules/system/views.py` (account settings), `auth/views.py` (team)
|
|
- Frontend account settings: `frontend/src/pages/account/AccountSettingsPage.tsx`
|
|
- Frontend auth store: `frontend/src/store/authStore.ts`
|
|
|
|
## High-Level Responsibilities
|
|
- Maintain tenant identity (`Account`) and link users, sites, sectors, plans, subscriptions, and credits.
|
|
- Control access via account state and user roles.
|
|
- Provide account-level settings (name, billing email/address, tax info).
|
|
|
|
## Detailed Behavior
|
|
- Account fields: `name`, `slug`, `owner`, `plan`, `credits`, `status` (`active`, `suspended`, `trial`, `cancelled`), timestamps.
|
|
- User fields: extends Django user with `account` FK and `role` (`developer`, `owner`, `admin`, `editor`, `viewer`, `system_bot`).
|
|
- Plan/subscription: `Plan` defines limits and included credits; `Subscription` links account to plan and holds billing cycle/status; `Account.plan` references current plan.
|
|
- Sites: `Site` attaches to account; `SiteUserAccess` grants non-admin users site-level access.
|
|
- Middleware: `AccountContextMiddleware` resolves account from JWT or session, ensures account is active, and attaches plan information; rejects access for inactive accounts.
|
|
- Settings update: `AccountSettings` API exposes billing fields consumed by `AccountSettingsPage`.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `Account`, `User`, `Plan`, `Subscription`, `Site`, `SiteUserAccess`, `Sector`, `CreditTransaction`, `CreditUsageLog`.
|
|
|
|
## Execution Flow
|
|
- Signup/Login → JWT issued with `account_id` → middleware sets `request.account`.
|
|
- Requests pass through permissions tied to roles and account context.
|
|
- Plan changes/subscriptions update `Account.plan` and `Subscription` records (via billing endpoints and `invoice_service`/`payment_service`).
|
|
- Account settings updates persist via system/account settings endpoint and reflect in billing data.
|
|
|
|
## Cross-Module Interactions
|
|
- Billing uses `Account.credits` and plan linkage; `credit_service` deducts/credits per action.
|
|
- Sites/Planner/Writer/Automation all inherit account scoping via base viewsets and base models.
|
|
- Integration (WordPress) uses account-scoped `Site.wp_api_key` for API key auth.
|
|
|
|
## State Transitions (if applicable)
|
|
- `status`: trial → active → (suspended/cancelled) based on plan/payment handling (enforced via middleware checks).
|
|
- `plan` changes when subscriptions are created/updated; `Subscription.status` drives billing state.
|
|
- Site activation independent per site; account state still gates overall access.
|
|
|
|
## Error Handling
|
|
- Middleware rejects requests for inactive/suspended accounts; API returns unified error response.
|
|
- Permissions reject unauthorized roles before hitting business logic.
|
|
|
|
## Tenancy Rules
|
|
- Every model inherits account (direct FK or via base models); every request resolves `request.account`.
|
|
- Querysets in viewsets filter by `account` (and site/sector where applicable); public reads limited to specific cases (e.g., active site by slug).
|
|
|
|
## Billing Rules (if applicable)
|
|
- Plan inclusion and subscription determine credit grants; credits stored on `Account`; deductions logged via `CreditTransaction`/`CreditUsageLog`.
|
|
|
|
## Background Tasks / Schedulers (if applicable)
|
|
- None specific to account state; billing/automation tasks run with account context provided by Celery payloads.
|
|
|
|
## Key Design Considerations
|
|
- Account is the tenant boundary; all downstream objects carry account FK for isolation.
|
|
- Middleware centralizes account activation/plan validation to avoid per-view duplication.
|
|
|
|
## How Developers Should Work With This Module
|
|
- When adding new resources, inherit from `AccountBaseModel`/`SiteSectorBaseModel` and use base viewsets to enforce scoping.
|
|
- On new plan features/limits, extend `Plan` and ensure middleware/permissions or service checks enforce them.
|
|
- Preserve slug immutability for stability across integrations.
|