56 lines
3.6 KiB
Markdown
56 lines
3.6 KiB
Markdown
# 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 excludes the active merchant and exposes only eligible anonymized cohort aggregates. It displays a value only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise it explains that there is not enough data. This never hides the merchant's own analytics.
|
|
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`.
|
|
9. Merchant-facing dates use the Jalali calendar in `Asia/Tehran`; API instants remain explicit ISO-8601 UTC and filtering sends unambiguous boundaries.
|
|
10. Approved reporting periods include day, Jalali month, Persian season, and named Iranian holiday/event windows. Every comparison states its exact period and baseline; one observed event period is not presented as recurring seasonality.
|
|
|
|
## 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
|