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

docs: define peer comparison presentation

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 17:00:40 +03:30
parent 8ba8c2c74f
commit b07674dae9
2 changed files with 8 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
DESIGN.md
View File

@@ -1,7 +1,7 @@
# Design System — ZarinPal Merchant Analytics
- Status: Draft baseline for approval
- Version: 0.2.0
- Version: 0.2.1
- Last updated: 2026-08-20
- Direction: Persian-first RTL
@@ -106,7 +106,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
## Data visualization
- 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.
- Default comparisons: current period vs previous equivalent period and merchant vs eligible merchants in the same category and selected period. Peer cards show the merchant-weighted cohort median and the active merchant's performance percentile; each peer contributes one value regardless of transaction volume. A higher displayed percentile always means better, so processing-time and fee-rate ranks are direction-adjusted. 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, 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.
@@ -146,6 +146,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
| Version | Date | Decision |
|---|---|---|
| 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. |
| 0.2.0 | 2026-08-20 | Corrected payment lifecycle semantics from CTO guidance: `Paid` and `Verified` are bank-payment successes, `Paid` remains unverified, and session-level fees are real Rial amounts. |
| 0.1.9 | 2026-08-20 | Added rate-limit UX, 15-second SSE heartbeat/recovery, one-hour replay, and failed-section-only manual retry. |
| 0.1.8 | 2026-08-20 | Fixed the four parallel section ids, 30-day cache, idempotent start/SSE flow, and section timeout/retry behavior. |