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

docs: record production analytics decisions

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 13:59:36 +03:30
parent 5e83da4a19
commit f472ad5b1d
5 changed files with 108 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/PHYSICAL-SCHEMA-PROPOSAL.md
View File

@@ -51,6 +51,8 @@ Synthetic profile fields carry an explicit `profile_is_synthetic` marker. Creden
`adjusted_fee` uses fixed precision and is labeled as an obfuscated relative value. The physical precision is finalized from exact decimal profiling before migration approval.
Both fact tables distinguish `bootstrap` from `zarinpal_live` origin. Bootstrap rows reference an import run; live rows do not invent one. Live creation/update metadata forms the incremental analytics watermark contract, including status changes to an existing session.
### Rebuildable analytics projections
| Table family | Grain | Purpose |
@@ -62,6 +64,8 @@ Synthetic profile fields carry an explicit `profile_is_synthetic` marker. Creden
Projection names/columns are finalized by the analytics metric catalogue. Avoid a generic key/value metrics table because it weakens types, constraints, and discoverability.
Projection metadata records source watermark, calculation version, calculated time, and status. An incremental refresh runs at least every 15 minutes; a nightly reconciliation checks/rebuilds an authoritative window and advances freshness only after successful atomic publication.
## Initial index policy
- Unique indexes implement source identities and natural relationship constraints.
@@ -80,5 +84,4 @@ Projection names/columns are finalized by the analytics metric catalogue. Avoid
## Production population boundary
After the one-time CSV bootstrap, ZarinPal—not this project—writes future production payment records to PostgreSQL. The exact contract is still open: ZarinPal may write this normalized schema directly or expose an existing authoritative schema for read-only analytics. This project will not invent recurring ETL until that boundary is answered.
After the one-time CSV bootstrap, ZarinPal—not this project—writes future production payment records directly to the normalized PostgreSQL session/attempt tables. This project owns the schema/migration and analytics contract but not ZarinPal's write workflow. Compatibility, required fields, source origin, and creation/update watermarks are versioned interfaces; recurring CSV ETL is prohibited.