WooNooW/.agent/plans/affiliate-module.md

# Affiliate Module Plan

## Overview
Referral tracking with hybrid customer/affiliate roles, integrated as a core plugin module.

---

## Module Architecture

### Core Features
- **Affiliate registration**: Customers can become affiliates
- **Approval workflow**: Manual or auto-approval of affiliates
- **Unique referral links/codes**: Each affiliate gets unique tracking
- **Commission tracking**: Track referrals and calculate earnings
- **Tiered commission rates**: Different rates per product/category/affiliate level
- **Payout management**: Track and process affiliate payouts
- **Affiliate dashboard**: Self-service stats and link generator

### Hybrid Roles
- A customer can also be an affiliate
- No separate user type; affiliate data linked to existing user
- Affiliates can still make purchases (self-referral rules configurable)

---

## Database Schema

### Table: `woonoow_affiliates`
```sql
CREATE TABLE woonoow_affiliates (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT UNSIGNED NOT NULL UNIQUE,
  status ENUM('pending', 'active', 'rejected', 'suspended') DEFAULT 'pending',
  referral_code VARCHAR(50) NOT NULL UNIQUE,
  commission_rate DECIMAL(5,2) DEFAULT NULL,  -- Override global rate
  tier_id BIGINT UNSIGNED DEFAULT NULL,
  payment_email VARCHAR(255) DEFAULT NULL,
  payment_method VARCHAR(50) DEFAULT NULL,
  total_earnings DECIMAL(15,2) DEFAULT 0,
  total_unpaid DECIMAL(15,2) DEFAULT 0,
  total_paid DECIMAL(15,2) DEFAULT 0,
  referral_count INT UNSIGNED DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_user_id (user_id),
  INDEX idx_status (status),
  INDEX idx_referral_code (referral_code)
);
```

### Table: `woonoow_referrals`
```sql
CREATE TABLE woonoow_referrals (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  affiliate_id BIGINT UNSIGNED NOT NULL,
  order_id BIGINT UNSIGNED NOT NULL,
  customer_id BIGINT UNSIGNED DEFAULT NULL,
  subtotal DECIMAL(15,2) NOT NULL,
  commission_rate DECIMAL(5,2) NOT NULL,
  commission_amount DECIMAL(15,2) NOT NULL,
  status ENUM('pending', 'approved', 'rejected', 'paid') DEFAULT 'pending',
  referral_type ENUM('link', 'code', 'coupon') DEFAULT 'link',
  ip_address VARCHAR(45) DEFAULT NULL,
  user_agent TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  approved_at DATETIME DEFAULT NULL,
  paid_at DATETIME DEFAULT NULL,
  INDEX idx_affiliate (affiliate_id),
  INDEX idx_order (order_id),
  INDEX idx_status (status)
);
```

### Table: `woonoow_payouts`
```sql
CREATE TABLE woonoow_payouts (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  affiliate_id BIGINT UNSIGNED NOT NULL,
  amount DECIMAL(15,2) NOT NULL,
  method VARCHAR(50) DEFAULT NULL,
  reference VARCHAR(255) DEFAULT NULL,  -- Bank ref, PayPal transaction, etc.
  status ENUM('pending', 'processing', 'completed', 'failed') DEFAULT 'pending',
  notes TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  completed_at DATETIME DEFAULT NULL,
  INDEX idx_affiliate (affiliate_id),
  INDEX idx_status (status)
);
```

### Table: `woonoow_affiliate_tiers` (Optional)
```sql
CREATE TABLE woonoow_affiliate_tiers (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  commission_rate DECIMAL(5,2) NOT NULL,
  min_referrals INT UNSIGNED DEFAULT 0,  -- Auto-promote at X referrals
  min_earnings DECIMAL(15,2) DEFAULT 0,   -- Auto-promote at X earnings
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

---

## Backend Structure

```
includes/Modules/Affiliate/
├── AffiliateModule.php      # Bootstrap, hooks, tracking
├── AffiliateManager.php     # Core logic
├── ReferralTracker.php      # Track referral cookies/links
└── AffiliateSettings.php    # Settings schema

includes/Api/AffiliatesController.php  # REST endpoints
```

### AffiliateManager Methods
```php
- register($user_id)              # Register user as affiliate
- approve($affiliate_id)          # Approve pending affiliate
- reject($affiliate_id, $reason)  # Reject application
- suspend($affiliate_id)          # Suspend affiliate
- track_referral($order, $affiliate) # Create referral record
- calculate_commission($order, $affiliate) # Calculate earnings
- approve_referral($referral_id)  # Approve pending referral
- create_payout($affiliate_id, $amount) # Create payout request
- process_payout($payout_id)      # Mark payout complete
- get_affiliate_stats($affiliate_id) # Dashboard stats
```

### Referral Tracking
1. Affiliate shares link: `yourstore.com/?ref=CODE`
2. ReferralTracker sets cookie: `wnw_ref=CODE` (30 days default)
3. On checkout, check cookie and link to affiliate
4. On order completion, create referral record

---

## REST API Endpoints

### Admin Endpoints
```
GET    /affiliates                 # List affiliates
GET    /affiliates/{id}            # Affiliate details
PUT    /affiliates/{id}            # Update affiliate
POST   /affiliates/{id}/approve    # Approve affiliate
POST   /affiliates/{id}/reject     # Reject affiliate
GET    /affiliates/referrals       # All referrals
GET    /affiliates/payouts         # All payouts
POST   /affiliates/payouts/{id}/complete # Complete payout
```

### Customer/Affiliate Endpoints
```
GET    /my-affiliate               # Check if affiliate
POST   /my-affiliate/register      # Register as affiliate
GET    /my-affiliate/stats         # Dashboard stats
GET    /my-affiliate/referrals     # My referrals
GET    /my-affiliate/payouts       # My payouts
POST   /my-affiliate/payout-request # Request payout
GET    /my-affiliate/links         # Generate referral links
```

---

## Admin SPA

### Affiliates List (`/marketing/affiliates`)
- Table: Name, Email, Status, Referrals, Earnings, Actions
- Filters: Status, Date range
- Actions: Approve, Reject, View

### Affiliate Detail (`/marketing/affiliates/:id`)
- Affiliate info card
- Stats summary
- Referrals list
- Payouts history
- Action buttons

### Referrals List (`/marketing/affiliates/referrals`)
- All referrals across affiliates
- Filters: Status, Affiliate, Date

### Payouts (`/marketing/affiliates/payouts`)
- Payout requests
- Process payouts
- Payment history

---

## Customer SPA

### Become an Affiliate (`/my-account/affiliate`)
- Registration form (if not affiliate)
- Dashboard (if affiliate)

### Affiliate Dashboard
- Stats: Total Referrals, Pending, Approved, Earnings
- Referral link generator
- Recent referrals
- Payout request button

### My Referrals
- List of referrals with status
- Commission amount

### My Payouts
- Payout history
- Pending amount
- Request payout form

---

## Settings Schema

```php
return [
  'enabled' => true,
  'registration_type' => 'open',  // open, approval, invite
  'auto_approve' => false,
  'default_commission_rate' => 10,  // 10%
  'commission_type' => 'percentage',  // percentage, flat
  'cookie_duration' => 30,  // days
  'min_payout_amount' => 50,
  'payout_methods' => ['bank_transfer', 'paypal'],
  'allow_self_referral' => false,
  'referral_approval' => 'auto',  // auto, manual
  'approval_delay_days' => 14,  // Wait X days before auto-approve
];
```

---

## Implementation Priority
1. Database tables and AffiliateManager
2. ReferralTracker (cookie-based tracking)
3. Order hook to create referrals
4. Admin SPA affiliates management
5. Customer SPA affiliate dashboard
6. Payout management
7. Tier system (optional)