Initial MobilityOps build pack (docs, contracts, scaffold)

2026-08-01 20:34:43 +02:00
commit 24188d9b10
71 changed files with 3412 additions and 0 deletions
@@ -0,0 +1,75 @@
+# API contract summary
+
+The machine-readable baseline is `contracts/openapi.yaml`.
+
+## Authentication
+
+The demo may use signed server-issued sessions or short-lived JWTs. Demo-role buttons create an authenticated session; they do not bypass authorization middleware.
+
+## Required routes
+
+### System and demo
+
+- `GET /health`
+- `GET /api/v1/system/status`
+- `POST /api/v1/demo/login`
+- `POST /api/v1/demo/reset` — Operations Manager only
+
+### Dashboard
+
+- `GET /api/v1/dashboard`
+
+### Vehicles
+
+- `GET /api/v1/vehicles`
+- `GET /api/v1/vehicles/{public_ref}`
+
+### Bookings and return
+
+- `GET /api/v1/bookings`
+- `GET /api/v1/bookings/{public_ref}`
+- `POST /api/v1/bookings/{public_ref}/return`
+
+Return commands require an `Idempotency-Key` header and optimistic version where relevant.
+
+### Data quality
+
+- `GET /api/v1/data-quality/issues`
+- `GET /api/v1/data-quality/issues/{public_ref}`
+- `POST /api/v1/data-quality/issues/{public_ref}/defer`
+- `POST /api/v1/data-quality/issues/{public_ref}/reject`
+- `POST /api/v1/data-quality/issues/{public_ref}/merge-customers`
+
+### Knowledge
+
+- `POST /api/v1/knowledge/questions`
+- `GET /api/v1/knowledge/status`
+
+### Automation and audit
+
+- `GET /api/v1/workflows`
+- `POST /api/v1/workflows/{event_id}/retry`
+- `GET /api/v1/audit`
+
+### MCP-provider endpoints
+
+Service-token protected:
+
+- `GET /api/v1/integrations/mcp/operations-summary`
+- `GET /api/v1/integrations/mcp/attention-vehicles`
+- `GET /api/v1/integrations/mcp/vehicles/{public_ref}`
+
+Knowledge search may be routed by the Hub directly to RAGcore or through a narrowly scoped MobilityOps façade. Use the contract chosen in `docs/10-mcp-hub-integration.md`.
+
+## Error shape
+
+```json
+{
+  "error": {
+    "code": "ODOMETER_REGRESSION",
+    "message": "The submitted reading is below the current canonical odometer.",
+    "correlation_id": "...",
+    "details": {}
+  }
+}
+```