122 lines
6.4 KiB
Markdown
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.
|