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

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