330 lines
18 KiB
Markdown
330 lines
18 KiB
Markdown
# Frontend UX Audit Report — TorbatYar Commercial Usability
|
|
|
|
> **Audit only.** No code changes. No new products. No roadmap phases.
|
|
> Date: 2026-07-28
|
|
> Sources: `docs/project-status.yaml`, Experience FE snapshot, Commercial Foundation contracts, existing `frontend/app/**` pages
|
|
> Note: `docs/service-snapshots/frontend*.yaml` — **not found** (gap)
|
|
|
|
**Verdict:** The frontend is **not yet commercially usable end-to-end**. Wave-1 onboarding UX exists, but the customer journey **breaks after workspace creation** — no trial/subscription/license activation UI, dashboard is a stub launcher, and commercial rules (trial limits, feature locking, domain gating) are largely absent from tenant-facing UI.
|
|
|
|
---
|
|
|
|
## 1. Frontend UX Audit Report
|
|
|
|
| Area | Finding | Status |
|
|
| --- | --- | --- |
|
|
| **Landing / Home** | Platform host → Business Onboarding home (`frontend/app/page.tsx`): intent grid + recommended bundle + CTA. Tenant host → `TenantSitePage` + `AppStoreGrid` (app launcher). | PARTIAL |
|
|
| **Home** | Commercially oriented copy; 8 intents only (not full 17 business types). Pricing hints are static FE strings. | PARTIAL |
|
|
| **Dashboard** | `/dashboard` shows tenant name, plan/subscription fields (often empty), domains list, and **4 “بهزودی” cards with no links**. No product launcher, no setup checklist, no upgrade CTA. | SCAFFOLD |
|
|
| **Onboarding** | `/onboarding` AuthGuard wizard: business → branding → domain → review → complete. Creates tenant via Core API; shows FE bundle preview; does **not** activate entitlements/subscription/trial. | PARTIAL |
|
|
| **Signup** | `/register` → `AuthPanel` signup mode. | READY (auth) |
|
|
| **Login** | `/login` → `AuthPanel` / SSO. Header “ورود” uses `useAuth().login()`. | READY (auth) |
|
|
| **Workspace selection** | `TenantSwitcher` on dashboard only when `memberships.length > 1`. No dedicated workspace picker page. | PARTIAL |
|
|
| **Tenant creation** | Onboarding `createTenant` + admin `/admin/tenants/new`. Tenant-facing path exists. | PARTIAL |
|
|
| **Business selection** | Home + onboarding select from `BUSINESS_INTENTS` (8). Canonical catalog has 17 types. | PARTIAL |
|
|
| **Service catalog** | `PLATFORM_APPS` + `AppStoreGrid` on tenant site only (not platform home). Mixed available/coming_soon. | PARTIAL |
|
|
| **Bundle selection** | Preview only from FE mirror of bundles; no multi-bundle compare, no API select event. | SCAFFOLD |
|
|
| **Subscription flow** | Tenant UI: **missing**. Admin tenant detail can create/view subscription via Core API. | SCAFFOLD / missing tenant |
|
|
| **Trial flow** | API types include `trialing` / `trial_ends_at`; **no tenant trial UX**. | SCAFFOLD |
|
|
| **Profile completion** | `/dashboard/settings` → `AccountSettings` (account). Vertical-specific profiles (beauty/healthcare) exist separately. No commercial profile (industry/country/currency) in platform onboarding. | PARTIAL |
|
|
| **Empty states** | DS `EmptyState` exists; platform dashboard does not use rich empty/setup states. Experience CRUD uses list empty patterns. | PARTIAL |
|
|
| **Navigation** | Global `SiteHeader` only (logo, login/dashboard/admin). **No app sidebar** on platform dashboard. Service portals have their own nav (Experience, Payment, etc.). | PARTIAL |
|
|
| **Sidebar** | Platform: none. Per-module portals: yes (varies). | PARTIAL |
|
|
| **Responsive** | Home/onboarding/dashboard use responsive grids; RTL root layout. | PARTIAL / OK for MVP |
|
|
| **Accessibility** | Experience DS claims WCAG smoke; platform home uses buttons/labels but no systematic a11y audit evidence in this pass. | PARTIAL |
|
|
| **Dark mode** | `ColorModeProvider` present; **no global toggle in SiteHeader**. Experience design-system supports light/dark. | PARTIAL |
|
|
| **Loading states** | Text “در حال بارگذاری…” common; Button `loading` props; Experience `loading.tsx` route shells. Few skeletons on platform pages. | PARTIAL |
|
|
| **Error states** | Inline red banners; Experience `error.tsx` + DS ErrorState; API 422 formatting improved for Experience. | PARTIAL |
|
|
| **Skeletons** | DS `Skeleton` exists; platform dashboard/onboarding rarely use it. | PARTIAL |
|
|
| **Search** | DS toolbar search placeholder; **no global product/workspace search**. | SCAFFOLD / missing |
|
|
| **Notifications** | No platform notification center. Loyalty has notifications page (module-specific). | SCAFFOLD / missing |
|
|
|
|
---
|
|
|
|
## 2. Scaffold Inventory
|
|
|
|
Legend: **READY** · **PARTIAL** · **SCAFFOLD** · **BROKEN**
|
|
|
|
### Platform commercial surface
|
|
|
|
| Page / surface | Mark | Evidence |
|
|
| --- | --- | --- |
|
|
| `/` Business Onboarding Home | PARTIAL | Intent + bundle preview work; no activation backend; incomplete type set |
|
|
| `/` Tenant host site | PARTIAL | App launcher grid; not commercial OS |
|
|
| `/login`, `/register` | READY | AuthPanel |
|
|
| `/onboarding` | PARTIAL | Real tenant create/branding/domain/complete APIs; no trial/bundle/license activation |
|
|
| `/dashboard` | SCAFFOLD | Quick links all “بهزودی”, no hrefs; plan/subscription display-only |
|
|
| `/dashboard/settings` | PARTIAL | Account settings; not commercial billing |
|
|
| `SiteHeader` | PARTIAL | Minimal; no catalog/apps/billing |
|
|
| Bundle catalog FE (`business-bundles.ts`) | SCAFFOLD as SoT | Documented as temporary mirror; not codegen |
|
|
|
|
### Admin (platform operator — not customer journey)
|
|
|
|
| Page | Mark | Evidence |
|
|
| --- | --- | --- |
|
|
| `/admin/tenants`, `/admin/tenants/[id]` | PARTIAL | Subscription create/get exists for admins |
|
|
| `/admin/tenants/new` | PARTIAL | Admin tenant create |
|
|
|
|
### Product hubs (application launchers / ops)
|
|
|
|
| Area | Mark | Notes |
|
|
| --- | --- | --- |
|
|
| `/experience/hub` + studio routes | PARTIAL → many READY CRUD | FE-11.5 list CRUD hardened; hub is thin launcher; FE-11.6 registry UI absent (expected) |
|
|
| `/payment/hub` + admin routes | PARTIAL / READY for MVP ops | Payment operator UI, not customer checkout/subscription storefront |
|
|
| `/hospitality/hub`, `/delivery/*`, `/crm/hub`, `/loyalty/*`, `/communication`, `/accounting`, `/sports-center/*`, `/healthcare/*`, `/beauty/*` | PARTIAL | Vertical depth varies; not wired to commercial activation pipeline |
|
|
| Coming-soon apps in `PLATFORM_APPS` | SCAFFOLD | ecommerce, restaurant duplicate, etc. |
|
|
|
|
### Scaffold patterns still present
|
|
|
|
- Dashboard quick-link cards: **buttons/cards without action**
|
|
- Bundle “activation” copy without entitlement API calls
|
|
- Static monthly hints in FE catalog
|
|
- No fake charts found on platform dashboard (good); Payment KPIs claimed live in prior audit
|
|
- Experience secondary forms: still “field polish” open per snapshot
|
|
- Global search / notifications: missing shells
|
|
|
|
---
|
|
|
|
## 3. Commercial Journey Report
|
|
|
|
Target journey vs actual:
|
|
|
|
| Step | Expected | Actual | Break? |
|
|
| --- | --- | --- | --- |
|
|
| Visitor | Public landing | Platform home OK | — |
|
|
| Landing | Business-oriented | Home onboarding OK | — |
|
|
| Business Type Selection | Full catalog | 8 intents only | Soft break |
|
|
| Needs Assessment | Rule engine inputs (size, needs flags…) | Intent click only | **Break** |
|
|
| Recommended Products | Product Registry | Service links from FE bundle | Soft break |
|
|
| Recommended Bundle | Catalog SoT | FE `primaryBundle` | Soft break |
|
|
| Create Workspace | Tenant + workspace | Onboarding createTenant | — |
|
|
| Trial Activation | Subscription trialing + license | **Missing tenant UI + no auto-activation** | **HARD BREAK** |
|
|
| Workspace Dashboard | Operating system / setup | Stub “بهزودی” cards | **HARD BREAK** |
|
|
| Product Setup | Guided entitle → hub | Manual link to first required service href | Soft break |
|
|
| Upgrade | Upgrade prompts | Missing | **HARD BREAK** |
|
|
| Subscription | Tenant subscribe/pay | Admin-only subscription tools | **HARD BREAK** |
|
|
| Payment | Customer billing / Torbat Pay activation | Payment hub is PSP ops, not journey step | **HARD BREAK** |
|
|
| Domain | Subdomain before pay; custom after active sub | Onboarding allows **optional custom domain anytime**; no subscription gate | **HARD BREAK** (rules) |
|
|
| Production | Ready state | No production checklist / domain verify UX on dashboard | **Break** |
|
|
|
|
**Primary break point:** after `onboarding.complete` → first service hub. No trial, license, entitlement grant, or commercial dashboard generation.
|
|
|
|
---
|
|
|
|
## 4. Missing Pages
|
|
|
|
| Missing page (reuse/extend preferred) | Purpose |
|
|
| --- | --- |
|
|
| `/pricing` or `/plans` | Public / post-login plan compare |
|
|
| `/subscribe` or `/billing` | Tenant subscription + trial start |
|
|
| `/licenses` or billing entitlements view | Show licensed products/capabilities |
|
|
| `/upgrade` | Upgrade prompts from locked features |
|
|
| `/apps` or dashboard apps panel | Entitled service launcher (reuse `PLATFORM_APPS` + entitlements) |
|
|
| `/onboarding/needs` | Size, employees, goals, flags (recommendation inputs) |
|
|
| `/onboarding/bundle` | Explicit bundle confirm (not only preview) |
|
|
| `/domains` (tenant) | Subdomain vs custom domain policy UI |
|
|
| `/setup` checklist | Post-trial product setup wizard |
|
|
| Global notifications page/center | Cross-product alerts |
|
|
| Global search | Workspace/apps/resources |
|
|
|
|
---
|
|
|
|
## 5. Missing Components
|
|
|
|
| Component | Need |
|
|
| --- | --- |
|
|
| `EntitlementGate` / `FeatureLock` | Hide/lock UI by feature check API |
|
|
| `UpgradePrompt` modal/banner | Upsell when locked |
|
|
| `TrialBanner` | Trial countdown / limits |
|
|
| `BundlePicker` | Multi-bundle select from SoT |
|
|
| `NeedsAssessmentForm` | RecommendationRequest fields |
|
|
| `PlanCard` / `PricingTable` | Pricing catalog display |
|
|
| `SubscriptionStatusCard` | Active/trialing/past_due actions |
|
|
| `AppsLauncherGrid` (entitlement-aware) | Replace dead dashboard cards |
|
|
| `SetupChecklist` | Activation → production steps |
|
|
| `DomainPolicyGuard` | Block custom domain until subscription active |
|
|
| Header `ColorModeToggle` | Expose existing provider |
|
|
| Platform `Sidebar` / command nav | Business OS navigation |
|
|
| Notification bell | Alerts |
|
|
|
|
---
|
|
|
|
## 6. Broken Navigation
|
|
|
|
| Issue | Detail |
|
|
| --- | --- |
|
|
| Dashboard dead ends | Four module cards have **no `href` / onClick** |
|
|
| Home → product hubs | Deep-links to hubs without entitlement check — may open empty/unauthorized modules |
|
|
| No path Home → Pricing → Subscribe | Missing routes |
|
|
| Header lacks Apps / Billing / Setup | Only Dashboard / Account / Admin |
|
|
| Onboarding complete → arbitrary first service | Skips dashboard OS; user may never see workspace summary |
|
|
| Tenant vs platform dual home | AppStoreGrid only on tenant host — platform users lose catalog after login unless they hunt URLs |
|
|
| Bundle service “باز کردن” before workspace | Can navigate to hubs pre-tenant |
|
|
|
|
---
|
|
|
|
## 7. API Gaps (frontend consumption)
|
|
|
|
| Capability | Backend/API note | FE usage |
|
|
| --- | --- | --- |
|
|
| Onboarding create/branding/domain/complete | Core APIs exist | Used |
|
|
| Tenant context (plan_name, subscription_status) | Returned | Display only; often empty |
|
|
| Subscriptions CRUD | `api.subscriptions.*` | **Admin only** |
|
|
| Plans list | `api.plans.list` | **Admin only** |
|
|
| Feature check | `features/check` | **Not used in tenant UI gates** |
|
|
| Commercial Foundation registries | Docs only — **no APIs** | N/A (expected) |
|
|
| Bundle select / license request / activation events | Contracts only | **No FE** |
|
|
| Recommendation evaluator | Contracts only | FE static map |
|
|
| Payment customer checkout for subscription | Not same as Payment hub MVP | Missing journey |
|
|
| Entitlement-aware apps list | Partial Core features | Missing |
|
|
|
|
---
|
|
|
|
## 8. Recommended execution order
|
|
|
|
1. **Dashboard rescue** — replace “بهزودی” cards with entitlement-aware app launcher (reuse `PLATFORM_APPS` + `TenantSwitcher` + links already in bundles).
|
|
2. **Onboarding commercial bridge** — after tenant create: explicit bundle confirm; call existing subscription/trial APIs if available; else clear “manual activation” state + admin path.
|
|
3. **Domain policy UX** — subdomain default; gate custom domain until `subscription_status=active` (or document temporary override).
|
|
4. **Feature locking + upgrade prompts** — wire `features/check` into hub entry and key actions.
|
|
5. **Needs assessment + type catalog alignment** — expand intents toward business-type catalog; collect size/goals flags (still FE/rules-local until evaluator exists).
|
|
6. **Billing pages** — tenant subscribe/trial/upgrade using existing Core plan/subscription endpoints (reuse admin patterns).
|
|
7. **Setup checklist** — guided links into Experience/Payment/… hubs.
|
|
8. **Shell polish** — header nav, dark mode toggle, skeletons, empty states, notifications shell.
|
|
9. **Codegen bundles from YAML** — when commercial FE phase registered (out of scope until authorized).
|
|
|
|
---
|
|
|
|
## 9. Priority list
|
|
|
|
### Critical
|
|
|
|
- Dashboard dead links / non-OS behavior
|
|
- Missing trial/subscription activation after onboarding (journey hard break)
|
|
- No feature/capability locking on product entry
|
|
- Custom domain allowed without active subscription (policy break)
|
|
|
|
### High
|
|
|
|
- Entitlement-aware apps launcher on dashboard
|
|
- Tenant billing/subscribe/trial UI (reuse Core APIs used by admin)
|
|
- Upgrade prompts
|
|
- Bundle confirm step + post-complete routing to dashboard (not random hub)
|
|
- Align business types with catalog (at least cafe split, missing types)
|
|
|
|
### Medium
|
|
|
|
- Needs assessment fields (size, employees, goals, flags)
|
|
- Domain management page
|
|
- Setup checklist / production readiness
|
|
- Header navigation (Apps, Billing, Setup)
|
|
- Loading skeletons + richer empty states on platform pages
|
|
- Dark mode toggle exposure
|
|
|
|
### Low
|
|
|
|
- Global search
|
|
- Notifications center
|
|
- a11y deep pass
|
|
- FE bundle codegen from commercial YAML
|
|
- Full 17-type marketing polish
|
|
|
|
---
|
|
|
|
## 10. Phased implementation plan (reuse existing pages)
|
|
|
|
> Do **not** replace Home / Onboarding / Dashboard. Extend them.
|
|
|
|
### Phase A — Dashboard as launcher (reuse `/dashboard`)
|
|
|
|
- Keep tenant summary card.
|
|
- Replace `QUICK_LINKS` with linked tiles from `PLATFORM_APPS` filtered by membership/features when available; fallback: bundle-recommended services for current tenant type.
|
|
- Add CTA: “تکمیل راهاندازی” → checklist section on same page.
|
|
- Add link to settings + billing placeholder route.
|
|
|
|
### Phase B — Onboarding bridge (reuse `/onboarding`)
|
|
|
|
- Keep 4 steps; insert or extend **review** with: confirmed bundle, trial checkbox, subdomain display.
|
|
- On complete: prefer `router.push("/dashboard")` then deep-links; optionally start trial via `api.subscriptions` if plan IDs known.
|
|
- Persist `businessType` / intent on tenant metadata if API allows; else localStorage bridge for dashboard recommendations.
|
|
|
|
### Phase C — Commercial rules (reuse dashboard + onboarding domain step)
|
|
|
|
- Domain step: emphasize subdomain; custom domain disabled with upgrade message unless subscription active.
|
|
- Wrap hub entry links with feature check (shared guard component).
|
|
- Trial banner on dashboard when `trialing`.
|
|
|
|
### Phase D — Billing UI (new routes, reuse admin subscription forms)
|
|
|
|
- Extract admin subscription form patterns into tenant `/billing`.
|
|
- Plans from `api.plans.list`; subscribe/trial; show license/plan on dashboard cards (already have fields).
|
|
|
|
### Phase E — Needs + catalog alignment (reuse `/` assess section + onboarding business step)
|
|
|
|
- Expand `BUSINESS_INTENTS` toward `business-type-catalog` codes (map IDs carefully).
|
|
- Add optional needs fields (employees, branches, website/delivery/crm flags) feeding local recommendation sort — still no new backend engine.
|
|
|
|
### Phase F — Shell (reuse `SiteHeader`, `ColorModeProvider`, DS)
|
|
|
|
- Header: Dashboard, Apps (`/dashboard#apps`), Billing, Account, theme toggle.
|
|
- Apply Skeleton/EmptyState on platform pages consistently.
|
|
|
|
**Explicitly deferred:** new products, Marketplace, QR, Booking, Payment 14.6+, Experience FE-11.6, commercial registry engines.
|
|
|
|
---
|
|
|
|
## Dashboard Audit (Step 4 summary)
|
|
|
|
**Current behavior:** weak **application launcher stub** (cards without links) + tenant metadata panel.
|
|
**Not** a business operating system (no setup, billing, entitlements, notifications, cross-product tasks, domain ops, upgrade).
|
|
|
|
**Missing OS capabilities:** apps rail, setup checklist, billing/trial, entitlement map, domain manager, team access (card says soon), branding manager (soon), search, notifications, upgrade, production readiness.
|
|
|
|
---
|
|
|
|
## Onboarding Audit (Step 5 summary)
|
|
|
|
| Field | Supported? |
|
|
| --- | --- |
|
|
| Business Type | Partial (8 intents) |
|
|
| Business Size | No |
|
|
| Industry | No (type only) |
|
|
| Country | No |
|
|
| Language | No (Experience workspace has language later) |
|
|
| Currency | No (Experience workspace has currency later) |
|
|
| Timezone | No (Experience workspace later) |
|
|
| Brand colors | Yes |
|
|
| Logo | Yes (URL only) |
|
|
| Domain preference | Partial (optional custom; no subdomain UX clarity) |
|
|
| Employees | No |
|
|
| Goals | No |
|
|
| Recommended services | Preview only |
|
|
| Bundle recommendation | Preview only |
|
|
| Trial creation | No |
|
|
| Workspace creation | Yes (tenant as workspace) |
|
|
|
|
---
|
|
|
|
## Commercial Rules Validation (Step 6 summary)
|
|
|
|
| Rule | UI support |
|
|
| --- | --- |
|
|
| Trial | No tenant UX |
|
|
| Demo period | No |
|
|
| Trial limits | No |
|
|
| Subscription | Admin only |
|
|
| License | No tenant UX |
|
|
| Bundle | Preview only |
|
|
| Entitlements | Not gated in UI |
|
|
| Recommended services | Yes (static) |
|
|
| Subdomain before payment | Not enforced / unclear UX |
|
|
| Custom domain only after active subscription | **Not enforced** |
|
|
| Feature locking | No |
|
|
| Capability locking | No |
|
|
| Upgrade prompts | No |
|
|
|
|
---
|
|
|
|
## STOP
|
|
|
|
Audit complete. **No implementation performed.** Await explicit authorization before Phase A+.
|