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

docs: define analytics freshness states

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 15:58:56 +03:30
parent 9a26a51eab
commit fd8923faeb
2 changed files with 11 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
DESIGN.md
View File

@@ -1,7 +1,7 @@
# Design System — ZarinPal Merchant Analytics
- Status: Draft baseline for approval
- Version: 0.1.3
- Version: 0.1.4
- Last updated: 2026-08-20
- Direction: Persian-first RTL
@@ -93,7 +93,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
## Core component contracts
- **App shell:** sidebar/drawer, utility header, page title, merchant identity, freshness indicator.
- **App shell:** sidebar/drawer, utility header, page title, merchant identity, freshness indicator. “Fresh” means the latest successful analytics publication is no more than 15 minutes behind eligible source changes; a delayed or failed refresh shows an explicit stale state and last-successful time.
- **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.
- **Insight card:** deterministic finding, numeric evidence, suggested merchant action, confidence/limitation; AI-generated copy is visibly labeled later.
@@ -111,6 +111,8 @@ 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.
- 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.
- Named Iranian holidays come from reviewed, versioned calendar data. Analytical campaign windows such as a broader Nowruz period are labeled separately from official public-holiday dates.
## Motion
@@ -142,6 +144,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
| Version | Date | Decision |
|---|---|---|
| 0.1.4 | 2026-08-20 | Defined the 15-minute freshness/stale UX, kept `Paid` separate from confirmed `Verified` success, and distinguished official holidays from analytical event windows. |
| 0.1.3 | 2026-08-20 | Added explicit Jalali-month, Persian-season, and named holiday/event reporting periods with visible baselines and evidence. |
| 0.1.2 | 2026-08-20 | Added the insufficient-data state and visibility threshold for anonymized peer comparisons. |
| 0.1.1 | 2026-08-20 | Fixed merchant-facing time presentation to the Jalali calendar in `Asia/Tehran`, with explicit UTC API instants. |