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

109 lines
5.2 KiB
Markdown

# Phase 3 — Admin UI (React-Native `admin-ui` + web `admin-web`)
Status: **not started.**
Depends on: **Phase 2 backend.**
## 1. Goal
Let a regional admin:
1. see **global + regional** products on the Products page;
2. edit a **global** product's **market data only** (price / stock / offer / region
suspension) — everything else read-only — via a **separate component**;
3. see **global stores read-only** (no edit/delete).
## 2. Shared types (`packages/shared/types/*`)
- `Store`: add `isGlobal: boolean`; change `owner` to `number | null`.
- `AdminProduct` (and `AdminProductWithRelations`): add `isGlobal: boolean` (derived from the
store) so lists/edits can branch without a second call.
- No change to `AdminSku` shape (it already carries all market flags).
> Confirm exact files: `packages/shared/types/admin.ts` (`Store`, `AdminProduct`).
## 3. Server contract (from Phase 2 — restate so the UI is built to match)
- `admin.product.getProducts` / `getProductById` return global + regional; each product has
`isGlobal`.
- `admin.store.getStores` / `getStoreById` return global stores with `isGlobal: true`,
`owner: null`.
- `admin.product.updateProduct` **for a global product** accepts **only** market fields:
`price`, `marketPrice`, `flashPrice`, `isFlashAvailable`, `isOutOfStock`,
`isSuspendedInRegion`, `isOffer`. Structural fields are rejected/ignored.
- `admin.product.updateProductPrices` / `toggleOutOfStock` remain region-scoped and work on
global SKUs.
- Admins get 403/error for global store create/update/delete and global product
create/delete.
## 4. `admin-ui` (Expo / React Native)
### Products list — `app/(drawer)/dashboard/products/index.tsx`
- Show global + regional products.
- Add a **Global** badge on global rows/cards.
- Optionally a filter chip `All / Regional / Global` alongside the existing
`all / in-stock / out-of-stock` chips (`FilterType`).
- `onEdit(id)` → navigates to `products/edit?id=…` as today; the edit screen branches.
### Products edit — `app/(drawer)/dashboard/products/edit.tsx`
- After `trpc.admin.product.getProductById`, branch on `product.isGlobal`:
- **regional** → existing `ProductForm` (+ add/update flows unchanged).
- **global** → render the **new `GlobalProductForm`**.
- Keep the existing image-upload / mutation plumbing for the regional path.
### New component — `src/components/GlobalProductForm.tsx`
- **Read-only** (rendered as text/locked): name, short/long description, store, increment
step, product type, per-SKU name + images + features, combo items.
- **Editable**: a per-SKU market block — `price`, `marketPrice`, `flashPrice`,
`isFlashAvailable`, `isOutOfStock`, `isOffer`, `isSuspendedInRegion`.
- Submit → `admin.product.updateProduct` with **only** the market fields (never structural).
- Show a hint banner: "Global product — shared across regions. You can edit price & stock for
your region only."
### Products add — `app/(drawer)/dashboard/products/add.tsx`
- Unchanged (admins cannot create global products). Optionally hide/note global store choices
in the store picker (a regional product can't be assigned to a global store).
### Stores list — `app/(drawer)/dashboard/stores/index.tsx`
- Show global stores with a **Global** badge.
- **Disable edit/delete** for global stores (read-only). Keep them visible.
### Stores edit — `app/(drawer)/dashboard/stores/edit.tsx`
- If the store `isGlobal`: render read-only (no submit) with a "Global store — managed by a
superadmin" banner.
### Store picker (in `ProductForm` / `ProductsSelector`)
- Ensure global stores don't appear as selectable owners/stores for regional product creation
(or are clearly marked and rejected by the backend).
## 5. `admin-web` (TanStack Router)
Mirror §4:
- `src/routes/dashboard.products.tsx` — global badge + optional filter.
- `src/routes/dashboard.products.edit.tsx` — branch to a new
`src/components/GlobalProductForm.tsx` when `product.isGlobal`.
- `src/routes/dashboard.products.new.tsx` — unchanged.
- `src/routes/dashboard.stores.tsx` — global badge, edit/delete disabled.
- `src/routes/dashboard.stores.edit.tsx` — read-only for global.
- Reuse the same field rules; share the market-fields type from `@packages/shared` if helpful.
## 6. Verification
1. `bunx tsc --noEmit` on both apps (compare any pre-existing web-ui/admin-web error counts).
2. Manual/RTL smoke (only if asked — *not* the full suite):
- Products page lists a seeded global product with a badge.
- Editing it shows read-only structure + editable market fields; saving changes **only**
the caller region's price/stock (verify via `availability.json`).
- Global store rows show a badge and have no edit/delete action.
3. No migrations, no test-suite run (unless the user asks).
## 7. Risks / notes
- `admin-ui` and `admin-web` both have a `ProductForm`; keep them behaviourally consistent
but don't force a shared component across the RN/web boundary.
- The global edit must never send structural fields — the backend rejects them, but avoid
surfacing false "saved" states.
- `owner: number | null` change ripples to store display components (`StoreItem`, store
detail) — handle null ("Global" / "—").
## 8. Out of scope
Superadmin creation/editing of global entities (Phase 4).