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

4 KiB

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:
    { 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).