docs(api): consolidate v2 frontend backend guides

2026-03-12 14:09:05 +01:00
parent fe43ff23cf
commit b61babe3c6
9 changed files with 740 additions and 910 deletions
--- a/docs/BACKEND/API_GUIDES/V2/README.md
+++ b/docs/BACKEND/API_GUIDES/V2/README.md
@@ -0,0 +1,120 @@
+# V2 Backend API Guide
+
+This is the frontend-facing source of truth for the v2 backend.
+
+If you are building against the new backend, start here.
+
+## 1) Which service to use
+
+| Use case | Service |
+| --- | --- |
+| File upload, signed URLs, model calls, rapid order helpers, verification flows | `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`
+
+## 3) Auth and headers
+
+All protected routes require:
+
+```http
+Authorization: Bearer <firebase-id-token>
+```
+
+All 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
+
+### Ready now
+
+- `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
+
+### Do not move yet
+
+- reports
+- payments and finance screens
+- undocumented dashboard reads
+- undocumented scheduling reads and writes
+- any flow that assumes verification history is durable in SQL
+
+## 5) Important caveat
+
+`core-api-v2` is usable now, but verification job state is not yet persisted to `krow-sql-v2`.
+
+What is durable today:
+- uploaded files in Google Cloud Storage
+- generated signed URLs
+- model invocation itself
+
+What is not yet durable:
+- verification job history
+- verification review history
+- verification event history
+
+That means frontend can integrate with verification routes now, but should not treat them as mission-critical durable state yet.
+
+## 6) Recommended frontend environment variables
+
+```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
+```
+
+## 7) Service docs
+
+- [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`.