zarinpal-analytics-backend/tasks/todo.md

Merchant Analytics API Task List

• Status: Draft for review — implementation not authorized
• Plan: tasks/plan.md
• Contract: docs/API-SPEC.md and docs/openapi.yaml version 1.0.0

Every task must satisfy its acceptance criteria and the standing Definition of Done. File lists are expected blast radii, not permission to modify unrelated files.

Task 1: Establish the OpenAPI toolchain and conformance harness

Description: Select, approve, and pin the Go OpenAPI generation/validation tooling; make contract validation and generated-artifact drift checks reproducible from a clean checkout.

Acceptance criteria:

• One approved pinned toolchain validates OpenAPI 3.1 and produces only the intended server/types artifacts.
• Generated artifacts contain no hand-edited business logic and regenerate with a clean Git diff.
• Stable operationId values, schemas, media types, and security requirements are covered by a contract test harness.

Verification:

• Run the documented OpenAPI validate/generate/check commands from a clean checkout.
• Run focused generator/conformance tests and confirm a deliberate contract mismatch fails.
• Review generated and lockfile/checksum diffs; approve any new dependency before installation.

Dependencies: Approved implementation authorization and separately approved Go scaffold.

Files likely touched:

• go.mod
• go.sum
• internal/api/contract/
• internal/api/contract_test.go
• approved command/tool configuration

Estimated scope: Medium (3–5 files/artifact groups)

Task 2: Build the shared HTTP boundary and protected-request middleware

Description: Create the API server boundary for /api/v1, central Problem Details mapping, request ids, 16 KiB body/8 KiB target limits, no-store/security headers, session resolution, and CSRF/origin enforcement.

Acceptance criteria:

• All protected handlers receive merchant/user context only from a verified server-side session.
• Boundary failures use the approved RFC 9457 schema/code/status mapping without internal details.
• Request limits, unknown fields/parameters, CSRF/origin checks, and no-store/security headers behave as specified.

Verification:

• Focused middleware tests cover missing/expired/revoked sessions, malformed input, size limits, request ids, CSRF, and origin/fetch metadata.
• Cross-tenant client inputs cannot create or replace merchant context.
• go test ./... and go vet ./... pass.

Dependencies: Task 1 and approved Identity session-verification interface.

Files likely touched:

• internal/api/http/server.go
• internal/api/http/problem.go
• internal/api/http/middleware.go
• internal/api/http/middleware_test.go

Estimated scope: Medium (4 files)

Checkpoint 1: Boundary readiness

• Tasks 1–2 acceptance criteria pass.
• OpenAPI generation is reproducible with a clean diff.
• Human review confirms the tenant and error boundaries before feature handlers begin.

Task 3: Implement authentication session endpoints

Description: Implement login, current-session, and logout as one vertical slice through the approved Identity provider, including secure cookie and generic-failure behavior.

Acceptance criteria:

• Login creates a revocable session and sets only the approved __Host-zpa_session cookie attributes.
• Current-session JSON matches OpenAPI and exposes a session-bound CSRF token but no authentication token.
• Logout revokes server state before clearing the cookie; expected credential failures remain indistinguishable and throttled.

Verification:

• Integration tests cover success, enumeration resistance, cookie flags, rotation, expiry, revocation, throttling, CSRF, and dependency failure.
• OpenAPI conformance tests cover all auth statuses and headers.
• go test -race ./... passes for affected packages.

Dependencies: Task 2 and approved Identity provider implementation.

Files likely touched:

• internal/api/http/auth_handler.go
• internal/api/http/auth_handler_test.go
• internal/api/identity.go
• cmd/api/main.go

Estimated scope: Medium (4 files)

Task 4: Implement approved reporting-period discovery

Description: Return only allowlisted day/week/Jalali-month/Persian-season periods with exact UTC/Tehran boundaries, ready Persian labels, and the approved default.

Acceptance criteria:

• Period responses match OpenAPI and use backend-calculated half-open boundaries.
• Iranian weeks start Saturday; default selection is the latest complete Jalali month containing source data.
• Unknown parameters/types are rejected and arbitrary date ranges are impossible.

Verification:

• Table tests cover all period types, month/year boundaries, Saturday–Friday weeks, empty source ranges, and timezone independence.
• Integration tests reconcile returned ids/boundaries with calendar_dates.
• OpenAPI examples and go test ./... pass.

Dependencies: Task 2 and approved calendar/period provider implementation.

Files likely touched:

• internal/api/http/period_handler.go
• internal/api/http/period_handler_test.go
• internal/api/periods.go

Estimated scope: Medium (3 files)

Task 5: Implement analytics-run start and snapshot retrieval

Description: Implement idempotent run creation/current-run resolution and tenant-scoped snapshot retrieval for all four sections.

Acceptance criteria:

• Same intent/key replays safely, key/body conflicts fail, and equivalent concurrent starts resolve one current run.
• Run snapshots serialize every section state/result exactly as OpenAPI defines.
• Missing and cross-tenant run ids return the same 404 RESOURCE_NOT_FOUND response.

Verification:

• Concurrency tests cover atomic idempotency claim, in-flight duplicates, current revisions, and no duplicate jobs.
• Contract tests cover 200, 202, 401, 403, 404, 422, 429, and dependency failures.
• Integration tests assert that rejected/limited requests enqueue no work.

Dependencies: Tasks 1–2 and approved Analytics run provider implementation.

Files likely touched:

• internal/api/http/run_handler.go
• internal/api/http/run_handler_test.go
• internal/api/analytics.go
• internal/api/idempotency.go

Estimated scope: Medium (4 files)

Checkpoint 2: Core API flow

• Tasks 3–5 acceptance criteria pass.
• Authenticated merchant flow works through the actual HTTP server and test dependencies.
• Cross-tenant and idempotency adversarial tests pass.
• Human review approves the core flow before streaming/detail work.

Task 6: Implement authenticated SSE delivery and recovery

Description: Stream typed run/section events with 15-second heartbeats, one-hour authorized replay, snapshot reset, and session-aware disconnect/reconnect behavior.

Acceptance criteria:

• Event framing, ids, names, and JSON data match the approved SSE schemas and UTF-8 media type.
• Retained ids replay only later authorized events; unavailable ids reset with run.snapshot and never disclose another tenant.
• Session expiry/revocation, connection limits, and completed-run closure behave as specified.

Verification:

• Integration tests cover ordered partial readiness, failure isolation, suppression, heartbeat timing, replay, reset, disconnect, revocation, and user/merchant connection limits.
• Proxy-style tests assert no buffering/compression and required stream headers.
• Race tests cover concurrent publish/replay/disconnect paths.

Dependencies: Task 5 and approved Analytics event provider implementation.

Files likely touched:

• internal/api/http/sse_handler.go
• internal/api/http/sse_handler_test.go
• internal/api/events.go
• internal/api/events_test.go

Estimated scope: Medium (4 files)

Task 7: Implement exhausted-section manual retry

Description: Add the idempotent retry-attempt subresource for one exhausted failed section without disturbing ready siblings.

Acceptance criteria:

• Only an exhausted, retryable failed section for the current run/revisions is accepted.
• Retry idempotency and independent user/merchant throttles prevent duplicate work.
• Ready siblings remain unchanged and stale/cross-tenant requests fail safely.

Verification:

• Tests cover retryable/non-retryable states, duplicate keys, stale revisions, throttling, cross-tenant ids, and no sibling restart.
• Rejected retries enqueue no work.
• OpenAPI conformance and go test -race ./... pass.

Dependencies: Tasks 5–6.

Files likely touched:

• internal/api/http/retry_handler.go
• internal/api/http/retry_handler_test.go
• internal/api/retry.go

Estimated scope: Medium (3 files)

Checkpoint 3: Asynchronous behavior

• Tasks 6–7 acceptance criteria pass.
• SSE and retry runtime checks pass through the actual queue/cache test boundary.
• Human review confirms recovery and rate-limit behavior.

Task 8: Implement cursor-paginated session detail views

Description: Implement the three approved detail views with deterministic ordering, opaque bound cursors, default 25/maximum 100 rows, and a strict field allowlist.

Acceptance criteria:

• UNVERIFIED_PAID, FAILED, and RETRIED filters match catalogue definitions and reconcile to aggregates.
• Cursors bind tenant, canonical filters, ordering, expiry, and last row; invalid reuse returns generic INVALID_CURSOR.
• Detail rows expose only approved fields and the tenant-scoped opaque terminal reference.

Verification:

• Tests cover page boundaries, duplicate timestamps, cursor tampering/expiry/filter change/cross-tenant reuse, limits, and empty results.
• Integration queries reconcile representative merchants and approved periods.
• Sensitive-field absence and measured query-plan checks pass.

Dependencies: Tasks 2 and 4 plus approved Analytics detail provider implementation.

Files likely touched:

• internal/api/http/detail_handler.go
• internal/api/http/detail_handler_test.go
• internal/api/details.go
• internal/api/cursor.go
• internal/api/cursor_test.go

Estimated scope: Medium (5 files)

Task 9: Implement safeguarded Persian CSV export

Description: Stream the same authorized detail predicate/projection as Persian CSV with BOM, Persian spaced headers/statuses, machine-safe numeric/ISO values, formula neutralization, and approved caps.

Acceptance criteria:

• CSV and JSON share one canonical tenant/filter/projection policy; CSV adds no unavailable field.
• Output matches the approved encoding, headers, labels, quoting, disposition, no-store, and nosniff contract.
• Preflight rejects over 100,000 rows/50 MiB, generation ends within 60 seconds, throttling applies, and interrupted streams are audited as incomplete.

Verification:

• Golden tests cover Persian output, BOM, CRLF, quotes/newlines, all status mappings, and stable headers with spaces.
• Security tests cover =, +, -, @, tab, CR, LF formula prefixes and forbidden-field absence.
• Integration tests cover filter parity, snapshot consistency, caps, deadline, disconnect, throttle, and content headers.

Dependencies: Task 8.

Files likely touched:

• internal/api/http/export_handler.go
• internal/api/http/export_handler_test.go
• internal/api/export.go
• internal/api/export_test.go

Estimated scope: Medium (4 files)

Checkpoint 4: Reconciliation and data boundary

• Tasks 8–9 acceptance criteria pass.
• Detail/CSV reconciliation and sensitive-data negative tests pass.
• Export resource limits hold under representative merchant volume.
• Human review approves the merchant evidence boundary.

Task 10: Publish the stable API problem-type catalogue

Description: Document every stable application error code and make each approved https://zarinpal.amiirkhl.ir/docs/errors/{error-slug} URI resolve to safe human-readable guidance.

Acceptance criteria:

• Every OpenAPI problem code maps to one stable slug, title, status, meaning, safe resolution guidance, and retry rule.
• Published pages expose no internal topology, SQL, stack, secret, tenant existence, or security-control detail useful for abuse.
• Contract tests fail when a returned problem type/code lacks catalogue documentation.

Verification:

• Link checks confirm every production type URI resolves successfully.
• OpenAPI and catalogue mapping tests pass with no duplicate slug/code.
• Security review approves public wording.

Dependencies: Tasks 2–9 for the final error-code set; hosting mechanism approval.

Files likely touched:

• docs/ERROR-CATALOGUE.md
• error-page source/template location approved by the hosting plan
• internal/api/http/problem_catalogue_test.go

Estimated scope: Medium (2–3 files/artifact groups)

Task 11: Add API audit and observability instrumentation

Description: Instrument the approved audit events, metrics, logs, and traces with bounded-cardinality safe metadata and 90-day analytics/export-audit retention.

Acceptance criteria:

• Required auth/run/SSE/detail/export audit outcomes and operational metrics are emitted with correlation ids.
• Only authorized backend operators can access analytics/export audit records; automatic deletion occurs after 90 days.
• Telemetry excludes credentials, tokens, raw cursors/filters, payment rows, payer tokens, peer data, and high-cardinality sensitive labels.

Verification:

• Tests assert required event/metric emission for success, rejection, failure, timeout, and interrupted export.
• Negative leak tests inspect structured logs, traces, and audit records.
• Retention/access-control tests pass using an accelerated test clock.

Dependencies: Tasks 3–10 and the approved audit/observability adapters.

Files likely touched:

• internal/api/observability.go
• internal/api/audit.go
• internal/api/observability_test.go
• internal/api/audit_test.go

Estimated scope: Medium (4 files)

Task 12: Complete contract, security, race, and performance verification

Description: Run and close the full implementation Definition of Done across all API operations and critical failure/abuse paths.

Acceptance criteria:

• Every OpenAPI operation/status/media type/header/security requirement has automated contract coverage.
• Tenant isolation, session/CSRF, idempotency, SSE, cursor, export, audit, and sensitive-field abuse suites pass.
• Representative detail/export query plans and resource bounds meet approved behavior with no unreviewed exception.

Verification:

• Run go test ./..., go test -race ./..., go vet ./..., golangci-lint run, and govulncheck ./....
• Run reproducible OpenAPI validation/generation and confirm a clean Git diff.
• Exercise critical merchant flows end to end through the deployed-style proxy/test environment.

Dependencies: Tasks 1–11.

Files likely touched:

• API contract/integration test packages
• approved test fixtures containing no sensitive source data
• API runbook/documentation corrections if verification finds drift

Estimated scope: Medium (3–5 files/artifact groups)

Checkpoint 5: Complete

• Tasks 1–12 and every checkpoint pass.
• Full project Definition of Done is satisfied.
• No unrelated frontend, deployment, physical-schema, ERD, or raw-data changes are included.
• Human review approves completion before merge or deployment.