# Flow — Can't Fix Internally → Return with Reason (Technician)

> Persona: **Suresh Kale** (TECH), Maintenance team, Game Zone Ahmedabad-1, reports to **Mahesh Patil (Maintenance TL)**. Source: `CHANGE_LIST_v1.1.md` CL-2 + `FOUNDATION_SPEC §4a`. Screens: `TECH-WO-DETAIL` → `TECH-WO-RETURN`. Sheet: `bottom-sheets/return-reason.html`.

---

## Preconditions
- Suresh has an `ASSIGNED` (or already `IN_PROGRESS`) work-order — e.g. **WO-1044 · Toddler Zone · Soft-play seam loose** — and on inspecting it on the floor finds it **can't be fixed on-site** (needs a replacement panel / specialist / part not in stock).

## Steps

1. **Open the work-order.** From `TECH-WO-TODAY` or `TECH-WO-DETAIL`, Suresh reviews the source A-item + issue photos and decides this is beyond an on-site repair.

2. **Choose Return.** He taps **Return** (action bar on `TECH-WO-DETAIL`, or the Return slot) → opens `TECH-WO-RETURN` (or the **return-reason bottom sheet**, `return-reason.html`).

3. **Give a reason — required.** Suresh picks a quick-reason chip ("Needs specialist / vendor") and/or types the detail: *"Foam backing under the seam is split — needs a replacement soft-play panel; no stock on-site, vendor order required."* He may attach an **optional** photo of the blocker.
   - **Gate:** the **Return** button stays disabled until a non-empty reason is present (UI **and** server reject an empty reason).

4. **Submit the return.** Suresh taps **Return to Maintenance TL** → `PATCH /work-orders/:id/return { reason }` (`If-Match`) → WO state `IN_PROGRESS → RETURNED`, `returnReason` stored, a `WorkOrderEvent` written, and the **Maintenance TL (Mahesh) is notified** (FCM + in-app). The WO appears on his `MTL-WO-REVIEW` queue.

5. **Hand-off completes.** The WO is now **back with the Maintenance TL** — he will either **re-assign** it (`RETURNED → ASSIGNED`, possibly to Suresh again or another technician) or **escalate / outsource** it to the Store Manager (`RETURNED → OUTSOURCED` — the only state that reaches the SM). The source checklist **stays `HELD`** until the WO finally closes.

## Rules enforced in this flow
- **A reason is mandatory** to return — no reason, no return (UI **and** server `422`).
- **Return goes UP to the Maintenance TL, never to the Store Manager directly** — only the Maintenance TL can outsource/escalate (CL-2 locked rule).
- **No approval / no close-out** — the Technician cannot approve a checklist, outsource, or close the parent; he only returns with a reason.
- **Scope + concurrency:** own assigned WOs only (`403` otherwise); `If-Match` → `409` if the WO was reassigned meanwhile.
- **Online-only:** returning records server-side; offline → online-only retry (`states/offline.html`), reason held on device.

## Result
- WO-1044 is `RETURNED` with Suresh's reason + audit trail; it lands on the Maintenance TL's review queue for re-assign or outsource; the parent checklist remains Held until it closes.
