docs: limit analytics reporting periods

docs/decisions/0007-calendar-aware-analytics-projections.md

@@ -5,7 +5,7 @@
 
 ## Context
 
-The source contains approximately 2.2 million payment-attempt rows, but attempts are only one domain entity. Merchant, terminal, session, attempt, import, identity, and calendar concepts require separate normalized relations connected by constraints. The product also needs daily, Jalali-month, Persian-season, and Iranian holiday/event analysis, including evidence that may later support bounded AI recommendations.
+The source contains approximately 2.2 million payment-attempt rows, but attempts are only one domain entity. Merchant, terminal, session, attempt, import, identity, and reporting-date concepts require separate normalized relations connected by constraints. The product needs daily, weekly, Jalali-month, and Persian-season analysis.
 
 Calculating every dashboard result from normalized attempt rows on every request creates avoidable latency. Conversely, splitting attempts into unrelated tables by month/category or adding PostgreSQL partitions before measuring query and maintenance behavior introduces complexity without evidence. Some metrics are additive across days, while distinct payer-token counts and percentiles are not.
 
@@ -13,9 +13,9 @@ Calculating every dashboard result from normalized attempt rows on every request
 
 Keep normalized business/source-of-truth relations: categories, merchants, merchant users, terminals, payment sessions, payment attempts, and import provenance. The attempt relation retains one row per source attempt; normalization does not arbitrarily distribute a single entity's rows across category/month tables.
 
-Add a versioned calendar model containing Gregorian and Jalali date attributes, Persian seasons, weekdays, and curated named events such as Nowruz. Calendar-event definitions have explicit provenance/version and are deterministic inputs to analytics, not LLM-generated labels.
+Add a reporting-date model containing Gregorian and Jalali date attributes, explicit reporting-week boundaries, Persian months/seasons, and weekdays.
 
-Build idempotent, rebuildable daily base projections containing additive components such as session count, attempt count, successful count, amount sum, and fee sum as approved by the metric catalogue. Derive month/season/event totals by grouping these components through the calendar model and recompute ratios from their numerators and denominators.
+Build idempotent, rebuildable daily base projections containing additive components such as session count, attempt count, successful count, amount sum, and fee sum as approved by the metric catalogue. Derive week/month/season totals by grouping these components through the reporting-date model and recompute ratios from their numerators and denominators.
 
 Create separate metric-specific period projections only for non-additive metrics or query paths proven expensive—for example, exact unique payer-token counts cannot be obtained by summing daily distinct counts. Projection rows record source import/version and freshness.
 
@@ -25,8 +25,6 @@ Keep normalized fact tables unpartitioned initially. Add targeted indexes from a
 
 - The normalized ERD remains semantically correct while dashboards read smaller, purpose-built projections.
 - Daily components support many calendar groupings without precomputing every possible period.
-- Calendar definitions and metric provenance make future AI observations traceable.
-- A single observed Nowruz period may be reported as an observation but not claimed as recurring seasonality; multiple comparable years are needed for that claim.
+- Explicit reporting-period definitions and metric provenance make future AI observations traceable.
 - Projection refresh, failure, stale-state visibility, and reconciliation tests become required operational behavior.
 - Schema/index/projection details remain subject to data profiling and approved metric/API requirements.
-

docs/decisions/0009-versioned-iranian-calendar.md

@@ -1,24 +0,0 @@
-# ADR 0009: Version reviewed Iranian calendar snapshots in Git
-
-- Status: Accepted
-- Date: 2026-08-20
-
-## Context
-
-Monthly, Persian-season, Nowruz, and public-holiday analytics need deterministic Gregorian/Jalali mappings and named date ranges. Runtime dependence on a public calendar API would add availability, version drift, and reproducibility risks. Official holiday dates can change across years, especially events derived from other calendars.
-
-## Decision
-
-Commit a reviewed, machine-readable calendar snapshot for every supported Jalali year. Use the Calendar Center of the University of Tehran Institute of Geophysics as the authoritative annual source (`https://calendar.ut.ac.ir/`). The source URL/document identity, retrieval date, checksum, reviewer, and snapshot schema version accompany each file.
-
-For the challenge period, cover both Jalali 1404 and 1405 because Gregorian January–June 2026 crosses the Jalali year boundary. Runtime code reads validated database calendar tables populated from these versioned snapshots and never calls an external calendar API.
-
-Differentiate official public holidays from analytical event/campaign windows. A Nowruz analytical window may extend beyond officially closed days, but its exact dates, rationale, and version are explicit rather than inferred by an LLM.
-
-## Consequences
-
-- Historical analytics are reproducible even if websites/APIs change.
-- Annual calendar updates are reviewed source changes with validation tests.
-- Unsupported years fail clearly instead of guessing holiday membership.
-- Calendar data is committed reference data; raw payment archives remain ignored.
-

docs/decisions/0010-limit-reporting-periods.md

@@ -0,0 +1,20 @@
+# ADR 0010: Limit MVP reporting periods
+
+- Status: Accepted
+- Date: 2026-08-20
+
+## Context
+
+Earlier drafts included named Iranian holidays and analytical event windows. That scope adds calendar sourcing, versioning, UX distinctions, and analytics definitions that are not required for the challenge MVP.
+
+## Decision
+
+Limit reporting periods to Tehran-local daily, weekly, Jalali-month, and Persian-season views. Remove named holidays, Nowruz-specific periods, public-holiday calendars, and generic event-window reporting from the current product and data model.
+
+The exact weekly boundary remains an explicit reporting-period decision; it must not be inferred differently by the database, API, and frontend.
+
+## Consequences
+
+- No holiday/event entities, imported holiday snapshots, runtime calendar API, or holiday-specific UI are required.
+- A reporting-date dimension remains useful for deterministic Gregorian/Jalali conversion and consistent week, month, and season grouping.
+- Holiday/event analytics may return only through a future approved spec and ADR.