# Partner Nook — Gap Analysis (PRD vs Implementation vs GoAffPro)

**No new code yet.** This is the full audit before implementation. Compares the
client PRD (§4.1–4.10), the current build, and GoAffPro's product logic — with a
deep dive on the **Affiliate Dashboard** (the main gap).

---

## A. How GoAffPro is architected (the "why" behind each module)

GoAffPro is two products glued by a tracking engine:

1. **Merchant admin** — set up the program (commissions, coupons, groups, rewards),
   manage partners (affiliates, sales, payouts), grow (recruit, marketing), and
   configure (settings). *Purpose: the brand runs the whole program here.*
2. **Affiliate portal** — the partner logs in to get their link/coupon, grab
   marketing assets, track performance, and get paid. *Purpose: self-serve so the
   brand doesn't manually handle each partner.*
3. **Tracking engine** — records clicks (referral link + cookie) and coupon
   conversions, attributes each sale, applies the commission rules. *Purpose: the
   hard part — who brought which sale — done automatically.*

**Affiliate portal tabs & their job:**
- **Home** — referral link (editable code) + coupon (customizable name) + share
  icons + a summary table (Referrals/clicks, Orders, Conversion %, Sales, Earnings).
- **Marketing Tools** — generate a trackable link for any product (paste URL or
  pick product), save link collections, and download merchant-uploaded creative
  assets (banners/images/videos).
- **Payments** — total received, pending, last payment date, transaction history,
  payment-method setup, payout request.
- **Settings** — profile, password, notification preferences.
- **Advanced** — Analytics, Transactions (wallet ledger), Network (MLM), Shop
  (affiliate store), Pages, Party Links.

The **money lifecycle** underpinning it: commission is *pending* (hold period) →
*available* → *paid*, with a wallet/transactions ledger as the source of truth.

---

## B. PRD §4 — clause-by-clause status

Legend: ✅ done · 🟡 partial · ❌ missing

### 4.1 Onboarding & Registration
| Feature | Status | Note |
|---|---|---|
| Signup page | ✅ | works; basic fields only |
| Auto / manual approval | ✅ | `autoApprove` + admin approve |
| Welcome email | 🟡 | **logged**, not actually sent (no SMTP) |
| Custom signup fields | ❌ | `SignupFieldDef` table exists; no admin UI, not rendered on signup |

### 4.2 Affiliate Dashboard  ← **biggest gap**
| Feature | Status | Note |
|---|---|---|
| Referral link | 🟡 | shown/copy; not editable (no vanity code by affiliate) |
| Coupon code | 🟡 | shown/copy; affiliate can't customize |
| Performance stats | 🟡 | clicks/sales/earnings/balance; **no conversion %, no time-series analytics** |
| Payout history | ✅ | basic list |
| Payment details (UPI/Bank/PayPal) | ❌ **UI** | backend `POST /affiliates/:id/payment` exists; **no form in portal** |
| Earnings download (CSV/PDF) | ❌ | not built |
| Marketing tools (product links, assets) | ❌ | not built |
| Settings (profile/password/notifications) | ❌ | not built |
| Design quality | 🟡 | **old basic UI** — never got the admin redesign/components |

### 4.3 Admin Dashboard
| Feature | Status |
|---|---|
| Affiliate list · profile · approve/reject · edit · tags & notes · bulk actions · search/filter | ✅ all done |

### 4.4 Tracking & Attribution
| Feature | Status | Note |
|---|---|---|
| Click tracking | 🟡 | demo `/r/:code` only; **no click tracking on the real Shopify store** |
| Coupon tracking | ✅ | demo + real Shopify sync |
| Conversion tracking | ✅ | demo + real sync |
| Cookie duration | 🟡 | setting stored, **not enforced** |
| Conflict resolution (first/last click) | 🟡 | setting stored, **not applied** |
| Refund handling | 🟡 | admin manual refund reverses commission; **real Shopify refunds not auto-synced** |
| Fraud protection | 🟡 | self-referral + same-IP in demo; **not wired into real Shopify sync** |

### 4.5 Commission Management
| Feature | Status | Note |
|---|---|---|
| Flat % · flat amount · per-affiliate · groups · tiered · commission-on-subtotal | ✅ | engine works |
| Signup bonus | ✅ | applied on approval |
| Performance bonus / target | 🟡 | schema + group form exist; **never evaluated or paid out** |

### 4.6 Coupon Management
| Feature | Status | Note |
|---|---|---|
| Auto-generate · discount value · manual assignment | ✅ | + real Shopify discount codes |
| Vanity codes | 🟡 | admin can set; **affiliate can't customize** |
| Auto-apply at checkout (via link) | ❌ | not built |
| Usage limits | 🟡 | stored in DB; **not pushed to the Shopify discount / not enforced** |
| Bulk coupon update | ❌ | no bulk edit (only push-all) |

### 4.7 Sales & Analytics
| Feature | Status |
|---|---|
| All sales · per-affiliate report · program summary · date filter · sales status · leaderboard | ✅ all done |

### 4.8 Payouts
| Feature | Status | Note |
|---|---|---|
| Payout dashboard · min threshold · manual payout · payment request · payout history | ✅ | |
| PayPal payouts | ❌ | not integrated (PRD allows Phase 2) |
| Invoices | ❌ | no invoice generation/download |

### 4.9 Communication & Notifications
| Feature | Status | Note |
|---|---|---|
| Welcome / sale / payout / bulk emails | 🟡 | **logged only** — no real SMTP send; no per-event on/off config; no templates editor |

### 4.10 Branding
| Feature | Status | Note |
|---|---|---|
| Logo & colors · custom T&C (field) | ✅ | |
| Custom domain | 🟡 | field only, not functional hosting |
| Signup page templates | ❌ | not built |
| T&C shown on signup | ❌ | stored, not displayed to affiliate |

### 5. Out of scope (correctly NOT built)
MLM, mobile app, IG post analytics, party plans, marketplace, comp-plan builder,
multi-store, legal e-signing. ✅ matches PRD.

---

## C. THE FIVE LISTS

### 1) ✅ Already completed
- Full **admin CRM**: Overview (KPIs + charts), Affiliates (DataTable, full CRUD,
  bulk approve, detail w/ coupon+commission+tags+payment), Sales (filters, refund),
  Commission Groups (CRUD), Payouts (owed, mark-paid, requests), Leaderboard,
  Marketing (bulk email + log), Fraud (list/resolve), Settings, Branding.
- **Commission engine**: per-affiliate → group → tiered → default; subtotal/total.
- **Coupon system** + auto-generate + discount value + usage-limit fields.
- **Fraud**: self-referral + same-IP (demo path).
- **Real Shopify integration**: connect, push real discount codes, sync real
  orders → attribute → commission (verified end-to-end).
- **Design system**: UI kit, DataTable, Toasts, Modals/Confirm, charts, responsive
  collapsible shell.

### 2) 🟡 Incomplete / partial
- **Affiliate dashboard** — old basic UI; missing payment-details form, earnings
  download, marketing tools, settings, conversion %/analytics.
- **Emails** — logged, not sent (no SMTP).
- **Target/performance bonus** — configurable but never evaluated/paid.
- **Cookie duration & conflict resolution** — stored, not enforced.
- **Coupon usage limits** — stored, not applied to the real Shopify discount.
- **Refund/fraud on real Shopify sync** — only on the demo path.
- **Vanity/custom coupon by affiliate** — admin-only today.

### 3) ❌ Missing from the PRD
- **Custom signup fields** (4.1)
- **Affiliate: payment-details UI, earnings download, marketing tools, settings** (4.2)
- **Auto-apply coupon at checkout** (4.6) · **bulk coupon update** (4.6)
- **PayPal payouts** (4.8) · **invoices** (4.8)
- **Real email sending** (4.9)
- **Signup-page templates** (4.10) · **T&C shown at signup** (4.10)
- **Click tracking on the real store** (4.4) · enforce cookie/conflict (4.4)

### 4) ❌ Missing vs a *complete* affiliate CRM (GoAffPro-level, beyond PRD)
- **Wallet / transactions ledger** (pending vs available vs paid) + **commission hold time**.
- **Affiliate product-link generator** & **saved link collections**.
- **Creative/digital assets library** (merchant uploads → affiliate downloads).
- **Affiliate analytics tab** (time-series, top products).
- **Email template editor + per-event notification config + drip campaigns**.
- **Real-time webhooks** (vs manual "Sync orders").
- **Program managers / roles**, **activity log**, **recruit/marketplace listing**.
- **Product/collection-level commission**, **commission modifiers/rules**, **recurring/connection commission**.
- **Tax (W9/1099), payout scheduler**.
- **Secure affiliate auth** (current portal uses an id-as-token in localStorage).

---

## D. Step-by-step implementation plan (proposed order)

**Phase 1 — Affiliate Dashboard rebuild (the priority).** Tabbed portal on the new
design system:
1. **Portal shell** — top bar + tabs (Home · Marketing · Payments · Settings), reuse UI kit.
2. **Home** — stat cards (clicks, orders, conversion %, sales ₹, earnings), referral
   link (copy + share), coupon, recent sales.
3. **Marketing Tools** — product-link generator (paste URL / pick product → tracked
   link), creative assets list (from a new admin Digital Assets module).
4. **Payments** — balance (available/pending), payout request (min-threshold aware),
   payout history, **payment-method form** (UPI/Bank/PayPal), **earnings CSV download**.
5. **Settings** — edit profile, change password, notification prefs.

**Phase 2 — Close core PRD gaps.**
6. **Wallet/transactions ledger** + commission **hold time** (pending→available).
7. **Custom signup fields** (admin define → render on signup → show in affiliate detail).
8. **Invoices** (generate per payout, downloadable) + **payout method on payout**.
9. **Coupon**: push usage-limits to the Shopify discount; **bulk coupon update**.
10. **Target/performance bonus** evaluation + payout.

**Phase 3 — Real Shopify depth.**
11. **Webhooks** (real-time orders/refunds) replacing manual sync + **refund + fraud** on real orders.
12. **Digital assets** admin module (upload → affiliate Marketing Tools).
13. **Email**: real SMTP (SendGrid/Mailgun) + per-event config + templates.

**Phase 4 — Polish / optional.**
14. Signup-page templates + T&C at signup, secure affiliate auth (JWT), PayPal payouts.

---

*Recommended first: **Phase 1 — rebuild the Affiliate Dashboard** (your stated
priority), since it's the most visible missing piece and the affiliate half of the
product. Approve and I'll start there.*