From 5cd145c28377219b3071bebfa5998f3f300387d8 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 17:54:32 +0330 Subject: [PATCH] docs(dashboard): require detail CSV exports --- DESIGN.md | 7 +++++-- docs/DASHBOARD-SPEC.md | 4 +++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 7fb7565..b7ef772 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics -- Status: Approved baseline — licensed font assets pending; implementation not yet authorized -- Version: 0.3.0 +- Status: Approved baseline — implementation not yet authorized +- Version: 0.3.1 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -65,6 +65,7 @@ Light and dark modes are first-class variants of the same semantic token system. - Required Persian UI family: licensed **Iran Yekan X Professional** (`IRANYekanX`), matching the current ZarinPal panel's `IRANYekanXVFaNumVF` variable font. - Required asset: the Persian-number (`FaNum`) variable webfont in WOFF2, covering the `wght` axis from 100–1000. The product uses 400 for body/value text, 500 for labels and controls, 600 for emphasis, and 700 for section/page headings. No separate static weights are required when the variable file is supplied. - Purchase/issue the website or software license for this project and domain. Font files are proprietary assets: they must be delivered privately, self-hosted by the frontend, excluded from public-source distribution unless the license explicitly permits it, and never copied from ZarinPal's CDN. +- The purchased package has been verified to contain `IRANYekanXVFaNumVF.woff2`, its WOFF fallback, static families, documentation, and license material. The binaries and license identifier remain outside the public repositories; Platform Operations must define a reproducible private build/deployment injection path before implementation. - Runtime fallback while the licensed asset is unavailable: `Tahoma`, system sans-serif. The fallback is for resilience, not the approved visual baseline. - Evidence: inspection of the current [ZarinPal panel](https://next.zarinpal.com/beta/panel) found `IRANYekanXVFaNumVF` declared for weights 100–1000. The licensed [Iran Yekan X product page](https://fontiran.com/fonts/iranyekan) identifies the professional package as the option containing all weights, the variable font, Persian-number assets, and WOFF/WOFF2 webfonts. - Use tabular numerals for tables/KPIs where supported. @@ -128,6 +129,7 @@ Navigation labels should describe merchant tasks, not internal database concepts - **Chart card:** title, period/filter controls, concise takeaway, plot, legend, accessible tabular alternative, provenance link, and section-local loading/error behavior. - **Insight card:** deterministic finding, numeric evidence, suggested merchant action, confidence/limitation; AI-generated copy is visibly labeled later. - **Data table:** semantic headers, server pagination/sorting, row actions named for screen readers, responsive priority, empty/error states. +- **Analytics export:** eligible merchant-owned detail views expose an explicit CSV export action that applies the current approved filters and clearly states period, unit, generation state, and failure/retry behavior. Aggregate-only cards and peer data are not exported unless separately specified. - **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved daily, weekly, Jalali-month, and Persian-season periods with unambiguous comparison baselines. - **Status badge:** text plus icon/shape; color reinforces but never carries meaning alone. - **Feedback:** inline field errors, page-level error boundary, skeleton only when layout is known, retry action for recoverable failures. @@ -182,6 +184,7 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 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. | | 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. | diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index 5394a11..2b5cd0d 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -46,6 +46,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe 28. A deterministic insight is promoted into an actionable card only when at least 100 relevant sessions contribute and the comparison changes by at least 3 percentage points for a rate or 20 percent for an amount/count. Smaller changes remain available as metrics without an action claim. 29. All merchant-facing values use Persian digits and monetary values use Rial only. Technical identifiers remain canonical and are directionally isolated. 30. Light and dark modes are supported from the first release through the semantic token contract in `DESIGN.md`; system preference is the default and an explicit accessible user choice persists locally. +31. Merchant-owned detail views that support operational handoff provide CSV export using the current authorized filters. Export never contains payer tokens, peer-level data, credentials, or fields absent from the corresponding authorized detail view. ## Frontend architecture baseline @@ -66,6 +67,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe - Merchant-facing digits are Persian, money is labeled in Rial only, and technical identifiers remain uncorrupted in RTL layouts. - Light and dark modes both meet the documented contrast, focus, chart, state, and reduced-motion requirements at all acceptance viewports, with no first-paint theme flash. - Below-threshold comparisons never produce actionable insight language, while qualifying insight cards expose their numeric evidence and limitation. +- Authorized CSV exports reconcile to the same filtered detail query shown in the dashboard, retain explicit Rial/date/status semantics, and remain tenant-isolated even when export parameters are manipulated. - Success views include `Paid` plus `Verified`, verification-completion views separate them, and unverified paid sessions are never styled or described as failures. - Paid volume and merchant fee values reconcile at session grain; fee totals remain unchanged when a session has additional attempts. - Retry recovery includes eventual `Paid` or `Verified`, and timing percentiles never treat missing values as zero. @@ -91,5 +93,5 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe - Approved analytics interface contract for the metric catalogue and cohort policy - Approved authentication/session API - OpenAPI/interface contract and error format -- Delivery of the licensed Iran Yekan X Professional FaNum variable webfont +- Approved private build/deployment injection path for the licensed Iran Yekan X Professional FaNum variable webfont - Static adapter fallback/routing behavior under the final Nginx configuration