Service Reports

A service report is the post-visit document the customer signs. One report per appointment (so multi-visit jobs produce one report per visit). Workestra auto-creates a draft report the moment a technician marks an appointment completed; the tech then fills in the narrative + photos and the customer signs via a share-token portal.

Lifecycle

Appointment completed
    │
    ▼ (auto-seed, idempotent)
Draft service report
    │
    ▼ (tech fills in)
Narrative + photos attached
    │
    ▼ (customer signs at /portal/fsm/service-report/[token])
Signature captured + PDF rendered
    │
    ▼
Email link to customer

What's auto-populated

When the appointment goes to completed, Workestra creates an fsm_service_reports row pre-linked to the appointment + work order. The tech can then add:

Reports are workspace-scoped (RLS) — no cross-workspace data leakage.

Customer signature

Generate a share token (srp_… prefix) for the report and send the URL to the customer. The portal lives at /portal/fsm/service-report/[token] and renders:

• The tech's narrative
• Attached photos / files
• A signature pad (HTML canvas)
• A typed name field

The customer:

1. Draws their signature on the canvas (mouse, finger, stylus).
2. Types their full name.
3. Clicks Submit signature.

The submission writes back:

• signed_at timestamp
• signed_ip (the request IP, for audit)
• customer_name_typed
• signature_svg — the path data, capped at ~10 KB to defend against pathological input

The portal page then shows a confirmation: "Thank you — your signature has been recorded."

PDF rendering

When the signature is submitted, Workestra fires a fire-and-forget PDF render in the background (Puppeteer + the shared finance_fsm bridge). The customer's "Submit" tap does not block on PDF generation — the response returns immediately, the PDF lands ~3 seconds later in Supabase storage at ws/<workspace>/fsm/service-reports/<id>.pdf.

The PDF includes:

• Workspace name + work order number
• Tech narrative
• List of attached photos / files
• The customer signature (rendered as inline SVG from the captured path)
• Signed by + timestamp
• Customer rating + feedback (when present)

Idempotency

Service reports are one per appointment. Re-running completeAppointment returns the existing report — no duplicates. This matters for:

• Re-tries on flaky networks
• The dispatcher walking back a status (e.g. completed → on_site to record a fix, then completed again)
• AI agents that may call complete_appointment more than once

Signature regeneration overwrites the prior signature — the customer can re-sign if a typo'd name was captured, etc.

Customer rating + feedback

The report carries optional customer_rating (1–5) and customer_feedback (free text). These are not yet captured by the portal signature flow (queued for the next release) but the schema is live — populate via the API today if you need it.

What about multi-visit jobs?

Each visit gets its own service report (one per appointment, not per work order). For a 3-day install:

• Visit 1 report — Day 1's work, signed by whoever was on site that day
• Visit 2 report — Day 2's work, separate signature
• Visit 3 report — final day, signature

This matches what most customer service-history expectations want: a paper trail per visit, not a single rolled-up "the whole project is done" sign-off.

Related

• Appointments — what triggers service report creation
• Customer Portal — what customers see
• Work Orders — the parent contract