docs(openapi): register the six specialised insight status routes

The generic metric-status route set the OpenAPI pattern for the assessment cards; retrofit the six specialised routes onto it. Add registry entries for /api/insights/{blood-pressure,pulse,weight,bmi,mood,medication-compliance}-status mirroring the metric-status envelope (hasProvider/text/cached/updatedAt plus the preparing + revalidating flags). Medication-compliance carries its richer summary + per-medication note array as its own schema. Regenerate the YAML. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> (cherry picked from commit 91887a13b30e8978e91f615604163331bdc54950)
2026-11-11 05:42:19 +00:00 · 2026-06-02 17:01:14 +02:00
1 parent 7fa2866154
commit 18cde65af7
@@ -2035,6 +2035,174 @@ paths:
        "401": *a1
        "422": *a2
        "429": *a3
+  /api/insights/blood-pressure-status:
+    get:
+      tags:
+        - Insights
+      summary: Blood-pressure assessment
+      description: "Data-driven plain-language assessment of the user's recent blood-pressure readings. Read-only: a cache
+        miss warms a generation out of band and serves the last-good text meanwhile (stale-while-revalidate). Auth via
+        cookie or Bearer."
+      parameters:
+        - in: query
+          name: locale
+          schema:
+            description: Optional UI-locale override; defaults to the session locale.
+            type: string
+            enum:
+              - de
+              - en
+          description: Optional UI-locale override; defaults to the session locale.
+      responses:
+        "200":
+          description: Assessment envelope (fresh, cached, or preparing).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BloodPressureStatusResponseEnvelope"
+        "401": *a1
+        "422": *a2
+        "429": *a3
+  /api/insights/pulse-status:
+    get:
+      tags:
+        - Insights
+      summary: Pulse assessment
+      description: "Data-driven plain-language assessment of the user's recent resting-pulse readings. Read-only: a cache miss
+        warms a generation out of band and serves the last-good text meanwhile (stale-while-revalidate). Auth via cookie
+        or Bearer."
+      parameters:
+        - in: query
+          name: locale
+          schema:
+            description: Optional UI-locale override; defaults to the session locale.
+            type: string
+            enum:
+              - de
+              - en
+          description: Optional UI-locale override; defaults to the session locale.
+      responses:
+        "200":
+          description: Assessment envelope (fresh, cached, or preparing).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PulseStatusResponseEnvelope"
+        "401": *a1
+        "422": *a2
+        "429": *a3
+  /api/insights/weight-status:
+    get:
+      tags:
+        - Insights
+      summary: Weight assessment
+      description: "Data-driven plain-language assessment of the user's recent weight trend. Read-only: a cache miss warms a
+        generation out of band and serves the last-good text meanwhile (stale-while-revalidate). Auth via cookie or
+        Bearer."
+      parameters:
+        - in: query
+          name: locale
+          schema:
+            description: Optional UI-locale override; defaults to the session locale.
+            type: string
+            enum:
+              - de
+              - en
+          description: Optional UI-locale override; defaults to the session locale.
+      responses:
+        "200":
+          description: Assessment envelope (fresh, cached, or preparing).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WeightStatusResponseEnvelope"
+        "401": *a1
+        "422": *a2
+        "429": *a3
+  /api/insights/bmi-status:
+    get:
+      tags:
+        - Insights
+      summary: BMI assessment
+      description: "Data-driven plain-language assessment of the user's body-mass index. Read-only: a cache miss warms a
+        generation out of band and serves the last-good text meanwhile (stale-while-revalidate). Auth via cookie or
+        Bearer."
+      parameters:
+        - in: query
+          name: locale
+          schema:
+            description: Optional UI-locale override; defaults to the session locale.
+            type: string
+            enum:
+              - de
+              - en
+          description: Optional UI-locale override; defaults to the session locale.
+      responses:
+        "200":
+          description: Assessment envelope (fresh, cached, or preparing).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BmiStatusResponseEnvelope"
+        "401": *a1
+        "422": *a2
+        "429": *a3
+  /api/insights/mood-status:
+    get:
+      tags:
+        - Insights
+      summary: Mood assessment
+      description: "Data-driven plain-language assessment of the user's recent mood entries. Read-only: a cache miss warms a
+        generation out of band and serves the last-good text meanwhile (stale-while-revalidate). Auth via cookie or
+        Bearer."
+      parameters:
+        - in: query
+          name: locale
+          schema:
+            description: Optional UI-locale override; defaults to the session locale.
+            type: string
+            enum:
+              - de
+              - en
+          description: Optional UI-locale override; defaults to the session locale.
+      responses:
+        "200":
+          description: Assessment envelope (fresh, cached, or preparing).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MoodStatusResponseEnvelope"
+        "401": *a1
+        "422": *a2
+        "429": *a3
+  /api/insights/medication-compliance-status:
+    get:
+      tags:
+        - Insights
+      summary: Medication-compliance assessment
+      description: "Data-driven plain-language assessment of the user's medication compliance — an overall `summary` plus a
+        per-medication note array. Read-only: a cache miss warms a generation out of band and serves the last-good
+        envelope meanwhile (stale-while-revalidate). Auth via cookie or Bearer."
+      parameters:
+        - in: query
+          name: locale
+          schema:
+            description: Optional UI-locale override; defaults to the session locale.
+            type: string
+            enum:
+              - de
+              - en
+          description: Optional UI-locale override; defaults to the session locale.
+      responses:
+        "200":
+          description: Compliance assessment envelope (fresh, cached, or preparing).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MedicationComplianceStatusResponseEnvelope"
+        "401": *a1
+        "422": *a2
+        "429": *a3
  /api/insights/metric-status:
    get:
      tags:
@@ -6578,6 +6746,204 @@ components:
        - mean
        - sum
      additionalProperties: false
+    BloodPressureStatusResponseEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/InsightStatusResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    InsightStatusResponse:
+      type: object
+      properties:
+        hasProvider:
+          type: boolean
+          description: False when the user has no usable AI provider — `text` then carries the generic no-key guidance.
+        text:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: The assessment narrative (plain text, rendered as React text children). Null while a first generation is
+            preparing.
+        cached:
+          type: boolean
+          description: True when `text` is served from cache (incl. last-good).
+        updatedAt:
+          anyOf:
+            - type: string
+              format: date-time
+              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
+            - type: "null"
+          description: When the served assessment was generated; null when none.
+        preparing:
+          description: True when a first assessment is being generated out of band and no prior text exists yet — the client polls
+            until it lands.
+          type: boolean
+        revalidating:
+          description: True when `text` is served from last-good cache (stale-while-revalidate) while a fresh generation is in
+            flight. The client keeps polling on `preparing || revalidating` (bounded) so the open card upgrades to the
+            warmed assessment without a remount.
+          type: boolean
+      required:
+        - hasProvider
+        - text
+        - cached
+        - updatedAt
+      additionalProperties: false
+      description: "Specialised per-metric assessment envelope (blood-pressure, pulse, weight, bmi, mood). Identical shape to
+        the generic metric-status card so the `InsightStatusCard` consumes it unchanged. Read-only +
+        stale-while-revalidate: a cache miss warms a generation out of band and serves the last-good text meanwhile."
+    PulseStatusResponseEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/InsightStatusResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    WeightStatusResponseEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/InsightStatusResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    BmiStatusResponseEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/InsightStatusResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    MoodStatusResponseEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/InsightStatusResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    MedicationComplianceStatusResponseEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/MedicationComplianceStatusResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    MedicationComplianceStatusResponse:
+      type: object
+      properties:
+        hasProvider:
+          type: boolean
+          description: False when the user has no usable AI provider — `summary` then carries the generic no-key guidance.
+        summary:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: The overall compliance narrative (plain text). Null while a first generation is preparing.
+        medications:
+          type: array
+          items:
+            $ref: "#/components/schemas/MedicationComplianceStatusItem"
+          description: Per-medication compliance notes. Empty while preparing or when no medication qualifies.
+        cached:
+          type: boolean
+          description: True when the envelope is served from cache (incl. last-good).
+        updatedAt:
+          anyOf:
+            - type: string
+              format: date-time
+              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
+            - type: "null"
+          description: When the served assessment was generated; null when none.
+        preparing:
+          description: True when a first assessment is being generated out of band and no prior summary exists yet — the client
+            polls until it lands.
+          type: boolean
+        revalidating:
+          description: True when the envelope is served from last-good cache (stale-while-revalidate) while a fresh generation is
+            in flight. The client keeps polling on `preparing || revalidating` (bounded).
+          type: boolean
+      required:
+        - hasProvider
+        - summary
+        - medications
+        - cached
+        - updatedAt
+      additionalProperties: false
+      description: Medication-compliance assessment envelope. Unlike the other six specialised cards it carries a `summary`
+        plus a per-medication `text` array rather than a single `text` field. Read-only + stale-while-revalidate.
+    MedicationComplianceStatusItem:
+      type: object
+      properties:
+        medicationId:
+          type: string
+          description: The medication this note belongs to.
+        text:
+          type: string
+          description: Per-medication compliance note (plain text).
+      required:
+        - medicationId
+        - text
+      additionalProperties: false
    MetricStatusResponseEnvelope:
      type: object
      properties: