Approved Amendment: Routed ZarinPal Merchant Experience

Status: Approved by the user on 2026-08-20
Delivery branch: feature/zarinpal-dashboard-redesign
Mode: Operate

Objective

Replace the single long dashboard with a recognizable ZarinPal-style merchant shell and routed analytics experience backed by the real local dataset.

Direction contract

World: crisp ZarinPal merchant console—white working surfaces, compact outlined controls, restrained radii, quiet gray canvas, blue active states, and a small yellow brand accent.
First viewport: a useful overview, not a wall of KPIs: a plain-language finding, payment-flow chart with inspectable points, four key outcomes, and recent transactions.
Navigation: persistent top utility bar plus a right sidebar that collapses to icons on desktop and becomes an accessible drawer on mobile.
Signature interaction: terminal and period changes update the URL and recompose the payment-flow visualization; chart points reveal exact values on hover and keyboard focus.
Cross-surface reach: the same filter bar, table language, metric help, statuses, spacing, and motion apply on overview, transactions, payment performance, fees, peers, and methodology pages.
Honest risk: dense financial data can become visually noisy. The implementation leads with one written takeaway per section, keeps exact evidence nearby, and moves full tables to their own routes.

API additions

GET /api/v1/analytics/terminals lists only terminals belonging to the authenticated merchant.
POST /api/v1/analytics/runs accepts an optional tenant-validated terminalId.
Overview data adds a bounded daily payment-history series for the selected period and terminal.
GET /api/v1/analytics/session-details adds ALL, status, and amount bounds while preserving cursor pagination and merchant scope.
GET /api/v1/analytics/sessions/{sessionId} returns one merchant-owned session and its ordered attempt history, or the same safe 404 used for absent resources.

Routes and URL state

Authenticated routes are /dashboard, /transactions, /transactions/[sessionId], /payments, /fees, /peers, and /methodology.

Every analytical page uses:

range=day|week|month|season
terminal=all|<opaque-terminal-id>

The transactions page additionally uses optional status, minAmount, and maxAmount parameters. Invalid values fall back safely and are never sent as authorization inputs.

Acceptance criteria

The supplied logo is visually cropped to its light/dark wordmark variant in the top bar without displaying the source sheet.
Sidebar labels disappear when collapsed; icons are unwrapped and neutral except for the active item, which uses blue icon/text plus a subtle active surface.
Each sidebar section is a real SvelteKit route and deep-link refresh works through the existing static fallback.
Daily, weekly, monthly, and seasonal choices are visible on every analytical route and copied URLs restore the view.
Terminal selection changes merchant-owned aggregates and detail rows.
The overview chart exposes exact daily amount/count through pointer and keyboard interaction and includes a textual summary.
Tables use status/date/amount filters, readable rows, and transaction links; no search field is present.
Transaction detail shows the session facts and ordered attempt history without payer tokens or invented failure causes.
Important metrics have a keyboard-reachable formula tooltip.
Peer messaging uses factual, supportive Persian and never reveals peer identities or rows.
Motion is functional, bounded to 120–220 ms, and disabled by prefers-reduced-motion.
The feature runs beside the current local instance and is not merged without explicit user confirmation.

Verification

Backend: go test ./..., go vet ./..., focused authenticated HTTP smoke tests.
Frontend: npm test, npm run check, npm run build.
Browser: login, terminal switch, all routes, URL-restored filters, chart hover/focus, transaction drill-down, sidebar collapse, mobile drawer, console/network errors, and desktop/mobile screenshots.

4.1 KiB Raw Blame History Unescape Escape