From 6d3cfc7290a4cf5bd08e6d40ed9135705056d789 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 12:36:37 +0330 Subject: [PATCH] docs: draft merchant dashboard specification --- docs/DASHBOARD-SPEC.md | 54 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/DASHBOARD-SPEC.md diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md new file mode 100644 index 0000000..c028fc1 --- /dev/null +++ b/docs/DASHBOARD-SPEC.md @@ -0,0 +1,54 @@ +# Merchant Dashboard Capability Spec + +- Status: Draft — not approved for implementation +- Capability: Merchant dashboard +- Last updated: 2026-08-20 + +## Objective + +Give a non-technical merchant a fast, trustworthy Persian RTL view of payment performance, problems, opportunities, and anonymized peer context, with every claim traceable to deterministic metrics. + +## Actors + +- Demo merchant user: signs in with assigned username/password and sees one merchant. +- Merchant user: same MVP permissions; broader roles are out of scope until specified. +- Judge/operator: can use different seeded merchant accounts but receives no hidden cross-tenant browser privilege. + +## Functional requirements + +1. Login establishes a secure backend session and returns a generic failure for invalid credentials. +2. The app shell identifies the active merchant and offers logout. +3. Overview shows data freshness, selected period, primary outcomes, trend, and prioritized deterministic insights. +4. Payment performance supports success/failure/retry/timing analysis and traceable drill-downs. +5. Peer comparison exposes only eligible anonymized cohort aggregates and explains suppression/limitations. +6. Filters and pagination are reflected in the URL where sharing/reload is useful. +7. Every screen implements loading, empty, partial-data, stale, unauthorized, forbidden, and recoverable-error behavior as applicable. +8. Responsive behavior and component contracts follow `DESIGN.md`. + +## Frontend architecture baseline + +- SvelteKit 2 + Svelte 5 runes + strict TypeScript + Tailwind CSS v4. +- Static/client-rendered application behind Nginx, consuming the Go API under the same origin where practical. +- Route groups separate authentication and authenticated application layouts. +- Server state belongs to a typed API layer; local UI state uses the smallest appropriate Svelte primitive/context. +- No SvelteKit server endpoints, database access, or private secrets in the frontend baseline. +- API types should be generated from the approved interface description. + +## Acceptance criteria + +- A user can authenticate as at least two distinct seeded merchants and each dashboard shows different, correctly isolated data. +- Direct URL/API manipulation cannot expose another merchant's details. +- Critical flows work at 360 px, 768 px, 1024 px, and a wide desktop viewport in RTL. +- Login, navigation drawer, filters, chart alternatives, and logout are keyboard complete and screen-reader understandable. +- Values visibly specify period and unit; missing/suppressed/zero states are distinct. +- Production build passes type checking, linting, unit/component tests, and Playwright critical-flow tests. +- No raw dataset record, payer-card key, credential, or AvalAI key enters client bundles/logging/storage. + +## Unresolved dependencies + +- Approved analytics metric catalogue and cohort suppression policy +- Approved authentication/session API +- OpenAPI/interface contract and error format +- Decisions listed in `DESIGN.md` +- Static adapter fallback/routing behavior under the final Nginx configuration +