# Phase 1 — Per-region `product_market_stats` Status: **✅ implemented 2026-10-10** (backend + sqlite helper; migration folded into `0006`). Depends on: nothing. Blocks: Phases 2–4. > **Implementation notes** > - New `packages/db_helper_sqlite/src/lib/market-stats.ts` (`marketStatsForRegion`, > `isMarketStatsSuspended`). > - `productSkus.marketStats` is now a `many` relation; every `with: { marketStats: true }` > site picks the region row. > - `getProductDetailById` / `getProductById` (user + order) derive the region from the SKU's > product row; `getAllProductsWithUnits` picks per-SKU region. > - `getOrderProductById` now returns a single region-picked `marketStats` object; the order > path reads `product.isSuspended` (global) / `product.marketStats?.isSuspendedInRegion`. > - Suspension: a SKU is unavailable when `product_skus.is_suspended` (global) **or** > `product_market_stats.is_suspended_in_region` (per region) — helper `isSkuSuspended`. The > admin product write still sets the **global** `productSkus.isSuspended` in Phase 1; the > superadmin/region split lands in Phase 2. > - `getAvailabilityForCache` / `getProductAvailability` / `getSuspendedSkuIds` / > `updateProductPrices` / `toggleProductOutOfStock` / `updateProduct` / `createProduct` are > all region-filtered. > - The `0006` copy backfills every pre-existing market-stats row to the seeded region > (Mahabubnagar), matching the product backfill — so a fresh apply leaves regions 2+ empty > until products are created there (as before). > - Verified: `tsc --noEmit` backend/admin-ui/user-ui PASS (web-ui's 12 pre-existing errors > unchanged); `0000`→`0006` + data on a fresh DB yields `region_id=1`, `is_offer`, > `is_suspended_in_region` correctly. ## 1. Goal Turn `product_market_stats` from **1 row per SKU** into **1 row per (SKU, region)** so that a region's price / stock / offer / suspension live in that region's own row. This phase does **not** introduce global products yet — it only makes the market data region-scoped. **Success criterion:** after Phase 1, the customer caches (`products.json`, `availability.json`) and admin product screens for regions 1/2/3 are **identical to today** (same prices, stock, availability). No behaviour change for existing regional products. ## 2. Non-goals - No `is_global`, no `store_info`/`product_info` changes, no superadmin UI. - No global products (that's Phase 2). The region a market-stats row belongs to is derived from the SKU's product row. ## 3. Data model ### `packages/db_helper_sqlite/src/db/schema.ts` `productMarketStats` (currently lines ~204–214): ```ts export const productMarketStats = sqliteTable('product_market_stats', { id: integer().primaryKey({ autoIncrement: true }), skuId: integer('sku_id').notNull().references(() => productSkus.id), regionId: integer('region_id').notNull().references(() => regions.id), marketPrice: numericText('market_price'), ourPrice: numericText('our_price').notNull(), isFlashAvailable: integer('is_flash_available', { mode: 'boolean' }).notNull().default(false), flashPrice: numericText('flash_price'), isOutOfStock: integer('is_out_of_stock', { mode: 'boolean' }).notNull().default(false), isSuspendedInRegion: integer('is_suspended_in_region', { mode: 'boolean' }).notNull().default(false), isOffer: integer('is_offer', { mode: 'boolean' }).notNull().default(false), }, (t) => ({ unq_sku_region: uniqueIndex('product_market_stats_sku_region').on(t.skuId, t.regionId), })) ``` Changes vs today: - `skuId` loses `.unique()` (was 1:1). - **new** `regionId` (NOT NULL, FK `regions`). - **new** `isSuspendedInRegion` (bool, default false). The old market-stats `isSuspended` is **removed** — global suspension now lives on the SKU (`productSkus.isSuspended`), and its existing values are backfilled there. - **new** table-level unique index `(sku_id, region_id)`. - `productSkus` gains `isSuspended` (bool, default false) — the global (superadmin) kill-switch. ### Relations - `productSkusRelations`: `marketStats: one(productMarketStats)` → **`many(productMarketStats)`**. - `productMarketStatsRelations`: add `region: one(regions, { fields: [productMarketStats.regionId], references: [regions.id] })`. > A SKU now carries an **array** of market-stats rows. Every consumer must pick the row for > its `regionId` (helper below). ## 4. Schema change goes into `0006` (no new migration) `packages/db_helper_sqlite/drizzle/0006_regions_and_superadmins.sql` is **not applied yet** and already rebuilds `product_market_stats` via `__new_product_market_stats`. Fold the per-region fields into that rebuild instead of a standalone `0010` recreate — `0006` already rebuilds the whole FK subgraph in dependency order, so no extra recreate is required. ### Edits to `0006_regions_and_superadmins.sql` 1. **`CREATE TABLE __new_product_market_stats`** — the `is_offer` column is already folded in (from `0009`, see README); now add the region column + FK and the region-suspension flag: ```sql `region_id` integer NOT NULL, ... `is_suspended_in_region` integer DEFAULT false NOT NULL, ... FOREIGN KEY (`region_id`) REFERENCES `regions`(`id`) ON UPDATE no action ON DELETE no action ``` 2. **Its copy `INSERT INTO __new_product_market_stats … SELECT …`** — add `region_id` and `is_suspended_in_region` (the copy already selects `is_offer` and JOINs `product_skus` from the `0009` fold). All pre-existing rows are backfilled to Mahabubnagar: ```sql INSERT INTO `__new_product_market_stats` (`id`,`sku_id`,`region_id`,`market_price`,`our_price`,`is_flash_available`,`flash_price`,`is_out_of_stock`,`is_suspended`,`is_suspended_in_region`,`is_offer`) SELECT ms.`id`, ms.`sku_id`, (SELECT `id` FROM `regions` WHERE `name` = 'Mahabubnagar'), ms.`market_price`, ms.`our_price`, ms.`is_flash_available`, ms.`flash_price`, ms.`is_out_of_stock`, ms.`is_suspended`, false, COALESCE(ps.`is_offer`, false) FROM `product_market_stats` ms JOIN `product_skus` ps ON ps.`id` = ms.`sku_id`; ``` - The `JOIN product_skus` (already present from the `0009` fold) prunes **orphan** market-stats rows whose SKU no longer exists. 3. **Replace the index** created at the end of `0006`: `CREATE UNIQUE INDEX product_market_stats_sku_id_unique ON product_market_stats (sku_id)` → `CREATE UNIQUE INDEX product_market_stats_sku_region ON product_market_stats (sku_id, region_id)`. **Validation:** apply the edited `0006` (from `0000`) to a **fresh** DB copy; confirm `pragma table_info(product_market_stats)` shows `region_id` + `is_suspended_in_region`, the new unique index exists, and there is exactly one row per SKU with `region_id` = the seeded region. ## 5. Region-aware access helper Add a small shared helper (e.g. `packages/db_helper_sqlite/src/lib/market-stats.ts`): ```ts export type MarketStatsRow = InferSelectModel export function marketStatsForRegion(stats: MarketStatsRow[] | undefined, regionId: number): MarketStatsRow | undefined { return stats?.find((s) => s.regionId === regionId) } ``` Where a function does not currently receive a `regionId` (see §6), derive it from the SKU's product row (`sku.product.regionId`) in this phase. ## 6. Code changes Every `with: { marketStats: true }` now returns an **array**; every `.marketStats` read must pick the region's row and suspension must test **both** flags (`!is_suspended && !is_suspended_in_region`). ### `packages/db_helper_sqlite/src/stores/store-helpers.ts` | Site | Change | |---|---| | `getAllProductsForCache` (~121,126,129) | `marketStats` array → `marketStatsForRegion(..., regionId)`; suspension check adds `isSuspendedInRegion`; region filter stays `product.regionId === regionId` (Phase 2 adds global). | | `getAvailabilityForCache` (~154) | query is already `productMarketStats.findMany` — add `eq(productMarketStats.regionId, regionId)` and filter `!isSuspended && !isSuspendedInRegion`. | | `getAllProductCombosForCache` (~246,274) | `ci.sku.marketStats` → pick region row. | | suspended-sku set (~252–260) | add `regionId` to the `where`. | | `getAllSlotsWithProductsForCache` (~389,408) | pick region row; suspension filter adds region flag. | ### `packages/db_helper_sqlite/src/user-apis/product.ts` | Site | Change | |---|---| | `getProductDetailById(skuId)` (~12–31) | no region param → derive `sku.product.regionId`; pick row; suspension check both flags. | | combo items (~56,68) | pick region row. | | `getProductById(skuId)` (~143–165) | derive region from product; pick row. | | `getAllProductsWithUnits(tagId?)` (~217) | **no region** — add a `regionId` parameter (see below). | | `getSuspendedSkuIds(regionId)` (~271) | add `regionId` filter to the query. | | `getAllSkusSummary(regionId)` (~347) | pick region row; suspension check both flags. | > `getAllProductsWithUnits` is only consumed by the legacy controller > `apps/backend/src/apis/common-apis/apis/common-product.controller.ts` (pre-tRPC). Give it a > `regionId` param and pass the caller's region there, or note it as legacy if that controller > is dead. ### `packages/db_helper_sqlite/src/user-apis/order.ts` - `getProductById(skuId)` (~194–219) — derive region from product; pick row. (Phase 2 will add an explicit region for global SKUs.) ### `packages/db_helper_sqlite/src/user-apis/stores.ts` - `getStoreSummaries(regionId)` (~21,24) — pick region row. - `getStoreDetail(regionId, storeId)` (~81,87,90) — pick region row. ### `packages/db_helper_sqlite/src/user-apis/slots.ts` - `getProductAvailability(regionId)` (~37–61) — add `eq(productMarketStats.regionId, regionId)`. ### `packages/db_helper_sqlite/src/admin-apis/product.ts` (largest) - `mapSku` already takes a `marketStats` arg → callers must pass the region row. - `getAllProducts(regionId)` (~211–250): pick region row for `mapSku`; combo-item prices too. - `getProductById(regionId, id)` (~252): pick region row. - `createProduct` (~382): write `regionId` into the inserted market-stats row. - `updateProduct` (~535–556): upsert by `(skuId, regionId)` instead of `skuId`. - `updateProductPrices(regionId, …)` (~1118–1136): upsert by `(skuId, regionId)`. - `toggleProductOutOfStock(regionId, productId)` (~1143–1173): this is the **admin** toggle → it now sets **`is_suspended_in_region`**? *No — see note.* It currently toggles `is_out_of_stock`; keep it toggling `isOutOfStock` but scope to the region row. - `getProductTagInfoById` / `getAllProductTags` / groups (~670–952): pass region row to `mapSku`. > **Suspension toggle note:** the admin-facing "suspend SKU" path is `updateProduct` with > `isSuspended` today. In this phase keep writing whatever field the admin sends to the region > row; Phase 2 changes the admin field to `is_suspended_in_region` and reserves `is_suspended` > for superadmins. ### `packages/db_helper_sqlite/src/admin-apis/order.ts` - `~652,667,673`: picking the latest price for order items — scope to the order's region row (these queries already run in an order/region context; add the region filter). ### `apps/backend/src/trpc/apis/user-apis/apis/order.ts` - `~132` `product.marketStats?.isSuspended` — `getOrderProductById` will return a single, region-picked stats object after Phase 1; keep reading `isSuspended` and add `isSuspendedInRegion` to the unavailability check. ## 7. Cache behaviour - `scaffoldProducts(regionId)` / `scaffoldAvailability(regionId)` already take a region, so once the helpers are region-scoped the per-region caches are correct. - **Admin market-data writes must regenerate that region only**: `updateProductPrices` and `toggleOutOfStock` already call `createAvailabilityCacheFile(regionId)`; keep that. Full `updateProduct` calls `scheduleStoreInitialization(regionId)`. Unchanged. ## 8. Verification 1. `bunx tsc --noEmit` on `apps/backend`, `apps/admin-ui`, `apps/user-ui`, `apps/web-ui` (web-ui has ~12 pre-existing unrelated errors — compare counts). 2. Apply nothing to the dev DB. Validate the **edited `0006`** on a **fresh** DB copy (reset local D1 and apply from `0000`): `region_id` + `is_suspended_in_region` present, new unique index, one row per (SKU, region), orphans pruned. 3. Runtime probe (after the user applies the edited `0006`): for a region-1 and a region-2 SKU, GET `products.json` + `availability.json` and confirm prices/stock match the pre-change values. ## 9. Risks - **Relation churn:** 23 `marketStats: true` sites / 33 `.marketStats` reads. Miss one and it either silently uses the wrong region's row or reads an array as an object. - **Order pricing** (`user-apis/order.ts`, `admin-apis/order.ts`) must keep resolving the right region row — a wrong region row = wrong charged price. - **Suspension semantics** temporarily live in two places; keep both flags in every filter. ## 10. Out of scope (Phase 2+) Global products/stores, `is_global`, superadmin seeding, admin UI changes, the `is_suspended` vs `is_suspended_in_region` split enforcement.