13 KiB
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.marketStatsis now amanyrelation; everywith: { marketStats: true }site picks the region row.getProductDetailById/getProductById(user + order) derive the region from the SKU's product row;getAllProductsWithUnitspicks per-SKU region.getOrderProductByIdnow returns a single region-pickedmarketStatsobject; the order path readsproduct.isSuspended(global) /product.marketStats?.isSuspendedInRegion.- Suspension: a SKU is unavailable when
product_skus.is_suspended(global) orproduct_market_stats.is_suspended_in_region(per region) — helperisSkuSuspended. The admin product write still sets the globalproductSkus.isSuspendedin Phase 1; the superadmin/region split lands in Phase 2.getAvailabilityForCache/getProductAvailability/getSuspendedSkuIds/updateProductPrices/toggleProductOutOfStock/updateProduct/createProductare all region-filtered.- The
0006copy 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 --noEmitbackend/admin-ui/user-ui PASS (web-ui's 12 pre-existing errors unchanged);0000→0006+ data on a fresh DB yieldsregion_id=1,is_offer,is_suspended_in_regioncorrectly.
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, nostore_info/product_infochanges, 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):
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:
skuIdloses.unique()(was 1:1).- new
regionId(NOT NULL, FKregions). - new
isSuspendedInRegion(bool, default false). The old market-statsisSuspendedis 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). productSkusgainsisSuspended(bool, default false) — the global (superadmin) kill-switch.
Relations
productSkusRelations:marketStats: one(productMarketStats)→many(productMarketStats).productMarketStatsRelations: addregion: 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
-
CREATE TABLE __new_product_market_stats— theis_offercolumn is already folded in (from0009, see README); now add the region column + FK and the region-suspension flag:`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 -
Its copy
INSERT INTO __new_product_market_stats … SELECT …— addregion_idandis_suspended_in_region(the copy already selectsis_offerand JOINsproduct_skusfrom the0009fold). All pre-existing rows are backfilled to Mahabubnagar: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 the0009fold) prunes orphan market-stats rows whose SKU no longer exists.
- The
-
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):
export type MarketStatsRow = InferSelectModel<typeof productMarketStats>
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. |
getAllProductsWithUnitsis only consumed by the legacy controllerapps/backend/src/apis/common-apis/apis/common-product.controller.ts(pre-tRPC). Give it aregionIdparam 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) — addeq(productMarketStats.regionId, regionId).
packages/db_helper_sqlite/src/admin-apis/product.ts (largest)
mapSkualready takes amarketStatsarg → callers must pass the region row.getAllProducts(regionId)(~211–250): pick region row formapSku; combo-item prices too.getProductById(regionId, id)(~252): pick region row.createProduct(~382): writeregionIdinto the inserted market-stats row.updateProduct(~535–556): upsert by(skuId, regionId)instead ofskuId.updateProductPrices(regionId, …)(~1118–1136): upsert by(skuId, regionId).toggleProductOutOfStock(regionId, productId)(~1143–1173): this is the admin toggle → it now setsis_suspended_in_region? No — see note. It currently togglesis_out_of_stock; keep it togglingisOutOfStockbut scope to the region row.getProductTagInfoById/getAllProductTags/ groups (~670–952): pass region row tomapSku.
Suspension toggle note: the admin-facing "suspend SKU" path is
updateProductwithisSuspendedtoday. In this phase keep writing whatever field the admin sends to the region row; Phase 2 changes the admin field tois_suspended_in_regionand reservesis_suspendedfor 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
~132product.marketStats?.isSuspended—getOrderProductByIdwill return a single, region-picked stats object after Phase 1; keep readingisSuspendedand addisSuspendedInRegionto 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:
updateProductPricesandtoggleOutOfStockalready callcreateAvailabilityCacheFile(regionId); keep that. FullupdateProductcallsscheduleStoreInitialization(regionId). Unchanged.
8. Verification
bunx tsc --noEmitonapps/backend,apps/admin-ui,apps/user-ui,apps/web-ui(web-ui has ~12 pre-existing unrelated errors — compare counts).- Apply nothing to the dev DB. Validate the edited
0006on a fresh DB copy (reset local D1 and apply from0000):region_id+is_suspended_in_regionpresent, new unique index, one row per (SKU, region), orphans pruned. - Runtime probe (after the user applies the edited
0006): for a region-1 and a region-2 SKU, GETproducts.json+availability.jsonand confirm prices/stock match the pre-change values.
9. Risks
- Relation churn: 23
marketStats: truesites / 33.marketStatsreads. 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.