59 lines
4.1 KiB
Markdown
59 lines
4.1 KiB
Markdown
# 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.
|