# Shop Portal — Detailed Review Plan

**Scope:** shop portal only (`frontend/`, aurora) on `shop.navagoo.localhost` · branch `tailwind-poc`.
**Design source of truth:** React demo (`../Navagoo_MI`) + `ai_specs/07_DEMO_PARITY/*` + UX judgment.
**Mode:** fix-as-we-go. **Tracker:** `_REVIEW/REVIEW_TRACKER.md`. **Per-page docs:** `_REVIEW/page_reviews/NN_*.md`.

---

## PART A — Methodology

### A.1 Two lenses (every page gets both)
- **Design lens** — placement, hierarchy, RTL, spacing/rhythm, element states (rest/hover/focus/active/disabled/empty/loading/error), responsive (320/768/1024/1440), both languages, parity vs demo.
- **Logic lens** — every interactive element is *triggered*, its result observed, its backing controller/service traced, and its nested target (modal/sub-page/endpoint) followed **one level deep**, covering success + validation + error paths.

### A.2 The review graph — "who reviews what"
```
REVIEWER (tool / skill / agent)        →  reviews  →  SUBJECT             →  leads to (nested)
─────────────────────────────────────────────────────────────────────────────────────────────
Claude-in-Chrome (read_page/snapshot)  →  inventory →  page elements       →  the element list itself
ui-review / ux-audit + design-taste    →  critiques →  visual design       →  demo screen + parity doc
accessibility-* (wcag-audit-patterns)  →  audits    →  a11y                →  keyboard path, contrast, ARIA
Claude-in-Chrome (click/fill) + verify →  exercises →  each action         →  modal / sub-page / endpoint
webapp-testing                         →  drives    →  multi-step flows     →  success + error states
php-reviewer / code-reviewer (agents)  →  reads     →  controller+service   →  DB write / API contract
security-reviewer (agent)              →  audits    →  state-changing code  →  auth, CSRF, mass-assign, IDOR
find-bugs / systematic-debugging       →  diagnoses →  a failing action     →  root cause → fix
```
Each SUBJECT is reviewed by **at least** its design reviewer + its logic reviewer; state-changing subjects additionally get the security reviewer.

### A.3 Severity rubric
| Level | Meaning | Gate |
|---|---|---|
| CRITICAL | data loss, security hole, action 500s / corrupts | BLOCK — fix before leaving page |
| HIGH | action broken, wrong result, broken layout, parity break | fix this page |
| MEDIUM | minor logic gap, state missing, spacing/rhythm off | fix if cheap, else log |
| LOW | polish, copy, micro-interaction | log |

### A.4 Evidence standard (per finding)
Design → screenshot id (+ breakpoint/lang). Logic → console + network capture of the request/response. Code → `file:line`. Fix → re-verified screenshot/network proving the new behavior.

### A.5 Safety rails — action test-classification
Every state-changing action is classified before triggering it live:
- **🟢 READ** — GET / preview only → trigger freely.
- **🟡 TEST-FIXTURE** — reversible write → use a disposable test record (e.g. the `sp_*@testzone321.local` specialists, a throwaway service/booking) and undo after; never touch real customer/financial rows.
- **🔴 FORBIDDEN-ON-LIVE** — irreversible, money, or outbound comms → **never auto-trigger**. Verify by code-trace + (optionally) a read-only dry run / local DB. Ask the user to perform if a live trigger is truly needed.

Cross rules: API contract is shared with the mobile app — flag any contract change before touching. Aurora pages must use `ngToast/ngConfirm/ngPrompt`. Rebuild `npm run build:css` after any class change.

### A.6 Sign-off gate (per page)
A page is ✅ only when: design deltas resolved-or-accepted · every 🟢/🟡 action triggered & green · every 🔴 action code-traced · nested modals/sub-pages covered · both languages + key breakpoints · fixes re-verified live.

---

## PART B — The 7-step loop, expanded

| # | Step | Performed by | Input → Output | Pass criteria |
|---|------|--------------|----------------|---------------|
| 1 | **Map** | Chrome `read_page(interactive)` + `snapshot`; cross-ref demo+spec | page → element inventory table (§1 of page doc) | every interactive ref captured with expected action + target |
| 2 | **Design pass** | Chrome `screenshot`/`resize`/`inspect` + `ui-review`/`design-taste` + a11y skill | inventory → design findings table | screenshots at 320/768/1024/1440 ×2 langs; deltas vs demo logged |
| 3 | **Logic pass** | Chrome `click`/`fill` + `verify`; `webapp-testing` for flows | each 🟢/🟡 action → observed result + network log | success + validation + error paths exercised; 🔴 skipped (traced in step 4) |
| 4 | **Code trace** | `php-reviewer`/`code-reviewer`/`security-reviewer` agents | action → controller→service→DB/endpoint notes | risks named (auth/CSRF/validation/IDOR/N+1/mass-assign); 🔴 actions verified by reading |
| 5 | **Catalog** | me | findings → page doc §2/§3/§4 + tracker issue rows | each finding has severity + evidence |
| 6 | **Fix** | me (+ build-error-resolver if build breaks) | CRITICAL/HIGH first → edit → `build:css` if needed | `php -l` clean; re-verified in Chrome |
| 7 | **Sign off** | me | update tracker row → ✅ + proof | A.6 gate met |

---

## PART C — Sequenced phases

**Phase 0 — Cross-cutting (once, before pages).** Sidebar nav routes + active states · top bar (language toggle `/site/set-locale` both ways, notifications bell, profile menu) · aurora layout (`tailwind.php`) · global dialogs (`ngToast/ngConfirm/ngPrompt`) · Feedback FAB · Demo-controls drawer gating. Output: `page_reviews/00_cross_cutting.md`.

**Phases 1–17 — pages, in tracker order.** Dependency notes:
- P1 Booking Calendar and P2 Agents share scheduling/shift logic → review P1 then P2 back-to-back.
- P4 Services + P5 Packages share the catalogue/VAT logic → consecutive.
- P6 Earnings + P7 Transfers + P8 Tips share `agents-wallet`/finance → consecutive; all contain 🔴 money actions (code-trace only).
- P9 Settings feeds P3 Shop Settings (districts) → P3 before/with P9.

**Within each page (micro-sequence):**
`main view → each tab/filter → each row action → each modal (open→fields→submit success→submit invalid→cancel) → each nested sub-page → code-trace every action → fix → re-verify → sign off.`

---

## PART D — Per-page dossiers (real actions from controller scan)

Legend: 🟢 read · 🟡 test-fixture · 🔴 forbidden-live(code-trace only). Reviewer: D=design, L=logic, S=security(+code).

### P1 — Booking Calendar  `/booking-calendar`  · `BookingCalendarController` (+ `Booking*Service`, behind it `BookingController`)
| Action / Route | Class | Method | Leads to | Reviewer |
|---|---|---|---|---|
| `index?view=day/list/month` | 🟢 | GET | the 3 views + toolbar | D+L |
| `detail?id=` | 🟢 | GET (iframe_aurora) | styled detail modal | D+L |
| `walk-in` | 🟡 | GET+POST create | walk-in modal → real booking | D+L+S |
| `group-booking` | 🟡 | GET+POST create | group modal → party | D+L+S |
| `block-time` | 🟡 | POST | block slot | L+S |
| `reschedule` / `reassign` | 🟡 | POST (drag) | move booking date/agent | L+S |
| behind: `booking/transition`,`collect` | 🟡 | POST | FSM + finance ledger | L+S |
| behind: `booking/cancel`,`cancel-preview` | 🔴/🟢 | POST/preview | refund math; cancel = customer impact | S (trace), L (preview only) |
| toolbar: search, status chips | 🟢 | client JS | filter rows | D+L |
**Nested one level:** detail modal → {Collect&complete, Reschedule, No-show, Cancel}; empty-slot click → walk-in; drag → reschedule/reassign.

### P2 — Agents  `/agents`  · `AgentsController`
| Action | Class | Leads to | Reviewer |
|---|---|---|---|
| `index` | 🟢 | list + Payroll tab + org-chart | D+L |
| `view?id=` | 🟢 | specialist detail | D+L |
| `create` / `update?id=` | 🟡 | agent form (+ shift rows, time-off, wage) | D+L+S |
| `shift-row` | 🟢 | AJAX shift-row partial | L |
| `structure-add-child` | 🟡 | new stub under parent *(R-002 locale fix here)* | L+S |
| `structure-rename` | 🟡 | inline rename | L |
| `structure-reparent` | 🟡 | drag reports-to *(R-002 here too)* | L+S |
| `structure-delete` | 🔴 | hard delete / deactivate guard | S (trace) |
| `toggle-status` / `toggle-show-hide` | 🟡 | activate / hide | L+S |
| `check-mobile` | 🟢 | uniqueness AJAX | L |
| `calendar`/`shop-calendar`/`filter-events` | 🟢 | agent calendar feed | L |
**Nested:** edit form → time-off add/remove, shift add/remove, wage/commission; org-chart → add/rename/reparent/delete.

### P3 — Shop Settings  `/shop-settings/index`  · `ShopSettingsController` (1 page, many tabs)
🟢 `index` (GET) + 🟡 save (POST same action). Reviewer D+L+S. Nested: each settings tab (profile, hours/overnight, location/districts→ depends on `settings/districts`, gallery, policies). Heavy design surface (32 form fields seen).

### P4 — Services  `/shop-service`  · `ShopServiceController`
| Group | Actions | Class | Reviewer |
|---|---|---|---|
| service CRUD | `index`🟢 `view`🟢 `create`🟡 `update`🟡 `delete`🔴 | | D+L+S |
| service state | `toggle-active`🟡 `toggle-hidden`🟡 | | L |
| pricing AJAX | `calculate-vat`🟢 `check-service-price`🟢 | | L |
| category img | `update-category-image`🟡 | | L |
| freebies | `freebie-save`🟡 `freebie-delete`🔴 `freebie-toggle-active`🟡 `freebie-toggle-hidden`🟡 | | L+S |
| bundles | `bundle-save`🟡 `bundle-delete`🔴 `bundle-toggle-active`🟡 `bundle-toggle-hidden`🟡 | | L+S |

### P5 — Packages  `/package`  · `PackageController`
package CRUD `index/view/create/update`(🟡) `delete`(🔴) `toggle-status`(🟡); subscriptions `subscriptions`🟢 `subscription-{create,update}`🟡 `subscription-delete`🔴 `subscription-toggle-status`🟡; pricing `get-period`🟢 `calculate-period`🟢. Reviewer D+L+S.

### P6 — Shop Earnings  `/earnings`  · `EarningsController`  ⚠️ money
🟢 `index`,`view`,`save-column-preferences`(🟡). 🔴 `pay-invoice`, `request-transfer`, `subscription-activate`, `subscription-cancel`, `add-card`, `set-default-card` → **code-trace + security-reviewer only; never auto-trigger.** Reviewer D+S.

### P7 — Transfer Requests  `/agents-wallet/index`  · `AgentsWalletController`  ⚠️ money
🟢 `index`,`view`,`view-payment`,`get-bank-account-details`,`save-column-preferences`(🟡). 🔴 `payment`,`create`,`delete` (payout) → code-trace + security only. Reviewer D+S.

### P8 — Specialists Tips  `/agents-wallet/specialist-tips`
🟢 `specialist-tips` (GET, same controller). Reviewer D+L.

### P9 — Settings  `/settings/index`  · `SettingsController`
🟢 `index`, `districts` (AJAX cascade). 🟡 save. Reviewer D+L. (districts feeds P3.)

### P10 — Customers  `/customers`  · `CustomersController`
🟢 `index`. 🟡 `freeze`/`unfreeze` (reversible pair → safe with test customer). Reviewer D+L+S.

### P11 — Customer Invitations  `/customer-invitations`  · `CustomerInvitationsController`
🟢 `index`. 🔴 `create` (POST — **sends invitation / outbound**) → code-trace + ask before live send. Reviewer D+S.

### P12 — Promo Codes  `/promo-code`  · `PromoCodeController`
🟢 `index`,`view`. 🟡 `create`,`update`. 🔴 `delete`. Reviewer D+L+S.

### P13 — Reviews  `/rate`  · `RateController`
🟢 `index`,`view`. 🔴 `delete` (removes a customer review). Reviewer D+L.

### P14 — Notifications  `/notifications/index`  · `NotificationsController`
🟢 `index`. 🟡 `mark-all-read`. Reviewer D+L.

### P15 — Dashboard  `/`  · `SiteController`
🟢 landing/dashboard widgets + KPI cards + quick links. Reviewer D+L. (entry surface — check every widget links somewhere valid.)

### P16 — Branches  `/branch`  · `BranchController`
🟢 `index`,`view`,`districts`. 🟡 `create`,`update`,`add-shop-gallery`,`status`,`toggle-approval-status`. 🔴 `delete`. Reviewer D+L+S.

### P17 — Social Media  `/social-media`  ⏸ gated (feature `enabled=0` in DB)
Blocked until enabled. When on: 🟢 `index`,`posts`. 🟡 `create`. 🔴 `send-connect`(email), `sync`(external API), `delete`. Reviewer D+L+S.

---

## PART E — Output flow
Per finding → page doc table + tracker issue row (R-NNN). Per fix → page doc §5 + tracker issue ✅ + re-verify proof. Per page done → tracker Design/Logic columns → ✅ with sign-off date. Session end → tracker is the single source of truth for what's reviewed, what's fixed, what's left.