feat: Add Milestone 3 documentation including feature testing plan, demo notes, and demo flow details

- Introduced comprehensive testing plan for Milestone 3 in m3-client-note.md - Documented feedback and suggestions from demo sessions in m3-notes.md - Created detailed demo flow for Milestone 3 in m3.md, outlining user interactions and expected outcomes - Added planning tasks for Milestone 4 in m4-planning.md, covering backend and frontend development tasks, research, and business tasks
2026-02-12 16:33:16 -05:00
parent 368f28f354
commit fd47d84045
18 changed files with 829 additions and 1411 deletions
--- a/docs/MILESTONES/M3/demos/m3-client-note.md
+++ b/docs/MILESTONES/M3/demos/m3-client-note.md
@@ -0,0 +1,257 @@
+# KROW Workforce Platform — Feature Testing Plan for Milestone 3
+
+**Version:** Milestone 3 (0.0.1-IlianaStaffM3 and 0.0.1-IlianaClientM3)
+**Estimated Duration:** 25-30 minutes
+
+---
+
+## Required Applications
+- Client Mobile Application (v0.0.1-IlianaClientM3)
+- Staff Mobile Application (v0.0.1-IlianaStaffM3)
+
+---
+
+## 1. Testing Environment Setup
+
+### Required Test Accounts
+
+**Client Account (Business User):**
+- Email: `legendary@krowd.com`
+- Password: `Demo2026!`
+- Client Name: "Krow"
+
+**Staff Account (Worker):**
+- Phone: `+15557654321`
+- OTP Code: `123456` (testing mode)
+- Name: "Mariana Torres"
+
+### Prerequisites
+1. ✅ Both apps installed on the device
+2. ✅ Network connection stable
+
+---
+
+## 2. Testing Steps
+
+### 2.1: Register Business (Client App)
+**Purpose:** Show the client onboarding experience
+
+**Steps:**
+1. Open Client App → Tap "Create Account"
+2. Enter business email, and password (not the provided test account credentials, use a new email for this step)
+3. Navigate to the home page
+
+**Observable Points:** : 
+ - Empty dashboard, no orders, no workers, clean slate
+
+---
+
+### 2.2: Register Staff (Staff App)
+**Purpose:** Show the worker onboarding experience
+
+**Steps:**
+1. Open Staff App → Tap "Sign Up"
+2. Enter phone number and verify with OTP code (not the provided test account credentials, use a new phone number for this step)
+3. Follow the onboarding process
+4. Navigate to the home page
+
+**Observable Points:** : 
+ - Empty shifts list, no available work yet
+
+---
+
+### 2.3: Client Sign In with an Existing Account (Client App)
+**Note:** Use the client demo account credentials provided above.
+**Purpose:** Show the sign-in experience for returning users
+
+**Steps:**
+1. Close Client App and reopen it.
+2. Tap "Sign In" button
+3. Enter credentials:
+   - Email: `legendary@krowd.com`
+   - Password: `Demo2026!`
+4. Tap "Sign In"
+
+---
+
+### 2.4: Client Views the Populated Dashboard (Client App)
+**Purpose:** Show how the client app displays active operations
+
+**Steps:**
+1. After signing in, observe the home screen
+2. Navigate through populated sections:
+   - Home: Coverage stats, upcoming shifts
+   - Orders: Posted shifts with workers assigned
+   - Coverage: Real-time worker status
+
+**Observable Points:**
+- Coverage percentage for today's shifts
+- Workers checked in vs. needed
+- Late workers alerts
+- Today's estimated labor cost
+
+---
+
+### 2.5: Client Creates a New Hub (Client App)
+**Purpose:** Show the hub creation process
+
+**Steps:**
+1. Navigate to Hubs page via the settings button in the top right corner of the home screen
+2. Tap the "Hubs" button in the settings menu.
+3. Tap the "+" icon at the bottom right of the hubs list, to open the hub creation form.
+4. Fill in hub details:
+   - Hub name: "Downtown Convention Center"
+   - Address: Start typing and select an address.
+5. Tap "Create Hub"
+6. See the new hub appear in the hubs list
+
+---
+
+### 2.6: Client Creates New Order (Client App)
+**Purpose:** Walk through the order creation process
+
+**Steps:**:
+1. Go back to the home screen.
+2. Navigate to the "Orders" tab in the bottom navigation.
+3. Tap the "+ Post" button on top right to open the order type selection screen.
+4. Select "One-Time" from the order type options.
+5. Fill in order details:
+- Order name: "Summer Gala 2026"
+- Date: [Select upcoming date]
+- Hub: [Select existing hub]
+- Add position: Server, Count: 3, Hours: 5PM-9PM
+6. Tap "Create Order"
+
+---
+
+### 2.7: Client Views Order Details (Client App)
+**Purpose:** View detailed shift information and worker assignments
+
+**Steps:**
+1. View the created order in the orders list on the order screen.
+
+**Observable Points:**
+- Event name and location
+- Roles needed
+- Clock in/out times
+- Estimated cost
+- Coverage percentage bar
+
+---
+
+### 2.8: Client Monitors Coverage Dashboard (Client App)
+**Purpose:** Show real-time worker tracking capabilities
+
+**Steps:**
+1. Navigate to the "Coverage" tab in the bottom navigation.
+2. Observe the worker status for active shifts.
+
+**Observable Points:**
+- Worker status (Checked In, En Route, Late, Not Arrived)
+- Color-coded status badges (green, yellow, red)
+- Worker information
+
+---
+
+### 2.9: Staff Logs In with Existing Account (Staff App)
+**Note:** Use the staff demo account credentials provided above.
+**Purpose:** Show the staff app sign-in experience for returning users
+
+**Steps:**
+1. Close the staff app and reopen it.
+2. Tap "Log In" button
+3. Enter phone number: `5557654321`
+4. Tap "Send Code"
+5. Enter OTP: `123456`
+
+---
+
+### 2.10: Staff Views Home Dashboard (Staff App)
+**Purpose:** View worker's personalized dashboard
+
+**Observable Points:**
+- Welcome message with worker's name
+- Today's Shifts section (confirmed shifts for today)
+- Tomorrow's Shifts section
+- Recommended shifts section
+
+---
+
+### 2.11: Staff Finds Available Shifts (Staff App)
+**Purpose:** Show the shift search and discovery experience for workers
+
+**Steps:**
+1. Navigate to the "Shifts" tab in the bottom navigation.
+2. Tap the "Find Shifts" button on top to view available shifts.
+
+**Observable Points:**
+- List of shifts
+- Hourly rate prominently displayed
+- Role requirements (e.g., "Bartender - Spring Gala")
+- Date, time, and duration
+
+**Note:**
+>Due to the current order flow, newly created orders do not appear in the Find Shifts section, as it requires an approval from the vendor. This was discussed during the demo.
+>We are actively updating this flow so orders will appear correctly in a future iteration.
+---
+
+### 2.12: Staff Applies for Shift (Staff App)
+**Purpose:** Show the application process from worker side
+
+**Steps:**
+1. Tap on an available shift to view details
+2. Review business name, location, pay, requirements
+3. Tap "Book Shift" button
+4. Tap "Book" on the confirmation dialog
+4. See confirmation
+
+---
+
+### 2.13: Staff Views Confirmed Shifts (Staff App)
+**Purpose:** Show worker's shift confirmation
+
+**Observable Points:**
+- Week-by-week calendar navigation
+- Color-coded status (Confirmed, Pending, Completed)
+- Quick access to shift details and directions
+
+---
+
+### 2.14: Staff Clock-In to Shift (Day of Event) (Staff App)
+**Purpose:** Demonstrate the clock-in process
+
+**Steps:**
+1. Navigate to the clock-in page.
+2. Use the "Clock In" slider to clock in.
+
+**Observable Points:**
+- Timestamp automatically recorded
+- Status changes to "Checked In" with green indicator
+
+---
+
+### 2.15: Staff Clocks-Out of Shift (Day of Event) (Staff App)
+**Purpose:** Demonstrate the clock-out process and shift completion
+
+**Steps:**
+1. Navigate to the clock-out page.
+2. Use the "Clock Out" slider to clock out.
+3. Navigate to the "My Shifts" section in the Shifts tab to see the updated status via the bottom navigation.
+
+**Observable Points:**
+- Clock-out timestamp automatically recorded
+- Status changes to "Completed" 
+
+---
+
+### 2.16: Staff Profile Management (Staff App)
+**Purpose:** Demonstrate worker profile features and compliance management
+
+**Steps:**
+1. Navigate to Profile tab in bottom navigation
+2. Review profile sections:
+   - **Profile Info:**
+   - **Emergency Contact:** Name, relationship, phone number
+   - **Bank Account:** Linked payment account for direct deposit
+   - **Tax Forms:** W-4, I-9 compliance documents
+   - **Time Card:** Historical shift records with hours and earnings
--- a/docs/MILESTONES/M3/demos/m3-notes.md
+++ b/docs/MILESTONES/M3/demos/m3-notes.md
@@ -0,0 +1,63 @@
+# KROW M3 Demo — Test Feedback
+
+**Date:** February 3, 2026
+
+---
+
+## Demo 1: Register Business & Show Empty States (Client App)
+
+- **Flickering company name:** Every time I navigate to the home screen, I see "your company" for a moment before it changes to the real name.
+- Creating a One-Time Order shows "No Vendors Available" — this is expected, OK.
+
+**Suggestions: Achintha:**
+- We need to have a shimmer loading state while fetching data, to avoid flickering and empty states.
+
+---
+
+## Demo 2: Register Staff & Show Empty States (Staff App)
+
+**Onboarding — Add preferred work locations:**
+- Suggestion: Use Google Maps to suggest only city names. Currently users can type anything, which will cause misspellings and inconsistent data. Important for the max distance feature.
+
+**Home page:**
+- Same flickering issue — shows "Krower" briefly before displaying the real name.
+
+**Profile page:**
+- Phone number should be read-only, or require re-verification if changed.
+- Emergency contact: "Save & Continue" works, but shouldn't we navigate to the profile page after? Other flows do this.
+- Tax Documents: Would be great to add a file uploader where our AI could identify documents and prefill fields.
+- Bank Account: Need to plan real bank verification (KYC)? Ensure the account is real and belongs to the user. Also, I can list banks but I don't see how to change/switch bank.
+
+**Home (empty state):**
+- Clicking "Find shifts →" does nothing. But "Find Shifts" with the search icon works.
+
+**My Availability:**
+- Working. Some latency, but OK for now.
+
+---
+
+## Demo 5: Client Creates a New Hub
+
+- Hub editing feature seems missing — we'll need this for NFC configuration later.
+- No confirmation before deleting a hub.
+
+---
+
+## Demo 6: Client Creates New Order
+
+- "Up Next (x)" counter is confusing. I created 2 orders but it shows "Up Next (1)". Sometimes shows 0 when navigating, then back to 1.
+
+---
+
+## Demo 8: Staff Logs In with Existing Account
+
+- If you accidentally click "Sign Up" with an existing phone number, you get stuck:
+  1. OTP screen shows error: "This user already has a staff profile. Please log in"
+  2. Clicking back → login → same OTP error loop
+  3. Only fix: kill and restart the app
+
+---
+
+## Demo 10: Staff Browses Available Shifts
+
+- **Blocker:** I don't see the shift I created as the Client.
--- a/docs/MILESTONES/M3/demos/m3.md
+++ b/docs/MILESTONES/M3/demos/m3.md
@@ -0,0 +1,348 @@
+# KROW Workforce Platform — Feature Demo Plan for Milestone 3
+
+**Version:** Milestone 3 (v3.0)  
+**Date:** February 3, 2026  
+**Audience:** Business Stakeholders, Customer Engineers, Sales Teams  
+**Duration:** 25-30 minutes
+
+---
+
+## 1️⃣ Demo Overview
+
+### Purpose
+
+This demo showcases the progress of the milestone 3.
+
+- **For Businesses (Client App):** One-time shift creation, worker management, real-time coverage tracking
+- **For Workers (Staff App):** Easy access to available shifts, clock-in and profile management
+- **Complete Workflow:** From shift posting and worker check-in and completion
+
+### Estimated Demo Duration
+
+**25-30 minutes**
+
+---
+
+## 2️⃣ Demo Environment Setup
+
+### Required Test Accounts
+
+**Client Account (Business User):**
+- Email: `legendary@krowd.com`
+- Password: `Demo2026!`
+- Client Name: "Krow"
+
+**Staff Account (Worker):**
+- Phone: `+15557654321`
+- OTP Code: `123456` (demo mode)
+- Name: "Mariana Torres"
+
+### Prerequisites
+1. ✅ Both apps installed on demo devices (or simulators)
+2. ✅ Network connection stable
+3. ✅ Seed data is ready to be populated (the database should be empty at start)
+
+### Make Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `make dataconnect-clean` | Clean the database before seeding |
+| `make dataconnect-seed` | Populate the database with seed data for demo |
+
+### Recent Fixes Applied
+- ✅ Fixed 2 bugs on TaxForm: marital status and Citizenship Status now properly saved
+- ✅ Fixed update screen after create or update TaxForm
+- ✅ Created seed data script
+- ✅ Created make commands to create and delete information in DataConnect
+
+---
+
+## 3️⃣ Demo Flows
+
+### Demo 0: Show Empty Database
+**Purpose:** Demonstrate the starting point before any data exists
+
+**Steps:**
+1. Run `make dataconnect-clean` to ensure database is empty
+2. Show the empty database in Firebase console
+
+---
+
+### Demo 1: Register Business & Show Empty States (Client App)
+**Purpose:** Show the client onboarding experience and empty states
+
+**Steps:**
+1. Open Client App → Tap "Create Account"
+2. Enter business email, and password
+3. Navigate to home page
+4. **Point out:** Empty dashboard, no orders, no workers, clean slate
+
+---
+
+### Demo 2: Register Staff & Show Empty States (Staff App)
+**Purpose:** Show the worker onboarding experience and empty states
+
+**Steps:**
+1. Open Staff App → Tap "Sign Up"
+2. Enter phone number and verify with OTP code
+3. Follow the onboarding process
+4. Navigate to home page
+5. **Point out:** Empty shifts list, no available work yet
+
+---
+
+### 🔄 PAUSE: Populate Database
+
+Run the seeding command:
+```bash
+make dataconnect-seed
+```
+
+---
+
+### Demo 3: Client Logs In with Existing Account
+**Purpose:** Show the sign-in experience for returning users
+
+**Screen:** Get Started → Sign In
+
+**Steps:**
+1. Restart Client App
+2. Tap "Sign In" button
+3. Enter credentials:
+   - Email: `legendary@krowd.com`
+   - Password: `Demo2026!`
+4. Tap "Sign In"
+
+---
+
+### Demo 4: Client Views Populated Dashboard
+**Purpose:** Show how the client app displays active operations
+
+**Steps:**
+1. After signing in, observe the home screen
+2. Navigate through populated sections:
+   - Home: Coverage stats, upcoming shifts
+   - Orders: Posted shifts with workers assigned
+   - Coverage: Real-time worker status
+
+**What to Notice:**
+- Coverage percentage for today's shifts
+- Workers checked in vs. needed
+- Late workers alerts
+- Today's estimated labor cost
+
+---
+
+### Demo 5: Client Creates a New Hub
+**Screen:** Hubs Tab → "Add Hub" button
+
+**Steps:**
+1. Navigate to Hubs tab in bottom navigation
+2. Tap the "+" or "Add Hub" button
+3. Fill in hub details:
+   - Hub name: "Downtown Convention Center"
+   - Address: Start typing and select from Google Places autocomplete
+4. Tap "Create Hub"
+5. See the new hub appear in the hubs list
+
+---
+
+### 📋 Main Demo Flow Explanation
+
+```
+Client Posts Shift [O1]
+    ↓
+*Vendor Accepts the Shift (Missing for now) / Vendor is selected by client* [O2] 
+    ↓
+Worker Searches for a Shift [O3]
+    ↓
+Worker Applies [O4]
+    ↓
+Confirmation (Missing for now, auto-confirmed)* [O5] 
+    ↓
+Worker Checks In [O6]
+    ↓
+Shift Completed [O7]
+```
+
+---
+
+### Demo 6: Client Creates New Order - [O1]
+**Purpose:** Walk through the shift creation process
+
+**Screen:** Orders Tab → "Post" button
+
+**What to Fill:**
+- Order name: "Spring Gala 2026"
+- Date: [Select upcoming date]
+- Location: [Select existing hub]
+- Add position: Server, Count: 3, Hours: 5PM-9PM
+
+---
+
+### Demo 7: Client Views Order Details
+**Purpose:** Show detailed shift information and worker assignments (second part is missing for now)
+
+**Screen:** Orders Tab → Tap on any order card
+
+**What to Notice:**
+- Event name and location
+- Roles needed (e.g., "2 Servers")
+- Clock in/out times
+- Estimated cost
+- Coverage percentage bar
+
+---
+
+### Demo 8: Staff Logs In with Existing Account
+**Purpose:** Show the worker sign-in experience
+
+**Screen:** Get Started → Sign In with Phone
+
+**Steps:**
+1. Restart the staff app
+2. Enter phone number: `5557654321`
+3. Tap "Send Code"
+4. Enter OTP: `123456`
+
+---
+
+### Demo 9: Staff Views Home Dashboard
+**Purpose:** Show worker's personalized dashboard
+
+**What to Notice:**
+- Today's Shifts section (confirmed shifts for today)
+- Tomorrow's Shifts section
+
+---
+
+### Demo 10: Staff Browses Available Shifts - [O3]
+**Purpose:** Show how workers discover and view available work
+
+**Screen:** Shifts → "Find Work"
+
+**What to Notice:**
+- List of shifts matching worker skills
+- Hourly rate prominently displayed
+- Role requirements (e.g., "Bartender - Spring Gala")
+- Date, time, and duration
+
+---
+
+### Demo 11: Staff Applies for Shift - [O4]
+**Purpose:** Show the application process from worker side
+
+**Screen:** Shift Details → "Book" Shift button
+
+**Steps:**
+1. Tap on an available shift to view details
+2. Review business name, location, pay, requirements
+3. Tap "Book" Shift button
+4. See confirmation
+
+---
+
+### Demo 12: Staff Views Confirmed Shifts - [O5]
+**Purpose:** Show worker's shift management interface
+
+**Screen:** Shifts Tab → "My Shifts"
+
+**What to Notice:**
+- Week-by-week calendar navigation
+- Color-coded status (Confirmed, Pending, Completed)
+- Quick access to shift details and directions
+
+---
+
+### Demo 13: Client Monitors Coverage Dashboard - [O5]
+**Purpose:** Show real-time worker tracking capabilities
+
+**Screen:** Client App → Coverage Tab
+
+**What to Notice:**
+- Live worker status (Checked In, En Route, Late, Not Arrived)
+- Color-coded status badges (green, yellow, red)
+- Worker information
+
+---
+
+### Demo 14: Staff Clock-In to Shift (Day of Event) - [O6]
+**Purpose:** Demonstrate the clock-in process
+**Screen:** Clockin page → "Clock In" slider
+
+**What to Notice:**
+- Timestamp automatically recorded
+- Status changes to "Checked In" with green indicator
+
+---
+
+### Demo 15: Client Sees Clock-In Update - [O6]
+**Purpose:** Show cross-app interaction and real-time updates
+
+**Screen:** Client App → Coverage Tab
+
+**Action:** Press the update button on the top right to refresh worker statuses
+
+**What to Notice:**
+- Status update
+- User status changes to "Checked In"
+- Check-in time displayed
+
+---
+
+### Demo 16: Staff Clocks-Out of Shift - [O7]
+**Purpose:** Demonstrate the clocks-out process and shift completion
+**Screen:** Clockin page -> Clock-out slider    
+
+**What to Notice:**
+- Clock-out timestamp automatically recorded
+- Status changes to "Completed"
+- Total hours worked calculated automatically
+
+---
+
+### Demo 17: Client Views Completed Shift in Coverage - [O7]
+**Purpose:** Show how completed shifts appear in the client app
+
+**Screen:** Client App → Coverage Tab
+
+**Action:** Press the refresh button to update worker statuses
+
+**What to Notice:**
+- Worker status changes to "Completed"
+- Check-out time displayed alongside check-in time
+- Total hours worked visible
+- Shift marked as complete in orders list
+- Cost finalized based on actual hours
+
+---
+
+### Demo 18: Staff Profile Management
+**Purpose:** Demonstrate worker profile features and compliance management
+
+**Screen:** Staff App → Profile Tab
+
+**Steps:**
+1. Navigate to Profile tab in bottom navigation
+2. Review profile sections:
+   - **Profile Info:**
+   - **Emergency Contact:** Name, relationship, phone number
+   - **Bank Account:** Linked payment account for direct deposit
+   - **Tax Forms:** W-9, I-9 compliance documents *(bugs fixed: marital status and Citizenship Status now work properly)*
+   - **Time Card:** Historical shift records with hours and earnings
+
+---
+
+## 4️⃣ Customer Handover Checklist
+
+### Deliverables
+
+- [ ] Android apps (Client and Staff)
+- [ ] Demo account credentials (see below)
+
+### Demo Accounts
+
+| Account | Credentials |
+|---------|-------------|
+| **Client** | Email: `legendary@krowd.com` / Password: `Demo2026!` |
+| **Staff** | Phone: `+15557654321` / OTP: `123456` (demo mode) |