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

RO-Quote Sync Mechanism

Overview

When a quote is generated from a Repair Order (RO), approved services on the quote sync back to the RO's services array on Save. This is the bidirectional RO ↔ Quote link.

Key Files

File	Role
src/components/quoteGenerator/QuoteSummary.tsx	Sync logic in handleSave (lines 146-194) and ensureShareToken (lines ~270-303)
src/pages/QuoteGenerator.tsx	Sets repairOriginId from data.repairOrderId on edit load (line ~524) and from fromRO URL param (line ~103)

Data Flow

1. New Quote from RO

• User clicks "Generate Quote" from RO → navigates to /quote?fromRO=RO_ID&name=...
• fromRO effect in QuoteGenerator.tsx loads the RO, sets repairOriginId = ro.id
• User adds/approves services, clicks Save
• handleSave in QuoteSummary.tsx creates the quote record with repairOrderId: repairOriginId (line 125)
• Sync block runs: filters services.filter(s => s.approved), loads current RO services, merges (by service name — avoids duplicates), updates RO with JSON.stringify(roServices)
• Toast: "Synced N approved service(s) to RO"

2. Editing Existing Quote from RO

• Quote has repairOrderId set in PocketBase
• Edit-load effect restores setRepairOriginId(data.repairOrderId) (QuoteGenerator.tsx line ~524)
• User approves more services, clicks Save
• Sync block runs same as above

3. Share with Customer (ensureShareToken)

• New quote: Creates the quote record, syncs approved services to RO, then creates share token. Same merge logic as handleSave.
• Editing existing quote (editId set): The if (!quoteId) block is SKIPPED — no sync on share of existing quotes. The quote is read from PB, share token created/returned. This is a known gap.

Critical Conditions

The sync block only runs when BOTH are true:

1. repairOriginId is set (non-null)
2. services.filter(s => s.approved).length > 0

Why Sync Might Not Run

Cause	Symptom
Quote's repairOrderId is null in PB	repairOriginId stays null; entire sync block skipped silently
No services approved	Sync block skipped; no toast shown (by design)
RO load fails (permissions/network)	Falls to catch block → error toast: "Sync to RO failed: ..."
Schema validation fails before sync	Error toast from Zod; sync never reached

Most common cause: The quote was created before the repairOrderId field existed. Check the quote in PocketBase admin — if repairOrderId is empty, the quote has no RO link. Generate a new quote from the RO to get the field populated.

PocketBase Fields

• quotes.repairOrderId — relation field linking quote to its originating RO. Set at quote creation (line 125 in handleSave).
• repairOrders.services — stored as JSON.stringify(array) (plain JSON text field, NOT a PocketBase relation).

Sync Merge Logic

Services are merged by name (not ID):

• If RO already has a service with the same name → update it (preserving status if already set)
• If name not found → append new service

Each synced service gets: id: 'qs-{quoteService.id}', name, description, laborHours (from price/rate), laborRate, partsCost: 0, total: price, status: 'pending'

Testing the Sync

1. Create an RO owned by the current user
2. Generate a quote from it (/quote?fromRO=RO_ID)
3. Add and approve services
4. Click Save
5. Check the RO in PocketBase — services should contain the approved services
6. Verify via API: GET /api/collections/repairOrders/records/RO_ID

Previous Investigation

• The sync code was verified working end-to-end (2026-07-08)
• All debug [SPQ-DEBUG] console.logs have been removed
• The sync runs in both handleSave and ensureShareToken (new-quote path only)
• RO services field is written as JSON.stringify(roServices) — always produces valid JSON arrays