docs: stream partial analytics over sse

DESIGN.md

@@ -1,7 +1,7 @@
 # Design System — ZarinPal Merchant Analytics
 
 - Status: Draft baseline for approval
-- Version: 0.1.6
+- Version: 0.1.7
 - Last updated: 2026-08-20
 - Direction: Persian-first RTL
 
@@ -93,9 +93,9 @@ Navigation labels should describe merchant tasks, not internal database concepts
 
 ## Core component contracts
 
-- **App shell:** sidebar/drawer, utility header, page title, merchant identity, analytics-cache status. First access shows an explicit calculation state. A current cached revision shows its calculated time; a source-revision mismatch or failed recalculation shows the previous result only with an explicit stale warning.
-- **Metric card:** label, formatted value/unit, comparison and period, semantic trend, definition link, states.
-- **Chart card:** title, period/filter controls, concise takeaway, plot, legend, accessible tabular alternative, provenance link.
+- **App shell:** sidebar/drawer, utility header, page title, merchant identity, analytics progress/status. First access opens an authenticated SSE stream and starts all analytics sections; the page reveals each section independently as it becomes ready.
+- **Metric card:** label, formatted value/unit, comparison and period, semantic trend, definition link, independent queued/calculating/ready/failed states.
+- **Chart card:** title, period/filter controls, concise takeaway, plot, legend, accessible tabular alternative, provenance link, and section-local loading/error behavior.
 - **Insight card:** deterministic finding, numeric evidence, suggested merchant action, confidence/limitation; AI-generated copy is visibly labeled later.
 - **Data table:** semantic headers, server pagination/sorting, row actions named for screen readers, responsive priority, empty/error states.
 - **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved daily, weekly, Jalali-month, and Persian-season periods with unambiguous comparison baselines.
@@ -111,6 +111,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
 - Tooltips are keyboard reachable and not the sole location of important values.
 - Charts have a textual summary and downloadable/visible data table when practical.
 - Zero, unavailable, suppressed, and not-yet-calculated are visually and linguistically distinct.
+- A ready section appears immediately without layout-shifting or blocking on unfinished siblings. Overall progress remains understandable without relying on animation.
 - Only source status `Verified` is presented as a confirmed successful payment. `Paid` is a separate operational state and is never merged into success or failure without a later approved metric-definition change.
 
 ## Motion
@@ -143,6 +144,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
 
 | Version | Date | Decision |
 |---|---|---|
+| 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. |
 | 0.1.5 | 2026-08-20 | Removed holiday/event reporting; limited period controls to daily, weekly, Jalali-month, and Persian-season views. |
 | 0.1.4 | 2026-08-20 | Kept `Paid` separate from confirmed `Verified` success. |

docs/DASHBOARD-SPEC.md

@@ -27,7 +27,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 9. Merchant-facing dates use the Jalali calendar in `Asia/Tehran`; API instants remain explicit ISO-8601 UTC and filtering sends unambiguous boundaries.
 10. Approved reporting periods are daily, weekly, Jalali-month, and Persian-season views. Weekly periods run Saturday through Friday in `Asia/Tehran`. Every comparison states its exact period and baseline.
 11. Only source session status `Verified` counts as a confirmed successful payment. `Paid` appears as a separate operational state until an approved metric-catalogue revision defines it otherwise.
-12. The first relevant dashboard access may calculate analytics and shows a bounded calculation/loading state. Later equivalent requests reuse the current PostgreSQL-backed merchant cache. When the source or cohort revision changes, the next access recalculates; an older result is shown only with an explicit stale warning and last-calculated time.
+12. The first relevant dashboard access starts all approved analytics-section jobs in bounded parallel. The app opens an authenticated, merchant-scoped SSE stream and renders each section as soon as its `ready` event arrives. A failed section has its own retry/error state and does not hide successful siblings.
+13. Later equivalent requests reuse current high-TTL 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.
+14. SSE reconnect uses stable event ids/resume semantics, shows a connection-recovery state, and never exposes job status or analytics for another merchant.
 
 ## Frontend architecture baseline
 
@@ -46,8 +48,10 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 - Login, navigation drawer, filters, chart alternatives, and logout are keyboard complete and screen-reader understandable.
 - Values visibly specify period and unit; missing/suppressed/zero states are distinct.
 - Confirmed-success views include only `Verified`; `Paid` is separately labeled and testable.
-- First access calculates once, a second equivalent access reuses the current cached revision, and concurrent first accesses do not create duplicate user-visible calculations.
-- A source-revision mismatch is visibly stale until successful recalculation; cache age alone does not make static data stale.
+- All core sections begin on first access and become visible independently in completion order without blocking the whole dashboard.
+- A second equivalent access reuses current Redis entries, and concurrent first accesses do not enqueue duplicate equivalent section jobs.
+- One section failure is isolated, retryable, and accessible; already-ready sections remain usable.
+- Disconnecting and reconnecting the SSE stream resumes safely without cross-merchant data or duplicated final sections.
 - 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.