7.4 KiB
Backwards-Compatibility Shims (Region Scoping)
Purpose: temporary measures added during the region-scoping rollout to keep existing clients, stored data, and cache URLs working unchanged. Each item here should be removed once the condition in its "Remove when" column is met.
Last reviewed: region scoping initial implementation.
Background
Region scoping was added platform-wide. Every user/staff belongs to a region, and
almost every table gained a region_id. Region 1 is the legacy region — it
owns all data that existed before regions and is what every already-shipped client
implicitly uses. All shims below exist so that:
- old clients (which send no region) keep working, and
- region 1's cache URLs / KV keys / counters stay byte-for-byte identical to what they were before regions existed.
The central constant is DEFAULT_REGION_ID = 1 in packages/shared/index.ts:14.
1. Cache path / KV / version "legacy format" switches
These compare regionId === DEFAULT_REGION_ID (or regionId == null) to choose the
legacy format (no region segment) versus the region-scoped format
(r-<id>/, _<id> suffix). They must stay until all clients read region-scoped
URLs, because region 1's files are still written without a prefix.
| # | File:line | What it does | Remove when |
|---|---|---|---|
| 1.1 | apps/backend/src/lib/cloud_cache.ts:16 |
regionPathPrefix → '' for region 1, r-<id>/ otherwise |
No client relies on the un-prefixed (region 1) paths |
| 1.2 | apps/backend/src/lib/cloud_cache.ts:54 |
Empty-regions fallback → [DEFAULT_REGION_ID] |
Can drop if regions is guaranteed non-empty (region 1 always exists) |
| 1.3 | apps/backend/src/lib/cloud_cache.ts:63 |
createAllCacheFiles returns region 1's result object |
Callers no longer expect region 1's result shape |
| 1.4 | apps/backend/src/lib/cloud_cache.ts:129 |
resolveRegionIds empty-regions fallback → [DEFAULT_REGION_ID] |
Same as 1.2 |
| 1.5 | apps/backend/src/lib/cloud_cache.ts:153 |
createAvailabilityCacheFile no-region call returns region 1's version |
Standalone availability callers no longer expect region 1's version |
| 1.6 | apps/backend/src/lib/cloud_cache.ts:203 |
createSlotsCacheFile no-region call returns region 1's version |
Standalone slots callers no longer expect region 1's version |
| 1.7 | apps/backend/src/lib/gen-store.ts:8 |
regionKvKey → legacy essential_consts key for region 1, essential_consts_<id> otherwise |
No client reads the legacy essential_consts KV key |
| 1.8 | apps/backend/src/lib/gen-store.ts:33 |
refreshGenKv also writes the legacy essential_consts key when region is 1/null |
Same as 1.7 |
| 1.9 | apps/backend/src/trpc/apis/common-apis/common-trpc-index.ts:33 |
scaffoldEssentialConsts.cachePathPrefix → '' for region 1, r-<id>/ otherwise |
Clients stop needing the legacy (empty) prefix |
| 1.10 | packages/db_helper_sqlite/src/admin-apis/const.ts:9 |
versionKey → legacy counters (cache_version, …) for region 1, <counter>_<id> otherwise |
No client reads the legacy un-suffixed counters |
How to remove the whole section: once every client is region-aware, drop the
regionId === DEFAULT_REGION_ID legacy branches and always emit the region-scoped
format (and migrate/rename region 1's existing counters + KV key, or keep region 1
as a normal region).
2. Region-1 data assumptions (kept during migration)
| # | File:line | What it does | Remove when |
|---|---|---|---|
| 2.1 | packages/db_helper_sqlite/src/admin-apis/product.ts:1089 |
backfillMarketStatsForRegion copies default prices from region 1's market-stats row |
Backfill no longer needs a seed source (or a different seed region is chosen) |
| 2.2 | packages/db_helper_sqlite/drizzle/0007_region_scoping.sql (DEFAULT 1 on all region_id columns) |
Migration backfills every existing row to region 1 | Keep permanently as history (do not edit an applied migration) — informational only |
3. Optional regionId on user-facing APIs (default to 1)
The user-facing request handlers and db helpers keep regionId optional and
default to DEFAULT_REGION_ID when absent, so old app builds (which send no region)
keep working. Admin paths were made required already.
3a. User-facing db helpers — regionId: number = DEFAULT_REGION_ID
| File | Occurrences |
|---|---|
packages/db_helper_sqlite/src/stores/store-helpers.ts |
9 (lines 41, 95, 142, 163, 198, 219, 273, 290, 329) |
packages/db_helper_sqlite/src/user-apis/product.ts |
5 (lines 21, 157, 236, 295, 339) |
packages/db_helper_sqlite/src/user-apis/stores.ts |
3 (lines 20, 71, 146) |
packages/db_helper_sqlite/src/user-apis/slots.ts |
2 (lines 22, 34) |
packages/db_helper_sqlite/src/user-apis/banners.ts |
1 (line 24) |
packages/db_helper_sqlite/src/user-apis/order.ts |
1 (line 190) |
apps/backend/src/stores/product-tag-store.ts:89 |
getTagsByStoreId(storeId, regionId = DEFAULT_REGION_ID) |
Remove when: the user app sends its region on every request → make these params required and drop the defaults (mirror the admin helpers).
3b. Address add/update — defaults to 1
| # | File:line | What it does | Remove when |
|---|---|---|---|
| 3.1 | packages/db_helper_sqlite/src/user-apis/address.ts:88 |
createUserAddress → regionId: input.regionId ?? DEFAULT_REGION_ID |
User app always sends regionId on address create |
| 3.2 | apps/backend/src/trpc/apis/user-apis/apis/address.ts (create/update zod) |
regionId is .optional() |
Same as 3.1 |
3c. Public procedure still pinned to region 1
| # | File:line | What it does | Remove when |
|---|---|---|---|
| 3.3 | apps/backend/src/trpc/apis/admin-apis/apis/vendor-snippets.ts:268 |
Public getUpcomingSlots passes DEFAULT_REGION_ID to getSlotsAfterDate |
The vendor/public page can pass a real region |
4. Hardcoded client region
| # | File:line | What it does | Remove when |
|---|---|---|---|
| 4.1 | apps/user-ui/src/constants.ts:3 |
export const REGION_ID = 1 — the user app is pinned to region 1 |
User app gains real region selection (derive from the user's address/default region) |
| 4.2 | apps/user-ui/src/hooks/prominent-api-hooks.ts:72,86,100,225 |
Reads essentialConsts.cachePathPrefix ?? '' and prepends it to cache URLs |
Keep the prefix logic permanently; only the ?? '' fallback can go once all responses include the field |
Note:
4.2is not purely temporary — thecachePathPrefixmechanism is the permanent way clients build region-scoped URLs. Only the empty-string fallback is a compat crutch.
5. Out of scope but related
db_helper_postgreswas not updated for regions (onlydb_helper_sqliteis used by the deployed backend). If Postgres is ever reactivated, it needs the sameregion_idwork — no compat shims were added there.- User-app region selection is deferred; hence §4.1.
Quick removal checklist (when all clients are region-aware)
- Delete
DEFAULT_REGION_IDfrompackages/shared/index.ts. - Remove the legacy branches in §1 (and migrate region 1's counters/KV key/paths).
- Make
regionIdrequired in §3a/§3b helpers + address zod. - Remove §3c's pinned
DEFAULT_REGION_ID. - Remove
REGION_IDfrom user-ui once it selects a region (§4.1). - Drop the
?? ''fallback in user-ui (§4.2) oncecachePathPrefixis always present. - Keep §2.2 (applied migration) untouched.