From 29adf60b8a9ec70e57cef7d2463ba4f71c8e8362 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Sun, 15 Mar 2026 00:27:34 -0400 Subject: [PATCH] feat(specification): update clock-in process with time-window enforcement and location verification details --- .claude/skills/krow-paper-design/SKILL.md | 32 ++- docs/DESIGN/product-specification.md | 273 ++++++++++++++-------- 2 files changed, 209 insertions(+), 96 deletions(-) diff --git a/.claude/skills/krow-paper-design/SKILL.md b/.claude/skills/krow-paper-design/SKILL.md index 93860546..b4f56157 100644 --- a/.claude/skills/krow-paper-design/SKILL.md +++ b/.claude/skills/krow-paper-design/SKILL.md @@ -190,10 +190,22 @@ All chips: border 1.5px, text Manrope 14px/600, gap 8px for icon+text - Active (filled): bg `#0A39DF`, radius 8px, padding 6px/12px - Text Manrope 12px/600 `#FFFFFF` -**Status Badges:** +**XSmall (Status Chips):** +- For inline status indicators on list rows, section overviews, and cards +- Height: ~20px, padding: 3px/8px, no border +- Text: Manrope 11px/700, uppercase, letter-spacing 0.03-0.04em +- Variants: + - Required/Pending: bg `#FEF9EE`, text `#D97706`, radius 6px + - Active/Complete: bg `#ECFDF5`, text `#059669`, radius 6px + - Confirmed/Info: bg `#E9F0FF`, text `#0A39DF`, radius 6px + - Error/Rejected: bg `#FEF2F2`, text `#F04444`, radius 6px + - Neutral/Disabled: bg `#F1F3F5`, text `#94A3B8`, radius 6px + +**Status Badges (legacy):** - Radius: 8px, padding: 4px/8px - Text: Manrope 11px/600-700, uppercase, letter-spacing 0.04em - Colors follow semantic badge table above +- Prefer XSmall Chips for new designs ### Text Inputs @@ -247,6 +259,24 @@ All chips: border 1.5px, text Manrope 14px/600, gap 8px for icon+text - Value: Inter Tight 20px/700 `#121826` - Layout: flex row, equal width columns, gap 8px +### Notice Banners + +Contextual banners for alerts, warnings, and informational notices. Used in forms, review screens, and detail pages. + +- Container: radius 10px, padding 14px, gap 6px, flex column +- Icon + Title row: flex row, gap 8-10px, align center +- Icon: 18×18 SVG, same color as text +- Title: Manrope 14px/600, line-height 18px +- Body: Manrope 12px/400, line-height 18px + +**Variants:** +| Variant | Background | Color | Title Weight | Icon | +|---------|-----------|-------|-------------|------| +| Error | `#FEF2F2` | `#F04444` | 600 | ⊗ (circle-x) | +| Warning | `#FEF9EE` | `#E6A817` | 600 | △ (triangle-alert) | +| Info/Notice | `#E9F0FF` | `#0A39DF` | 600 | ⓘ (circle-info) | +| Success | `#ECFDF5` | `#059669` | 600 | ✓ (circle-check) | + ### Contact/Info Rows - Container: radius 12px, border 0.5px `#D1D5DB`, background `#FFFFFF`, overflow clip diff --git a/docs/DESIGN/product-specification.md b/docs/DESIGN/product-specification.md index 0163fa86..fd7e5515 100644 --- a/docs/DESIGN/product-specification.md +++ b/docs/DESIGN/product-specification.md @@ -6,7 +6,7 @@ ## Document Information **Version**: 1.0 -**Last Updated**: March 9, 2026 +**Last Updated**: March 14, 2026 **Purpose**: This document describes the functional behavior and user experience of KROW's mobile workforce management platform from a design perspective. --- @@ -1575,130 +1575,213 @@ Provide workers with a personalized dashboard showing shift summaries, recommend ## Staff: Clock In Out ### Purpose -Track worker attendance with location verification. Workers can check in and out of shifts, log break times, and enable commute tracking. +Track worker attendance with time-window enforcement and location verification. Workers view their scheduled shifts, check in using a swipe or NFC gesture, record break details during check-out, and can override location requirements with a written justification when GPS is unavailable. ### User Stories -#### Story 1: Check In to Shift with Location Verification +#### Story 1: View and Select Today's Shift **As a** worker -**I want to** register my arrival to a shift with automatic location verification \n**So that** I confirm my presence and initiate time tracking +**I want to** see my scheduled shifts for today and select which one I'm attending +**So that** I can clock in to the correct shift + +**Task Flow:** +1. Worker accesses the attendance tracking area +2. System loads the worker's shifts for the selected date (defaults to today) +3. Worker can navigate through a date strip spanning 3 days in the past, today, and 3 days ahead; only today is interactive +4. Each shift in the list shows: + - Role or position title + - Client name and venue location + - Scheduled start and end times + - Hourly rate +5. If already clocked in, the active shift is automatically highlighted +6. Otherwise, the most recent shift in the list is selected by default +7. Worker selects a shift to begin time-window and location verification for that venue + +**Information Required:** +- Shift selection (when multiple shifts are scheduled for the day) + +**Information Provided to User:** +- All shifts scheduled for today +- Which dates in the strip have shifts scheduled +- Which shift is currently active or selected + +**Edge Cases:** +- No shifts today: Message "No shifts scheduled today" with access to the shift marketplace +- Single shift: Auto-selected, no manual selection needed + +--- + +#### Story 2: Check In to Shift +**As a** worker +**I want to** register my arrival at a shift within the allowed time window +**So that** my work time is tracked from the moment I arrive ```mermaid graph TD - A[Start: Access Clock In] --> B[Load Today's Shifts] - B --> C{Multiple Shifts?} - C -->|Yes| D[Select Specific Shift] - C -->|No| E[Shift Auto-Selected] - D --> F[Request Location Permission] - E --> F - F --> G{Permission Granted?} - G -->|No| H[Error: Location Required] - G -->|Yes| I[Acquire Current Location] - I --> J[Calculate Distance from Venue] - J --> K{Within 500m?} - K -->|No| L[Warning: Too Far from Venue] - K -->|Yes| M[Enable Check-In] - M --> N{Confirmation Method?} - N -->|Swipe| O[Swipe Gesture Confirmation] - N -->|Action| P[Direct Confirmation] - O --> Q[Optional: Provide Check-In Notes] + A[Select Shift] --> B{Within Check-In Window?} + B -->|Too Early| C[Notice: Shows Time When Check-In Opens] + B -->|Window Open| D{GPS Permission?} + D -->|Denied| E[Permission Denied — Override Available] + D -->|Permanently Denied| F[Must Enable in Device Settings — Override Available] + D -->|Granted| G{GPS Service Enabled?} + G -->|Off| H[GPS Off — Override Available] + G -->|On| I[Acquiring Location — 30s Window] + I -->|Within 500m| J[Location Verified] + I -->|Outside 500m| K[Outside Geofence — Override Available] + I -->|Timeout| L[GPS Timeout — Retry or Override] + E --> M{Override with Justification?} + F --> M + H --> M + K --> M + L --> M + M -->|Submit Justification| J + M -->|Retry GPS| I + J --> N{Confirm Method?} + N -->|Swipe| O[Complete Swipe Gesture] + N -->|NFC| P[Complete NFC Tap] + O --> Q[Check-In Submitted] P --> Q - Q --> R[Submit Check-In] - R --> S[Success: Arrival Registered] - S --> T[Display Check-Out Capability
Show Break Logging
Show Commute Tracking] + Q --> R[Check-In Confirmed — Background Location Tracking Begins] ``` **Task Flow:** -1. User accesses attendance tracking area -2. System loads today's scheduled shifts -3. Shift selection:\n - If multiple shifts scheduled: User selects desired shift\n - If single shift: System auto-selects\n4. System requests location access permission (if not previously granted)\n5. User grants location access\n6. System acquires user's current geographical position\n7. System calculates distance from designated shift venue\n8. If within 500 meter radius:\n - Check-in capability becomes available\n - Distance information displayed (e.g., \"120m away\")\n9. User can register arrival via two methods:\n - **Gesture confirmation**: Swipe action across designated area\n - **Direct confirmation**: Direct action submission\n10. Optional notes interface appears (user can provide additional information or skip)\n11. User confirms arrival registration\n12. System confirms successful check-in: \"Checked in to [Shift Name]\"\n13. Interface updates to show:\n - Check-in timestamp\n - Break logging capability\n - Check-out capability\n - Optional: Commute tracking features\n\n**Information Required:**\n- Location permission (system request)\n- Shift selection (if multiple available)\n- Check-in confirmation (gesture or direct action)\n- Optional arrival notes (text)\n\n**Information Provided to User:**\n- Current distance from venue location\n- Location verification status\n- Check-in confirmation with precise timestamp\n- Updated interface showing departure registration capability\n\n**Edge Cases:**\n- **Location permission denied**: Error message \"Location access required to check in\" with guidance to device settings\n- **Distance exceeds threshold** (>500m): Warning \"You're too far from the venue. Move closer to check in.\" with actual distance displayed\n- **GPS signal unavailable**: Error \"Unable to determine location. Check your connection.\"\n- **Already registered arrival**: Display \"Already checked in at [time]\" with departure registration capability\n- **Incorrect shift selected**: User can modify selection before arrival confirmation\n- **Network connectivity issues**: Queue check-in for submission when connection restored - ---- - -#### Story 2: Log Break Time -**As a** worker -**I want to** record when I take breaks -**So that** my break time is accurately tracked and properly deducted from billable hours - -**Task Flow:** -1. User has registered arrival to shift -2. System displays break logging capability -3. User initiates break period recording -4. System displays running timer tracking break duration -5. User completes break and ends break period recording -6. System records total break duration -7. Optional: User can categorize break type (lunch, rest, etc.) +1. Worker selects a shift +2. System checks the current time against the shift's scheduled start time +3. If more than 15 minutes before shift start: check-in is not yet available; the time when it opens is displayed +4. Once within the check-in window, location verification begins automatically +5. System requests GPS permission if not already granted +6. GPS attempts to acquire the worker's current location (up to 30-second window) +7. System calculates distance from the shift's venue coordinates +8. If within 500 metres: check-in is enabled +9. If location cannot be verified (outside geofence, GPS timeout, permission issues): worker may provide a written justification to override — see Story 3 +10. With location verified or overridden, worker confirms check-in using one of two methods: + - **Swipe confirmation**: Drag a slider across at least 80% of its range + - **NFC confirmation**: Tap device to the NFC reader at the venue +11. System submits check-in to the backend +12. System confirms check-in with a timestamp +13. Background location tracking begins automatically for the duration of the shift **Information Required:** -- Break start (user-initiated) -- Break end (user-initiated) -- Optional: Break type classification +- GPS permission (system request) +- Shift selection (if multiple shifts today) +- Check-in confirmation (swipe gesture or NFC tap) **Information Provided to User:** -- Active break timer display -- Total break time recorded -- Confirmation of break logging +- Time window status: how long until check-in opens, or confirmation that it is open +- Location verification status and current distance from venue +- Check-in confirmation with exact timestamp +- Confirmation that background location tracking is now active **Edge Cases:** -- Forgot to end break: Capability to manually adjust break duration -- Multiple breaks: System tracks each break period independently with cumulative tracking -- System interruption: Break timer continues in background, recovers on re-access +- **Too early to check in**: Check-in unavailable; exact time when it becomes available is shown +- **GPS permission denied**: Worker can open device settings or use justification override +- **GPS permanently denied**: Worker must enable location in device settings; override also available +- **GPS service off**: Worker directed to enable device GPS; override also available +- **Outside geofence**: Distance from venue displayed; override with written justification permitted +- **GPS timeout (30 seconds)**: Worker can retry location check or use justification override +- **Already checked in**: Check-out flow shown instead; prior check-in time displayed --- -#### Story 3: Check Out of Shift +#### Story 3: Override Location Requirement **As a** worker -**I want to** register my departure from a shift -**So that** my work time is fully recorded for compensation +**I want to** clock in even when location verification cannot be completed +**So that** my attendance is recorded despite GPS issues beyond my control **Task Flow:** -1. User has registered arrival and completed work -2. User initiates departure registration -3. Optional notes interface appears -4. User provides additional information (if desired) or skips -5. User confirms departure -6. System verifies location again (same 500m proximity requirement) -7. System records departure timestamp -8. System calculates total work time (arrival - departure minus breaks) -9. System presents work summary displaying: - - Arrival time - - Departure time - - Total hours worked - - Break time deducted - - Estimated compensation (if available) - -**Information Required:**\n- Departure confirmation\n- Optional departure notes (text)\n- Location verification\n\n**Information Provided to User:**\n- Departure confirmation with precise timestamp\n- Comprehensive work summary (hours worked, breaks taken, estimated pay)\n- Complete time tracking information\n\n**Edge Cases:**\n- Departure distance exceeds venue threshold: Warning message but may allow with approval workflow\n- Forgot to register departure: Supervisor manual adjustment capability or automatic departure at scheduled shift end\n- Early departure: Warning \"Shift not yet complete. Confirm early check-out?\" with acknowledgment required\n- Network issues: Queue departure registration for submission when connected - ---- - -#### Story 4: Enable Commute Tracking -**As a** worker -**I want to** enable commute tracking -**So that** clients can monitor my estimated arrival time - -**Task Flow:** -1. After registering shift arrival, user sees commute tracking capability -2. User enables commute tracking -3. System begins continuous location monitoring -4. System calculates estimated time of arrival to venue -5. ETA information displayed to user and visible to client -6. System provides real-time updates of distance and ETA -7. When user proximity reaches venue (distance < 50m), system automatically disables commute mode +1. Location verification fails or cannot complete (permission denied, GPS off, outside 500m, or 30-second timeout) +2. System presents the reason for the location issue and an option to proceed without verification +3. Worker requests to proceed without location verification +4. System presents a written justification form +5. Worker provides a written explanation of why location verification is not possible +6. Justification must be non-empty before submission is allowed +7. Worker submits justification +8. System marks the attendance record as location-overridden and stores the justification note +9. Check-in confirmation (swipe or NFC) becomes available +10. Worker proceeds with normal check-in flow **Information Required:** -- Commute tracking preference (enabled/disabled) -- Continuous location updates +- Written justification (required; cannot be empty) **Information Provided to User:** +- Explanation of the location issue encountered +- Confirmation that the override justification has been recorded +- Confirmation that check-in can now proceed + +**Edge Cases:** +- Empty justification: Submission is prevented until text is provided +- Justification is stored alongside the attendance record for administrative review + +--- + +#### Story 4: Check Out with Break Details +**As a** worker +**I want to** record my departure and any break taken during my shift +**So that** my total worked hours and compensation are calculated accurately + +**Task Flow:** +1. Worker has previously checked in and is within the check-out time window (within 15 minutes of shift end) +2. If attempting to check out too early: check-out is not yet available; the time when it opens is displayed +3. Same location verification and override rules apply as check-in (Story 2 and Story 3) +4. Worker confirms check-out using swipe or NFC (same methods as check-in) +5. System presents a multi-step break details form: + - **Step 1**: Did you take a lunch break? (Yes / No) + - **Step 2a — if Yes**: Select break start time and break end time (available in 15-minute increments) + - **Step 2b — if No**: Select the reason no break was taken (from a predefined list) + - **Step 3**: Optional additional notes about the shift + - **Step 4**: Review summary of all submitted details +6. Worker confirms the summary +7. System submits check-out and break information to the backend +8. System confirms shift is complete +9. Background location tracking stops automatically + +**Information Required:** +- Check-out confirmation (swipe gesture or NFC tap) +- Break taken: Yes or No +- If Yes: break start time and break end time (15-minute increments) +- If No: reason for no break (selection from predefined options) +- Optional: additional shift notes + +**Information Provided to User:** +- Time window status (when check-out becomes available, or confirmed open) +- Break detail form with step-by-step guidance +- Summary of all submitted information before final confirmation +- Check-out confirmation with exact timestamp +- Shift completion status + +**Edge Cases:** +- **Too early to check out**: Check-out unavailable; exact time when it becomes available is shown +- **Geofence and override rules**: Same location verification and override flow as check-in applies +- **Break time selection**: Times are chosen from 15-minute slot options, not free-text entry +- **Network issue**: Check-out request queued for submission when connection is restored + +--- + +#### Story 5: Track Commute to Shift +**As a** worker +**I want to** share my estimated arrival time before a shift +**So that** the client knows when to expect me + +**Task Flow:** +1. Before a shift begins, the system offers commute tracking +2. Worker consents to sharing commute location data +3. System monitors the worker's distance to the venue and calculates estimated time of arrival +4. ETA information is made visible to the client +5. Worker is shown their current distance to the venue and estimated arrival time +6. When the worker arrives within range of the venue, commute tracking automatically deactivates + +**Information Required:** +- Consent to share commute location + +**Information Provided to User:** +- Current distance to the shift venue - Estimated arrival time (e.g., "Arriving in 12 minutes") -- Distance to venue (e.g., "2.3 km away") -- Real-time progress updates +- Confirmation when commute tracking deactivates upon arrival **Edge Cases:** -- Location tracking interruption: System displays last known position -- Arrival but ETA persisting: Auto-clears when within 50m proximity -- Privacy preference: User can disable tracking at any time -- Route changes: ETA automatically recalculates based on current position +- Location permission required for commute tracking to function +- Worker can withdraw consent and disable commute tracking at any time +- Route changes cause estimated arrival time to automatically recalculate ---