feat(api): add unified v2 gateway and mobile read slice

2026-03-13 15:17:00 +01:00
parent 13bcfc9d40
commit 817a39e305
29 changed files with 6788 additions and 87 deletions
--- a/docs/BACKEND/API_GUIDES/V2/README.md
+++ b/docs/BACKEND/API_GUIDES/V2/README.md
@@ -2,31 +2,43 @@

 This is the frontend-facing source of truth for the v2 backend.

-If you are building against the new backend, start here.
+## 1) Frontend entrypoint

-## 1) Which service to use
+Frontend should target one public base URL:

-| Use case | Service |
+```env
+API_V2_BASE_URL=<krow-api-v2-url>
+```
+
+The unified v2 gateway exposes:
+
+- `/auth/*`
+- `/core/*`
+- `/commands/*`
+- `/query/*`
+- `/query/client/*`
+- `/query/staff/*`
+
+Internal services still stay separate behind that gateway.
+
+## 2) Internal service split
+
+| Use case | Internal service |
 | --- | --- |
-| File upload, signed URLs, model calls, rapid order helpers, verification flows | `core-api-v2` |
+| File upload, signed URLs, model calls, verification helpers | `core-api-v2` |
 | Business writes and workflow actions | `command-api-v2` |
-| Screen reads for the implemented v2 views | `query-api-v2` |
-
-## 2) Live dev base URLs
-
- Core API: `https://krow-core-api-v2-e3g6witsvq-uc.a.run.app`
- Command API: `https://krow-command-api-v2-e3g6witsvq-uc.a.run.app`
- Query API: `https://krow-query-api-v2-e3g6witsvq-uc.a.run.app`
+| Screen reads and mobile read models | `query-api-v2` |
+| Frontend-facing single host and auth wrappers | `krow-api-v2` |

 ## 3) Auth and headers

-All protected routes require:
+Protected routes require:

 ```http
 Authorization: Bearer <firebase-id-token>
 ```

-All command routes also require:
+Command routes also require:

 ```http
 Idempotency-Key: <unique-per-user-action>
@@ -43,78 +55,88 @@ All services return the same error envelope:
 }
 ```

-## 4) What frontend can use now
+## 4) What frontend can use now on this branch

-### Ready now
+### Unified gateway

- `core-api-v2`
-  - upload file
-  - create signed URL
-  - invoke model
-  - rapid order transcribe
-  - rapid order parse
-  - create verification
-  - get verification
-  - review verification
-  - retry verification
- `command-api-v2`
-  - create order
-  - update order
-  - cancel order
-  - assign staff to shift
-  - accept shift
-  - change shift status
-  - clock in
-  - clock out
-  - favorite and unfavorite staff
-  - create staff review
- `query-api-v2`
-  - order list
-  - order detail
-  - favorite staff list
-  - staff review summary
-  - assignment attendance detail
+- `POST /auth/client/sign-in`
+- `POST /auth/client/sign-up`
+- `POST /auth/sign-out`
+- `POST /auth/client/sign-out`
+- `POST /auth/staff/sign-out`
+- `GET /auth/session`
+- Proxy access to `/core/*`, `/commands/*`, `/query/*`

-### Do not move yet
+### Client read routes

- reports
- payments and finance screens
- undocumented dashboard reads
- undocumented scheduling reads and writes
- any flow that assumes verification history is durable in SQL
+- `GET /query/client/session`
+- `GET /query/client/dashboard`
+- `GET /query/client/reorders`
+- `GET /query/client/billing/accounts`
+- `GET /query/client/billing/invoices/pending`
+- `GET /query/client/billing/invoices/history`
+- `GET /query/client/billing/current-bill`
+- `GET /query/client/billing/savings`
+- `GET /query/client/billing/spend-breakdown`
+- `GET /query/client/coverage`
+- `GET /query/client/coverage/stats`
+- `GET /query/client/hubs`
+- `GET /query/client/cost-centers`
+- `GET /query/client/vendors`
+- `GET /query/client/vendors/:vendorId/roles`
+- `GET /query/client/hubs/:hubId/managers`
+- `GET /query/client/orders/view`

-## 5) Important caveat
+### Staff read routes

-`core-api-v2` is usable now, but verification job state is not yet persisted to `krow-sql-v2`.
+- `GET /query/staff/session`
+- `GET /query/staff/dashboard`
+- `GET /query/staff/profile-completion`
+- `GET /query/staff/availability`
+- `GET /query/staff/clock-in/shifts/today`
+- `GET /query/staff/clock-in/status`
+- `GET /query/staff/payments/summary`
+- `GET /query/staff/payments/history`
+- `GET /query/staff/payments/chart`
+- `GET /query/staff/shifts/assigned`
+- `GET /query/staff/shifts/open`
+- `GET /query/staff/shifts/pending`
+- `GET /query/staff/shifts/cancelled`
+- `GET /query/staff/shifts/completed`
+- `GET /query/staff/shifts/:shiftId`
+- `GET /query/staff/profile/sections`
+- `GET /query/staff/profile/personal-info`
+- `GET /query/staff/profile/industries`
+- `GET /query/staff/profile/skills`
+- `GET /query/staff/profile/documents`
+- `GET /query/staff/profile/certificates`
+- `GET /query/staff/profile/bank-accounts`
+- `GET /query/staff/profile/benefits`

-What is durable today:
- uploaded files in Google Cloud Storage
- generated signed URLs
- model invocation itself
+### Existing v2 routes still valid

-What is not yet durable:
- verification job history
- verification review history
- verification event history
+- `/core/*` routes documented in `core-api.md`
+- `/commands/*` routes documented in `command-api.md`
+- `/query/tenants/*` routes documented in `query-api.md`

-That means frontend can integrate with verification routes now, but should not treat them as mission-critical durable state yet.
+## 5) Remaining gaps after this slice

-## 6) Recommended frontend environment variables
+Still not implemented yet:

-```env
-CORE_API_V2_BASE_URL=https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
-COMMAND_API_V2_BASE_URL=https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
-QUERY_API_V2_BASE_URL=https://krow-query-api-v2-e3g6witsvq-uc.a.run.app
-```
+- staff phone OTP wrapper endpoints
+- hub write flows
+- hub NFC assignment write route
+- invoice approve and dispute commands
+- staff apply / decline / request swap commands
+- staff profile update commands
+- availability write commands
+- reports suite
+- durable verification persistence in `core-api-v2`

-## 7) Service docs
+## 6) Docs

+- [Unified API](./unified-api.md)
 - [Core API](./core-api.md)
 - [Command API](./command-api.md)
 - [Query API](./query-api.md)
-
-## 8) Frontend integration rule
-
-Do not point screens directly at database access just because a route does not exist yet.
-
-If a screen is missing from the docs, the next step is to define the route contract and add it to `query-api-v2` or `command-api-v2`.
+- [Mobile gap analysis](./mobile-api-gap-analysis.md)
--- a/docs/BACKEND/API_GUIDES/V2/mobile-api-gap-analysis.md
+++ b/docs/BACKEND/API_GUIDES/V2/mobile-api-gap-analysis.md
@@ -0,0 +1,66 @@
+# Mobile API Gap Analysis
+
+Source compared against implementation:
+
+- `/Users/wiel/Downloads/mobile-backend-api-specification.md`
+
+## Implemented in this slice
+
+- unified frontend-facing base URL design
+- client auth wrapper for email/password sign-in and sign-up
+- auth session and sign-out endpoints
+- client read surface for dashboard, billing, coverage, hubs, vendor lookup, and date-range order items
+- staff read surface for dashboard, availability, clock-in reads, payments, shifts, and profile sections
+- schema support for:
+  - cost centers
+  - hub managers
+  - recurring staff availability
+  - staff benefits
+- seed support for:
+  - authenticated demo staff user
+  - cost center and hub manager data
+  - staff benefits and availability
+  - attire and tax-form example documents
+
+## Still missing
+
+### Auth
+
+- staff phone OTP start
+- staff OTP verify
+- staff profile setup endpoint
+
+### Client writes
+
+- hub create
+- hub update
+- hub delete
+- hub NFC assignment
+- assign manager to hub
+- invoice approve
+- invoice dispute
+
+### Staff writes
+
+- availability update
+- availability quick set
+- shift apply
+- shift decline
+- request swap
+- personal info update
+- preferred locations update
+- profile photo upload wrapper
+
+### Reports
+
+- report summary
+- daily ops
+- spend
+- coverage
+- forecast
+- performance
+- no-show
+
+### Core persistence
+
+- `core-api-v2` verification jobs still need durable SQL persistence
--- a/docs/BACKEND/API_GUIDES/V2/unified-api.md
+++ b/docs/BACKEND/API_GUIDES/V2/unified-api.md
@@ -0,0 +1,50 @@
+# Unified API V2
+
+This service exists so frontend can use one base URL without forcing backend into one codebase.
+
+## Base idea
+
+Frontend talks to one service:
+
+- `krow-api-v2`
+
+That gateway does two things:
+
+1. exposes auth/session endpoints
+2. forwards requests to the right internal v2 service
+
+## Route groups
+
+### Auth
+
+- `POST /auth/client/sign-in`
+- `POST /auth/client/sign-up`
+- `POST /auth/sign-out`
+- `POST /auth/client/sign-out`
+- `POST /auth/staff/sign-out`
+- `GET /auth/session`
+
+### Proxy passthrough
+
+- `/core/*` -> `core-api-v2`
+- `/commands/*` -> `command-api-v2`
+- `/query/*` -> `query-api-v2`
+
+### Mobile read models
+
+These are served by `query-api-v2` but frontend should still call them through the unified host:
+
+- `/query/client/*`
+- `/query/staff/*`
+
+## Why this shape
+
+- frontend gets one base URL
+- backend keeps separate read, write, and service helpers
+- we can scale or refactor internals later without breaking frontend paths
+
+## Current auth note
+
+Client email/password auth is wrapped here.
+
+Staff phone OTP is not wrapped here yet. That still needs its own proper provider-backed implementation rather than a fake backend OTP flow.