# Technician (Mobile) — Developer Handoff

> Handoff pack for **dev-mode v1.0 — Technician (CL-2, new role)**. Built 2026-06-19, mirroring the ANCHOR mobile pack (`staff-court-monitor-mobile/`). Source: `docs/design/SCREEN_LIST.md` TECH block, `docs/design/DESIGN_SYSTEM.md` (§2.4 `wo-*`, §6.22 WorkOrderCard, §7 TECH nav), `docs/dev-mode-v1.0/FOUNDATION_SPEC.md` (§4a WO flow, §5 TECH scoping), `docs/CHANGE_LIST_v1.1.md` (CL-2).
> Persona: **Suresh Kale** · Technician · Game Zone Ahmedabad-1 · Maintenance team · reports to Mahesh Patil (Maintenance TL).
> Surface: **Mobile (Flutter), portrait ~390px.** This pack pairs with `maintenance-tl-web` (the assigner / reviewer).

---

## Who consumes which file

| Role | Primary file | Why |
|---|---|---|
| **Mobile (Flutter) Developer** | `tasks.md` Mobile-FE column → filter `Priority=P0`, sort by Dependencies. Build queue. Pixel target = `screens/*.html` at 390px. | Builds the assign→start→done/return flow from the Flutter design-system; WorkOrderCard + fix-photo gate + reason gate + online-only retry. |
| **Backend Developer** | `tasks.md` Backend column + `api-contract.md` + `FOUNDATION_SPEC §3/§4a`. | The WO transition endpoints; done photo-gate + parent `HELD` release; return → Maintenance TL notify. Shared with `maintenance-tl-web`. |
| **Tester** | `spec.md` acceptance summary + the two `flows/`. | Mobile `integration_test`: done photo-gate, return reason-gate, no-approve, assignee scope (403), parent-release on last WO. |
| **Web Frontend Developer** | **N/A for this slot** (mobile-primary surface). The thin web read-only fallback is a P2 secondary surface, not built here. | — |

---

## Definition of Done for the Technician slot

The slot ships when all P0 behaviours in `spec.md` pass in a UAT build, evidenced by:

1. **Login → role-resolve:** login routes to Technician Home via `GET /me`; nav (5 bottom-nav slots) + permissions come from the server — **no hardcoded role logic** in the app.
2. **My-WO integrity:** `TECH-WO-TODAY` shows exactly the WOs **assigned to Suresh** in his Game Zone, with the correct `wo-*` state chip + SLA/age + source checklist + ride; nothing assigned to others leaks.
3. **WorkOrderCard (DESIGN_SYSTEM §6.22):** source checklist + ride + A-item + `StatusBadge wo=…` + age/SLA chip; tap → detail.
4. **Detail + Start:** `TECH-WO-DETAIL` shows the source A-item, issue photos, instructions, and the WO timeline (§6.14 WO variant); **Start work** transitions `ASSIGNED → IN_PROGRESS` (`/start`, If-Match, audit).
5. **Done photo-gate (UI + server):** Done is blocked client-side AND rejected server-side (422) unless ≥1 `WorkOrderPhoto` (`kind: COMPLETION`) exists; the fix photo is a multipart upload to **local-disk storage**; thumbnail + remove work; camera FAB present.
6. **Done closes at maintenance + parent release:** on success WO → `DONE`, `closedAt` set; the action does **not** notify the Store Manager; when it's the last open WO the parent `ChecklistInstance` releases from `HELD` and resumes the cascade.
7. **Return reason-gate + routing:** Return is blocked unless a non-empty reason is present (UI + server 422); on success WO → `RETURNED`, **Maintenance TL notified**, routed back to the Maintenance TL (never the SM directly).
8. **No approve / no route / no outsource:** no such affordance exists anywhere in the app; the resolver denies those endpoints to TECH (403).
9. **Profile:** `SH-PROFILE` shows role / team / reports-to / skills + logout.
10. **States:** loading (skeleton), empty (nothing-assigned), error+retry, **offline online-only retry preserving the in-memory draft**, 403 (out-of-scope/unassigned), 401 (session expired), locked (login) all render and are reachable.
11. **Chrome + scope + concurrency:** navy top app bar + Game-Zone scope strip + 5-slot bottom nav + camera FAB on Done, matching `DESIGN_SYSTEM §8.2`; no cross-Game-Zone / cross-assignee data leak; every transition `If-Match`-guarded (409 on stale); CI Dart-model drift gate green.

P1 items are nice-to-have for the slot; out-of-slot items (approve/verify, route, assign/reassign, outsource, checklist filling, reports, templates) are explicitly not here.

---

## Slot scope at a glance

- **7 screen mockups** (login, dashboard, work-orders, detail, done, return, profile) · **7 state variants** · **3 bottom-sheets** = **17 HTML artifacts** (PNG render is a later step).
- Endpoints consumed: auth (login/refresh/logout/forgot/reset), `/me`, my dashboard, my work-orders, WO detail, start/done/return transitions, fix-photo upload, notifications, device register.
- **Pairs with `maintenance-tl-web`:** the Maintenance TL assigns/reviews; the Technician starts/dones/returns. The WorkOrder entity + state machine + photo endpoint are **Wave-0 / Foundation** (shared).

## Blocking questions / decisions before build

- [ ] **WO SLA source:** is `dueAt` per-priority (normal/high) set at routing time, or a fixed default? Spec assumes a per-priority default, overrideable by the Maintenance TL at assign.
- [ ] **Fix-photo count:** exactly 1 fix photo required, or a minimum per WO? Spec assumes ≥1 per WO (mirrors §4a completion-photo gate).
- [ ] **Return → re-assign target:** on re-assign after a return, does it default back to the same Technician or go to the Maintenance TL's picker? Spec assumes the Maintenance TL chooses (`MTL-WO-REVIEW`).
- [ ] **Start mandatory before Done?** can a Technician go `ASSIGNED → DONE` directly, or must he `Start` first? Spec assumes Start is required (`ASSIGNED → IN_PROGRESS → DONE`).
- [ ] **Parent-release timing:** is the `HELD → TL_APPROVED` resume immediate on the last WO close, or does it re-enter at the TL verify step? Spec assumes resume at the TL step (`FOUNDATION_SPEC §4`).
- [ ] **FCM on iOS:** confirm APNs cert/key provisioning for the unified app before the assign/return notification touchpoints are testable end-to-end.
- [ ] **Web read-only fallback:** confirm it's P2 (not built in this slot), reusing the same 5 destinations as a minimal left rail.

---

## File references
- Pack root: `docs/design/dev-mode-v1.0/technician-mobile/`
- Screens: `screens/*.html` · States: `states/*.html` · Sheets: `bottom-sheets/*.html`
- Spec: `spec.md` · API: `api-contract.md` · Handoffs: `HANDOFFS.md` · Flows: `flows/*.md`
- Anchor mirrored: `docs/design/dev-mode-v1.0/staff-court-monitor-mobile/`
- Upstream pack: `docs/design/dev-mode-v1.0/maintenance-tl-web/`
- Foundation: `docs/dev-mode-v1.0/FOUNDATION_SPEC.md` (§4a) · Change list: `docs/CHANGE_LIST_v1.1.md` (CL-2)
- Project plan: `docs/PROJECT_PLAN.md` · Design system: `docs/design/DESIGN_SYSTEM.md`
