From 1654fd5f6551629d5b6298b7513b7ae6a22a719c Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 19:00:08 +0330 Subject: [PATCH] docs(spec): align dashboard implementation contracts --- DESIGN.md | 3 ++- docs/DASHBOARD-SPEC.md | 12 ++++++------ docs/DASHBOARD-UX-SPEC.md | 16 ++++++++-------- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index b6196ac..f8c3d75 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Approved baseline — implementation not yet authorized -- Version: 0.3.2 +- Version: 0.3.3 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -184,6 +184,7 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 0.3.3 | 2026-08-20 | Replaced merchant/cohort revision freshness language with the approved immutable completed-import dataset snapshot. This changes trace labels only; cache age still does not imply stale data. | | 0.3.2 | 2026-08-20 | Made the licensed Iran Yekan X FaNum variable WOFF2 and its required license file Git-tracked frontend assets, eliminating a separate private build-injection path. | | 0.3.1 | 2026-08-20 | Verified the purchased Iran Yekan X Professional FaNum variable assets and required a private, reproducible injection path for public repositories. Added merchant-owned detail CSV export as an MVP component contract. | | 0.3.0 | 2026-08-20 | Approved Iran Yekan X Professional FaNum variable typography, Persian digits, Rial-only values, and first-class light/dark semantic themes. Added the deterministic insight eligibility threshold. | diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index d606570..924c4ca 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -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. diff --git a/docs/DASHBOARD-UX-SPEC.md b/docs/DASHBOARD-UX-SPEC.md index 502cbca..5e35785 100644 --- a/docs/DASHBOARD-UX-SPEC.md +++ b/docs/DASHBOARD-UX-SPEC.md @@ -401,7 +401,7 @@ Do not reveal which threshold failed, a near-threshold count that could aid diff - Payment lifecycle: why `Paid` and `Verified` are bank successes and only `Verified` is finalized. - Coverage: unknown statuses, timing non-null coverage, sample counts, and missing baseline behavior. - Peer privacy: equal-per-merchant median, direction-aware percentile, suppression, and prohibited peer detail. -- Calculation lifecycle: lazy first access, independent four-section delivery, revision/version trace, and 30-day disposable cache without implying TTL-based staleness. +- Calculation lifecycle: lazy first access, independent four-section delivery, immutable dataset-snapshot/metric-version trace, and 30-day disposable cache without implying TTL-based staleness. - Insight policy: 100-session evidence floor and approved change thresholds; observational, not causal language. Definitions open as a page or anchored side panel. They are linkable, keyboard reachable, and do not trap important content inside hover-only tooltips. @@ -451,7 +451,7 @@ Overall progress is written as a contextual message such as «۲ از ۴ بخش ### 10.3 Stale/freshness language -The frontend does not label data stale merely because a Redis entry is old or its 30-day TTL is approaching. Revisioned source/cohort keys and metric-definition version determine reuse. “Stale” appears only if a future approved interface returns an explicit stale/quality state. During SSE interruption, ready data is labeled with its calculation timestamp and connection recovery state, not silently called current or stale. +The frontend does not label data stale merely because a Redis entry is old or its 30-day TTL is approaching. The immutable completed-import dataset snapshot and metric-definition version determine reuse. “Stale” appears only if a future approved interface returns an explicit stale/quality state. During SSE interruption, ready data is labeled with its calculation timestamp and connection recovery state, not silently called current or stale. ### 10.4 Event ordering and duplication @@ -771,7 +771,7 @@ Persian digits are applied to rendered variable values. Technical identifiers in ## 20. Implementation handoff checklist (after approval only) -- Obtain approved machine-readable analytics, identity, detail, SSE, error, and export contracts. +- Generate transport types only from approved backend `docs/openapi.yaml` version `1.0.0` and fail checks on drift. - Resolve static adapter/Nginx fallback behavior. - Verify that local, CI, and Docker builds consume the tracked FaNum variable font and retain its adjacent license file without external downloads. - Create implementation tasks for shell, formatting, authentication, filters, run/SSE state model, each canonical section, detail tables, export, themes, and tests. @@ -780,9 +780,9 @@ Persian digits are applied to rendered variable values. Technical identifiers in No implementation work begins until the dashboard capability and this UX specification are explicitly approved. -## 21. Remaining approval questions +## 21. Resolved implementation handoff -1. Approve or revise the backend draft CSV contract: synchronous delivery, eligible detail types/columns, UTF-8 BOM, ASCII `snake_case` headers, UTC timestamps, filename policy, 100,000-row/50-MiB caps, 60-second deadline, throttling, retention, and audit event. -2. Should CSV preflight be a modal dialog on desktop or an inline disclosure, provided the mobile experience remains a focus-managed full-screen dialog/sheet? -3. Approve the draft `AuthSession.merchant.displayName` field as authoritative for the shell and export preflight when the demo username differs. -4. Is a downloadable chart-data table required in MVP, or is a visible semantic table alternative sufficient while CSV remains limited to authorized detail views? +- CSV follows the approved backend contract: synchronous merchant-detail export, Persian headers, UTF-8 BOM, UTC timestamps, safe filename, 100,000-row/50-MiB/60-second caps, throttling, and 90-day analytics/export audit retention. +- Export confirmation may use a compact inline disclosure on desktop and a focus-managed full-screen dialog/sheet on narrow screens. +- `AuthSession.merchant.displayName` is authoritative for the shell and export confirmation when it differs from the demo username. +- Every chart has a visible semantic table alternative. CSV remains limited to approved merchant-owned detail views; chart-data download is not a separate MVP export.