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

docs: define merchant-weighted peer benchmarks

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 17:00:36 +03:30
parent c3f6061a21
commit c6c1a2b3a4
6 changed files with 37 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/METRIC-CATALOGUE.md
View File

@@ -1,7 +1,7 @@
# Analytics Metric Catalogue
- Status: Draft — listed definitions approved; remaining peer weighting is open
- Version: 0.2.0
- Status: Draft — listed definitions approved
- Version: 0.3.0
- Last updated: 2026-08-20
Every merchant-facing number identifies its grain, formula, source fields, filters, Tehran-local period, unit, missing-data behavior, trace path, and definition version.
@@ -84,6 +84,13 @@ Every merchant-facing number identifies its grain, formula, source fields, filte
- `Paid` and `Verified` are both bank-payment successes, but only `Verified` is finalized.
- `Reversed` is not in the success numerator; display it separately when non-zero.
## Open definition
## Peer comparison
- Merchant-weighted versus transaction-weighted peer comparisons
- Cohort: eligible merchants in the active merchant's category for the same selected reporting period; always exclude the active merchant.
- Availability: return a typed suppressed state unless at least 10 other merchants and 1,000 combined peer payment sessions contribute. Suppression never hides the active merchant's own metrics.
- Weighting: calculate each eligible peer merchant's metric independently, then use the median of those merchant values. Every merchant contributes one value regardless of payment volume.
- Rationale: merchant volume is extremely skewed (median 78 attempts, p95 8,915, maximum 1,138,592). A transaction-weighted average would mostly describe the largest merchants, while a merchant-weighted median represents a typical peer and resists extreme values.
- Output: expose the cohort median and the active merchant's performance percentile; never expose an individual peer's identity, value, or rank.
- Percentile direction: a higher displayed percentile always means better performance. Use the natural direction for payment success, verification completion, and retry recovery; invert the ranking direction for processing time and paid fee rate, where lower is better.
- Benchmarked metrics: `payment_success_rate`, `verification_completion_rate`, `retry_recovery_rate`, `init_time_ms` p50/p95, `verify_time_ms` p50/p95, and `paid_fee_rate`.
- Periods: calculate benchmarks for the same selected day, Saturday–Friday week, Jalali month, or Persian season as the active merchant value. Never compare unlike periods.