# Implementation Plan: Merchant Analytics API

- Status: Approved plan — detailed tasks and implementation not yet 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

```text
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.