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

fix: expose complete dataset period catalog

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 22:28:07 +03:30
parent d6de48fd15
commit 6523e90a03
8 changed files with 140 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/ANALYTICS-SPEC.md
View File

@@ -167,7 +167,7 @@ Every section uses a versioned typed contract and has independent `queued`, `cal
- Normalized PostgreSQL facts are authoritative; Redis is a 30-day disposable analytics cache.
- Four sections calculate lazily and in bounded parallel, with partial authenticated SSE delivery.
- Reporting covers day, Iranian week, Jalali month, and Persian season only.
- Reporting covers every complete day, Iranian week, Jalali month, and Persian season inside the imported dataset's local-date coverage; arbitrary client-computed ranges remain disallowed.
- Peer comparison uses same-category merchant-weighted medians and direction-aware percentiles with the approved suppression threshold.
- Payment lifecycle, retry, timing, and real-fee definitions follow `METRIC-CATALOGUE.md` and ADR 0013.
- Asynq `v0.26.0` is pinned and acknowledged as pre-1.0; jobs have bounded concurrency, timeouts, rate limits, and exponential-backoff retries.

2
docs/API-SPEC.md
View File

@@ -79,7 +79,7 @@ Clients select one allowlisted `periodId` returned by `GET /analytics/periods`;
- `timezone: Asia/Tehran` and `jalaliLabelFa`, ready for display;
- `isComplete` and `isDefault` flags.
The default is the latest complete Jalali month containing source data. Weekly periods start Saturday at `00:00` and end at the following Saturday `00:00` in Tehran. The optional `periodType` query is allowlisted and filters the returned descriptors. The server rejects stale or fabricated period ids and invalid period types instead of accepting client-computed dates.
The catalog contains every complete day, Saturday–Friday week, Jalali month, and Persian season inside the imported dataset's local-date coverage. Descriptors are grouped by type and ordered newest-first within each group. The default is the latest complete Jalali month containing source data. Weekly periods start Saturday at `00:00` and end at the following Saturday `00:00` in Tehran. The optional `periodType` query is allowlisted and filters the returned descriptors. The server rejects stale or fabricated period ids and invalid period types instead of accepting client-computed dates.
## Analytics-run contract

9
docs/openapi.yaml
View File

@@ -136,9 +136,11 @@ paths:
operationId: listAnalyticsPeriods
summary: List approved reporting periods
description: |
Returns allowlisted periods with server-calculated UTC and Tehran-local
half-open boundaries. Clients start runs with a returned `periodId` and
never submit arbitrary timestamps.
Returns every complete allowlisted day, Iranian week, Jalali month, and
Persian season inside the imported dataset's local-date coverage, with
server-calculated UTC and Tehran-local half-open boundaries. Periods are
grouped by type and ordered newest-first inside each group. Clients start
runs with a returned `periodId` and never submit arbitrary timestamps.
parameters:
- name: periodType
in: query
@@ -1090,6 +1092,7 @@ components:
$ref: '#/components/schemas/PeriodId'
periods:
type: array
description: Dataset-bounded complete periods, grouped by type and newest-first within each group.
maxItems: 1000
items:
$ref: '#/components/schemas/ReportingPeriod'