# Specification: 008-scheduling-module-rewrite

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-02-19 |
| **Current Phase** | Implementation — Phase 4 Complete (12 tests, 6 files) |
| **Last Updated** | 2026-02-19 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | 16 features across MoSCoW categories, 15 tracking events |
| solution-design.md | completed | 5 ADRs, full directory map, runtime flows, test specs |
| implementation-plan.md | completed | 8 phases, ~200 tasks, TDD structure, full PRD traceability, Codex-reviewed |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-19 | Full rewrite chosen over fix/expand | Existing module was built speculatively; needs ground-up rebuild against actual backend API |
| 2026-02-19 | Full spec workflow (PRD -> SDD -> PLAN) | Complex rewrite with 50+ endpoints warrants thorough specification |
| 2026-02-19 | PRD completed | 16 features (10 Must + 4 Should + 2 Could), 4 user journeys, 15 analytics events, competitive analysis |
| 2026-02-19 | Employee self-service excluded | Clock in/out, time-off submission, availability, shift swaps are Team App features, not Manager App |
| 2026-02-19 | Denial notes optional | Backend accepts both; forcing notes would slow workflow |
| 2026-02-19 | PRD reviewed by Codex | 3 blockers found: missing API mapping, unresolved entitlements, missing permissions matrix |
| 2026-02-19 | All 3 blockers resolved | Added Permissions Matrix, Dependencies section, API Endpoint Mapping, resolved store entitlement question |
| 2026-02-19 | 5 important items addressed | Clarified ambiguous acceptance criteria, added edge cases for Shift CRUD/Copy/Publish/Labor, clarified owner persona, added dependencies, added metric baselines |
| 2026-02-19 | Store entitlement resolved | Schedule tab hidden when hasSchedulingAccess is false; deep links redirect to "not available" screen |
| 2026-02-19 | Owner = Manager for scheduling | No owner-exclusive features; owners use store switcher for multi-store oversight |
| 2026-02-19 | Notification prefs per-user per-store | Each store has independent preference settings for each user |
| 2026-02-19 | SDD completed | Validate-and-enhance strategy; 5 ADRs; ~90% existing code reuse; gap-fill for 6 new screens/widgets |
| 2026-02-19 | All 5 ADRs confirmed | ADR-1: Validate-and-enhance, ADR-2: New screen files, ADR-3: fl_chart, ADR-4: Additive entities, ADR-5: Optimistic UI |
| 2026-02-19 | SDD reviewed by Codex | 4 blockers + 4 important items found |
| 2026-02-19 | All 8 Codex findings resolved | B1: Version is correct (PRD stale). B2: Added copyWeekSchedule + batch prefs methods. B3: F15/F16 explicitly deferred (ADR-6). B4: Added batch notification update. I1: Status colors aligned to PRD. I2: Shift deletion reason added. I3: Request history/sorting specified. I4: Analytics event mapping table added |
| 2026-02-19 | PLAN completed | 8 phases with TDD structure. Deep codebase discovery: 65% existing code, 35% gap-fill. P1 (data foundation) → P2-P6 (parallel features) → P7 (tests) → P8 (integration/E2E) |
| 2026-02-19 | Codebase inventory confirmed | 14 providers, 12 screens, 9 widgets, 11 models/entities, 21 datasource methods all exist. Missing: 4 screens, 5 widgets, 1 provider, 5 models, 9 repo methods |
| 2026-02-19 | Phase parallelism designed | P2 (schedule views), P4 (clock override), P5 (notification prefs), P6 (screen hardening) can execute in parallel after P1 completes |
| 2026-02-19 | PLAN reviewed by Codex | 0 blockers, 8 important, 3 enhancements found |
| 2026-02-19 | All 11 Codex findings resolved | I1: Repo method count 8→9 (added updateNotificationPreferencesBatch). I2: Added F13 implementation tasks (T6.5). I3: Added F1 store switching + F3 batch limits/Select All/Clear tasks. I4: Analytics events distributed to feature phases (P2-P6). I5: Shift card styling moved from P3→P2 (resolved circular dependency). I6: Gap analysis aligned to SDD ~90%. I7: Testing gotchas (Future.microtask, overnight shifts, DST) added to P7. I8: Prime/Validate sections added to P7/P8. E1: Provider reference corrected (weekly_schedule_provider, not my_schedule). E2: Entity count 5→6. E3: F15/F16 no-op verification explicit |
| 2026-02-19 | Phase 1 implemented | Data layer foundation: 99 tests, 9 new models, 4 new entities, 9 repo methods, 6 mapper files |
| 2026-02-19 | Phase 2 implemented | Schedule view screens: 67 tests, 7 new files, 5 modified. Codex review: 6 fixes applied (late init crash, empty state CTA, copy week guards, daily scroll fix, analytics wiring) |
| 2026-02-19 | Phase 3 implemented | Shift management enhancements: 19 tests, 1 new test file, 2 modified. Codex review: 4 fixes applied (overnight banner logic, provider-level delete reason guard, duplicate conflicts dialog, save button disabled for past shifts) |
| 2026-02-19 | Phase 4 implemented | Clock Override screen (F9): 12 tests, 1 new screen, 1 new test file, 4 modified. Codex review: 4 fixes applied (SnackBar pop ordering, cached employee state, analytics event wiring, future timestamp test) |

## Context

Full rewrite of the scheduling module from the ground up. The backend already has 50+ scheduling API endpoints fully implemented and ready. The current Flutter scheduling module was built speculatively and needs a ground-up rebuild using actual backend API documentation as the source of truth.

**Key facts:**
- Backend API base URL: `/api/mobile/scheduling/{typeNum}/...`
- App uses unified JWT auth (Spec 003) - no separate scheduling login
- Live app is for MANAGERS (Owner/Manager roles)
- 11 API categories: Auth, Schedule Viewing, Clock In/Out, Availability, Time Off, Open Shifts, Shift Swaps, Notification Preferences, Manager Dashboard, Manager Requests, Manager Shift Management
- Replaces the existing code from Spec 002 (manager-scheduling-features)

**Reference:**
- Backend API docs: `../buyerkiosk-team/docs/backend-api-updates.md`
- Current scheduling code: `lib/presentation/providers/scheduling/`, `lib/data/datasources/scheduling/`, etc.
- Unified auth spec: `docs/specs/003-unified-jwt-auth/`
- OpenAPI spec: `docs/api/mobile-scheduling-openapi.yaml`

---
*This file is managed by the specification-management skill.*