# Store Manager (Web) — Developer Handoff

> Handoff pack for **dev-mode v1.0 Step 3b — the Store Manager web pack**, mirroring the ANCHOR (`staff-court-monitor-mobile/`) file-for-file. Built 2026-06-18 from the locked design (`docs/design/SCREEN_LIST.md` SM block, `docs/design/DESIGN_SYSTEM.md`, `docs/dev-mode-v1.0/FOUNDATION_SPEC.md`).
> Persona: **Rohit Shah** · Store Manager · Game Zone Ahmedabad-1 · reports to Anjali Mehta (OH). Surface: **Web (Next.js + Tailwind), desktop 1440×900.**

---

## 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 shell (240px navy sidebar + topbar branch badge), DataTables, roster grid + bulk-upload wizard, the SM approval viewer + cascade timeline, reports. |
| **Backend Developer** | `tasks.md` Backend column + `api-contract.md` + `FOUNDATION_SPEC §3/§4/§5`. | Publish→auto-assign trigger; SM-level approve/sendback (OH notify / send-back-to-filler); GZ-scoped lists; bulk-upload validation; reports + export. |
| **Tester** | `spec.md` acceptance summary + the two `flows/`. | Web e2e: publish→auto-assign, SM approve→OH, send-back→filler (restart from TL), GZ-scope 403, bulk-upload validation, derived Pending. |
| **Mobile (Flutter) Developer** | **N/A for this slot** (this is the web-primary surface). The SM mobile companion (on-floor approvals) is a P2 secondary surface, not built here. | — |

---

## Definition of Done for the Store Manager 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 SM Dashboard via `GET /me`; sidebar (**8 items** — Upload Check List replaces Templates per CL-1, plus Outsource Inbox per CL-2) + permissions + the **branch badge** (read-only, Ahmedabad-1) come from the server — **no hardcoded role logic**, **no Game-Zone switcher**.
2. **Game-Zone scoping (§4c, FOUNDATION §5):** every list/read is server-filtered to the SM's Game Zone; an out-of-zone id → 403 (`states/forbidden.html`); no cross-GZ data appears anywhere.
3. **Limited onboard:** `SM-USER-NEW`/`-EDIT` offer only roles **≤ SM** (TL/SCM/MON/CS); Game Zone is server-forced; OH/SM role attempts → 422; reassign-manager confirm works.
4. **Roster builder:** drag/click creates DRAFT `RosterEntry` rows by ride+shift; conflict + gap alerts render; opener toggle sets the 114-pt opener; day/week/month views; leave drives gap recompute.
5. **Bulk upload with validation:** dry-run lists row-level errors (out-of-GZ email, unknown ride, duplicate) in the upload-errors modal; commit is blocked until resolved (or valid-only); a clean commit creates DRAFT entries — never a cross-GZ insert.
6. **Publish → auto-assign:** the publish-confirm modal is explicit about the side effect; `POST /roster/publish` transitions entries + fires auto-assign (idempotent); `ROSTER_PUBLISHED` audit + notifications.
7. **Checklist overview:** DataTable with cascade + `renderStatusForViewer(SM)` Pending; Active/Overdue tabs; filters; drilldown drawer with timeline + photos.
8. **Assign / override:** the assign/override modal creates `ChecklistAssignment` (+ instance) / reassigns a filler within the team; cross-GZ target → 422/403.
9. **SM approval (the 2nd level):** Approve → `SM_APPROVED`, **OH notified**, leaves the SM queue; **Send-back → original filler (not TL)**, reason required (422 if empty), re-fill restarts cascade from TL; the screen is a **photo viewer** (gallery + lightbox) with item time/initials read-only.
10. **Reports:** Positive (all-G), Negative (A items + issue photos + lightbox), Overdue (solid-red badge + escalate indicator), all own-GZ, all with PDF/Excel export.
11. **States:** loading (skeleton), empty/all-clear, error+retry, 403 (out-of-scope), 401 (session expired), locked (login) all render and are reachable; **409** handled on concurrent publish/approve/edit.
12. **Chrome + tokens:** 240px navy sidebar with orange active accent + sticky topbar (search · branch badge · bell · profile) + breadcrumb + 1440 content well, matching `DESIGN_SYSTEM §8.1`; navy-on-orange primary buttons; G green / A red-orange; CI TS-model drift gate green.

13. **CL-1 Upload Check List (own GZ):** SM **authors** check lists via the ChecklistBuilder (Details → Sections&Items → Assign → Review); `gameZoneId` server-forced to own; seeded/global templates read-only; assign maps role/ride/shift → auto-assign; edit is versioned (applies on next auto-assign); cross-GZ → 422/403.
14. **CL-2 Outsource Inbox:** only `OUTSOURCED` work-orders reach SM (own GZ); WO detail shows issue photos + Technician return reason + MTL note + WorkOrder ApprovalTimeline; **Confirm outsource** (required note) notifies the Maintenance TL and keeps the parent checklist **HELD** until every A-item WO closes; SM never assigns a Technician / manages the maintenance queue; non-`OUTSOURCED`/out-of-zone → 403.

P1 items are nice-to-have for the slot; out-of-slot items (filling, TL verify, OH final-approve, Game-Zone/ride master, **the maintenance queue + Technician assignment** [`maintenance-tl-web`/`technician-mobile`], **cross-GZ template authoring** [OH], all-zones views) are explicitly not here.

---

## Slot scope at a glance

- **22 screen mockups** (login + dashboard + users + user-new + user-edit + user-detail + hierarchy + roster + roster-upload + shift-templates + leave + roster-publish + checklist-overview + checklist-assign + checklist-approve + **upload-check-list** + 3 reports + **checklist-tpl-assign** + **checklist-tpl-edit** + **wo-outsource**) · **6 state variants** · **6 modals/drawer** = **34 HTML artifacts** (PNG render is a later step).
- Endpoints consumed: auth, `/me` + dashboard, users (Limited CRUD) + hierarchy + rides, roster build/templates/leave, **bulk upload (dry-run + commit)**, **publish→auto-assign**, checklist overview + assign/override, **SM approve/sendback (level 2)**, photo viewer, **own-GZ check-list CRUD + mappings (CL-1)**, **outsource work-order list/detail/outsource/return (CL-2)**, reports + export, notifications.
- **The manager-web archetype:** the OH pack reuses this shell + DataTable + approval + reports, differing by the **Game-Zone selector** (all) vs **branch badge** (own) and the **final** vs **second** approval level. TL (web) reuses roster + checklist + reports at **team** scope.

## Blocking questions / decisions before fan-out (carried from the anchor + SM-specific)

- [ ] **Ride↔template auto-assign map** (`§9 #2`, `DEV_EXECUTION_PLAN` D4): confirm at the client demo which templates land per ride and which shift role is the 114-pt "opener". The engine is generic; only seed rows are blocked. *(Same blocker as the anchor.)*
- [ ] **Bulk-upload commit mode:** "all-or-nothing" (block on any error) vs "commit valid rows only" — spec exposes both; which is the default the client wants?
- [ ] **Roster builder input:** drag-drop is the design contract; is a click-to-assign fallback acceptable for v1.0 (same `RosterEntry` output) to de-risk the FE?
- [ ] **Report export engine:** server-rendered PDF/Excel (assumed) vs client-side — affects the BE `/reports/:type/export` task. Confirm PDF library (e.g. Puppeteer/`pdfkit`) + Excel (`exceljs`).
- [ ] **Re-publish semantics on changed rosters:** confirm idempotent upsert keeps existing in-progress instances and only adds new ones (assumed) — no wipe of filled work on re-publish.
- [ ] **SM dashboard "compliance %"** definition: % of due instances OH-approved by EOD vs % submitted — confirm the metric with the client.
- [ ] **Web push (FCM web)**: is the SM topbar bell in-app only for Phase 1, or also web push? (Anchor decision #10 is iOS/APNs; web push is the SM-side analogue.)

---

## File references
- Pack root: `docs/design/dev-mode-v1.0/store-manager-web/`
- Screens: `screens/*.html` · States: `states/*.html` · Modals: `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`
