150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
# V2 Backend API Guide
|
|
|
|
This is the frontend-facing source of truth for the v2 backend.
|
|
|
|
## 1) Use one base URL
|
|
|
|
Frontend should call one public gateway:
|
|
|
|
```env
|
|
API_V2_BASE_URL=https://krow-api-v2-933560802882.us-central1.run.app
|
|
```
|
|
|
|
Frontend should not call the internal `core`, `command`, or `query` Cloud Run services directly.
|
|
|
|
## 2) Current status
|
|
|
|
The unified v2 gateway is ready for frontend integration in `dev`.
|
|
|
|
What was validated live against the deployed stack:
|
|
|
|
- client sign-in
|
|
- staff auth bootstrap
|
|
- client dashboard, billing, coverage, hubs, vendors, managers, team members, orders, and reports
|
|
- client coverage incident feed for geofence and override review
|
|
- client hub, order, coverage review, device token, and late-worker cancellation 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, push token registration, clock-in, clock-out, location stream upload, 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
|
|
export FIREBASE_WEB_API_KEY="$(gcloud secrets versions access latest --secret=firebase-web-api-key --project=krow-workforce-dev)"
|
|
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
|
|
|
|
Protected routes require:
|
|
|
|
```http
|
|
Authorization: Bearer <firebase-id-token>
|
|
```
|
|
|
|
Write routes also require:
|
|
|
|
```http
|
|
Idempotency-Key: <unique-per-user-action>
|
|
```
|
|
|
|
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
|
|
{
|
|
"code": "STRING_CODE",
|
|
"message": "Human readable message",
|
|
"details": {},
|
|
"requestId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 4) Attendance policy and monitoring
|
|
|
|
V2 now supports an explicit attendance proof policy:
|
|
|
|
- `NFC_REQUIRED`
|
|
- `GEO_REQUIRED`
|
|
- `EITHER`
|
|
|
|
The effective policy is resolved as:
|
|
|
|
1. shift override if present
|
|
2. hub default if present
|
|
3. fallback to `EITHER`
|
|
|
|
For geofence-heavy staff flows, frontend should read the policy from:
|
|
|
|
- `GET /staff/clock-in/shifts/today`
|
|
- `GET /staff/shifts/:shiftId`
|
|
- `GET /client/hubs`
|
|
|
|
Important operational rules:
|
|
|
|
- outside-geofence clock-ins can be accepted only when override is enabled and a written reason is provided
|
|
- NFC mismatches are rejected and are not overrideable
|
|
- attendance proof logs are durable in SQL and raw object storage
|
|
- device push tokens are durable in SQL and can be registered separately for client and staff apps
|
|
- background location streams are stored as raw batch payloads in the private v2 bucket and summarized in SQL for query speed
|
|
- incident review lives on `GET /client/coverage/incidents`
|
|
- confirmed late-worker recovery is exposed on `POST /client/coverage/late-workers/:assignmentId/cancel`
|
|
- queued alerts are written to `notification_outbox`, dispatched by the private Cloud Run worker service `krow-notification-worker-v2`, and recorded in `notification_deliveries`
|
|
|
|
## 5) Route model
|
|
|
|
Frontend sees one base URL and one route shape:
|
|
|
|
- `/auth/*`
|
|
- `/client/*`
|
|
- `/staff/*`
|
|
- direct upload aliases like `/upload-file` and `/staff/profile/*`
|
|
|
|
Internally, the gateway still forwards to:
|
|
|
|
| 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` |
|
|
|
|
## 6) Frontend integration rule
|
|
|
|
Use the unified routes first.
|
|
|
|
Do not build new frontend work on:
|
|
|
|
- `/query/tenants/*`
|
|
- `/commands/*`
|
|
- `/core/*`
|
|
|
|
Those routes still exist for backend/internal compatibility, but mobile/frontend migration should target the unified surface documented in [Unified API](./unified-api.md).
|
|
|
|
## 7) Docs
|
|
|
|
- [Authentication](./authentication.md)
|
|
- [Unified API](./unified-api.md)
|
|
- [Core API](./core-api.md)
|
|
- [Command API](./command-api.md)
|
|
- [Query API](./query-api.md)
|
|
- [Mobile API Reconciliation](./mobile-api-gap-analysis.md)
|