# Specification: 002-manager-scheduling-features

## Status

| Field | Value |
|-------|-------|
| **Created** | 2025-12-30 |
| **Current Phase** | PLAN Completed - Ready for Implementation |
| **Last Updated** | 2025-12-30 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | 14 features defined, all questions resolved, Codex reviewed |
| solution-design.md | completed | All 6 ADRs confirmed, Codex reviewed & enhanced |
| implementation-plan.md | completed | 11 phases, 14 PRD features mapped, TDD structure | |

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

## PRD Review (2025-12-30)

### Review Process
- **Reviewer:** Codex (o3 model)
- **Completion Date:** 2025-12-30

### Key Findings from Codex Review

**Blockers Resolved:**
1. ✅ Timeline clarification marker removed → ASAP (Q1 2025)
2. ✅ Store access restriction question resolved → Feature flag rollout
3. ✅ Schedule publishing vs Shift CRUD conflict clarified → Same as web rules
4. ✅ Audit trail location permission policy defined → Soft prompt, allow without
5. ✅ Auth backward compatibility contradiction fixed → Clarified server-side behavior
6. ✅ Permission matrix added for role-based access

**Important Improvements Made:**
1. Added baseline metrics to problem statement (4h → 30min target)
2. Defined "late" threshold (>5 minutes after scheduled start)
3. Specified conflict warnings as informational (non-blocking)
4. Added partial failure handling for batch approvals
5. Specified labor cost "not configured" behavior
6. Added comprehensive edge cases (store switching, timezone, pagination, location denied)
7. Added UX state handling requirements (loading, empty, error, offline)
8. Added explicit dependencies (location, biometrics, secure storage, API SLA)
9. Added migration-specific KPIs (JWT migration rate, biometric opt-in)

### User Decisions Made
| Question | Decision | Rationale |
|----------|----------|-----------|
| Mobile shift edits behavior | Same as web | Consistency with existing workflow |
| Location permission denied | Allow without location | UX over strict audit compliance |
| Store access restrictions | Feature flag rollout | Gradual rollout reduces risk |
| Timeline | ASAP (Q1 2025) | Business priority |

### Changes Made to PRD
- Added Permission Matrix section with role capabilities
- Added UX State Handling section
- Added Dependencies section with specific packages and SLAs
- Enhanced edge cases (7 new scenarios)
- Resolved all open questions (8/8 now resolved)
- Added migration KPIs to success metrics
- Clarified acceptance criteria for measurability

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2025-12-30 | Full JWT migration | Replace API key auth entirely with email/password login for cleaner architecture |
| 2025-12-30 | Biometric + remember me | Face ID/Touch ID after first login for faster access |
| 2025-12-30 | Store picker after login | Login once, select store, can switch - matches multi-store owner workflow |
| 2025-12-30 | Manager-only focus | Employee self-service (swaps, time-off requests) handled by Team app |
| 2025-12-30 | No clock in/out | Time clock with GPS lives in Team app |
| 2025-12-30 | No schedule publishing | Publishing remains web-only feature |
| 2025-12-30 | Full shift CRUD | Managers can create/edit/delete shifts from mobile |
| 2025-12-30 | Batch approvals | Support approving/denying multiple requests at once |
| 2025-12-30 | Self-approval per store | Store setting controls whether managers can approve own time-off |
| 2025-12-30 | Immediate API key invalidation | Old API key stops working once user logs in with JWT |
| 2025-12-30 | Full audit trail | Track device ID, location, timestamp on all approval actions |
| 2025-12-30 | Batch limit of 10 | Maximum 10 requests per batch approval action |

## SDD Review (2025-12-30)

### Review Process
- **Reviewer:** Codex (o3 model)
- **Completion Date:** 2025-12-30

### Key Findings from Codex Review

**Blockers Resolved:**
1. ✅ Auth strategy contradiction fixed → Single JWT auth for ALL endpoints post-migration (ADR-1 updated)
2. ✅ Missing PRD features added → Features 11-14 (Request History, Employee Schedule, Conflicts, Quick Actions) now fully designed
3. ✅ Store picker pending count added → `pendingRequestCount` field added to `StoreAccessModel`

**Important Improvements Made:**
1. Added Feature Flag Enforcement section with provider/guard logic
2. Added Analytics & Event Tracking section with 8 event types
3. Added Interface Contracts section with detailed pagination, decision, and batch payloads
4. Added Error Model with unified error codes (AUTH_*, REQUEST_*, VALIDATION_*, etc.)
5. Added Idempotency Strategy for mutations (client UUID, server caching)
6. Added Offline Behavior (no queuing - block mutations, show cached data)
7. Added New Package Dependencies section with platform setup requirements
8. Updated interceptor example to show migration-aware unified auth

### Architecture Decisions Confirmed
| ADR | Decision | Status |
|-----|----------|--------|
| ADR-1 | Single JWT auth for all endpoints (updated) | ✅ Confirmed |
| ADR-2 | JWT tokens in secure storage | ✅ Confirmed |
| ADR-3 | Family providers for per-store data | ✅ Confirmed |
| ADR-4 | Location as soft requirement | ✅ Confirmed |
| ADR-5 | Biometric gates refresh token only | ✅ Confirmed |
| ADR-6 | Scheduling routes as /scheduling/* sub-tree | ✅ Confirmed |

### Backend Dependencies Identified
- Legacy `mobile.php` endpoints must accept JWT Bearer auth post-migration
- Feature flag per store returned in login response
- Idempotency key handling for mutations (24h cache)

## PLAN Review (2025-12-30)

### Review Process
- **Reviewer:** Codex (o3 model)
- **Completion Date:** 2025-12-30

### Key Findings from Codex Review

**Blockers Resolved:**
1. ✅ Added Phase 0 Pre-Implementation Gate for validating OpenAPI, app plumbing, and backend dependencies
2. ✅ Added Platform Setup tasks (T1.4) for iOS Info.plist and Android Manifest configurations
3. ✅ Added SchedulingApiClient (T1.7) for JWT-authenticated scheduling API calls
4. ✅ Added FCM device token registration (T4.3.7) after login
5. ✅ Added "feature not available" screen (T5.5.4-5.5.5) for stores without scheduling access

**Important Improvements Made:**
1. Fixed PRD feature references (Who's Working is F7, My Schedule is F8 - not F6/F7)
2. Fixed denial note optionality (note is optional per SDD, not required)
3. Split coarse datasource tasks into granular endpoint-specific tasks (T3.4.2-T3.4.10)
4. Added Risks & Mitigations sections to Phases 1, 3, 4, 5, 7, and 9
5. Added Mid-Plan Integration Checkpoints after Phases 5, 7, and 9

### Plan Structure
| Phase | Description | Task Count |
|-------|-------------|------------|
| Phase 0 | Pre-Implementation Gate | 10 tasks |
| Phase 1 | Core Infrastructure | 30 tasks |
| Phase 2 | Data Layer (Models/Entities) | 18 tasks |
| Phase 3 | Repository & Datasource | 17 tasks |
| Phase 4 | Authentication & Providers | 18 tasks |
| Phase 5 | Login & Store Selector Screens | 17 tasks |
| Phase 6 | Manager Dashboard | 16 tasks |
| Phase 7 | Pending Requests & Approvals | 22 tasks |
| Phase 8 | Shift CRUD | 13 tasks |
| Phase 9 | Advanced Features (F11-14) | 28 tasks |
| Phase 10 | Analytics & Observability | 8 tasks |
| Phase 11 | Integration & E2E Validation | 38 tasks |

**Total: 12 Phases, 200+ Tasks, All 14 PRD Features Mapped**

### Parallel Execution Opportunities
- Phase 2: Auth, Scheduling, and Advanced models can be built in parallel
- Phase 6: Providers and Widgets can be built in parallel
- Phase 9: All 4 advanced features (F11-F14) can be built in parallel

### Integration Checkpoints
- After Phase 5: Validate complete auth flow
- After Phase 7: Validate core approval flow with audit trail
- After Phase 9: Validate all 14 features functional

## Context

Add manager-level scheduling features to the BuyerKiosk Live Flutter app using the Mobile Scheduling API (docs/api/mobile-scheduling-openapi.yaml). Features include:
- Approving/denying shift swap requests
- Approving/denying time-off requests
- Approving/denying clock override requests
- Approving/denying open shift claims
- Manager dashboard with pending request counts
- Labor cost tracking
- Who's working status
- Shift CRUD operations
- Schedule publishing and copying

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