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

docs(spec): align dashboard implementation contracts

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 19:00:08 +03:30
parent 98dada4cb0
commit 1654fd5f65
3 changed files with 16 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/DASHBOARD-SPEC.md
View File

@@ -31,7 +31,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
11. `Paid` and `Verified` both count as successful bank payments. `Paid` means funds were deducted but merchant verification is incomplete; `Verified` is finalized. Success and paid-volume metrics include both, while verification-health metrics show them separately.
12. The first relevant dashboard access sends an idempotent authenticated `POST` that creates or returns the current analytics run and starts four sections in bounded parallel: overview, payment performance, fees, and peer comparison.
13. The app then opens the run's authenticated `GET` 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.
14. Later equivalent requests reuse 30-day 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. Later equivalent requests reuse 30-day Redis entries keyed by the immutable completed-import dataset snapshot and metric-definition version; cache age alone does not make static data stale.
15. SSE reconnect uses stable event ids/resume semantics, shows a connection-recovery state, and never exposes job status or analytics for another merchant.
16. Each section attempt times out after 60 seconds. The backend may perform at most two automatic transient retries using exponential backoff/jitter; the UI represents the section as calculating during automatic retries and exposes failure/retry only after exhaustion or a non-retryable error.
17. SSE expects a heartbeat every 15 seconds and supports authorized replay for one hour. After replay expires, the app fetches the current run snapshot before reopening the stream.
@@ -96,11 +96,11 @@ Resolved specification inputs:
- Backend `ANALYTICS-SPEC.md` is approved, and the definitions in `METRIC-CATALOGUE.md` version `0.4.0` are authoritative.
- Backend `IDENTITY-SPEC.md` is approved for demo authentication, sessions, and tenant isolation.
- `DESIGN.md` version `0.3.2` approves the Git-tracked `static/fonts/IRANYekanXVFaNumVF.woff2` asset and adjacent `static/fonts/FontLicense.txt`.
- `DESIGN.md` version `0.3.3` approves the Git-tracked `static/fonts/IRANYekanXVFaNumVF.woff2` asset and adjacent `static/fonts/FontLicense.txt`.
Still required before implementation:
Resolved implementation contracts:
- Approved machine-readable analytics, identity, detail, SSE, error, and CSV export interface contracts.
- Provider contract incorporation of the approved CSV schema, UTF-8 BOM encoding, filename, 100,000-row and 50 MiB caps, synchronous 60-second delivery limit, rate limit, and 30-day audit retention behavior.
- Static adapter fallback/routing behavior under the final Nginx configuration.
- Backend `docs/openapi.yaml` version `1.0.0` is the approved machine-readable analytics, identity, detail, SSE, error, and CSV export interface contract.
- CSV uses the approved Persian headers, UTF-8 BOM, filename policy, 100,000-row and 50 MiB caps, synchronous 60-second limit, and rate limit. Analytics/detail/export audit retention is 90 days; minimal demo authentication audit retention is 30 days.
- Static adapter output is served with history fallback only for frontend routes; `/api/v1` and other reserved operational paths never fall through to `index.html`.
- Separate explicit authorization to begin Phase 4 implementation.