# Product Requirements Document

**Specification ID:** 001-team-mobile-app
**Version:** 1.0
**Status:** DRAFT
**Last Updated:** December 2025
**Depends On:** 007-unified-users-auth (implemented), 013-employee-scheduling, 014-manage-employees-unified

---

## Validation Checklist

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

---

## Product Overview

### Vision
Empower resale store team members with a native mobile app that puts scheduling, time tracking, team communication, and daily performance at their fingertips—replacing the need for third-party scheduling tools like WhenIWork.

### Problem Statement
Store employees using BuyerKiosk's homegrown scheduling system currently have limited mobile access to their work information:

1. **No Schedule Visibility**: Employees cannot check their upcoming shifts from their personal phones—they must be in-store or contact a manager
2. **Kiosk-Only Time Clock**: Clocking in/out requires physical presence at the shared workbook kiosk, creating bottlenecks during shift changes
3. **No Mobile Notifications**: Employees miss shift changes, schedule updates, and team announcements because there's no push notification system
4. **Fragmented Communication**: Team communication happens through personal text messages or third-party apps, not integrated with the work platform
5. **Performance Blind Spot**: Employees can't see their daily performance stats (buys completed, items processed) without accessing the desktop system

**Business Impact:**
- Managers spend time answering "when do I work?" questions
- Late arrivals due to schedule confusion
- No direct communication channel with team members
- Employees feel disconnected from their performance metrics

### Value Proposition
The BuyerKiosk Team App delivers:

1. **Schedule at Your Fingertips**: View current and upcoming shifts instantly from any device
2. **Clock In Anywhere**: Geo-fenced time clock allows clocking in from the parking lot (within store radius)
3. **Real-Time Updates**: Push notifications for schedule changes, shift reminders, and team messages
4. **Team Chat (Future)**: Integrated messaging for store-level and company-wide communication
5. **Performance Dashboard**: Daily stats showing personal contribution to store goals
6. **Native Experience**: iOS and Android apps built with Flutter for a fast, native feel

## User Personas

### Primary Persona: Floor Employee (Taylor)
- **Demographics:** 18-30 years old, part-time or full-time sales associate, high mobile proficiency, uses smartphone for everything
- **Goals:**
  - Know their schedule for upcoming weeks without asking
  - Clock in/out quickly without waiting for the shared kiosk
  - See how they're performing compared to goals
  - Get notified when schedule changes
- **Pain Points:**
  - Has to remember to check schedule at work or text manager
  - Sometimes late because forgot shift time
  - No visibility into personal performance metrics
  - Feels disconnected when not at the store

### Secondary Personas

#### Shift Lead / Buyer (Marcus)
- **Demographics:** 22-35 years old, key holder with partial management responsibilities, works 30-40 hours/week
- **Goals:**
  - See who's scheduled with them each shift
  - Quick clock-in when arriving to open the store
  - Monitor team attendance in real-time
  - Access buy queue and store stats from mobile
- **Pain Points:**
  - Opening the store alone, needs to clock in fast
  - Can't see if co-workers are running late until they don't show up
  - Has to use desktop to check queue status

#### Store Manager (Sarah)
- **Demographics:** 28-45 years old, manages daily operations, moderate-high technical comfort
- **Goals:**
  - Monitor who's clocked in vs scheduled
  - Send quick messages to team
  - Check store performance from anywhere
  - Approve time-off requests on the go (future)
- **Pain Points:**
  - Has to be at computer to see attendance
  - No way to message entire team at once
  - Can't review schedules when away from store

## User Journey Maps

### Primary User Journey: Checking Schedule and Clocking In

1. **Awareness:** Taylor wonders "Do I work tomorrow?" while at home in the evening
2. **Action:** Opens the Team App on phone, sees "My Schedule" on home screen
3. **Discovery:** Sees they work 10am-6pm tomorrow at the Anna location
4. **Next Day:** Arrives at store parking lot at 9:55am, opens app
5. **Clock In:** Taps "Clock In" button, app confirms they're within geo-fence, records time punch
6. **Confirmation:** Sees green checkmark and "Clocked in at 9:55 AM" with shift details
7. **Throughout Day:** Checks performance stats during break, sees 8 buys completed

### Secondary User Journeys

#### Schedule Change Notification Journey
1. Manager updates Taylor's shift from Tuesday to Wednesday in the web admin
2. Taylor receives push notification: "Schedule Update: Your Tuesday 12-8 shift has been moved to Wednesday 12-8"
3. Taylor opens app, sees updated schedule with change highlighted
4. Taylor taps shift to see details and any notes from manager

#### End-of-Shift Clock Out Journey
1. Taylor finishes shift, heading to car
2. Opens app, taps "Clock Out"
3. App shows shift summary: 8 hours worked, no breaks recorded
4. Taylor realizes they forgot to log lunch break
5. Sees "Forgot Break?" option, taps to add break time (or notes it for manager to fix)
6. Confirms clock out, sees day's performance summary

#### Store Manager Mobile Check-In Journey
1. Sarah is at home, wants to see how Saturday is going
2. Opens Team App, sees store dashboard
3. Views: 4 employees clocked in, 12 buys completed, $450 buy spend
4. Notices Marcus hasn't clocked in but is scheduled
5. Taps Marcus's name, sees he's 15 minutes late
6. Can send quick message: "Running late?" (future feature)

## Feature Requirements

### Must Have Features (MVP)

#### Feature 1: User Authentication
- **User Story:** As a team member, I want to log into the app with my BuyerKiosk credentials so that I can access my work information securely
- **Acceptance Criteria:**
  - [ ] Login with username/email and password
  - [ ] Support for existing BuyerKiosk accounts (via unified users system)
  - [ ] Biometric authentication (FaceID/TouchID) after initial password login
  - [ ] Secure token storage on device (using platform keychain/keystore)
  - [ ] Auto-login on app reopen (until explicit logout)
  - [ ] Password reset flow via email
  - [ ] Support for multiple store assignments (user sees all their stores)
  - [ ] Session timeout after 30 days of inactivity

#### Feature 2: My Schedule View
- **User Story:** As a team member, I want to see my upcoming shifts so that I know when I'm scheduled to work
- **Acceptance Criteria:**
  - [ ] Default view shows current week's schedule
  - [ ] Can navigate forward up to 4 weeks
  - [ ] Each shift shows: date, start time, end time, position, store (if multi-store)
  - [ ] Today's shift prominently displayed on home screen
  - [ ] Visual indicator for current day
  - [ ] Pull-to-refresh to get latest schedule
  - [ ] Works offline with cached data (shows "last updated" timestamp)

#### Feature 3: Time Clock (Clock In/Out)
- **User Story:** As a team member, I want to clock in and out from my phone so that I don't have to wait for the shared kiosk
- **Acceptance Criteria:**
  - [ ] "Clock In" button visible when not clocked in
  - [ ] "Clock Out" button visible when clocked in
  - [ ] Geo-fence validation: must be within configured radius of store (default 1000 feet)
  - [ ] Clear error message if outside geo-fence: "You must be at the store to clock in"
  - [ ] PIN verification required (employee's clock PIN)
  - [ ] Shows confirmation with timestamp after successful punch
  - [ ] Real-time sync with backend (time punch appears in web admin immediately)
  - [ ] Offline handling: queue punch and sync when connectivity restored
  - [ ] Cannot clock in more than 15 minutes before scheduled shift start

#### Feature 4: Break Tracking
- **User Story:** As a team member, I want to log my breaks so that my hours are calculated correctly
- **Acceptance Criteria:**
  - [ ] "Start Break" button when clocked in
  - [ ] Select break type: Paid or Unpaid
  - [ ] "End Break" button when on break
  - [ ] Break duration displayed in real-time while on break
  - [ ] Warning if break exceeds 60 minutes
  - [ ] Break summary shown on clock out
  - [ ] Geo-fence NOT required for break actions (employee may leave premises)

#### Feature 5: Today's Performance Stats
- **User Story:** As a team member, I want to see my daily performance so that I know how I'm contributing to store goals
- **Acceptance Criteria:**
  - [ ] Dashboard shows: hours worked today, buys completed (if buyer), items processed
  - [ ] Compare to daily goals if configured
  - [ ] Shows store totals alongside personal stats
  - [ ] Updates in real-time or on pull-to-refresh
  - [ ] Historical view: see stats from past 7 days

#### Feature 6: Store Selector (Multi-Store Users)
- **User Story:** As a team member who works at multiple stores, I want to switch between stores so that I can see the right schedule and clock into the right location
- **Acceptance Criteria:**
  - [ ] Store selector visible if user has multiple store assignments
  - [ ] Default to most recently accessed store
  - [ ] Schedule and clock functions scoped to selected store
  - [ ] Clear indicator of which store is currently selected
  - [ ] Geo-fence validation uses selected store's location

#### Feature 7: Push Notifications
- **User Story:** As a team member, I want to receive notifications about schedule changes so that I don't miss important updates
- **Acceptance Criteria:**
  - [ ] Notification when schedule is changed (shift added, modified, or deleted)
  - [ ] Shift reminder: configurable time before shift (default 1 hour)
  - [ ] Notification when approaching overtime threshold (for stores with overtime alerts)
  - [ ] User can configure notification preferences in app settings
  - [ ] Notifications work when app is closed (background push)

### Should Have Features

#### Feature 8: Team Schedule View
- **User Story:** As a shift lead, I want to see who else is scheduled with me so that I know who's working
- **Acceptance Criteria:**
  - [ ] Toggle between "My Schedule" and "Team Schedule"
  - [ ] Team view shows all scheduled employees for each day
  - [ ] Clock-in status indicator (green = clocked in, gray = not yet, red = late/no-show)
  - [ ] Only visible to users with team_schedule permission (shift leads and above)

#### Feature 9: Store Dashboard
- **User Story:** As a manager, I want to see real-time store statistics so that I can monitor performance from anywhere
- **Acceptance Criteria:**
  - [ ] Current queue count and average wait time
  - [ ] Today's buy count and spend
  - [ ] Clocked-in employee count vs scheduled
  - [ ] Sales/buy goal progress (if configured)
  - [ ] Pull-to-refresh for latest data

#### Feature 10: Profile Management
- **User Story:** As a team member, I want to update my profile information so that my contact details are current
- **Acceptance Criteria:**
  - [ ] View current profile: name, email, phone, photo
  - [ ] Update phone number
  - [ ] Update profile photo (upload from camera or gallery)
  - [ ] View store assignments (read-only)
  - [ ] Cannot change email or name (managed by admin)

#### Feature 11: Timesheet View
- **User Story:** As a team member, I want to review my hours for the week so that I can verify my time before payroll
- **Acceptance Criteria:**
  - [ ] View current week's time punches
  - [ ] Shows: date, clock in, clock out, break time, total hours
  - [ ] Weekly total hours displayed
  - [ ] Flag edited punches (shows "Edited by manager" indicator)
  - [ ] Navigate to previous weeks

### Could Have Features

#### Feature 12: Team Chat
- **User Story:** As a team member, I want to message my coworkers so that I can communicate about work without using personal text messages
- **Acceptance Criteria:**
  - [ ] Store-level chat channel (all employees at that store)
  - [ ] Direct messages between team members
  - [ ] Push notifications for new messages
  - [ ] Message read receipts
  - [ ] Manager can post announcements (pinned messages)

#### Feature 13: Availability Submission
- **User Story:** As a team member, I want to submit my availability so that managers can schedule me for times I can work
- **Acceptance Criteria:**
  - [ ] Weekly availability grid
  - [ ] Mark available/unavailable for each day/time block
  - [ ] Submit for manager review
  - [ ] View submission status (pending, approved, rejected)

#### Feature 14: Time-Off Requests
- **User Story:** As a team member, I want to request time off so that managers know when I can't work
- **Acceptance Criteria:**
  - [ ] Select date range for time off
  - [ ] Select type: vacation, sick, personal
  - [ ] Add notes
  - [ ] View request status (pending, approved, denied)
  - [ ] Push notification when status changes

#### Feature 15: Shift Swap/Coverage Requests
- **User Story:** As a team member, I want to request someone cover my shift so that I can handle schedule conflicts
- **Acceptance Criteria:**
  - [ ] Select shift to swap
  - [ ] Request coverage from specific coworker or open to all
  - [ ] Receive notifications when someone offers to cover
  - [ ] Manager approval required before swap finalizes

### Won't Have (This Phase)

| Exclusion | Rationale |
|-----------|-----------|
| **WhenIWork/Homebase Integration** | This app is specifically for stores using BuyerKiosk's homegrown scheduling system |
| **Schedule Creation/Editing** | Managers create schedules in web admin; this is an employee-facing app |
| **Payroll Export** | Handled in web admin by managers |
| **Advanced Reporting** | Desktop/web admin feature |
| **Customer-Facing Features** | This is a team/employee app only |
| **Inventory Management** | Separate system/app |
| **POS Functions** | Handled by store's POS system |
| **Training/Onboarding** | Out of scope for MVP |

## Detailed Feature Specifications

### Feature: Time Clock with Geo-Fencing

**Description:** The time clock allows employees to clock in/out from their personal mobile devices while ensuring they're physically at or near the store. This prevents remote time theft while providing convenience.

**User Flow:**
1. Employee opens app, sees home screen with current clock status
2. If not clocked in and within geo-fence: "Clock In" button is enabled
3. Employee taps "Clock In"
4. App prompts for 4-6 digit clock PIN
5. Employee enters PIN, taps confirm
6. App validates: location within geo-fence + correct PIN + not already clocked in
7. On success: Shows green confirmation with timestamp, button changes to "Clock Out"
8. On failure: Shows specific error (wrong PIN, outside geo-fence, etc.)

**Business Rules:**
- BR-1: Geo-fence radius is configurable per store (default 1000 feet / ~300 meters)
- BR-2: Clock PIN is the same PIN used at the workbook kiosk (stored in userStoreAssignments.clockPin)
- BR-3: Three failed PIN attempts locks clock function for 5 minutes
- BR-4: Employee cannot clock in more than 15 minutes before their scheduled shift start
- BR-5: Employee CAN clock out at any time (no geo-fence required for clock out)
- BR-6: If employee clocks in without a scheduled shift, punch is flagged as "unscheduled" for manager review
- BR-7: Geo-fence check uses device GPS; if GPS unavailable, show error asking user to enable location services
- BR-8: Time punches sync immediately when online; queue locally if offline and sync when connectivity returns

**Edge Cases:**
| Scenario | Expected Behavior |
|----------|-------------------|
| GPS disabled on device | Show prompt to enable location services; cannot clock in without GPS |
| Weak GPS signal | Use last known location if < 5 minutes old; otherwise show "Unable to verify location" |
| Exactly on geo-fence boundary | Allow clock in (inclusive boundary) |
| Clock in with no scheduled shift | Allow but flag as "Unscheduled Clock-In" with visual indicator |
| App offline during clock in | Queue punch locally with device timestamp; show "Pending Sync" indicator |
| Multiple stores in close proximity | Use selected store's geo-fence; user must explicitly select correct store |
| Employee forgets to clock out | No automatic clock out; manager must add missing punch |
| Clock in attempt while already clocked in | Show error: "Already clocked in at [time]" |

### Feature: Push Notifications

**Description:** Push notifications keep employees informed about schedule changes, shift reminders, and important updates without requiring them to open the app.

**Notification Types:**

| Type | Trigger | Content | Timing |
|------|---------|---------|--------|
| Schedule Changed | Manager modifies employee's shift | "[Store] Schedule Update: Your [Day] shift has been changed" | Immediate |
| Shift Added | Manager adds new shift | "[Store] New Shift: [Day] [Start]-[End]" | Immediate |
| Shift Removed | Manager deletes shift | "[Store] Shift Cancelled: Your [Day] [Start]-[End] shift has been removed" | Immediate |
| Shift Reminder | Approaching scheduled shift | "Reminder: Your shift at [Store] starts in [X] minutes" | Configurable (15min, 30min, 1hr, 2hr before) |
| Overtime Alert | Hours approaching overtime threshold | "Heads up: You're approaching [X] hours this week" | When 36+ hours worked (configurable) |

**User Preferences:**
- Enable/disable all notifications
- Enable/disable shift reminders
- Shift reminder timing (15min, 30min, 1hr, 2hr before)
- Enable/disable schedule change notifications
- Quiet hours (no notifications between X and Y time)

## Success Metrics

### Key Performance Indicators

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| **App Adoption** | 70% of eligible employees within 3 months | Active users / total employees at BuyerKiosk-scheduling stores |
| **Mobile Clock Usage** | 50% of clock actions via mobile within 6 months | Mobile punches / total punches |
| **Schedule View Engagement** | 3+ schedule views per user per week | App analytics |
| **Notification Open Rate** | 40%+ | Push notification analytics |
| **Time-to-Clock-In** | <30 seconds from app open | App analytics (time from app_opened to clock_in_success) |

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `app_opened` | user_id, store_id, platform (ios/android) | Track daily active users |
| `login_success` | user_id, method (password/biometric/token_refresh) | Track auth patterns |
| `biometric_enabled` | user_id, biometric_type (face/fingerprint) | Track biometric adoption |
| `schedule_viewed` | user_id, store_id, week_offset | Track schedule engagement |
| `clock_in_attempted` | user_id, store_id, location_accuracy | Track clock attempts |
| `clock_in_success` | user_id, store_id, scheduled (bool), seconds_from_app_open | Track successful clocks |
| `clock_in_failed` | user_id, store_id, failure_reason | Track issues |
| `clock_out_success` | user_id, store_id, hours_worked | Track clock outs |
| `break_started` | user_id, store_id, break_type | Track break usage |
| `notification_received` | user_id, notification_type | Track delivery |
| `notification_opened` | user_id, notification_type | Track engagement |
| `store_switched` | user_id, from_store, to_store | Track multi-store users |

---

## Constraints and Assumptions

### Constraints
- **Platform Support:** iOS 14+ and Android 10+ (covers 95%+ of active devices)
- **Connectivity:** App must handle offline scenarios gracefully; core features need occasional connectivity
- **Backend Dependency:** Requires 007-unified-users-auth and 013-employee-scheduling to be implemented
- **Geo-Location:** Requires user to grant location permissions for clock functionality
- **Push Notifications:** Requires user to grant notification permissions (can function without, but degraded experience)

### Assumptions
- Stores using BuyerKiosk scheduling have accurate store address configured for geo-fencing
- Employees have smartphones capable of running the app (iOS/Android)
- Store WiFi or cellular connectivity available at store locations
- Clock PINs are already set up for employees in the web admin
- Backend mobile APIs will be extended to support new functionality

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| **GPS Accuracy Issues** | High | Medium | Use multiple location sources (GPS, WiFi, cell); configurable geo-fence radius; manual override for managers |
| **Low App Adoption** | High | Medium | Make app valuable beyond clocking (schedule visibility, stats); manager encouragement; simple onboarding |
| **Offline Clock Punch Loss** | High | Low | Queue punches locally with redundancy; visual "pending sync" indicator; manager notification of offline punches |
| **Time Theft via GPS Spoofing** | Medium | Low | Detect common spoofing apps; compare punch patterns; flag anomalies for manager review |
| **Battery Drain from GPS** | Medium | Medium | Only check GPS when clocking (not continuous); optimize location checks |
| **Push Notification Delivery** | Medium | Low | Use reliable service (Firebase); in-app notification center as backup |

## Open Questions

- [x] Primary use case: Stores using BuyerKiosk native scheduling (not WhenIWork/Homebase)
- [x] Should managers be able to clock in employees remotely via the app? **Decision: Desktop only** - managers clock others via web admin only
- [x] What is the acceptable geo-fence radius range? **Decision: Default 1000 feet** - configurable per store
- [x] Should the app support biometric login? **Decision: Yes, MVP feature** - FaceID/TouchID after initial login
- [ ] For team chat (future): Store-level only, or also cross-store for multi-location owners?
- [ ] Should overtime alerts be opt-in or on by default?

---

## Supporting Research

### Competitive Analysis

| App | Strengths | Weaknesses | Learnings |
|-----|-----------|------------|-----------|
| **WhenIWork** | Clean schedule UI, robust notifications, shift swapping | Per-employee cost, external system | Notification timing options are valued |
| **Homebase** | Free tier, integrated hiring | Limited features on free tier | Schedule + clock in same app is expected |
| **Deputy** | Good geo-fencing, facial recognition | Complex, enterprise-focused | Geo-fence is table stakes |
| **7shifts** | Restaurant-focused, labor forecasting | Niche industry | Vertical focus can be powerful |

**Key Patterns to Adopt:**
- Home screen shows today's shift prominently
- One-tap clock in (after initial authentication)
- Clear visual distinction between scheduled/clocked-in/on-break states
- Pull-to-refresh everywhere
- Schedule changes push immediately

### User Research

**Based on feedback from BuyerKiosk store owners and employees:**
1. "I just want to know when I work without asking" - Most requested feature
2. "The kiosk gets busy during shift change" - Pain point driving mobile clock-in
3. "I want to see how I'm doing compared to goals" - Employee engagement driver
4. "Texting my team is annoying, I wish there was one place" - Future chat value

### Market Data
- 85% of hourly workers own smartphones (Pew Research 2024)
- Mobile time clock adoption increases accuracy by 20% and reduces "buddy punching" (SHRM)
- Schedule visibility is the #1 requested feature for hourly workforce apps (Workforce Institute)
- Average employee checks schedule 5-7 times per week when mobile access available

---

## Document History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | December 2025 | Claude | Initial PRD draft |