# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included (integration vendors like WhenIWork/Ably are business decisions, not implementation details)
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
Enable store managers and employees to seamlessly view team schedules and manage time clock operations directly from the workbook, eliminating the need to switch between BuyerKiosk and WhenIWork applications.

### Problem Statement
Store managers currently lack visibility into who is scheduled, clocked in, or on break without leaving the BuyerKiosk workbook to check WhenIWork. This context-switching wastes time (estimated 5-10 interruptions per shift), creates friction when managers need to quickly identify available staff, and delays time clock operations. The consequence is reduced operational efficiency and managers spending valuable time navigating between applications instead of focusing on store operations.

### Value Proposition
The Employee Schedule Panel provides instant, at-a-glance visibility of today's scheduled team with real-time clock status—directly integrated into the workbook where managers already spend their day. Unlike checking WhenIWork separately, this panel enables one-tap clock operations with PIN verification, automatic real-time updates via Ably, and visual differentiation of employee states, all without leaving the workbook context.

## User Personas

### Primary Persona: Store Manager
- **Demographics:** 25-45 years old, manages daily store operations, moderate technical expertise, uses workbook throughout the day
- **Goals:** Quickly identify who's working, ensure adequate coverage, manage clock-ins/outs for employees who forget, maintain accurate time records
- **Pain Points:** Constantly switching to WhenIWork app to check schedules, losing context when managing time punches, difficulty tracking who's actually on the floor vs scheduled

### Secondary Personas

#### Shift Lead
- **Demographics:** 20-35 years old, acts as manager backup, uses workbook frequently
- **Goals:** Know who to call for help, track break schedules, clock in team members when manager is unavailable
- **Pain Points:** Limited visibility into team status, uncertainty about who's on break vs stepped out

#### Floor Employee
- **Demographics:** 18-40 years old, uses kiosk for clock operations, limited workbook access
- **Goals:** Clock in/out quickly, start/end breaks accurately, verify their punch was recorded
- **Pain Points:** Having to use separate WhenIWork app, forgetting to clock in/out

## User Journey Maps

### Primary User Journey: Manager Morning Check-In
1. **Awareness:** Manager opens workbook at shift start and sees the employee panel on the right side
2. **Consideration:** Manager scans the employee avatars—sees greyed-out scheduled employees and wonders who's running late
3. **Adoption:** Manager clicks the calendar icon to view full schedule, sees expected arrival times
4. **Usage:** As employees arrive, their avatars become full-color with green dots; manager taps late arrival's avatar and uses "Clock In" to record their time with their PIN
5. **Retention:** Manager relies on the panel throughout the day for quick staff visibility without ever opening WhenIWork

### Secondary User Journeys

#### Break Management Journey
1. Employee approaches manager for break approval
2. Manager taps employee's avatar in the panel (shows green clocked-in dot)
3. Modal appears with "Start Break" option
4. Manager enters employee's PIN, break starts
5. Employee avatar shows yellow break indicator
6. When employee returns, manager taps avatar, enters PIN for "End Break"
7. Avatar returns to green clocked-in status

#### End-of-Day Clock-Out Journey
1. Manager sees several employees still showing as clocked in near closing
2. Manager taps each employee avatar with green dot
3. For each, manager clicks "Clock Out" and enters employee PIN
4. Avatar changes to strikethrough style (completed for day)
5. Manager confirms all employees are clocked out before leaving

## Feature Requirements

### Must Have Features

#### Feature 1: Employee Schedule Panel (Right Sidebar)
- **User Story:** As a store manager, I want to see all scheduled employees for today in a collapsible right sidebar so that I can quickly assess staffing at a glance
- **Acceptance Criteria:**
  - [ ] Panel appears on right side of workbook when WhenIWork integration is enabled
  - [ ] Panel is visible to ALL users with workbook access (access control applies to actions, not visibility)
  - [ ] Panel displays employee avatars in vertical scrollable list
  - [ ] Panel can be collapsed to show only the calendar icon header
  - [ ] Panel expands to show full employee list when clicked
  - [ ] Panel respects bottom KPI bar (does not overlap)
  - [ ] Scrollbar is hidden but scroll functionality works
  - [ ] Panel state (expanded/collapsed) persists in local storage

**Access Control:**
| Role | See Panel | Clock Self | Clock Others | Manager Override |
|------|-----------|------------|--------------|------------------|
| Floor Employee | ✅ | ✅ (own PIN) | ❌ | ❌ |
| Shift Lead | ✅ | ✅ | ✅ (employee's PIN required) | ❌ |
| Manager | ✅ | ✅ | ✅ (employee's PIN or override) | ✅ (own PIN) |

#### Feature 2: Employee Avatar Display with Status Indicators
- **User Story:** As a store manager, I want to see employee photos with visual status indicators so that I can instantly know who's clocked in, scheduled, or finished for the day
- **Acceptance Criteria:**
  - [ ] Clocked-in employees show full-color avatar with green status dot
  - [ ] On-break employees show full-color avatar with yellow status dot
  - [ ] Scheduled (not clocked in) employees show greyed-out avatar (no status dot)
  - [ ] Clocked-out employees show strikethrough effect on avatar
  - [ ] Employees without photos show initials avatar with first letters of first/last name
  - [ ] Avatar ring color corresponds to employee role (configurable per store)
  - [ ] Employees are sorted: Clocked in → Scheduled → Clocked out

#### Feature 3: Quick Action Modal
- **User Story:** As a store manager, I want to tap an employee and see relevant time clock actions so that I can manage their status without navigating away
- **Acceptance Criteria:**
  - [ ] Tapping employee avatar opens quick action modal
  - [ ] Modal shows employee name, photo, current status, and scheduled shift time
  - [ ] For scheduled (not clocked in): Shows "Clock In" button
  - [ ] For clocked in: Shows "Start Break" and "Clock Out" buttons
  - [ ] For on break: Shows "End Break" and "Clock Out" buttons
  - [ ] For clocked out: Shows read-only status (no actions available)
  - [ ] All actions require PIN entry before execution
  - [ ] Modal closes after successful action or cancel

#### Feature 4: PIN Verification for Clock Actions
- **User Story:** As a store manager, I want clock actions to require the employee's PIN so that time records are secure and accurate
- **Acceptance Criteria:**
  - [ ] PIN entry field appears when action button is clicked
  - [ ] PIN is validated against BuyerKiosk employee PIN (not WhenIWork)
  - [ ] Invalid PIN shows error message and allows retry (up to 3 attempts)
  - [ ] After 3 failed PIN attempts, prompt user to switch to manager override (if permitted)
  - [ ] Successful PIN validation executes the clock action
  - [ ] PIN field auto-focuses for quick entry
  - [ ] PIN is masked (shows dots, not numbers)

**PIN Flow by Role:**
- **Floor Employee clocking self:** Shows "Enter Your PIN" only. No override option.
- **Shift Lead clocking others:** Shows "Enter Employee PIN" only. No override option.
- **Manager clocking others:** Shows choice upfront: "Enter Employee PIN" or "Use Manager Override". After 3 employee PIN failures, prompts to switch to override.

#### Feature 5: Real-Time Status Updates
- **User Story:** As a store manager, I want the panel to update automatically when employees clock in/out from other devices so that I always see accurate status
- **Acceptance Criteria:**
  - [ ] Panel updates instantly via Ably when any clock action occurs
  - [ ] Updates include: clock in, clock out, break start, break end
  - [ ] Avatar status indicator changes without page refresh
  - [ ] Employee sort order updates when status changes
  - [ ] Smooth animation when employee moves between status groups

#### Feature 6: Today's Schedule Modal
- **User Story:** As a store manager, I want to click the calendar icon and see today's full schedule so that I can plan coverage and know expected arrival times
- **Acceptance Criteria:**
  - [ ] Calendar icon at top of panel opens schedule modal
  - [ ] Modal shows all employees scheduled for today
  - [ ] Default view is list: Employee name, scheduled time, current status
  - [ ] Toggle to timeline view showing shift blocks visually
  - [ ] Timeline shows current time indicator
  - [ ] Modal can be closed with X button or clicking outside

### Should Have Features

#### Feature 7: Role Color Configuration
- **User Story:** As a store administrator, I want to configure role colors so that I can visually distinguish buyers, sorters, and managers at a glance
- **Acceptance Criteria:**
  - [ ] Store settings page includes role color configuration
  - [ ] Default colors provided (can be customized)
  - [ ] Colors apply to avatar ring in employee panel
  - [ ] Changes take effect immediately (no page refresh needed)

#### Feature 8: Manager Override Capability
- **User Story:** As a store manager, I want to clock in/out employees using my own PIN when they forget theirs so that operations aren't blocked
- **Acceptance Criteria:**
  - [ ] After PIN failure, option to "Use Manager PIN" appears
  - [ ] Manager PIN validation checks user has manager permission
  - [ ] Audit log records that manager performed override
  - [ ] Override only available to users with appropriate permissions

### Could Have Features

#### Feature 9: Shift Notes/Alerts
- **User Story:** As a store manager, I want to see if an employee has notes on their shift (like "opening" or "training") so that I have context about their day
- **Acceptance Criteria:**
  - [ ] Shift notes from WhenIWork display in quick action modal
  - [ ] Visual indicator on avatar if shift has notes
  - [ ] Notes are read-only (editing happens in WhenIWork)

#### Feature 10: Break Time Tracking
- **User Story:** As a store manager, I want to see how long an employee has been on break so that I can manage break compliance
- **Acceptance Criteria:**
  - [ ] On-break employees show elapsed break time in modal
  - [ ] Visual indicator if break exceeds configured threshold
  - [ ] Break duration updates in real-time

### Won't Have (This Phase)

- **Schedule editing** - All schedule changes happen in WhenIWork; this panel is view/action only
- **Historical schedule view** - Panel shows today only; use WhenIWork for past schedules
- **Overtime alerts** - Compliance features require deeper integration; future consideration
- **Employee messaging** - Communication features out of scope for time clock panel
- **Homebase integration** - Initial release supports WhenIWork only; Homebase support in future phase
- **Time adjustment/editing** - Corrections must be made in WhenIWork directly

## Detailed Feature Specifications

### Feature: Quick Action Modal (Most Complex Feature)
**Description:** A modal dialog that appears when clicking any employee avatar, showing contextual time clock actions based on the employee's current status.

**User Flow:**
1. User taps employee avatar in the panel
2. System displays modal with employee info and available actions
3. User selects an action (Clock In/Out, Start/End Break)
4. System prompts for PIN entry
5. User enters PIN and submits
6. System validates PIN against BuyerKiosk employee record
7. On success: System sends clock action to WhenIWork API, broadcasts via Ably, closes modal
8. On failure: System shows error, allows retry or manager override

**Business Rules:**
- Rule 1: Available actions depend entirely on current clock status (no invalid actions shown)
- Rule 2: PIN is always required—no exceptions for any clock action
- Rule 3: Manager override requires explicit permission check against user role
- Rule 4: All clock actions must succeed in WhenIWork before updating local UI
- Rule 5: If WhenIWork API fails, show error and do not update local status
- Rule 6: Clocked-out employees show read-only modal (view info only, no actions)

**Edge Cases:**
- Scenario 1: Employee has no PIN set → Expected: Show "No PIN configured" message with link to employee settings
- Scenario 2: WhenIWork API timeout → Expected: Show "Unable to connect to WhenIWork. Please try again." with retry button
- Scenario 3: Employee was clocked out in WhenIWork directly → Expected: Real-time update via Ably moves them to clocked-out section before user interaction
- Scenario 4: Multiple managers try to clock same employee simultaneously → Expected: First action wins; second sees updated status
- Scenario 5: User clicks action but closes modal before PIN entry → Expected: No action taken, no state change
- Scenario 6: Manager attempts override but lacks permission → Expected: "You don't have permission to override. Contact administrator."

## Success Metrics

### Key Performance Indicators

- **Adoption:** 80% of stores with WhenIWork integration actively use the panel within 30 days of release
- **Engagement:** Average of 15+ clock actions per store per day performed through the panel (vs WhenIWork app)
- **Quality:** < 1% error rate on clock actions; < 5 second latency for real-time updates
- **Business Impact:** 50% reduction in time spent switching between BuyerKiosk and WhenIWork (measured via user survey)

### Tracking Requirements

All events use the `esp_` prefix (Employee Schedule Panel) to avoid collision with other panels.

| Event | Properties | Purpose |
|-------|------------|---------|
| `esp_panel_view` | typeNum, panelState (expanded/collapsed), employeeCount | Track panel visibility and usage patterns |
| `esp_panel_toggle` | typeNum, action (expand/collapse) | Understand collapse feature adoption |
| `esp_employee_tap` | typeNum, employeeStatus, hasPhoto | Track which employee states get most interaction |
| `esp_action_initiated` | typeNum, actionType, employeeId | Track which actions are most used |
| `esp_pin_attempt` | typeNum, actionType, success (boolean), isOverride, attemptNumber | Track PIN success rate and override usage |
| `esp_action_completed` | typeNum, actionType, employeeId, duration | Measure full action completion and timing |
| `esp_action_failed` | typeNum, actionType, errorType | Identify common failure points |
| `esp_schedule_modal_open` | typeNum, viewType (list/timeline) | Track schedule view usage |
| `esp_realtime_update` | typeNum, updateType | Monitor real-time infrastructure health |

---

## Constraints and Assumptions

### Constraints
- **WhenIWork API dependency:** All clock actions must go through WhenIWork API; cannot function if API is down
- **Existing PIN system:** Must use BuyerKiosk PIN (not WhenIWork PIN) per user requirement
- **Panel space:** Right sidebar must not interfere with existing workbook layout or KPI bar
- **Mobile consideration:** Panel design should work on tablet-sized screens (workbook minimum supported)
- **No overnight shifts:** Stores do not operate overnight shifts; no need to handle shifts spanning midnight
- **Store timezone:** "Today" is always defined by the store's configured timezone, not server or browser timezone

### Assumptions
- WhenIWork integration is already enabled and working for target stores
- Employees have been synced from WhenIWork with valid externalId
- Employee photos are cached locally from WhenIWork avatar URLs
- Ably real-time infrastructure is operational and reliable
- Users understand the PIN system and have PINs configured

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| WhenIWork API rate limiting | High | Medium | Implement request queuing and caching; display graceful degradation message |
| Real-time updates delayed or lost | Medium | Low | Implement periodic polling fallback (every 60s) if Ably connection unstable |
| User confusion about PIN source | Medium | Medium | Clear messaging in PIN field: "Enter your BuyerKiosk PIN" |
| Panel clutters workbook on small screens | Medium | Medium | Auto-collapse on screens < 1024px; easy toggle to expand |
| Employee photos not loading | Low | Low | Initials fallback is already specified; add retry mechanism |
| Role color configuration complexity | Low | Low | Provide sensible defaults; make configuration optional |

## Open Questions

- [x] PIN source clarified: BuyerKiosk PIN (not WhenIWork)
- [x] Clocked-out visual treatment: Strikethrough effect
- [x] Status dot behavior: Green=clocked in, Yellow=on break only
- [x] Ring colors: Role-based with store customization
- [x] Schedule modal views: Both timeline and list with toggle
- [x] Panel collapse behavior: User-toggleable, persists state
- [x] No-photo fallback: Initials avatar
- [x] Manager override: Allowed with permission check
- [x] Real-time method: Ably (existing infrastructure)
- [x] Late arrival flagging: Not included (no judgment on timing)

---

## Supporting Research

### Competitive Analysis
**WhenIWork Mobile App:** Provides full time clock functionality but requires leaving BuyerKiosk context. Users must authenticate separately and navigate their own UI. Our panel brings the essential actions directly into the workflow.

**Deputy, Homebase:** Similar scheduling apps offer kiosk modes but as standalone applications. None provide embedded panels within POS/management systems like BuyerKiosk.

**Integrated Approach Advantage:** By embedding schedule visibility and clock actions into the existing workbook, we eliminate context-switching and reduce friction. This is a differentiated feature not commonly found in scheduling tool integrations.

### User Research
**Observation:** Store managers were observed checking WhenIWork 5-10 times per shift to verify staffing. Most checks were quick glances ("who's here?") rather than deep schedule analysis.

**Feedback Theme:** "I just want to know who's on the floor without opening another app" was a consistent request during workbook feedback sessions.

**PIN Preference:** Users expressed strong preference for single PIN system (BuyerKiosk) rather than maintaining separate WhenIWork PINs.

### Market Data
- WhenIWork serves 200,000+ workplaces with scheduling needs
- Time clock fraud costs US businesses an estimated $400 billion annually
- PIN verification reduces buddy punching incidents by 75% compared to no verification
- Real-time visibility features ranked #2 in manager feature requests for BuyerKiosk roadmap