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

docs: correct payment and fee semantics

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 16:53:59 +03:30
parent 96a27e1b98
commit c3f6061a21
7 changed files with 138 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/DATA-PROFILING-REPORT.md
View File

@@ -56,7 +56,7 @@ These are source codes, not Persian user-facing descriptions. Meanings and succe
|---|---|---|
| `try_seq` | 0–135 | `smallint`, non-negative |
| `amount` | 1,000–2,000,000,000 | `bigint`, Rial |
| `adjusted_fee` | 1,920–284,800 | fixed-precision numeric; obfuscated relative fee only |
| `adjusted_fee` | 1,920–284,800 | positive integer merchant-fee value; confidentiality-adjusted in the challenge source and normalized as real `fee_amount_rial` per ADR 0013 |
| `init_time_ms` | 44–59,905 | nullable integer milliseconds |
| `verify_time_ms` | 35–58,553 | nullable integer milliseconds |
| `expire_in` | timestamp strings | rename canonically to `expires_at`; it is not a duration |
@@ -68,7 +68,8 @@ No negative or zero amount/fee/timing values were observed. Source identifiers a
- Each observed category id has one Persian title.
- The quick scan found no merchant-to-category or terminal-to-owner conflict, but exact staging validation remains mandatory because session rows are not contiguous.
- Merchant volume is highly skewed: median merchant has 78 attempts, p95 has 8,915, and the largest has 1,138,592. Unweighted merchant benchmarks and volume-weighted transaction benchmarks answer different questions and must be named separately.
- One terminal/merchant/category and one amount/session relationship are proposed invariants, subject to exact staging validation before constraints are finalized.
- One terminal/merchant/category, amount/session, and fee/session relationship are proposed invariants, subject to exact staging validation before constraints are finalized.
- All 150,450 rows repeating a previously observed session repeated the same `adjusted_fee`; zero fee conflicts were found. The normalized model therefore stores the fee once per session rather than once per attempt.
## Timestamp quality
@@ -110,7 +111,6 @@ Populated `payer_card_key` values are opaque alphanumeric tokens 6–11 characte
- Drop anomalous rows silently
- Replace missing values with plausible defaults
- Treat `adjusted_fee` as ZarinPal's real fee
- Sum the repeated source fee at attempt grain
- Depend on CSV row order
- Claim payer tokens represent verified people