# AI Page Insights and Calendar Intelligence

Status: implemented platform contract; reviewed production calendar data must be imported and approved before module flags are enabled.

## Scope and authority

The platform serves `overview`, `payments`, `fees`, `peers` (shown to merchants as `جایگاه رقابتی`), `transactions`, and `growth`. Transaction-detail pages are excluded. Merchant identity comes only from the authenticated session; the optional terminal must belong to that merchant. Every filter-driven analytics module uses the server-validated reporting period resolved for the visible analytics run, and that period enters its persisted scope and fingerprint. Table filters other than terminal and reporting period never enter the insight scope.

PostgreSQL and Go own dates, aggregates, rankings, confidence, forecasts, calendar classifications, and freshness. Provider input may contain aggregate evidence IDs only. Raw payment rows, payer-card keys, session source keys, and unsuppressed peer values are forbidden. For `peers`, the sanitized `peerComparison` evidence contains only suppression state/reason, cohort/session counts, and the eight approved metric medians, direction-aware percentiles, and directions; it never contains peer identities or individual values. The deterministic fallback identifies the strongest and weakest categories and recommends one action for the weakest category. Percentiles are calculated by a shared merchant-grain calculator with at least ten peers and one thousand combined peer sessions, excluding the active merchant.

## Time semantics

`asOfDate` and `forecastStartDate` are the real `Asia/Tehran` date supplied through an injectable clock. `dataThroughDate` is the latest completed dataset date. A lag of zero or one day is `FRESH`, two through seven is `LAGGING`, and more than seven is `STALE`. Stale output remains visible, is labelled “latest observed state,” and is capped at `LOW` confidence. Missing prior-year evidence is `INSUFFICIENT_DATA`, never synthetic history.

## Persistence and delivery

`ai_insight_snapshots` preserves immutable revisions and the latest valid `READY` or deterministic `PARTIAL` result. `ai_insight_jobs` is a PostgreSQL durable queue with bounded leases and recovery. `ai_insight_events` retains one hour of tenant-scoped replay for SSE. Fingerprints cover merchant, optional terminal, module, real as-of date, dataset watermark, calendar, analytics, prompt/schema, and model versions.

Manual refresh requires CSRF plus `Idempotency-Key` and is limited to one accepted refresh per module, terminal scope, and Tehran day. Import, calendar, and nightly jobs do not consume this quota. Refreshes never hide an earlier valid snapshot.

## Calendar workflow

Calendar versions move through `DRAFT`, `APPROVED`, `ACTIVE`, and `RETIRED`. Import validation requires coverage of three previous and two future Jalali years, source lineage, unique keys, valid classifications, resolved recurrence dates, and safe commercial posture. The importer and reviewer must be different actors. Activation is serialized and schedules new insight snapshots.

Use `go run ./cmd/calendar -action import -file <reviewed.json> -current-jalali-year 1405`, then separate `approve` and `activate` commands. Production readiness requires a human-reviewed University of Tehran official-calendar extraction plus separately sourced Iran-impact events. The codebase does not treat an example or partial catalog as production-ready.

## UI contract

Each filter-driven analytics page mounts an independent `AIInsightPanel` after its analytics run resolves. It depends on module, optional terminal, and the exact reporting-period id returned by that run. The visible feedback is one or two short plain-text Persian paragraphs with no Markdown, lists, formulas, KPI jargon, evidence identifiers, or expandable analytical detail. It explains the main business meaning and, when useful, one simple next action for a manager without analytics training. The selected Jalali period remains visible beside the summary. Loading, refresh, limited, and unavailable states stay independent and accessible. Growth retains its legacy 90-day detail during the compatibility release.