90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# Analytics Metric Catalogue
|
||
|
||
- Status: Draft — listed definitions approved; remaining peer weighting is open
|
||
- Version: 0.2.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.
|
||
|
||
## Bank-paid sessions
|
||
|
||
- Canonical id: `bank_paid_sessions`
|
||
- Grain: distinct payment session
|
||
- Formula: count sessions where `session_status IN ('Paid', 'Verified')`
|
||
- Meaning: the buyer completed the bank payment and funds were deducted
|
||
- Unit: sessions
|
||
- Time attribution: session `created_at` in `Asia/Tehran`
|
||
- Traceability: merchant-scoped session identifiers and attempt histories
|
||
|
||
## Payment success rate
|
||
|
||
- Canonical id: `payment_success_rate`
|
||
- Numerator: `bank_paid_sessions`
|
||
- Denominator: sessions where `session_status IN ('Paid', 'Verified', 'Failed', 'Reversed')`
|
||
- Formula: numerator / denominator; undefined when denominator is zero
|
||
- Unknown statuses: excluded from both sides and disclosed as coverage/quality evidence until classified
|
||
- Unit: percentage
|
||
|
||
## Verified sessions
|
||
|
||
- Canonical id: `verified_sessions`
|
||
- Formula: count sessions where `session_status = 'Verified'`
|
||
- Meaning: bank payment and merchant verification are complete; the payment is finalized
|
||
- Unit: sessions
|
||
|
||
## Unverified paid sessions
|
||
|
||
- Canonical id: `unverified_paid_sessions`
|
||
- Formula: count sessions where `session_status = 'Paid'`
|
||
- Meaning: bank payment succeeded and funds were deducted, but merchant verification is incomplete
|
||
- Presentation: actionable verification gap; never label as failure
|
||
- Unit: sessions
|
||
|
||
## Verification completion rate
|
||
|
||
- Canonical id: `verification_completion_rate`
|
||
- Formula: `verified_sessions / bank_paid_sessions`; undefined when no bank-paid sessions exist
|
||
- Unit: percentage
|
||
|
||
## Paid volume
|
||
|
||
- Canonical id: `bank_paid_amount_rial`
|
||
- Formula: sum session `amount` once where `session_status IN ('Paid', 'Verified')`
|
||
- Unit: Rial
|
||
- Subsets: `verified_amount_rial` uses `Verified`; `unverified_paid_amount_rial` uses `Paid`
|
||
|
||
## Retried sessions and eventual payment
|
||
|
||
- `retried_sessions`: count sessions containing more than one payment attempt
|
||
- `eventually_paid_after_retry_sessions`: count retried sessions whose final session status is `Paid` or `Verified` and which contain a lower-`try_seq` attempt whose status is neither `Paid` nor `Verified`
|
||
- `retry_recovery_rate`: `eventually_paid_after_retry_sessions / retried_sessions`; undefined when no retried sessions exist
|
||
- Grain/unit: distinct sessions
|
||
- Traceability: ordered merchant-scoped attempt history; never depend on CSV row order
|
||
|
||
## Processing time
|
||
|
||
- Report median (p50) and p95 separately for `init_time_ms` and `verify_time_ms`
|
||
- Include only non-null values for the relevant field
|
||
- Always show contributing sample count and coverage percentage
|
||
- Do not replace missing timing with zero
|
||
- Unit: milliseconds, with human-readable seconds allowed as an additional presentation
|
||
|
||
## Merchant fee
|
||
|
||
- Canonical field: `fee_amount_rial`, sourced from CSV `adjusted_fee` and stored once per session
|
||
- `paid_fee_amount_rial`: sum session fee once where `session_status IN ('Paid', 'Verified')`
|
||
- `paid_fee_rate`: `paid_fee_amount_rial / bank_paid_amount_rial`; undefined when paid amount is zero
|
||
- Meaning/presentation: real merchant fee in Rial; do not label it obfuscated or relative-only in the product
|
||
- Retry rule: never sum the repeated source value per attempt
|
||
|
||
## Common behavior
|
||
|
||
- Rates are recomputed from summed numerator/denominator components for every selected day, Saturday–Friday week, Jalali month, and Persian season.
|
||
- 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.
|
||
|
||
## Open definition
|
||
|
||
- Merchant-weighted versus transaction-weighted peer comparisons
|