starcoach-hackathon/zarinpal-analytics-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: stream partial analytics over sse

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 16:28:44 +03:30
parent d68e2e477c
commit 22ec54d8f4
2 changed files with 13 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
DESIGN.md
View File

@@ -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. |