# Finance Parity Wave — 2026-07-05

**Goal:** make the portal `/earnings` Finance hub match the demo `#/shop/finance/*` — logic AND UI.
**Requested by user:** "the earnings is called in the demo finance — make the earnings the same as the finance, also the logic and the UI. make a plan and make a wave, very fast."

## Method (playbook golden rule followed)
Both sides were **rendered and screenshotted first** (demo via Vite :5173 preview, portal via
logged-in preview browser at shop.navagoo.localhost/earnings) before any code was written.
Note: demo gained new deps (`cmdk`, `@radix-ui/react-popover`) — `npm install` needed in
`Navagoo_MI/navagoo-app` before it boots.

## Verified differences (portal → demo)

| # | Area | Portal (before) | Demo (target) |
|---|---|---|---|
| 1 | Sidebar | "Shop Earnings" | **"Finance" / المالية** |
| 2 | Tab bar | pill segmented + icons, "Charges" | underline TabNav, no icons, "Detailed Charges", count badges (unpaid invoices = red, eligible = neutral) |
| 3 | Earnings cards | 8 cards (4 legacy extras) | exactly 4: Revenue / Navagoo Fees / Net Earnings / Withdrawable(+Request transfer) |
| 4 | Earnings extras | — | "In-store collected: SAR X · cash Y · card Z" strip |
| 5 | Earnings table | 11 cols (BOOKING ID, FINAL COLLECTED, FINAL COLLECTIBLE…) | 10 demo cols: BOOKING(code+customer) / DATE / STATUS / PAYMENT("100% Online"/"Pay on Visit"/"Deposit (30%)") / BOOKING VALUE / NET EARNINGS(± + incl-fees subtext) / NAVAGOO PAYOUT / ELIGIBLE("Yes"/"Nd left") / SETTLEMENT / COLLECTION |
| 6 | Settlement | formula missing TIPS; no Eligibility table; withdrawal history table | "Net payout this cycle" (COLLECTED+TIPS−MKT−PROC−VAT=NET) + hold/min footnotes + **Eligibility table** (BOOKING/CUSTOMER/SPECIALIST/STATUS/VALUE/TIPS/CHARGES/NET/HELD) + **Transfer requests** list |
| 7 | Charges | ID/DATE/BASE AMOUNT/TOTAL naming | CHARGE ID/CHARGE DATE/BASIS/RATE/CHARGE/FEE VAT + colored type chips + reversal note |
| 8 | Invoices | plain empty state; ID/TYPE/GROSS TOTAL cols | INVOICE/PERIOD/CHARGES/FEE VAT/AMOUNT DUE/STATUS/ISSUED/DUE + icon empty state |
| 9 | Subscription | no billing-period toggle | Monthly/6mo/12mo toggle + demo plan cards + current-plan banner |
| 10 | Logic | controller lacks tips/in-store/eligibility rows/tab counts | Foundation adds them from real DB (additive) |

| 11 | Earning detail | separate page `/earnings/view?id=` | demo opens a **right slide-over drawer** on row click: badges → YOUR EARNINGS (revenue/VAT/online/in-person/tips/specialist tip) → NAVAGOO FEES (marketing/processing/VAT/total) → settles-via-Navagoo waterfall → LEDGER ROWS. Port = view.php rewritten to drawer content + `?iframe=1` chrome-less via iframe_aurora + row click opens ngDrawer with iframe (dedicated agent, files: view.php + _earnings.php) |

**Intentional divergences:** settlement CTA stays **"Request transfer"** (demo's "Approve & send"
is simulator-only); invoices empty-state drops demo's "Simulate menu" wording.

## Wave (Workflow run `wf_d6f718c0-c58`)
- **Foundation** (1 agent): `EarningsController::actionIndex` additive view-model — `inStore`,
  `settlementFormula.tips`, `eligibilityRows`, `transferRequests`, `tabCounts`, `earningsRows`
  (no N+1). Returns exact contract for builders.
- **Build** (5 parallel, disjoint files): index.php+sidebar/menu rename · _earnings.php ·
  _settlement.php · _charges.php · _invoices.php+_subscription.php.
- **Verify** (6 parallel): php -l + hook integrity (data-tab/data-pane/ng-request-transfer) +
  adversarial fidelity vs demo tsx.
- **Integration (orchestrator):** apply returned i18n keys centrally to
  `common/messages/{ar,en}/{frontend,backend}.php` (Arabic-guard), `npm run build:css`,
  curl smoke + preview screenshots vs demo, commit.

## Status
- [x] Both sides rendered + screenshotted
- [x] Wave completed (12 agents, all lint clean, no criticals)
- [x] Detail drawer ported (view.php demo EarningsDrawer + row-click ngDrawer/iframe opening)
- [x] Integration: 64 i18n keys (ar+en), verifier fixes (Held=elapsed days, Notifications formula term,
      tips sub-line, date "21 May 2026", subtitle key, honest add-card copy), build:css
- [x] Browser-verified: tabs + drawer open on row click with demo content (screenshots)
- [x] Commit

### Deferred (logged, small)
- Invoices "Being settled via {TR}" locked-row state (needs open-TR↔invoice linkage)
- inStore cash/card split renders 0 (no cash-vs-card column — NVG-BEA-001 schema gap)
- 6/12-month billing toggle disabled (plans are monthly-priced only)
- Eligible chip tones green/amber vs demo blue/slate (cosmetic)