docs: define calendar-aware analytics model

docs/DATA-FOUNDATION-SPEC.md

@@ -13,6 +13,8 @@ Repeatably ingest the supplied payment-attempt archive into PostgreSQL, preserve
 - Streamed `.csv.gz` ingestion from a local, Git-ignored input path
 - Import runs, checksums, schema version, row counts, rejection/error reporting
 - Normalized merchant, category, terminal, payment-session, payment-attempt, and account/profile concepts
+- Versioned Gregorian/Jalali calendar dates and curated Iranian event/holiday periods
+- Rebuildable daily base summaries and metric-specific period projections for approved analytics
 - Synthetic merchant display profiles and one demo account per merchant
 - Idempotent re-runs and explicit import lifecycle
 - Database constraints/indexes driven by documented access paths
@@ -36,6 +38,10 @@ erDiagram
     MERCHANT ||--o{ PAYMENT_SESSION : receives
     TERMINAL ||--o{ PAYMENT_SESSION : handles
     PAYMENT_SESSION ||--|{ PAYMENT_ATTEMPT : contains
+    CALENDAR_DATE ||--o{ CALENDAR_DATE_EVENT : includes
+    CALENDAR_EVENT ||--o{ CALENDAR_DATE_EVENT : occurs_on
+    CALENDAR_DATE ||--o{ MERCHANT_DAY_SUMMARY : groups
+    MERCHANT ||--o{ MERCHANT_DAY_SUMMARY : summarizes
     IMPORT_RUN ||--o{ PAYMENT_SESSION : introduced_by
     IMPORT_RUN ||--o{ PAYMENT_ATTEMPT : introduced_by
     IMPORT_RUN ||--o{ IMPORT_ISSUE : reports
@@ -111,6 +117,34 @@ erDiagram
       bigint affected_rows
       jsonb evidence
     }
+    CALENDAR_DATE {
+      date date PK
+      int jalali_year
+      int jalali_month
+      int jalali_day
+      text persian_season
+      int iso_weekday
+    }
+    CALENDAR_EVENT {
+      bigint id PK
+      text code UK
+      text title_fa
+      text event_type
+      text source_version
+    }
+    CALENDAR_DATE_EVENT {
+      date date FK
+      bigint calendar_event_id FK
+    }
+    MERCHANT_DAY_SUMMARY {
+      bigint merchant_id FK
+      date local_date FK
+      bigint session_count
+      bigint attempt_count
+      bigint successful_count
+      bigint amount_sum
+      bigint source_import_run_id FK
+    }
 ```
 
 This ERD is a logical baseline, not an approved physical schema. In particular, source key types, card-key retention, analytics projections/materialized views, and whether session-level fields can conflict across retries must be resolved from a profiling report before migrations are approved.
@@ -124,6 +158,7 @@ This ERD is a logical baseline, not an approved physical schema. In particular,
 5. Validate uniqueness of `(session_key, try_seq)`, referential consistency, parseability, null rates, ranges, timestamp ordering, and merchant/terminal/category relationships.
 6. Promote accepted data transactionally or through a resumable, explicitly versioned workflow; a failed run cannot appear complete.
 7. Emit a machine-readable and human-readable import report. Do not log raw card keys or credentials.
+8. Populate and validate the approved calendar range, then rebuild affected analytics projections idempotently after source promotion. Projection failure must not make an incomplete projection appear fresh.
 
 ## Synthetic merchant/account rules
 
@@ -143,6 +178,9 @@ This ERD is a logical baseline, not an approved physical schema. In particular,
 - Missing values remain missing rather than being silently replaced with factual-looking defaults.
 - The import report captures checksum, importer revision, timings, counts, validation failures, and quality metrics.
 - Raw data and database state remain ignored by Git; code, schema, rules, docs, and safe templates are tracked.
+- Daily, Jalali-month, Persian-season, and approved calendar-event analytics reconcile to deterministic source queries for additive metrics.
+- Rates are recomputed from their numerator and denominator over the requested period rather than averaged from daily percentages.
+- Non-additive metrics such as unique payer-token counts are never produced by summing daily distinct counts.
 
 ## Approval gates / unresolved decisions
 
@@ -158,6 +196,6 @@ Resolved: retain `payer_card_key` unchanged as a restricted, merchant-scoped opa
 
 Resolved: peer benchmarks exclude the active merchant and require at least 10 other merchants plus 1,000 combined peer sessions in the approved cohort/window. Otherwise the benchmark is suppressed as insufficient data; the merchant's own analytics remain available. See ADR 0006.
 
-Remaining approval gates:
+Resolved: use normalized source-of-truth entities plus versioned calendar/event dimensions, rebuildable daily base summaries, and metric-specific projections for non-additive or measured high-cost period analytics. Monthly, Persian-season, and holiday results use explicit calendar definitions. Keep fact tables unpartitioned initially and introduce partitioning only from measured need. See ADR 0007.
 
-1. Physical partitioning/materialization strategy, which must follow measured query needs rather than the logical ERD alone.
+No broad architecture approval gates remain for this capability. Physical columns, indexes, constraints, calendar source, projection shapes, and migration details still require profiling evidence and acceptance in the implementation-ready revision of this spec.