81 lines
6.1 KiB
Markdown
81 lines
6.1 KiB
Markdown
# Credit System
|
|
|
|
## Purpose
|
|
Detail how credits are priced, checked, deducted, logged, and reported across the platform.
|
|
|
|
## Code Locations (exact paths)
|
|
- Credit logic: `backend/igny8_core/business/billing/services/credit_service.py`
|
|
- Credit costs config: `backend/igny8_core/business/billing/models.py` (`CreditCostConfig`)
|
|
- Ledger and usage logs: `backend/igny8_core/business/billing/models.py` (`CreditTransaction`, `CreditUsageLog`)
|
|
- API endpoints: `backend/igny8_core/modules/billing/views.py` (`CreditBalanceViewSet`, `CreditUsageViewSet`)
|
|
- Constants and exceptions: `backend/igny8_core/business/billing/constants.py`, `exceptions.py`
|
|
- Plan included credits: `backend/igny8_core/auth/models.py` (`Plan.included_credits`, `Account.credits`)
|
|
|
|
## High-Level Responsibilities
|
|
- Compute operation costs (configurable per operation and unit) and enforce sufficient balance before AI/content actions.
|
|
- Deduct or add credits atomically while writing both transaction and usage log records.
|
|
- Provide balance, usage history, summaries, and limits endpoints for clients.
|
|
- Allow admin-configurable cost overrides via `CreditCostConfig`.
|
|
|
|
## Detailed Behavior
|
|
- Cost resolution (`CreditService.get_credit_cost`):
|
|
- First checks `CreditCostConfig` for the operation (active records). Supports units: `per_request`, `per_100_words`, `per_200_words`, `per_item`, `per_image`. Applies amounts when provided (e.g., words, items, images).
|
|
- Falls back to hardcoded `CREDIT_COSTS` constants; raises `CreditCalculationError` for unknown operations.
|
|
- Legacy variable costs: content_generation per 100 words, optimization per 200 words, image_generation per image, idea_generation per idea.
|
|
- Balance enforcement:
|
|
- `check_credits`/`check_credits_legacy` raise `InsufficientCreditsError` when balance insufficient.
|
|
- `deduct_credits_for_operation` computes cost, checks balance, builds a default description per operation when not supplied, then calls `deduct_credits`.
|
|
- Deduction (`deduct_credits`):
|
|
- Atomic: decrements `Account.credits`, writes `CreditTransaction` with negative amount and balance_after, writes `CreditUsageLog` capturing operation_type, cost_usd/model/tokens/related object references, metadata.
|
|
- Add credits (`add_credits`):
|
|
- Atomic: increments `Account.credits`, writes `CreditTransaction` with positive amount and balance_after.
|
|
- Logging:
|
|
- `CreditTransaction` is the authoritative ledger; `CreditUsageLog` tracks per-operation usage for analytics and summaries.
|
|
- `CreditCostConfig` tracks `previous_cost` on save when cost changes.
|
|
- Reporting endpoints (modules/billing):
|
|
- `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month (from `CreditUsageLog`), and remaining credits.
|
|
- `CreditUsageViewSet.list`: paginated usage logs filtered by operation_type and date range, account-scoped.
|
|
- `CreditUsageViewSet.summary`: aggregates credits and USD cost by operation and model over a date range (defaults to current month).
|
|
- `CreditUsageViewSet.limits`: returns plan limits (users/sites/industries/author profiles) and current usage counts, plus credits info; returns empty limits if account/plan missing.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `CreditCostConfig`: operation_type, credits_cost, unit, display_name, description, is_active, previous_cost, updated_by, timestamps.
|
|
- `CreditTransaction`: transaction_type (purchase/subscription/refund/deduction/adjustment), amount (+/-), balance_after, description, metadata, reference_id, created_at.
|
|
- `CreditUsageLog`: operation_type (clustering/idea_generation/content_generation/image_generation/reparse/legacy names), credits_used, cost_usd, model_used, tokens_in/out, related object type/id, metadata, created_at.
|
|
- `Account.credits`: current balance; `Plan.included_credits`: monthly included credits.
|
|
|
|
## Execution Flow
|
|
- Caller requests an operation → `get_credit_cost` computes cost → `check_credits` ensures balance → `deduct_credits` mutates balance and writes ledger + usage → upstream operation proceeds (AI/content).
|
|
- Balance/usage endpoints read from `Account`, `CreditUsageLog`, `Plan` to present current balances, month-to-date usage, summaries, and limits.
|
|
|
|
## Cross-Module Interactions
|
|
- AI/automation/planner/writer services call `CreditService` before expensive operations; automation aggregates credits used per stage from AI task logs, while billing logs capture actual deductions at AI call sites.
|
|
- Plan limits (users/sites/industries/authors) referenced in billing limits endpoint inform account management elsewhere.
|
|
|
|
## State Transitions
|
|
- Balance changes recorded per transaction; usage accumulates per operation. Cost configs can be toggled active/inactive and updated with audit of previous cost.
|
|
|
|
## Error Handling
|
|
- Unknown operation types raise `CreditCalculationError`; insufficient balance raises `InsufficientCreditsError` (mapped to HTTP 402 in callers).
|
|
- Balance/usage endpoints fall back to zeros/empty when account/plan missing rather than erroring.
|
|
|
|
## Tenancy Rules
|
|
- All credit operations and queries are account-scoped; viewsets filter by `request.account`/`request.user.account`. No cross-tenant access.
|
|
|
|
## Billing Rules
|
|
- Costs derived from `CreditCostConfig` > constants; units must match supplied amount. Ledger and usage logs are mandatory for every deduction/addition.
|
|
|
|
## Background Tasks / Schedulers
|
|
- None dedicated; credit usage often originates from AI Celery tasks but logging happens at the service call site.
|
|
|
|
## Key Design Considerations
|
|
- Centralized credit math and atomic DB updates prevent drift between balance, ledger, and usage logs.
|
|
- Configurable costs allow runtime tuning without code changes.
|
|
- Reporting endpoints are read-only and tolerant of missing plan data to keep dashboards resilient.
|
|
|
|
## How Developers Should Work With This Module
|
|
- Always route credit checks/deductions/additions through `CreditService`.
|
|
- When adding new AI operations, register operation_type in `CreditUsageLog`/constants and optionally seed `CreditCostConfig`.
|
|
- Include amount (words/items/images) when calling `deduct_credits_for_operation` so unit-based pricing applies.
|
|
- Use balance/usage endpoints for UI/analytics; avoid custom queries that bypass account scoping.
|