feat(api): complete unified v2 mobile surface

2026-03-13 17:02:24 +01:00
parent 817a39e305
commit b455455a49
39 changed files with 7726 additions and 506 deletions
--- a/docs/BACKEND/API_GUIDES/V2/README.md
+++ b/docs/BACKEND/API_GUIDES/V2/README.md
@@ -2,33 +2,48 @@

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

-## 1) Frontend entrypoint
+## 1) Use one base URL

-Frontend should target one public base URL:
+Frontend should call one public gateway:

 ```env
-API_V2_BASE_URL=<krow-api-v2-url>
+API_V2_BASE_URL=https://krow-api-v2-933560802882.us-central1.run.app
 ```

-The unified v2 gateway exposes:
+Frontend should not call the internal `core`, `command`, or `query` Cloud Run services directly.

- `/auth/*`
- `/core/*`
- `/commands/*`
- `/query/*`
- `/query/client/*`
- `/query/staff/*`
+## 2) Current status

-Internal services still stay separate behind that gateway.
+The unified v2 gateway is ready for frontend integration in `dev`.

-## 2) Internal service split
+What was validated live against the deployed stack:

-| Use case | Internal service |
-| --- | --- |
-| File upload, signed URLs, model calls, verification helpers | `core-api-v2` |
-| Business writes and workflow actions | `command-api-v2` |
-| Screen reads and mobile read models | `query-api-v2` |
-| Frontend-facing single host and auth wrappers | `krow-api-v2` |
+- client sign-in
+- staff auth bootstrap
+- client dashboard, billing, coverage, hubs, vendors, managers, team members, orders, and reports
+- client hub and order write flows
+- client invoice approve and dispute
+- staff dashboard, availability, payments, shifts, profile sections, documents, certificates, attire, bank accounts, benefits, and time card
+- staff availability, profile, tax form, bank account, shift apply, shift accept, clock-in, clock-out, and swap request
+- direct file upload helpers and verification job creation through the unified host
+- client and staff sign-out
+
+The live validation command is:
+
+```bash
+source ~/.nvm/nvm.sh
+nvm use 23.5.0
+node backend/unified-api/scripts/live-smoke-v2-unified.mjs
+```
+
+The demo tenant can be reset with:
+
+```bash
+source ~/.nvm/nvm.sh
+nvm use 23.5.0
+cd backend/command-api
+npm run seed:v2-demo
+```

 ## 3) Auth and headers

@@ -38,13 +53,19 @@ Protected routes require:
 Authorization: Bearer <firebase-id-token>
 ```

-Command routes also require:
+Write routes also require:

 ```http
 Idempotency-Key: <unique-per-user-action>
 ```

-All services return the same error envelope:
+For now:
+
+- backend wraps sign-in and sign-out
+- frontend can keep using Firebase token refresh on the client
+- backend is the only thing frontend should call for session-oriented API flows
+
+All routes return the same error envelope:

 ```json
 {
@@ -55,83 +76,35 @@ All services return the same error envelope:
 }
 ```

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

-### Unified gateway
+Frontend sees one base URL and one route shape:

- `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/*`
+- `/auth/*`
+- `/client/*`
+- `/staff/*`
+- direct upload aliases like `/upload-file` and `/staff/profile/*`

-### Client read routes
+Internally, the gateway still forwards to:

- `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`
+| Frontend use case | Internal service |
+| --- | --- |
+| auth/session wrapper | `krow-api-v2` |
+| uploads, signed URLs, model calls, verification workflows | `core-api-v2` |
+| writes and workflow actions | `command-api-v2` |
+| reads and mobile read models | `query-api-v2` |

-### Staff read routes
+## 5) Frontend integration rule

- `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`
+Use the unified routes first.

-### Existing v2 routes still valid
+Do not build new frontend work on:

- `/core/*` routes documented in `core-api.md`
- `/commands/*` routes documented in `command-api.md`
- `/query/tenants/*` routes documented in `query-api.md`
+- `/query/tenants/*`
+- `/commands/*`
+- `/core/*`

-## 5) Remaining gaps after this slice
-
-Still not implemented yet:
-
- 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`
+Those routes still exist for backend/internal compatibility, but mobile/frontend migration should target the unified surface documented in [Unified API](./unified-api.md).

 ## 6) Docs

@@ -139,4 +112,4 @@ Still not implemented yet:
 - [Core API](./core-api.md)
 - [Command API](./command-api.md)
 - [Query API](./query-api.md)
- [Mobile gap analysis](./mobile-api-gap-analysis.md)
+- [Mobile API Reconciliation](./mobile-api-gap-analysis.md)