240 lines
13 KiB
Markdown
240 lines
13 KiB
Markdown
# 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<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.
|