275 lines
6.3 KiB
Markdown
275 lines
6.3 KiB
Markdown
# Credits & Limits Implementation - Quick Summary
|
|
|
|
**Status:** 🚧 READY TO IMPLEMENT
|
|
**Timeline:** 5 weeks
|
|
**Priority:** HIGH
|
|
|
|
---
|
|
|
|
## The Big Picture
|
|
|
|
### What We're Doing
|
|
Simplifying the IGNY8 credits and limits system from complex (10+ limits) to simple (4 limits only).
|
|
|
|
### Core Philosophy
|
|
**Keep only 4 hard limits. Everything else = credits.**
|
|
|
|
---
|
|
|
|
## The 4 Limits (FINAL)
|
|
|
|
| Limit | Type | What It Controls |
|
|
|-------|------|-----------------|
|
|
| **Sites** | Hard | Max sites per account (e.g., 1, 2, 5, unlimited) |
|
|
| **Team Users** | Hard | Max team members (e.g., 1, 2, 3, 5) |
|
|
| **Keywords** | Hard | Total keywords in workspace (e.g., 100, 1K, 5K, 20K) |
|
|
| **Ahrefs Queries** | Monthly | Live keyword research per month (e.g., 0, 50, 200, 500) |
|
|
|
|
**Everything else (content, images, ideas, etc.) = credits only.**
|
|
|
|
---
|
|
|
|
## What Gets REMOVED
|
|
|
|
### Database Fields to Delete
|
|
|
|
**From Plan Model:**
|
|
- ❌ `max_content_ideas`
|
|
- ❌ `max_content_words`
|
|
- ❌ `max_images_basic`
|
|
- ❌ `max_images_premium`
|
|
- ❌ `max_image_prompts`
|
|
- ❌ `max_clusters` (consider merging with keywords)
|
|
|
|
**From Account Model:**
|
|
- ❌ `usage_content_ideas`
|
|
- ❌ `usage_content_words`
|
|
- ❌ `usage_images_basic`
|
|
- ❌ `usage_images_premium`
|
|
- ❌ `usage_image_prompts`
|
|
|
|
### Why?
|
|
- Confusing for users (double limiting)
|
|
- Maintenance overhead
|
|
- Credit system already provides control
|
|
|
|
---
|
|
|
|
## What Gets ADDED
|
|
|
|
### New Fields
|
|
|
|
**Plan Model:**
|
|
```python
|
|
max_ahrefs_queries = models.IntegerField(default=50)
|
|
```
|
|
|
|
**Account Model:**
|
|
```python
|
|
usage_ahrefs_queries = models.IntegerField(default=0)
|
|
```
|
|
|
|
### New Feature: Keyword Research
|
|
|
|
**Two ways to add keywords:**
|
|
|
|
1. **Browse Pre-Researched Keywords** (FREE)
|
|
- IGNY8's global keyword database
|
|
- Pre-analyzed, ready to use
|
|
- Limited by: `max_keywords` (workspace limit)
|
|
|
|
2. **Research with Ahrefs** (LIMITED)
|
|
- Live Ahrefs API queries
|
|
- Fresh, custom keyword data
|
|
- Limited by: `max_ahrefs_queries` (monthly limit)
|
|
|
|
---
|
|
|
|
## Page Changes
|
|
|
|
### Plans & Billing Page (Simplified)
|
|
|
|
**Current Plan Tab - BEFORE:**
|
|
- ❌ Credit balance display
|
|
- ❌ Usage charts
|
|
- ❌ Limit progress bars
|
|
- ❌ "Credits used this month" breakdown
|
|
|
|
**Current Plan Tab - AFTER:**
|
|
- ✅ Plan name, price, renewal date
|
|
- ✅ Brief summary: "50 articles • 2 sites • 2 users"
|
|
- ✅ Upgrade CTA
|
|
- ❌ NO detailed usage (moved to Usage page)
|
|
|
|
### Usage Page (Enhanced)
|
|
|
|
**NEW Tab Structure:**
|
|
|
|
1. **Overview** (NEW)
|
|
- Quick stats cards (credits, sites, users, keywords)
|
|
- Period selector (7, 30, 90 days)
|
|
- Top metrics
|
|
|
|
2. **Your Limits**
|
|
- Only 4 limits with progress bars
|
|
- Sites, Users, Keywords, Ahrefs Queries
|
|
|
|
3. **Credit Insights** (NEW)
|
|
- Credits by Site
|
|
- Credits by Action Type
|
|
- Credits by Image Quality (basic/quality/premium)
|
|
- Credits by Automation
|
|
- Timeline chart
|
|
|
|
4. **Activity Log**
|
|
- Detailed transaction history
|
|
- (Renamed from "API Activity")
|
|
|
|
---
|
|
|
|
## Key Implementation Tasks
|
|
|
|
### Backend (Week 1-2)
|
|
|
|
1. **Remove unused fields**
|
|
- Create migration to drop fields
|
|
- Update models, serializers
|
|
- Remove from LimitService mappings
|
|
|
|
2. **Add Ahrefs fields**
|
|
- Add to Plan and Account models
|
|
- Add to LimitService mappings
|
|
- Create Ahrefs service
|
|
|
|
3. **Enforce limits properly**
|
|
- Add keyword limit checks to ALL entry points
|
|
- Add automation credit pre-check
|
|
- Validate before all operations
|
|
|
|
### Frontend (Week 2-3)
|
|
|
|
1. **Clean up Plans & Billing**
|
|
- Remove duplicate credit/usage data
|
|
- Keep only financial info
|
|
|
|
2. **Enhance Usage page**
|
|
- Add Overview tab
|
|
- Add Credit Insights tab with widgets
|
|
- Multi-dimensional breakdowns
|
|
|
|
3. **Build Keyword Research**
|
|
- Browse panel (existing SeedKeywords)
|
|
- Ahrefs panel (new)
|
|
- Query limit indicator
|
|
|
|
4. **Update terminology**
|
|
- Remove "API", "operations"
|
|
- Use "actions", "activities"
|
|
|
|
---
|
|
|
|
## Validation Requirements
|
|
|
|
### Must Check BEFORE Every Operation
|
|
|
|
**All AI Operations:**
|
|
```python
|
|
# 1. Check credits
|
|
CreditService.check_credits(account, estimated_credits)
|
|
|
|
# 2. Execute
|
|
result = ai_service.execute()
|
|
|
|
# 3. Deduct
|
|
CreditService.deduct_credits_for_operation(...)
|
|
```
|
|
|
|
**Keyword Creation:**
|
|
```python
|
|
# Check limit
|
|
LimitService.check_hard_limit(account, 'keywords', count)
|
|
|
|
# Then create
|
|
Keywords.objects.bulk_create([...])
|
|
```
|
|
|
|
**Automation Runs:**
|
|
```python
|
|
# Estimate total cost
|
|
estimated = estimate_automation_cost(config)
|
|
|
|
# Check BEFORE starting
|
|
CreditService.check_credits(account, estimated)
|
|
|
|
# Then run
|
|
execute_automation(config)
|
|
```
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### Technical
|
|
- [ ] All unused fields removed
|
|
- [ ] 4 limits properly enforced
|
|
- [ ] Credit checks before ALL operations
|
|
- [ ] Automation pre-checks credits
|
|
- [ ] No duplicate data across pages
|
|
|
|
### User Experience
|
|
- [ ] Simple 4-limit model is clear
|
|
- [ ] Multi-dimensional insights are actionable
|
|
- [ ] Keyword research flow is intuitive
|
|
- [ ] Error messages are user-friendly
|
|
- [ ] Upgrade prompts at right moments
|
|
|
|
### Business
|
|
- [ ] Reduced support questions
|
|
- [ ] Higher upgrade conversion
|
|
- [ ] Better credit visibility
|
|
- [ ] System scales cleanly
|
|
|
|
---
|
|
|
|
## Suggested Plan Values
|
|
|
|
| Plan | Price | Credits/mo | Sites | Users | Keywords | Ahrefs/mo |
|
|
|------|-------|-----------|-------|-------|----------|-----------|
|
|
| **Free** | $0 | 2,000 | 1 | 1 | 100 | 0 |
|
|
| **Starter** | $49 | 10,000 | 2 | 2 | 1,000 | 50 |
|
|
| **Growth** | $149 | 40,000 | 5 | 3 | 5,000 | 200 |
|
|
| **Scale** | $399 | 120,000 | ∞ | 5 | 20,000 | 500 |
|
|
|
|
---
|
|
|
|
## Timeline
|
|
|
|
**Week 1:** Backend cleanup (remove fields, add Ahrefs)
|
|
**Week 2:** Enforcement (keyword limits, automation checks)
|
|
**Week 3:** Frontend cleanup (remove duplicates, update UI)
|
|
**Week 4:** New features (Credit Insights, Keyword Research)
|
|
**Week 5:** Testing & Production deployment
|
|
|
|
---
|
|
|
|
## Files to Review
|
|
|
|
**Full Implementation Plan:**
|
|
- `docs/plans/CREDITS-LIMITS-IMPLEMENTATION-PLAN.md`
|
|
|
|
**Current System Docs:**
|
|
- `docs/10-MODULES/BILLING.md`
|
|
- `docs/40-WORKFLOWS/CREDIT-SYSTEM.md`
|
|
|
|
**Code:**
|
|
- Backend: `backend/igny8_core/auth/models.py`
|
|
- Backend: `backend/igny8_core/business/billing/services/limit_service.py`
|
|
- Frontend: `frontend/src/pages/account/PlansAndBillingPage.tsx`
|
|
- Frontend: `frontend/src/pages/account/UsageAnalyticsPage.tsx`
|
|
|
|
---
|
|
|
|
**Status:** ✅ READY FOR TEAM REVIEW AND IMPLEMENTATION
|
|
|
|
**Next Step:** Schedule implementation kickoff meeting with backend, frontend, and QA leads.
|