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

docs: define lazy analytics cache states

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 16:17:42 +03:30
parent 9a0c2f1b3b
commit d68e2e477c
2 changed files with 8 additions and 6 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.5
- Version: 0.1.6
- 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. “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.
- **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.
- **Insight card:** deterministic finding, numeric evidence, suggested merchant action, confidence/limitation; AI-generated copy is visibly labeled later.
@@ -143,8 +143,9 @@ Navigation labels should describe merchant tasks, not internal database concepts
| Version | Date | Decision |
|---|---|---|
| 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 | Defined the 15-minute freshness/stale UX and kept `Paid` separate from confirmed `Verified` success. |
| 0.1.4 | 2026-08-20 | Kept `Paid` separate from confirmed `Verified` success. |
| 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. |
| 0.1.0 | 2026-08-20 | Established ZarinPal-inspired RTL foundation from supplied public/panel screenshots; fixed SvelteKit/Svelte/TypeScript/Tailwind stack; defined responsive shell, core components, accessibility, chart, and motion rules. |