feat: add backoffice review capture endpoint + reviews composition (SITES-43974)

docs/openapi/api.yaml

@@ -288,6 +288,8 @@ paths:
     $ref: './site-opportunities.yaml#/site-opportunity-suggestion'
   /sites/{siteId}/opportunities/{opportunityId}/suggestions/{suggestionId}/fixes:
     $ref: './site-opportunities.yaml#/site-opportunity-suggestion-fixes'
+  /sites/{siteId}/opportunities/{opportunityId}/suggestions/{suggestionId}/backoffice-reviews:
+    $ref: './site-opportunities.yaml#/site-opportunity-suggestion-backoffice-reviews'
   /sites/{siteId}/opportunities/{opportunityId}/suggestions/status:
     $ref: './site-opportunities.yaml#/site-opportunity-suggestions-status'
   /sites/{siteId}/opportunities/{opportunityId}/suggestions/auto-fix:

docs/openapi/schemas.yaml

@@ -11377,3 +11377,62 @@ ReferralTrafficWeeks:
         $ref: '#/ReferralTrafficWeekEntry'
   required:
     - weeks
+
+SuggestionReview:
+  type: object
+  description: |
+    A human-review feedback event for a suggestion (Learning Agent feedback loop,
+    SITES-43974). Composed at read time from the feedback_event store. Raw patch
+    fields are omitted unless explicitly requested via ?include=reviews,patches.
+  properties:
+    eventId:
+      type: string
+      format: uuid
+      description: Client-supplied idempotency key for the review.
+    eventTime:
+      type: string
+      format: date-time
+      description: When the review action happened (server-stamped).
+    source:
+      type: string
+      enum: [backoffice, aso_ui, aemy_pr]
+      description: Capture surface (derived server-side from the route).
+    verdict:
+      type: string
+      enum: [up, down]
+      description: The reviewer's verdict.
+    signal:
+      type: string
+      enum: [positive, negative]
+      description: Persisted training label, derived from the verdict.
+    reviewerId:
+      type: string
+      description: >-
+        Server-derived, opaque IMS user identifier (e.g. <id>@<authSrc>) — NOT a
+        mailbox. Stable per user (reviewer-continuity signal). Null when not set.
+    detailMarkdown:
+      type: string
+      description: Sanitised ESE rationale. Null when not provided.
+    rejectionCategory:
+      type: string
+      enum: [product_bug, bad_recommendation, other]
+      description: Optional reject category. Null when not set.
+    stateTransition:
+      type: string
+      description: The accompanying suggestion state transition. Null when not set.
+    tier:
+      type: string
+      enum: [paid, free]
+    previousFix:
+      type: object
+      description: Patch snapshot at review time (only when ?include=...,patches).
+    editedFix:
+      type: object
+      description: ESE-edited patch (only when ?include=...,patches).
+  required:
+    - eventId
+    - eventTime
+    - source
+    - verdict
+    - signal
+    - tier

docs/openapi/site-opportunities.yaml

@@ -1174,6 +1174,91 @@ site-opportunity-suggestion:
     security:
       - ims_key: [ ]
 
+site-opportunity-suggestion-backoffice-reviews:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+    - $ref: './parameters.yaml#/opportunityId'
+    - $ref: './parameters.yaml#/suggestionId'
+  post:
+    operationId: createBackofficeReview
+    summary: |
+      Capture an ESE review verdict for a suggestion (Backoffice feedback loop)
+    description: |
+      Records a single human-review feedback event for the suggestion as part of
+      the Learning Agent feedback loop (SITES-43974). `source` is bound to
+      `backoffice` by this route and must not be supplied in the body. `eventId`
+      is a mandatory client-supplied idempotency key (UUID v4) — a duplicate POST
+      with the same `eventId` collapses to a no-op and returns 200 with the
+      existing review. Customer-derived fields are secret-scrubbed and the
+      markdown is sanitised server-side before storage; raw patches are not
+      echoed in the response.
+    tags:
+      - opportunity-suggestions
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - eventId
+              - verdict
+            properties:
+              eventId:
+                type: string
+                format: uuid
+                description: Client-supplied idempotency key (UUID v4), retained across retries.
+              verdict:
+                type: string
+                enum: [up, down]
+                description: The reviewer's verdict (translated server-side to a positive/negative signal).
+              detailMarkdown:
+                type: string
+                maxLength: 8192
+                description: Optional ESE rationale (markdown). Required on reject by the UI; sanitised + 8 KB cap server-side.
+              rejectionCategory:
+                type: string
+                enum: [product_bug, bad_recommendation, other]
+                description: Optional category on a reject.
+              stateTransition:
+                type: string
+                description: The accompanying suggestion state transition, e.g. PENDING_VALIDATION->REJECTED or EDIT.
+              previousFix:
+                type: object
+                description: Patch snapshot at review time (secret-scrubbed server-side).
+              editedFix:
+                type: object
+                description: ESE-edited patch when supplied (optional; secret-scrubbed server-side).
+    responses:
+      '201':
+        description: Review recorded
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/SuggestionReview'
+      '200':
+        description: Idempotent no-op — a review with this eventId already exists
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/SuggestionReview'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404'
+      '413':
+        description: detail_markdown exceeds the 8 KB limit
+      '500':
+        $ref: './responses.yaml#/500'
+      '503':
+        $ref: './responses.yaml#/503'
+    security:
+      - ims_key: [ ]
+
 site-opportunity-suggestions-edge-live-preview:
   parameters:
     - $ref: './parameters.yaml#/siteId'

package.json

@@ -85,7 +85,7 @@
     "@adobe/spacecat-shared-athena-client": "1.9.12",
     "@adobe/spacecat-shared-brand-client": "1.1.42",
     "@adobe/spacecat-shared-content-client": "1.8.24",
-    "@adobe/spacecat-shared-data-access": "3.79.0",
+    "@adobe/spacecat-shared-data-access": "https://gist.github.com/tathagat2241/baa0d24fc1d1b06a50238574767b273d/raw/43d71f553d033c2bbe2488c170b1833030ff3aa8/adobe-spacecat-shared-data-access-3.79.0.tgz",
     "@adobe/spacecat-shared-drs-client": "1.12.1",
     "@adobe/spacecat-shared-gpt-client": "1.6.23",
     "@adobe/spacecat-shared-http-utils": "1.29.1",