starcoach-hackathon/zarinpal-analytics-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: ground competitive insights in peer metrics

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-22 18:45:29 +08:00
parent 1a8a61cfe7
commit 4f91726edb
10 changed files with 497 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/AI-PAGE-INSIGHTS-SPEC.md
View File

@@ -4,9 +4,9 @@ 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. 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.
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.
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