Merge pull request #559 from Oloodi/Inconsistent-Shift-Booking-Status

BE: Create seed data for the validation database #555

docs/MILESTONES/M4/Seed/README.md

@@ -0,0 +1,104 @@
+# M4 Seed Data
+
+## What This Seed Contains
+
+This seed reflects the full local database state as of **M4** and is the canonical reference for populating the validation (staging) database.
+
+### Entity Inventory
+
+| Entity              | Count | Notes                                                                                                              |
+| ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------ |
+| `User`              | 2     | 1 business user (Krow), 1 staff user (Mariana Torres)                                                              |
+| `Business`          | 1     | "Krow" — ACTIVE, PREMIUM rate group                                                                                |
+| `Team`              | 1     | Krow team                                                                                                          |
+| `TeamHub`           | 3     | City Ops, Central Ops, Downtown Ops                                                                                |
+| `Vendor`            | 1     | "Golden Gate Event Services" — APPROVED, PREFERRED tier                                                            |
+| `VendorRate`        | 4     | Rate cards per role category                                                                                       |
+| `RoleCategory`      | 9     | All categories (Kitchen, Concessions, Facilities, Bartending, Security, Event Staff, Management, Technical, Other) |
+| `Role`              | 4     | Cook, Bartender, Event Staff, Security Guard                                                                       |
+| `Staff`             | 6     | Mariana Torres, Ethan Walker, Sofia Ramirez, Lucas Chen, Priya Patel, Miguel Alvarez                               |
+| `Workforce`         | 6     | One workforce record per staff member under Golden Gate vendor                                                     |
+| `StaffRole`         | 8     | Skill/role assignments per staff                                                                                   |
+| `StaffAvailability` | 9     | Weekly availability slots for 3 primary staff members                                                              |
+| `Certificate`       | 4     | Food Handler, Background Check, RBS, Safety certs for Mariana Torres                                               |
+| `Document`          | 3     | Document type catalog (W4, I9, ID Copy)                                                                            |
+| `TaxForm`           | 1     | W4 form for Mariana Torres                                                                                         |
+| `Order`             | 20    | Mix of COMPLETED (12), POSTED (4), PARTIAL_STAFFED (4)                                                             |
+| `Shift`             | 20    | COMPLETED (12), OPEN (8)                                                                                           |
+| `ShiftRole`         | 20    | 1 per shift                                                                                                        |
+| `Assignment`        | 4     | New M4 fulfillment flow via Workforce                                                                              |
+| `Application`       | 19    | COMPLETED (15), CONFIRMED (4)                                                                                      |
+| `Invoice`           | 12    | PAID (2), APPROVED (10)                                                                                            |
+| `RecentPayment`     | 3     | For PAID invoices only                                                                                             |
+
+### Date Range
+
+- Historical completed orders: **Jan 26 – Feb 2, 2026**
+- Open/posted orders: **Feb 3 – Feb 8, 2026**
+
+---
+
+## Prerequisites
+
+1. **Firebase CLI** installed and authenticated:
+
+   ```bash
+   npm install -g firebase-tools
+   firebase login
+   ```
+
+2. **Firebase project configured** for the validation environment. Check the project alias:
+
+   ```bash
+   firebase projects:list
+   ```
+
+3. **Data Connect service deployed** on the validation project. The schema must be migrated before seeding.
+
+4. The validation database must be **empty or truncated** before running this seed. Re-running on existing data will cause duplicate key errors (all IDs are hardcoded UUIDs).
+
+---
+
+## How to Run Against the Validation DB
+
+### Option A — Firebase CLI (Recommended)
+
+```bash
+# From the repo root
+firebase dataconnect:sdk:generate   # ensure SDK is in sync
+
+# Execute the seed mutation directly
+firebase dataconnect:execute \
+  --project <validation-project-id> \
+  docs/MILESTONES/M4/Seed/seed.gql
+```
+
+### Option B — Firebase Console
+
+1. Open [Firebase Console](https://console.firebase.google.com) → select the **validation project**
+2. Navigate to **Data Connect** → **Execute**
+3. Paste the contents of `seed.gql`
+4. Click **Run**
+
+### Option C — VS Code Extension
+
+1. Open the Firebase Data Connect extension
+2. Switch to the validation project
+3. Open `seed.gql`, click **Run mutation**
+
+---
+
+## Important Notes
+
+- **Do not run automatically** — this file is committed as a reference only. Manual execution is required.
+- **Idempotency**: This seed is NOT idempotent. Running it twice on the same database will fail due to unique constraint violations on hardcoded IDs.
+- **Transaction**: The entire seed runs in a single `@transaction`. If any insert fails, the whole mutation rolls back.
+- **Composite keys**: `Certificate`, `StaffRole`, `StaffAvailability`, and `StaffDocument` use composite primary keys. Duplicate `(staffId, type)` combinations will cause failures.
+- **Validation DB project ID**: Confirm the target project ID with the team before running.
+
+---
+
+## Seed Source Reference
+
+The base data (Users through RecentPayments) mirrors `backend/dataconnect/functions/seed.gql` (v.3).  
+M4 additions: `VendorRate`, `Workforce`, `StaffRole`, `StaffAvailability`, `Certificate`, `Document`, `TaxForm`, `Assignment`.