docs & ux improvmeents

2025-12-25 20:31:58 +00:00
parent 90e6e96b2b
commit 4bffede052
247 changed files with 6869 additions and 53517 deletions
--- a/docs/10-MODULES/BILLING.md
+++ b/docs/10-MODULES/BILLING.md
@@ -0,0 +1,254 @@
+# Billing Module
+
+**Last Verified:** December 25, 2025  
+**Status:** ✅ Active  
+**Backend Path:** `backend/igny8_core/modules/billing/` + `backend/igny8_core/business/billing/`  
+**Frontend Path:** `frontend/src/pages/Billing/` + `frontend/src/pages/Account/`
+
+---
+
+## Quick Reference
+
+| What | File | Key Items |
+|------|------|-----------|
+| Models | `business/billing/models.py` | `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig` |
+| Service | `business/billing/services/credit_service.py` | `CreditService` |
+| Views | `modules/billing/views.py` | `CreditBalanceViewSet`, `CreditUsageViewSet` |
+| Frontend | `pages/Account/PlansAndBillingPage.tsx` | Plans, credits, billing history |
+| Store | `store/billingStore.ts` | `useBillingStore` |
+
+---
+
+## Purpose
+
+The Billing module manages:
+- Credit balance and transactions
+- Usage tracking and limits
+- Plan enforcement
+- Payment processing
+
+---
+
+## Data Models
+
+### CreditTransaction (Ledger)
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| account | FK | Owner account |
+| transaction_type | CharField | purchase/subscription/refund/deduction/adjustment |
+| amount | Decimal | Positive (add) or negative (deduct) |
+| balance_after | Decimal | Balance after transaction |
+| description | CharField | Transaction description |
+| metadata | JSON | Additional data |
+| reference_id | CharField | External reference |
+| created_at | DateTime | Transaction time |
+
+### CreditUsageLog (Analytics)
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| account | FK | Owner account |
+| operation_type | CharField | clustering/idea_generation/content_generation/image_generation |
+| credits_used | Decimal | Credits consumed |
+| cost_usd | Decimal | USD cost |
+| model_used | CharField | AI model used |
+| tokens_in | Integer | Input tokens |
+| tokens_out | Integer | Output tokens |
+| content_type | FK | Related content type |
+| object_id | Integer | Related object ID |
+| metadata | JSON | Additional data |
+| created_at | DateTime | Usage time |
+
+### CreditCostConfig
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| operation_type | CharField | Operation name |
+| credits_cost | Decimal | Credits per unit |
+| unit | CharField | per_request/per_100_words/per_200_words/per_item/per_image |
+| display_name | CharField | UI display name |
+| description | TextField | Description |
+| is_active | Boolean | Enable/disable |
+| previous_cost | Decimal | Previous cost (audit) |
+| updated_by | FK | Last updater |
+
+---
+
+## Credit Calculation Methods
+
+### Method 1: Token-Based (Text Models)
+
+Used for: Clustering, Ideas, Content Generation, Optimization
+
+**Flow:**
+1. AI call completes
+2. OpenAI returns actual token usage
+3. Calculate: `total_tokens = input_tokens + output_tokens`
+4. Look up `CreditCostConfig` for operation
+5. Apply formula based on unit:
+   - `per_100_words`: `credits = ceil(words / 100) * cost`
+   - `per_item`: `credits = items * cost`
+6. Apply minimum credits
+7. Deduct from balance
+
+### Method 2: Fixed Cost (Image Models)
+
+Used for: Image Generation
+
+**Flow:**
+1. Before AI call
+2. Calculate: `credits = num_images * cost_per_image`
+3. Check balance sufficient
+4. Deduct credits
+5. Then make AI call
+
+---
+
+## API Endpoints
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/api/v1/billing/balance/` | `CreditBalanceViewSet.list` | Current balance + monthly usage |
+| GET | `/api/v1/billing/usage/` | `CreditUsageViewSet.list` | Usage log (paginated) |
+| GET | `/api/v1/billing/usage/summary/` | `CreditUsageViewSet.summary` | Aggregated by operation |
+| GET | `/api/v1/billing/usage/limits/` | `CreditUsageViewSet.limits` | Plan limits + current usage |
+| GET | `/api/v1/billing/transactions/` | `TransactionViewSet.list` | Transaction history |
+
+---
+
+## Credit Service API
+
+### Check Credits
+
+```python
+CreditService.check_credits(account, required_credits)
+# Raises InsufficientCreditsError if balance < required
+```
+
+### Deduct Credits
+
+```python
+CreditService.deduct_credits_for_operation(
+    account=account,
+    operation_type='content_generation',
+    amount=word_count,  # For per_word operations
+    model='gpt-4o-mini',
+    tokens_in=2500,
+    tokens_out=1500,
+    metadata={'content_id': 123}
+)
+```
+
+### Add Credits
+
+```python
+CreditService.add_credits(
+    account=account,
+    amount=1000,
+    transaction_type='purchase',
+    description='Credit package purchase'
+)
+```
+
+---
+
+## Plan Limits
+
+### Hard Limits (Never Reset)
+
+| Limit | Field | Description |
+|-------|-------|-------------|
+| Sites | `max_sites` | Maximum sites per account |
+| Users | `max_users` | Maximum team members |
+| Keywords | `max_keywords` | Total keywords allowed |
+| Clusters | `max_clusters` | Total clusters allowed |
+
+### Monthly Limits (Reset on Billing Cycle)
+
+| Limit | Field | Description |
+|-------|-------|-------------|
+| Content Ideas | `max_content_ideas` | Ideas per month |
+| Content Words | `max_content_words` | Words generated per month |
+| Basic Images | `max_images_basic` | Basic AI images per month |
+| Premium Images | `max_images_premium` | Premium AI images per month |
+| Image Prompts | `max_image_prompts` | Prompts per month |
+
+---
+
+## Usage Limits Panel
+
+**Component:** `UsageLimitsPanel.tsx`
+
+Displays:
+- Progress bars for each limit
+- Color coding: blue (safe), yellow (warning), red (critical)
+- Days until reset for monthly limits
+- Upgrade CTA when approaching limits
+
+---
+
+## Credit Costs Reference
+
+Current costs (from `CreditCostConfig`):
+
+| Operation | Unit | Default Cost |
+|-----------|------|--------------|
+| Clustering | per_request | 10 credits |
+| Idea Generation | per_item | 2 credits |
+| Content Generation | per_100_words | 5 credits |
+| Image Generation (Basic) | per_image | 3 credits |
+| Image Generation (Premium) | per_image | 5 credits |
+| Content Optimization | per_200_words | 3 credits |
+
+---
+
+## Frontend Pages
+
+### Plans & Billing (`/account/plans`)
+
+**Tabs:**
+1. **Current Plan** - Active plan, upgrade options
+2. **Credits Overview** - Balance, usage chart, cost breakdown
+3. **Purchase Credits** - Credit packages
+4. **Billing History** - Invoices and transactions
+
+### Usage Analytics (`/account/usage`)
+
+**Tabs:**
+1. **Limits & Usage** - Plan limits with progress bars
+2. **Activity** - Credit transaction history
+3. **API Usage** - API call statistics
+
+---
+
+## Integration Points
+
+| From | To | Trigger |
+|------|----|---------| 
+| AIEngine | CreditService | Pre-check and post-deduct |
+| Automation | CreditService | Per-stage credit tracking |
+| Subscription | Account | Credit allocation |
+| Admin | CreditCostConfig | Price adjustments |
+
+---
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| 402 error | Insufficient credits | Add credits or reduce operation |
+| Usage not showing | Log not created | Check CreditService called |
+| Limits wrong | Cache stale | Clear cache, reload |
+| Monthly usage high | Automation running | Pause automation |
+
+---
+
+## Planned Changes
+
+| Feature | Status | Description |
+|---------|--------|-------------|
+| AI Model Config database | 🔜 Planned | Move model pricing to database |
+| Budget alerts | 🔜 Planned | Email when approaching limits |
+| Usage forecasting | 🔜 Planned | Predict credit usage |
+| Overage billing | 🔜 Planned | Charge for overages instead of blocking |