# Operation Head (Web) — Developer Handoff

> Handoff pack for **dev-mode v1.0 Step 3b — Operation Head (web)**. Built 2026-06-18; **Change List v1.1 (CL-1 + CL-2) applied 2026-06-19**. Mirrors the ANCHOR pack (`staff-court-monitor-mobile/`) file-for-file. Source of truth: `docs/design/SCREEN_LIST.md` OH block (22 screens), `docs/design/DESIGN_SYSTEM.md` (§6.2 sidebar, §6.3 topbar, §6.21 ChecklistBuilder, §6.22 WorkOrderCard, §8.1 web shell), `docs/dev-mode-v1.0/FOUNDATION_SPEC.md`.
> Persona: **Anjali Desai** · Operation Head · sees ALL Game Zones · terminal approver (level 3) · full dynamic-RBAC access.
> Surface: **Web (Next.js), desktop 1440×900.** OH is the **top-authority web counterpart** of the anchor; the Store Manager web pack is largely a scope-down of this one.

---

## Who consumes which file

| Role | Primary file | Why |
|---|---|---|
| **Web Frontend (Next.js) Developer** | `tasks.md` Web-FE column → filter `Priority=P0`, sort by Dependencies. Build queue. Pixel target = `screens/*.html` at 1440px. | Builds the navy 240px sidebar + topbar Game-Zone selector shell, the dashboard/overview DataTables, the final-approval drawer, and the live RBAC matrix from the web design-system. |
| **Backend Developer** | `tasks.md` Backend column + `api-contract.md` + `FOUNDATION_SPEC §4/§5`. | The endpoints in `api-contract.md`; the **terminal approve** + send-back-to-filler step, the derived-Pending aggregation, the RBAC matrix read/write. |
| **Tester** | `spec.md` acceptance summary + the two `flows/`. | Web e2e: terminal approve → Done, send-back-to-filler + restart-from-TL, derived-Pending across frequencies, live RBAC-matrix edit, cross-GZ scope. |
| **Mobile (Flutter) Developer** | **N/A for this slot** (web-primary surface). The OH mobile companion (on-floor approvals) is a P2 secondary surface, not built here. | — |

---

## Definition of Done for the Operation Head (web) 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 the OH Dashboard via `GET /me`; the **240px navy sidebar** (8 items, 3 groups) + permissions come from the server — **no hardcoded role logic**; active item = 3px orange left bar.
2. **Topbar Game-Zone selector:** `Game Zone · All ▾` aggregates across all branches; switching to one branch re-scopes every `[GZ: all]` view; OH never loses cross-GZ rights (scope = convenience, not a security boundary).
3. **Dashboard org-wide health:** `OH-DASH` shows the Pending / Overdue / Done / Compliance% / Roster-gap KPIs + per-Game-Zone tiles; Pending is segmentable by frequency; tile click drills into a branch; Pending KPI matches the overview's derived query.
4. **Derived Pending (§9 #5):** `OH-CHK-OVERVIEW` renders **Pending** (amber) for anything not yet `OH_APPROVED` — daily/weekly/monthly/quarterly/yearly alike — via the shared `renderStatusForViewer()`; the Overdue tab is solid-red; Pending is never stored.
5. **Final approval = Done:** `OH-CHK-APPROVE` Approve (green) → `OH_APPROVED`/Done; the instance drops off every Pending list; `If-Match` → 409 on stale; only the OH step (`SM_APPROVED`) is approvable.
6. **Send-back to filler + restart-from-TL (§9 #3 / #8):** Send-back (red-orange) requires a reason (422 if blank) → `SENT_BACK`, returns to the **original filler** (not SM); on re-submit the cascade restarts from TL.
7. **Evidence viewer (read-only, §4a / §9 #9):** the approval drawer + Negative report show completion + per-A-item photos in a lightbox (local-disk URLs); item time + initials render **read-only** (server-stamped); OH edits none of them.
8. **Game Zone management:** `OH-GZ-*` enforces **one Store Manager per GZ** (assign/reassign modals); `OH-RIDE-MASTER` enforces ride-code-unique-within-GZ; `OH-GZ-DETAIL` tabs (staff/rides/rosters/checklists) are GZ-scoped.
9. **User onboarding + hierarchy:** `OH-USER-NEW` wizard filters reports-to by the §3 hierarchy + Game Zone and multiselects certified rides (the auto-assign gate); `OH-HIER-TREE` renders the org-wide 7-level tree with a per-GZ filter.
10. **Live dynamic RBAC:** `OH-ROLES` edits write `RolePermission` (with `updatedBy`) and take effect on the **next request, no redeploy**; Trainee TL = TL is shown as a note; reset-to-seed works; **no spec'd endpoint hardcodes a role check**.
11. **States + chrome:** loading (skeleton), empty, no-results, error+retry, 401 (session-expired → login), 403 (defensive) all render; navy 240px sidebar + 64px topbar + breadcrumb match `DESIGN_SYSTEM §8.1`; no cross-Game-Zone data leak for lower roles; CI type-drift gate green.

P1 items are nice-to-have for the slot; out-of-slot items (filling, TL/SM approval steps, roster build, **Work-Order route/assign/fix actions**) are explicitly not here. **Template authoring IS now in-slot (CL-1):** OH has full checklist-template CRUD across all GZ (Upload Check List).

---

## Slot scope at a glance

- **24 screen mockups** (login, dashboard, game-zones list/new/edit/detail, ride master, users list/new/edit/detail, roles matrix, hierarchy, roster-all, checklist overview, checklist approve, **upload-checklist + template assign + template edit (CL-1)**, **work-order overview (CL-2)**, positive/negative/overdue reports, profile) · **6 state variants** · **8 modals/drawers** = **38 HTML artifacts** (PNG render is a later step).
- Endpoints consumed: auth, `/me`, OH dashboard aggregate, game-zone CRUD + rides, users CRUD + managers + hierarchy, roles matrix read/write, roster-all (read-only), checklist overview + instance + timeline + **approve/sendback** (terminal), **checklist-template CRUD + assign (CL-1)**, **work-orders read/overview (CL-2, read-only)**, reports (positive/negative/overdue + export), photo viewer.
- **OH is the top-authority web counterpart:** the Store Manager (SM) web pack is a near-clone scoped to one Game Zone (branch badge instead of the selector; `OH-ROLES` read-only for SM; no GZ CRUD; SM approval is level 2, not terminal).

## Blocking questions / decisions before fan-out / build

- [ ] **RBAC matrix endpoints** (`GET /roles/matrix`, `PATCH /roles/:roleId/permissions`, `/roles/matrix/reset`): confirm the contract — the schema exists in `FOUNDATION_SPEC §1` but these read/write endpoints are **not enumerated** there. `OH-ROLES` is blocked on this. (Flagged in `api-contract.md` gap #2.)
- [ ] **`GET /oh/dashboard` aggregate shape:** confirm the per-GZ tile + KPI roll-up response (compliance %, pending-by-frequency, roster gaps). Pure aggregation, no new fields, but the shape must be locked. (gap #1.)
- [ ] **Roster-gap source:** what defines an "unstaffed required ride/shift" gap? There is no `required-coverage` master in the schema. Confirm at the demo whether gaps are computed against a config/rule or only against published-but-unfilled rows. (gap #3 — a genuine design question, not assumed.)
- [ ] **Report export:** confirm the PDF/Excel export endpoint + format contract (server-rendered vs client). Not in `FOUNDATION_SPEC`. (gap #4.)
- [ ] **OH "Done" notification:** does the filler get a "your checklist is Done" notification on OH approval, or is Done only visible by polling `*-CHK-STATUS`? (P1; `HANDOFFS.md`.)
- [ ] **Compliance % definition:** is the dashboard "compliance %" the G-rate of items, the % of checklists fully approved, or % submitted on time? Confirm the metric at the demo before wiring the KPI.
- [ ] **Game-Zone selector "All" performance:** at N branches the all-GZ aggregates (dashboard, overview, reports) need pagination/caching limits confirmed (default 25, max 100 per `FOUNDATION_SPEC §2`).

---

## File references
- Pack root: `docs/design/dev-mode-v1.0/operation-head-web/`
- Screens: `screens/*.html` · States: `states/*.html` · Modals/drawers: `modals/*.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/`
- Foundation: `docs/dev-mode-v1.0/FOUNDATION_SPEC.md` · Dev plan: `docs/dev-mode-v1.0/DEV_EXECUTION_PLAN.md`
- Project plan: `docs/PROJECT_PLAN.md` · Design system: `docs/design/DESIGN_SYSTEM.md` · Workflow: `docs/WORKFLOW_GUIDE.md`
