diff --git a/DESIGN.md b/DESIGN.md index 5159d8a..58d3349 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Draft baseline for approval -- Version: 0.1.5 +- Version: 0.1.6 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -93,7 +93,7 @@ Navigation labels should describe merchant tasks, not internal database concepts ## Core component contracts -- **App shell:** sidebar/drawer, utility header, page title, merchant identity, freshness indicator. “Fresh” means the latest successful analytics publication is no more than 15 minutes behind eligible source changes; a delayed or failed refresh shows an explicit stale state and last-successful time. +- **App shell:** sidebar/drawer, utility header, page title, merchant identity, analytics-cache status. First access shows an explicit calculation state. A current cached revision shows its calculated time; a source-revision mismatch or failed recalculation shows the previous result only with an explicit stale warning. - **Metric card:** label, formatted value/unit, comparison and period, semantic trend, definition link, states. - **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. @@ -143,8 +143,9 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 0.1.6 | 2026-08-20 | Replaced time-based analytics freshness with lazy first-access calculation and revision-based merchant/cohort cache states; defined Saturday–Friday weeks. | | 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.4 | 2026-08-20 | 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 9c1606e..40c94c4 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -25,9 +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 are daily, weekly, Jalali-month, and Persian-season views. Every comparison states its exact period and baseline. +10. Approved reporting periods are daily, weekly, Jalali-month, and Persian-season views. Weekly periods run Saturday through Friday in `Asia/Tehran`. 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. +12. The first relevant dashboard access may calculate analytics and shows a bounded calculation/loading state. Later equivalent requests reuse the current PostgreSQL-backed merchant cache. When the source or cohort revision changes, the next access recalculates; an older result is shown only with an explicit stale warning and last-calculated time. ## Frontend architecture baseline @@ -46,7 +46,8 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe - 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. - 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. +- First access calculates once, a second equivalent access reuses the current cached revision, and concurrent first accesses do not create duplicate user-visible calculations. +- A source-revision mismatch is visibly stale until successful recalculation; cache age alone does not make static data stale. - 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.