fix: scope page insights to reporting periods

docs/AI-PAGE-INSIGHTS-SPEC.md

@@ -4,7 +4,7 @@ Status: implemented platform contract; reviewed production calendar data must be
 
 ## Scope and authority
 
-The platform serves `overview`, `payments`, `fees`, `peers`, `transactions`, and `growth`. Transaction-detail pages are excluded. Merchant identity comes only from the authenticated session; the optional terminal must belong to that merchant. The transactions module may additionally use a validated reporting period so its summary matches the page; that period enters its persisted scope and fingerprint. Table filters never enter the insight scope.
+The platform serves `overview`, `payments`, `fees`, `peers`, `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.
 
@@ -26,4 +26,4 @@ Use `go run ./cmd/calendar -action import -file <reviewed.json> -current-jalali-
 
 ## UI contract
 
-Each page mounts an independent `AIInsightPanel`. It depends only on module and terminal. It keeps prior copy during refresh, represents loading/stale/partial/limited/unavailable states independently, announces status changes, preserves RTL and keyboard behavior, and gives mourning or memorial events restrained neutral styling. Growth retains its legacy 90-day detail during the compatibility release.
+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.

docs/openapi.yaml

@@ -647,7 +647,7 @@ paths:
       parameters:
         - {name: module, in: path, required: true, schema: {$ref: '#/components/schemas/AIInsightModule'}}
         - {name: terminalId, in: query, required: false, schema: {type: string, maxLength: 128}}
-        - {name: periodId, in: query, required: false, description: Used only by the transactions module to match the selected reporting period., schema: {type: string, maxLength: 128}}
+        - {name: periodId, in: query, required: false, description: Server-offered reporting period used to match the visible analytics run., schema: {type: string, maxLength: 128}}
         - $ref: '#/components/parameters/RequestIdHeader'
       responses:
         '200': {description: Latest ready or deterministic-partial snapshot., content: {application/json: {schema: {$ref: '#/components/schemas/AIInsight'}}}}
@@ -1709,7 +1709,7 @@ components:
       additionalProperties: false
       properties:
         terminalId: {type: string, maxLength: 128}
-        periodId: {type: string, maxLength: 128, description: Used only by the transactions module.}
+        periodId: {type: string, maxLength: 128, description: Server-offered reporting period used to match the visible analytics run.}
     AIInsightJob:
       type: object
       additionalProperties: false