feat(api): add staff order booking contract and shift timeline alias

docs/BACKEND/API_GUIDES/V2/staff-shifts.md

@@ -4,10 +4,11 @@ This document is the frontend handoff for the `staff/shifts/*` routes on the uni
 
 Base URL:
 
-- `https://krow-api-v2-933560802882.us-central1.run.app`
+- `https://krow-api-v2-e3g6witsvq-uc.a.run.app`
 
 ## Read routes
 
+- `GET /staff/orders/available`
 - `GET /staff/shifts/assigned`
 - `GET /staff/shifts/open`
 - `GET /staff/shifts/pending`
@@ -17,6 +18,7 @@ Base URL:
 
 ## Write routes
 
+- `POST /staff/orders/:orderId/book`
 - `POST /staff/shifts/:shiftId/apply`
 - `POST /staff/shifts/:shiftId/accept`
 - `POST /staff/shifts/:shiftId/decline`
@@ -30,6 +32,68 @@ All write routes require:
 
 ## Shift lifecycle
 
+### Find work by order
+
+`GET /staff/orders/available`
+
+- use this for grouped recurring or permanent work cards
+- each item represents one order plus one role
+- this feed is already filtered to the current worker context
+- `schedule` gives the preview for the whole booking window
+
+Example response:
+
+```json
+{
+  "orderId": "uuid",
+  "orderType": "RECURRING",
+  "roleId": "uuid",
+  "roleCode": "BARISTA",
+  "roleName": "Barista",
+  "clientName": "Google Mountain View Cafes",
+  "location": "Google MV Cafe Clock Point",
+  "locationAddress": "1600 Amphitheatre Pkwy, Mountain View, CA",
+  "hourlyRateCents": 2300,
+  "hourlyRate": 23,
+  "requiredWorkerCount": 1,
+  "filledCount": 0,
+  "instantBook": false,
+  "dispatchTeam": "CORE",
+  "dispatchPriority": 1,
+  "schedule": {
+    "totalShifts": 3,
+    "startDate": "2026-03-24",
+    "endDate": "2026-03-28",
+    "daysOfWeek": ["WED", "FRI"],
+    "startTime": "09:00",
+    "endTime": "15:00",
+    "timezone": "America/Los_Angeles",
+    "firstShiftStartsAt": "2026-03-25T16:00:00.000Z",
+    "lastShiftEndsAt": "2026-03-27T22:00:00.000Z"
+  }
+}
+```
+
+`POST /staff/orders/:orderId/book`
+
+- use this when the worker books the full order instead of one shift
+- booking is atomic across the future shifts in that order for the selected role
+- backend returns `PENDING` when the booking is reserved but not instant-booked
+- backend returns `CONFIRMED` when every future shift in that booking path is instant-booked
+
+Example request:
+
+```json
+{
+  "roleId": "uuid"
+}
+```
+
+Important:
+
+- `roleId` for the order-booking flow is the role catalog id returned by `GET /staff/orders/available`
+- it is not the same thing as the per-shift `shift_roles.id`
+
 ### Find shifts
 
 `GET /staff/shifts/open`