feat: Affiliate program enrichment (Link Builder, Curated Collections, Smart Links)

AFFILIATE_PROGRAM_ENRICHMENT_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,52 @@
+# 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.