26 lines
2.0 KiB
Markdown
26 lines
2.0 KiB
Markdown
# ADR 0004: Interpret source timestamps as Asia/Tehran and normalize to UTC
|
|
|
|
- Status: Accepted
|
|
- Date: 2026-08-20
|
|
|
|
## Context
|
|
|
|
The challenge archive contains timezone-naive timestamp strings such as `2026-01-02 11:52:56`. It supplies no offset or timezone column. Analytics depend on consistent daily/hourly windows, retry durations, settlement timing, and period comparisons, so leaving interpretation implicit would make results environment-dependent.
|
|
|
|
## Decision
|
|
|
|
Interpret every valid timezone-naive source timestamp as local civil time in the IANA `Asia/Tehran` zone. Convert canonical persisted timestamps to UTC-backed PostgreSQL `timestamptz` values. API contracts expose ISO-8601 timestamps with an explicit UTC offset (`Z`); merchant-facing presentation converts them to `Asia/Tehran` and uses the Jalali calendar.
|
|
|
|
The importer records the assumed zone and timezone-data/runtime version in its manifest. The raw archive remains immutable operational input identified by checksum, preserving the original textual values and allowing a new import version if authoritative source metadata later contradicts the assumption. A changed interpretation must never silently update an existing completed import.
|
|
|
|
Missing or invalid timestamp values remain missing/rejected according to the import validation policy; they are not replaced with import time. Timestamp-order anomalies are reported as data-quality evidence and are not automatically “corrected.”
|
|
|
|
## Consequences
|
|
|
|
- Day/hour analytics have one documented merchant-relevant timezone.
|
|
- Database comparisons and API interchange use explicit instants rather than server-local time.
|
|
- The assumption is traceable and reversible through source checksum, immutable input, manifest metadata, and importer revision.
|
|
- Tests must cover conversion around relevant timezone-rule boundaries and ensure host/container timezone does not change results.
|
|
- Calendar conversion is a presentation concern; backend period boundaries are calculated from explicit `Asia/Tehran` local ranges and converted to UTC for querying.
|
|
|