363 lines
15 KiB
Markdown
363 lines
15 KiB
Markdown
# 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.
|