hermes-config/skills/self-hosting/shop-pro-quote/references/ro-detail-modal.md

# RODetailModal Architecture

## Overview

`src/pages/RODetailModal.tsx` (~1600 lines) — the full-featured modal viewer for a single Repair Order. Supports both modal (overlay via `navigate(-1)`) and standalone page rendering. Contains 5 tabs: Details, Services, Financial, History, and Timeline.

## Tabs

| Tab | Key Content |
|-----|-------------|
| `details` | Status management, info bar, services summary, promised-time override, clock, void, satisfaction rating |
| `services` | Catalog search + add, manual service rows, new-service creation, totals |
| `financial` | CP/Warranty Total/Cost inputs, Shop Charge input, live Gross Profit display. Writes to `financial` blob keys v2 already reads. See `references/financial-summary-modal.md`. |
| `history` | VIN-based vehicle history (past ROs + quotes for the same VIN) |
| `timeline` | Audit timeline from `roEvents.ts` + Financial Audit Trail from `roFinancialAudit` collection |

## Component Structure

```
RODetailModal
├── Modal wrapper (fixed overlay) or standalone full page
├── Tab bar (Details, Services, Financial, History, Timeline)
├── Tab content (one at a time via activeTab state)
│   ├── detailsContent
│   ├── servicesContent
│   ├── financialContent
│   ├── historyContent
│   └── timelineContent
└── AddTimeModal
```

## Data-Fetching Patterns

### Core RO Fetch
- `fetchRO()` — called on mount, fetches the RO from PocketBase, normalizes services JSON
- `fetchCatalogServices()` — fetches all catalog services for the Services tab

### Tab-Triggered Fetches
Each tab that needs its own data follows this pattern:

```tsx
const loadX = useCallback(async () => {
  if (!ro) return;
  setXLoading(true);
  try {
    const records = await pb.collection('x').getFullList({ filter: ..., sort: ... });
    setXData(records.map(...));
  } catch { setXData([]); }
  finally { setXLoading(false); }
}, [ro]);

useEffect(() => {
  if (activeTab === 'tabname') loadX();
}, [activeTab, loadX]);
```

### Examples:
- **History tab**: `loadHistory()` queries `repairOrders` and `quotes` by VIN, triggered when `activeTab === 'history'`
- **Financial Audit Trail**: `loadFinancialAudit()` queries `roFinancialAudit` by `roId`, triggered when `activeTab === 'timeline'`

## Financial Tab (implemented)

See `references/financial-summary-modal.md` for full design rationale and v1 history.

### State
- `finCpTotal`, `finCpCost`, `finWarrTotal`, `finWarrCost`, `finShopCharge` — string inputs
- `finSaving`, `finSaved`, `finSeeded` — booleans for save state and pre-seed gate

### Pre-seed
On first opening the Financial tab (`activeTab === 'financial'` and `!finSeeded`), inputs are pre-seeded from the RO's existing `financial` blob, falling back to `computeROTotals()` values (CP Total falls back to `totals.total`, Shop Charge falls back to `totals.shopCharge`). The `finSeeded` flag prevents reseeding on subsequent tab switches. Ray confirmed pre-seed is desired.

### Live computed values
- `cpNetTotal` = `max(0, CP Total - Warr Total)`
- `cpNetCost` = `max(0, CP Cost - Warr Cost)`
- `cpGrossProfit` = `cpNetTotal - cpNetCost - Shop Charge`
- `warrGrossProfit` = `Warr Total - Warr Cost`
- `overallGrossProfit` = `cpGrossProfit + warrGrossProfit`

These match `customerPayGpOf()` and `warrantyGpOf()` in `FinancialDashboard.tsx`, so dashboard totals pick up the entered values with zero dashboard-side changes.

### Save
`handleSaveFinancial()` preserves existing blob keys (e.g. `customerType`), writes `grossTotal`/`grossCost`/`warrTotal`/`warrCost`/`shopCharge`/`cpProfit`/`whProfit`/`grossProfit`/`totalAmount`/`totalCost`/`completedAt` to the `financial` JSON blob, appends a `'financial'` ROEvent for the timeline, and relies on the PB M25 hook for audit-trail creation.

### Layout
- Sticky save bar at top (Save Financial button) — per the modal standard, this is the only save button
- Helper text explaining the deduction rules
- Customer Pay card (green): CP Total input, CP Cost input, CP Net Total display, CP Net Cost display, CP Gross Profit display
- Warranty card (blue): Warranty Total input, Warranty Cost input, Warranty GP display
- Shop Charge card (amber): Shop Charge input, CP GP after Shop Charge display
- Gross Profit summary bar: Overall Gross Profit (large, color-coded green/red), CP GP + Warranty GP breakdown

## Timeline Tab

### Audit Timeline (existing)
- Reads events from `readEvents(ro)` (stored in the RO's `financial` JSON blob)
- Renders `TimelineEntry` components for each event type (created, status, clock_start, financial, etc.)

### Financial Audit Trail (added Phase 4.3)
- Queries `roFinancialAudit` PocketBase collection filtered by current RO `roId`, sorted newest-first (`-at`)
- Each entry shows: field name (camelCase → Title Case via `formatFieldName`), `from → to` JSON values in monospace, "by" attribution, truncated hash with full hash on `title` hover
- Only renders when entries exist (hidden otherwise)
- Shows `Loader2` spinner while loading

#### Adding a New Data Section to a Tab
The pattern:
1. Add state: `const [data, setData] = useState<Type[]>([])` + `const [loading, setLoading] = useState(false)`
2. Add `useCallback` load function querying PocketBase
3. Add `useEffect` hooked to `activeTab` and `ro`
4. Add conditional render in the tab's content JSX (loading spinner + data display + empty state)
5. Reuse existing imports (Loader2, formatDateTime, etc.)

## Types

- `ROFinancialAuditEntry` in `src/types.ts`:
  ```ts
  interface ROFinancialAuditEntry {
    id: string; roId: string; field: string;
    from: unknown; to: unknown; by: string; at: string;
    prevHash: string; hash: string;
  }
  ```

## Associated Files

- `src/pages/RODetailModal.tsx` — main component
- `src/components/ROForm.tsx` — shared create/edit form (now includes catalog search; see `references/roform-catalog-search.md`)
- `src/types.ts` — type definitions (ROFinancialAuditEntry, ROEvent, RepairOrder, etc.)
- `src/lib/roEvents.ts` — event reading/writing for timeline (readEvents, appendROEvent, clock*, void*)
- `src/lib/format.ts` — formatCurrency, formatDateTime, formatElapsed
- `src/lib/totals.ts` — computeROTotals, roServiceTotal
- `src/lib/technicianData.ts` — parseRepairOrderServices, syncAssignmentsForROServices
- `src/store/settings.ts` — useSettings hook for shop charge/tax rates

## Maintenance Reminders (Phase 4.6)

The Details tab header includes a "Set Reminder" button (BellRing icon) that opens an inline form to create maintenance reminders. See `references/reminders.md` for full details on the reminders feature.

### Quick Reference
- **Button location**: Header button group, after Generate Quote
- **Form**: Inline below header, blue-themed card with mileage/interval/notes fields
- **State**: `showReminderForm`, `reminderMileage`, `reminderInterval`, `reminderNotes`, `savingReminder`
- **Handler**: `handleSaveReminder()` creates record in `reminders` PocketBase collection
- **Dashboard widget**: See `src/pages/Dashboard.tsx` — displays active reminders at top of dashboard