freshyo/docs/consts-three-tables-part2-user-ui.md
2026-10-08 19:48:14 +05:30

122 lines
6.4 KiB
Markdown

# Plan — Part 2/2: user-ui (consume the per-bound flat JSON)
Part 2 of 2. Adapts **`apps/user-ui`** to request the precomputed flat JSON by `boundId` and read
the flat shape. Backend + admin UIs are Part 1
(`consts-three-tables-part1-backend-admin.md`) and must land first (the client depends on
`{ boundId }` input, `listRegions.effectiveBoundId`, and the flat payload).
## 0. Decisions
- user-ui **sends `boundId`** (persisted client-side) and reads the flat JSON.
- Scope: `apps/user-ui` only. `apps/web-ui` stays on the old contract (breaks; see §4).
- AGENTS.md: no test runs, no migrations, no git; log planned diffs to `change-log.txt` before
editing non-`.md`/`.txt` files.
## 1. Flat JSON contract (from Part 1)
`common.essentialConsts({ boundId })` returns the union of global + region + bound rows plus
identity/env:
```jsonc
{
"versionNum": "1.1.0", "playStoreUrl": "...", "appStoreUrl": "...", "internalAppVersion": 1,
"products_version_num": 2, "availability_version_num": 2, "slots_version_num": 2,
"popularItems": "[]", "allItemsOrder": "[]", "isFlashDeliveryEnabled": true,
"supportMobile": "...", "supportEmail": "...", "welcomeMessage": "...",
"minRegularOrderValue": 300, "freeDeliveryThreshold": 300, "deliveryCharge": 20,
"flashFreeDeliveryThreshold": 500, "flashDeliveryCharge": 69,
"assetsDomain": "...", "apiCacheKey": "...", "regionId": 1, "boundId": 7,
"webviewHtml": null, "isWebviewClosable": true
}
```
- `allItemsOrder` is the region's value (identical across bounds of the same region).
- The nested `effectiveSettings`/`regionSettings` block is gone.
- `EssentialConstsApiType` (`@backend/trpc/router`) already reflects this (derived from
`scaffoldEssentialConsts`).
## 2. Region-bound state (client must know its boundId)
Today the client knows only `regionId` (persisted in `regionStore`); the resolved bound is
transient. Changes:
### 2.1 `src/store/regionStore.ts`
- Add `selectedBoundId: number | null`.
- `setRegion(region: RegionSummary, boundId?: number | null)` persists both; include
`selectedBoundId` in `partialize`; extend the no-op guard to compare boundId.
### 2.2 `src/hooks/useRegion.ts`
- Expose `boundId` (from the store) on `UseRegionResult`.
- On a successful `resolveRegionByLocation`, persist
`setRegion(resolved.region, resolved.bound.id)` (instead of region-only).
### 2.3 `src/lib/region-switch.ts`
- `confirmRegionSwitch(region, queryClient, boundId?)` forwards the boundId to
`regionStore.setRegion` (manual picks get the region's effective bound id).
### 2.4 `src/components/RegionSelector.tsx`
- `listRegions` now returns `effectiveBoundId` per region → pass it through
`confirmRegionSwitch` so a manually chosen region still has a `boundId`.
## 3. Consuming the flat JSON
### 3.1 `src/hooks/prominent-api-hooks.ts`
- **`useGetEssentialConsts`**
- read `boundId` from `useRegion()` (not `regionId`);
- `trpc.common.essentialConsts.useQuery({ boundId }, { refetchInterval: 60000, enabled: isReady && boundId != null, placeholderData: initialData })`;
- persist under `` `essential_consts_b${boundId}` `` (was `essential_consts_r{regionId}`).
- **URL builders** (rename to the new keys):
- `useCacheUrl` / `useStoreWithProducts` → `products_version_num` (was `cacheVersion`);
- `useAvailabilityCacheUrl` → `availability_version_num`;
- `useSlotsCacheUrl` → `slots_version_num`;
- region id in URLs → `data.regionId` (via `useDiscoveryRegionId`, now reading the flat
`regionId` with `useRegion().regionId` fallback).
- **`useRegionalConsts`** → thin passthrough of the flat data (delivery values are already
top-level). Keep the exported function so `cart-page`, `checkout-page`, `floating-cart-bar`, and
`PaymentAndOrderComponent` need no edits.
- Remove the `effectiveSettings`/`regionSettings` fallback fields from `DiscoveryData` and the now
unused `discoverySettings` helper.
### 3.2 Unchanged (verify only)
- `cart-page.tsx`, `checkout-page.tsx`, `floating-cart-bar.tsx`, `PaymentAndOrderComponent.tsx`
keep reading `deliveryCharge` / `flashDeliveryCharge` / `freeDeliveryThreshold` /
`flashFreeDeliveryThreshold` / `minRegularOrderValue` (now flat).
- `AddToCartDialog.tsx` (`isFlashDeliveryEnabled`), `flash-delivery/_layout.tsx`
(`isFlashDeliveryEnabled`), `NextOrderGlimpse.tsx` (`supportMobile`),
`me/complaints/index.tsx` (`supportMobile`/`supportEmail`), `UpdateChecker.tsx`
(`internalAppVersion`), `HealthTestWrapper.tsx` (`versionNum`/`playStoreUrl`/`appStoreUrl`),
`WebViewWrapper.tsx` (`webviewHtml`/`isWebviewClosable`) — field names unchanged in the flat JSON.
- `LocationBar.tsx`, `LocationTestWrapper.tsx`, `FirstUserWrapper.tsx` — region-only; unaffected.
## 4. Out of scope / consequences
- **`apps/web-ui`** (`src/hooks/prominent-api-hooks.ts`) still calls
`common.essentialConsts({ regionId })` and reads `cacheVersion`/`availabilityVersionNum`/
`slotsVersionNum` → will fail input validation and show no data until migrated. Not in this plan.
- If the hard break must be avoided, Part 1 can add a `regionId` fallback (server maps to
`getEffectiveBoundId(regionId)`); then web-ui keeps working read-only. Decide before shipping.
## 5. Verification
0. Append planned diffs + timestamp to `change-log.txt` first.
1. Typecheck: `npx tsc --noEmit --project apps/user-ui/tsconfig.json`.
2. Smoke (after Part 1 is deployed + migration 0009 applied):
- Pick/auto-resolve a region → `boundId` persisted in `freshyo-region`.
- `common.essentialConsts` called with `{ boundId }`; payload cached under
`essential_consts_b{boundId}`.
- Catalog URLs contain `products_version_num` / `availability_version_num` /
`slots_version_num` and the correct `regionId`.
- Cart/checkout show the selected bound's delivery values; switching region updates them.
- Flash gate (`isFlashDeliveryEnabled`), update gate (`internalAppVersion`/`versionNum`),
support links, and webview notice all still work.
## 6. Checklist
1. `change-log.txt` — append planned diffs.
2. `src/store/regionStore.ts` — `selectedBoundId` + persist.
3. `src/hooks/useRegion.ts` — expose `boundId`; persist on resolve.
4. `src/lib/region-switch.ts` — forward boundId.
5. `src/components/RegionSelector.tsx` — use `effectiveBoundId`.
6. `src/hooks/prominent-api-hooks.ts` — `{ boundId }` input, per-bound cache key, renamed
version fields, simplified `useRegionalConsts`, drop `effectiveSettings` fallbacks.
7. Typecheck `apps/user-ui`; fix self-introduced errors.