From 4b04f9c58a8ad5e74ef252353c8f1cf52211e501 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 18:30:13 +0330 Subject: [PATCH] docs(api): plan merchant API implementation --- tasks/plan.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 tasks/plan.md diff --git a/tasks/plan.md b/tasks/plan.md new file mode 100644 index 0000000..c23ca8e --- /dev/null +++ b/tasks/plan.md @@ -0,0 +1,170 @@ +# 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 + +```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.