# 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