docs: approve routed ZarinPal redesign

docs/ZARINPAL-REDESIGN-AMENDMENT.md

@@ -0,0 +1,58 @@
+# 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.