docs: approve dashboard analytics defaults

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.
+4. Whether a dark theme is required; it is not assumed merely because the public site uses dark feature sections.
-5. Whether a dark theme is required; it is not assumed merely because the public site uses dark feature sections.

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.