docs(api): consolidate v2 frontend backend guides

2026-03-12 14:09:05 +01:00
parent fe43ff23cf
commit b61babe3c6
9 changed files with 740 additions and 910 deletions
--- a/docs/BACKEND/API_GUIDES/V2/query-api.md
+++ b/docs/BACKEND/API_GUIDES/V2/query-api.md
@@ -0,0 +1,151 @@
+# V2 Query API
+
+Use `query-api-v2` for implemented read screens in the v2 clients.
+
+Base URL:
+
+```text
+https://krow-query-api-v2-e3g6witsvq-uc.a.run.app
+```
+
+## 1) Required header
+
+```http
+Authorization: Bearer <firebase-id-token>
+```
+
+## 2) Route summary
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/query/tenants/:tenantId/orders` | Order list |
+| `GET` | `/query/tenants/:tenantId/orders/:orderId` | Order detail with shifts and roles |
+| `GET` | `/query/tenants/:tenantId/businesses/:businessId/favorite-staff` | Favorite staff list |
+| `GET` | `/query/tenants/:tenantId/staff/:staffId/review-summary` | Staff rating summary and recent reviews |
+| `GET` | `/query/tenants/:tenantId/assignments/:assignmentId/attendance` | Attendance session and event detail |
+| `GET` | `/readyz` | Ready check |
+
+## 3) Order list
+
+```text
+GET /query/tenants/:tenantId/orders
+```
+
+Optional query params:
+- `businessId`
+- `status`
+- `limit`
+- `offset`
+
+Response shape:
+
+```json
+{
+  "items": [
+    {
+      "id": "uuid",
+      "orderNumber": "ORD-1001",
+      "title": "Cafe Event Staffing",
+      "status": "OPEN",
+      "serviceType": "EVENT",
+      "startsAt": "2026-03-12T08:00:00.000Z",
+      "endsAt": "2026-03-12T16:00:00.000Z",
+      "businessId": "uuid",
+      "businessName": "Google Mountain View Cafes",
+      "vendorId": "uuid",
+      "vendorName": "Legendary Staffing Pool A",
+      "shiftCount": 1,
+      "requiredWorkers": 2,
+      "assignedWorkers": 1
+    }
+  ],
+  "requestId": "uuid"
+}
+```
+
+## 4) Order detail
+
+```text
+GET /query/tenants/:tenantId/orders/:orderId
+```
+
+Response shape:
+
+```json
+{
+  "id": "uuid",
+  "orderNumber": "ORD-1001",
+  "title": "Cafe Event Staffing",
+  "status": "OPEN",
+  "businessId": "uuid",
+  "businessName": "Google Mountain View Cafes",
+  "vendorId": "uuid",
+  "vendorName": "Legendary Staffing Pool A",
+  "shifts": [
+    {
+      "id": "uuid",
+      "shiftCode": "SHIFT-1",
+      "title": "Morning Shift",
+      "status": "OPEN",
+      "startsAt": "2026-03-12T08:00:00.000Z",
+      "endsAt": "2026-03-12T16:00:00.000Z",
+      "requiredWorkers": 2,
+      "assignedWorkers": 1,
+      "roles": [
+        {
+          "id": "uuid",
+          "roleCode": "BARISTA",
+          "roleName": "Barista",
+          "workersNeeded": 2,
+          "assignedCount": 1
+        }
+      ]
+    }
+  ],
+  "requestId": "uuid"
+}
+```
+
+## 5) Favorite staff list
+
+```text
+GET /query/tenants/:tenantId/businesses/:businessId/favorite-staff
+```
+
+Optional query params:
+- `limit`
+- `offset`
+
+## 6) Staff review summary
+
+```text
+GET /query/tenants/:tenantId/staff/:staffId/review-summary
+```
+
+Optional query params:
+- `limit`
+
+Response includes:
+- staff identity
+- average rating
+- rating count
+- recent reviews
+
+## 7) Assignment attendance detail
+
+```text
+GET /query/tenants/:tenantId/assignments/:assignmentId/attendance
+```
+
+Response includes:
+- assignment status
+- shift info
+- attendance session
+- ordered attendance events
+- NFC and geofence validation fields
+
+## 8) Current boundary
+
+Frontend should use only these documented reads on `query-api-v2`.
+
+Do not point dashboard, reports, finance, or other undocumented list/detail views here yet.