docs
This commit is contained in:
IGNY8 VPS (Salman)
858
docs/billing/credits-system-audit-and-improvement-plan.md
Normal file
858
docs/billing/credits-system-audit-and-improvement-plan.md
Normal file
@@ -0,0 +1,858 @@
|
||||
# Credits System - Complete Audit and Improvement Plan
|
||||
|
||||
**Date:** December 4, 2025
|
||||
**Status:** Audit Complete - Awaiting Implementation
|
||||
**Priority:** HIGH
|
||||
|
||||
---
|
||||
|
||||
## 📋 EXECUTIVE SUMMARY
|
||||
|
||||
This document provides a comprehensive audit of the IGNY8 credits system, identifies gaps and potential issues, and proposes improvements including backend admin configuration for credit costs per function.
|
||||
|
||||
**Current State:** ✅ Working
|
||||
**Areas for Improvement:** Configuration Management, Billing Integration, Admin UI, Reporting
|
||||
|
||||
---
|
||||
|
||||
## 🔍 SYSTEM ARCHITECTURE AUDIT
|
||||
|
||||
### Current Credit System Components
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CREDITS SYSTEM │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. Account Model (credits field) │
|
||||
│ 2. CreditTransaction Model (history) │
|
||||
│ 3. CreditUsageLog Model (detailed usage) │
|
||||
│ 4. CreditService (business logic) │
|
||||
│ 5. CREDIT_COSTS (hardcoded constants) │
|
||||
│ 6. Credit API Endpoints │
|
||||
│ 7. Frontend Dashboard │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ DATABASE MODELS AUDIT
|
||||
|
||||
### 1. Account Model (`auth.Account`)
|
||||
|
||||
**Location:** `backend/igny8_core/auth/models.py`
|
||||
|
||||
**Credits Field:**
|
||||
```python
|
||||
credits = models.IntegerField(default=0, help_text="Current credit balance")
|
||||
```
|
||||
|
||||
**Status:** ✅ Working
|
||||
**Findings:**
|
||||
- Simple integer field for balance
|
||||
- No soft delete or archive mechanism
|
||||
- No credit expiration tracking
|
||||
- No overdraft protection
|
||||
|
||||
**Recommendations:**
|
||||
- ✅ Keep simple design (no changes needed)
|
||||
- Add `credits_expires_at` field for subscription credits
|
||||
- Add `bonus_credits` field separate from subscription credits
|
||||
|
||||
---
|
||||
|
||||
### 2. CreditTransaction Model
|
||||
|
||||
**Location:** `backend/igny8_core/business/billing/models.py`
|
||||
|
||||
**Current Structure:**
|
||||
```python
|
||||
class CreditTransaction(AccountBaseModel):
|
||||
TRANSACTION_TYPE_CHOICES = [
|
||||
('purchase', 'Purchase'),
|
||||
('subscription', 'Subscription Renewal'),
|
||||
('refund', 'Refund'),
|
||||
('deduction', 'Usage Deduction'),
|
||||
('adjustment', 'Manual Adjustment'),
|
||||
]
|
||||
|
||||
transaction_type = models.CharField(max_length=20, choices=TRANSACTION_TYPE_CHOICES)
|
||||
amount = models.IntegerField() # + for add, - for deduct
|
||||
balance_after = models.IntegerField()
|
||||
description = models.CharField(max_length=255)
|
||||
metadata = models.JSONField(default=dict)
|
||||
created_at = models.DateTimeField(auto_now_add=True)
|
||||
```
|
||||
|
||||
**Status:** ✅ Working
|
||||
**Findings:**
|
||||
- Comprehensive transaction types
|
||||
- Good metadata for context
|
||||
- Proper indexing on account/type/date
|
||||
- Missing: invoice_id FK, payment_method
|
||||
|
||||
**Recommendations:**
|
||||
- Add `invoice_id` FK (for billing integration)
|
||||
- Add `payment_method` field ('stripe', 'manual', 'free')
|
||||
- Add `status` field ('pending', 'completed', 'failed', 'refunded')
|
||||
- Add `external_transaction_id` for Stripe payment IDs
|
||||
|
||||
---
|
||||
|
||||
### 3. CreditUsageLog Model
|
||||
|
||||
**Location:** `backend/igny8_core/business/billing/models.py`
|
||||
|
||||
**Current Structure:**
|
||||
```python
|
||||
class CreditUsageLog(AccountBaseModel):
|
||||
OPERATION_TYPE_CHOICES = [
|
||||
('clustering', 'Clustering'),
|
||||
('idea_generation', 'Idea Generation'),
|
||||
('content_generation', 'Content Generation'),
|
||||
('image_prompt_extraction', 'Image Prompt Extraction'),
|
||||
('image_generation', 'Image Generation'),
|
||||
('linking', 'Content Linking'),
|
||||
('optimization', 'Content Optimization'),
|
||||
('site_structure_generation', 'Site Structure Generation'),
|
||||
('site_page_generation', 'Site Page Generation'),
|
||||
]
|
||||
|
||||
operation_type = models.CharField(max_length=50, choices=OPERATION_TYPE_CHOICES)
|
||||
credits_used = models.IntegerField()
|
||||
cost_usd = models.DecimalField(max_digits=10, decimal_places=2, null=True)
|
||||
model_used = models.CharField(max_length=100, blank=True)
|
||||
tokens_input = models.IntegerField(null=True)
|
||||
tokens_output = models.IntegerField(null=True)
|
||||
related_object_type = models.CharField(max_length=50, blank=True)
|
||||
related_object_id = models.IntegerField(null=True)
|
||||
metadata = models.JSONField(default=dict)
|
||||
created_at = models.DateTimeField(auto_now_add=True)
|
||||
```
|
||||
|
||||
**Status:** ✅ Working
|
||||
**Findings:**
|
||||
- Excellent detail tracking (model, tokens, cost)
|
||||
- Good related object tracking
|
||||
- Proper operation type choices
|
||||
- Missing: site/sector isolation, duration tracking
|
||||
|
||||
**Recommendations:**
|
||||
- Add `site` FK for multi-tenant filtering
|
||||
- Add `sector` FK for isolation
|
||||
- Add `duration_seconds` field (API call time)
|
||||
- Add `success` boolean field (track failures)
|
||||
- Add `error_message` field for failed operations
|
||||
|
||||
---
|
||||
|
||||
## 💳 CREDIT COST CONFIGURATION AUDIT
|
||||
|
||||
### Current Implementation: Hardcoded Constants
|
||||
|
||||
**Location:** `backend/igny8_core/business/billing/constants.py`
|
||||
|
||||
```python
|
||||
CREDIT_COSTS = {
|
||||
'clustering': 10, # Per clustering request
|
||||
'idea_generation': 15, # Per cluster → ideas request
|
||||
'content_generation': 1, # Per 100 words
|
||||
'image_prompt_extraction': 2, # Per content piece
|
||||
'image_generation': 5, # Per image
|
||||
'linking': 8, # Per content piece
|
||||
'optimization': 1, # Per 200 words
|
||||
'site_structure_generation': 50, # Per site blueprint
|
||||
'site_page_generation': 20, # Per page
|
||||
}
|
||||
```
|
||||
|
||||
**Status:** ⚠️ Working but NOT configurable
|
||||
**Problems:**
|
||||
1. ❌ **Hardcoded values** - Requires code deployment to change
|
||||
2. ❌ **No admin UI** - Cannot adjust costs without developer
|
||||
3. ❌ **No versioning** - Cannot track cost changes over time
|
||||
4. ❌ **No A/B testing** - Cannot test different pricing
|
||||
5. ❌ **No per-account pricing** - All accounts same cost
|
||||
6. ❌ **No promotional pricing** - Cannot offer discounts
|
||||
|
||||
---
|
||||
|
||||
## 💰 BILLING & INVOICING GAPS
|
||||
|
||||
### Current State
|
||||
|
||||
**✅ Working:**
|
||||
- Credit deduction on AI operations
|
||||
- Credit transaction logging
|
||||
- Credit balance API
|
||||
- Credit usage API
|
||||
- Monthly credit replenishment (Celery task)
|
||||
|
||||
**❌ Missing (NOT Implemented):**
|
||||
1. **Invoice Generation** - No Invoice model or PDF generation
|
||||
2. **Payment Processing** - No Stripe/PayPal integration
|
||||
3. **Subscription Management** - No recurring billing
|
||||
4. **Purchase Credits** - No one-time credit purchase flow
|
||||
5. **Refund Processing** - No refund workflow
|
||||
6. **Payment History** - No payment records
|
||||
7. **Tax Calculation** - No tax/VAT handling
|
||||
8. **Billing Address** - No billing info storage
|
||||
|
||||
---
|
||||
|
||||
## 🎯 PROPOSED SOLUTION: Backend Admin Configuration
|
||||
|
||||
### New Model: CreditCostConfig
|
||||
|
||||
**Purpose:** Make credit costs configurable from Django Admin
|
||||
|
||||
**Location:** `backend/igny8_core/modules/billing/models.py`
|
||||
|
||||
```python
|
||||
class CreditCostConfig(models.Model):
|
||||
"""
|
||||
Configurable credit costs per AI function
|
||||
Admin-editable alternative to hardcoded constants
|
||||
"""
|
||||
# Operation identification
|
||||
operation_type = models.CharField(
|
||||
max_length=50,
|
||||
unique=True,
|
||||
choices=CreditUsageLog.OPERATION_TYPE_CHOICES,
|
||||
help_text="AI operation type"
|
||||
)
|
||||
|
||||
# Cost configuration
|
||||
credits_cost = models.IntegerField(
|
||||
validators=[MinValueValidator(0)],
|
||||
help_text="Credits required for this operation"
|
||||
)
|
||||
|
||||
# Unit of measurement
|
||||
unit = models.CharField(
|
||||
max_length=50,
|
||||
default='per_request',
|
||||
choices=[
|
||||
('per_request', 'Per Request'),
|
||||
('per_100_words', 'Per 100 Words'),
|
||||
('per_200_words', 'Per 200 Words'),
|
||||
('per_item', 'Per Item'),
|
||||
('per_image', 'Per Image'),
|
||||
],
|
||||
help_text="What the cost applies to"
|
||||
)
|
||||
|
||||
# Metadata
|
||||
display_name = models.CharField(max_length=100, help_text="Human-readable name")
|
||||
description = models.TextField(blank=True, help_text="What this operation does")
|
||||
|
||||
# Status
|
||||
is_active = models.BooleanField(default=True, help_text="Enable/disable this operation")
|
||||
|
||||
# Audit fields
|
||||
created_at = models.DateTimeField(auto_now_add=True)
|
||||
updated_at = models.DateTimeField(auto_now=True)
|
||||
updated_by = models.ForeignKey(
|
||||
'auth.User',
|
||||
null=True,
|
||||
blank=True,
|
||||
on_delete=models.SET_NULL,
|
||||
help_text="Admin who last updated"
|
||||
)
|
||||
|
||||
# Change tracking
|
||||
previous_cost = models.IntegerField(
|
||||
null=True,
|
||||
blank=True,
|
||||
help_text="Cost before last update (for audit trail)"
|
||||
)
|
||||
|
||||
class Meta:
|
||||
db_table = 'igny8_credit_cost_config'
|
||||
verbose_name = 'Credit Cost Configuration'
|
||||
verbose_name_plural = 'Credit Cost Configurations'
|
||||
ordering = ['operation_type']
|
||||
|
||||
def __str__(self):
|
||||
return f"{self.display_name} - {self.credits_cost} credits {self.unit}"
|
||||
|
||||
def save(self, *args, **kwargs):
|
||||
# Track cost changes
|
||||
if self.pk:
|
||||
old = CreditCostConfig.objects.get(pk=self.pk)
|
||||
if old.credits_cost != self.credits_cost:
|
||||
self.previous_cost = old.credits_cost
|
||||
super().save(*args, **kwargs)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Django Admin Configuration
|
||||
|
||||
**Location:** `backend/igny8_core/modules/billing/admin.py`
|
||||
|
||||
```python
|
||||
from django.contrib import admin
|
||||
from django.utils.html import format_html
|
||||
from .models import CreditCostConfig
|
||||
|
||||
@admin.register(CreditCostConfig)
|
||||
class CreditCostConfigAdmin(admin.ModelAdmin):
|
||||
list_display = [
|
||||
'operation_type',
|
||||
'display_name',
|
||||
'credits_cost_display',
|
||||
'unit',
|
||||
'is_active',
|
||||
'cost_change_indicator',
|
||||
'updated_at',
|
||||
'updated_by'
|
||||
]
|
||||
|
||||
list_filter = ['is_active', 'unit', 'updated_at']
|
||||
search_fields = ['operation_type', 'display_name', 'description']
|
||||
|
||||
fieldsets = (
|
||||
('Operation', {
|
||||
'fields': ('operation_type', 'display_name', 'description')
|
||||
}),
|
||||
('Cost Configuration', {
|
||||
'fields': ('credits_cost', 'unit', 'is_active')
|
||||
}),
|
||||
('Audit Trail', {
|
||||
'fields': ('previous_cost', 'updated_by', 'created_at', 'updated_at'),
|
||||
'classes': ('collapse',)
|
||||
}),
|
||||
)
|
||||
|
||||
readonly_fields = ['created_at', 'updated_at', 'previous_cost']
|
||||
|
||||
def credits_cost_display(self, obj):
|
||||
"""Show cost with color coding"""
|
||||
if obj.credits_cost >= 20:
|
||||
color = 'red'
|
||||
elif obj.credits_cost >= 10:
|
||||
color = 'orange'
|
||||
else:
|
||||
color = 'green'
|
||||
return format_html(
|
||||
'<span style="color: {}; font-weight: bold;">{} credits</span>',
|
||||
color,
|
||||
obj.credits_cost
|
||||
)
|
||||
credits_cost_display.short_description = 'Cost'
|
||||
|
||||
def cost_change_indicator(self, obj):
|
||||
"""Show if cost changed recently"""
|
||||
if obj.previous_cost is not None:
|
||||
if obj.credits_cost > obj.previous_cost:
|
||||
icon = '📈' # Increased
|
||||
color = 'red'
|
||||
elif obj.credits_cost < obj.previous_cost:
|
||||
icon = '📉' # Decreased
|
||||
color = 'green'
|
||||
else:
|
||||
icon = '➡️' # Same
|
||||
color = 'gray'
|
||||
|
||||
return format_html(
|
||||
'{} <span style="color: {};">({} → {})</span>',
|
||||
icon,
|
||||
color,
|
||||
obj.previous_cost,
|
||||
obj.credits_cost
|
||||
)
|
||||
return '—'
|
||||
cost_change_indicator.short_description = 'Recent Change'
|
||||
|
||||
def save_model(self, request, obj, form, change):
|
||||
"""Track who made the change"""
|
||||
obj.updated_by = request.user
|
||||
super().save_model(request, obj, form, change)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Updated CreditService to Use Database
|
||||
|
||||
**Location:** `backend/igny8_core/business/billing/services/credit_service.py`
|
||||
|
||||
```python
|
||||
class CreditService:
|
||||
"""Service for managing credits"""
|
||||
|
||||
@staticmethod
|
||||
def get_credit_cost(operation_type, amount=None):
|
||||
"""
|
||||
Get credit cost for an operation.
|
||||
Now checks database config first, falls back to constants.
|
||||
|
||||
Args:
|
||||
operation_type: Type of operation
|
||||
amount: Optional amount (word count, image count, etc.)
|
||||
|
||||
Returns:
|
||||
int: Credit cost
|
||||
"""
|
||||
# Try to get from database config first
|
||||
try:
|
||||
from igny8_core.modules.billing.models import CreditCostConfig
|
||||
|
||||
config = CreditCostConfig.objects.filter(
|
||||
operation_type=operation_type,
|
||||
is_active=True
|
||||
).first()
|
||||
|
||||
if config:
|
||||
base_cost = config.credits_cost
|
||||
|
||||
# Apply unit-based calculation
|
||||
if config.unit == 'per_100_words' and amount:
|
||||
return max(1, (amount // 100)) * base_cost
|
||||
elif config.unit == 'per_200_words' and amount:
|
||||
return max(1, (amount // 200)) * base_cost
|
||||
elif config.unit in ['per_item', 'per_image'] and amount:
|
||||
return amount * base_cost
|
||||
else:
|
||||
return base_cost
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f"Failed to get cost from database, using constants: {e}")
|
||||
|
||||
# Fallback to hardcoded constants
|
||||
from igny8_core.business.billing.constants import CREDIT_COSTS
|
||||
|
||||
base_cost = CREDIT_COSTS.get(operation_type, 1)
|
||||
|
||||
# Apply multipliers for word-based operations
|
||||
if operation_type == 'content_generation' and amount:
|
||||
return max(1, (amount // 100)) # 1 credit per 100 words
|
||||
elif operation_type == 'optimization' and amount:
|
||||
return max(1, (amount // 200)) # 1 credit per 200 words
|
||||
elif operation_type in ['image_generation'] and amount:
|
||||
return amount * base_cost
|
||||
else:
|
||||
return base_cost
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 ADMIN UI - CREDIT COST CONFIGURATION
|
||||
|
||||
### Management Command: Initialize Credit Costs
|
||||
|
||||
**Location:** `backend/igny8_core/modules/billing/management/commands/init_credit_costs.py`
|
||||
|
||||
```python
|
||||
from django.core.management.base import BaseCommand
|
||||
from igny8_core.modules.billing.models import CreditCostConfig
|
||||
from igny8_core.business.billing.constants import CREDIT_COSTS
|
||||
|
||||
class Command(BaseCommand):
|
||||
help = 'Initialize credit cost configurations from constants'
|
||||
|
||||
def handle(self, *args, **options):
|
||||
"""Migrate hardcoded costs to database"""
|
||||
|
||||
operation_metadata = {
|
||||
'clustering': {
|
||||
'display_name': 'Auto Clustering',
|
||||
'description': 'Group keywords into semantic clusters using AI',
|
||||
'unit': 'per_request'
|
||||
},
|
||||
'idea_generation': {
|
||||
'display_name': 'Idea Generation',
|
||||
'description': 'Generate content ideas from keyword clusters',
|
||||
'unit': 'per_request'
|
||||
},
|
||||
'content_generation': {
|
||||
'display_name': 'Content Generation',
|
||||
'description': 'Generate article content using AI',
|
||||
'unit': 'per_100_words'
|
||||
},
|
||||
'image_prompt_extraction': {
|
||||
'display_name': 'Image Prompt Extraction',
|
||||
'description': 'Extract image prompts from content',
|
||||
'unit': 'per_request'
|
||||
},
|
||||
'image_generation': {
|
||||
'display_name': 'Image Generation',
|
||||
'description': 'Generate images using AI (DALL-E, Runware)',
|
||||
'unit': 'per_image'
|
||||
},
|
||||
'linking': {
|
||||
'display_name': 'Content Linking',
|
||||
'description': 'Generate internal links between content',
|
||||
'unit': 'per_request'
|
||||
},
|
||||
'optimization': {
|
||||
'display_name': 'Content Optimization',
|
||||
'description': 'Optimize content for SEO',
|
||||
'unit': 'per_200_words'
|
||||
},
|
||||
'site_structure_generation': {
|
||||
'display_name': 'Site Structure Generation',
|
||||
'description': 'Generate complete site blueprint',
|
||||
'unit': 'per_request'
|
||||
},
|
||||
'site_page_generation': {
|
||||
'display_name': 'Site Page Generation',
|
||||
'description': 'Generate site pages from blueprint',
|
||||
'unit': 'per_item'
|
||||
},
|
||||
}
|
||||
|
||||
created_count = 0
|
||||
updated_count = 0
|
||||
|
||||
for operation_type, cost in CREDIT_COSTS.items():
|
||||
# Skip legacy aliases
|
||||
if operation_type in ['ideas', 'content', 'images', 'reparse']:
|
||||
continue
|
||||
|
||||
metadata = operation_metadata.get(operation_type, {})
|
||||
|
||||
config, created = CreditCostConfig.objects.get_or_create(
|
||||
operation_type=operation_type,
|
||||
defaults={
|
||||
'credits_cost': cost,
|
||||
'display_name': metadata.get('display_name', operation_type.replace('_', ' ').title()),
|
||||
'description': metadata.get('description', ''),
|
||||
'unit': metadata.get('unit', 'per_request'),
|
||||
'is_active': True
|
||||
}
|
||||
)
|
||||
|
||||
if created:
|
||||
created_count += 1
|
||||
self.stdout.write(
|
||||
self.style.SUCCESS(f'✅ Created: {config.display_name} - {cost} credits')
|
||||
)
|
||||
else:
|
||||
updated_count += 1
|
||||
self.stdout.write(
|
||||
self.style.WARNING(f'⚠️ Already exists: {config.display_name}')
|
||||
)
|
||||
|
||||
self.stdout.write(
|
||||
self.style.SUCCESS(f'\n✅ Complete: {created_count} created, {updated_count} already existed')
|
||||
)
|
||||
```
|
||||
|
||||
**Run command:**
|
||||
```bash
|
||||
python manage.py init_credit_costs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 POTENTIAL ISSUES & FIXES
|
||||
|
||||
### Issue 1: Race Conditions in Credit Deduction
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
# Current code (simplified)
|
||||
if account.credits < required:
|
||||
raise InsufficientCreditsError()
|
||||
account.credits -= required # Race condition here!
|
||||
account.save()
|
||||
```
|
||||
|
||||
**Risk:** Two requests could both check balance and deduct simultaneously
|
||||
|
||||
**Fix:** Use database-level atomic update
|
||||
```python
|
||||
from django.db.models import F
|
||||
|
||||
@transaction.atomic
|
||||
def deduct_credits(account, amount):
|
||||
# Atomic update with check
|
||||
updated = Account.objects.filter(
|
||||
id=account.id,
|
||||
credits__gte=amount # Check in database
|
||||
).update(
|
||||
credits=F('credits') - amount
|
||||
)
|
||||
|
||||
if updated == 0:
|
||||
raise InsufficientCreditsError()
|
||||
|
||||
account.refresh_from_db()
|
||||
return account.credits
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 2: Negative Credit Balance
|
||||
|
||||
**Problem:** No hard constraint preventing negative credits
|
||||
|
||||
**Fix 1:** Database constraint
|
||||
```python
|
||||
# Migration
|
||||
operations = [
|
||||
migrations.AddConstraint(
|
||||
model_name='account',
|
||||
constraint=models.CheckConstraint(
|
||||
check=models.Q(credits__gte=0),
|
||||
name='credits_non_negative'
|
||||
),
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
**Fix 2:** Service layer validation (current approach - OK)
|
||||
|
||||
---
|
||||
|
||||
### Issue 3: Missing Credit Expiration
|
||||
|
||||
**Problem:** Subscription credits never expire
|
||||
|
||||
**Fix:** Add expiration tracking
|
||||
```python
|
||||
# Account model
|
||||
credits_expires_at = models.DateTimeField(null=True, blank=True)
|
||||
|
||||
# Celery task (daily)
|
||||
@shared_task
|
||||
def expire_credits():
|
||||
"""Expire old credits"""
|
||||
expired = Account.objects.filter(
|
||||
credits_expires_at__lt=timezone.now(),
|
||||
credits__gt=0
|
||||
)
|
||||
|
||||
for account in expired:
|
||||
# Transfer to expired_credits field or log
|
||||
account.credits = 0
|
||||
account.save()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 4: No Usage Analytics
|
||||
|
||||
**Problem:** Hard to analyze which functions cost most credits
|
||||
|
||||
**Fix:** Add aggregation views
|
||||
```python
|
||||
# Backend
|
||||
@action(detail=False, methods=['get'])
|
||||
def cost_breakdown(self, request):
|
||||
"""Get credit cost breakdown by operation"""
|
||||
from django.db.models import Sum
|
||||
|
||||
breakdown = CreditUsageLog.objects.filter(
|
||||
account=request.account
|
||||
).values('operation_type').annotate(
|
||||
total_credits=Sum('credits_used'),
|
||||
count=Count('id')
|
||||
).order_by('-total_credits')
|
||||
|
||||
return Response(breakdown)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 5: No Budget Alerts
|
||||
|
||||
**Problem:** Users can run out of credits unexpectedly
|
||||
|
||||
**Fix:** Add threshold alerts
|
||||
```python
|
||||
# After each deduction
|
||||
def check_low_balance(account):
|
||||
if account.credits < 100: # Configurable threshold
|
||||
send_low_balance_email(account)
|
||||
|
||||
if account.credits < 50:
|
||||
send_critical_balance_email(account)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 FUTURE ENHANCEMENTS
|
||||
|
||||
### Phase 1: Billing Integration (Priority: HIGH)
|
||||
|
||||
**Models to Add:**
|
||||
1. `Invoice` - Store invoice records
|
||||
2. `Payment` - Track payments
|
||||
3. `Subscription` - Recurring billing
|
||||
4. `CreditPackage` - One-time credit purchases
|
||||
|
||||
**Integrations:**
|
||||
- Stripe for payments
|
||||
- PDF generation for invoices
|
||||
- Email notifications
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Advanced Pricing (Priority: MEDIUM)
|
||||
|
||||
**Features:**
|
||||
1. **Volume Discounts**
|
||||
- 1000+ credits/month: 10% discount
|
||||
- 5000+ credits/month: 20% discount
|
||||
|
||||
2. **Per-Account Pricing**
|
||||
- Enterprise accounts: Custom pricing
|
||||
- Trial accounts: Limited operations
|
||||
|
||||
3. **Promotional Codes**
|
||||
- Discount codes
|
||||
- Free credit grants
|
||||
|
||||
4. **Credit Bundles**
|
||||
- Starter: 500 credits
|
||||
- Pro: 2000 credits
|
||||
- Enterprise: 10000 credits
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Usage Analytics Dashboard (Priority: MEDIUM)
|
||||
|
||||
**Features:**
|
||||
1. **Cost Breakdown Charts**
|
||||
- By operation type
|
||||
- By time period
|
||||
- By site/sector
|
||||
|
||||
2. **Trend Analysis**
|
||||
- Daily/weekly/monthly usage
|
||||
- Forecasting
|
||||
- Budget alerts
|
||||
|
||||
3. **Comparison Reports**
|
||||
- Compare accounts
|
||||
- Compare time periods
|
||||
- Benchmark against averages
|
||||
|
||||
---
|
||||
|
||||
## 🧪 TESTING CHECKLIST
|
||||
|
||||
### Unit Tests Required
|
||||
|
||||
- [ ] Test CreditCostConfig model creation
|
||||
- [ ] Test CreditService with database config
|
||||
- [ ] Test fallback to constants
|
||||
- [ ] Test atomic credit deduction
|
||||
- [ ] Test negative balance prevention
|
||||
- [ ] Test cost calculation with units
|
||||
|
||||
### Integration Tests Required
|
||||
|
||||
- [ ] Test full credit deduction flow
|
||||
- [ ] Test monthly replenishment
|
||||
- [ ] Test admin UI operations
|
||||
- [ ] Test concurrent deductions (race conditions)
|
||||
- [ ] Test cost changes propagate correctly
|
||||
|
||||
### Manual Testing Required
|
||||
|
||||
- [ ] Create credit config in Django Admin
|
||||
- [ ] Update cost and verify in logs
|
||||
- [ ] Deactivate operation and verify rejection
|
||||
- [ ] Test with different units (per 100 words, per image)
|
||||
- [ ] Verify audit trail (previous_cost, updated_by)
|
||||
|
||||
---
|
||||
|
||||
## 📋 IMPLEMENTATION ROADMAP
|
||||
|
||||
### Week 1: Database Configuration
|
||||
- [ ] Create `CreditCostConfig` model
|
||||
- [ ] Create migration
|
||||
- [ ] Create Django Admin
|
||||
- [ ] Create init_credit_costs command
|
||||
- [ ] Update CreditService to use database
|
||||
|
||||
### Week 2: Testing & Refinement
|
||||
- [ ] Write unit tests
|
||||
- [ ] Write integration tests
|
||||
- [ ] Manual QA testing
|
||||
- [ ] Fix race conditions
|
||||
- [ ] Add constraints
|
||||
|
||||
### Week 3: Documentation & Deployment
|
||||
- [ ] Update API documentation
|
||||
- [ ] Create admin user guide
|
||||
- [ ] Deploy to staging
|
||||
- [ ] User acceptance testing
|
||||
- [ ] Deploy to production
|
||||
|
||||
### Week 4: Monitoring & Optimization
|
||||
- [ ] Monitor cost changes
|
||||
- [ ] Analyze usage patterns
|
||||
- [ ] Optimize slow queries
|
||||
- [ ] Plan Phase 2 features
|
||||
|
||||
---
|
||||
|
||||
## 🎯 SUCCESS CRITERIA
|
||||
|
||||
✅ **Backend Admin:** Credits configurable via Django Admin
|
||||
✅ **No Code Deploys:** Cost changes don't require deployment
|
||||
✅ **Audit Trail:** Track who changed costs and when
|
||||
✅ **Backward Compatible:** Existing code continues to work
|
||||
✅ **Performance:** No regression in credit deduction speed
|
||||
✅ **Data Integrity:** No race conditions or negative balances
|
||||
✅ **Testing:** 100% test coverage for critical paths
|
||||
|
||||
---
|
||||
|
||||
## 📊 CREDITS SYSTEM FLOWCHART
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[AI Operation Request] --> B{Check CreditCostConfig}
|
||||
B -->|Found| C[Get Cost from Database]
|
||||
B -->|Not Found| D[Get Cost from Constants]
|
||||
C --> E[Calculate Total Cost]
|
||||
D --> E
|
||||
E --> F{Sufficient Credits?}
|
||||
F -->|Yes| G[Atomic Deduct Credits]
|
||||
F -->|No| H[Raise InsufficientCreditsError]
|
||||
G --> I[Create CreditTransaction]
|
||||
I --> J[Create CreditUsageLog]
|
||||
J --> K[Return Success]
|
||||
H --> L[Return Error]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 SECURITY CONSIDERATIONS
|
||||
|
||||
### Credit Manipulation Prevention
|
||||
|
||||
1. **No Client-Side Credit Calculation**
|
||||
- All calculations server-side
|
||||
- Credits never exposed in API responses
|
||||
|
||||
2. **Atomic Transactions**
|
||||
- Use database transactions
|
||||
- Prevent race conditions
|
||||
|
||||
3. **Audit Logging**
|
||||
- Log all credit changes
|
||||
- Track who/when/why
|
||||
|
||||
4. **Rate Limiting**
|
||||
- Prevent credit abuse
|
||||
- Throttle expensive operations
|
||||
|
||||
5. **Admin Permissions**
|
||||
- Only superusers can modify costs
|
||||
- Track all admin changes
|
||||
|
||||
---
|
||||
|
||||
## END OF AUDIT
|
||||
|
||||
This comprehensive audit identifies all aspects of the credits system, proposes a database-driven configuration approach, and provides a clear roadmap for implementation. The system is currently working well but lacks flexibility for cost adjustments without code deployments.
|
||||
|
||||
**Recommendation:** Implement the CreditCostConfig model in Phase 1 to enable admin-configurable costs.
|
||||
Reference in New Issue
Block a user