99 lines
8.4 KiB
Markdown
99 lines
8.4 KiB
Markdown
# Billing Module Reference
|
||
|
||
## Purpose
|
||
Explain how billing is implemented: invoices, payments, credit packages, credit history/usage, payment methods, and limits, as exposed by billing services and API viewsets.
|
||
|
||
## Code Locations (exact paths)
|
||
- Models: `backend/igny8_core/business/billing/models.py`
|
||
- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
|
||
- API (business billing): `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/business/billing/urls.py`
|
||
- API (core billing endpoints): `backend/igny8_core/modules/billing/views.py`, `backend/igny8_core/modules/billing/urls.py`
|
||
- Plan metadata (included credits/limits): `backend/igny8_core/auth/models.py` (`Plan`, `Account`)
|
||
|
||
## High-Level Responsibilities
|
||
- Maintain credit ledger, usage logs, configurable per-operation costs, invoices, payments, credit packages, country-level payment method configs, and account-scoped payment methods.
|
||
- Expose endpoints for invoices/payments/credit packages/transactions, credit balance/usage/limits, and admin billing operations.
|
||
- Deduct or add credits atomically while recording both transactions and usage logs.
|
||
- Provide manual and (placeholder) Stripe/PayPal payment flows.
|
||
|
||
## Detailed Behavior
|
||
- Invoices (`InvoiceViewSet`):
|
||
- `list`/`retrieve`: fetch account-scoped invoices; include totals, line items, billing period, dates.
|
||
- `download_pdf`: returns PDF bytes from `InvoiceService.generate_pdf` (currently placeholder text payload).
|
||
- Payments (`PaymentViewSet`):
|
||
- `list`: account-scoped payments with amounts, methods, status, invoice linkage, timestamps.
|
||
- `available_methods`: delegates to `PaymentService.get_available_payment_methods` (country/config-driven; returns methods plus metadata).
|
||
- `create_manual_payment`: creates a manual payment for an invoice (bank/local wallet); requires invoice_id, method, reference; rejects already-paid invoices; returns pending-approval status.
|
||
- Account payment methods (`AccountPaymentMethodViewSet`):
|
||
- CRUD for account-level payment metadata (non-sensitive). `perform_create`/`perform_update` enforce one default by resetting others when `is_default` true or none exists.
|
||
- `set_default` toggles default within the account.
|
||
- Credit packages (`CreditPackageViewSet`):
|
||
- `list`: active packages with credits/price/discount/featured/sort order.
|
||
- `purchase`: creates invoice via `InvoiceService.create_credit_package_invoice`; returns next action depending on requested payment method (`stripe`/`paypal` placeholders, manual fallback returns invoice info).
|
||
- Credit transactions (`CreditTransactionViewSet` in business billing views; also registered under `credits/transactions` in URLs): lists credit ledger entries per account.
|
||
- Core billing endpoints (`modules/billing/views.py`):
|
||
- `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month.
|
||
- `CreditUsageViewSet`: paginated credit usage logs with filters (operation_type, date range); `summary` aggregates by operation/model and totals (credits, USD); `limits` returns plan/account limits and usage (users/sites/etc.) based on `Plan` fields.
|
||
- Routing (`business/billing/urls.py`):
|
||
- Routers for invoices, payments, credit packages, transactions, payment methods, and canonical credit endpoints (balance/usage/transactions). Legacy available-methods endpoint exposed at `/payment-methods/available/`.
|
||
|
||
## Data Structures / Models Involved (no code)
|
||
- `CreditTransaction`: ledger with type, amount (positive/negative), balance_after, metadata.
|
||
- `CreditUsageLog`: per-AI-operation usage with operation_type, credits_used, cost_usd, model_used, tokens, related object references, metadata.
|
||
- `CreditCostConfig`: per-operation cost config with unit, display metadata, active flag, audit of previous cost.
|
||
- `Invoice`: invoice_number, status, amounts (subtotal/tax/total), currency, billing_period, line_items JSON, subscription link, payment metadata, timestamps.
|
||
- `Payment`: status lifecycle, method (stripe/paypal/bank/local wallet/manual), provider references, manual notes/approval, failure reason, metadata.
|
||
- `CreditPackage`, `PaymentMethodConfig` (country/method availability + instructions/bank/local wallet data), `AccountPaymentMethod` (account-scoped payment metadata).
|
||
- Plan/account credits and limits: `Plan.included_credits`, `Plan.max_users/sites/industries/author_profiles`, `Account.credits`.
|
||
|
||
## Execution Flow
|
||
- Credits:
|
||
- Operations call `CreditService.get_credit_cost` → `check_credits`/`deduct_credits` or `deduct_credits_for_operation` → updates `Account.credits`, writes `CreditTransaction` and `CreditUsageLog`.
|
||
- Costs resolved from `CreditCostConfig` when active; otherwise constants. Units support per request, per 100/200 words, per item/image/idea.
|
||
- Invoicing/Payments:
|
||
- Credit package purchase → invoice creation → next-action response (manual vs pending Stripe/PayPal integration).
|
||
- Manual payment submission → `PaymentService.create_manual_payment` persists pending approval.
|
||
- Credit balance/usage:
|
||
- Balance endpoint computes plan credits and month-to-date usage (from `CreditUsageLog`).
|
||
- Usage endpoint filters logs; summary aggregates by operation/model and totals; limits endpoint computes plan-based limits and usage (users/sites/etc.) per account.
|
||
|
||
## Cross-Module Interactions
|
||
- AI/automation/planner/writer flows trigger credit checks/deductions through `CreditService`; usage logs can be filtered by operation_type (clustering, idea_generation, content_generation, image_generation, optimization, reparse).
|
||
- Plan limits surfaced in billing limits endpoint affect account/user/site management elsewhere.
|
||
- Invoice/payment metadata may be used by frontend billing UI; manual payments require admin follow-up.
|
||
|
||
## State Transitions
|
||
- Credits mutate `Account.credits`; ledger captures each change; usage logs accumulate per operation.
|
||
- Invoices move through statuses (`draft/pending/paid/void/uncollectible`); payments through (`pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled`).
|
||
- Credit packages and payment methods have active/default flags; cost configs can be toggled active/inactive.
|
||
|
||
## Error Handling
|
||
- Insufficient credits raise `InsufficientCreditsError`; API returns 402 when caught (e.g., content generation, credit deduct flows).
|
||
- Manual payment rejects missing fields or already-paid invoices.
|
||
- Usage/balance endpoints return empty data when account/plan missing instead of hard errors.
|
||
- Validation errors on site/sector/account scoping propagate from base viewsets and model constraints.
|
||
|
||
## Tenancy Rules
|
||
- Account scoping enforced via `AccountModelViewSet` or explicit account filtering in viewsets; all billing data is per-account.
|
||
- Payment methods, invoices, payments, transactions, usage logs, and balances are filtered to `request.user.account` (or `request.account` from middleware).
|
||
- Plan data comes from the account’s associated plan; no cross-tenant visibility.
|
||
|
||
## Billing Rules
|
||
- Credit costs configurable via `CreditCostConfig`; fallback constants apply when no config.
|
||
- Credit deductions and ledger entries are atomic; usage logs record the same operation with optional model/token metadata.
|
||
- Balance endpoint includes plan monthly credits; limits endpoint reports plan/user/site limits but does not enforce them here.
|
||
|
||
## Background Tasks / Schedulers
|
||
- None specific to billing in this module; Stripe/PayPal integrations are placeholders. Any future webhooks should persist to these models and adjust credits/invoices/payments accordingly.
|
||
|
||
## Key Design Considerations
|
||
- Credit handling is centralized in `CreditService` to keep ledger and usage logs consistent.
|
||
- Usage/balance endpoints are read-mostly, with graceful handling when plan/account data is missing.
|
||
- Manual payments support bank/local wallet flows without storing sensitive data; account payment methods store display metadata only.
|
||
|
||
## How Developers Should Work With This Module
|
||
- Use `CreditService` for all credit checks/deductions/additions; do not mutate `Account.credits` directly.
|
||
- When adding new AI operations, add `operation_type` to `CreditUsageLog.OPERATION_TYPE_CHOICES` and `CreditCostConfig` seed/constants, then use `deduct_credits_for_operation`.
|
||
- Extend payment flows by implementing Stripe/PayPal handlers in `PaymentService` and wiring webhooks to update `Payment`/`Invoice`.
|
||
- Use existing serializers/viewsets when exposing billing data; keep queries scoped to `request.account`.
|