diff --git a/docs/GROWTH-ANALYST-UX-SPEC.md b/docs/GROWTH-ANALYST-UX-SPEC.md new file mode 100644 index 0000000..34fbd4f --- /dev/null +++ b/docs/GROWTH-ANALYST-UX-SPEC.md @@ -0,0 +1,32 @@ +# 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. `INSUFFICIENT_DATA` explains the minimum evidence without presenting a forecast. `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 refresh is explicit and limited once per merchant per Tehran day. + diff --git a/tasks/ai-growth-analyst.md b/tasks/ai-growth-analyst.md new file mode 100644 index 0000000..6553475 --- /dev/null +++ b/tasks/ai-growth-analyst.md @@ -0,0 +1,8 @@ +# AI Growth Analyst Frontend Tasks + +- [ ] U1: Regenerate OpenAPI types and extend the typed client/report state model. +- [ ] U2: Add `/growth`, sidebar navigation, dashboard teaser, and global-terminal scope integration. +- [ ] U3: Add accessible 90-day forecast chart, confidence/summary states, event evidence, opportunity/risk, peer, and campaign brief components. +- [ ] U4: Add initial/refresh skeletons, preserved previous report, SSE/poll recovery, daily refresh feedback, partial/insufficient/error states, and reduced-motion behavior. +- [ ] U5: Add unit/component tests, format/check/build verification, responsive RTL review, and light/dark accessibility review without browser automation unless the user grants permission. +