55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
# ZarinPal Merchant Analytics — Backend
|
|
|
|
Go backend for merchant identity, dataset ingestion, deterministic analytics, authenticated APIs, and later AvalAI integration.
|
|
|
|
Current state: the local MVP implements database migration, streaming dataset import,
|
|
secure demo identity, deterministic dashboard analytics, merchant-scoped details/CSV,
|
|
the authenticated HTTP API, and a Redis-connected worker boundary.
|
|
|
|
## Local development
|
|
|
|
Copy `.env.example` to the ignored `.env`, load its variables in your shell, and run:
|
|
|
|
```text
|
|
go run ./cmd/migrate
|
|
go run ./cmd/importer
|
|
go run ./cmd/admin
|
|
go run ./cmd/worker
|
|
go run ./cmd/api
|
|
```
|
|
|
|
`cmd/admin` idempotently creates or resets `DEMO_USERNAME` using `DEMO_PASSWORD`
|
|
and assigns it to the imported merchant with the largest session population. It
|
|
never prints the password or stores it outside the Argon2id hash. The local API
|
|
uses the `zpa_session` HttpOnly cookie when `COOKIE_SECURE=false`; secure
|
|
deployments use the contract's `__Host-zpa_session` cookie.
|
|
|
|
## Local dataset input
|
|
|
|
Place the provided archive at:
|
|
|
|
```text
|
|
data/incoming/challenge_data.csv.gz
|
|
```
|
|
|
|
The entire `data/incoming/` payload is ignored by Git. The one-time bootstrap importer will read from this location (or an explicitly supplied path), stream the compressed CSV, validate it, and write an import manifest containing the source checksum, schema version, row counts, quality results, and importer revision. It is an administrative bootstrap/recovery command, not a scheduled ingestion job. The hackathon MVP does not mutate payment facts after this import; any future ZarinPal live-write integration is outside this project's current scope. The raw file and resulting PostgreSQL data are not committed.
|
|
|
|
The proposed first-server Docker flow and Bash entrypoint are specified in [`docs/IMPORT-WORKFLOW-SPEC.md`](docs/IMPORT-WORKFLOW-SPEC.md). Implementation is authorized and must follow the dependency order in [`tasks/todo.md`](tasks/todo.md).
|
|
|
|
## Planned runnable boundaries
|
|
|
|
One repository may expose several small `cmd/` entry points while sharing domain packages under `internal/`:
|
|
|
|
- HTTP API
|
|
- dataset importer
|
|
- database migration command
|
|
- HTTP API with authenticated SSE analytics delivery
|
|
- on-demand analytics worker that calculates dashboard sections in parallel and caches versioned results in Redis
|
|
|
|
The approved package-layout and manual-constructor decisions are implemented through the scaffold and provider tasks.
|
|
|
|
## Merchant API contract
|
|
|
|
- [`docs/API-SPEC.md`](docs/API-SPEC.md) defines the reviewable MVP capability, security boundaries, SSE recovery, detail pagination, and CSV-export policy.
|
|
- [`docs/openapi.yaml`](docs/openapi.yaml) is the approved OpenAPI 3.1 interface source of truth for generated frontend types.
|