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

docs: limit dashboard reporting periods

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 16:04:06 +03:30
parent fd8923faeb
commit 9a0c2f1b3b
2 changed files with 7 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
DESIGN.md
View File

@@ -1,7 +1,7 @@
# Design System — ZarinPal Merchant Analytics
- Status: Draft baseline for approval
- Version: 0.1.4
- Version: 0.1.5
- Last updated: 2026-08-20
- Direction: Persian-first RTL
@@ -98,7 +98,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.
- **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.
- **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved day, Jalali-month, Persian-season, and named holiday/event periods with unambiguous comparison baselines.
- **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.
@@ -106,13 +106,12 @@ Navigation labels should describe merchant tasks, not internal database concepts
- Lead with a written takeaway and exact KPI; charts support the conclusion rather than decorate it.
- Default comparisons: current period vs previous equivalent period and merchant vs an eligible anonymized cohort. Peer values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise show a clear insufficient-data state.
- Always show unit, timezone/calendar, date or named-event window, comparison baseline, sample size, freshness, and missing-data caveat where material.
- Always show unit, timezone/calendar, exact reporting period, comparison baseline, sample size, freshness, and missing-data caveat where material.
- Success/failure colors remain semantic and consistent. Never use a rainbow categorical palette for ordered values.
- Tooltips are keyboard reachable and not the sole location of important values.
- Charts have a textual summary and downloadable/visible data table when practical.
- Zero, unavailable, suppressed, and not-yet-calculated are visually and linguistically distinct.
- Only source status `Verified` is presented as a confirmed successful payment. `Paid` is a separate operational state and is never merged into success or failure without a later approved metric-definition change.
- Named Iranian holidays come from reviewed, versioned calendar data. Analytical campaign windows such as a broader Nowruz period are labeled separately from official public-holiday dates.
## Motion
@@ -144,8 +143,8 @@ Navigation labels should describe merchant tasks, not internal database concepts
| Version | Date | Decision |
|---|---|---|
| 0.1.4 | 2026-08-20 | Defined the 15-minute freshness/stale UX, kept `Paid` separate from confirmed `Verified` success, and distinguished official holidays from analytical event windows. |
| 0.1.3 | 2026-08-20 | Added explicit Jalali-month, Persian-season, and named holiday/event reporting periods with visible baselines and evidence. |
| 0.1.5 | 2026-08-20 | Removed holiday/event reporting; limited period controls to daily, weekly, Jalali-month, and Persian-season views. |
| 0.1.4 | 2026-08-20 | Defined the 15-minute freshness/stale UX and kept `Paid` separate from confirmed `Verified` success. |
| 0.1.2 | 2026-08-20 | Added the insufficient-data state and visibility threshold for anonymized peer comparisons. |
| 0.1.1 | 2026-08-20 | Fixed merchant-facing time presentation to the Jalali calendar in `Asia/Tehran`, with explicit UTC API instants. |
| 0.1.0 | 2026-08-20 | Established ZarinPal-inspired RTL foundation from supplied public/panel screenshots; fixed SvelteKit/Svelte/TypeScript/Tailwind stack; defined responsive shell, core components, accessibility, chart, and motion rules. |