freshyo/docs/region-backwards-compat.md
2026-10-05 11:46:47 +05:30

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.