freshyo/docs/impl-plans/phase-4-superadmin-ui.md
2026-10-10 15:00:50 +05:30

85 lines
4 KiB
Markdown

# Phase 4 — Superadmin UI (`apps/superadmin-ui`)
Status: **not started.**
Depends on: **Phase 2 backend** (routers + helpers). Phase 3 independent.
## 1. Goal
Give superadmins screens to **create/edit/delete global stores** and **create/edit/delete
global products**, including the initial per-region market values that get seeded to every
region.
## 2. App shape (for reference)
- `apps/superadmin-ui` is a **TanStack Router** web app (Vite + Cloudflare).
- Routes are **file-based** in `src/routes/*.tsx`; `src/routeTree.gen.ts` is **generated** (do
not hand-edit — it regenerates when Vite runs / builds).
- Nav lives in `src/components/AppShell.tsx` (`NAV` array, `lucide-react` icons).
- Auth/context: `src/lib/auth-context.tsx`; tRPC client uses `trpc.superadmin.*`.
- Existing routes: `dashboard`, `regions`, `staff`, `constants`, `send-notifications`, `login`.
## 3. Backend surface used (Phase 2)
```
trpc.superadmin.globalStores.list | get | create | update | delete
trpc.superadmin.globalProducts.list | get | create | update | delete
```
- Global store `create/update`: `{ name, description?, imageUrl? }` (no owner, no region).
- Global product `create`: full structure
`{ name, shortDescription?, longDescription?, storeId (global), incrementStep?, productType?,
skus: [{ name?, images?, isComboOnly?, features[], comboItems? }] }`
**plus** initial market values per SKU
`{ price, marketPrice?, flashPrice?, isFlashAvailable?, isOutOfStock?, isOffer? }`
which the backend seeds to **every region**.
- Global product `update`: structural edit (name/SKUs/etc.) — regenerates all regions.
(Per-region market data is edited by regional admins in Phase 3; optionally expose a
per-region matrix here too — see §7.)
## 4. New routes / components
- `src/routes/global-stores.tsx` — list + create/edit (inline drawer or a `$id` sub-route
following the `regions.tsx` pattern) + delete. Reuse the image-upload flow used elsewhere
(check how `regions.tsx`/banners handle uploads; if none, add a presigned-URL uploader like
`admin-ui`'s `useUploadToObjectStorage`).
- `src/routes/global-products.tsx` — list + create/edit + delete.
- New components under `src/components/`:
- `GlobalStoreForm.tsx`
- `GlobalProductForm.tsx` (structure editor + initial market-values block per SKU).
- `src/components/AppShell.tsx` — add NAV entries:
```ts
{ to: '/global-stores', label: 'Global Stores', icon: Store /* or Storefront */ },
{ to: '/global-products', label: 'Global Products', icon: Package /* or Boxes */ },
```
(`lucide-react` icons).
> After adding files under `src/routes/`, run the dev server / build once so `routeTree.gen.ts`
> regenerates before typecheck.
## 5. Behaviour
- Global store create/edit → backend regens **all** regions' caches.
- Global product create → seeds market-stats rows for **every** region from the entered values.
- Global product structural delete → removes the product, its SKUs and all regions' market
rows; regen all regions.
- Global product edit → structural changes regen all regions; if a per-region editor is added
(§7) it must call the same backend scoping as admins.
## 6. Verification
1. `bunx tsc --noEmit` in `apps/superadmin-ui` (confirm `routeTree.gen.ts` is regenerated).
2. Manual (dev server): create a global store → appears in every region's admin store list
(Phase 3); create a global product with an initial price → a market-stats row exists for
each region and `availability.json` shows that price until a region overrides it.
## 7. Optional / follow-ups
- A superadmin **per-region market matrix** (rows = regions, columns = price/stock) on the
global product screen, backed by a superadmin-scoped market-stats update.
- Batch "seed/repair" action for regions missing rows for older global SKUs.
- Note: new regions seed from the **least-id region's** rows (see Phase 2). To change the
defaults future regions inherit, edit the least-id region's rows first.
## 8. Out of scope
Regional admin editing (Phase 3) and any schema/backend work (Phase 2).