commit e4b87e110dfc6471d877d3db37869243ac7476b0 Author: Amirhossein Khalili Date: Thu Aug 20 12:36:29 2026 +0330 docs: establish Go backend repository rules diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a1f18dc --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +# Raw/local data: keep README only +/data/incoming/* +!/data/incoming/README.md + +# Environment and secrets +.env +.env.* +!.env.example + +# Go outputs and local tooling +/bin/ +/dist/ +/coverage/ +*.test +*.out +/vendor/ +.idea/ +.vscode/ + diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..5e91807 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,4 @@ +# Compatibility Pointer + +The canonical agent instructions are in [`AGENTS.md`](AGENTS.md). Do not duplicate or diverge from them here. + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7dc95d0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# Backend Agent Operating Contract + +## Phase gate + +This repository is in specification mode. Do not create `go.mod`, application packages, migrations, containers, or executable code until the relevant capability spec is approved. + +For every Go-related task, always invoke and follow the `golang-how-to` skill, then the secondary Go skills it routes to. Before creating the Go project layout, ask the user to approve the architecture style and dependency-injection approach in that order. + +## Product invariants + +- The backend is the authority for authentication, authorization, tenant isolation, metric definitions, and data provenance. +- Every merchant-scoped query derives merchant identity from the authenticated server-side session; never trust a client-supplied merchant identifier as authorization. +- Cross-merchant results are minimum-cohort, anonymized aggregates only. +- Use integer minor currency units or an explicitly documented fixed-precision representation; never floating point for money. +- Preserve source timestamps and document their timezone assumptions. Normalize operational timestamps consistently. +- Raw imports are immutable inputs; corrections are new import versions, not silent mutation. +- `adjusted_fee` is obfuscated and may be used only for relative analysis. + +## Go baseline after approval + +- Keep `main` packages thin under `cmd/`; business code lives under `internal/`. +- Use explicit constructors; avoid `init()` side effects and mutable globals. +- Configuration comes from validated environment variables. Logs go to stdout as structured records without credentials, card keys, or sensitive payloads. +- Propagate `context.Context`; bound external calls, queues, batches, and database pools. +- Use parameterized queries and transactions with explicit boundaries. Stream/bulk-load the multi-million-row input instead of holding it in memory. +- Passwords use an approved adaptive hash (Argon2id or bcrypt per the approved auth spec); sessions use secure, HttpOnly cookies and server-side revocation. +- Required verification includes unit/integration tests, race detection where applicable, `go vet`, `golangci-lint`, `govulncheck`, and migration/import tests. + +## Git and documentation + +- Use atomic Conventional/Commitizen commits. +- Track specs, ERD/schema definitions, migrations, importer code, validation rules, manifests/templates, and runbooks. +- Ignore raw CSV archives, database volumes/dumps, credentials, and generated runtime data. +- Changes to a metric, API, schema, authorization rule, or AI data boundary require the corresponding spec/ADR update. + +## AI boundary (post-MVP) + +AvalAI is accessed only from the backend using a server-held API key. Prefer the simplest bounded LLM call/workflow that satisfies the approved use case. Send minimized, sanitized aggregates with explicit budgets/timeouts; persist trace metadata and deterministic inputs, not unnecessary sensitive prompts. AI output is advisory and must cite underlying deterministic metrics. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..0b91369 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# ZarinPal Merchant Analytics — Backend + +Go backend for merchant identity, dataset ingestion, deterministic analytics, authenticated APIs, and later AvalAI integration. + +Current state: specification bootstrap only. There is intentionally no Go module or application scaffold yet because the architecture and dependency-injection choices still require approval. + +## Local dataset input + +Place the provided archive at: + +```text +data/incoming/challenge_data.csv.gz +``` + +The entire `data/incoming/` payload is ignored by Git. Future import tooling will read from this location (or an explicitly supplied path), stream the compressed CSV, validate it, and write a tracked import manifest containing the source checksum, schema version, row counts, quality results, and importer revision. The raw file and resulting PostgreSQL data are not committed. + +## 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 +- analytics refresh/background job, only if the approved spec requires one + +The exact package layout is deferred until the Go architecture and DI decisions are approved. + diff --git a/data/incoming/README.md b/data/incoming/README.md new file mode 100644 index 0000000..09d32a6 --- /dev/null +++ b/data/incoming/README.md @@ -0,0 +1,16 @@ +# Incoming dataset + +Copy the challenge dataset to this directory as `challenge_data.csv.gz` before running the future importer. The archive is intentionally ignored by Git. + +Expected source columns: + +```text +session_key, try_seq, terminal_key, merchant_key, category_id, +category_title, amount, adjusted_fee, session_status, try_status, +switch_response_code, psp_code, issuer_bank_code, payer_card_key, +verify_type, init_time_ms, verify_time_ms, created_at, try_created_at, +verified_at, settled_at, expire_in +``` + +Do not add merchant passwords or other secrets to this directory. Demo credentials will be generated/seeding inputs managed separately through secure environment or one-off administrative workflows. +