repzo 1.0.292 → 1.0.293

package/src/oas/activity-ai-object-detection-session-frame.yaml

@@ -0,0 +1,600 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - Activity AI Object Detection Session Frame
+  version: 1.0.0
+  description: |
+    **Session Frame intake** is the write-only multipart endpoint the
+    mobile AR app POSTs each captured frame to during a shelf scan. It
+    is the ingest half of the Object Detection Sessions feature — see
+    `ai-object-detection-session` for the parent record. It replaces the
+    removed `/ai-object-detection-session-frame` endpoint, adding the
+    field-sales context: every frame is attributed to a **client**
+    (store) and optionally the capturing **rep**.
+
+    **What it does (per frame).**
+    1. Parses `meta_inline` (a JSON text field carrying the AR pose,
+       intrinsics, tracking quality, depth stats, frame id, and the
+       device's `session_id`).
+    2. Validates `client` — a `clients` `_id` that must exist (and not be
+       disabled) within the caller's namespace.
+    3. Upserts the parent `ai-object-detection-session` keyed by
+       `(company_namespace, session_id)` — the first frame opens the
+       session, later frames reuse it. Every frame (re)stamps the
+       session's `client` and — when sent — its `rep` and field-sales
+       context (`visit_id` / `route` / `business_day` / `time_zone`); a
+       frame without them never erases what an earlier one wrote. A
+       session without a `business_day` gets one stamped ONCE from the
+       capture time under the rep's stamping context (open-day snapshot:
+       shift schedule, `end_of_day` cut, time zone — the way every other
+       activity gets its business day). The evaluator copies the visit
+       id, route and business day onto the mission/metric results — that
+       is how the assigned-missions read tells "done in THIS visit" and
+       counts per-day demands in business days.
+    4. Resolves the frame image from `media_id` — the
+       `media.mediaStorages` `_id` of the **pre-uploaded** image (the
+       client uploads the RGB frame separately, e.g. via a presigned
+       URL, and passes its id here). The id is validated to exist within
+       the caller's namespace; the raw image bytes are **not** sent to
+       this endpoint. Optional `depth` / `confidence` binary blobs are
+       still uploaded inline as multipart files.
+    5. Materializes the frame as a normal `ai-object-detection-task`
+       carrying `session`, `frame_meta`, `file_media` (= `media_id`),
+       `depth_media`, and `confidence_media` — the inference/analysis
+       pipeline is unchanged.
+    6. Persists an activity frame document (collection
+       `ai.objectDetectionSessionFrames`) carrying `client`, `rep`, the
+       session/task refs, and the optional field-sales context
+       (`visit_id` / `route` / `business_day` / `time_zone` / `geo_tag` /
+       `time`). The image, per-frame AR meta, and
+       depth/confidence media are not duplicated — they live on the
+       referenced task.
+    7. Atomically increments the session's `frames_total`,
+       `frames_accepted`, and `tasks_count` counters.
+
+    **Who calls it.** Reps (rep-auth via `x-rep-login` + JWT) or an API
+    key. The tenant key (`company_namespace`) is injected from the
+    caller's credential. When authenticated as a rep and `rep` is not
+    sent, it defaults to the rep in the token.
+
+    **Only `create` is allowed.** `find`, `get`, `update`, `patch`, and
+    `remove` all reject. Query / inspect frames via the
+    `ai-object-detection-task` service filtered by `?session=:id`.
+
+    **Content type.** `multipart/form-data` — the `media_id` + `client` +
+    `meta_inline` text parts, plus optional `depth` / `confidence` file
+    parts. An `application/json` body carrying the same text fields is
+    also accepted (`meta_inline` / `geo_tag` may then be objects instead of
+    JSON strings); binary depth/confidence parts cannot be sent that way.
+
+    **Required fields per mode.** Frame post: `client`, `media_id` (top-level
+    or inside `meta_inline`) and `session_id` (top-level or inside
+    `meta_inline`). Completion marker: `session_id` + `session_complete`.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /activity-ai-object-detection-session-frame:
+    post:
+      summary: Submit one AR frame (or the upload-complete marker)
+      description: |
+        Multipart frame intake. Validates the `client`, upserts the parent
+        session (stamping its `client` and optional `category`), references
+        the pre-uploaded frame image by `media_id`, uploads the optional
+        depth/confidence blobs, materializes a task, persists the activity
+        frame document, and increments the session counters. Returns the
+        resulting ids.
+
+        **Completion marker:** when `session_complete=true` (top-level field
+        or inside `meta_inline`) the post carries NO frame — only
+        `session_id`. The session flips `open` → `uploaded`, and when it
+        carries a detection `category` (and its verdict is not `rejected`)
+        one background analysis is fired per category `model_settings` item,
+        serially. Responds with `SessionCompleteResult` instead of
+        `FrameResult`.
+      operationId: createActivityAiObjectDetectionSessionFrame
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FrameCreateBody"
+          multipart/form-data:
+            schema:
+              type: object
+              description: |
+                See the service description for which fields are required in
+                frame mode vs completion-marker mode.
+              properties:
+                media_id:
+                  type: string
+                  description: |
+                    `media.mediaStorages` `_id` of the pre-uploaded RGB frame
+                    image. Must exist within the caller's namespace. Becomes the
+                    task's `file_media`. May also be supplied inside `meta_inline`.
+                client:
+                  type: string
+                  description: |
+                    `clients` `_id` the captured shelf belongs to. Must exist
+                    (and not be disabled) within the caller's namespace. Stored
+                    on the activity frame document and stamped onto the parent
+                    session.
+                rep:
+                  type: string
+                  description: |
+                    Optional `representatives` `_id` of the capturing rep.
+                    Defaults to the rep in the token for rep-auth calls.
+                depth:
+                  type: string
+                  format: binary
+                  description: Optional raw float32 depth blob.
+                confidence:
+                  type: string
+                  format: binary
+                  description: Optional raw uint8 depth-confidence blob.
+                meta_inline:
+                  type: string
+                  description: |
+                    JSON-encoded per-frame AR metadata. Must include
+                    `session_id` unless it is sent top-level. See `MetaInline`
+                    in Schemas for the parsed shape.
+                meta:
+                  type: string
+                  description: Alias for `meta_inline`.
+                session_id:
+                  type: string
+                  description: |
+                    Fallback device session id if not present inside
+                    `meta_inline`.
+                visit_id:
+                  type: string
+                  description: |
+                    The DEVICE visit id (`visits.visit_id`) of the visit the
+                    scan happens in — the same id every activity carries.
+                    Visits are created offline and may not be synced yet, so it
+                    is stored as-is on the frame and the parent session and
+                    never resolved to a server ref. Also accepted inside
+                    `meta_inline` (the text part wins).
+                route:
+                  type: string
+                  description: Optional `sv.routes` `_id` of the visit's route.
+                business_day:
+                  type: string
+                  description: "Optional business day of the visit, `YYYY-MM-DD` (rejected otherwise). When absent the session is stamped once from the capture time under the rep's stamping context."
+                time_zone:
+                  type: string
+                  description: Optional IANA timezone of the device at capture.
+                geo_tag:
+                  type: string
+                  description: |
+                    Optional JSON-encoded `{lat, lng, formatted_address?}`
+                    capture location. `lat`/`lng` must be numeric.
+                time:
+                  type: number
+                  description: Optional device epoch (ms) of the capture.
+                session_complete:
+                  type: string
+                  enum: ["true"]
+                  description: |
+                    Completion-marker mode — send with `session_id` (and no
+                    frame parts) once the device's upload queue drains. Also
+                    accepted inside `meta_inline`.
+                company_namespace:
+                  type: array
+                  items: { type: string }
+                  description: Optional tenant namespace override for SDK callers.
+      responses:
+        "201":
+          description: |
+            Frame intake returns the created frame's session/task/frame/media
+            ids (`FrameResult`); a completion marker returns the session
+            status + auto-analysis outcome (`SessionCompleteResult`).
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/FrameResult"
+                  - $ref: "#/components/schemas/SessionCompleteResult"
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: api-key
+      description: |
+        Server-issued API key. Also accepted via the `x-api-key` header or the
+        `?apiKey=` query parameter as fallbacks.
+    JwtAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: |
+        Raw JWT in the `Authorization` header — **no `Bearer ` prefix**.
+        Obtained from `POST /authenticate` (admin / rep / client login).
+  schemas:
+    MetaInline:
+      type: object
+      description: |
+        Parsed shape of the `meta_inline` JSON text part. Fields map onto
+        the materialized task's `frame_meta`. The device's camelCase aliases
+        (`trackingScore`, `eulerYPR`, `imageStats`, `driftM`, `velocityMps`,
+        `imageRotationDeg`, `tracking` as a bare state string) are tolerated
+        and normalized; invalid values (e.g. `shutter: "—"`) are dropped.
+      properties:
+        session_id:
+          type: string
+          description: Device-generated session id (4-char).
+        media_id:
+          type: string
+          description: |
+            Fallback `media.mediaStorages` `_id` of the frame image, if not
+            sent as the top-level `media_id` form field.
+        visit_id:
+          type: string
+          description: Alias of the `visit_id` text part (the text part wins).
+        route:
+          type: string
+          description: Alias of the `route` text part.
+        business_day:
+          type: string
+          description: Alias of the `business_day` text part.
+        time_zone:
+          type: string
+          description: Alias of the `time_zone` text part.
+        frame_id:
+          type: number
+          description: Session-scoped frame counter.
+        ts:
+          type: number
+          description: Device epoch (ms).
+        pose:
+          type: array
+          items: { type: number }
+          description: 16-float 4x4 pose matrix, column-major.
+        euler_ypr:
+          type: array
+          items: { type: number }
+          description: 3-float yaw/pitch/roll in degrees.
+        intrinsics:
+          type: object
+          properties:
+            fx: { type: number }
+            fy: { type: number }
+            cx: { type: number }
+            cy: { type: number }
+        distortion:
+          type: object
+          properties:
+            k1: { type: number }
+            k2: { type: number }
+            k3: { type: number }
+            p1: { type: number }
+            p2: { type: number }
+        tracking:
+          type: object
+          properties:
+            state: { type: string, enum: [NORMAL, LIMITED, LOST] }
+            score: { type: number }
+            drift_m: { type: number }
+            velocity_mps: { type: number }
+        distance_to_shelf_m:
+          type: number
+          description: |
+            Shelf-distance gate (meters) captured at the frame. Also accepted
+            as `depth.distanceToShelfM` from the device. Stored on
+            `frame_meta.distance_to_shelf_m` and used by inference back-projection.
+        image_stats:
+          type: object
+          properties:
+            iso: { type: number }
+            shutter: { type: number }
+            lux: { type: number }
+            sharpness:
+              type: number
+              description: >-
+                Variance-of-Laplacian focus measure from the device (higher =
+                sharper, -1 = unmeasured). Persisted on
+                `frame_meta.image_stats.sharpness` — election-quality input.
+        depth:
+          type: object
+          description: >-
+            Depth-map summary from the device. `width`/`height` and the
+            confidence fractions persist on `frame_meta.depth_summary`
+            (election-quality input); `distanceToShelfM` persists on
+            `frame_meta.distance_to_shelf_m`.
+          properties:
+            width: { type: number }
+            height: { type: number }
+            minM:
+              type: number
+              description: Legacy nearest-depth sample (metres) — fallback for `min_distance_depth`.
+            maxM:
+              type: number
+              description: Legacy farthest-depth sample (metres) — fallback for `max_distance_depth`.
+            distanceToShelfM: { type: number }
+            confidence:
+              type: object
+              properties:
+                high: { type: number }
+                medium: { type: number }
+                low: { type: number }
+        depth_source:
+          type: string
+          enum: [lidar, estimated, none]
+        min_distance_depth:
+          type: number
+          description: >-
+            Flat capture-quality key (app >= 0.39.0): nearest depth sample in
+            the frame, meters. Derived from `depth.minM` for older builds.
+            Persisted on `frame_meta.min_distance_depth`.
+        max_distance_depth:
+          type: number
+          description: >-
+            Farthest depth sample in the frame, meters. Derived from
+            `depth.maxM` for older builds. Persisted on
+            `frame_meta.max_distance_depth`.
+        depth_variation:
+          type: number
+          description: >-
+            Depth span of the frame (max - min), meters — the device
+            validator's depth-variation gate input. Derived from
+            `depth.maxM - depth.minM` when absent. Persisted on
+            `frame_meta.depth_variation`.
+        yaw_degree:
+          type: number
+          description: >-
+            Camera yaw at capture, degrees. Derived from `euler_ypr[0]` for
+            older builds. Persisted on `frame_meta.yaw_degree`.
+        pitch_degree:
+          type: number
+          description: >-
+            Camera pitch at capture, degrees (fallback `euler_ypr[1]`).
+            Persisted on `frame_meta.pitch_degree`.
+        roll_degree:
+          type: number
+          description: >-
+            Camera roll at capture, degrees (fallback `euler_ypr[2]`).
+            Persisted on `frame_meta.roll_degree`.
+        frame_sharpness:
+          type: number
+          description: >-
+            Variance-of-Laplacian focus measure (higher = sharper). Falls back
+            to `image_stats.sharpness`; the unmeasured sentinel (-1) is
+            dropped. Persisted on `frame_meta.frame_sharpness`.
+        capture_tier:
+          type: string
+          enum: [good, warn, error]
+          description: >-
+            Device validator verdict for the frame at capture time, evaluated
+            against the polled detection-settings limits. Persisted on
+            `frame_meta.capture_tier`.
+        detection_settings_polled_at:
+          type: number
+          description: >-
+            Epoch ms of the app's last successful detection-settings poll
+            (`/ai-object-detection-detection-settings`) before this frame was
+            submitted — tells analysis which config governed capture.
+            Persisted on `frame_meta.detection_settings_polled_at`.
+        image_rotation_deg:
+          type: number
+          description: >-
+            Degrees the sensor image was rotated CW to produce the stored
+            image — lets inference map the detection box back into the
+            sensor frame exactly. Persisted on `frame_meta.image_rotation_deg`.
+        depth_shape:
+          type: array
+          items: { type: number }
+          description: "[width, height] of the depth blob."
+        image_shape:
+          type: array
+          items: { type: number }
+          description: "[width, height] of the image."
+        device:
+          type: object
+          description: >-
+            Device descriptor — applied to the session on first frame;
+            `app_version` is also persisted per-frame on
+            `frame_meta.app_version`.
+          properties:
+            platform: { type: string }
+            os: { type: string }
+            model: { type: string }
+            app_version: { type: string }
+            ar_engine: { type: string, enum: [ARKit, ARCore] }
+        capture_settings:
+          type: object
+          description: >-
+            Capture configuration in effect for the session — applied to the
+            session on first frame, next to `device`. The dashboard's Capture
+            context panel reads both.
+          properties:
+            rate_hz:
+              type: number
+              description: AR frame capture rate the app was set to (Hz).
+            recording_enabled: { type: boolean }
+            target_distance_m: { type: number }
+            resolution:
+              type: string
+              enum: [medium, high, max]
+              description: Camera format preference active during capture.
+        coverage_m2:
+          type: number
+          description: >-
+            Device-computed swept shelf area for the WHOLE session so far, m²
+            — includes quality-rejected capture attempts that are never
+            uploaded, so the server cannot recompute it. Upserted onto the
+            session via $max (monotonic; frames may arrive out of order).
+        world_alignment:
+          type: string
+          enum: [gravity]
+          description: >-
+            How the AR world's vertical relates to earth vertical. Both ARKit
+            (default `.gravity`) and ARCore run gravity-aligned world frames,
+            so world Y IS earth vertical — recorded on the session so
+            consumers never have to assume it.
+        ground:
+          type: object
+          description: >-
+            Floor lock measured on-device at capture entry (optional — the rep
+            can skip it): the floor's Y in the AR world frame plus lock
+            quality. With the gravity-aligned world, the height above the
+            floor of ANY world point is `y − ground.y_world`. The device
+            re-locks after every AR session restart (the world frame resets),
+            so the last write matches the newest frames' poses. Upserted onto
+            the parent session.
+          properties:
+            y_world:
+              type: number
+              description: Floor height (world Y), metres.
+            samples:
+              type: integer
+              description: Gated depth samples behind the median.
+            spread_m:
+              type: number
+              description: Interquartile spread of those samples, metres — lock quality.
+            camera_height_m:
+              type: number
+              description: Camera height above the floor at lock time, metres.
+        eye_level_m:
+          type: number
+          description: >-
+            Camera height above the locked floor while shooting the shelf
+            (median of the first stable capture frames), metres — ≈ the rep's
+            standing eye level. Upserted onto the parent session.
+        ground_skipped:
+          type: boolean
+          description: >-
+            True when the rep tapped Skip on the floor point — records the
+            deliberate choice so an absent `ground` can be told apart from a
+            lock that never converged. Upserted onto the parent session.
+        category:
+          type: string
+          description: >-
+            Optional `ai-object-detection-category` `_id` picked on the device
+            before calibration. Stamped onto the parent session with every
+            frame; drives the auto-analysis fired by the completion marker.
+            Non-fatal when the category no longer exists (frame is kept,
+            category not stamped).
+        mission:
+          type: string
+          description: >-
+            Optional `ai-object-detection-mission` `_id` the session was
+            STARTED FROM ("SCAN THIS MISSION"). Stamped onto the parent
+            session with every frame — the attribution anchor for mission
+            completions and mission-result rows. Non-fatal when the mission
+            no longer exists (frame is kept, mission not stamped).
+        session_complete:
+          type: boolean
+          description: >-
+            Completion-marker flag (see the endpoint description) — when true
+            the post is frameless and only flips the session to uploaded +
+            fires the category auto-analysis.
+    FrameCreateBody:
+      type: object
+      description: |
+        JSON-equivalent of the multipart intake (no binary depth/confidence
+        parts). Frame mode requires `client`, `media_id` and `session_id`
+        (the latter two top-level or inside `meta_inline`); completion-marker
+        mode requires `session_id` + `session_complete`.
+      properties:
+        media_id: { type: string }
+        session_id: { type: string }
+        meta_inline:
+          oneOf:
+            - type: string
+              description: JSON-encoded `MetaInline`.
+            - $ref: "#/components/schemas/MetaInline"
+        meta:
+          description: Alias for `meta_inline`.
+          oneOf:
+            - type: string
+            - $ref: "#/components/schemas/MetaInline"
+        client: { type: string }
+        rep: { type: string }
+        visit_id: { type: string }
+        route: { type: string }
+        business_day:
+          type: string
+          description: "`YYYY-MM-DD`."
+        time_zone: { type: string }
+        geo_tag:
+          oneOf:
+            - type: string
+              description: JSON-encoded `{ lat, lng, formatted_address? }`.
+            - type: object
+              properties:
+                lat: { type: number }
+                lng: { type: number }
+                formatted_address: { type: string }
+        time:
+          oneOf:
+            - type: number
+            - type: string
+          description: Device epoch (ms) of the capture.
+        session_complete:
+          oneOf:
+            - type: boolean
+            - type: string
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Optional tenant namespace override for SDK callers.
+    FrameResult:
+      type: object
+      properties:
+        session:
+          type: string
+          description: The parent session `_id`.
+        session_id:
+          type: string
+        task:
+          type: string
+          description: The materialized task `_id`.
+        frame:
+          type: string
+          description: The activity frame document `_id`.
+        frame_id:
+          type: number
+        client:
+          type: string
+          description: The `clients` `_id` the frame was attributed to.
+        file_media:
+          type: string
+          description: Media id of the uploaded image.
+        depth_media:
+          type: string
+          nullable: true
+          description: Media id of the uploaded depth blob, if provided.
+        confidence_media:
+          type: string
+          nullable: true
+          description: Media id of the uploaded confidence blob, if provided.
+    SessionCompleteResult:
+      type: object
+      description: Response of a `session_complete=true` (frameless) post.
+      properties:
+        session:
+          type: string
+          description: The session `_id`.
+        session_id:
+          type: string
+        status:
+          type: string
+          enum: [uploaded]
+        auto_analysis:
+          type: object
+          description: >-
+            Whether the category auto-analysis was fired. When triggered,
+            `runs` = number of category model_settings items queued (executed
+            serially in the background).
+          properties:
+            triggered: { type: boolean }
+            reason:
+              type: string
+              description: >-
+                Present when not triggered — no_category,
+                category_has_no_model_settings, session_verdict_rejected, or
+                error.
+            category: { type: string }
+            runs: { type: number }