123 lines
7.4 KiB
Markdown
123 lines
7.4 KiB
Markdown
# 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.2` is not purely temporary — the `cachePathPrefix` mechanism 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_postgres`** was not updated for regions (only `db_helper_sqlite` is
|
|
used by the deployed backend). If Postgres is ever reactivated, it needs the same
|
|
`region_id` work — no compat shims were added there.
|
|
- **User-app region *selection*** is deferred; hence §4.1.
|
|
|
|
---
|
|
|
|
## Quick removal checklist (when all clients are region-aware)
|
|
|
|
1. Delete `DEFAULT_REGION_ID` from `packages/shared/index.ts`.
|
|
2. Remove the legacy branches in §1 (and migrate region 1's counters/KV key/paths).
|
|
3. Make `regionId` **required** in §3a/§3b helpers + address zod.
|
|
4. Remove §3c's pinned `DEFAULT_REGION_ID`.
|
|
5. Remove `REGION_ID` from user-ui once it selects a region (§4.1).
|
|
6. Drop the `?? ''` fallback in user-ui (§4.2) once `cachePathPrefix` is always present.
|
|
7. Keep §2.2 (applied migration) untouched.
|