# UI & Flow — Yard Onboarding (Operations Director) Goal: the **Operations Director** runs yard onboarding self-service (no dev/SQL), and can see **where every yard stands** against a checklist. Start with the **IT checklist** (system/technical steps); the broader business checklist plugs in later as another section. This UI is the front-end of the registry/automation in `02` — "Add Yard" writes registry rows (additive overlay, per `03`); checklist items are mostly the `gps:verify` checks rendered as status. --- ## Where it lives - Filament page **"Yard Onboarding"** under the **Operations** nav group. - Visible to the Operations Director role (+ admins). - Two screens: **Yards list** → **Yard detail (checklist)**. Plus an **Add Yard** form. --- ## Screen 1 — Yards list A table: one row per yard, showing progress at a glance. ``` Yard Onboarding [ + Add Yard ] ───────────────────────────────────────────────────────────────────── Yard GPS Acct Locations IT Checklist Stage Updated ───────────────────────────────────────────────────────────────────── Wheels America USER-47 6 ███████░░ 7/8 Live 2d ago Spalding USER-49 2 ███████░░ 7/8 Live 2d ago Pull-A-Part GA USER-51 3 ████░░░░░ 4/8 Provisioning 1h ago Speedy Yard — 1 █░░░░░░░░ 1/8 Intake 10m ago ───────────────────────────────────────────────────────────────────── Filters: [ Stage ▾ ] [ Operator ▾ ] [ Has blockers ☐ ] ``` - **IT Checklist** = progress bar (auto-computed from the items in screen 2). - **Stage** = coarse status chip (Intake → Provisioning → Synced → Live). - Click a row → Yard detail. --- ## Screen 2 — Yard detail (the checklist) Header + locations + the checklist grouped by section. The IT checklist is the first section; later sections (Business, Finance, etc.) append below it. ``` ← Yards Wheels America Account: USER-47 · wheelsamerica@go-parts.com ─────────────────────────────────────────────────────────────────────────────── Locations (6): WAM-D 75237 · WAM-H 77040 · WAM-SA 78154 · WAM-L 90621 · … Operator: Dan Stage: Live [ Re-verify all ] [ Resolve from GPS ] ─────────────────────────────────────────────────────────────────────────────── ▣ IT CHECKLIST 8 / 9 ─────────────────────────────────────────────────────────────────────────────── ✓ Supplier ID(s) & codes mapped ⟵ GATE auto · 6/6 linked to suppliers ✓ GPS account & credential resolved auto · verified 2d ago ✓ Locations created in GPS manual · Dan, 2d ago ✓ Ship-from location IDs mapped auto · 6/6 resolved ✓ SHIP_NOTIFY webhook configured auto · verified 2d ago ✓ Appears in Ship dropdowns (single + bulk) auto ✓ Shows in Create B2C dropdown auto ✓ Blocked from Create B2B dropdown auto ⚠ Sample orders seeded for vendor manual [ Seed samples ] [ Mark done ] ─────────────────────────────────────────────────────────────────────────────── (later) ▢ BUSINESS CHECKLIST · ▢ FINANCE CHECKLIST ``` **Item anatomy** - **Status icon**: ✓ done · ○ pending · ⚠ blocked/attention · – n/a - **Label**: plain-language step - **Kind badge**: `auto` (system-verified — cannot be faked) vs `manual` (ops attests) - **Provenance**: who/when, or "verified N ago" - **Inline action** where useful: `Resolve from GPS`, `Seed samples`, `Sync to Central`, `Re-check`, or a `Mark done` checkbox for manual items. **Auto vs manual — why it matters** - `auto` items reflect **computed truth** (run the `gps:verify` check live / via `gps:reconcile`). They flip green by themselves and can't be lied into green. - `manual` items are ops attestations for things the system can't see (e.g. "locations created in the GPS UI", "vendor emails received"). --- ## The flow ``` [ + Add Yard ] ─▶ Intake form ─▶ map each location to an EXISTING supplier_id (GATE) │ (blocks save until every row is mapped) ▼ registry rows created (overlay) ─▶ checklist appears (supplier-mapping gate ✓, rest ○) │ ┌─────────────────────────────────────────────────────────────┘ ▼ Operator works the checklist top-down: • external steps (create GPS acct/locations, vendor replies) → manual tick / Mark done • automated steps → buttons: Resolve from GPS · Seed samples · Sync to Central • verification steps → auto-green when the system confirms (or [Re-check]) │ all IT items green ──────┘ ─▶ Stage: Live ``` ### Precondition — suppliers exist first (hard gate) **Onboarding assumes the supplier already exists in the `suppliers` table.** Before *anything* else proceeds, the yard must be **mapped to finalised supplier ID(s) + supplier code(s)** that already exist in `suppliers` (one per warehouse/location). The GPS account can exist independently of this, but our flow does not advance until the supplier mapping is in place. This is the **first checklist item and a gate**: while it's red, the rest of the checklist actions are disabled. Rationale: `gps_warehouses.supplier_id` is the FK the whole registry hangs on (location mapping, B2C/B2B, HAZMAT, exports all key off supplier_id), so nothing downstream is valid without it. ### Add Yard (intake form) Fields the Ops Director fills (everything else is auto-derived later): - Yard name - **Locations: repeater of `supplier (existing) · code · city · state · ZIP`** — each location row **must select an existing supplier** from `suppliers` (by supplier_id/code). Validated: supplier exists, is active, and isn't already mapped to another yard. No supplier yet → create it in `suppliers` first (out of this flow); the form won't let the row be saved unmapped. - Account email (GPS account — may already exist) - **Yard type** preset (e.g. "GPS used-parts yard" → sets exclusive + B2C-only + description-HAZMAT in one pick) — or expand to set flags individually. → On save: registry rows written (inert overlay) **only if every location is mapped to a valid supplier_id**; checklist instantiated with the supplier-mapping gate already green and the rest pending. ### Driving the steps - **Resolve from GPS** — runs `gps:resolve`: queries `shipdev` by email/ZIP, fills account code, credential, location IDs. Flips the two "resolved" items green. - **Seed samples** — calls `GoPartsShipService::createOrder` to drop test orders in the vendor's account for them to practice. - **Sync to Central** — runs `gps:sync`: sets `can_autofulfill`, warms caches; the overlay-read code now surfaces the yard. Flips the dropdown/B2C/B2B/HAZMAT items. - **Re-verify all** — re-runs every auto check; `gps:reconcile` also runs on a schedule so the board self-heals if someone changes something in GPS directly. --- ## IT checklist items (v1) | Item | Kind | Source of truth | |------|------|-----------------| | **Supplier ID(s) & codes mapped (GATE)** | auto | every location → existing `suppliers` row; blocks the rest until green | | GPS account & credential resolved | auto | `shipdev.warehouse_api_credentials` by email | | Locations created in GPS | manual | ops attests (GPS UI) | | Ship-from location IDs mapped | auto | `shipdev.ship_from_locations` by user+ZIP → registry | | SHIP_NOTIFY webhook configured | auto | `shipdev.webhook_configurations` | | Appears in Ship dropdowns (single + bulk) | auto | registry-merged config / WarehouseHelper | | Shows in Create B2C dropdown | auto | `getB2CSuppliers()` contains codes | | Blocked from Create B2B dropdown | auto | `getB2BSuppliers()` excludes codes | | Sample orders seeded for vendor | manual | ops (button assists) | (Add later: HAZMAT block active · Export button works · Sub-users provisioned · plus the full business checklist as its own section.) --- ## Build order (suggested) 1. **Tracking-first (low risk):** the list + detail + checklist as a **read-only status board**, with `auto` items powered by `gps:verify` against the *current* live yards (PAMS/Counselman/PartsBox/WAM/Spalding/OEM). Useful immediately, touches nothing live. 2. Add **Add Yard** + registry writes (needs Phase 0 registry tables). 3. Wire the **action buttons** (resolve/seed/sync) as the automation lands. Step 1 ships value before any of the risky refactor — it just *reports*.