From fd8923faeb0068dd45a0968695321926fe1fe36c Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 15:58:56 +0330 Subject: [PATCH] docs: define analytics freshness states --- DESIGN.md | 7 +++++-- docs/DASHBOARD-SPEC.md | 6 ++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 5311b32..0ba4ffb 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -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. | diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index 84b8aee..8470dea 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -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`. 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. +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 @@ -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. - 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. +- 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. - No raw dataset record, payer-card key, credential, or AvalAI key enters client bundles/logging/storage.