1
This commit is contained in:
486
v2/V2-Execution-Docs/04A-managed-services.md
Normal file
486
v2/V2-Execution-Docs/04A-managed-services.md
Normal file
@@ -0,0 +1,486 @@
|
||||
# IGNY8 Phase 4: Managed Services (04A)
|
||||
## Service Tiers, Backlink Orders, Ahrefs Integration, Backlink Indexing
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Date:** 2026-03-23
|
||||
**Phase:** IGNY8 Phase 4 — Business Layer
|
||||
**Status:** Build Ready
|
||||
**Source of Truth:** Codebase at `/data/app/igny8/`
|
||||
**Audience:** Claude Code, Backend Developers, Business Operations, Architects
|
||||
|
||||
---
|
||||
|
||||
## 1. CURRENT STATE
|
||||
|
||||
### Billing Infrastructure Exists
|
||||
The billing app provides:
|
||||
- `Plan` — subscription tier definition (Free/$49/$149/$349)
|
||||
- `Subscription` — active subscription per account, links to Plan
|
||||
- `CreditTransaction` — credit debit/credit events
|
||||
- `CreditUsageLog` — per-operation usage tracking
|
||||
- `CreditCostConfig` — configurable cost per operation type (PK = operation_type)
|
||||
- `AccountPaymentMethod` — saved Stripe/PayPal payment methods
|
||||
- `Payment` + `Invoice` — payment and invoice records
|
||||
- `CreditService` in `business/billing/` — pattern: `check_credits()` → execute → `deduct_credits()` → `log_usage()`
|
||||
- Stripe + PayPal live and integrated
|
||||
|
||||
### Current Plans
|
||||
|
||||
| Plan | Price | Sites | Users | Credits/Mo |
|
||||
|------|-------|-------|-------|------------|
|
||||
| Free | $0 | 1 | 1 | 100 |
|
||||
| Starter | $49 | 3 | 3 | 1,000 |
|
||||
| Growth | $149 | 10 | 10 | 5,000 |
|
||||
| Scale | $349 | Unlimited | Unlimited | 25,000 |
|
||||
|
||||
### What Does NOT Exist
|
||||
- No managed services layer — Alorig manages client sites manually
|
||||
- No backlink order tracking — orders placed manually on FatGrid/PRNews
|
||||
- No Ahrefs integration — domain/backlink data checked manually
|
||||
- No backlink indexing service — links indexed organically or manually submitted
|
||||
- No automated onboarding — each client setup is manual
|
||||
- 6 existing Alorig clients ready for managed service conversion
|
||||
|
||||
### Phase 2 Models Available
|
||||
- `SAGCampaign`, `SAGBacklink`, `CampaignKPISnapshot` (02E) — backlink campaign engine
|
||||
- `GSCConnection`, `URLInspectionRecord`, `GSCMetricsCache` (02C) — GSC data
|
||||
- `SAGLink`, `SAGLinkAudit`, `LinkMap` (02D) — internal linking
|
||||
- `SocialPost`, `SocialAccount`, `SocialEngagement` (02H) — socializer
|
||||
- `SchemaTemplate`, `SERPEnhancement`, `SchemaValidationResult` (02G) — schema
|
||||
- `AutomationConfig`, `AutomationRun` (automation app) — pipeline orchestration
|
||||
- All IDs are integers (BigAutoField)
|
||||
|
||||
---
|
||||
|
||||
## 2. WHAT TO BUILD
|
||||
|
||||
### Overview
|
||||
A managed services layer that lets Alorig sell done-for-you SEO services at two tiers, with integrated backlink ordering, Ahrefs API monitoring, and backlink indexing. Everything builds on existing IGNY8 models and infrastructure.
|
||||
|
||||
### Managed Service Tiers
|
||||
|
||||
**Managed Lite ($100/site/month):**
|
||||
- 10 articles/month (published to WordPress via pipeline)
|
||||
- Basic SAG setup + automation configuration (first month)
|
||||
- Monthly PDF report
|
||||
- Email support (48-hour response)
|
||||
- Automation config: weekly schedule, 3 articles/run, post + cluster_hub types
|
||||
- Review required before publish (Alorig team reviews in Writer)
|
||||
|
||||
**Managed Pro ($399/site/month):**
|
||||
- 30 articles/month (hubs prioritized early, supporting content later)
|
||||
- Full SAG architecture with detailed mode
|
||||
- Backlink campaign management (budget separate — pass-through + 20% markup)
|
||||
- Social media content generation + scheduling (configured platforms)
|
||||
- Retroactive schema enhancement on existing pages
|
||||
- GSC monitoring: auto-indexing, re-inspection, issue alerts
|
||||
- Weekly PDF report with full KPIs
|
||||
- Dedicated account manager (24-hour response)
|
||||
- Taxonomy term content generation
|
||||
|
||||
### Backlink Service Packages
|
||||
|
||||
**By Quality Level:**
|
||||
| Tier | Service | Alorig Cost | Client Price | Margin |
|
||||
|------|---------|-------------|-------------|--------|
|
||||
| Basic Guest Post | DR 30-50 via FatGrid | $30-80 | $150-300 | 3-5× |
|
||||
| Standard Guest Post | DR 50-70 via FatGrid | $100-300 | $400-800 | 2-3× |
|
||||
| Premium Guest Post | DR 70+ via FatGrid | $500-2,000 | $1,500-5,000 | 2-3× |
|
||||
| PR Basic | 300+ outlets (EIN Presswire) | $99-499 | $500-1,500 | 3-5× |
|
||||
| PR Premium | Yahoo/Bloomberg/Fox | $500-5,000 | $2,000-15,000 | 3-4× |
|
||||
|
||||
**Monthly Retainer Packages:**
|
||||
| Package | Links/Mo | DR Range | Monthly Cost | Market |
|
||||
|---------|----------|----------|-------------|--------|
|
||||
| Starter | 5-8 | DR 30-50 | $800-1,500 | PK |
|
||||
| Growth | 10-15 | DR 30-70 mix | $2,000-4,000 | UK/CA |
|
||||
| Authority | 15-25 | DR 40-70+ mix + PR | $4,000-8,000 | USA |
|
||||
| Enterprise | Custom | Custom | Custom | Multi-site/agency |
|
||||
|
||||
**Niche Surcharges:** Crypto/Casino 2-3×, Finance/Insurance 1.5-2×, Health/Medical 1.5-2×, Tech/SaaS 1.2-1.5×, General 1× baseline.
|
||||
|
||||
### Ahrefs API Integration
|
||||
|
||||
IGNY8 integrates with Ahrefs API v3 for automated domain metrics and backlink monitoring.
|
||||
|
||||
**API Endpoints Used:**
|
||||
| Ahrefs Endpoint | IGNY8 Use Case |
|
||||
|-----------------|----------------|
|
||||
| `GET /v3/site-explorer/domain-rating` | DR for any domain (backlink quality scoring) |
|
||||
| `GET /v3/site-explorer/backlinks` | Verify placed backlinks are live |
|
||||
| `GET /v3/site-explorer/referring-domains` | Referring domain list + metrics |
|
||||
| `GET /v3/site-explorer/organic-keywords` | Keyword rankings (supplement GSC data) |
|
||||
| `GET /v3/site-explorer/pages-by-traffic` | Top pages by organic traffic |
|
||||
| `GET /v3/site-explorer/metrics` | Domain summary (DR, referring domains, traffic, keywords) |
|
||||
| `GET /v3/site-explorer/metrics-history` | Historical DR + traffic trend |
|
||||
| `GET /v3/site-explorer/refdomains-history` | Referring domains over time |
|
||||
|
||||
**Use Cases:**
|
||||
1. **Backlink verification** — after SAGBacklink placed, verify via Ahrefs crawl data
|
||||
2. **Quality scoring** — auto-populate `source_dr`, `source_traffic` on SAGBacklink
|
||||
3. **Campaign KPIs** — pull DR, referring domains, keywords for CampaignKPISnapshot
|
||||
4. **Competitor analysis** — compare client's metrics against competitors
|
||||
5. **Dead link detection** — cross-reference lost backlinks with SAGBacklink records
|
||||
6. **Reporting** — feed ServiceReport data (04B)
|
||||
7. **Link prospecting** — find competitor backlinks for outreach
|
||||
|
||||
**Pricing:** Credits-based (varies by Ahrefs plan). API key stored per account in `AhrefsConnection`.
|
||||
|
||||
### Backlink Indexing Service
|
||||
|
||||
After a backlink is placed and verified live, submit it for Google indexing to accelerate authority transfer.
|
||||
|
||||
**Indexing Services (integrate best available):**
|
||||
- IndexNow API (free) — Bing/Yandex submission
|
||||
- SpeedyIndex — fast indexing, API available, credit-based
|
||||
- Omega Indexer — bulk indexing, ~$0.02-0.05/URL
|
||||
|
||||
**Integration Flow:**
|
||||
```
|
||||
SAGBacklink.status → 'live'
|
||||
→ Verify URL accessible (HTTP 200)
|
||||
→ Queue BacklinkIndexingRequest (status: queued)
|
||||
→ Submit via indexing service API (status: submitted)
|
||||
→ Wait 7 days, check if indexed
|
||||
→ If indexed → is_indexed = True, status → indexed
|
||||
→ If not after 14 days → re-submit once (status: resubmitted)
|
||||
→ If still not after 28 days → status → failed, flag for review
|
||||
```
|
||||
|
||||
**Client Pricing:** $0.10-0.20 per URL (5-10× markup); included in Managed Pro tier.
|
||||
|
||||
### Client Onboarding Automation
|
||||
|
||||
When `ManagedServiceSubscription` is created:
|
||||
1. Verify site has IGNY8 plugin installed + connected (`SiteIntegration` exists)
|
||||
2. If no blueprint → queue Celery task to auto-generate SAG blueprint
|
||||
3. Configure `AutomationConfig` based on `service_config` (schedule, stages, content types)
|
||||
4. Send welcome email (expectations, content approval process, contact info)
|
||||
5. Create first month's content tasks in pipeline queue
|
||||
6. Notify account manager: "New client onboarded, first content due"
|
||||
7. Update subscription status: pending → active
|
||||
|
||||
**Monthly Delivery Workflow (Lite):**
|
||||
```
|
||||
Month Start → Verify blueprint → Run pipeline (10 articles) →
|
||||
Alorig reviews → Approve/edit → Publish to WP →
|
||||
Update articles_published counter → Month End → Generate report → Send → Bill
|
||||
```
|
||||
|
||||
**Monthly Delivery Workflow (Pro — extends Lite):**
|
||||
```
|
||||
+ Run pipeline for 30 articles (hubs prioritized)
|
||||
+ Taxonomy term content generation
|
||||
+ Backlink: Load SAGCampaign plan → Browse FatGrid → Place orders →
|
||||
Track delivery → Quality check → Log SAGBacklink → Submit for indexing
|
||||
+ Social: Generate adapted posts → Schedule via best-time algorithm
|
||||
+ Schema: Retroactive scan → Push to WP
|
||||
+ GSC: Check indexing → Re-request pending → Flag issues
|
||||
+ Weekly: Generate report → Send
|
||||
```
|
||||
|
||||
### Margin Analysis
|
||||
|
||||
| Component | Managed Lite | Managed Pro |
|
||||
|-----------|-------------|-------------|
|
||||
| Service Fee | $100/month | $399/month |
|
||||
| Platform Cost (credits) | ~$15-25 | ~$50-80 |
|
||||
| Human Time | ~2-3 hrs/month | ~8-12 hrs/month |
|
||||
| Ahrefs API cost | ~$2-5 | ~$10-20 |
|
||||
| Indexing service cost | $0 | ~$5-15 |
|
||||
| **Gross Margin** | **~70-75%** | **~65-75%** |
|
||||
|
||||
Backlink purchase costs are pass-through with 20% markup — separate from service fee.
|
||||
|
||||
---
|
||||
|
||||
## 3. DATA MODELS & APIS
|
||||
|
||||
### New App: `services`
|
||||
|
||||
**App Label:** `services`
|
||||
**Location:** `igny8_core/services/`
|
||||
**Table Prefix:** `igny8_`
|
||||
|
||||
### New Models
|
||||
|
||||
**`ManagedServiceSubscription`** (extends `AccountBaseModel`)
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `site` | ForeignKey(Site) | Which site is being managed |
|
||||
| `tier` | CharField(max_length=20) | `lite` / `pro` |
|
||||
| `status` | CharField(max_length=20) | `pending` / `active` / `paused` / `cancelled` |
|
||||
| `monthly_price` | DecimalField(8,2) | Monthly fee |
|
||||
| `articles_per_month` | IntegerField | Target articles per month |
|
||||
| `account_manager` | ForeignKey(User, null=True) | Assigned team member |
|
||||
| `current_month_articles_published` | IntegerField(default=0) | Counter |
|
||||
| `current_month_start` | DateField(null=True) | Current billing period start |
|
||||
| `service_config` | JSONField | Per-site settings (automation, social, backlinks, reporting) |
|
||||
| `started_at` | DateTimeField(null=True) | Service start timestamp |
|
||||
| `cancelled_at` | DateTimeField(null=True) | Cancellation timestamp |
|
||||
| `next_billing_date` | DateField(null=True) | Next billing date |
|
||||
|
||||
Table: `igny8_managed_service_subscriptions`
|
||||
|
||||
**`BacklinkServiceOrder`** (extends `AccountBaseModel`)
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `site` | ForeignKey(Site) | Target site |
|
||||
| `campaign` | ForeignKey(SAGCampaign, null=True) | Linked campaign from 02E |
|
||||
| `managed_subscription` | ForeignKey(ManagedServiceSubscription, null=True) | If part of managed service |
|
||||
| `order_type` | CharField(max_length=20) | `one_time` / `monthly` |
|
||||
| `package` | CharField(max_length=50) | `starter` / `growth` / `authority` / `enterprise` / `custom` |
|
||||
| `client_price` | DecimalField(10,2) | Price charged to client |
|
||||
| `actual_cost` | DecimalField(10,2, default=0) | Actual cost to Alorig |
|
||||
| `margin` | DecimalField(10,2, default=0) | Calculated margin |
|
||||
| `niche_surcharge` | FloatField(default=1.0) | Niche multiplier |
|
||||
| `links_ordered` | IntegerField(default=0) | Total links ordered |
|
||||
| `links_delivered` | IntegerField(default=0) | Links delivered by vendor |
|
||||
| `links_live` | IntegerField(default=0) | Confirmed live |
|
||||
| `links_indexed` | IntegerField(default=0) | Confirmed indexed |
|
||||
| `status` | CharField(max_length=20) | `draft` / `approved` / `in_progress` / `delivered` / `completed` |
|
||||
| `ordered_at` | DateTimeField(null=True) | Order placement date |
|
||||
| `delivered_at` | DateTimeField(null=True) | Full delivery date |
|
||||
| `notes` | TextField(blank=True) | Internal notes |
|
||||
|
||||
Table: `igny8_backlink_service_orders`
|
||||
|
||||
**`AhrefsConnection`** (extends `AccountBaseModel`)
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `api_key` | TextField | Encrypted Ahrefs API key |
|
||||
| `plan_type` | CharField(null=True) | `lite` / `standard` / `advanced` / `enterprise` |
|
||||
| `credits_remaining` | IntegerField(null=True) | Remaining API credits |
|
||||
| `last_synced` | DateTimeField(null=True) | Last sync timestamp |
|
||||
| `status` | CharField(max_length=20) | `active` / `expired` / `error` |
|
||||
|
||||
Table: `igny8_ahrefs_connections`
|
||||
|
||||
**`AhrefsDomainSnapshot`** (extends `SiteSectorBaseModel`)
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `domain` | CharField(max_length=255) | Domain name |
|
||||
| `domain_rating` | FloatField | DR score |
|
||||
| `referring_domains` | IntegerField | Count |
|
||||
| `organic_keywords` | IntegerField | Count |
|
||||
| `organic_traffic` | IntegerField | Estimated monthly |
|
||||
| `backlinks_total` | IntegerField | Total backlinks |
|
||||
| `snapshot_date` | DateField | Date of snapshot |
|
||||
| `raw_data` | JSONField | Full API response |
|
||||
|
||||
Table: `igny8_ahrefs_domain_snapshots`
|
||||
|
||||
**`BacklinkIndexingRequest`** (extends `SiteSectorBaseModel`)
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `backlink` | ForeignKey(SAGBacklink) | Linked backlink from 02E |
|
||||
| `url` | URLField | Source URL to be indexed |
|
||||
| `indexing_service` | CharField(max_length=30) | `speedyindex` / `omega` / `colossus` / `indexnow` / `manual` |
|
||||
| `service_request_id` | CharField(null=True) | External service reference |
|
||||
| `submitted_at` | DateTimeField(null=True) | Submission timestamp |
|
||||
| `first_check_at` | DateTimeField(null=True) | First index check |
|
||||
| `last_check_at` | DateTimeField(null=True) | Last index check |
|
||||
| `check_count` | IntegerField(default=0) | Times checked |
|
||||
| `is_indexed` | BooleanField(default=False) | Is indexed |
|
||||
| `indexed_at` | DateTimeField(null=True) | When indexed |
|
||||
| `status` | CharField(max_length=20) | `queued` / `submitted` / `checking` / `indexed` / `failed` / `resubmitted` |
|
||||
| `cost` | DecimalField(6,4, default=0) | Cost per submission |
|
||||
|
||||
Table: `igny8_backlink_indexing_requests`
|
||||
|
||||
### Modified Models
|
||||
|
||||
**`SAGBacklink`** (from 02E linker app) — add fields:
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `is_indexed` | BooleanField(default=False) | Indexed in Google |
|
||||
| `indexed_at` | DateTimeField(null=True) | When indexed |
|
||||
| `ahrefs_verified` | BooleanField(default=False) | Verified via Ahrefs |
|
||||
| `ahrefs_last_seen` | DateTimeField(null=True) | Last seen in Ahrefs |
|
||||
| `indexing_submitted` | BooleanField(default=False) | Submitted for indexing |
|
||||
|
||||
### API Endpoints
|
||||
|
||||
All under `/api/v1/`:
|
||||
|
||||
**Managed Service Subscriptions:**
|
||||
| Method | Endpoint | Purpose |
|
||||
|--------|----------|---------|
|
||||
| GET | `/services/subscriptions/` | List all (admin only) |
|
||||
| POST | `/services/subscriptions/` | Create subscription |
|
||||
| GET | `/services/subscriptions/{id}/` | Detail |
|
||||
| PATCH | `/services/subscriptions/{id}/` | Update config/status |
|
||||
| POST | `/services/subscriptions/{id}/onboard/` | Trigger onboarding flow |
|
||||
| POST | `/services/subscriptions/{id}/pause/` | Pause service |
|
||||
| POST | `/services/subscriptions/{id}/resume/` | Resume service |
|
||||
| POST | `/services/subscriptions/{id}/cancel/` | Cancel service |
|
||||
|
||||
**Backlink Service Orders:**
|
||||
| Method | Endpoint | Purpose |
|
||||
|--------|----------|---------|
|
||||
| GET | `/services/backlink-orders/` | List all (admin) |
|
||||
| POST | `/services/backlink-orders/` | Create order |
|
||||
| GET | `/services/backlink-orders/{id}/` | Detail |
|
||||
| PATCH | `/services/backlink-orders/{id}/` | Update status |
|
||||
| GET | `/services/backlink-orders/{id}/links/` | Links in order |
|
||||
| POST | `/services/backlink-orders/{id}/approve/` | Client approval |
|
||||
|
||||
**Ahrefs Integration:**
|
||||
| Method | Endpoint | Purpose |
|
||||
|--------|----------|---------|
|
||||
| POST | `/integration/ahrefs/connect/` | Save API key |
|
||||
| DELETE | `/integration/ahrefs/disconnect/` | Remove connection |
|
||||
| GET | `/integration/ahrefs/status/` | Connection status + credits |
|
||||
| GET | `/integration/ahrefs/domain/{domain}/` | Domain metrics |
|
||||
| GET | `/integration/ahrefs/domain/{domain}/history/` | DR + traffic history |
|
||||
| GET | `/integration/ahrefs/backlinks/{domain}/` | Backlinks list |
|
||||
| GET | `/integration/ahrefs/referring-domains/{domain}/` | Referring domains |
|
||||
| GET | `/integration/ahrefs/organic-keywords/{domain}/` | Organic keywords |
|
||||
| POST | `/integration/ahrefs/verify-backlinks/` | Bulk verify SAGBacklinks |
|
||||
| POST | `/integration/ahrefs/snapshot/` | Take domain snapshot |
|
||||
|
||||
**Backlink Indexing:**
|
||||
| Method | Endpoint | Purpose |
|
||||
|--------|----------|---------|
|
||||
| POST | `/linker/indexing/submit/` | Submit URLs for indexing |
|
||||
| POST | `/linker/indexing/bulk-submit/` | Bulk submit all live unindexed |
|
||||
| GET | `/linker/indexing/requests/` | List requests (filter by site_id) |
|
||||
| GET | `/linker/indexing/requests/{id}/` | Single request status |
|
||||
| GET | `/linker/indexing/stats/` | Success rate, pending count |
|
||||
|
||||
**Admin Dashboard:**
|
||||
| Method | Endpoint | Purpose |
|
||||
|--------|----------|---------|
|
||||
| GET | `/services/dashboard/` | Revenue summary, client count, MRR |
|
||||
| GET | `/services/dashboard/overdue/` | Overdue deliverables |
|
||||
| GET | `/services/dashboard/margin/` | Margin tracking across orders |
|
||||
|
||||
### Celery Tasks
|
||||
|
||||
| Task | Schedule | Purpose |
|
||||
|------|----------|---------|
|
||||
| `onboard_managed_client` | On-demand | Full onboarding flow |
|
||||
| `process_managed_billing` | Monthly (1st) | Invoice all active subscriptions |
|
||||
| `reset_monthly_counters` | Monthly (1st) | Reset articles_published counters |
|
||||
| `check_delivery_status` | Daily | Flag subscriptions behind on deliverables |
|
||||
| `sync_ahrefs_domain_snapshot` | Weekly | Pull DR/traffic/referring domains per connected site |
|
||||
| `verify_backlinks_via_ahrefs` | Weekly | Cross-reference SAGBacklinks with Ahrefs data |
|
||||
| `submit_backlinks_for_indexing` | Daily | Submit live unindexed backlinks |
|
||||
| `check_indexing_status` | Daily | Check submitted URLs (after 7-day wait) |
|
||||
| `detect_lost_backlinks_ahrefs` | Weekly | Compare Ahrefs lost links with SAGBacklink records |
|
||||
|
||||
### Services
|
||||
|
||||
| Service | Purpose |
|
||||
|---------|---------|
|
||||
| `ManagedBillingService` | Subscription CRUD, billing, margin calculation |
|
||||
| `AhrefsService` | API client wrapper, rate limiting, credit tracking |
|
||||
| `BacklinkIndexingService` | Submit to indexing service, track status, retry logic |
|
||||
|
||||
---
|
||||
|
||||
## 4. IMPLEMENTATION STEPS
|
||||
|
||||
### Build Sequence
|
||||
|
||||
**Week 1: Foundation**
|
||||
1. Create `services` app under `igny8_core/services/`
|
||||
2. Create `ManagedServiceSubscription` model + migration
|
||||
3. Create `BacklinkServiceOrder` model + migration
|
||||
4. Create serializers + viewsets for both
|
||||
5. Build `ManagedBillingService` — subscription CRUD, billing integration
|
||||
6. Build onboarding Celery task
|
||||
|
||||
**Week 2: Ahrefs + Indexing**
|
||||
1. Create `AhrefsConnection` + `AhrefsDomainSnapshot` models + migration
|
||||
2. Build `AhrefsService` — API client with rate limiting and credit tracking
|
||||
3. Create `BacklinkIndexingRequest` model + migration
|
||||
4. Build `BacklinkIndexingService` — multi-provider submission
|
||||
5. Add 5 new fields to `SAGBacklink` model + migration
|
||||
6. Wire up all Celery tasks
|
||||
|
||||
**Week 3: API + Dashboard**
|
||||
1. Register all API endpoints
|
||||
2. Build admin dashboard endpoints (revenue, overdue, margin)
|
||||
3. Build onboarding flow end-to-end
|
||||
4. Test full managed service lifecycle
|
||||
|
||||
---
|
||||
|
||||
## 5. ACCEPTANCE CRITERIA
|
||||
|
||||
### Managed Services
|
||||
- [ ] `ManagedServiceSubscription` creates for Lite and Pro tiers
|
||||
- [ ] Onboarding flow: verify plugin → generate blueprint → configure automation → welcome email
|
||||
- [ ] Monthly billing generates invoices via existing Stripe/PayPal integration
|
||||
- [ ] `articles_published` counter tracks against `articles_per_month` target
|
||||
- [ ] Pause/resume/cancel flows work without data loss
|
||||
- [ ] Service config JSON stores per-site automation, social, backlink settings
|
||||
|
||||
### Backlink Orders
|
||||
- [ ] `BacklinkServiceOrder` tracks full lifecycle: draft → approved → in_progress → delivered → completed
|
||||
- [ ] Links tracker: ordered vs delivered vs live vs indexed counts accurate
|
||||
- [ ] Margin calculated correctly with niche surcharges
|
||||
- [ ] Orders linkable to SAGCampaign (02E)
|
||||
|
||||
### Ahrefs Integration
|
||||
- [ ] API key stored encrypted, connection test validates key
|
||||
- [ ] Domain metrics endpoint returns DR, referring domains, traffic, keywords
|
||||
- [ ] Weekly snapshots auto-populate `AhrefsDomainSnapshot`
|
||||
- [ ] Backlink verification cross-references SAGBacklink records
|
||||
- [ ] Lost backlink detection flags dead links
|
||||
- [ ] Credits consumption tracked
|
||||
|
||||
### Backlink Indexing
|
||||
- [ ] `BacklinkIndexingRequest` tracks full lifecycle: queued → submitted → checking → indexed/failed
|
||||
- [ ] Submissions go to configured indexing service API
|
||||
- [ ] 7-day wait before first check, re-submit at 14 days, fail at 28 days
|
||||
- [ ] Cost tracking per submission
|
||||
- [ ] `SAGBacklink.is_indexed` updated when confirmed
|
||||
|
||||
### Admin Dashboard
|
||||
- [ ] Revenue summary shows total MRR, client count by tier
|
||||
- [ ] Overdue endpoint flags behind-schedule content/links
|
||||
- [ ] Margin tracking shows per-order and aggregate margins
|
||||
|
||||
---
|
||||
|
||||
## 6. CLAUDE CODE INSTRUCTIONS
|
||||
|
||||
### Context Requirements
|
||||
1. Read 02E (Linker External) — SAGCampaign, SAGBacklink, CampaignKPISnapshot models
|
||||
2. Read existing billing app models — Plan, Subscription, CreditService
|
||||
3. Read 03B (WP Plugin Connected) — content delivery flow that managed services triggers
|
||||
4. Read automation app — AutomationConfig, AutomationRun for pipeline configuration
|
||||
|
||||
### Execution Order
|
||||
```
|
||||
services app skeleton → models + migrations → ManagedBillingService → AhrefsService →
|
||||
BacklinkIndexingService → API endpoints → Celery tasks → admin dashboard
|
||||
```
|
||||
|
||||
### Critical Rules
|
||||
1. **All IDs are integers** — BigAutoField PKs, integer FKs
|
||||
2. **Model names PLURAL** — Clusters, Keywords, Tasks, etc.
|
||||
3. **Table prefix** — `igny8_` for all tables
|
||||
4. **App label** — `services` for new app
|
||||
5. **Celery app** — `igny8_core` (same as all other tasks)
|
||||
6. **API pattern** — `/api/v1/services/` for managed service endpoints, `/api/v1/integration/ahrefs/` for Ahrefs, `/api/v1/linker/indexing/` for indexing
|
||||
7. **AccountBaseModel** for account-scoped models, **SiteSectorBaseModel** for site-scoped
|
||||
8. **Encrypt API keys** — Ahrefs API key encrypted at rest
|
||||
9. **Rate limiting** — respect Ahrefs API rate limits, exponential backoff on 429
|
||||
10. **No blocking** — all external API calls in Celery tasks, never in request/response cycle
|
||||
|
||||
### Cross-References
|
||||
|
||||
| Doc | Relationship |
|
||||
|-----|-------------|
|
||||
| 02E Linker External | SAGCampaign, SAGBacklink models — backlink orders link to these |
|
||||
| 02C GSC Integration | GSCMetricsCache — monitoring data for Pro tier, indexing status |
|
||||
| 02D Linker Internal | SAGLink, LinkMap — internal linking health for service delivery |
|
||||
| 02H Socializer | SocialPost, SocialAccount — social content for Pro tier |
|
||||
| 02G Rich Schema SERP | SchemaTemplate — retroactive schema enhancement for Pro tier |
|
||||
| 01A SAG Data Foundation | SAGBlueprint — auto-generated during onboarding |
|
||||
| 03B WP Plugin Connected | Content delivery to WordPress via sync endpoints |
|
||||
| 04B Whitelabel Reporting | Reports consume subscription + order data from this doc |
|
||||
| 04C Pricing Launch | Feature gates control who can purchase managed services |
|
||||
Reference in New Issue
Block a user