repzo 1.0.291 → 1.0.293

package/src/oas/ai-object-detection-metric-result.yaml

@@ -0,0 +1,734 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Metric Result
+  version: 1.0.0
+  description: |
+    **Metric results** — one document per (analysis, metric), holding TWO
+    deliberately separate value layers:
+
+    - `computed` — what the engine calculated from the AI analysis (always
+      includes `answer` + `score` 0..1). Machine-owned: every evaluation
+      replaces it and humans can NEVER modify it through the API.
+    - `overwrite` + `flag` + `confirmed_edit` — the human layer: sparse VALUE
+      overrides of the type's overwritable keys (ratio and score are DERIVED
+      from them server-side, never accepted), a boolean attention marker,
+      and the admin review gate. Human-owned: evaluations never touch them,
+      so an override keeps ruling across recalculations.
+
+    Both layers are STRICT per-type shapes (Mongoose embedded discriminators
+    keyed by the metric type — the promotions model pattern); the stored
+    subdocuments carry an internal `type` mirror. No loose payloads.
+
+    **Output families** fix what `answer` means (`output` on the document):
+    - `compatibility` (adjacent_block) — `answer` is a boolean verdict;
+      score = answer ? 1 : 0.
+    - `numerical` (facings_count, on_shelf_availability) — `answer` is the
+      collected value. BOTH types accept an optional `target_answer`: the
+      score is then answer ÷ target (clamped to 1). Without one, OSA returns
+      its own factor (availability = answer ÷ total, so mission points =
+      weight × availability) and facings_count falls back to the family
+      default: a NON-ZERO answer earns full score, a missing or zero answer
+      scores 0.
+    - `share_of_shelf` — `answer` is the MAIN segment's measured quantity
+      (cm, cm² or facings), `total` the CONSIDERED CATEGORY (the same
+      measure over facings whose label belongs to ANY of the metric's
+      segments — the rest of the shelf never dilutes the share), `ratio`
+      their quotient, `target_answer` = target_ratio × total, and score =
+      the main segment's min(1, ratio / target_ratio). Every segment row
+      (main + context) is reported as a SegmentOutput in
+      `computed.segments[]`.
+
+    `score` / `answer` / `ratio` on the document are the DENORMALIZED
+    EFFECTIVE values — the CONFIRMED `overwrite.*` when `confirmed_edit` is
+    true, else `computed.*` — the numbers mission scoring, widgets and
+    analytics read. An unconfirmed override is stored and visible but does
+    NOT change them.
+
+    **How results appear.** Automatically: every successful session analysis
+    (and every compose-only shelf recompute) evaluates the MISSION-ASSIGNED
+    metrics — the stamped mission's list for "SCAN THIS MISSION" sessions,
+    the union over the client's currently-assigned missions for generic
+    scans. Sessions no mission covers get NO results. Manually:
+    `POST { analysis }` recalculates the same assigned set on demand —
+    idempotent and safe (an optional `metrics[]` subset can only NARROW the
+    assigned set). `source_fingerprints` snapshots the analysis's stage
+    fingerprints at evaluation time, so a mismatch marks the result stale.
+    Each result also carries a denormalized SCAN CONTEXT (`user`/`user_name`
+    = the scanning rep, `client`/`client_name`, `teams`, `visit_id`,
+    `route`, `business_day`) in the activity-model shape so shared
+    dashboard filters work unchanged.
+
+    **Re-analysis & the human layer.** A NEW analysis of the same session
+    CARRIES the previous analysis's human layer forward (flag,
+    confirmed_edit, and the entered override VALUES — an override asserts
+    the SCENE's truth, not one machine attempt's), with the derived
+    ratio/score re-computed against the fresh machine values. Every
+    evaluation and every update here also re-syncs the STORED mission
+    results (`/ai-object-detection-mission-results`) of the analysis.
+
+    **Multi-tenancy, roles & lifecycle.** Scoped by `company_namespace`
+    (inherited from the analysis — there is no namespace-injection hook and
+    no create body field for it), soft-deleted via `disabled`. `update`
+    accepts ONLY `flag`, `overwrite` and (admin-only) `confirmed_edit`;
+    `PATCH` is not supported (400). ADMINS have full access. REPS read
+    results of THEIR OWN sessions (a `session` or `analysis` filter is
+    required on list reads), may raise `flag` (never clear it) and may
+    submit value overrides — a rep override is auto-flagged and stays
+    PENDING (`confirmed_edit: false`, not effective) until an admin confirms
+    it; recalculation and removal are admin-only. Optional population of
+    `metric`, `analysis` and `session` via `populatedKeys[]` (the populated
+    document replaces the id in place).
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-metric-result:
+    get:
+      summary: List metric results
+      operationId: findAiObjectDetectionMetricResult
+      parameters:
+        - in: query
+          name: _id
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: analysis
+          description: Filter by the analysis _id (the common read). Required for rep tokens unless `session` is given.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: session
+          description: Filter by session _id. Rep tokens must own the session.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: metric
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: user
+          description: Filter by the SCANNING rep's id (denormalized scan context).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: client
+          description: Filter by the scanned client's id (denormalized scan context).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: teams
+          description: "Filter by the scanning rep's team id(s) — pass once or as `?teams[]=`."
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: type
+          schema:
+            type: string
+            enum:
+              [
+                adjacent_block,
+                facings_count,
+                on_shelf_availability,
+                share_of_shelf,
+              ]
+        - in: query
+          name: flag
+          description: Only flagged (or unflagged) results.
+          schema: { type: boolean }
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [ok, error]
+        - in: query
+          name: search
+          description: Case-insensitive substring search on the metric-name snapshot `name`.
+          schema: { type: string }
+        - in: query
+          name: disabled
+          description: "Include soft-deleted results (`true`) or only live ones (`false`). Omitted = no filter."
+          schema: { type: boolean }
+        - in: query
+          name: from_updatedAt
+          schema: { type: number }
+        - in: query
+          name: to_updatedAt
+          schema: { type: number }
+        - in: query
+          name: from_createdAt
+          schema: { type: number }
+        - in: query
+          name: to_createdAt
+          schema: { type: number }
+        - in: query
+          name: populatedKeys
+          description: "Embed refs in place of the id. Supported: `metric`, `analysis`, `session`."
+          schema:
+            type: array
+            items:
+              type: string
+              enum: [metric, analysis, session]
+        - in: query
+          name: per_page
+          schema: { type: integer, minimum: 1 }
+        - in: query
+          name: page
+          schema: { type: integer, minimum: 1 }
+        - in: query
+          name: sort
+          description: Field to sort by (default `_id`).
+          schema: { type: string }
+        - in: query
+          name: sortPageOrder
+          schema:
+            type: string
+            enum: [asc, dsc]
+      responses:
+        "200":
+          description: Paginated results.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MetricResultFindResult"
+        "403":
+          description: Rep token without a `session`/`analysis` filter, or the session is not the rep's own.
+    post:
+      summary: Calculate / recalculate metrics for an analysis (admin)
+      description: |
+        Evaluates every ENABLED, MISSION-ASSIGNED metric (or the given subset
+        of them) against the analysis and upserts one result per metric.
+        Idempotent: `computed` is replaced, standing `flag`/`overwrite`
+        values are preserved and keep ruling the effective `score` while
+        confirmed. Also upserts the stored mission results of the session.
+        The tenant namespace comes from the caller's token — there is no
+        `company_namespace` body field.
+      operationId: createAiObjectDetectionMetricResult
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [analysis]
+              properties:
+                analysis:
+                  type: string
+                  description: The SUCCESSFUL analysis to evaluate.
+                metrics:
+                  type: array
+                  items: { type: string }
+                  description: Optional metric-id subset (default = every mission-assigned enabled metric; can only narrow that set).
+      responses:
+        "201":
+          description: Evaluation summary + the fresh result documents.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  analysis: { type: string }
+                  evaluated:
+                    type: number
+                    description: Metrics evaluated.
+                  errors:
+                    type: number
+                    description: Metrics whose evaluation or persistence failed.
+                  results:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/MetricResult"
+        "400":
+          description: "`analysis` missing, not found, or not in `success` status."
+        "403":
+          description: Rep tokens may not recalculate.
+  /ai-object-detection-metric-result/{id}:
+    get:
+      summary: Get a metric result
+      operationId: getAiObjectDetectionMetricResult
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The result document (refs are never populated on this read).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MetricResult"
+        "400":
+          description: Not found.
+        "403":
+          description: Rep token — the result's session is not the rep's own.
+    put:
+      summary: Human override — flag / overwrite / confirmed_edit
+      description: |
+        The ONLY writable fields are `flag`, `overwrite` and (admin-only)
+        `confirmed_edit`. `overwrite` accepts VALUE keys only — `ratio` and
+        `score` are rejected and instead DERIVED server-side from the
+        effective values by the type's own rule (SOS: ratio = answer ÷ total,
+        score = ratio ÷ target_ratio clamped; OSA: ratio = answer ÷ total,
+        score = answer ÷ target or the ratio; facings: answer ÷ target or
+        existence; compatibility: answer ? 1 : 0). `computed` is immutable
+        from the API — the AI-calculated values always remain visible next to
+        the override. Enterable keys per type:
+        - `adjacent_block`: `answer` (boolean), `member_count`, `cut_count`
+        - `facings_count`: `answer` (number)
+        - `on_shelf_availability`: `answer` (number)
+        - `share_of_shelf`: `answer`, `total`
+
+        REVIEW FLOW: any fresh `overwrite` resets `confirmed_edit` to false
+        (pending) unless the same ADMIN request sets it true; the override
+        only drives the effective `score` while confirmed. REP rules: only
+        results of the rep's own sessions; `flag` may be raised but not
+        cleared; sending a value override auto-raises `flag`;
+        `confirmed_edit` is rejected. The stored mission results of the
+        analysis are re-synced afterwards.
+      operationId: updateAiObjectDetectionMetricResult
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                flag: { type: boolean }
+                overwrite:
+                  $ref: "#/components/schemas/OverwriteInput"
+                confirmed_edit:
+                  type: boolean
+                  description: "ADMIN-ONLY review verdict — true makes the standing overwrite effective."
+      responses:
+        "200":
+          description: The updated result (derived overwrite ratio/score stamped; effective `score`/`answer`/`ratio` recomputed per `confirmed_edit`).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MetricResult"
+        "400":
+          description: "Non-overwritable key, `ratio`/`score` sent, wrong value type, or `overwrite` not an object."
+        "403":
+          description: Rep clearing `flag`, sending `confirmed_edit`, or touching another rep's session.
+        "404":
+          description: Not found.
+    delete:
+      summary: Soft-delete a metric result (admin)
+      operationId: removeAiObjectDetectionMetricResult
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The disabled result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MetricResult"
+        "403":
+          description: Rep tokens may not remove results.
+        "404":
+          description: Not found.
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: api-key
+    JwtAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+  schemas:
+    UserStamp:
+      type: object
+      description: "Who created / last edited the document (server-stamped from the token)."
+      properties:
+        _id: { type: string }
+        name: { type: string }
+        type:
+          type: string
+          enum: [admin, rep, client, tenant]
+        admin: { type: string }
+        rep: { type: string }
+        client: { type: string }
+        tenant: { type: string }
+    AdjacentBlockComputed:
+      type: object
+      description: "Computed shape for `adjacent_block` (compatibility)."
+      properties:
+        type:
+          type: string
+          enum: [adjacent_block]
+          description: Internal discriminator mirror.
+        output:
+          type: string
+          enum: [compatibility]
+          description: Family tag stamped by the engine.
+        answer:
+          type: boolean
+          description: The verdict — contiguous AND count within [from, to].
+        score: { type: number, minimum: 0, maximum: 1 }
+        member_count: { type: number }
+        cut_count: { type: number }
+        in_range: { type: boolean }
+        blocks:
+          type: array
+          items:
+            type: object
+            properties:
+              shelf: { type: number }
+              from_stack: { type: number }
+              to_stack: { type: number }
+              count: { type: number }
+    FacingsCountComputed:
+      type: object
+      description: "Computed shape for `facings_count` (numerical)."
+      properties:
+        type:
+          type: string
+          enum: [facings_count]
+        output:
+          type: string
+          enum: [numerical]
+          description: Family tag stamped by the engine.
+        answer:
+          type: number
+          description: The collected facings count.
+        target_answer:
+          type: number
+          description: "Echo of the metric's optional target — present only when set; score then = answer ÷ target_answer (clamped)."
+        score: { type: number, minimum: 0, maximum: 1 }
+        shelves:
+          type: array
+          items:
+            type: object
+            properties:
+              shelf: { type: number }
+              count: { type: number }
+    OnShelfAvailabilityComputed:
+      type: object
+      description: "Computed shape for `on_shelf_availability` (numerical)."
+      properties:
+        type:
+          type: string
+          enum: [on_shelf_availability]
+        output:
+          type: string
+          enum: [numerical]
+          description: Family tag stamped by the engine.
+        answer:
+          type: number
+          description: "How many of the selected labels are AVAILABLE (≥ 1 facing)."
+        score:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: "answer ÷ target_answer when a target is set, else `ratio` (the availability factor)."
+        target_answer:
+          type: number
+          description: "Echo of the metric's optional target — present only when set."
+        total:
+          type: number
+          description: How many labels were selected (the denominator).
+        ratio:
+          type: number
+          description: answer / total.
+        missing:
+          type: array
+          description: "The out-of-stock labels — the actionable list (names resolved at evaluation time)."
+          items:
+            type: object
+            properties:
+              label: { type: string }
+              name: { type: string }
+        present:
+          type: array
+          description: The available labels with their facing counts.
+          items:
+            type: object
+            properties:
+              label: { type: string }
+              name: { type: string }
+              facings: { type: number }
+    SegmentOutput:
+      type: object
+      description: |
+        One segment row's outcome inside a share-of-shelf evaluation.
+        Self-contained on purpose: embedded in `computed.segments[]` today
+        but ready to move to its own collection and to be reused by future
+        SOS-family metric types. Only the MAIN row carries `target_ratio`,
+        `target_answer` and `score`.
+      properties:
+        segment: { type: string }
+        name: { type: string }
+        resolved:
+          type: boolean
+          description: false = the segment was deleted after the metric referenced it.
+        main:
+          type: boolean
+          description: The row the metric's target is defined for — exactly one per metric.
+        labels:
+          type: array
+          items: { type: string }
+          description: The effective labels used (override or the segment's own).
+        answer:
+          type: number
+          description: Measured quantity in the metric's measure unit (cm or cm²).
+        overwrite_answer:
+          type: number
+          description: "The CONFIRMED answer override, colocated in the row (effective = overwrite_answer ?? answer) — present only while confirmed_edit is true. Source of truth is the result's `overwrite.answer`; the service keeps this copy in sync across override saves, confirmations and recalculations."
+        overwrite_ratio:
+          type: number
+          description: "The confirmed override's derived ratio, colocated with overwrite_answer (same lifecycle)."
+        overwrite_score:
+          type: number
+          description: "The confirmed override's derived score, colocated with overwrite_answer (same lifecycle)."
+        ratio:
+          type: number
+          description: answer / category total — rows sum to 1 when segments don't overlap.
+        target_ratio:
+          type: number
+          description: Main row only — the target share this segment must reach.
+        target_answer:
+          type: number
+          description: "Main row only — target_ratio × total: the quantity needed to hit the target."
+        score:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: "Main row only — attainment vs the target (share_of_shelf: min(1, ratio / target_ratio)). Missions multiply it by their weight."
+    ShareOfShelfComputed:
+      type: object
+      description: "Computed shape for `share_of_shelf` — the MAIN segment's numbers at the top level, every row in `segments[]`."
+      properties:
+        type:
+          type: string
+          enum: [share_of_shelf]
+        output:
+          type: string
+          enum: [share_of_shelf]
+          description: Family tag stamped by the engine.
+        answer:
+          type: number
+          nullable: true
+          description: "The MAIN segment's measured quantity (cm or cm²); null when nothing was measurable."
+        score:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: "= the main segment's score: min(1, ratio / target_ratio)."
+        total:
+          type: number
+          description: "The same measure over the CONSIDERED CATEGORY: facings whose label belongs to any of the metric's segments."
+        ratio:
+          type: number
+          description: answer / total — the main segment's share.
+        target_ratio:
+          type: number
+          description: The target the MAIN segment must meet (from the metric args).
+        target_answer:
+          type: number
+          description: "target_ratio × total — what the main segment needed, in measure units."
+        measure:
+          type: string
+          enum: [width_cm, area_cm2, facings]
+        unmeasured:
+          type: number
+          description: Considered facings without a physical size (excluded from both sides).
+        segments:
+          type: array
+          description: One SegmentOutput per metric row (the main one flagged + scored).
+          items:
+            $ref: "#/components/schemas/SegmentOutput"
+    Overwrite:
+      type: object
+      description: "Stored human layer — the entered VALUE keys plus the server-DERIVED `ratio`/`score`, strict per type (plus the internal `type` mirror). Which keys exist depends on the type: adjacent_block `answer` (boolean) / `member_count` / `cut_count` / `score`; facings_count `answer` / `score`; on_shelf_availability `answer` / `ratio` / `score`; share_of_shelf `answer` / `total` / `ratio` / `score`."
+      properties:
+        type:
+          type: string
+          enum:
+            [
+              adjacent_block,
+              facings_count,
+              on_shelf_availability,
+              share_of_shelf,
+            ]
+        answer:
+          description: boolean for adjacent_block, number otherwise.
+          oneOf:
+            - type: boolean
+            - type: number
+        member_count: { type: number }
+        cut_count: { type: number }
+        total: { type: number }
+        ratio: { type: number }
+        score: { type: number, minimum: 0, maximum: 1 }
+    OverwriteInput:
+      type: object
+      description: "Sparse VALUE overrides — only the type's overwritable keys; `ratio`/`score` are rejected (derived). Send `{}` to clear the override."
+      properties:
+        answer:
+          description: "adjacent_block: boolean verdict; other types: number."
+          oneOf:
+            - type: boolean
+            - type: number
+        member_count:
+          type: number
+          description: adjacent_block only.
+        cut_count:
+          type: number
+          description: adjacent_block only.
+        total:
+          type: number
+          description: share_of_shelf only.
+    MetricResult:
+      type: object
+      properties:
+        _id: { type: string }
+        disabled: { type: boolean }
+        metric:
+          type: string
+          description: "Metric id (or the populated metric document when `populatedKeys` includes `metric`)."
+        analysis:
+          type: string
+          description: "Analysis id (or the populated document when requested)."
+        session:
+          type: string
+          description: "Session id (or the populated document when requested)."
+        name:
+          type: string
+          description: Metric name snapshot at evaluation time.
+        type:
+          type: string
+          enum:
+            [
+              adjacent_block,
+              facings_count,
+              on_shelf_availability,
+              share_of_shelf,
+            ]
+        output:
+          type: string
+          enum: [compatibility, numerical, share_of_shelf]
+          description: The type's output family (denormalized for rendering).
+        args:
+          type: object
+          description: Args snapshot at evaluation time.
+        computed:
+          description: "Machine layer — strict per-type engine output incl. `answer` + `score` 0..1 (plus an internal `type` mirror). Never editable. Absent when the evaluation errored."
+          oneOf:
+            - $ref: "#/components/schemas/AdjacentBlockComputed"
+            - $ref: "#/components/schemas/FacingsCountComputed"
+            - $ref: "#/components/schemas/OnShelfAvailabilityComputed"
+            - $ref: "#/components/schemas/ShareOfShelfComputed"
+        user:
+          type: string
+          nullable: true
+          description: "Denormalized scan context (activity-model shape): the SCANNING rep's id — unset for admin-scanned sessions. Stamped by the evaluator; feeds the dashboard widgets' rep_id filter."
+        user_name: { type: string, nullable: true }
+        client:
+          type: string
+          nullable: true
+          description: "The scanned client's id (widget client.* filters inflate it in their header stages)."
+        client_name: { type: string, nullable: true }
+        teams:
+          type: array
+          items: { type: string }
+          description: "The scanning rep's team ids at evaluation time (team-shared dashboards)."
+        visit_id:
+          type: string
+          description: Device visit id of the visit the scan happened in (copied from the session).
+        route:
+          type: string
+          description: "`sv.routes` `_id` of the visit's route."
+        business_day:
+          type: string
+          description: "Business day of the scan, `YYYY-MM-DD`."
+        overwrite:
+          $ref: "#/components/schemas/Overwrite"
+        flag: { type: boolean }
+        confirmed_edit:
+          type: boolean
+          description: "Admin review gate — the overwrite only drives the effective score while true. A fresh overwrite resets it to false; reps can never set it."
+        score:
+          type: number
+          description: "EFFECTIVE score 0..1 (confirmed `overwrite.score`, else `computed.score`)."
+        answer:
+          description: "EFFECTIVE answer, reconciled like `score` (confirmed override wins) — boolean verdict or number per the output family. What widgets/analytics aggregate."
+          nullable: true
+          oneOf:
+            - type: boolean
+            - type: number
+        ratio:
+          type: number
+          nullable: true
+          description: "EFFECTIVE ratio, reconciled like `score` (OSA availability / SOS share; null for types without one)."
+        status:
+          type: string
+          enum: [ok, error]
+        error: { type: string, nullable: true }
+        evaluated_at:
+          type: number
+          description: Unix ms of the evaluation.
+        engine_version: { type: number }
+        source_fingerprints:
+          type: object
+          description: The analysis's stage fingerprints at evaluation time — mismatch vs the analysis's current ones = stale result.
+        creator:
+          $ref: "#/components/schemas/UserStamp"
+        editor:
+          $ref: "#/components/schemas/UserStamp"
+        company_namespace:
+          type: array
+          items: { type: string }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+    MetricResultFindResult:
+      type: object
+      description: Standard paginated result envelope.
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/MetricResult"
+        total_result: { type: number }
+        current_count: { type: number }
+        total_pages: { type: number }
+        current_page: { type: number }
+        per_page: { type: number }
+        first_page_url: { type: string }
+        last_page_url: { type: string }
+        next_page_url: { type: string, nullable: true }
+        prev_page_url: { type: string, nullable: true }
+        path: { type: string }