## Tower Paints & Chems — End‑to‑End Testing Guide

This document lists **hands‑on test steps** for the key flows in the system, for both **Admin** and **Partner**:

- Benefits (tier & profile)
- Goods Allocation (onboarding dispatch)
- Remittances (money sent to Tower)
- Analytics (returns, projections, compliance)

Assumptions:
- API: `http://localhost/api`
- Frontend: `http://localhost:5173`
- You have at least one **admin** user and can create partners from the admin panel.

---

## 1. Benefits (Tier & Profile)

### 1.1 Admin: Create a Zonal partner with targets

1. Open the app in a browser:  
   `http://localhost:5173`
2. Log in as an **admin** user on the **Login** page.
3. In the left sidebar, click **Partners** → you should be on `/admin/partners`.
4. Click the **Create** button to open the **Create partner** modal.
5. In the form:
   - **Partner name**: `Tower Zonal Test`
   - **Code**: `TP-ZONAL-001`
   - **Contact name**: any name
   - **Phone**: any Nigerian phone number
   - **Email**: a unique test email (this will be the partner user login)
   - **Tier**: select **Zonal**
   - **Status**: **Approved**
   - **Yearly targets (₦)** – you should see defaults; you can keep or adjust:
     - Paint: `50000000`
     - Plasterboard: `20000000`
     - Polystyrene: `5000000`
6. Click **Create partner**.
7. Confirm the new partner appears in the list with tier **Zonal** and status **approved**.

> Result: You now have a Zonal partner with correct tier, discounts/returns, and yearly targets, ready to test benefits and analytics.

### 1.2 Partner: View benefits on Profile page

1. Log out of admin (or open an incognito window).
2. Log in using the **partner user** created in step 1.1:
   - Email: the email you entered in the Create Partner form.
   - Password: the default or whatever your backend uses for created users.
3. After login you should land on `/partner` (Partner dashboard).
4. In the left sidebar, click **Profile** → `/partner/profile`.
5. Verify the **Profile** page shows:
   - **Account** section:
     - Name, Email, Phone (from user).
   - **Partnership** section:
     - Badge like **“Zonal Partner”**.
     - Status badge: **Approved**.
     - Payment badge: **Payment confirmed** (if payment_status is confirmed for this partner).
     - Business name, State, Territory.
   - **My Benefits & Entitlements**:
     - Purchase discounts:
       - Paint: **15%**
       - Plasterboard: **7%**
       - Polystyrene: **5%**
     - Yearly returns (up to):
       - Paint: **10%**
       - Plasterboard: **5%**
       - Polystyrene: **2%**
     - Logistics subsidy text: **100% subsidy** for Zonal.
     - Bullet points:
       - Territory exclusivity.
       - Yearly training.
       - Yearly advert support.
       - Zonal‑only bullet: same % returns from downline State Reps.
       - 85% target rule reminder.
   - **Investment Package** (Zonal only):
     - Products: ₦19M
     - Mixer: ₦2.5M
     - Registration: ₦1M
     - Total: ₦22.5M

> Result: The partner can see their full business benefits and the ₦22.5M Zonal package breakdown.

---

## 2. Goods Allocation (Onboarding Dispatch)

### 2.1 Admin: Record an allocation for a partner

1. Log in as **admin** and go to **Partners**: `/admin/partners`.
2. Click on the Zonal partner you created (e.g. `Tower Zonal Test`) to open **Partner Detail**: `/admin/partners/:id`.
3. On the Partner Detail page, locate the **Allocations (goods dispatched)** card.
4. Check that:
   - It shows **Total allocated value: —** initially (no allocations).
   - Below, you see “No allocations recorded yet.”
5. Click the **Create allocation** button:
   - A modal titled **“Create allocation”** opens.
6. In the **Create allocation** modal:
   - **Allocation date**: leave as today or choose another date.
   - **Notes**: e.g. `Initial Zonal package`.
   - In **Allocation items**:
     - For the first row:
       - Product name: `Satin Paint 20L`
       - Qty: `100`
       - Unit value (₦): `50000`
     - Click **Add item** and add another row:
       - Product name: `POP Cornice`
       - Qty: `50`
       - Unit value (₦): `30000`
   - Verify that the **Total** at the bottom updates to:
     - `100 * 50000 + 50 * 30000 = 5,000,000 + 1,500,000 = ₦6,500,000`
7. Click **Save allocation**.
8. Back on the **Allocations** card:
   - You should now see:
     - **Total allocated value: ₦6,500,000** (formatted).
     - A list entry with the allocation date and total value.
     - A brief list of product names (e.g. `Satin Paint 20L, POP Cornice…`).

> Result: The Zonal partner now has a recorded allocation with product names, quantities, and values. This does not affect inventory — it’s a pure financial allocation record.

### 2.2 Partner: See allocated goods summary

1. Log in as that **Zonal partner** again.
2. Go to **Profile** → `/partner/profile`.
3. Scroll down below **Investment Package**.
4. Verify the **“Products received”** section appears:
   - Text like:  
     “Total value of goods allocated to you so far: ₦6,500,000”
   - A short explanatory note that this reflects all recorded allocations.

> Result: The partner sees a clear, read‑only summary of the total value of all goods dispatched to them.

---

## 3. Remittances (Money Sent to Tower)

### 3.1 Partner: Submit a new remittance

1. Log in as a **partner** (Zonal/State/Local/Advert).
2. In the sidebar, click **Remittances** → `/partner/remittances`.
3. Confirm:
   - Page title: **Remittances**.
   - A summary card showing **“Confirmed remittances total: ₦0”** if none yet.
   - A **History** card listing previous remittances (likely empty at first).
4. Click **New remittance**.
5. In the **New remittance** modal:
   - **Date**: leave as today.
   - **Amount (₦)**: e.g. `1500000`.
   - **Tower bank account**: choose one from the dropdown (comes from `/admin/banks`).
   - **Category**: choose `Paint`, `Plasterboard`, `Polystyrene`, or `Mixed` (e.g. `Mixed`).
   - **Reference**: e.g. `TRF-TEST-001`.
   - **Notes**: e.g. `Remittance for Week 12 sales`.
6. Click **Submit**.
7. After a successful toast:
   - The modal closes.
   - The history table shows a new row:
     - Date: your chosen date.
     - Amount: `₦1,500,000`.
     - Category: e.g. `mixed`.
     - Bank: your selected Tower bank.
     - Reference: `TRF-TEST-001`.
     - Status: **Pending** (yellow badge).
   - The summary **Confirmed remittances total** remains ₦0 (remittance is still pending).

> Result: The partner has submitted a cash remittance to Tower, pending admin confirmation.

### 3.2 Admin: Review and confirm/reject remittances

1. Log in as **admin**.
2. Navigate to **Remittances** for admins: `/admin/remittances` (or via your admin menu if wired).
3. Confirm:
   - Filters card with **Status**, **From**, and **To** fields.
   - Table listing remittances (including the one you just submitted as a partner).
4. (Optional) Filter:
   - Set **Status** = `pending`.
   - Click **Apply** to see only pending remittances.
5. In the table, find the row for your test remittance:
   - Check **Date**, **Partner** name, **Amount**, **Category**, **Bank**, **Status = pending**.
6. Click **View** on that row:
   - A **Remittance detail** modal opens.
   - Shows partner, date, amount, category, bank, reference, notes, status.
7. Test **Reject**:
   - Click **Reject**.
   - If prompted, enter a short rejection reason or leave blank.
   - Confirm you see a success toast.
   - Table should now show **Status = rejected** (red badge).
8. Test **Confirm** (create another remittance first if needed):
   - Submit a second remittance from the partner (repeat steps in 3.1).
   - Back in `/admin/remittances`, open that new remittance in **View**.
   - Click **Confirm**.
   - Status changes to **confirmed** (green badge) after reload.

> Result: Admin can see, confirm, or reject partner remittances with a full audit of basic info and notes.

### 3.3 Partner: See confirmed totals

1. Log back in as the same **partner**.
2. Go to `/partner/remittances`.
3. Check:
   - In **Summary**, **Confirmed remittances total** now includes all remittances with status `confirmed`.
   - In **History**, your rejected entry shows `Status = rejected` and confirmed ones show `Status = confirmed`.

> Result: Partners can see their full remittance history and how much Tower has confirmed.

---

## 4. Analytics (Returns, Projections, Compliance)

The analytics layer is already wired to:

- Use `yearly_targets` (synced from partner yearly_target_* or tier defaults).
- Use `sales_reports` for weekly category totals.
- Use `sales` for actual transactional totals in some services.

### 4.1 Admin: View analytics

1. Log in as **admin**.
2. Navigate to **Analytics**: `/admin/analytics`.
3. Test:
   - Use filters or partner selection (depending on your UI) to pick the Zonal partner you created.
   - Verify:
     - **Return simulator** loads based on that partner’s yearly targets and sales.
     - **Projection card** reflects the 85% rule with given targets.
     - **Compliance tracker** shows weekly submissions (after you submit sales reports as partner).

> Result: Admin can see if a partner is on track for returns, if they are compliant with weekly reporting, and what their projected year‑end outcome is.

### 4.2 Partner: View analytics

1. Log in as **partner** (Zonal/State/Local/Advert).
2. Go to **Analytics**: `/partner/analytics`.
3. Verify:
   - Return Simulator and projection widgets use:
     - The partner’s yearly targets (from `YearlyTarget`).
     - The partner’s own weekly sales reports and sales data.
   - Compliance + targets behave correctly when you:
     - Add weekly **Sales Reports** via the existing **SalesSubmitForm** or dedicated compliance UI.

> Result: Partners can self‑serve to understand how close they are to meeting the 85% threshold and what their potential returns look like.

---

## 5. Quick Smoke Checklist

Run through this checklist to confirm everything is wired correctly:

- [ ] Can create a Zonal partner with yearly targets from admin.
- [ ] Partner Profile shows correct tier, benefits, and Zonal investment breakdown.
- [ ] Admin can create allocations; total allocated value updates; products appear on Partner Detail.
- [ ] Partner Profile shows “Products received” with the summed allocation value.
- [ ] Partner can submit remittances; they appear as pending in history.
- [ ] Admin can view, confirm, and reject remittances; statuses update correctly.
- [ ] Partner sees confirmed totals and status changes on their Remittances page.
- [ ] Admin Analytics loads for the test partner and reflects targets/sales correctly.
- [ ] Partner Analytics shows their own returns/projections/compliance using the test data.