90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
## Authenticated Session
|
|
|
|
A time-bounded and revocable authorization grant connecting one authenticated merchant user to exactly one merchant boundary. Logout, account disablement, idle expiry, or absolute expiry ends the grant.
|
|
|
|
## Terminal
|
|
|
|
A merchant-owned payment endpoint identified by the source terminal key. In the challenge archive, the terminal also carries its invariant verification method (`Automated` or `Manual`); one merchant may own terminals configured differently.
|
|
|
|
## Payment Session
|
|
|
|
One payment journey identified by the source session key. A session belongs to one merchant and terminal and can contain zero or more payment attempts.
|
|
|
|
## Payment Attempt
|
|
|
|
One actual try within a payment session, distinguished by a positive try sequence. Most source rows represent attempts, but a source row with `try_seq = 0` and `try_status = NoAttempt` is a session marker and must not become an attempt.
|
|
|
|
## No-Attempt Session
|
|
|
|
A payment session for which the source explicitly records `try_seq = 0` and `try_status = NoAttempt`. It has zero payment attempts; the marker preserves the session without inventing an attempt.
|
|
|
|
## 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 product's real Rial fee associated with one payment session. It is counted once per session regardless of the number of attempts.
|
|
|
|
## Opaque Payer Token
|
|
|
|
The nullable `payer_card_key` source value: a pseudonymous card identifier whose equality is meaningful only within one merchant. It supports internal repeat-card analytics where populated, but it is not a card number, a cross-merchant identifier, or a 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 immutable dataset snapshot. It is not independent business truth.
|
|
|
|
## Dataset Snapshot
|
|
|
|
The one completed import run selected for the MVP. Its immutable import-run id, source checksum, and schema version identify the PostgreSQL facts represented by a Redis cache key. The MVP does not mutate payment facts or require cache-invalidation triggers.
|
|
|
|
## 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.
|