feat: rank growth events with grounded evidence

docs/openapi.yaml

@@ -1528,25 +1528,80 @@ components:
         expectedSessions: {$ref: '#/components/schemas/GrowthRange'}
         expectedAmountRial: {$ref: '#/components/schemas/GrowthRange'}
         historicalEvidenceId: {type: string}
-    GrowthUpcomingEvent:
+    GrowthHistoricalEventEvidence:
       type: object
       additionalProperties: false
-      required: [evidenceId, eventId, eventTitleFa, date, eventType, officialHoliday, merchantCategories, behavioralChannels]
+      required: [priorStartDate, priorEndDate, observationCount, paidSessionUpliftBps, amountUpliftBps, materialWin, materialDecline]
+      properties:
+        priorStartDate: {type: string, format: date-time}
+        priorEndDate: {type: string, format: date-time}
+        observationCount: {type: integer, minimum: 0, description: Number of eligible comparison windows used to establish the baseline.}
+        paidSessionUpliftBps: {type: integer, format: int64}
+        amountUpliftBps: {type: integer, format: int64}
+        materialWin: {type: boolean}
+        materialDecline: {type: boolean}
+    GrowthProfileEventEvidence:
+      type: object
+      additionalProperties: false
+      required: [matchedSignals]
+      properties:
+        matchedSignals:
+          type: array
+          items: {type: string, minLength: 1}
+        historyUnavailableReason: {$ref: '#/components/schemas/GrowthHistoryUnavailableReason'}
+    GrowthHistoryUnavailableReason:
+      type: string
+      enum: [INSUFFICIENT_BASELINE_OBSERVATIONS, INSUFFICIENT_BASELINE_SESSIONS, INSUFFICIENT_HISTORY, INCOMPLETE_EVENT_WINDOW, INSUFFICIENT_COHORT, TERMINAL_SCOPE_UNSUPPORTED]
+    GrowthUpcomingEventCommon:
+      type: object
+      required: [evidenceId, eventId, occasionKey, eventVariant, eventTitleFa, date, endDate, eventType, officialHoliday, merchantCategories, behavioralChannels]
       properties:
         evidenceId: {type: string}
         eventId: {type: string}
+        occasionKey: {type: string, minLength: 1}
+        eventVariant: {type: string, enum: [PRIMARY, CAMPAIGN_WINDOW, OPERATIONAL_WINDOW]}
         eventTitleFa: {type: string}
         date: {type: string, format: date-time}
+        endDate: {type: string, format: date-time}
         eventType: {type: string}
         officialHoliday: {type: boolean}
         merchantCategories: {type: array, items: {type: string}}
         behavioralChannels: {type: array, items: {type: string}}
+    GrowthUpcomingHistoricalEvent:
+      allOf:
+        - {$ref: '#/components/schemas/GrowthUpcomingEventCommon'}
+        - type: object
+          required: [insightBasis, historicalEvidence]
+          properties:
+            insightBasis: {type: string, enum: [HISTORICAL]}
+            historicalEvidence: {$ref: '#/components/schemas/GrowthHistoricalEventEvidence'}
+    GrowthUpcomingProfileEvent:
+      allOf:
+        - {$ref: '#/components/schemas/GrowthUpcomingEventCommon'}
+        - type: object
+          required: [insightBasis, profileEvidence]
+          properties:
+            insightBasis: {type: string, enum: [BUSINESS_PROFILE]}
+            profileEvidence: {$ref: '#/components/schemas/GrowthProfileEventEvidence'}
+    GrowthUpcomingEvent:
+      oneOf:
+        - {$ref: '#/components/schemas/GrowthUpcomingHistoricalEvent'}
+        - {$ref: '#/components/schemas/GrowthUpcomingProfileEvent'}
+      discriminator:
+        propertyName: insightBasis
+        mapping:
+          HISTORICAL: '#/components/schemas/GrowthUpcomingHistoricalEvent'
+          BUSINESS_PROFILE: '#/components/schemas/GrowthUpcomingProfileEvent'
     GrowthEventRecommendation:
       type: object
       additionalProperties: false
-      required: [evidenceId, relevanceReason]
+      description: Exactly three recommendations are returned in descending priority order. Their positive integer priorityPercent values sum to 100.
+      required: [evidenceId, priorityPercent, stance, insightBasis, relevanceReason]
       properties:
         evidenceId: {type: string}
+        priorityPercent: {type: integer, minimum: 1, maximum: 98}
+        stance: {type: string, enum: [PROMOTE, PREPARE, CAUTION]}
+        insightBasis: {type: string, enum: [HISTORICAL, BUSINESS_PROFILE]}
         relevanceReason: {type: string, minLength: 1, maxLength: 320}
     GrowthRisk:
       type: object
@@ -1609,6 +1664,7 @@ components:
             category: {type: string}
             niches: {type: array, items: {type: string}}
             salesChannels: {type: array, items: {type: string}}
+            businessDescriptions: {type: array, items: {type: string}}
     GrowthReport:
       type: object
       additionalProperties: false
@@ -1628,7 +1684,12 @@ components:
           additionalProperties: false
           required: [eventRecommendations]
           properties:
-            eventRecommendations: {type: array, minItems: 3, maxItems: 3, items: {$ref: '#/components/schemas/GrowthEventRecommendation'}}
+            eventRecommendations:
+              type: array
+              minItems: 3
+              maxItems: 3
+              description: Ranked in descending priorityPercent order; the three percentages sum to exactly 100.
+              items: {$ref: '#/components/schemas/GrowthEventRecommendation'}
         failureCode: {type: string}
         cached: {type: boolean}
         stale: {type: boolean}