# Maintenance Team Leader (Web) — Dev-mode v1.0 design pack

> **Change List v1.1 role pack (CL-2) — mirrors the Operation Head web pack** (`operation-head-web/`) file-for-file in structure, fidelity, and visual style. Built 2026-06-19.
> This is the **maintenance branch of the cascade**: it *receives* A-item work-orders routed by the operations Team Leader, assigns them to Technicians, reviews the result, and escalates **only** outsource cases to the Store Manager. Internal fixes close here.
> **Persona:** **Vikram Rana** · Maintenance Team Leader (`MTL`) · level 3 (reports to the Store Manager, alongside the operations Team Leader) · **scoped to ONE Game Zone** (Ahmedabad-1). Heads the maintenance team of Technicians.
> **Platform:** **Web (Next.js admin panel) — desktop 1440×900 baseline.** Web is this role's *primary* surface (`SCREEN_LIST` surface key = W). A thin mobile companion mirrors the queue + review actions for on-floor use, but is NOT this pack's pixel target.
> **Chrome:** Maniax web shell per `DESIGN_SYSTEM §8.1` — **240px navy sidebar** (wordmark lockup → 2 nav groups → utility cluster → user chip) + **64px sticky topbar** with a **non-interactive branch badge** (`Game Zone · Ahmedabad-1`, like SM/TL — NOT the OH selector).

---

## What's in this pack

| File / folder | What |
|---|---|
| `README.md` | You are here — slot scope, persona, sidebar, topbar branch badge, hard constraints, out-of-slot. |
| `SCREENS.md` | Full web screen inventory (the FE burn-down checklist) with states/modals per screen. |
| `spec.md` | Per-screen acceptance detail (Given/When/Then) — assign/review/close-internal, outsource-only-reaches-SM, Technician-done-photo-gated, parent-checklist-HELD. |
| `api-contract.md` | Every endpoint this role consumes (`Method \| Path \| Roles \| Body \| Returns`) — the WO endpoints from `FOUNDATION_SPEC §4a`. |
| `HANDOFFS.md` | Cross-role touchpoints — receives routed A-items from operations TL `TL-CHK-VERIFY`; assigns to `technician-mobile`; escalates to `SM-WO-OUTSOURCE`; releasing the last WO un-HOLDs the checklist back into the TL cascade. |
| `flows/` | `route-to-fix-to-close.md`, `return-and-outsource.md` — multi-step walkthroughs. |
| `screens/` | Self-contained HTML mockups (web 1440×900) — the pixel target. |
| `states/` | loading / empty / error / 403 / 401-session-expired / no-results state variants. |
| `modals/` | assign-technician · escalate-outsource-confirm · photo-lightbox · reassign-confirm (web uses **modals/drawers**, NOT bottom-sheets). |
| `handoff/README.md` | Definition of Done + blocking questions for this slot. |
| `handoff/tasks.md` | Task rows: Screen ID, file, states/modals, dependencies, Web-FE + Backend tasks, priority. |

## How to read this pack

1. Start with **`SCREENS.md`** — the bird's-eye of the 7 MTL screens (+ shared auth entry + profile).
2. Use **`handoff/README.md`** DoD as your tick-list.
3. For each screen, read its **`spec.md`** section + the relevant **`flows/`** walkthrough + the **`api-contract.md`** rows.
4. Use **`HANDOFFS.md`** when wiring the route-in / assign-out / outsource / un-HOLD touchpoints (don't reinvent the contract — it lives in `FOUNDATION_SPEC §4 / §4a`).
5. Open any `screens/*.html` in a browser at 1440px width to see the visual contract.

## Sidebar (web, data-driven — `DESIGN_SYSTEM §2.6 + §7`)

Fixed **240px**, bg `brand-navy`, white text, `brand-light-blue` group labels, **orange active accent** (3px left-edge bar + orange icon/label). Wordmark lockup top (AIR in orange / MANIAX in white). **5 nav items in 2 groups** (+ utility cluster). Utility cluster (Notifications · Profile · Settings · Logout) + user chip pinned at the bottom of every screen.

| Group | Item | Lucide | Target screen |
|---|---|---|---|
| OVERVIEW | Dashboard | `layout-dashboard` | `MTL-DASH` |
| OPERATIONS | Work-Order Queue | `wrench` | `MTL-WO-QUEUE` (→ `MTL-WO-DETAIL` / `MTL-WO-ASSIGN` / `MTL-WO-REVIEW`) |
| OPERATIONS | Assign | `user-plus` | `MTL-WO-ASSIGN` |
| OPERATIONS | Escalate / Outsource | `arrow-up-circle` | `MTL-WO-ESCALATE` (→ `SM-WO-OUTSOURCE`) |
| PEOPLE | Maintenance Team | `users` | `MTL-TEAM` |

> The **Game-Zone scope lives in the topbar, not the nav** (`DESIGN_SYSTEM §6.3 / §7`). The MTL gets a **non-interactive branch badge** (`🏢 Game Zone · Ahmedabad-1`), exactly like SM/TL — there is no dropdown / no cross-GZ switch. The MTL never sees other branches.

## Topbar — branch badge (MTL-specific)

64px sticky, `surface` bg + `shadow-sm` bottom. Breadcrumb left · global search (WO#) center · **branch badge** + bell + profile right.
- The badge reads `🏢 Game Zone · Ahmedabad-1` and is **read-only** (no caret, no dropdown) — it is a scope *indicator*, not a selector.
- This matches SM/TL chrome. Only the **OH** gets the interactive Game-Zone selector (their pack).

## Hard constraints (re-affirmed)

- **Web desktop only.** 1440×900 baseline. Desktop **modals + right-side panels** (NOT mobile bottom-sheets). Navy 240px sidebar, 64px topbar.
- **Design tokens:** Maniax palette (`#F58220` orange / `#ED1C24` red-orange / `#2E6DB4` blue / `#16284A` navy / `#7FB2E5` light-blue), **DM Sans**, **navy-on-orange** primary buttons, light-blue as fill-only. Per `DESIGN_SYSTEM.md`.
- **Work-Order state colors (locked, `DESIGN_SYSTEM §2.4`):** open `#94A3B8` · routed `#7FB2E5` · assigned `#2E6DB4` · in-progress `#C2410C` · returned `#E0860B` · done `#1E9E5A` · outsourced `#16284A` · overdue solid `#ED1C24`. Held source checklist `#C2410C`. Status by label+icon+color, never color alone.
- **Only OUTSOURCED reaches the SM (CL-2, locked):** internally-fixed actions **close at the maintenance level** (`wo-done`); the only WO state that escalates to the Store Manager is `wo-outsourced`. `DONE` never notifies the SM.
- **Technician Done is photo-gated (§4a):** a Technician cannot mark a WO Done without ≥1 fix photo (`WorkOrderPhoto`). The MTL views the fix photo on review; the MTL itself does not upload photos.
- **Single-track hold (CL-2):** the parent inspection checklist sits in **HELD** while any of its A-item WOs is open; it **cannot reach Done** until every WO is `DONE`/`OUTSOURCED`. Closing the **last** WO un-HOLDs it and resumes the TL→SM→OH cascade.
- **One WO per A-item:** `WorkOrder @@unique(responseId)` — routing an A-response is idempotent. The MTL queue is a list of these WOs.
- **Dynamic RBAC.** Sidebar + permissions come from `GET /me`; no hardcoded role logic. The assign/review/outsource affordances render because the resolver grants the MTL those permissions at `own` scope — not because the code checks `role === 'MTL'`.
- **Own-GZ scope (§5):** the MTL is scoped to its own Game Zone; the resolver server-forces `gameZoneId = me.gameZoneId` on every WO read/write. No cross-GZ visibility.
- **Local-disk photo storage** on the VPS — the lightbox loads `WorkOrderPhoto.url` / `Photo.url` from local disk, no cloud bucket pickers.
- **Concurrency:** WO mutations carry `If-Match: <workOrder.version>` → **409** if the state moved (e.g. the tech already returned it). The UI refetches the timeline.
- **English-only, single-tenant.** No language/tenant/theme switcher beside the wordmark.

## What's NOT in this slot

- **Routing A-items** — the **operations Team Leader** routes A-items to maintenance (`TL-CHK-VERIFY` → "Route to Maintenance"). The MTL *receives* already-routed WOs; it does not create them.
- **Doing the physical fix** — the **Technician** starts / marks-done (+photo) / returns. Those screens live in `technician-mobile`. The MTL assigns + reviews + decides only.
- **Outsourcing decisions / vendor management** — the MTL *escalates* an outsource report; the **Store Manager** acts on it (`SM-WO-OUTSOURCE`). Vendor/PO handling is SM-side (and largely P2+).
- **Filling / approving inspection checklists** — the MTL is not in the G/A approval cascade (that's TL→SM→OH). The MTL only handles the maintenance branch of A-items.
- **Roster / users / Game-Zone CRUD** — none. The MTL's only "people" surface is the read-only `MTL-TEAM` load view; staffing the maintenance team is SM/OH onboarding.
- **The mobile companion** (on-floor queue + review) is a P2 secondary surface; this pack is the web pixel target.
- **Rotation, Capacity, Training, Events, School Visits** — out of Phase 1 (P3–P5).

---

## File references

- Pack root: `docs/design/dev-mode-v1.0/maintenance-tl-web/`
- Mirrored reference: `docs/design/dev-mode-v1.0/operation-head-web/`
- Upstream pack (routes in): `docs/design/dev-mode-v1.0/` operations-TL pack (`TL-CHK-VERIFY`)
- Downstream packs: `technician-mobile` (assign-out), SM pack `SM-WO-OUTSOURCE` (outsource-out)
- Foundation: `docs/dev-mode-v1.0/FOUNDATION_SPEC.md` (§4 cascade + single-track hold, §4a Work-Order flow + endpoints, §5 MTL scoping, WorkOrder/WorkOrderEvent/WorkOrderPhoto models)
- Change list: `docs/CHANGE_LIST_v1.1.md` (CL-2) · Screen list: `docs/design/SCREEN_LIST.md` (MTL block) · Design system: `docs/design/DESIGN_SYSTEM.md` (§2.4 `wo-*` + `st-held`, §6.14 ApprovalTimeline workorder variant, §6.22 WorkOrderCard, §7 MTL sidebar)
