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

docs(spec): align immutable dataset operations

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 19:00:13 +03:30
parent 480fd207c7
commit d05a1ad276
2 changed files with 4 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
AGENTS.md
View File

@@ -28,7 +28,7 @@ This repository owns deployment concerns only. Backend and frontend directories
## Operational baseline ## Operational baseline
- Everything runs through Docker, Docker Compose, Bash scripts, and environment files/templates. - Everything runs through Docker, Docker Compose, Bash scripts, and environment files/templates.
- The CSV-to-PostgreSQL workflow is a one-time administrative bootstrap/recovery command, never a scheduled ingestion service. ZarinPal owns future production payment writes. - The CSV-to-PostgreSQL workflow is a one-time administrative bootstrap/recovery command, never a scheduled ingestion service. MVP payment facts remain immutable after that import; future live writes require a new approved integration contract.
- An idempotent authenticated start request enqueues overview, payment-performance, fees, and peer-comparison jobs for bounded parallel calculation by a separate on-demand Go worker. Redis caches/coordinates each section for 30 days, and a separate authenticated SSE request streams partial completion. This worker is event-driven, never scheduled. - An idempotent authenticated start request enqueues overview, payment-performance, fees, and peer-comparison jobs for bounded parallel calculation by a separate on-demand Go worker. Redis caches/coordinates each section for 30 days, and a separate authenticated SSE request streams partial completion. This worker is event-driven, never scheduled.
- The worker uses Asynq pinned to `v0.26.0`. Asynq is pre-`v1.0.0`; never use a floating dependency or upgrade it without compatibility review and passing queue/retry/recovery tests. - The worker uses Asynq pinned to `v0.26.0`. Asynq is pre-`v1.0.0`; never use a floating dependency or upgrade it without compatibility review and passing queue/retry/recovery tests.
- Each section attempt has a 60-second timeout and at most two automatic retries for transient failures using exponential backoff with jitter. Deterministic failures are not retried. - Each section attempt has a 60-second timeout and at most two automatic retries for transient failures using exponential backoff with jitter. Deterministic failures are not retried.

6
CAPABILITY-MAP.md
View File

@@ -13,9 +13,9 @@ The hackathon demo will seed one account per merchant. Where merchant profile fi
| Order | Capability | Responsibility | Depends on | MVP | | Order | Capability | Responsibility | Depends on | MVP |
|---:|---|---|---|:---:| |---:|---|---|---|:---:|
| 1 | Data foundation | PostgreSQL model, one-time CSV bootstrap, provenance, validation, quality reporting, synthetic merchant profiles; future source writes are owned by ZarinPal | — | Yes | | 1 | Data foundation | PostgreSQL model, one-time CSV bootstrap, provenance, validation, quality reporting, synthetic merchant profiles; MVP payment facts are immutable afterward | — | Yes |
| 2 | Identity and access | Replaceable demo credential adapter, sessions, tenant isolation, demo account seeding; future ZarinPal SSO is external | Data foundation | Yes | | 2 | Identity and access | Replaceable demo credential adapter, sessions, tenant isolation, demo account seeding; future ZarinPal SSO is external | Data foundation | Yes |
| 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, bounded parallel on-demand section jobs, 30-day Redis cache, PostgreSQL revision invalidation | Data foundation | Yes | | 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, bounded parallel on-demand section jobs, and a 30-day Redis cache namespaced by the sole completed immutable dataset snapshot | Data foundation | Yes |
| 4 | Merchant API | Stable authenticated interfaces and tenant-scoped SSE for partial analytics delivery | Identity and access, analytics engine | Yes | | 4 | Merchant API | Stable authenticated interfaces and tenant-scoped SSE for partial analytics delivery | Identity and access, analytics engine | Yes |
| 5 | Merchant dashboard | Persian RTL dashboard, responsive navigation, accessible charts/tables and explanations | Merchant API | Yes | | 5 | Merchant dashboard | Persian RTL dashboard, responsive navigation, accessible charts/tables and explanations | Merchant API | Yes |
| 6 | AI assistance | AvalAI-backed explanation/recommendation workflow over sanitized aggregates | Analytics engine, merchant API | No | | 6 | AI assistance | AvalAI-backed explanation/recommendation workflow over sanitized aggregates | Analytics engine, merchant API | No |
@@ -51,7 +51,7 @@ Build sequence: data foundation → identity and analytics → API → dashboard
9. `Paid` and `Verified` are both successful bank payments; `Paid` still requires merchant verification and `Verified` is finalized. Paid-volume and recovery metrics include both while verification metrics keep them separate. 9. `Paid` and `Verified` are both successful bank payments; `Paid` still requires merchant verification and `Verified` is finalized. Paid-volume and recovery metrics include both while verification metrics keep them separate.
10. Merchant fees are real Rial amounts stored/summed once per session; repeated attempt rows never multiply a fee. 10. Merchant fees are real Rial amounts stored/summed once per session; repeated attempt rows never multiply a fee.
11. MVP reporting periods are limited to daily, Saturday–Friday weekly, Jalali-month, and Persian-season views with consistent `Asia/Tehran` boundaries across database, API, and frontend. 11. MVP reporting periods are limited to daily, Saturday–Friday weekly, Jalali-month, and Persian-season views with consistent `Asia/Tehran` boundaries across database, API, and frontend.
12. An idempotent start request enqueues overview, payment-performance, fees, and peer-comparison sections for bounded parallel calculation by a separate Go worker; Redis caches each typed section for 30 days under merchant/cohort and metric-definition revisions. 12. An idempotent start request enqueues overview, payment-performance, fees, and peer-comparison sections for bounded parallel calculation by a separate Go worker; Redis caches each typed section for 30 days under the merchant, completed dataset snapshot, and metric-definition version.
13. A separate authenticated SSE request exposes each section as it becomes ready. Redis and the on-demand worker remain private, and Redis is never a source of truth or backup target. 13. A separate authenticated SSE request exposes each section as it becomes ready. Redis and the on-demand worker remain private, and Redis is never a source of truth or backup target.
14. Each section attempt is limited to 60 seconds and at most two transient retries with exponential backoff/jitter; deterministic errors fail immediately. 14. Each section attempt is limited to 60 seconds and at most two transient retries with exponential backoff/jitter; deterministic errors fail immediately.
15. The worker pins pre-1.0 Asynq `v0.26.0`, runs at 16 jobs globally and 4/merchant by default, and changes require reviewed dependency/load evidence. 15. The worker pins pre-1.0 Asynq `v0.26.0`, runs at 16 jobs globally and 4/merchant by default, and changes require reviewed dependency/load evidence.