docs: add Multi-Surface Feature Parity Guide

Multi-Surface Feature Parity Guide.md

@@ -0,0 +1,212 @@
+# Multi-Surface Feature Parity Guide
+
+> **Rule source:** AGENTS.md §8 — every feature change must be evaluated against all 4 surfaces and ported where an equivalent exists.
+
+---
+
+## The 4 surfaces at a glance
+
+```
+/dashboard/seller/*          → Seller Dashboard
+/dashboard/request-template/* → Seller Dashboard (product/template management)
+/dashboard/shop-settings/*   → Seller Dashboard (shop branding & settings)
+
+/shop/*                      → Platform Marketplace (public)
+/dashboard/shops/*           → Platform Marketplace (buyer logged-in)
+
+/dashboard/shop/[slug]/*     → White-label Shop Platform (tenant admin)
+/store/*                     → White-label Shop Platform (public storefront)
+
+/telegram/*                  → Telegram Mini App
+```
+
+---
+
+## Surface primitives — never mix
+
+### Seller Dashboard + Platform Marketplace
+Both share the same layout and component system.
+
+| Concern | Primitive |
+|---|---|
+| Layout | `DashboardContent`, `Card`, `CustomBreadcrumbs` (MUI) |
+| Styling | MUI `sx` + `theme.vars.palette.*` — no hex colors (see rule §1) |
+| Strings | `useTranslate()` → `src/locales/langs/en/common.json` + `fa/common.json` |
+| Data | `useSWR` + `src/actions/*.ts` hooks |
+| Components | MUI + `src/components/*` |
+
+### White-label Shop Platform
+Uses the same MUI/SWR stack but a **different layout shell**.
+
+| Concern | Primitive |
+|---|---|
+| Layout | `ShopDashboardLayout` (`src/sections/shop/shop-dashboard-layout.tsx`) for admin; `StorefrontLayout` (`src/sections/storefront/storefront-layout.tsx`) for public |
+| Sections | `src/sections/shop/shop-*.tsx`, `src/sections/storefront/storefront-*.tsx` |
+| Strings | Same `useTranslate()` → `common.json` |
+| Data | Same `src/actions/*.ts` — **reuse actions, don't duplicate** |
+
+### Telegram Mini App
+Completely different design system — **never import MUI here**.
+
+| Concern | Primitive |
+|---|---|
+| Layout | Full-bleed mobile, `TelegramTabBar`, bottom-sheets |
+| Styling | `TG_PALETTE` CSS vars (`var(--tg-saffron-600)`, `var(--tg-ink-700)`, etc.) via `inline style={{}}` |
+| Strings | `t` prop typed as `TelegramDict` — add to `locales/en.ts` + `locales/fa.ts` + declare in `locales/types.ts` |
+| Data | `src/sections/telegram/hooks/use-telegram-*.ts` (wrap the same `src/actions/*.ts` calls) |
+| Components | `src/sections/telegram/components/telegram-*.tsx` only |
+
+---
+
+## Feature → surface mapping
+
+Legend: ✅ full  ⚠️ partial (read/display only)  ❌ not present  🔮 planned
+
+### Product Templates (کالا)
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Create / edit template | ✅ `request-template-create/edit-view` | ❌ | ❌ | ❌ |
+| Template list (my products) | ✅ `request-template-list-view` | ❌ | ✅ `shop-catalog-view` | ❌ |
+| Template detail (buyer) | ❌ | ✅ `request-template-shop-details-view` | ✅ `storefront-item-view` | ✅ `telegram-template-detail-view` |
+| Browse all templates | ❌ | ✅ `public-shops-view` | ✅ `storefront-catalog-view` | ✅ `telegram-shop-view` |
+
+### Collections (مجموعه)
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Create / edit collection | ✅ `seller-collections-new-edit-form` | ❌ | ❌ | ❌ |
+| Browse by collection | ❌ | 🔮 | 🔮 | 🔮 |
+| Collection detail (buyer) | ❌ | 🔮 | 🔮 | 🔮 |
+
+### Shop / Seller Profile
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| My shop overview | ⚠️ `shop-settings/*` | ❌ | ✅ `shop-overview-view` | ❌ |
+| Public shop page | ❌ | ✅ `public-seller-shop-view`, `seller-profile-view` | ✅ `storefront-catalog-view` | ✅ `telegram-seller-shop-view` |
+| Shop branding / settings | ✅ `shop-settings/` | ❌ | ✅ `shop-settings-view` | ❌ |
+| Shop admins | ❌ | ❌ | ✅ `shop-admins-view` | ❌ |
+
+### Requests (درخواست‌ها)
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Request list (seller side) | ✅ `seller/marketplace` | ❌ | ✅ `shop-orders-view` | ✅ `telegram-requests-view` |
+| Request list (buyer side) | ❌ | ✅ `/dashboard/request` | ❌ | ✅ `telegram-requests-view` |
+| Request detail | ✅ | ✅ | ✅ | ✅ `telegram-request-detail-view` |
+| Create new request | ❌ | ✅ `/dashboard/request/new` | ✅ | ✅ `telegram-new-request-view` |
+| Request from template | ❌ | ✅ `/dashboard/request/from-template` | ✅ | ✅ |
+| Archived requests | ❌ | ✅ | ❌ | ✅ `telegram-archived-requests-view` |
+
+### Chat
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Chat list | ✅ `/dashboard/chat` | ✅ | ❌ | ✅ `telegram-chat-view` |
+| Chat thread | ✅ | ✅ | ❌ | ✅ `telegram-chat-thread-view` |
+| Archived chats | ❌ | ✅ | ❌ | ✅ `telegram-archived-chats-view` |
+
+### Analytics & Reporting
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Analytics dashboard | ✅ `seller-analytics-view` | ❌ | ✅ `shop-overview-view` | ❌ |
+| Home stats summary | ❌ | ❌ | ❌ | ✅ `telegram-home-stats` |
+
+### Inventory
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Inventory list | ✅ `inventory-list-view` | ❌ | ✅ `shop-inventory-view` | ❌ |
+| Inventory detail | ✅ `inventory-detail-view` | ❌ | ⚠️ | ❌ |
+
+### Customers & Reviews
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Customer list | ✅ `seller-customers-view` | ❌ | ✅ `shop-customers-view` | ❌ |
+| Reviews | ✅ `seller-reviews-view` | ❌ | ❌ | ❌ |
+
+### Payments & Wallet
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Cart | ❌ | ✅ `/dashboard/shops/checkout` | ✅ `/store/checkout` | ✅ `telegram-cart-view` |
+| Checkout | ❌ | ✅ `request-template-checkout-view` | ✅ | ✅ `telegram-checkout-view` |
+| Payment flow | ✅ | ✅ | ✅ | ✅ `telegram-payment-view` |
+| Payment history | ✅ | ✅ | ✅ | ✅ `telegram-payment-history-view` |
+| Wallet | ✅ `/dashboard/account/wallet` | ✅ | ❌ | ✅ `telegram-wallet-view` |
+
+### Account & Profile
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| Profile settings | ✅ `/dashboard/account` | ✅ | ✅ | ✅ `telegram-account-view` |
+| Delivery addresses | ✅ `/dashboard/account/address` | ✅ | ❌ | ✅ `telegram-addresses-view` |
+| Notifications settings | ✅ | ✅ | ❌ | ✅ `telegram-notifications-view` |
+| Passkey / security | ✅ | ✅ | ❌ | ❌ |
+
+### Other
+
+| Feature | Seller Dash | Platform | White-label | Mini App |
+|---|---|---|---|---|
+| AI Assist | ✅ `/dashboard/assist` | ✅ | ❌ | ✅ `telegram-settings-view` (assist tab) |
+| Points / loyalty | ✅ `/dashboard/points` | ✅ | ❌ | ✅ `telegram-points-view` |
+| Disputes | ✅ `/dashboard/disputes` | ✅ | ❌ | ❌ |
+| Posts / blog | ✅ `/dashboard/post` | ✅ `/post` | ❌ | ❌ |
+| Dynamic pricing | ✅ (admin) | ❌ | ❌ | ❌ |
+
+---
+
+## Porting recipes by change type
+
+### Text / copy change
+1. Update `en/common.json` + `fa/common.json` (covers Seller Dash, Platform, White-label).
+2. Find the matching key in `src/sections/telegram/locales/types.ts` → update `locales/en.ts` + `locales/fa.ts`.
+3. If key doesn't exist in Mini App yet: declare it in `TelegramDict` (types.ts) first.
+
+### New field displayed on an entity card/row
+1. Find every view that renders that entity (use mapping table above).
+2. Add the field to each view using **that surface's primitives** — no MUI inside telegram, no TG_PALETTE outside it.
+3. Add locale strings for every surface involved.
+
+### New status / enum value
+1. Update `TG_REQUEST_STATUS_VARIANT` or `TG_ESCROW_STATE_CHIPS` in `src/sections/telegram/constants.ts`.
+2. Update the corresponding color/label map in `src/sections/request/constants.ts` (used by Seller Dash + Platform).
+3. Add the label string to all locale files.
+4. Check `shop-orders-view.tsx` for any inline status chip that also needs updating.
+
+### New API field on a shared type
+1. Update the type in `src/types/*.ts`.
+2. Update `src/actions/*.ts` — the normalization function that maps API responses to the type.
+3. All 4 surfaces reuse the same types and actions — they get the field for free once it's in the type.
+4. Decide per surface whether to **display** it (add UI) or just carry it silently.
+
+### Platform has a feature Seller Dashboard is missing
+Platform (`/shop/*`) was built later and has richer discovery, cart, and public browsing. If Platform adds something that would benefit sellers too (e.g. a filter, a sort option, a field on a product card), evaluate adding it to the Seller Dashboard equivalent view in the same PR.
+
+---
+
+## What's intentionally surface-specific (do NOT port)
+
+| Feature | Where only | Why |
+|---|---|---|
+| Template CRUD (create/edit) | Seller Dashboard | Sellers create products; buyers only view |
+| Collection CRUD | Seller Dashboard | Sellers organize; buyers browse (future) |
+| Shop admins management | White-label only | Multi-admin is a tenant feature |
+| Admin dashboard (networks, trezor, thresholds, AML) | Dashboard `/admin/*` | Platform operator only |
+| Haptic feedback | Mini App only | Telegram Web App SDK, no equivalent on web |
+| TG_PALETTE dark/light toggle | Mini App only | Uses Telegram's native color scheme |
+| Tenant slug routing `[tenantSlug]` | White-label only | Multi-tenant feature |
+
+---
+
+## Checklist before merging
+
+- [ ] Identified which surface(s) the change affects
+- [ ] Checked all 3 other surfaces against the mapping table
+- [ ] Ported to every surface with a full or partial equivalent
+- [ ] Used each surface's own primitives (no cross-contamination)
+- [ ] Added locale strings to all surfaces involved (both fa + en)
+- [ ] PR description names every surface updated — and explicitly names any surface skipped