# Quote Sharing & Customer Approval Architecture

## Overview

The quote → share → customer approve/decline → shop notified flow. Covers v2 React/Vite frontend only.

## Key Files

| File | Role |
|------|------|
| `src/components/quoteGenerator/QuoteSummary.tsx` | "Share with Customer" button + email/SMS draft links |
| `src/pages/QuoteApprove.tsx` | Public customer-facing approval page (no auth) |
| `src/store/quote.ts` | Zustand store with `approvedSubtotal()`, decision state |
| `src/lib/contactLinks.ts` | `openEmailDraft()` and `openSmsDraft()` — local mailto:/sms: links only |
| `src/lib/totals.ts` | Billable subtotal logic: approved-only vs all-non-declined |
| `src/pages/Dashboard.tsx` | Real-time subscription on quotes collection (line 162) |
| `src/schemas/quote.ts` | Zod validation — `shareToken`, `status`, service `customerDecision` |

## Share Flow (QuoteSummary.tsx:104-170)

1. `ensureShareToken()` called — saves quote to PocketBase if not yet saved, generates a `crypto.randomUUID()` token, writes it to `quote.shareToken`
2. Returns URL: `${window.location.origin}/quote/approve/${token}`
3. **Copy to clipboard**: `handleShare()` (line 154) — copies link, shows shareUrl UI with Email/SMS buttons
4. **Email draft**: `handleSendEmail()` (line 172) — calls `openEmailDraft(to="customerPhone", subject, body)` which fires `mailto:` link. Does NOT send from server.
5. **SMS draft**: `handleSendSms()` (line 195) — calls `openSmsDraft(to="customerPhone", body)` which fires `sms:` link. Does NOT send from server.
6. Quote status set to `'sent'` on first share.

**Important**: `customerEmail` does NOT exist on `CustomerInfo` or the quote schema (`quoteWriteSchema`). Only `customerPhone` is captured. The `mailto:` link uses phone number as the `to` field (a no-op in most clients).

## Customer Approval Page (QuoteApprove.tsx)

### Loading
- Public route: `/quote/approve/:token` — no auth required
- `loadQuote()` queries PocketBase using `shareToken` as both filter and query param (PB API rule gating)
- On load, stamps `viewedAt` on the quote record via `stampViewed()` — fires once per quote

### Approval Flow
1. Customer sees per-service Approve/Decline toggle buttons
2. Must make a decision on every visible service before submitting
3. Must enter their full name as signature
4. `handleSubmitAll()` (line 159) writes per-service decisions to PocketBase:
   - `customerDecision`: `'approved'` / `'declined'`
   - `approved`: `true` / `false`
   - `authorizedBy`: customer's name
   - `authorizedAt`: ISO timestamp
   - `authorizedMethod`: `'signature'`
5. Top-level quote `status` computed:
   - All approved → `'approved'`
   - All declined → `'declined'`
   - Mixed → `'sent'` (stays "pending" in UI filters)

### Security Gaps
- **No identity verification**: The share token (UUID) is the only gate. Anyone with the URL can approve/decline. No phone/email verification, no PIN, no expiry.
- **No customer email field**: `CustomerInfo` type lacks `email`. Only repair orders and invoices have `customerEmail`. No way to send the share link to an email address even if email sending were implemented.
- **No expiry**: Roadmap item 4.2 suggests PB `onRecordBeforeUpdateRequest` hook checking `quoteExpiryDays` from settings, but not implemented.

## How the Shop Knows

### Dashboard Real-Time Subscription (Dashboard.tsx:157-189)
```ts
unsub = await pb.collection('quotes').subscribe('*', (data) => {
  // Delta-applies quote changes to the in-memory list
  // Stats (approved count, pending review) update reactively
});
```
- **Live on Dashboard only**: Stats update without refresh while on that page
- **No proactive notification anywhere**: No toast popup, no browser Notification API, no sound, no email/SMS sent to the shop
- **Other pages**: Quotes page (`QuoteGenerator.tsx`) must be manually refreshed

### Toggle in Settings
- Settings → Notifications tab has "Email Notifications" toggle (description: "Receive email notifications for quote updates and approvals")
- **Placard only**: Saved to `localStorage` as `spq-emailNotifications`. No backend code reads this preference. No email is ever sent regardless of toggle state.
- Roadmap 4.1 describes a PB `onRecordAfterUpdateRequest` hook that would auto-send email via PB SMTP when quote status changes from `sent` to `approved`/`declined` — not implemented.

## Verified Capabilities & Gaps Matrix

| Capability | Status | Where |
|-----------|--------|-------|
| Generate share link with UUID token | ✅ Done | QuoteSummary.tsx:104-146 |
| Copy link to clipboard | ✅ Done | QuoteSummary.tsx:164 |
| Open local email/SMS draft | ⚠️ mailto:/sms: only, no server sending | contactLinks.ts |
| Customer views & stamps viewedAt | ✅ Done | QuoteApprove.tsx:56-67 |
| Per-service approve/decline | ✅ Done | QuoteApprove.tsx:155-157 |
| Per-service authorizedBy/authorizedAt tracking | ✅ Done | QuoteApprove.tsx:180-192 |
| Quote status update (approved/declined/sent) | ✅ Done | QuoteApprove.tsx:198-205 |
| Real-time Dashboard updates | ✅ Done | Dashboard.tsx:162-183 |
| **Toast/notification when customer responds** | ❌ Missing | — |
| **Browser Notification API alert** | ❌ Missing | — |
| **Email sent to shop on approval** | ❌ Missing | Planned at roadmap 4.1 |
| **Phone/last-4 verification** | ❌ Missing | — |
| **Quote expiry** | ❌ Missing | Planned at roadmap 4.2 |
| **customerEmail field on quote form** | ❌ Missing | Only on RO/Invoice schemas |
| **Server-side email sending** | ❌ Missing | No SMTP util in codebase |
| **Server-side SMS sending** | ❌ Missing | Would need Twilio/etc |

## Related Roadmap Items

- **4.1 Quote approval notifications**: PB hook sends email when status flips from `sent` to `approved`/`declined`. Requires PB SMTP from 3.2 (already configured in Docker env per Ray).
- **4.2 Quote expiry enforcement**: PB hook blocks updates if `quoteExpiryDays` exceeded and request uses `shareToken` query param.

## Approximate Approach for Adding Identity Verification (least-infrastructure option)

1. Add `verificationCode` (short random string, e.g. last-4-of-phone or 4-digit PIN) to the quote PB record — set it when generating the share link
2. On `QuoteApprove.tsx` load, if verification code exists, show a code-entry prompt before revealing services
3. Customer enters the code → matches → show the approval UI
4. The verification code can be communicated separately (verbally, or via SMS/email through existing channels)
5. No server-side infrastructure beyond the PB record field