diff --git a/DESIGN.md b/DESIGN.md index 58d3349..efb2f5c 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Draft baseline for approval -- Version: 0.1.6 +- Version: 0.1.7 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -93,9 +93,9 @@ Navigation labels should describe merchant tasks, not internal database concepts ## Core component contracts -- **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. +- **App shell:** sidebar/drawer, utility header, page title, merchant identity, analytics progress/status. First access opens an authenticated SSE stream and starts all analytics sections; the page reveals each section independently as it becomes ready. +- **Metric card:** label, formatted value/unit, comparison and period, semantic trend, definition link, independent queued/calculating/ready/failed states. +- **Chart card:** title, period/filter controls, concise takeaway, plot, legend, accessible tabular alternative, provenance link, and section-local loading/error behavior. - **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 daily, weekly, Jalali-month, and Persian-season periods with unambiguous comparison baselines. @@ -111,6 +111,7 @@ Navigation labels should describe merchant tasks, not internal database concepts - 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. +- A ready section appears immediately without layout-shifting or blocking on unfinished siblings. Overall progress remains understandable without relying on animation. - 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. ## Motion @@ -143,6 +144,7 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 0.1.7 | 2026-08-20 | Moved analytics results to high-TTL Redis and defined partial, parallel section delivery through authenticated SSE. | | 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 | Kept `Paid` separate from confirmed `Verified` success. | diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index 40c94c4..19063d3 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -27,7 +27,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe 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. 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. 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. +12. The first relevant dashboard access starts all approved analytics-section jobs in bounded parallel. The app opens an authenticated, merchant-scoped SSE stream and renders each section as soon as its `ready` event arrives. A failed section has its own retry/error state and does not hide successful siblings. +13. Later equivalent requests reuse current high-TTL Redis entries. PostgreSQL merchant/cohort revision changes select new cache keys and cause only missing sections to be recalculated; cache age alone does not make static data stale. +14. SSE reconnect uses stable event ids/resume semantics, shows a connection-recovery state, and never exposes job status or analytics for another merchant. ## Frontend architecture baseline @@ -46,8 +48,10 @@ 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. -- 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. +- All core sections begin on first access and become visible independently in completion order without blocking the whole dashboard. +- A second equivalent access reuses current Redis entries, and concurrent first accesses do not enqueue duplicate equivalent section jobs. +- One section failure is isolated, retryable, and accessible; already-ready sections remain usable. +- Disconnecting and reconnecting the SSE stream resumes safely without cross-merchant data or duplicated final sections. - 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.