54 lines
4.7 KiB
Markdown
54 lines
4.7 KiB
Markdown
# Cross-Repository Specification and Plan Review
|
||
|
||
- Status: Ready for stakeholder review — implementation not authorized
|
||
- Date: 2026-08-20
|
||
- Scope: `zarinpal-analytics-backend`, `zarinpal-analytics-frontend`, and `zarinpal-analytics-deployment`
|
||
|
||
## Outcome
|
||
|
||
The approved product, data, analytics, identity, API, UX, and operations specifications are sufficiently resolved to plan implementation. No application code, migrations, containers, executable scripts, dependency manifests, or generated artifacts are authorized by this review.
|
||
|
||
## Confirmed shared contracts
|
||
|
||
| Concern | Agreed contract | Owning repository |
|
||
|---|---|---|
|
||
| Dataset | One pinned archive is imported once into normalized PostgreSQL tables; raw challenge data is ignored by Git | Backend |
|
||
| Data lifetime | MVP payment facts are immutable after the sole completed import; future replacement or live writes require a new specification | Backend |
|
||
| Import activation | On the first server release only: start data services, migrate, import and reconcile, then activate public services | Deployment |
|
||
| Tenant authority | Merchant context comes only from the revocable server-side demo session, never from client-supplied merchant identifiers | Backend |
|
||
| Analytics | Day, Saturday–Friday week, Jalali month, and Persian season metrics follow catalogue `0.4.0` | Backend |
|
||
| Async delivery | Four independently completing sections use Redis/Asynq and authenticated SSE; Asynq is pinned pre-1.0 at `v0.26.0` | Backend |
|
||
| Cache identity | Redis keys include merchant, sole completed dataset snapshot, metric version, period, and section; PostgreSQL has no MVP invalidation triggers | Backend |
|
||
| Payment states | `Paid` means bank payment succeeded but merchant verification did not; `Verified` completed both steps; money success includes both where specified | Backend |
|
||
| Detail/export | Authorized details reconcile to aggregates; selected detail views support bounded Persian CSV export with the shared projection | Backend / Frontend |
|
||
| API | REST/SSE contract is approved as OpenAPI `1.0.0`; frontend transport types will be generated from the pinned artifact | Backend / Frontend |
|
||
| UI | SvelteKit 2, Svelte 5, TypeScript, Tailwind, RTL Persian digits, IRANYekanX Pro, responsive light/dark ZarinPal-inspired system | Frontend |
|
||
| Deployment | Three repositories, Docker Compose, Nginx, TLS, environment files, guarded operations, encrypted PostgreSQL backup/restore | Deployment |
|
||
|
||
## Implementation plan map
|
||
|
||
1. Backend foundation: Go workspace, normalized Ent/Atlas schema, guarded one-time importer, validation/promotion/recovery, and deterministic demo accounts.
|
||
2. Backend services: bounded demo authentication, metric query kernel, Redis/Asynq orchestration, details, exports, and provider integration.
|
||
3. Backend HTTP surface: OpenAPI conformance, middleware, auth/period/run/SSE/retry/detail/CSV endpoints, audit, and hardening.
|
||
4. Frontend: foundation and tokens, generated transport, shell/auth, dashboard sections, partial SSE states, detail/export workflows, responsive/accessibility/theme verification.
|
||
5. Deployment: adapt Qlockify's Compose/Nginx/environment/manual-release/backup operations, integrate first-start ordering, verify locally with safe placeholders, then perform the separately authorized server release with real runtime values.
|
||
|
||
Backend provider work and frontend visual-system work can proceed in parallel after separate implementation authorization. Deployment scaffolding can also proceed in parallel once command/build contracts are stable; production bootstrap and cutover remain sequential gates.
|
||
|
||
## Deferred interface details (not planning blockers)
|
||
|
||
These are build-time choices, not unresolved product requirements:
|
||
|
||
- exact pinned OpenAPI generation/validation tools and repository command wrappers;
|
||
- exact frontend/backend build and health commands after their scaffolds exist (frontend history fallback is already restricted to non-API routes);
|
||
- exact backend/frontend command and environment-variable names after their scaffolds exist;
|
||
- the hosting path for human-readable API problem pages.
|
||
|
||
Server IP/DNS state, Git credentials, ACME email, ParsPack values, operator identity, and alert destinations are runtime inputs supplied when their operations are performed. They do not block implementation planning or local placeholder-based validation. Deployment uses no CI/CD pipeline, runner, or registry.
|
||
|
||
No secrets, raw dataset, generated database, credentials, certificates, backups, or runtime volumes may be committed.
|
||
|
||
## Authorization gate
|
||
|
||
Approval of these plans permits task tracking only. Implementation starts only after the user sends a separate explicit instruction to implement. Remote pushes remain forbidden until the user separately requests a push.
|