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/command-api.md
+++ b/docs/BACKEND/API_GUIDES/V2/command-api.md
@@ -0,0 +1,229 @@
+# V2 Command API
+
+Use `command-api-v2` for write actions that change business state.
+
+Base URL:
+
+```text
+https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
+```
+
+## 1) Required headers
+
+```http
+Authorization: Bearer <firebase-id-token>
+Idempotency-Key: <unique-per-user-action>
+Content-Type: application/json
+```
+
+## 2) Route summary
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `POST` | `/commands/orders/create` | Create order with shifts and roles |
+| `POST` | `/commands/orders/:orderId/update` | Update mutable order fields |
+| `POST` | `/commands/orders/:orderId/cancel` | Cancel order and related eligible records |
+| `POST` | `/commands/shifts/:shiftId/assign-staff` | Assign workforce to shift role |
+| `POST` | `/commands/shifts/:shiftId/accept` | Accept an assigned shift |
+| `POST` | `/commands/shifts/:shiftId/change-status` | Move shift to a new valid status |
+| `POST` | `/commands/attendance/clock-in` | Record clock-in event |
+| `POST` | `/commands/attendance/clock-out` | Record clock-out event |
+| `POST` | `/commands/businesses/:businessId/favorite-staff` | Add favorite staff |
+| `DELETE` | `/commands/businesses/:businessId/favorite-staff/:staffId` | Remove favorite staff |
+| `POST` | `/commands/assignments/:assignmentId/reviews` | Create or update staff review |
+| `GET` | `/readyz` | Ready check |
+
+## 3) Order create
+
+```text
+POST /commands/orders/create
+```
+
+Request body:
+
+```json
+{
+  "tenantId": "uuid",
+  "businessId": "uuid",
+  "vendorId": "uuid",
+  "orderNumber": "ORD-1001",
+  "title": "Cafe Event Staffing",
+  "serviceType": "EVENT",
+  "shifts": [
+    {
+      "shiftCode": "SHIFT-1",
+      "title": "Morning Shift",
+      "startsAt": "2026-03-12T08:00:00.000Z",
+      "endsAt": "2026-03-12T16:00:00.000Z",
+      "requiredWorkers": 2,
+      "roles": [
+        {
+          "roleCode": "BARISTA",
+          "roleName": "Barista",
+          "workersNeeded": 2
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 4) Order update
+
+```text
+POST /commands/orders/:orderId/update
+```
+
+Required body fields:
+- `tenantId`
+- at least one mutable field such as `title`, `description`, `vendorId`, `serviceType`, `startsAt`, `endsAt`, `locationName`, `locationAddress`, `latitude`, `longitude`, `notes`, `metadata`
+
+You can also send `null` to clear nullable fields.
+
+## 5) Order cancel
+
+```text
+POST /commands/orders/:orderId/cancel
+```
+
+Example request:
+
+```json
+{
+  "tenantId": "uuid",
+  "reason": "Client cancelled"
+}
+```
+
+## 6) Shift assign staff
+
+```text
+POST /commands/shifts/:shiftId/assign-staff
+```
+
+Example request:
+
+```json
+{
+  "tenantId": "uuid",
+  "shiftRoleId": "uuid",
+  "workforceId": "uuid",
+  "applicationId": "uuid"
+}
+```
+
+## 7) Shift accept
+
+```text
+POST /commands/shifts/:shiftId/accept
+```
+
+Example request:
+
+```json
+{
+  "shiftRoleId": "uuid",
+  "workforceId": "uuid"
+}
+```
+
+## 8) Shift status change
+
+```text
+POST /commands/shifts/:shiftId/change-status
+```
+
+Example request:
+
+```json
+{
+  "tenantId": "uuid",
+  "status": "PENDING_CONFIRMATION",
+  "reason": "Waiting for worker confirmation"
+}
+```
+
+Allowed status values:
+- `DRAFT`
+- `OPEN`
+- `PENDING_CONFIRMATION`
+- `ASSIGNED`
+- `ACTIVE`
+- `COMPLETED`
+- `CANCELLED`
+
+## 9) Attendance
+
+### Clock in
+
+```text
+POST /commands/attendance/clock-in
+```
+
+### Clock out
+
+```text
+POST /commands/attendance/clock-out
+```
+
+Example request body for both:
+
+```json
+{
+  "assignmentId": "uuid",
+  "sourceType": "NFC",
+  "sourceReference": "iphone-15-pro-max",
+  "nfcTagUid": "NFC-DEMO-ANA-001",
+  "deviceId": "device-123",
+  "latitude": 37.422,
+  "longitude": -122.084,
+  "accuracyMeters": 8,
+  "capturedAt": "2026-03-11T17:15:00.000Z"
+}
+```
+
+## 10) Favorite staff
+
+### Add favorite
+
+```text
+POST /commands/businesses/:businessId/favorite-staff
+```
+
+### Remove favorite
+
+```text
+DELETE /commands/businesses/:businessId/favorite-staff/:staffId
+```
+
+Request body when adding:
+
+```json
+{
+  "tenantId": "uuid",
+  "staffId": "uuid"
+}
+```
+
+## 11) Staff review
+
+```text
+POST /commands/assignments/:assignmentId/reviews
+```
+
+Example request:
+
+```json
+{
+  "tenantId": "uuid",
+  "businessId": "uuid",
+  "staffId": "uuid",
+  "rating": 5,
+  "reviewText": "Strong shift performance",
+  "tags": ["punctual", "professional"]
+}
+```
+
+## 12) Live status
+
+These routes were live-tested on `2026-03-11` against the deployed dev service and `krow-sql-v2`.