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

docs: approve analytics presentation defaults

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 17:29:27 +03:30
parent a70fc15517
commit 96e045c4e1
2 changed files with 17 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/METRIC-CATALOGUE.md
View File

@@ -1,7 +1,7 @@
# Analytics Metric Catalogue
- Status: Draft — listed definitions approved
- Version: 0.3.0
- Version: 0.4.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.
@@ -61,6 +61,14 @@ Every merchant-facing number identifies its grain, formula, source fields, filte
- Grain/unit: distinct sessions
- Traceability: ordered merchant-scoped attempt history; never depend on CSV row order
## Payment-stage diagnostics
- `no_attempt_sessions`: count sessions with zero normalized payment attempts. During challenge bootstrap this corresponds to the source marker `try_seq = 0 AND try_status = 'NoAttempt'`; the marker itself is not an attempt.
- `reached_bank_sessions`: count distinct sessions containing at least one attempt with `try_status IN ('InBank', 'Paid', 'Verified', 'Reversed')`.
- `in_bank_without_result_sessions`: count sessions whose latest positive-sequence attempt is `InBank` and which have no later `Paid`, `Verified`, `Failed`, or `Reversed` attempt.
- `failed_sessions`: count sessions with final `session_status = 'Failed'`; drill-down may distinguish zero-attempt, reached-bank, and other observable stages without inventing undocumented failure causes.
- Grain/unit: distinct payment sessions; attempt-stage counts must deduplicate by session when presented as sessions.
## Processing time
- Report median (p50) and p95 separately for `init_time_ms` and `verify_time_ms`
@@ -83,6 +91,7 @@ Every merchant-facing number identifies its grain, formula, source fields, filte
- Zero, undefined, missing, suppressed peer value, and calculation failure remain distinct states.
- `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.
- `NoAttempt` is a source session marker, not a failed payment attempt. `InBank` means the user reached a bank gateway but no later outcome was recorded for that attempt; do not call it a bank rejection.
## Peer comparison