feat(backend): implement v2 domain slice and live smoke

2026-03-11 18:23:55 +01:00
parent bc068373e9
commit fe43ff23cf
40 changed files with 5191 additions and 99 deletions
--- a/docs/MILESTONES/M4/planning/m4-v2-frontend-migration-guide.md
+++ b/docs/MILESTONES/M4/planning/m4-v2-frontend-migration-guide.md
@@ -0,0 +1,303 @@
+# M4 V2 Frontend Migration Guide
+
+Status: Active  
+Last updated: 2026-03-11  
+Audience: Web and mobile frontend developers
+
+## 1) Purpose
+This document tells frontend exactly how to migrate toward the v2 backend services on this branch.
+
+It is intentionally strict about readiness:
+1. `core-api-v2` is ready for frontend integration now for uploads, signed URLs, model calls, and verification workflows.
+2. `command-api-v2` now has a first real write slice backed by the v2 SQL schema and verified through live smoke tests.
+3. `query-api-v2` now has a first real read slice backed by the v2 SQL schema and verified through live smoke tests.
+
+Frontend should not assume all three services are ready just because they are deployed.
+
+## 2) Live dev service URLs
+1. Core API v2: `https://krow-core-api-v2-e3g6witsvq-uc.a.run.app`
+2. Command API v2: `https://krow-command-api-v2-e3g6witsvq-uc.a.run.app`
+3. Query API v2: `https://krow-query-api-v2-e3g6witsvq-uc.a.run.app`
+
+## 3) Readiness summary
+
+| Service | Status | Frontend guidance |
+| --- | --- | --- |
+| `core-api-v2` | Ready now with persistence caveat | Use for file upload, signed URLs, model calls, rapid order helpers, and verification flows |
+| `command-api-v2` | First production slice | Use for documented v2 write flows only |
+| `query-api-v2` | First production slice | Use for documented v2 read flows only |
+
+## 4) Non-negotiable migration rules
+1. Do not point undocumented read screens to `query-api-v2` yet.
+2. Do not replace undocumented order, shift, or staffing mutations with `command-api-v2` yet.
+3. Do move all new service-style frontend work to `core-api-v2`.
+4. Do use command/query v2 for the routes listed in this document when building the new v2 clients.
+5. Any new frontend abstraction should separate:
+   - `core service client`
+   - `command service client`
+   - `query service client`
+   - `legacy Data Connect access`
+6. Build the frontend with switchable adapters so the command/query cutover is a client config change, not a rewrite.
+
+## 5) Auth and headers
+All protected v2 routes currently require Firebase ID token:
+
+```http
+Authorization: Bearer <firebase-id-token>
+```
+
+All services return:
+1. `X-Request-Id` response header
+2. Standard error envelope:
+
+```json
+{
+  "code": "STRING_CODE",
+  "message": "Human readable message",
+  "details": {},
+  "requestId": "uuid"
+}
+```
+
+Additional rule for command routes:
+
+```http
+Idempotency-Key: <unique-per-user-action>
+```
+
+## 6) What frontend can migrate now
+
+### 6.1 Move to `core-api-v2` now
+1. File uploads
+2. Signed download URL generation
+3. Rapid order voice transcription
+4. Rapid order structured parsing
+5. Generic model invocation
+6. Verification job creation
+7. Verification status polling
+8. Manual verification review and retry
+
+### 6.2 Keep on existing stack for now
+1. Business reads
+2. Staff reads
+3. Shift lists and details outside the documented order detail shape
+4. Applications lists and details not yet served by query v2
+5. Payments and reporting reads
+
+### 6.3 Move to command/query v2 now for the new v2 clients
+1. Order creation
+2. Order update
+3. Order cancel
+4. Shift assign staff
+5. Shift accept
+6. Shift status change
+7. Attendance clock-in and clock-out
+8. Favorite staff add and remove
+9. Staff review create
+10. Order list
+11. Order detail
+12. Favorite staff list
+13. Staff review summary
+14. Assignment attendance detail
+
+## 7) Core API v2 routes frontend can use today
+Use this service for backend capabilities that should not run directly from the client.
+
+Important caveat:
+1. File storage is real and backed by Google Cloud Storage.
+2. Verification job state is not yet persisted to the v2 SQL schema.
+3. Frontend can integrate with these routes now, but do not treat verification history as mission-critical durable state yet.
+
+Base URL:
+
+```text
+https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
+```
+
+Routes:
+1. `POST /core/upload-file`
+2. `POST /core/create-signed-url`
+3. `POST /core/invoke-llm`
+4. `POST /core/rapid-orders/transcribe`
+5. `POST /core/rapid-orders/parse`
+6. `POST /core/verifications`
+7. `GET /core/verifications/:verificationId`
+8. `POST /core/verifications/:verificationId/review`
+9. `POST /core/verifications/:verificationId/retry`
+10. `GET /health`
+
+For request and response examples, use:
+1. `docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md`
+2. `docs/MILESTONES/M4/planning/m4-api-catalog.md`
+
+## 8) Command API v2 routes ready for the first migration slice
+These routes are deployed and backed by the v2 SQL schema. They enforce auth, policy gate, and idempotency.
+
+Base URL:
+
+```text
+https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
+```
+
+Routes:
+1. `POST /commands/orders/create`
+2. `POST /commands/orders/:orderId/update`
+3. `POST /commands/orders/:orderId/cancel`
+4. `POST /commands/shifts/:shiftId/change-status`
+5. `POST /commands/shifts/:shiftId/assign-staff`
+6. `POST /commands/shifts/:shiftId/accept`
+7. `POST /commands/attendance/clock-in`
+8. `POST /commands/attendance/clock-out`
+9. `POST /commands/businesses/:businessId/favorite-staff`
+10. `DELETE /commands/businesses/:businessId/favorite-staff/:staffId`
+11. `POST /commands/assignments/:assignmentId/reviews`
+12. `GET /health`
+13. `GET /readyz`
+
+Implemented now:
+1. `POST /commands/orders/create`
+2. `POST /commands/orders/:orderId/update`
+3. `POST /commands/orders/:orderId/cancel`
+4. `POST /commands/shifts/:shiftId/change-status`
+5. `POST /commands/shifts/:shiftId/assign-staff`
+6. `POST /commands/shifts/:shiftId/accept`
+7. `POST /commands/attendance/clock-in`
+8. `POST /commands/attendance/clock-out`
+9. `POST /commands/businesses/:businessId/favorite-staff`
+10. `DELETE /commands/businesses/:businessId/favorite-staff/:staffId`
+11. `POST /commands/assignments/:assignmentId/reviews`
+
+Live verification completed on 2026-03-11:
+1. order create
+2. order update
+3. order cancel
+4. shift assign staff
+5. shift accept
+6. shift status change
+7. attendance clock-in
+8. attendance clock-out
+9. favorite add
+10. favorite list
+11. review create
+12. review summary
+13. order list/detail
+14. attendance detail
+
+Order creation request contract:
+
+```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-11T08:00:00.000Z",
+      "endsAt": "2026-03-11T16:00:00.000Z",
+      "requiredWorkers": 2,
+      "roles": [
+        {
+          "roleCode": "BARISTA",
+          "roleName": "Barista",
+          "workersNeeded": 2
+        }
+      ]
+    }
+  ]
+}
+```
+
+Order creation success response:
+
+```json
+{
+  "orderId": "uuid",
+  "orderNumber": "ORD-1001",
+  "status": "OPEN",
+  "shiftCount": 1,
+  "shiftIds": ["uuid"],
+  "idempotencyKey": "abc-123",
+  "requestId": "uuid"
+}
+```
+
+Important:
+1. This is the first real write slice, not the full command surface.
+2. Frontend should migrate only the documented routes.
+3. Reuse one idempotency key per user action and never retry with a new key unless the UI is creating a brand new action.
+4. The old `501` placeholders for order update, order cancel, shift status change, and shift assign staff are now implemented.
+
+## 9) Query API v2 routes ready for the first migration slice
+Base URL:
+
+```text
+https://krow-query-api-v2-e3g6witsvq-uc.a.run.app
+```
+
+Current routes:
+1. `GET /health`
+2. `GET /healthz`
+3. `GET /readyz`
+4. `GET /query/tenants/:tenantId/orders`
+5. `GET /query/tenants/:tenantId/orders/:orderId`
+6. `GET /query/tenants/:tenantId/businesses/:businessId/favorite-staff`
+7. `GET /query/tenants/:tenantId/staff/:staffId/review-summary`
+8. `GET /query/tenants/:tenantId/assignments/:assignmentId/attendance`
+
+Frontend can point the new v2 clients to these routes now. Frontend should not point any undocumented screen, list, detail page, dashboard, or reporting view to `query-api-v2` yet.
+
+## 10) Recommended frontend adapter shape
+Frontend should isolate backend calls behind service adapters instead of calling routes inline in screens.
+
+Suggested split:
+1. `coreApiClient`
+2. `commandApiClient`
+3. `queryApiClient`
+4. `legacyDataConnectClient`
+
+Suggested cutover plan:
+1. Move service-style operations to `coreApiClient` first.
+2. Add `commandApiClient` now as the write path for the documented v2 write routes.
+3. Add `queryApiClient` now as the read path for the documented v2 read routes.
+4. Keep everything else on `legacyDataConnectClient` until the replacement route exists.
+5. Expand migration route-by-route instead of big-bang switching whole apps.
+
+## 11) Frontend implementation checklist
+1. Add three environment variables:
+   - `CORE_API_V2_BASE_URL`
+   - `COMMAND_API_V2_BASE_URL`
+   - `QUERY_API_V2_BASE_URL`
+2. Add shared auth header injection using Firebase ID token.
+3. Add shared response envelope parsing.
+4. Add request ID logging in frontend network layer.
+5. Add `Idempotency-Key` generation utility for command calls.
+6. Build command/query clients behind feature flags or adapter switches.
+7. Start integration with `core-api-v2`, `command-api-v2`, and `query-api-v2` for the documented routes only.
+
+## 12) Frontend do and do not
+Do:
+1. Treat `core-api-v2` as the real backend entrypoint for uploads, model work, and verification.
+2. Treat documented command/query v2 routes as the real backend entrypoint for the first v2 domain slice.
+3. Build migration-safe abstractions now.
+4. Keep old reads and writes isolated so they can be swapped cleanly later.
+
+Do not:
+1. Hardcode v2 command success as if business action is complete.
+2. Point undocumented dashboards or reports to query v2 yet.
+3. Remove current Data Connect code until the replacement route actually exists and is verified.
+
+## 13) Practical migration sequence
+1. Replace existing upload helpers with `core-api-v2`.
+2. Replace signed URL generation with `core-api-v2`.
+3. Point rapid order helpers to `core-api-v2`.
+4. Point attire and document verification flows to `core-api-v2`.
+5. Introduce command client wrapper with idempotency header support.
+6. Point new v2 order creation, shift accept, attendance, favorites, and reviews flows to `command-api-v2`.
+7. Point new v2 order list/detail, favorites, review summary, and attendance detail screens to `query-api-v2`.
+8. Point new v2 order update, order cancel, shift assign, and shift status flows to `command-api-v2`.
+9. Keep payments, reports, and remaining scheduling mutations on the legacy stack until the replacement routes exist.