143 lines
3.6 KiB
Markdown
143 lines
3.6 KiB
Markdown
# V2 Backend API Guide
|
|
|
|
This is the frontend-facing source of truth for the v2 backend.
|
|
|
|
## 1) Frontend entrypoint
|
|
|
|
Frontend should target one public base URL:
|
|
|
|
```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, 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` |
|
|
|
|
## 3) Auth and headers
|
|
|
|
Protected routes require:
|
|
|
|
```http
|
|
Authorization: Bearer <firebase-id-token>
|
|
```
|
|
|
|
Command routes also require:
|
|
|
|
```http
|
|
Idempotency-Key: <unique-per-user-action>
|
|
```
|
|
|
|
All services return the same error envelope:
|
|
|
|
```json
|
|
{
|
|
"code": "STRING_CODE",
|
|
"message": "Human readable message",
|
|
"details": {},
|
|
"requestId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 4) What frontend can use now on this branch
|
|
|
|
### Unified gateway
|
|
|
|
- `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/*`
|
|
|
|
### Client read routes
|
|
|
|
- `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`
|
|
|
|
### Staff read routes
|
|
|
|
- `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`
|
|
|
|
### Existing v2 routes still valid
|
|
|
|
- `/core/*` routes documented in `core-api.md`
|
|
- `/commands/*` routes documented in `command-api.md`
|
|
- `/query/tenants/*` routes documented in `query-api.md`
|
|
|
|
## 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`
|
|
|
|
## 6) Docs
|
|
|
|
- [Unified API](./unified-api.md)
|
|
- [Core API](./core-api.md)
|
|
- [Command API](./command-api.md)
|
|
- [Query API](./query-api.md)
|
|
- [Mobile gap analysis](./mobile-api-gap-analysis.md)
|