zarinpal-analytics-backend/tasks/plan.md

Implementation Plan: Merchant Analytics API

• Status: Draft for review — implementation not authorized
• Capability: Merchant API
• Approved contract: docs/API-SPEC.md and docs/openapi.yaml version 1.0.0
• Task list: tasks/todo.md
• Last updated: 2026-08-20

Overview

Implement the approved /api/v1 REST, SSE, paginated-detail, and CSV interfaces as the HTTP adapter of the capability-oriented Go modular monolith. The API layer validates untrusted HTTP input, resolves the merchant from the server-side session, calls approved Identity/Analytics provider contracts, and serializes only OpenAPI-defined output. It does not own metric formulas, normalized payment facts, queue behavior, or deployment configuration.

Preconditions and boundaries

• The approved Identity, Data Foundation, Analytics Engine, API, ADR, metric, and data-guide decisions remain authoritative.
• Architecture and dependency injection are already approved: capability-oriented modular monolith with manual constructor wiring in thin cmd/ composition roots.
• This plan does not authorize go.mod, packages, generated files, dependencies, migrations, containers, or executable code.
• Implementation starts only after the plan and task list are approved and the user separately authorizes implementation.
• The API work depends on implementation-ready provider interfaces from Identity and Analytics. Internal provider signatures may be refined without changing the approved HTTP contract.
• Any OpenAPI generator, validator, router, rate-limiter, or CSV dependency must be version-pinned, checked against official documentation, security-reviewed, and approved before addition.

Architecture decisions

• docs/openapi.yaml remains the public interface source of truth. Generated artifacts are reproducible outputs, never a competing hand-written contract.
• HTTP handlers live in the Merchant API capability and depend on narrow consumer-owned Identity/Analytics interfaces.
• Shared HTTP middleware owns request ids, request-size limits, safe Problem Details serialization, authentication, CSRF/origin enforcement, and no-store/security headers.
• Merchant identity is never accepted from a path, query, header, request body, cursor, or event id. It is resolved from the current server-side session on every protected request.
• JSON detail and CSV export share one canonical filter/authorization/projection policy so export cannot widen the authorized view.
• SSE reauthorizes connection and replay, uses retained opaque event ids, and resets to a current snapshot when replay is unavailable.
• Audit and observability record safe metadata and correlation ids, not payment rows, credentials, tokens, raw cursors, or peer data.

Dependency graph

Approved OpenAPI 1.0.0 + backend scaffold
                |
                v
Contract toolchain and HTTP boundary
                |
      +---------+----------+
      |                    |
      v                    v
Identity adapter      Analytics provider adapters
      |                    |
      v          +---------+---------+
Auth endpoints  Periods   Runs/snapshot
                            |
                     +------+------+
                     v             v
                    SSE       Section retry

Analytics provider adapters
                |
                v
        Detail JSON pagination
                |
                v
             CSV export
                |
                v
     Audit, observability, and full conformance

Ordered task index

Phase 1: Contract and HTTP boundary

• Task 1: Establish the OpenAPI toolchain and conformance harness.
• Task 2: Build the shared HTTP boundary and protected-request middleware.

Checkpoint 1: Boundary readiness

• OpenAPI validation/generation is reproducible from a clean checkout.
• Shared Problem Details, request limits, request ids, cookie authentication, and CSRF/origin behavior pass focused tests.
• Human review confirms no application handler can obtain tenant authority from client input.

Phase 2: Core vertical slices

• Task 3: Implement login, current-session, and logout endpoints.
• Task 4: Implement approved reporting-period discovery.
• Task 5: Implement analytics-run start and snapshot retrieval.

Checkpoint 2: Core API flow

• A merchant can authenticate, obtain an approved period, start one deduplicated run, and read its snapshot.
• Cross-tenant ids are indistinguishable from missing ids.
• OpenAPI examples and focused integration tests pass.

Phase 3: Partial delivery and recovery

• Task 6: Implement authenticated SSE delivery and recovery.
• Task 7: Implement exhausted-section manual retry.

Checkpoint 3: Asynchronous behavior

• Independent section completion, heartbeat, replay, snapshot reset, revocation, and sibling-failure isolation pass integration tests.
• Existing start/retry/SSE limits reject before queue or stream work.

Phase 4: Evidence and export

• Task 8: Implement cursor-paginated session detail views.
• Task 9: Implement safeguarded Persian CSV export.

Checkpoint 4: Reconciliation and data boundary

• Each detail view reconciles with its approved aggregate.
• JSON and CSV use identical tenant/filter predicates and approved field projections.
• Payer tokens, credentials, peer rows, and internal keys are absent from responses, exports, logs, and traces.

Phase 5: Operational hardening

• Task 10: Publish the stable API problem-type catalogue.
• Task 11: Add API audit and observability instrumentation.
• Task 12: Complete contract, security, race, and performance verification.

Checkpoint 5: Implementation-ready completion

• All OpenAPI operations and documented status codes have passing contract tests.
• go test, race detection, go vet, golangci-lint, and govulncheck pass using repository-approved commands.
• Runtime checks cover tenant isolation, session revocation, SSE recovery, cursor integrity, export caps, formula neutralization, and sensitive-field absence.
• Documentation matches runtime behavior and the full project Definition of Done is satisfied.
• Human review approves completion before merge or deployment.

Verification strategy

Per task

• Write tests that fail before the behavior exists and pass after it is implemented.
• Run focused package tests for the changed slice.
• Validate docs/openapi.yaml and regenerate/check generated artifacts without diff.
• Run go test ./... and go vet ./... once the Go scaffold exists.
• Inspect the staged diff and scan it for secrets and forbidden data fields before every commit.

At checkpoints

• Run go test -race ./..., golangci-lint run, and govulncheck ./... after the required tools are pinned by the approved scaffold/tooling task.
• Exercise the actual HTTP server against PostgreSQL and Redis test dependencies for authentication, tenant isolation, analytics lifecycle, SSE, pagination, and export behavior.
• Run OpenAPI request/response conformance tests for all examples, errors, media types, headers, and security requirements.
• Verify query plans and bounded resource behavior for detail/export paths with representative merchant volumes.

Parallelization

• Tasks 3 and 4 may proceed in parallel only after Tasks 1–2 stabilize shared HTTP types and middleware.
• Task 6 and the read-only parts of Task 8 may proceed in parallel after Task 5 and the Analytics provider interfaces stabilize.
• Task 9 is sequential after Task 8 because CSV must reuse its authorization, filters, and projection.
• Tasks 10–11 may proceed alongside later feature slices once stable error codes and audit events exist.
• Task 12 is sequential after all feature slices and instrumentation are complete.

Risks and mitigations

Risk	Impact	Mitigation
Generated types drift from OpenAPI	High	Reproducible pinned generation plus clean-diff and contract-test gates
Tenant scope leaks through ids/cursors/replay	Critical	Session-derived merchant context, ownership checks in providers, identical not-found policy, adversarial integration tests
SSE behavior differs across proxy/browser boundaries	High	Test event framing, heartbeat, buffering headers, replay, reset, disconnect, and revocation through the deployed-style proxy path
CSV widens detail access or leaks formulas/sensitive data	Critical	Reuse one canonical detail query/projection, preflight limits, formula neutralization, allowlist tests, abort-aware audit result
Retry/idempotency races duplicate jobs	High	Atomic intent claim, canonical request hash, current-run deduplication, concurrency tests
Large merchant queries exhaust API resources	High	Cursor pagination, fixed filters, timeouts, export preflight caps, measured plans, bounded streaming
Error details expose internals	Medium	Central RFC 9457 mapper with stable allowlisted codes and negative leak tests
Pre-1.0 queue behavior changes	High	Preserve approved Asynq v0.26.0 pin and run retry/deduplication/recovery integration tests before any upgrade

Implementation gates, not product questions

• Select and approve exact pinned OpenAPI generation/validation tooling before adding dependencies.
• Confirm repository-wide build/test/lint command wrappers when the separately authorized Go scaffold is created.
• Confirm the hosting mechanism that makes https://zarinpal.amiirkhl.ir/docs/errors/{error-slug} dereferenceable; the URI namespace and content responsibility are already approved.

Product questions

None.