# TechTitans POS — Customer CRM Phase C3 UI Redesign

**Date:** 2026-11-12 · **Branch:** `techtitans/integration` (backend + frontend) · Local commits only (no push/deploy).
**Builds on:** the legacy audit (`customer-legacy/01–06`) and Phase C2 (`CUSTOMER-CRM-C2-IMPLEMENTATION.md`). Primarily a UI/UX upgrade of the Customer Profile — the CRM architecture and all C2 functionality are preserved.

**Guardrails honoured:** NH POS untouched, no legacy PHP executed, no historical data migrated, no insecure/legacy upload handlers added, nothing pushed. The only backend change is one additive, justified feature (the human customer reference) — documented below.

## 1. Old portal vs C2 vs C3

| Aspect | Old TechTitans portal | C2 (before) | C3 (now) |
|---|---|---|---|
| Identity header | plain table, session-bound | basic badges + contact subtitle | **premium navy→teal gradient** header: avatar, name, **human reference**, type/status, phone·email·since, Edit + New order |
| Staff reference | `customer_id` int | **raw UUID shown** (not ideal) | **`CUST-0001`** human number (UUID never exposed) |
| Service cards | due-vs-total text rollups | 4 cards (navy/amber/cyan/coral) | 4 **meaningful-colour** cards: Orders **blue**, Repairs **purple**, IPTV **emerald**, Outstanding **coral/green** |
| Tabs | left-rail links | plain text tabs | **icon tabs + count badges + active state**, horizontal-scroll on mobile |
| Overview | per-table N+1 queries | 2 cards + activity | **dashboard**: customer info (+address), quick actions, relationships, recent activity + **View all** |
| Notes & Activity | notes text field | **stub** ("coming later") | **filterable timeline** (All/Orders/Repairs/IPTV/Payments/Notes) of real records |
| Edit customer | separate page | — (no edit UI) | **right-side Edit drawer** (PATCH, reuses the service) |
| Family/groups | Add Family / Group buttons | APIs only, no UI | **right-side relationships drawer** (existing CRM relationship APIs) |

## 2. Human customer reference (the one backend change)
Section 2 forbids exposing the raw UUID as the staff reference, and C2 did. **Investigation:** the repo already uses dedicated per-scope number sequences (`iptv_number_sequences`, `repair_number_sequences`, `order_number_sequences`) via an atomic `INSERT … ON DUPLICATE KEY UPDATE … LAST_INSERT_ID` allocator. **Implemented the same pattern for customers** (documented here, then built as a scoped additive change):
- New `customer_number_sequences` (per-tenant, since customers are tenant-owned) + `CustomerNumberSequencer` → `CUST-{seq}`.
- Additive migration adds **nullable, `UNIQUE(tenant_id, customer_number)`, indexed** `customers.customer_number`; **existing rows are backfilled** per tenant in creation order and the sequence is seeded to the max. The internal **UUID `id` is never touched**.
- `CustomerService` assigns the number on **every create path** (create / find-or-create / order resolution); `CustomerResource` exposes it; the C2 search now also matches it (search by `CUST-0001`).

## 3. UI redesign
- **Header** (`.cust-head`): navy→teal gradient, ringed avatar, name + reference chip, type/status badges, phone·email·since meta, **Edit customer** (customers.manage) + **New order**.
- **Service cards**: soft-coloured, solid-fill icon tiles; distinguish **active vs total** (Repairs = open / total; IPTV = active / connections; Orders = count + last; Outstanding coral when owed, emerald when settled — read from the authoritative stats, never recomputed).
- **Overview**: **Customer information** (name, reference, type, phone, email, default address, since, notes) · **Quick actions** (New order/repair/IPTV, Add note, Edit) · **Relationships & groups** (+ Add) · **Recent activity** (6 most recent, View all → Notes & activity tab).
- **Tabs** (`.cust-tab`): 16px icons, active navy pill, **count badges** (Orders, Addresses, CRM computed cheaply from the loaded profile), 40px targets, horizontal scroll on mobile.
- **Notes & Activity** (`CustomerActivityPanel`): a **composed, filterable** chronological view of REAL records — orders, payments, repair tickets, IPTV connections (+ the customer note) — each with its real timestamp and a link to the record. Filter chips show only kinds that have data; bounded with a "Showing N of M · Show more" footer. **No audit trail is manufactured from timestamps.**
- **Edit / Relationships drawers**: both right-side `FormDrawer`s reusing the existing services (PATCH customer; CRM relationship add/remove) — never a new table, never an auto-merge.
- **Styling**: palette navy `#123B55` / teal `#008F83` / blue `#0284C7` / purple `#7C3AED` / emerald `#059669` / coral `#E24B50`; soft cards, white panels, subtle shadows, consistent iconography.

## 4. Features reused (not rebuilt)
Customer identity/model, C2 search + phone normalization + duplicate suggestions, financial ledger (`CustomerFinancialService`), order/repair/IPTV customer-scoped endpoints, CRM groups/tags/relationships APIs, addresses/contacts, permissions + tenant isolation. The profile composes these; it never duplicates data or recomputes money.

## 5. Customer photo / documents (gap, not implemented)
There is **no secure customer media/document backend** today (the avatar is initials-only). Per section 8, legacy upload handlers are unsafe (confirmed upload RCE in `customer-legacy/02`) and are **not** reused, and no insecure generic upload was added for visual completeness. **Required for a future increment:** a `customers.manage`-gated avatar/document endpoint with a strict MIME/type allow-list, off-webroot storage, size limits and AV scanning (mirroring how the repair/IPTV modules handle media). Documented here as the remaining functional gap.

## 6. Testing

### Backend (`php artisan test --filter=Customer`) → **107 passed**
`CustomerSearchC2Test` gained *"customers get a human number and are searchable by it"* (sequential `CUST-####`, unique, exposed on profile + directory, searchable). All existing customer tests green. **Pint** clean; **PHPStan** clean on every changed file.

### Frontend → **65 customers+iptv+api tests passed**
Updated fixtures for the new `customer_number`; `CustomerProfilePage.test.tsx` asserts the human reference + Overview service cards + Customer information + Recent activity. `tsc -b`, `eslint`, `npm run build` all clean (pre-existing bundle-size advisory only).

### Live Playwright (real dev UI, techtitans tenant)
- **Overview**: gradient header shows **`CUST-0002`** (not a UUID); recolored service cards (Orders 5 · Repairs 2/2 · IPTV 24/32 · Outstanding CA$181.18); Customer information, Quick actions, Relationships, Recent activity (+ View all) with real orders.
- **Notes & activity**: 6 filter chips; real orders + IPTV timeline with timestamps; "Showing 15 of 50 · Show more".
- **Edit customer** drawer opens.
- **No horizontal overflow** at 1920 / 1440 / 768 / 390 and zoom-emulated 125 % (1152) / 150 % (960) / 200 % (720). **0 console errors.**
- Screenshots: `screenshots/customer-crm-c3/` (`c3-overview`, `c3-activity`, `c3-edit-drawer`, `c3-mobile`, `c3-wide`, and `c2-overview-before` for comparison).

## 7. Functional preservation (verified)
Customer identity rules, C2 search/phone/duplicate logic, financial calculations, IPTV/repair relationships, permissions, tenant isolation, and existing routes/API contracts are all unchanged — every action still flows through the existing services. The new `customer_number` is additive and never alters the UUID.

## 8. Remaining gaps / next increments
- **Secure customer avatar/documents** backend (§5).
- **Server-side audited activity endpoint** — the timeline is composed client-side from the module ledgers; a single paginated `GET /customers/{id}/activity` over the append-only audit log would add create/update events + deeper history and employee attribution.
- **Customer-wide outstanding across modules** (orders+IPTV+repairs) and a **merge-review** tool for pre-existing duplicates.

## 9. Files changed
- **Backend:** `database/migrations/2026_11_12_140000_create_customer_number_sequences_table.php`, `..._140001_add_customer_number_to_customers_table.php` (new), `app/Customers/CustomerNumberSequencer.php` (new), `app/Customers/CustomerService.php` (assign number + search), `app/Customers/CustomerResource.php` (expose), `app/Models/Customer.php` (guard), `tests/Feature/Customers/CustomerSearchC2Test.php`.
- **Frontend:** `src/lib/api/customers.ts` (`customer_number` + `update` + `UpdateCustomerBody`), `src/pages/customers/` — new `CustomerActivityPanel.tsx`, `CustomerEditDrawer.tsx`, `CustomerRelationshipsDrawer.tsx`, `customerActivity.ts`; rewritten `CustomerProfilePage.tsx` + `CustomerOverviewPanel.tsx`; `customers.css` (C3 styles); updated test fixtures.

## 10. Commits (local only — no push)
- **Backend:** this commit — customer_number (sequence + migration + backfill) + search + tests + this report + screenshots.
- **Frontend:** `a097e11` — premium profile redesign (header, cards, icon tabs, Overview, activity, edit + relationships drawers).