add passenger telemetry

docs/openapi-draft.yaml

@@ -23,6 +23,7 @@ tags:
   - name: Alerts
   - name: Users
   - name: Telemetry
+  - name: Passenger Telemetry
   - name: Realtime
 paths:
   /health:
@@ -1694,7 +1695,8 @@ paths:
   /api/v1/telemetry/ingest:
     post:
       tags: [Telemetry]
-      summary: Ingest GPS telemetry
+      summary: Ingest official vehicle GPS telemetry
+      description: For driver apps, GPS trackers, and official telemetry only. Passenger apps must use /api/v1/passenger-telemetry/ingest instead.
       security:
         - BearerAuth: []
         - ApiKeyAuth: []
@@ -1733,10 +1735,58 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/passenger-telemetry/ingest:
+    post:
+      tags: [Passenger Telemetry]
+      summary: Ingest anonymized passenger telemetry
+      description: |
+        Accepts opt-in, temporary, anonymous passenger geo-signals for short-lived aggregation.
+        Raw passenger points are not exposed through public REST APIs or WebSocket messages.
+        The server may emit only aggregate approximate virtual vehicles with source=crowdsourced.
+      security:
+        - BearerAuth: []
+        - ApiKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PassengerTelemetryIngestRequest'
+            example:
+              session_id: temporary-anonymous-id
+              latitude: 55.485
+              longitude: 28.768
+              accuracy_m: 18.5
+              speed_kmh: 32
+              heading: 91
+              observed_at: '2026-05-20T12:30:00Z'
+              route_id: '12'
+              stop_id: '123'
+              app_state: foreground
+      responses:
+        '202':
+          description: Passenger signal accepted for aggregation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PassengerTelemetryIngestResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /api/v1/realtime/routes/{routeId}/vehicles:
     get:
       tags: [Realtime]
       summary: Live vehicles snapshot for route
+      description: Returns official live vehicles plus aggregate approximate crowdsourced virtual vehicles when confidence is sufficient. Raw passenger points are never returned.
       security:
         - BearerAuth: []
         - ApiKeyAuth: []
@@ -2879,11 +2929,66 @@ components:
         sourceRef:
           type: string
           nullable: true
+    PassengerTelemetryIngestRequest:
+      type: object
+      required: [session_id, latitude, longitude]
+      additionalProperties: false
+      properties:
+        session_id:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: Temporary anonymous session id; not a user, account, phone, or device id.
+        latitude:
+          type: number
+          minimum: -90
+          maximum: 90
+        longitude:
+          type: number
+          minimum: -180
+          maximum: 180
+        accuracy_m:
+          type: number
+          minimum: 0
+          maximum: 1000
+          nullable: true
+        speed_kmh:
+          type: number
+          minimum: 0
+          maximum: 120
+          nullable: true
+        heading:
+          type: number
+          minimum: 0
+          maximum: 360
+          nullable: true
+        observed_at:
+          type: string
+          format: date-time
+          nullable: true
+        route_id:
+          oneOf:
+            - type: integer
+            - type: string
+          nullable: true
+          description: Optional client hint; server verifies it before aggregation.
+        stop_id:
+          oneOf:
+            - type: integer
+            - type: string
+          nullable: true
+        app_state:
+          type: string
+          enum: [foreground, background]
+          nullable: true
     LiveVehicleState:
       type: object
       properties:
         vehicle_id:
-          type: integer
+          oneOf:
+            - type: integer
+            - type: string
+          description: Official vehicles use numeric ids; crowdsourced virtual vehicles use crowd:{routeId}:{clusterId}.
         vehicle_number:
           type: string
           nullable: true
@@ -2917,12 +3022,31 @@ components:
         accuracy_meters:
           type: number
           nullable: true
+        accuracy_m:
+          type: number
+          nullable: true
         source_type:
           type: string
           nullable: true
         source_ref:
           type: string
           nullable: true
+        source:
+          type: string
+          enum: [official, crowdsourced]
+          nullable: true
+        confidence:
+          type: number
+          minimum: 0
+          maximum: 1
+          nullable: true
+        confidence_label:
+          type: string
+          enum: [LOW, MEDIUM, HIGH]
+          nullable: true
+        is_estimated:
+          type: boolean
+          nullable: true
         last_seen_at:
           type: string
           format: date-time
@@ -2942,3 +3066,10 @@ components:
           type: string
         vehicle:
           $ref: '#/components/schemas/LiveVehicleState'
+    PassengerTelemetryIngestResponse:
+      type: object
+      required: [accepted]
+      properties:
+        accepted:
+          type: boolean
+          example: true