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 # Design System — ZarinPal Merchant Analytics
- Status: Draft baseline for approval - Status: Draft baseline for approval
- Version: 0.1.3 - Version: 0.1.4
- Last updated: 2026-08-20 - Last updated: 2026-08-20
- Direction: Persian-first RTL - Direction: Persian-first RTL
@@ -93,7 +93,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
## Core component contracts ## 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. - **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. - **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. - **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. - Tooltips are keyboard reachable and not the sole location of important values.
- Charts have a textual summary and downloadable/visible data table when practical. - Charts have a textual summary and downloadable/visible data table when practical.
- Zero, unavailable, suppressed, and not-yet-calculated are visually and linguistically distinct. - 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 ## Motion
@@ -142,6 +144,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
| Version | Date | Decision | | 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.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.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.1 | 2026-08-20 | Fixed merchant-facing time presentation to the Jalali calendar in `Asia/Tehran`, with explicit UTC API instants. |

6
docs/DASHBOARD-SPEC.md
View File

@@ -26,6 +26,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
8. Responsive behavior and component contracts follow `DESIGN.md`. 8. Responsive behavior and component contracts follow `DESIGN.md`.
9. Merchant-facing dates use the Jalali calendar in `Asia/Tehran`; API instants remain explicit ISO-8601 UTC and filtering sends unambiguous boundaries. 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 include day, Jalali month, Persian season, and named Iranian holiday/event windows. Every comparison states its exact period and baseline; one observed event period is not presented as recurring seasonality. 10. Approved reporting periods include day, Jalali month, Persian season, and named Iranian holiday/event windows. Every comparison states its exact period and baseline; one observed event period is not presented as recurring seasonality.
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. A successful incremental analytics publication must appear within 15 minutes of eligible source changes. The UI shows the latest successful publication time, distinguishes stale from unavailable data, and does not claim freshness after a failed refresh. Nightly reconciliation may correct projections without changing metric meaning.
13. Official Iranian holidays come from reviewed, versioned calendar snapshots. Any broader analytical campaign/event period is labeled separately and exposes its exact date range.
## Frontend architecture baseline ## Frontend architecture baseline
@@ -43,6 +46,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
- Critical flows work at 360 px, 768 px, 1024 px, and a wide desktop viewport in RTL. - Critical flows work at 360 px, 768 px, 1024 px, and a wide desktop viewport in RTL.
- Login, navigation drawer, filters, chart alternatives, and logout are keyboard complete and screen-reader understandable. - 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. - Values visibly specify period and unit; missing/suppressed/zero states are distinct.
- Confirmed-success views include only `Verified`; `Paid` is separately labeled and testable.
- Freshness becomes stale after the approved 15-minute bound, exposes the last successful publication time, and recovers only after a successful publication.
- Official-holiday and analytical-event labels cannot be confused, and their exact dates are available to the user.
- Production build passes type checking, linting, unit/component tests, and Playwright critical-flow tests. - 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. - No raw dataset record, payer-card key, credential, or AvalAI key enters client bundles/logging/storage.