859 lines
26 KiB
Markdown
859 lines
26 KiB
Markdown
# 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.
|