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

docs(metrics): align catalogue with physical schema

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 18:49:55 +03:30
parent f9356da179
commit a0e2b70cf4
1 changed files with 11 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/METRIC-CATALOGUE.md
View File

@@ -1,11 +1,20 @@
# Analytics Metric Catalogue # Analytics Metric Catalogue
- Status: Draft — listed definitions approved - Status: Approved specification — implementation not yet authorized
- Version: 0.4.0 - Version: 0.4.0
- Last updated: 2026-08-20 - 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. Every merchant-facing number identifies its grain, formula, source fields, filters, Tehran-local period, unit, missing-data behavior, trace path, and definition version.
## Physical source mapping
- Session-grain metrics read `payment_sessions`, scoped by `merchant_id` and the approved half-open `created_at` period.
- Attempt-grain diagnostics and timings join `payment_attempts.payment_session_id` to the already merchant-scoped session set.
- Money uses `payment_sessions.amount_rial` and `payment_sessions.fee_amount_rial` exactly once per session.
- Terminal filters join the session's `terminal_id`; peer cohorts join the merchant's `category_id` and exclude the active merchant.
- The sole completed `import_runs` row identifies the immutable MVP dataset snapshot included in cache/result metadata.
- `calendar_dates` defines Saturday–Friday weeks, Jalali months, and Persian seasons; no holiday dimension exists.
## Bank-paid sessions ## Bank-paid sessions
- Canonical id: `bank_paid_sessions` - Canonical id: `bank_paid_sessions`
@@ -49,7 +58,7 @@ Every merchant-facing number identifies its grain, formula, source fields, filte
## Paid volume ## Paid volume
- Canonical id: `bank_paid_amount_rial` - Canonical id: `bank_paid_amount_rial`
- Formula: sum session `amount` once where `session_status IN ('Paid', 'Verified')` - Formula: sum session `amount_rial` once where `session_status IN ('Paid', 'Verified')`
- Unit: Rial - Unit: Rial
- Subsets: `verified_amount_rial` uses `Verified`; `unverified_paid_amount_rial` uses `Paid` - Subsets: `verified_amount_rial` uses `Verified`; `unverified_paid_amount_rial` uses `Paid`