diff --git a/DESIGN.md b/DESIGN.md index 5052e92..b852e88 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Draft baseline for approval -- Version: 0.2.3 +- Version: 0.2.4 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -115,6 +115,9 @@ Navigation labels should describe merchant tasks, not internal database concepts - A ready section appears immediately without layout-shifting or blocking on unfinished siblings. Overall progress remains understandable without relying on animation. - Source statuses `Paid` and `Verified` both count as successful bank payments because funds were deducted. Keep them visually distinguishable: `Paid` means merchant verification is incomplete and is an actionable gap; `Verified` is finalized. - Present `fee_amount_rial` as the merchant's real fee, summed once per session. Never multiply it by retry attempts or label it as obfuscated/relative-only in the product. +- First load selects the latest complete Jalali month containing data and compares only with the immediately previous equivalent period. An absent baseline has an explicit unavailable state. +- Overview leads with bank-paid amount, bank-paid session count, success rate, and verification completion. Retry, timing, and fee modules follow in that order of detail. +- Drill-down tables for unverified-paid, failed, and retried sessions are read-only. They never reveal payer tokens or peer rows; `NoAttempt` and `InBank` are stage labels, not invented failure causes. ## Motion @@ -146,6 +149,7 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 0.2.4 | 2026-08-20 | Fixed the static-demo default period, comparison fallback, overview KPI priority, and safe read-only drill-down scope; added accurate `NoAttempt`/`InBank` stage language from the CTO data guide. | | 0.2.3 | 2026-08-20 | Kept authentication UX intentionally demo-sized: generic and throttled username/password login now, with a clean replacement boundary for ZarinPal SSO after acceptance. | | 0.2.2 | 2026-08-20 | Defined backend-owned session UX: authentication tokens remain inaccessible to the frontend, and expiry/revocation returns the user to login with a generic, accessible message. | | 0.2.1 | 2026-08-20 | Defined same-category peer cards as an equal-per-merchant median plus direction-aware percentile. This prevents the dataset's largest merchants from dominating what should represent a typical peer. | @@ -166,5 +170,4 @@ Any material token/component/interaction change increments this version and adds 1. Licensed Yekan-family assets vs open `Vazirmatn` fallback. 2. Persian or Latin digits for dashboard values. 3. Rial-only vs Toman display and conversion wording. -4. Exact information architecture and MVP metric set after the analytics spec. -5. Whether a dark theme is required; it is not assumed merely because the public site uses dark feature sections. +4. Whether a dark theme is required; it is not assumed merely because the public site uses dark feature sections. diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index 340361a..0cc83ce 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -40,6 +40,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe 22. Authentication uses a backend-owned server-side session. The frontend receives only a `Secure`, `HttpOnly`, `SameSite=Lax` cookie and never reads or stores an authentication token. 23. Expired, revoked, logged-out, or disabled-account sessions stop dashboard and SSE access immediately and return the user to login without exposing internal authentication details. 24. The demo login handles typed throttling with `Retry-After`, never reveals whether a username exists, and does not implement password recovery, registration, or SSO. ZarinPal SSO replaces the demo credential screen after product acceptance. +25. First dashboard access defaults to the latest complete Jalali month containing data. The comparison is the immediately previous equivalent complete month; if unavailable/empty, the UI explicitly says comparison is unavailable and does not silently substitute another baseline. +26. Overview KPI order is bank-paid amount, bank-paid session count, payment success rate, then verification completion. Retry, processing-time, and fee analysis follow below. +27. Read-only drill-downs are available for unverified-paid, failed, and retried sessions. They exclude payer tokens and peer-level data and may distinguish zero-attempt/reached-bank stages without inventing failure causes. ## Frontend architecture baseline @@ -72,6 +75,8 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe - Missing heartbeats trigger controlled connection recovery; one-hour replay or snapshot fallback restores the authorized current state. - Rate-limited responses enqueue no duplicate work, preserve ready sections, and delay retry according to `Retry-After`. - Daily, weekly, Jalali-month, and Persian-season filters use the same explicit boundaries as the API and database. +- The initial static-demo view selects the latest complete Jalali month with data and uses only the immediately previous equivalent period as its baseline. +- Overview KPI order and read-only unverified/failed/retried drill-downs match the approved analytics contract without exposing payer tokens or peers. - 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.