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

7
docs/DASHBOARD-SPEC.md
View File

@@ -20,7 +20,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
2. The app shell identifies the active merchant and offers logout.
3. Overview shows data freshness, selected period, primary outcomes, trend, and prioritized deterministic insights.
4. Payment performance supports success/failure/retry/timing analysis and traceable drill-downs.
5. Peer comparison excludes the active merchant and exposes only eligible anonymized cohort aggregates. It displays a value only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise it explains that there is not enough data. This never hides the merchant's own analytics.
5. Peer comparison uses other eligible merchants in the active merchant's category for the same selected period and excludes the active merchant. For payment success, verification completion, retry recovery, processing-time p50/p95, and paid fee rate, it shows the merchant-weighted cohort median plus the active merchant's direction-aware performance percentile. Every peer has equal weight regardless of transaction volume. Values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise the page explains that there is not enough data. This never hides the merchant's own analytics.
6. Filters and pagination are reflected in the URL where sharing/reload is useful.
7. Every screen implements loading, empty, partial-data, stale, unauthorized, forbidden, and recoverable-error behavior as applicable.
8. Responsive behavior and component contracts follow `DESIGN.md`.
@@ -57,6 +57,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
- 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.
- Peer benchmarks use only the same category and selected period, exclude the active merchant, and give every eligible peer merchant one equal-weight metric value.
- Peer cards show the cohort median and a percentile where higher always means better; processing-time and fee-rate ranks are direction-adjusted because lower values are better.
- A high-volume peer cannot dominate the cohort median, and under-sized cohorts produce the typed insufficient-data state without hiding merchant-owned analytics.
- All core sections begin on first access and become visible independently in completion order without blocking the whole dashboard.
- The start request is idempotent and always maps equivalent concurrent starts to the same current run.
- A second equivalent access reuses current Redis entries, and concurrent first accesses do not enqueue duplicate equivalent section jobs.
@@ -71,7 +74,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
## Unresolved dependencies
- Approved analytics metric catalogue and cohort suppression policy
- Approved analytics interface contract for the metric catalogue and cohort policy
- Approved authentication/session API
- OpenAPI/interface contract and error format
- Decisions listed in `DESIGN.md`