starcoach-hackathon/zarinpal-analytics-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): set analytics audit retention

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 18:18:45 +03:30
parent d133019a14
commit 20c9ba35a6
1 changed files with 6 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/API-SPEC.md
View File

@@ -238,7 +238,7 @@ Limits are enforced before enqueuing or expensive work where possible. User and
Record login success/failure category, logout, analytics start/deduplication, manual retry, SSE authorization/replay reset, detail access, and CSV export requested/completed/rejected/aborted. Export audit records include user id, merchant id, canonical view/filter fingerprint, period id, row count, byte count, result, request id, and timestamps—not exported row values, payer tokens, credentials, raw cursors, filenames from users, or peer data. Record login success/failure category, logout, analytics start/deduplication, manual retry, SSE authorization/replay reset, detail access, and CSV export requested/completed/rejected/aborted. Export audit records include user id, merchant id, canonical view/filter fingerprint, period id, row count, byte count, result, request id, and timestamps—not exported row values, payer tokens, credentials, raw cursors, filenames from users, or peer data.
Minimal demo authentication audit retention remains 30 days. Retention for analytics-access/export audit records is unresolved and must be approved before implementation. Minimal demo authentication audit retention remains 30 days. Analytics-access and CSV-export audit records are retained for 90 days, are accessible only to explicitly authorized backend operators, and are automatically deleted after the retention window. The MVP has no merchant-facing audit endpoint or audit-history UI.
### Metrics and traces ### Metrics and traces
@@ -261,6 +261,7 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section
- Request/rate/export limits reject before expensive work and return Problem Details plus `Retry-After` where applicable. - Request/rate/export limits reject before expensive work and return Problem Details plus `Retry-After` where applicable.
- Problem responses keep HTTP status and `status` aligned, expose stable `code`, and leak no stack, SQL, secret, cursor content, peer identity, or cross-tenant existence. - Problem responses keep HTTP status and `status` aligned, expose stable `code`, and leak no stack, SQL, secret, cursor content, peer identity, or cross-tenant existence.
- Contract/security tests cover schema examples, unknown fields/params, cross-tenant ids and cursors, stale event ids, idempotency races, export filter parity, formula injection, row/byte/deadline caps, and sensitive-field absence. - Contract/security tests cover schema examples, unknown fields/params, cross-tenant ids and cursors, stale event ids, idempotency races, export filter parity, formula injection, row/byte/deadline caps, and sensitive-field absence.
- Analytics-access and CSV-export audit records are visible only to authorized backend operators and are deleted after 90 days.
## Boundaries ## Boundaries
@@ -274,13 +275,13 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section
- CSV export is capped at 100,000 rows, 50 MiB estimated uncompressed output, and a 60-second deadline. - CSV export is capped at 100,000 rows, 50 MiB estimated uncompressed output, and a 60-second deadline.
- CSV export is limited to 3 requests per 10 minutes with burst 1 in independent authenticated-user and merchant buckets. - CSV export is limited to 3 requests per 10 minutes with burst 1 in independent authenticated-user and merchant buckets.
- CSV uses UTF-8 with a BOM, Persian column names separated by normal spaces, and Persian status labels. Numeric cells remain plain calculation-safe numbers and timestamps remain UTC ISO values. - CSV uses UTF-8 with a BOM, Persian column names separated by normal spaces, and Persian status labels. Numeric cells remain plain calculation-safe numbers and timestamps remain UTC ISO values.
- Analytics-access and CSV-export audit records are retained for 90 days and are accessible only to explicitly authorized backend operators; the MVP exposes no merchant audit-history surface.
## Remaining product questions ## Remaining product questions
1. Define retention and operator access policy for analytics-access and CSV-export audit records; Identity's 30-day demo-auth retention does not automatically cover these events. 1. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias.
2. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias. 2. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract.
3. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract. 3. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string.
4. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string.
## Standards references ## Standards references