From 49084ea577a2908ad0eb3f1962bf47c2af981731 Mon Sep 17 00:00:00 2001
From: Amirhossein Khalili <amirhosseinkhalili901@gmail.com>
Date: Fri, 21 Aug 2026 00:38:36 +0330
Subject: [PATCH] docs: finalize growth report lifecycle contract

---
 docs/openapi.yaml | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 570bf98..c78acea 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1049,7 +1049,7 @@ components:
             intervalCoverageBps: {type: integer, format: int64, minimum: 0, maximum: 10000}
     GrowthHistoricalWin:
       type: object
-      additionalProperties: true
+      additionalProperties: false
       required: [evidenceId, eventId, eventTitleFa, startDate, endDate, materialWin]
       properties:
         evidenceId: {type: string}
@@ -1092,8 +1092,8 @@ components:
         evidenceId: {type: string}
         date: {type: string, format: date-time}
         endDate: {type: string, format: date-time}
-        sessionDeclineBps: {type: integer, format: int64, minimum: 2000}
-        amountDeclineBps: {type: integer, format: int64, minimum: 2000}
+        sessionDeclineBps: {type: integer, format: int64, minimum: 0, description: At least one decline dimension is 2000 BPS or greater.}
+        amountDeclineBps: {type: integer, format: int64, minimum: 0, description: At least one decline dimension is 2000 BPS or greater.}
         expectedSessions: {$ref: '#/components/schemas/GrowthRange'}
         expectedAmountRial: {$ref: '#/components/schemas/GrowthRange'}
     GrowthPeer:
@@ -1119,6 +1119,18 @@ components:
         preparationAction: {type: string}
         limitation: {type: string}
         evidenceIds: {type: array, minItems: 1, items: {type: string}}
+    GrowthFallbackBrief:
+      type: object
+      additionalProperties: false
+      required: [headlineFa, guidanceFa, offerFa, messageFa, preparationFa, limitationFa, evidenceIds]
+      properties:
+        headlineFa: {type: string}
+        guidanceFa: {type: string}
+        offerFa: {type: string}
+        messageFa: {type: string}
+        preparationFa: {type: string}
+        limitationFa: {type: string}
+        evidenceIds: {type: array, minItems: 1, items: {type: string}}
     GrowthEvidence:
       type: object
       additionalProperties: false
@@ -1129,13 +1141,14 @@ components:
         opportunities: {type: array, maxItems: 5, items: {$ref: '#/components/schemas/GrowthOpportunity'}}
         risks: {type: array, maxItems: 3, items: {$ref: '#/components/schemas/GrowthRisk'}}
         peer: {$ref: '#/components/schemas/GrowthPeer'}
-        fallbackBriefs: {type: array, items: {$ref: '#/components/schemas/GrowthCampaignBrief'}}
+        fallbackBriefs: {type: array, items: {$ref: '#/components/schemas/GrowthFallbackBrief'}}
     GrowthReport:
       type: object
       additionalProperties: false
-      required: [reportId, status, scope, horizonDays, deterministicEvidence, cached, stale, nextRefreshAt, createdAt, updatedAt, eventsUrl]
+      required: [reportId, revision, status, scope, horizonDays, cached, stale, nextRefreshAt, createdAt, updatedAt, eventsUrl]
       properties:
         reportId: {type: string}
+        revision: {type: integer, minimum: 1}
         status: {type: string, enum: [QUEUED, ANALYZING, GENERATING, READY, PARTIAL, FAILED]}
         scope:
           type: object
@@ -2120,3 +2133,7 @@ components:
           type: string
           format: uri-reference
           description: Optional safe recovery link for run-related problems.
+        nextRefreshAt:
+          type: string
+          format: date-time
+          description: Present for REFRESH_LIMITED responses.