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

240 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.