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

docs: stream partial analytics over sse

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 16:28:44 +03:30
parent d68e2e477c
commit 22ec54d8f4
2 changed files with 13 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/DASHBOARD-SPEC.md
View File

@@ -27,7 +27,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
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. 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. 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.
12. The first relevant dashboard access starts all approved analytics-section jobs in bounded parallel. The app opens an authenticated, merchant-scoped SSE stream and renders each section as soon as its `ready` event arrives. A failed section has its own retry/error state and does not hide successful siblings.
13. Later equivalent requests reuse current high-TTL Redis entries. PostgreSQL merchant/cohort revision changes select new cache keys and cause only missing sections to be recalculated; cache age alone does not make static data stale.
14. SSE reconnect uses stable event ids/resume semantics, shows a connection-recovery state, and never exposes job status or analytics for another merchant.
## Frontend architecture baseline
@@ -46,8 +48,10 @@ 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.
- 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.
- All core sections begin on first access and become visible independently in completion order without blocking the whole dashboard.
- A second equivalent access reuses current Redis entries, and concurrent first accesses do not enqueue duplicate equivalent section jobs.
- One section failure is isolated, retryable, and accessible; already-ready sections remain usable.
- Disconnecting and reconnecting the SSE stream resumes safely without cross-merchant data or duplicated final sections.
- 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.