docs: move lazy analytics cache to redis

docs/PHYSICAL-SCHEMA-PROPOSAL.md

@@ -10,7 +10,7 @@
 - Preserve source identifiers as text and use internal surrogate keys for joins.
 - Keep payment session and payment attempt grains separate.
 - Use UTC `timestamptz` for canonical instants and `bigint` for Rial amounts.
-- Keep normalized facts as source of truth; analytics projections are rebuildable.
+- Keep normalized PostgreSQL facts as source of truth; Redis analytics results are disposable and rebuildable.
 - No initial table partitioning. Add indexes from approved access paths and measured query plans.
 - The CSV importer is a one-time administrative bootstrap, not a production ingestion service.
 
@@ -51,20 +51,16 @@ Synthetic profile fields carry an explicit `profile_is_synthetic` marker. Creden
 
 Both fact tables distinguish `bootstrap` from `zarinpal_live` origin. Bootstrap rows reference an import run; live rows do not invent one. Payment facts are append-only for the MVP; inserts advance database-managed analytics revisions.
 
-### Rebuildable analytics projections
+### Analytics invalidation state
 
-| Table family | Grain | Purpose |
+| Table | Grain | Purpose |
 |---|---|---|
-| `merchant_day_metrics` | merchant + Tehran local date | Additive counts/sums and metric numerators/denominators |
-| `merchant_day_*_breakdowns` | merchant + date + approved dimension | Only metric-catalogue breakdowns proven useful, such as PSP/failure groups |
-| `merchant_period_*` | merchant + approved day/week/month/season period | Non-additive or measured expensive metrics only |
-| `cohort_period_*` | approved cohort + period | Suppressed peer benchmark inputs/outputs with provenance and freshness |
-| `merchant_analytics_state` | one row per merchant | current source revision, cached revision, metric-definition version, calculation status/time |
-| `cohort_analytics_state` | one row per benchmark cohort/category | current source revision and cached revision for peer projections |
+| `merchant_analytics_revisions` | one row per merchant | monotonically increasing source revision advanced by related fact inserts |
+| `cohort_analytics_revisions` | one row per benchmark cohort/category | monotonically increasing peer-source revision advanced by relevant inserts |
 
-Projection names/columns are finalized by the analytics metric catalogue. Avoid a generic key/value metrics table because it weakens types, constraints, and discoverability.
+No calculated dashboard result is stored in PostgreSQL. Analytics queries and Redis value contracts are finalized by the metric catalogue and API spec.
 
-Projection rows record merchant/cohort source revision, metric-definition version, calculated time, and publication status. Inserts atomically increment the affected revision through schema-owned database logic so direct upstream writes cannot bypass invalidation. A dashboard cache miss or revision mismatch acquires a PostgreSQL advisory/row lock, builds typed projections, and advances the cached revision only after atomic publication. No generic JSON metric cache, Redis, scheduled refresh, or time-to-live expiry is required.
+Inserts atomically increment affected revision rows through schema-owned database logic so direct upstream writes cannot bypass invalidation. Redis keys include merchant/cohort revisions, metric-definition version, and analytics-section id. Old revision keys expire under a configurable high TTL; invalidation does not scan or delete arbitrary keys. Redis values follow typed, versioned response schemas and contain aggregates only.
 
 ## Initial index policy
 
@@ -72,7 +68,6 @@ Projection rows record merchant/cohort source revision, metric-definition versio
 - `payment_sessions (merchant_id, created_at DESC)` supports merchant period queries.
 - `payment_sessions (terminal_id, created_at DESC)` supports terminal drill-down.
 - `payment_attempts (payment_session_id, try_seq)` is unique and supports session traceability.
-- Projection primary keys start with merchant/cohort and period.
 - Additional status, PSP, bank, payer-token, or timestamp indexes require an approved API query and `EXPLAIN (ANALYZE, BUFFERS)` evidence; do not index every CSV column.
 
 ## Deletion and mutation policy
@@ -81,7 +76,7 @@ Projection rows record merchant/cohort source revision, metric-definition versio
 - Imported source facts are immutable after a completed import. Corrections create a new versioned recovery/import decision.
 - Production payment facts are append-only in the MVP. Update/delete semantics require a future ADR and corresponding cache-invalidation rules.
 - Synthetic display profiles and credentials can change independently from source facts.
-- Derived projections may be rebuilt and atomically replaced; source and metric-definition revisions prevent stale data from appearing current.
+- Redis analytics entries are disposable and rebuilt on a cache miss. Source/cohort and metric-definition revisions prevent stale keys from appearing current.
 
 ## Production population boundary