Alpha stage commit

docs/09_api_contract.md

@@ -0,0 +1,121 @@
+# API Contract
+
+The machine-readable OpenAPI draft is in `schemas/openapi.yaml`.
+
+## Core endpoints
+
+### Create trip
+
+`POST /v1/trips`
+
+Creates a trip shell from user inputs.
+
+### Plan route
+
+`POST /v1/routes/plan`
+
+Input:
+
+- start/end/imported GPX,
+- profile,
+- constraints,
+- preferred providers.
+
+Output:
+
+- route id,
+- geometry,
+- distance/elevation,
+- scores,
+- warnings,
+- candidate alternatives.
+
+### Plan stages
+
+`POST /v1/stages/plan`
+
+Input:
+
+- route id,
+- day count/date range,
+- daily constraints,
+- sleep preferences.
+
+Output:
+
+- stage cards,
+- Plan A/B endpoints,
+- sleep/food/water/repair/bailout candidates,
+- stage warnings.
+
+### Corridor POIs
+
+`GET /v1/routes/{route_id}/pois?category=water&buffer_km=5`
+
+Returns route-relevant POIs with distance along route, detour distance, confidence, and source.
+
+### Critical gaps
+
+`GET /v1/routes/{route_id}/gaps`
+
+Returns computed gaps for water, food, sleep, repair, bailout, and charging.
+
+### Rule cards
+
+`GET /v1/rules?bbox=minLon,minLat,maxLon,maxLat&route_id=...`
+
+Returns route- or area-specific advisory cards.
+
+### Offline pack
+
+`POST /v1/offline-packs`
+
+Generates a manifest and download URLs for cached trip data.
+
+### Export
+
+`GET /v1/routes/{route_id}/export?format=gpx`
+
+MVP: GPX. Later: TCX and FIT.
+
+### Local report
+
+`POST /v1/reports`
+
+Submits a dated, location-bound structured report. The MVP response includes `moderationStatus`, `trustScore`, and `queuedOffline` when an offline client id is supplied.
+
+### Report sync
+
+`POST /v1/reports/sync`
+
+Future endpoint. The current MVP queues reports client-side while offline and resubmits them through `POST /v1/reports`.
+
+## Error handling
+
+Errors should include:
+
+- machine-readable code,
+- human-readable message,
+- remediation suggestion,
+- provider/source if relevant.
+
+Example:
+
+```json
+{
+  "error": "PROVIDER_UNAVAILABLE",
+  "message": "routing provider \"openrouteservice\" is not available in this MVP runtime. Set ROUTING_PROVIDER=mock for fixture mode or configure the selected provider adapter and credentials.",
+  "details": {
+    "providerName": "openrouteservice",
+    "providerType": "routing",
+    "setupHint": "Set ROUTING_PROVIDER=mock for fixture mode or configure the selected provider adapter and credentials."
+  }
+}
+```
+
+## Current MVP notes
+
+- `schemas/openapi.yaml` reflects implemented response fields including route segments, surface breakdown, attribution, stage POI buckets, offline manifest metadata, and report queue ids.
+- `format=gpx` is implemented. TCX/FIT are reserved for future `DeviceExportProvider` adapters.
+- Mock providers are deterministic and require no external keys.
+- Rule cards and access/protected-area warnings are advisory and confidence-scored.