# Affiliate Link Enrichment - Implementation Plan

This document outlines the phased implementation plan for the Affiliate Link Enrichment feature, based on the `AFFILIATE_PROGRAM_ENRICHMENT.md` brief and the current state of the WooNooW project.

## 1. Current State of the Project

- **Frontend (`customer-spa/src/pages/Account/AffiliateDashboard.tsx`)**: The affiliate dashboard currently only provides a **single, generic storefront link**: `site.com/shop?ref=YOUR_CODE`. This creates the "generic storefront" problem described in the brief. 
- **Backend (`includes/Modules/Affiliate/AffiliateTracker.php`)**: The backend is highly prepared. The tracking logic natively intercepts **any** page visit that has the `?ref=` parameter. Furthermore, it already captures UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `referrer_url`) and stores them in the `woonoow_ref_utm` cookie, which are eventually saved to the `woonoow_referrals` table when an order is completed.

---

## Phase 1: Immediate Opportunities (Low Effort, High Impact)

Because the backend already tracks referrals across the entire site and captures campaign parameters, Phase 1 can be implemented strictly via **Frontend (SPA) changes**, requiring no backend database migrations.

### 1.1 Implement a "Link Generator" UI (Customer SPA)
Add a new "Link Builder" section in the Affiliate Dashboard (`AffiliateDashboard.tsx`) where affiliates can:
- **Single Product Link**: Select a specific product (via a dropdown/search) to generate a link like `/product/slug?ref=CODE`.
- **Category Link**: Select a category to generate a link like `/shop?category=slug&ref=CODE`.
- **Campaign Tracking**: Add custom Campaign tags (`utm_campaign`, `utm_source`, etc.) to the generated links.

### 1.2 Campaign Analytics UI
Since the `woonoow_referrals` table already stores UTM data:
- **Affiliate Dashboard**: Update the UI to show earnings/clicks grouped by `utm_campaign` or `utm_source`.
- **Admin SPA**: Add reports in the admin area to view referral performance by campaign, fulfilling the trackability requirement.

---

## Phase 2: Medium-Term Opportunities (Curated Collections)

To fulfill the "Curated Collection Link" requirement (where an affiliate groups a themed set of relevant products), we need to build a new feature:

### 2.1 Backend Development
- Create a new custom database table or Custom Post Type (e.g., `woonoow_affiliate_collections`) that maps an Affiliate ID to a list of Product IDs, along with a title and description.
- Create REST API endpoints for affiliates to CRUD their collections.

### 2.2 Frontend Development
- **Affiliate Dashboard**: Add a "My Collections" manager where affiliates can pick products, set a title, and generate a specific collection link. 
- **Storefront**: Add a new dynamic route to the customer-spa (e.g., `/shop/collection/:collection_id?ref=CODE`) that fetches and displays only the specific products in that collection.

---

## Phase 3: Advanced Opportunities (Smart Rotation)

To support "Controlled Smart Rotation" (rotating a small pool of products):

### 3.1 Smart Router API Endpoint
- Create a lightweight REST API endpoint (e.g., `/wp-json/woonoow/v1/go/:rotation_id`).
- When a visitor clicks this link, the backend briefly evaluates the rotation rules, applies the `?ref=` and UTM cookies server-side, and does a 302 redirect to the chosen product page.

### 3.2 UI/UX
- Add configuration settings in the Affiliate Dashboard to set up these rule-based or random rotation links.