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

6.4 KiB

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:

{
  "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

  1. Append planned diffs + timestamp to change-log.txt first.
  2. Typecheck: npx tsc --noEmit --project apps/user-ui/tsconfig.json.
  3. 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.