docs: define analytics rate-limit states

DESIGN.md

@@ -1,7 +1,7 @@
 # Design System — ZarinPal Merchant Analytics
 
 - Status: Draft baseline for approval
-- Version: 0.1.8
+- Version: 0.1.9
 - Last updated: 2026-08-20
 - Direction: Persian-first RTL
 
@@ -101,6 +101,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
 - **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved daily, weekly, Jalali-month, and Persian-season periods with unambiguous comparison baselines.
 - **Status badge:** text plus icon/shape; color reinforces but never carries meaning alone.
 - **Feedback:** inline field errors, page-level error boundary, skeleton only when layout is known, retry action for recoverable failures.
+- **Rate-limited state:** explain when an analytics start, stream, or manual retry is temporarily limited; preserve ready content, honor the server `Retry-After`, and never run a client-side retry loop.
 
 ## Data visualization
 
@@ -144,6 +145,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
 
 | Version | Date | Decision |
 |---|---|---|
+| 0.1.9 | 2026-08-20 | Added rate-limit UX, 15-second SSE heartbeat/recovery, one-hour replay, and failed-section-only manual retry. |
 | 0.1.8 | 2026-08-20 | Fixed the four parallel section ids, 30-day cache, idempotent start/SSE flow, and section timeout/retry behavior. |
 | 0.1.7 | 2026-08-20 | Moved analytics results to high-TTL Redis and defined partial, parallel section delivery through authenticated SSE. |
 | 0.1.6 | 2026-08-20 | Replaced time-based analytics freshness with lazy first-access calculation and revision-based merchant/cohort cache states; defined Saturday–Friday weeks. |

docs/DASHBOARD-SPEC.md

@@ -32,6 +32,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 14. Later equivalent requests reuse 30-day Redis entries. PostgreSQL merchant/cohort revision changes select new cache keys and cause only missing sections to be recalculated; cache age alone does not make static data stale.
 15. SSE reconnect uses stable event ids/resume semantics, shows a connection-recovery state, and never exposes job status or analytics for another merchant.
 16. Each section attempt times out after 60 seconds. The backend may perform at most two automatic transient retries using exponential backoff/jitter; the UI represents the section as calculating during automatic retries and exposes failure/retry only after exhaustion or a non-retryable error.
+17. SSE expects a heartbeat every 15 seconds and supports authorized replay for one hour. After replay expires, the app fetches the current run snapshot before reopening the stream.
+18. Manual retry targets only one exhausted failed section. It is disabled while active, never restarts ready siblings, and handles a typed `429` by honoring `Retry-After`.
+19. Analytics starts, manual retries, and concurrent SSE connections expose accessible rate-limited states without discarding already-ready content or retrying in a tight loop.
 
 ## Frontend architecture baseline
 
@@ -56,6 +59,8 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 - One section failure is isolated, retryable, and accessible; already-ready sections remain usable.
 - A section does not remain indefinitely loading: each attempt is bounded to 60 seconds and no more than two automatic exponential-backoff retries occur.
 - Disconnecting and reconnecting the SSE stream resumes safely without cross-merchant data or duplicated final sections.
+- Missing heartbeats trigger controlled connection recovery; one-hour replay or snapshot fallback restores the authorized current state.
+- Rate-limited responses enqueue no duplicate work, preserve ready sections, and delay retry according to `Retry-After`.
 - Daily, weekly, Jalali-month, and Persian-season filters use the same explicit boundaries as the API and database.
 - Production build passes type checking, linting, unit/component tests, and Playwright critical-flow tests.
 - No raw dataset record, payer-card key, credential, or AvalAI key enters client bundles/logging/storage.