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,218 @@
+openapi: 3.1.0
+info:
+  title: MobilityOps API
+  version: 0.1.0
+  description: Contract baseline for the MobilityOps proof of concept.
+servers:
+  - url: http://localhost:8128
+paths:
+  /health:
+    get:
+      operationId: health
+      responses:
+        '200':
+          description: Healthy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Health'
+  /api/v1/dashboard:
+    get:
+      operationId: getDashboard
+      responses:
+        '200':
+          description: Persisted operational summary
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dashboard'
+  /api/v1/vehicles:
+    get:
+      operationId: listVehicles
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+        - in: query
+          name: attention_only
+          schema:
+            type: boolean
+            default: false
+      responses:
+        '200':
+          description: Vehicle list
+  /api/v1/vehicles/{public_ref}:
+    get:
+      operationId: getVehicle
+      parameters:
+        - $ref: '#/components/parameters/PublicRef'
+      responses:
+        '200':
+          description: Vehicle detail
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/bookings:
+    get:
+      operationId: listBookings
+      responses:
+        '200':
+          description: Booking list
+  /api/v1/bookings/{public_ref}:
+    get:
+      operationId: getBooking
+      parameters:
+        - $ref: '#/components/parameters/PublicRef'
+      responses:
+        '200':
+          description: Booking detail
+  /api/v1/bookings/{public_ref}/return:
+    post:
+      operationId: registerVehicleReturn
+      parameters:
+        - $ref: '#/components/parameters/PublicRef'
+        - in: header
+          name: Idempotency-Key
+          required: true
+          schema:
+            type: string
+            minLength: 8
+            maxLength: 128
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterReturnRequest'
+      responses:
+        '200':
+          description: Existing idempotent result replayed
+        '201':
+          description: Return registered
+        '409':
+          description: State or concurrency conflict
+  /api/v1/data-quality/issues:
+    get:
+      operationId: listDataQualityIssues
+      responses:
+        '200':
+          description: Quality issues
+  /api/v1/data-quality/issues/{public_ref}/merge-customers:
+    post:
+      operationId: mergeDuplicateCustomers
+      parameters:
+        - $ref: '#/components/parameters/PublicRef'
+      responses:
+        '200':
+          description: Merge completed
+        '409':
+          description: Issue no longer mergeable
+  /api/v1/knowledge/questions:
+    post:
+      operationId: askKnowledgeQuestion
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [question]
+              properties:
+                question:
+                  type: string
+                  minLength: 3
+                  maxLength: 1000
+      responses:
+        '200':
+          description: Grounded, insufficient or unavailable answer
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GroundedAnswer'
+  /api/v1/integrations/mcp/operations-summary:
+    get:
+      operationId: mcpOperationsSummary
+      security:
+        - serviceToken: []
+      responses:
+        '200':
+          description: Read-only operational summary
+components:
+  securitySchemes:
+    serviceToken:
+      type: http
+      scheme: bearer
+  parameters:
+    PublicRef:
+      in: path
+      name: public_ref
+      required: true
+      schema:
+        type: string
+  responses:
+    NotFound:
+      description: Not found
+  schemas:
+    Health:
+      type: object
+      required: [status, service]
+      properties:
+        status:
+          const: ok
+        service:
+          const: mobilityops-api
+    Dashboard:
+      type: object
+      required: [metrics, attention_items]
+      properties:
+        metrics:
+          type: object
+          additionalProperties:
+            type: integer
+        attention_items:
+          type: array
+          items:
+            type: object
+    RegisterReturnRequest:
+      type: object
+      required: [end_odometer_km, fuel_level_percent, cleanliness_ok, damage_reported, technical_warning]
+      properties:
+        end_odometer_km:
+          type: integer
+          minimum: 0
+        fuel_level_percent:
+          type: integer
+          minimum: 0
+          maximum: 100
+        cleanliness_ok:
+          type: boolean
+        damage_reported:
+          type: boolean
+        technical_warning:
+          type: boolean
+        notes:
+          type: string
+          maxLength: 2000
+    GroundedAnswer:
+      type: object
+      required: [answer, evidence_state, sources, provider, correlation_id]
+      properties:
+        answer:
+          type: string
+        evidence_state:
+          enum: [grounded, insufficient, unavailable]
+        sources:
+          type: array
+          items:
+            type: object
+            required: [document_id, title, version, section, excerpt]
+            properties:
+              document_id: {type: string}
+              title: {type: string}
+              version: {type: string}
+              section: {type: string}
+              excerpt: {type: string}
+        provider:
+          type: string
+        correlation_id:
+          type: string