4.1 KiB
Domain Glossary
Merchant
A business represented in the source data. A merchant owns terminals, payment sessions, and merchant users. In the MVP, detailed data is visible only within that merchant's authenticated boundary.
Merchant User
A person/account permitted to authenticate as one merchant. The hackathon seed creates an initial demo user for each merchant; a merchant and a merchant user are not the same concept.
Terminal
A merchant-owned payment endpoint identified by the source terminal key.
Payment Session
One payment journey identified by the source session key. A session belongs to one merchant and terminal and can contain one or more payment attempts.
Payment Attempt
One try within a payment session, distinguished by its try sequence. This is the grain of a source CSV row and must not be confused with a unique payment session.
Bank-Paid Session
A payment session whose source status is Paid or Verified. In both states the buyer completed payment at the bank and funds were deducted. This is the numerator population for payment success and paid-volume metrics.
Verified Session
A bank-paid session whose merchant verification step is complete (Verified). It is finalized, and is a subset of bank-paid sessions.
Unverified Paid Session
A bank-paid session whose bank step succeeded but whose merchant verification step has not completed (Paid). It is successful at the bank, not a failure, and must remain visible as an actionable verification gap.
Merchant Fee
The Rial fee associated with one payment session. The challenge source calls it adjusted_fee and repeats the same value on each attempt row; the normalized model stores it once on the session as fee_amount_rial.
Opaque Payer Token
The nullable payer_card_key source value. It is an unverified, merchant-scoped token used only for internal approximate repeat-payer analytics. It is not a card number or verified person identifier.
Import Run
One traceable attempt to ingest a specific source archive/schema using a specific importer revision. It records outcome, counts, validation evidence, and provenance.
Calendar Date
One civil date enriched with Gregorian and Jalali calendar attributes, Persian month/season, weekday, and reporting attributes.
Reporting Period
An approved time window used for metrics: Tehran-local day, week, Jalali month, or Persian season.
Analytical Metric
A deterministic numerical measure with a definition, source fields, filters, period, unit, missing-data behavior, and drill-down path.
Analytics Projection
A rebuildable, versioned analytics result derived from normalized PostgreSQL facts and cached in Redis for one merchant/cohort revision. It is not independent business truth.
Analytics Revision
A monotonically increasing PostgreSQL merchant or cohort version changed when a related payment fact is inserted. Redis cache keys include the revisions they represent; a mismatch causes request-triggered section jobs to calculate new keys while older keys expire through TTL.
Analytics Section
One independently calculable and deliverable dashboard part. The MVP section ids are overview, payment_performance, fees, and peer_comparison. All four start on first dashboard access and become visible independently through authenticated SSE events.
Peer Cohort
The other eligible merchants in the active merchant's category and selected reporting period, used for anonymized comparison. The active merchant is excluded, and a benchmark is suppressed unless at least 10 peers and 1,000 combined peer sessions contribute.
Merchant-Weighted Cohort Median
The median of one independently calculated metric value per eligible peer merchant. Every merchant contributes one value regardless of transaction volume, so the result represents a typical peer rather than primarily representing the largest merchants.
Peer Performance Percentile
The active merchant's position among eligible same-category peers for one metric and reporting period. A higher displayed percentile always means better performance; metrics where lower values are better are direction-adjusted before ranking.