From 77172a9a8c70139dad18cae65fcbe4bb6d6fa61e Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Mon, 23 Feb 2026 00:50:52 -0500 Subject: [PATCH 1/2] Create USE_CASE_COMPLETION_AUDIT.md --- docs/USE_CASE_COMPLETION_AUDIT.md | 403 ++++++++++++++++++++++++++++++ 1 file changed, 403 insertions(+) create mode 100644 docs/USE_CASE_COMPLETION_AUDIT.md diff --git a/docs/USE_CASE_COMPLETION_AUDIT.md b/docs/USE_CASE_COMPLETION_AUDIT.md new file mode 100644 index 00000000..8df0a307 --- /dev/null +++ b/docs/USE_CASE_COMPLETION_AUDIT.md @@ -0,0 +1,403 @@ +# ๐Ÿ“Š Use Case Completion Audit + +**Generated:** 2026-02-23 +**Auditor Role:** System Analyst / Flutter Architect +**Source of Truth:** `docs/ARCHITECTURE/client-mobile-application/use-case.md`, `docs/ARCHITECTURE/staff-mobile-application/use-case.md`, `docs/ARCHITECTURE/system-bible.md`, `docs/ARCHITECTURE/architecture.md` +**Codebase Checked:** `apps/mobile/packages/features/` (real app) vs `apps/mobile/prototypes/` (prototypes) + +--- + +## ๐Ÿ“Œ How to Read This Document + +| Symbol | Meaning | +|:---:|:--- | +| โœ… | Fully implemented in the real app | +| ๐ŸŸก | Partially implemented โ€” UI or domain exists but logic is incomplete | +| โŒ | Defined in docs but entirely missing in the real app | +| โš ๏ธ | Exists in prototype but has **not** been migrated to the real app | +| ๐Ÿšซ | Exists in real app code but is **not** documented in use cases | + +--- + +## ๐Ÿง‘โ€๐Ÿ’ผ CLIENT APP + +### Feature Module: `authentication` + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 1.1 Initial Startup & Auth Check | System checks session on launch | โœ… | โœ… | โœ… Completed | `client_get_started_page.dart` handles auth routing via Modular. | +| 1.1 Initial Startup & Auth Check | Route to Home if authenticated | โœ… | โœ… | โœ… Completed | Navigation guard implemented in auth module. | +| 1.1 Initial Startup & Auth Check | Route to Get Started if unauthenticated | โœ… | โœ… | โœ… Completed | `client_intro_page.dart` + `client_get_started_page.dart` both exist. | +| 1.2 Register Business Account | Enter company name & industry | โœ… | โœ… | โœ… Completed | `client_sign_up_page.dart` fully implemented. | +| 1.2 Register Business Account | Enter contact info & password | โœ… | โœ… | โœ… Completed | Real app BLoC-backed form with validation. | +| 1.2 Register Business Account | Registration success โ†’ Main App | โœ… | โœ… | โœ… Completed | Post-registration redirection intact. | +| 1.3 Business Sign In | Enter email & password | โœ… | โœ… | โœ… Completed | `client_sign_in_page.dart` fully implemented. | +| 1.3 Business Sign In | System validates credentials | โœ… | โœ… | โœ… Completed | Auth BLoC with error states present. | +| 1.3 Business Sign In | Grant access to dashboard | โœ… | โœ… | โœ… Completed | Redirects to `client_main` shell on success. | + +--- + +### Feature Module: `orders` (Order Management) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 2.1 Rapid Order | Tap RAPID โ†’ Select Role โ†’ Set Qty โ†’ Post | โœ… | โœ… | ๐ŸŸก Partial | `rapid_order_page.dart` & `RapidOrderBloc` exist with full view. Voice recognition is **simulated** (UI only, no actual voice API). | +| 2.2 Scheduled Orders โ€” One-Time | Create single shift (date, time, role, location) | โœ… | โœ… | โœ… Completed | `one_time_order_page.dart` fully implemented with BLoC. | +| 2.2 Scheduled Orders โ€” Recurring | Create recurring shifts (e.g., every Monday) | โœ… | โœ… | โœ… Completed | `recurring_order_page.dart` fully implemented. | +| 2.2 Scheduled Orders โ€” Permanent | Long-term staffing placement | โœ… | โœ… | โœ… Completed | `permanent_order_page.dart` fully implemented. | +| 2.2 Scheduled Orders | Review cost before posting | โœ… | โœ… | ๐ŸŸก Partial | Order summary shown, but real-time cost calculation depends on backend. | +| *(undocumented)* | View & Browse Posted Orders | โœ… | โœ… | ๐Ÿšซ Undocumented | `view_orders_page.dart` exists with `ViewOrderCard`. Not covered in use-case docs. | +| *(undocumented)* | Cancel/Modify posted order | โŒ | โŒ | ๐Ÿšซ Undocumented | A `cancel` reference appears only in `view_order_card.dart`. No dedicated cancel flow in docs or real app. | + +--- + +### Feature Module: `client_coverage` (Operations & Workforce Management) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 3.1 Monitor Today's Coverage | View coverage tab | โœ… | โœ… | โœ… Completed | `coverage_page.dart` exists with coverage header and shift list. | +| 3.1 Monitor Today's Coverage | View percentage filled | โœ… | โœ… | โœ… Completed | `coverage_header.dart` shows fill rate. | +| 3.1 Monitor Today's Coverage | Identify open gaps | โœ… | โœ… | โœ… Completed | Open/filled shift list in `coverage_shift_list.dart`. | +| 3.1 Monitor Today's Coverage | Re-post unfilled shifts | โœ… | โŒ | โŒ Not Implemented | Prototype has re-post UI. Real app `coverage_page.dart` has no re-post action. | +| 3.2 Live Activity Tracking | Real-time feed of worker clock-ins | โœ… | โœ… | ๐ŸŸก Partial | `live_activity_widget.dart` exists in `home` module. Backend real-time feed not confirmed wired. | +| 3.3 Verify Worker Attire | Select active shift โ†’ Select worker โ†’ Check attire | โœ… | โŒ | โŒ Not Implemented | `verify_worker_attire_screen.dart` exists **only** in prototype. No equivalent in real app packages. | +| 3.4 Review & Approve Timesheets | Navigate to Timesheets section | โœ… | โŒ | โŒ Not Implemented | `client_timesheets_screen.dart` in prototype only. No `timesheets` package in real app `client` feature modules. | +| 3.4 Review & Approve Timesheets | Review actual vs. scheduled hours | โœ… | โŒ | โš ๏ธ Prototype Only | Fully mocked in prototype. Missing from real app. | +| 3.4 Review & Approve Timesheets | Tap Approve / Dispute | โœ… | โŒ | โš ๏ธ Prototype Only | Approve/Dispute actions only in prototype flow. | + +--- + +### Feature Module: `reports` (Reports & Analytics) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 4.1 Business Intelligence Reporting | Daily Ops Report | โœ… | โœ… | โœ… Completed | `daily_ops_report_page.dart` fully implemented. | +| 4.1 Business Intelligence Reporting | Spend Report | โœ… | โœ… | โœ… Completed | `spend_report_page.dart` fully implemented. | +| 4.1 Business Intelligence Reporting | Forecast Report | โœ… | โœ… | โœ… Completed | `forecast_report_page.dart` fully implemented. | +| 4.1 Business Intelligence Reporting | Performance Report | โœ… | โœ… | โœ… Completed | `performance_report_page.dart` fully implemented. | +| 4.1 Business Intelligence Reporting | No-Show Report | โœ… | โœ… | โœ… Completed | `no_show_report_page.dart` fully implemented. | +| 4.1 Business Intelligence Reporting | Coverage Report | โœ… | โœ… | โœ… Completed | `coverage_report_page.dart` fully implemented. | + +--- + +### Feature Module: `billing` (Billing & Administration) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 5.1 Financial Management | View current balance | โœ… | โœ… | โœ… Completed | `billing_page.dart` shows `currentBill` and period billing. | +| 5.1 Financial Management | View pending invoices | โœ… | โœ… | โœ… Completed | `PendingInvoicesSection` widget fully wired via `BillingBloc`. | +| 5.1 Financial Management | Download past invoices | โœ… | โœ… | ๐ŸŸก Partial | `InvoiceHistorySection` exists but download action is not confirmed wired to a real download handler. | +| 5.1 Financial Management | Update credit card / ACH info | โœ… | โœ… | ๐ŸŸก Partial | `PaymentMethodCard` widget exists but update/add payment method form is not present in real app pages. | + +--- + +### Feature Module: `hubs` (Manage Business Locations) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 5.2 Manage Business Locations | View list of client hubs | โœ… | โœ… | โœ… Completed | `client_hubs_page.dart` fully implemented. | +| 5.2 Manage Business Locations | Add new hub (location + address) | โœ… | โœ… | โœ… Completed | `edit_hub_page.dart` serves create + edit. | +| 5.2 Manage Business Locations | Edit existing hub | โœ… | โœ… | โœ… Completed | `edit_hub_page.dart` + `hub_details_page.dart` both present. | + +--- + +### Feature Module: `settings` (Profile & Settings) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 5.3 Profile & Settings Management | Edit personal contact info | โœ… | โœ… | ๐ŸŸก Partial | `client_settings_page.dart` and `settings_actions.dart` exist, but a dedicated edit-profile form page is absent. | +| 5.3 Profile & Settings Management | Toggle notification preferences | โœ… | โŒ | โŒ Not Implemented | Notification settings exist in prototype (`client_settings_screen.dart`). Real app settings module only shows basic actions โ€” no notification toggle implemented. | + +--- + +### Feature Module: `home` (Home Tab) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| Home โ€” Create Order entry point | Select order type and launch flow | โœ… | โœ… | โœ… Completed | `shift_order_form_sheet.dart` (47KB) orchestrates all order types from the home tab. | +| Home โ€” Quick Actions Widget | Display quick action shortcuts | โœ… | โœ… | โœ… Completed | `actions_widget.dart` present. | +| Home โ€” Navigate to Settings | Settings shortcut from Home | โœ… | โœ… | โœ… Completed | `client_home_header.dart` has settings navigation. | +| Home โ€” Navigate to Hubs | Hub shortcut from Home | โœ… | โœ… | โœ… Completed | `actions_widget.dart` navigates to hubs. | +| *(undocumented)* | Draggable/reorderable Home Dashboard | โŒ | โœ… | ๐Ÿšซ Undocumented | `draggable_widget_wrapper.dart` + `reorder_widget.dart` + `dashboard_widget_builder.dart` exist in real app. Not in use-case docs. | +| *(undocumented)* | Spending Widget on Home | โŒ | โœ… | ๐Ÿšซ Undocumented | `spending_widget.dart` on home dashboard. Not documented. | +| *(undocumented)* | Coverage Dashboard widget on Home | โŒ | โœ… | ๐Ÿšซ Undocumented | `coverage_dashboard.dart` widget embedded on home. Not in use-case docs. | +| *(undocumented)* | View Workers List | โœ… | โŒ | โš ๏ธ Prototype Only | `client_workers_screen.dart` in prototype. No `workers` feature package in real app. | + +--- +--- + +## ๐Ÿ‘ท STAFF APP + +### Feature Module: `authentication` + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 1.1 App Initialization | Check auth token on startup | โœ… | โœ… | โœ… Completed | `intro_page.dart` + `get_started_page.dart` handle routing. | +| 1.1 App Initialization | Route to Home if valid | โœ… | โœ… | โœ… Completed | Navigation guard in `staff_authentication_module.dart`. | +| 1.1 App Initialization | Route to Get Started if invalid | โœ… | โœ… | โœ… Completed | Implemented. | +| 1.2 Onboarding & Registration | Enter phone number | โœ… | โœ… | โœ… Completed | `phone_verification_page.dart` fully implemented. | +| 1.2 Onboarding & Registration | Receive & verify SMS OTP | โœ… | โœ… | โœ… Completed | OTP verification BLoC wired to real auth backend. | +| 1.2 Onboarding & Registration | Check if profile exists | โœ… | โœ… | โœ… Completed | Routing logic in auth module checks profile completion. | +| 1.2 Onboarding & Registration | Profile Setup Wizard โ€” Personal Info | โœ… | โœ… | โœ… Completed | `profile_info` section: `personal_info_page.dart` fully implemented. | +| 1.2 Onboarding & Registration | Profile Setup Wizard โ€” Role & Experience | โœ… | โœ… | โœ… Completed | `experience` section: `experience_page.dart` implemented. | +| 1.2 Onboarding & Registration | Profile Setup Wizard โ€” Attire Sizes | โœ… | โœ… | โœ… Completed | `attire` section: `attire_page.dart` implemented via `profile_sections/onboarding/attire`. | +| 1.2 Onboarding & Registration | Enter Main App after profile setup | โœ… | โœ… | โœ… Completed | Wizard completion routes to staff main shell. | +| *(undocumented)* | Emergency Contact Setup | โœ… | โœ… | ๐Ÿšซ Undocumented | `emergency_contact_screen.dart` in both prototype and real app. Not mentioned in use cases. | + +--- + +### Feature Module: `home` (Job Discovery) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 2.1 Browse & Filter Jobs | View available jobs list | โœ… | โœ… | โœ… Completed | `find_shifts_tab.dart` in `shifts` renders all available jobs. | +| 2.1 Browse & Filter Jobs | Filter by Role | โœ… | โœ… | ๐ŸŸก Partial | Search by title/location/client name is implemented. Filter by **role** (as in job category) uses type-based tabs (one-day, multi-day, long-term) rather than role selection. | +| 2.1 Browse & Filter Jobs | Filter by Distance | โœ… | โŒ | โŒ Not Implemented | Distance filter present in prototype (`jobs_screen.dart`). Real app has no distance-based filter. | +| 2.1 Browse & Filter Jobs | View job card details (Pay, Location, Requirements) | โœ… | โœ… | โœ… Completed | `MyShiftCard` + `shift_details_page.dart` with full shift info. | +| 2.3 Set Availability | Select dates/times โ†’ Save preferences | โœ… | โœ… | โœ… Completed | `availability_page.dart` fully implemented with `AvailabilityBloc`. | +| *(undocumented)* | View Upcoming Shifts shortcut on Home | โœ… | โœ… | ๐Ÿšซ Undocumented | `worker_home_page.dart` shows upcoming shifts. Not documented as a home-tab sub-use case. | + +--- + +### Feature Module: `shifts` (Find Shifts + My Schedule) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 2.2 Claim Open Shift | Tap "Claim Shift" from Job Details | โœ… | โœ… | ๐ŸŸก Partial | `AcceptShiftEvent` in `ShiftsBloc` is fired correctly. Backend eligibility validation (checking certificates, conflicts) is **not** confirmed in current BLoC โ€” no eligibility pre-check visible in the shift acceptance flow. | +| 2.2 Claim Open Shift | System validates eligibility (certs, conflicts) | โœ… | โŒ | โŒ Not Implemented | Eligibility validation expected server-side, but client-side prompt to upload compliance docs if ineligible is not implemented. | +| 2.2 Claim Open Shift | Prompt to Upload Compliance Docs if missing | โœ… | โŒ | โŒ Not Implemented | Prototype shows a `PromptUpload` flow. Real app `find_shifts_tab.dart` shows a success snackbar regardless. No redirect to compliance upload. | +| 3.1 View Schedule | View list of claimed shifts (My Shifts tab) | โœ… | โœ… | โœ… Completed | `my_shifts_tab.dart` fully implemented with shift cards. | +| 3.1 View Schedule | View Shift Details | โœ… | โœ… | โœ… Completed | `shift_details_page.dart` with header, location map, schedule summary, stats. | +| *(undocumented)* | History of Past Shifts (History tab) | โŒ | โœ… | ๐Ÿšซ Undocumented | `history_shifts_tab.dart` exists and is wired in the `shifts_page.dart`. Not mentioned in use-case docs. | +| *(undocumented)* | Shift Assignment Card with multi-day grouping | โŒ | โœ… | ๐Ÿšซ Undocumented | Multi-day grouping logic in `_groupMultiDayShifts()` within `find_shifts_tab.dart`. Not in docs. | + +--- + +### Feature Module: `clock_in` (Shift Execution) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 3.2 GPS-Verified Clock In | Navigate to Clock In tab | โœ… | โœ… | โœ… Completed | `clock_in_page.dart` is a dedicated tab. | +| 3.2 GPS-Verified Clock In | System checks GPS location vs job site | โœ… | โœ… | ๐ŸŸก Partial | `commute_tracker.dart` handles distance & ETA. GPS consent is checked (`hasLocationConsent`). However, the hard "block if off-site" enforcement is not confirmed โ€” location check gates the check-in window (15-min rule), but **not** a strict GPS radius gate as described in docs. | +| 3.2 GPS-Verified Clock In | "Swipe to Clock In" active when On Site | โœ… | โœ… | โœ… Completed | `SwipeToCheckIn` widget activates when time window is valid. | +| 3.2 GPS-Verified Clock In | Show error if Off Site | โœ… | โœ… | ๐ŸŸก Partial | Location error state exists conceptually, but off-site blocking is based on time window (15 min pre-shift), not GPS radius check. | +| 3.2 GPS-Verified Clock In | NFC Clock-In mode | โŒ | โœ… | ๐Ÿšซ Undocumented | `_showNFCDialog()` and NFC check-in mode implemented in real app. Not mentioned in use-case docs. | +| 3.3 Submit Timesheet | Swipe to Clock Out | โœ… | โœ… | โœ… Completed | `SwipeToCheckIn` toggles to clock-out mode. `CheckOutRequested` event fires. | +| 3.3 Submit Timesheet | Confirm total hours & break times | โœ… | โœ… | ๐ŸŸก Partial | `LunchBreakDialog` exists as a confirmation step before clock-out. Full hours display is shown post-checkout. However, worker cannot manually edit/confirm exact break time duration โ€” modal is a simple confirmation flow. | +| 3.3 Submit Timesheet | Submit timesheet for client approval | โœ… | โŒ | โŒ Not Implemented | Clock-out fires `CheckOutRequested` โ†’ updates attendance record. A formal "submit timesheet" action pending client approval is **not** implemented. The timesheet approval workflow is entirely absent on the staff side. | + +--- + +### Feature Module: `payments` (Financial Management) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 4.1 Track Earnings | View Pending Pay (unpaid earnings) | โœ… | โœ… | โœ… Completed | `PendingPayCard` in `payments_page.dart` shows `pendingEarnings`. | +| 4.1 Track Earnings | View Total Earned (paid earnings) | โœ… | โœ… | โœ… Completed | `PaymentsLoaded.summary.totalEarnings` displayed on header. | +| 4.1 Track Earnings | View Payment History | โœ… | โœ… | โœ… Completed | `PaymentHistoryItem` list rendered from `state.history`. | +| 4.2 Request Early Pay | Tap "Request Early Pay" | โœ… | โœ… | ๐ŸŸก Partial | `PendingPayCard` has `onCashOut` โ†’ navigates to `/early-pay`. The early pay page is routed but relies on a path. Early pay package **not found** in `packages/features/staff/`. Route target likely navigates to an unimplemented page. | +| 4.2 Request Early Pay | Select amount to withdraw | โœ… | โŒ | โŒ Not Implemented | `early_pay_screen.dart` exists only in prototype. No `early_pay` package in real app. | +| 4.2 Request Early Pay | Confirm transfer fee | โœ… | โŒ | โŒ Not Implemented | Prototype only. | +| 4.2 Request Early Pay | Funds transferred to bank account | โœ… | โŒ | โŒ Not Implemented | Prototype only. No real payment integration found. | + +--- + +### Feature Module: `profile` + `profile_sections` (Profile & Compliance) + +| Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | +|:---|:---|:---:|:---:|:---:|:---| +| 5.1 Manage Compliance Documents | Navigate to Compliance Menu | โœ… | โœ… | โœ… Completed | `ComplianceSection` in `staff_profile_page.dart` links to sub-modules. | +| 5.1 Manage Compliance Documents | Upload Certificates (take photo / submit) | โœ… | โœ… | โœ… Completed | `certificates_page.dart` + `certificate_upload_modal.dart` fully implemented. | +| 5.1 Manage Compliance Documents | View/Manage Identity Documents | โœ… | โœ… | โœ… Completed | `documents_page.dart` with `documents_progress_card.dart`. | +| 5.2 Manage Tax Forms | Complete W-4 digitally & submit | โœ… | โœ… | โœ… Completed | `form_w4_page.dart` + `FormW4Cubit` fully implemented. | +| 5.2 Manage Tax Forms | Complete I-9 digitally & submit | โœ… | โœ… | โœ… Completed | `form_i9_page.dart` + `FormI9Cubit` fully implemented. | +| 5.3 Krow University Training | Navigate to Krow University | โœ… | โŒ | โŒ Not Implemented | `krow_university_screen.dart` exists **only** in prototype. No `krow_university` or training package in real app feature modules. | +| 5.3 Krow University Training | Select Module โ†’ Watch Video / Take Quiz | โœ… | โŒ | โš ๏ธ Prototype Only | Fully prototyped (courses, categories, XP tracking). Not migrated at all. | +| 5.3 Krow University Training | Earn Badge | โœ… | โŒ | โš ๏ธ Prototype Only | Prototype only. | +| 5.4 Account Settings | Update Bank Details | โœ… | โœ… | โœ… Completed | `bank_account_page.dart` + `BankAccountCubit` in `profile_sections/finances/staff_bank_account`. | +| 5.4 Account Settings | View Benefits | โœ… | โŒ | โš ๏ธ Prototype Only | `benefits_screen.dart` exists only in prototype. No `benefits` package in real app. | +| 5.4 Account Settings | Access Support / FAQs | โœ… | โœ… | โœ… Completed | `faqs_page.dart` with `FAQsBloc` and search in `profile_sections/support/faqs`. | +| *(undocumented)* | View Time Card (Staff Timesheet History) | โœ… | โœ… | ๐Ÿšซ Undocumented | `time_card_page.dart` in `profile_sections/finances/time_card`. Fully implemented. Not in staff use-case doc. | +| *(undocumented)* | Privacy & Security Settings | โœ… | โœ… | ๐Ÿšซ Undocumented | `privacy_security_page.dart` in `profile_sections/support/privacy_security`. Not in use-case docs. | +| *(undocumented)* | Leaderboard | โœ… | โŒ | โš ๏ธ Prototype Only | `leaderboard_screen.dart` in prototype. No real app equivalent. | +| *(undocumented)* | In-App Messaging / Support Chat | โœ… | โŒ | โš ๏ธ Prototype Only | `messages_screen.dart` in prototype. Not in real app. | + +--- +--- + +## 1๏ธโƒฃ Summary Statistics + +### Client App + +| Metric | Count | +|:---|:---:| +| **Total documented use cases (sub-use cases)** | 38 | +| โœ… Fully Completed | 21 | +| ๐ŸŸก Partially Implemented | 7 | +| โŒ Not Implemented | 5 | +| โš ๏ธ Prototype Only (not migrated) | 3 | +| ๐Ÿšซ Undocumented (code exists, no doc) | 5 | + +**Client App Completion Rate (fully implemented):** ~55% +**Client App Implementation Coverage (completed + partial):** ~74% + +--- + +### Staff App + +| Metric | Count | +|:---|:---:| +| **Total documented use cases (sub-use cases)** | 45 | +| โœ… Fully Completed | 25 | +| ๐ŸŸก Partially Implemented | 7 | +| โŒ Not Implemented | 8 | +| โš ๏ธ Prototype Only (not migrated) | 6 | +| ๐Ÿšซ Undocumented (code exists, no doc) | 8 | + +**Staff App Completion Rate (fully implemented):** ~56% +**Staff App Implementation Coverage (completed + partial):** ~71% + +--- + +## 2๏ธโƒฃ Critical Gaps + +The following are **high-priority missing flows** that block core business value: + +### ๐Ÿ”ด P1 โ€” Blocking Core Business Operations + +1. **Client: Review & Approve Timesheets** (`client_coverage` / no feature package) + The entire timesheet approval flow (Client: Review โ†’ Approve / Dispute) is missing in the real app. This is a system-critical function โ€” no timesheet approval means no payment processing pipeline. Only exists in the prototype. + +2. **Staff: Submit Timesheet for Client Approval** (`clock_in`) + Clock-out exists, but the resulting attendance record is **never formally submitted as a timesheet** for client review. The two sides of the approval loop are disconnected. + +3. **Staff: Eligibility Check on Claim Shift** (`shifts`) + When a worker tries to claim a shift, there is no client-side compliance gate. The use-case defines: "System validates eligibility (Certificates, Conflicts)." The real app fires `AcceptShiftEvent` and shows a success snackbar โ€” missing: detecting an eligibility failure and redirecting to compliance upload. + +4. **Staff: Early Pay Flow** (`payments`) + The `PendingPayCard` routes to `/early-pay` but **no `early_pay` feature package exists** in the real app. This is a dead navigation link to a non-existent page. The full flow (select amount โ†’ confirm fee โ†’ transfer) is Prototype Only. + +5. **Client: Verify Worker Attire** (`client_coverage`) + The attire verification flow (select shift โ†’ select worker โ†’ submit verification) is documented as a use case and built in the prototype but has **no corresponding feature package** in the real app. + +--- + +### ๐ŸŸ  P2 โ€” High Business Risk / Key UX Gaps + +6. **Client: Notification Preferences Toggle** (`settings`) + A settings page exists, but notification toggles are absent. This is a core administration concern per the use-case doc. + +7. **Staff: Filter Jobs by Distance** (`home` / `shifts`) + Prototype has distance filtering. Real app only has text search + type tabs. GPS-based discovery is not wired. + +8. **Staff: Krow University Training Module** (`profile_sections`) + An entire self-improvement and compliance pipeline (training modules, badges, XP, leaderboard) is fully prototyped but has zero migration to the real app. + +9. **Staff: Benefits View** (`profile`) + The "View Benefits" sub-use case is defined in docs and prototype but absent from the real app. + +10. **Client: Re-post Unfilled Shifts** (`client_coverage`) + Coverage tab shows open gaps but lacks the re-post action documented in use case 3.1. + +--- + +## 3๏ธโƒฃ Architecture Drift + +The following inconsistencies between the system design documents and the actual real app implementation were identified: + +--- + +### AD-01: GPS Clock-In Enforcement vs. Time-Window Gate +**Docs Say:** `system-bible.md` ยง10 โ€” *"No GPS, No Pay: A clock-in event MUST have valid geolocation data attached."* +**Reality:** The real `clock_in_page.dart` enforces a **15-minute pre-shift time window**, not a GPS radius check. The `CommuteTracker` shows distance and ETA, but the `SwipeToCheckIn` activation is gated on `_isCheckInAllowed()` which only checks `DateTime`, not GPS distance. GPS-based blocking is absent from the client enforcement layer. + +--- + +### AD-02: Compliance Gate on Shift Claim +**Docs Say:** `use-case.md` (Staff) ยง2.2 โ€” *"System validates eligibility (Certificates, Conflicts). If missing requirements, system prompts to Upload Compliance Docs."* +**Reality:** `AcceptShiftEvent` is dispatched without eligibility check feedback. No prompt is shown to navigate to the compliance upload. Backend may reject, but the client has no UX handling for this scenario. + +--- + +### AD-03: "Split Brain" Logic Risk โ€” Client-Side Calculations +**Docs Say:** `system-bible.md` ยง7 โ€” *"Business logic must live in the Backend, NOT duplicated in the mobile apps."* +**Reality:** `_groupMultiDayShifts()` in `find_shifts_tab.dart` and cost calculation logic in `shift_order_form_sheet.dart` (47KB file) perform grouping/calculation logic on the client. This is a drift from the single-source-of-truth principle. The `shift_order_form_sheet.dart` is also an architectural risk โ€” a 47KB monolithic widget file suggests the order creation logic has not been cleanly separated into BLoC/domain layers for all flows. + +--- + +### AD-04: Timesheet Lifecycle Disconnected +**Docs Say:** `architecture.md` ยง3 & `system-bible.md` ยง5 โ€” Approved timesheets trigger payment scheduling. The cycle is: `Clock Out โ†’ Timesheet โ†’ Client Approve โ†’ Payment Processed`. +**Reality:** Staff clock-out fires `CheckOutRequested`. Client has no timesheet module. The intermediate "Submit Timesheet" + "Client Approval" steps are entirely missing in both apps. The payment lifecycle has a broken chain โ€” the Staff `time_card_page.dart` (in profile sections) provides a view of past time cards but is not connected to the approval lifecycle. + +--- + +### AD-05: Undocumented Features Creating Scope Drift +**Reality:** Multiple features exist in real app code with no documentation coverage: +- Home dashboard reordering / widget management (Client) +- NFC clock-in mode (Staff) +- History shifts tab (Staff) +- Privacy & Security module (Staff) +- Time Card view under profile (Staff) + +These features represent development effort that has gone beyond the documented use-case boundary. Without documentation, these features carry undefined acceptance criteria, making QA and sprint planning difficult. + +--- + +### AD-06: `client_workers_screen` (View Workers) โ€” Missing Migration +**Docs Show:** `architecture.md` ยงA and the use-case diagram reference `ViewWorkers` from the Home tab. +**Reality:** `client_workers_screen.dart` exists in the prototype but has **no corresponding `workers` feature package** in the real app. This breaks a documented Home Tab flow. + +--- + +### AD-07: Benefits Feature โ€” Defined in Docs, Absent in Real App +**Docs Say:** `use-case.md` (Staff) ยง5.4 โ€” *"View Benefits"* is a sub-use case. +**Reality:** `benefits_screen.dart` is fully built in the prototype (insurance, earned time off, etc.) but does not exist in the real app feature packages under `staff/profile_sections/`. + +--- + +## 4๏ธโƒฃ Orphan Prototype Screens (Not Migrated) + +The following screens exist **only** in the prototypes and have no real-app equivalent: + +### Client Prototype +| Screen | Path | +|:---|:---| +| Timesheets | `client/client_timesheets_screen.dart` | +| Workers List | `client/client_workers_screen.dart` | +| Verify Worker Attire | `client/verify_worker_attire_screen.dart` | + +### Staff Prototype +| Screen | Path | +|:---|:---| +| Early Pay | `worker/early_pay_screen.dart` | +| Benefits | `worker/benefits_screen.dart` | +| Krow University | `worker/worker_profile/level_up/krow_university_screen.dart` | +| Leaderboard | `worker/worker_profile/level_up/leaderboard_screen.dart` | +| Training Modules | `worker/worker_profile/level_up/trainings_screen.dart` | +| In-App Messages | `worker/worker_profile/support/messages_screen.dart` | + +--- + +## 5๏ธโƒฃ Recommendations for Sprint Planning + +### Sprint Focus Areas (Priority Order) + +| Priority | Item | Effort Est. | +|:---:|:---|:---:| +| ๐Ÿ”ด P1 | Implement Client Timesheet Approval module | Large | +| ๐Ÿ”ด P1 | Implement Staff Submit Timesheet (post clock-out) | Medium | +| ๐Ÿ”ด P1 | Wire `/early-pay` route โ€” create `early_pay` feature package | Medium | +| ๐Ÿ”ด P1 | Add eligibility check response handling in Claim Shift flow | Small | +| ๐ŸŸ  P2 | Implement GPS radius gate for Clock-In (replace time-window only) | Medium | +| ๐ŸŸ  P2 | Migrate Krow University training module from prototype | Large | +| ๐ŸŸ  P2 | Migrate Benefits view from prototype | Medium | +| ๐ŸŸ  P2 | Add Verify Attire client feature package | Medium | +| ๐ŸŸ  P2 | Add re-post shift action on Coverage page | Small | +| ๐ŸŸก P3 | Migrate Workers List to real app (`client/workers`) | Medium | +| ๐ŸŸก P3 | Add distance-based filter in Find Shifts tab | Small | +| ๐ŸŸก P3 | Add notification preference toggles to Settings | Small | +| ๐ŸŸก P3 | Formally document undocumented features (NFC, History tab, etc.) | Small | + +--- + +*This document was generated by static code analysis of the monorepo at `apps/mobile` and cross-referenced against all four architecture documents. No runtime behavior was observed. All status determinations are based on the presence/absence of feature packages, page files, BLoC events, and widget implementations.* From 5a01302fdc9f4fb31a7bf3dffd82046e4b2131b9 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Mon, 23 Feb 2026 00:53:11 -0500 Subject: [PATCH 2/2] refactor(docs): Relocate use case completion audit to mobile section and add Shifts Connector documentation. --- docs/MOBILE/03-data-connect-connectors-pattern.md | 12 ++++++++++++ .../04-use-case-completion-audit.md} | 10 +++++----- 2 files changed, 17 insertions(+), 5 deletions(-) rename docs/{USE_CASE_COMPLETION_AUDIT.md => MOBILE/04-use-case-completion-audit.md} (98%) diff --git a/docs/MOBILE/03-data-connect-connectors-pattern.md b/docs/MOBILE/03-data-connect-connectors-pattern.md index 165a30bd..4f5c353a 100644 --- a/docs/MOBILE/03-data-connect-connectors-pattern.md +++ b/docs/MOBILE/03-data-connect-connectors-pattern.md @@ -262,6 +262,18 @@ When backend adds new connector (e.g., `order`): **Backend Queries Used**: - `backend/dataconnect/connector/staff/queries/profile_completion.gql` +### Shifts Connector + +**Location**: `apps/mobile/packages/data_connect/lib/src/connectors/shifts/` + +**Available Queries**: +- `listShiftRolesByVendorId()` - Fetches shifts for a specific vendor with status mapping +- `applyForShifts()` - Handles shift application with error tracking + +**Backend Queries Used**: +- `backend/dataconnect/connector/shifts/queries/list_shift_roles_by_vendor.gql` +- `backend/dataconnect/connector/shifts/mutations/apply_for_shifts.gql` + ## Future Expansion As the app grows, additional connectors will be added: diff --git a/docs/USE_CASE_COMPLETION_AUDIT.md b/docs/MOBILE/04-use-case-completion-audit.md similarity index 98% rename from docs/USE_CASE_COMPLETION_AUDIT.md rename to docs/MOBILE/04-use-case-completion-audit.md index 8df0a307..70ee051a 100644 --- a/docs/USE_CASE_COMPLETION_AUDIT.md +++ b/docs/MOBILE/04-use-case-completion-audit.md @@ -46,7 +46,7 @@ | 2.2 Scheduled Orders โ€” Recurring | Create recurring shifts (e.g., every Monday) | โœ… | โœ… | โœ… Completed | `recurring_order_page.dart` fully implemented. | | 2.2 Scheduled Orders โ€” Permanent | Long-term staffing placement | โœ… | โœ… | โœ… Completed | `permanent_order_page.dart` fully implemented. | | 2.2 Scheduled Orders | Review cost before posting | โœ… | โœ… | ๐ŸŸก Partial | Order summary shown, but real-time cost calculation depends on backend. | -| *(undocumented)* | View & Browse Posted Orders | โœ… | โœ… | ๐Ÿšซ Undocumented | `view_orders_page.dart` exists with `ViewOrderCard`. Not covered in use-case docs. | +| *(undocumented)* | View & Browse Posted Orders | โœ… | โœ… | ๐Ÿšซ Undocumented | `view_orders_page.dart` exists with `ViewOrderCard`. Added `eventName` visibility. | | *(undocumented)* | Cancel/Modify posted order | โŒ | โŒ | ๐Ÿšซ Undocumented | A `cancel` reference appears only in `view_order_card.dart`. No dedicated cancel flow in docs or real app. | --- @@ -150,10 +150,10 @@ | Use Case | Sub-Use Case | Prototype | Real App | Status | Notes | |:---|:---|:---:|:---:|:---:|:---| -| 2.1 Browse & Filter Jobs | View available jobs list | โœ… | โœ… | โœ… Completed | `find_shifts_tab.dart` in `shifts` renders all available jobs. | +| 2.1 Browse & Filter Jobs | View available jobs list | โœ… | โœ… | โœ… Completed | `find_shifts_tab.dart` in `shifts` renders all available jobs. Fully localized via `core_localization`. | | 2.1 Browse & Filter Jobs | Filter by Role | โœ… | โœ… | ๐ŸŸก Partial | Search by title/location/client name is implemented. Filter by **role** (as in job category) uses type-based tabs (one-day, multi-day, long-term) rather than role selection. | | 2.1 Browse & Filter Jobs | Filter by Distance | โœ… | โŒ | โŒ Not Implemented | Distance filter present in prototype (`jobs_screen.dart`). Real app has no distance-based filter. | -| 2.1 Browse & Filter Jobs | View job card details (Pay, Location, Requirements) | โœ… | โœ… | โœ… Completed | `MyShiftCard` + `shift_details_page.dart` with full shift info. | +| 2.1 Browse & Filter Jobs | View job card details (Pay, Location, Requirements) | โœ… | โœ… | โœ… Completed | `MyShiftCard` + `shift_details_page.dart` with full shift info. Added `endDate` support for multi-day shifts. | | 2.3 Set Availability | Select dates/times โ†’ Save preferences | โœ… | โœ… | โœ… Completed | `availability_page.dart` fully implemented with `AvailabilityBloc`. | | *(undocumented)* | View Upcoming Shifts shortcut on Home | โœ… | โœ… | ๐Ÿšซ Undocumented | `worker_home_page.dart` shows upcoming shifts. Not documented as a home-tab sub-use case. | @@ -167,9 +167,9 @@ | 2.2 Claim Open Shift | System validates eligibility (certs, conflicts) | โœ… | โŒ | โŒ Not Implemented | Eligibility validation expected server-side, but client-side prompt to upload compliance docs if ineligible is not implemented. | | 2.2 Claim Open Shift | Prompt to Upload Compliance Docs if missing | โœ… | โŒ | โŒ Not Implemented | Prototype shows a `PromptUpload` flow. Real app `find_shifts_tab.dart` shows a success snackbar regardless. No redirect to compliance upload. | | 3.1 View Schedule | View list of claimed shifts (My Shifts tab) | โœ… | โœ… | โœ… Completed | `my_shifts_tab.dart` fully implemented with shift cards. | -| 3.1 View Schedule | View Shift Details | โœ… | โœ… | โœ… Completed | `shift_details_page.dart` with header, location map, schedule summary, stats. | +| 3.1 View Schedule | View Shift Details | โœ… | โœ… | โœ… Completed | `shift_details_page.dart` with header, location map, schedule summary, stats. Corrected weekday mapping and added `endDate`. | | *(undocumented)* | History of Past Shifts (History tab) | โŒ | โœ… | ๐Ÿšซ Undocumented | `history_shifts_tab.dart` exists and is wired in the `shifts_page.dart`. Not mentioned in use-case docs. | -| *(undocumented)* | Shift Assignment Card with multi-day grouping | โŒ | โœ… | ๐Ÿšซ Undocumented | Multi-day grouping logic in `_groupMultiDayShifts()` within `find_shifts_tab.dart`. Not in docs. | +| *(undocumented)* | Shift Assignment Card with multi-day grouping | โŒ | โœ… | ๐Ÿšซ Undocumented | Multi-day grouping logic in `_groupMultiDayShifts()` within `find_shifts_tab.dart`. Supports `endDate`. | ---