diff --git a/DESIGN.md b/DESIGN.md index 0ba4ffb..5159d8a 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Draft baseline for approval -- Version: 0.1.4 +- Version: 0.1.5 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -98,7 +98,7 @@ Navigation labels should describe merchant tasks, not internal database concepts - **Chart card:** title, period/filter controls, concise takeaway, plot, legend, accessible tabular alternative, provenance link. - **Insight card:** deterministic finding, numeric evidence, suggested merchant action, confidence/limitation; AI-generated copy is visibly labeled later. - **Data table:** semantic headers, server pagination/sorting, row actions named for screen readers, responsive priority, empty/error states. -- **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved day, Jalali-month, Persian-season, and named holiday/event periods with unambiguous comparison baselines. +- **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved daily, weekly, Jalali-month, and Persian-season periods with unambiguous comparison baselines. - **Status badge:** text plus icon/shape; color reinforces but never carries meaning alone. - **Feedback:** inline field errors, page-level error boundary, skeleton only when layout is known, retry action for recoverable failures. @@ -106,13 +106,12 @@ Navigation labels should describe merchant tasks, not internal database concepts - Lead with a written takeaway and exact KPI; charts support the conclusion rather than decorate it. - Default comparisons: current period vs previous equivalent period and merchant vs an eligible anonymized cohort. Peer values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise show a clear insufficient-data state. -- Always show unit, timezone/calendar, date or named-event window, comparison baseline, sample size, freshness, and missing-data caveat where material. +- Always show unit, timezone/calendar, exact reporting period, comparison baseline, sample size, freshness, and missing-data caveat where material. - Success/failure colors remain semantic and consistent. Never use a rainbow categorical palette for ordered values. - Tooltips are keyboard reachable and not the sole location of important values. - Charts have a textual summary and downloadable/visible data table when practical. - Zero, unavailable, suppressed, and not-yet-calculated are visually and linguistically distinct. - Only source status `Verified` is presented as a confirmed successful payment. `Paid` is a separate operational state and is never merged into success or failure without a later approved metric-definition change. -- Named Iranian holidays come from reviewed, versioned calendar data. Analytical campaign windows such as a broader Nowruz period are labeled separately from official public-holiday dates. ## Motion @@ -144,8 +143,8 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| -| 0.1.4 | 2026-08-20 | Defined the 15-minute freshness/stale UX, kept `Paid` separate from confirmed `Verified` success, and distinguished official holidays from analytical event windows. | -| 0.1.3 | 2026-08-20 | Added explicit Jalali-month, Persian-season, and named holiday/event reporting periods with visible baselines and evidence. | +| 0.1.5 | 2026-08-20 | Removed holiday/event reporting; limited period controls to daily, weekly, Jalali-month, and Persian-season views. | +| 0.1.4 | 2026-08-20 | Defined the 15-minute freshness/stale UX and kept `Paid` separate from confirmed `Verified` success. | | 0.1.2 | 2026-08-20 | Added the insufficient-data state and visibility threshold for anonymized peer comparisons. | | 0.1.1 | 2026-08-20 | Fixed merchant-facing time presentation to the Jalali calendar in `Asia/Tehran`, with explicit UTC API instants. | | 0.1.0 | 2026-08-20 | Established ZarinPal-inspired RTL foundation from supplied public/panel screenshots; fixed SvelteKit/Svelte/TypeScript/Tailwind stack; defined responsive shell, core components, accessibility, chart, and motion rules. | diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index 8470dea..9c1606e 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -25,10 +25,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe 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. +10. Approved reporting periods are daily, weekly, Jalali-month, and Persian-season views. Every comparison states its exact period and baseline. 11. Only source session status `Verified` counts as a confirmed successful payment. `Paid` appears as a separate operational state until an approved metric-catalogue revision defines it otherwise. 12. A successful incremental analytics publication must appear within 15 minutes of eligible source changes. The UI shows the latest successful publication time, distinguishes stale from unavailable data, and does not claim freshness after a failed refresh. Nightly reconciliation may correct projections without changing metric meaning. -13. Official Iranian holidays come from reviewed, versioned calendar snapshots. Any broader analytical campaign/event period is labeled separately and exposes its exact date range. ## Frontend architecture baseline @@ -48,7 +47,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe - Values visibly specify period and unit; missing/suppressed/zero states are distinct. - Confirmed-success views include only `Verified`; `Paid` is separately labeled and testable. - Freshness becomes stale after the approved 15-minute bound, exposes the last successful publication time, and recovers only after a successful publication. -- Official-holiday and analytical-event labels cannot be confused, and their exact dates are available to the user. +- Daily, weekly, Jalali-month, and Persian-season filters use the same explicit boundaries as the API and database. - 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.