freshyo/docs/impl-plans/phase-1-per-region-market-stats.md
2026-10-10 15:00:50 +05:30

13 KiB
Raw Blame History

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):

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:

    	`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:

    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):

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.

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.