zarinpal-analytics-frontend/docs/GROWTH-ANALYST-UX-SPEC.md

AI Growth Analyst UX Spec

• Status: Approved — implementation authorized 2026-08-21
• Route: /growth
• Language/direction: Persian, RTL

Experience

• Add تحلیل‌گر رشد to the authenticated sidebar and a compact dashboard teaser linking to it.
• Reuse the global terminal selector. Merchant scope may show peers; terminal scope explains that peer comparison is unavailable.
• Keep the previous successful report visible during refresh. Initial and uncached states use visible light/dark skeletons; no state renders an empty page.
• Header states the 90-day horizon starts after the latest complete dataset date. A daily به‌روزرسانی تحلیل action shows nextRefreshAt, loading, and typed rate-limit feedback.
• Render a responsive, keyboard-accessible forecast chart with count/amount mode, hover/focus points, P10–P90 band, axes/units, chart summary, and a non-visual data alternative.
• Show historical wins, up to five upcoming opportunities, up to three gentle low-period warnings, and a peer card when permitted.
• Each brief contains server-rendered timing/range/evidence plus validated AI headline, interpretation, offer/message suggestion, one preparation step, confidence, and limitation.
• PARTIAL keeps deterministic charts/cards and explains that the written AI interpretation was unavailable. LOW keeps the forecast visible with an explicit limited-history or high-variance warning. INSUFFICIENT_DATA is reserved for scopes with no historical observations. FAILED offers safe retry without hiding an older successful report.
• Motion is restrained, supports reduced motion, and does not block reading. All interactive targets are at least 44 px.

Copy rules

• Use natural professional Persian, Persian ی/ک, appropriate نیم‌فاصله, Persian digits, and Rial.
• Keep tone constructive: describe opportunity, preparation, and uncertainty; do not shame the merchant or claim guaranteed outcomes.
• Every recommendation visibly cites its deterministic evidence card. AI is labeled advisory.
• No chat, notifications, campaign execution, user memory, provider/model names, token usage, or internal failure details appear in merchant UI.

Acceptance

• Works at 360, 768, 1024, and wide desktop widths in light/dark RTL layouts.
• All job, cache, refresh, partial, insufficient, unauthorized, and recoverable error states are accessible and tested.
• Generated OpenAPI types are used; no handwritten duplicate growth DTOs or browser secrets exist.
• Cached navigation performs no generation request. Manual retry remains available while the current scope has no persisted AI-written summary; after one exists, refresh is limited once per merchant per Tehran day.