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
docs/DASHBOARD-SPEC.md
View File

@@ -25,9 +25,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
7. Every screen implements loading, empty, partial-data, stale, unauthorized, forbidden, and recoverable-error behavior as applicable.
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 are daily, weekly, Jalali-month, and Persian-season views. Every comparison states its exact period and baseline.
10. Approved reporting periods are daily, weekly, Jalali-month, and Persian-season views. Weekly periods run Saturday through Friday in `Asia/Tehran`. Every comparison states its exact period and baseline.
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.
12. The first relevant dashboard access may calculate analytics and shows a bounded calculation/loading state. Later equivalent requests reuse the current PostgreSQL-backed merchant cache. When the source or cohort revision changes, the next access recalculates; an older result is shown only with an explicit stale warning and last-calculated time.
## Frontend architecture baseline
@@ -46,7 +46,8 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
- 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.
- First access calculates once, a second equivalent access reuses the current cached revision, and concurrent first accesses do not create duplicate user-visible calculations.
- A source-revision mismatch is visibly stale until successful recalculation; cache age alone does not make static data stale.
- Daily, weekly, Jalali-month, and Persian-season filters use the same explicit boundaries as the API and database.
- 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.