docs: record production analytics decisions

docs/METRIC-CATALOGUE.md

@@ -0,0 +1,37 @@
+# Analytics Metric Catalogue
+
+- Status: Draft — definitions are approved individually
+- Version: 0.1.0
+- Last updated: 2026-08-20
+
+Every merchant-facing number must identify its grain, formula, source fields, filters, time basis, unit, missing-data behavior, trace path, and definition version.
+
+## Confirmed successful sessions
+
+- Canonical id: `confirmed_successful_sessions`
+- Grain: distinct payment session
+- Formula: count payment sessions where source `session_status = 'Verified'`
+- Unit: sessions
+- Time attribution: session `created_at`, converted to `Asia/Tehran` local reporting date
+- Missing behavior: `session_status` is required; unknown values are not counted and trigger quality evidence
+- Traceability: drill down to eligible session identifiers and their attempt histories within the authenticated merchant
+- Approved decision: `Paid` is not included; it remains a separate state until ZarinPal provides an authoritative definition
+
+## Paid but not confirmed as verified
+
+- Canonical id: `paid_unverified_sessions`
+- Grain: distinct payment session
+- Formula: count payment sessions where source `session_status = 'Paid'`
+- Unit: sessions
+- Presentation: separate operational state; never label as confirmed success or failure
+- Traceability: same merchant-scoped session/attempt drill-down
+
+## Open definitions
+
+- Success-rate denominator and treatment of `Failed`/`Reversed`/`Paid`
+- Amount metric inclusion by session status
+- Retry and recovery definitions
+- Timing percentile definitions and missing coverage
+- Fee-ratio terminology for obfuscated `adjusted_fee`
+- Merchant-weighted versus transaction-weighted peer comparisons
+