# Phase 7: Manual QA Checklist

## Spec 013: Employee Scheduling - Integration & End-to-End Validation

This checklist covers manual QA tasks for validating the BuyerKiosk native scheduling system.

---

## 1. ID Mapping Triangle Validation

The BuyerKiosk scheduling system uses **central user IDs** (`kiosk_users.users.id`), NOT store-local employee IDs (`employees.employeeID`). Verify this triangle works end-to-end:

### 1.1 User-Employee Link Verification
- [ ] Navigate to Admin > Team Members > [Any Employee]
- [ ] Verify the employee is linked to a central user account
- [ ] Check that `user_employee_links` has a corresponding record
- [ ] Verify `scheduleShifts.employeeId` matches `users.id` (not `employees.employeeID`)

### 1.2 Schedule Assignment
- [ ] Create a new shift in Admin > Scheduling
- [ ] Verify the shift appears in the database with `employeeId = users.id`
- [ ] Verify the employee's "My Schedule" page shows the shift
- [ ] Delete the shift and verify it soft-deletes correctly

---

## 2. Store-Local Day Boundaries (Late-Night Shifts)

Test shifts that cross midnight in the store's local timezone.

### 2.1 Late-Night Shift Display
- [ ] Create a shift: 11:00 PM - 7:00 AM (next day)
- [ ] Verify the shift groups to its START date (not end date)
- [ ] Verify both times display correctly in admin calendar
- [ ] Verify the employee sees correct times in "My Schedule"

### 2.2 Overnight Shift Time Punches
- [ ] Clock in during a late-night shift (e.g., 11:15 PM)
- [ ] Verify the punch records correct UTC timestamp
- [ ] Clock out after midnight (e.g., 7:00 AM)
- [ ] Verify total hours calculated correctly (8 hours for 11pm-7am)
- [ ] Verify Timesheet Dashboard shows correct hours

---

## 3. DST Change Week Testing

Test shifts around DST transitions (Spring forward / Fall back).

### 3.1 Spring Forward (2nd Sunday of March)
**Date to test: March 9, 2025 (2:00 AM becomes 3:00 AM)**

- [ ] Create a shift that spans the DST change (e.g., 12:00 AM - 9:00 AM)
- [ ] Verify displayed hours account for the "lost" hour
- [ ] Create a shift entirely after DST change (9:00 AM - 5:00 PM)
- [ ] Verify it displays as 8 hours worked
- [ ] Verify time punches record correctly during DST transition

### 3.2 Fall Back (1st Sunday of November)
**Date to test: November 2, 2025 (2:00 AM becomes 1:00 AM)**

- [ ] Create a shift that spans the DST change
- [ ] Verify displayed hours account for the "gained" hour
- [ ] Verify time punches during the repeated hour are handled correctly

---

## 4. Override Conditions

### 4.1 Unscheduled Employee Clock-In
- [ ] Ensure an employee has NO shift scheduled for today
- [ ] Attempt to clock in via Time Clock
- [ ] Verify "You are not scheduled today" message appears
- [ ] Use manager override to allow clock-in
- [ ] Verify punch is marked as `isUnscheduled = 1`
- [ ] Verify punch appears in Timesheet Dashboard with unscheduled flag

### 4.2 Outside-Window Clock-In
- [ ] Create a shift for 9:00 AM - 5:00 PM
- [ ] Set clock-in early tolerance to 15 minutes
- [ ] Attempt clock-in at 8:00 AM (45 min early)
- [ ] Verify warning about being too early
- [ ] Use manager override to allow clock-in
- [ ] Verify punch is marked as `isManagerOverride = 1`
- [ ] Verify override reason is recorded

---

## 5. Ably Real-Time Event Assertions

Verify WebSocket events fire correctly for schedule changes.

### 5.1 Shift Events
- [ ] Open browser DevTools > Network > WS filter
- [ ] Create a new shift in Admin > Scheduling
- [ ] Verify `schedule.shift.created` event fires on Ably channel
- [ ] Update the shift (change time or position)
- [ ] Verify `schedule.shift.updated` event fires
- [ ] Delete the shift
- [ ] Verify `schedule.shift.deleted` event fires

### 5.2 Time Punch Events
- [ ] Open DevTools on Workbook page
- [ ] Clock in an employee via Time Clock
- [ ] Verify `schedule.punch.created` event fires
- [ ] Verify Schedule Panel updates in real-time
- [ ] Clock out
- [ ] Verify punch update event fires

### 5.3 Event Payload Validation
For each event, verify the payload includes:
- [ ] `typeNum` (store identifier)
- [ ] `shiftId` or `punchId`
- [ ] `employeeId` (should be central user ID)
- [ ] `timestamp`

---

## 6. Redis Cache Invalidation Verification

### 6.1 Schedule Cache
- [ ] Load the schedule for a specific date
- [ ] Check Redis has cached key `schedule:{typeNum}:{date}`
- [ ] Create/update/delete a shift on that date
- [ ] Verify Redis cache key was invalidated
- [ ] Reload the page and verify fresh data loads

### 6.2 My Schedule Cache
- [ ] Load "My Schedule" page for an employee
- [ ] Check Redis for user-specific cache key
- [ ] Update the employee's schedule
- [ ] Verify cache invalidation occurred
- [ ] Refresh and verify updated schedule appears

### 6.3 Cache TTL Verification
- [ ] Load schedule data
- [ ] Check Redis key TTL (should be 5 minutes for schedule data)
- [ ] Wait for TTL expiration
- [ ] Verify stale data is not served

---

## 7. E2E Journey Tests

### 7.1 Weekly Schedule Creation Journey
1. [ ] Admin logs in and navigates to Scheduling
2. [ ] Creates 5 shifts for different employees across the week
3. [ ] Views calendar in Week view
4. [ ] Edits a shift (changes time and position)
5. [ ] Copies a shift to another day
6. [ ] Deletes a shift
7. [ ] Verifies all changes appear correctly

### 7.2 Daily Time Clock Management Journey
1. [ ] Employee opens Time Clock interface
2. [ ] Clocks in for scheduled shift
3. [ ] Verifies clock-in appears in Workbook Schedule Panel
4. [ ] Takes a paid break (15 min)
5. [ ] Returns from break
6. [ ] Takes unpaid lunch break (30 min)
7. [ ] Returns from lunch
8. [ ] Clocks out
9. [ ] Verifies total hours calculation excludes unpaid break

### 7.3 End-of-Week Timesheet Approval Journey
1. [ ] Manager opens Timesheet Dashboard
2. [ ] Selects current week
3. [ ] Reviews all employees' time punches
4. [ ] Edits a missed punch (adds clock-out)
5. [ ] Reviews overtime calculations
6. [ ] Exports timesheet to CSV
7. [ ] Approves all timesheets for the week

### 7.4 Employee Schedule Viewing Journey
1. [ ] Employee logs in
2. [ ] Navigates to "My Schedule"
3. [ ] Views current week's shifts
4. [ ] Scrolls to view all 5 weeks
5. [ ] Verifies shift details (position, times, hours)
6. [ ] Verifies no edit controls are visible (read-only)

---

## 8. Provider Gate Testing

### 8.1 BuyerKiosk Provider Enabled
- [ ] Set store's `schedulingProvider = 'buyerkiosk'`
- [ ] Verify all scheduling features work
- [ ] Verify "My Schedule" endpoint returns data

### 8.2 WhenIWork Provider (Fallback)
- [ ] Set store's `schedulingProvider = 'wheniwork'`
- [ ] Navigate to "My Schedule"
- [ ] Verify response: `{"error": "PROVIDER_NOT_SUPPORTED"}`
- [ ] Verify Admin Scheduling shows WhenIWork integration

### 8.3 No Provider
- [ ] Set store's `schedulingProvider = 'none'`
- [ ] Navigate to Scheduling pages
- [ ] Verify appropriate "not enabled" messages

---

## 9. Authentication & Authorization

### 9.1 Session Expiration
- [ ] Load "My Schedule" page
- [ ] Clear session cookie in DevTools
- [ ] Click refresh/navigate
- [ ] Verify redirect to login page
- [ ] Verify no JS errors in console

### 9.2 Store Group Access
- [ ] Log in as user with access to Store A only
- [ ] Try to access Store B scheduling endpoint
- [ ] Verify 403 Forbidden response

### 9.3 Permission Checks
- [ ] Log in as employee (no admin rights)
- [ ] Try to access Admin > Scheduling
- [ ] Verify access denied
- [ ] Try to edit/delete shifts via API
- [ ] Verify 403 response

---

## 10. Data Integrity Checks

### 10.1 Soft Delete Verification
- [ ] Delete a shift
- [ ] Query database: shift should have `deleted_at IS NOT NULL`
- [ ] Verify shift no longer appears in UI
- [ ] Verify shift still exists in database (for audit)

### 10.2 Audit Trail
- [ ] Edit a time punch
- [ ] Verify `edited_at`, `editedByUserId`, `editNote` are set
- [ ] View punch in Timesheet Dashboard
- [ ] Verify edit indicator shows

### 10.3 Foreign Key Integrity
- [ ] Try to create shift with non-existent employeeId
- [ ] Verify proper error handling
- [ ] Try to delete position that's used by shifts
- [ ] Verify referential integrity maintained

---

## Sign-Off

| Tester | Date | Result | Notes |
|--------|------|--------|-------|
| | | | |
| | | | |

---

*Generated for Spec 013 Phase 7 - December 2024*