starcoach-hackathon/zarinpal-analytics-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define seasonal reporting periods

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 13:38:23 +03:30
parent 70c0d9a4f2
commit 9a26a51eab
2 changed files with 5 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
DESIGN.md
View File

@@ -1,7 +1,7 @@
# Design System — ZarinPal Merchant Analytics # Design System — ZarinPal Merchant Analytics
- Status: Draft baseline for approval - Status: Draft baseline for approval
- Version: 0.1.2 - Version: 0.1.3
- Last updated: 2026-08-20 - Last updated: 2026-08-20
- Direction: Persian-first RTL - 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. - **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. - **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. - **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, Persian date/time semantics. - **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.
- **Status badge:** text plus icon/shape; color reinforces but never carries meaning alone. - **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. - **Feedback:** inline field errors, page-level error boundary, skeleton only when layout is known, retry action for recoverable failures.
@@ -106,7 +106,7 @@ 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. - 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. - 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 window, sample size, freshness, and missing-data caveat where material. - Always show unit, timezone/calendar, date or named-event window, 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. - 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. - Tooltips are keyboard reachable and not the sole location of important values.
- Charts have a textual summary and downloadable/visible data table when practical. - Charts have a textual summary and downloadable/visible data table when practical.
@@ -142,6 +142,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
| Version | Date | Decision | | Version | Date | Decision |
|---|---|---| |---|---|---|
| 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.2 | 2026-08-20 | Added the insufficient-data state and visibility threshold for anonymized peer comparisons. | | 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.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. | | 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. |

1
docs/DASHBOARD-SPEC.md
View File

@@ -25,6 +25,7 @@ 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. 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`. 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. 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 ## Frontend architecture baseline