freshyo/docs/impl-plans
2026-10-10 15:00:50 +05:30
..
phase-1-per-region-market-stats.md enh 2026-10-10 15:00:50 +05:30
phase-2-global-stores-and-products-backend.md enh 2026-10-10 15:00:50 +05:30
phase-3-admin-ui.md enh 2026-10-10 15:00:50 +05:30
phase-4-superadmin-ui.md enh 2026-10-10 15:00:50 +05:30
README.md enh 2026-10-10 15:00:50 +05:30

Global Stores & Products — Implementation Plans

Feature: global stores and global products that exist across every region, with per-region market data (price / stock / offer / region suspension) on product_market_stats.

Status: planned, not started. Do not begin Phase 2 until Phase 1 is verified.

Confirmed decisions

Decision Choice
Global store admin access Read-only for regional admins. Only superadmins create/edit/delete global stores.
Global product defaults Superadmin enters initial price/flags on create → a market-stats row is seeded for every region (and for future regions when created).
Seeding a new region On region create, replicate the least-id region's global data (its per-region market-stats rows for global SKUs) into the new region.
Suspension Global is_suspended lives on product_skus (superadmin only). Per-region is_suspended_in_region lives on product_market_stats (that region's admin). The admin "suspend" toggle moves to the region flag in Phase 2.
"Global" representation store_info.is_global = 1 and region_id = NULL; a product is global iff its store is global.
Rollout Phased: backend → admin UI → superadmin UI.
Global SKUs in slots/banners/tags/coupons Allowed in every region (they resolve as "global").

Phases

  1. Phase 1 — Per-region product_market_stats Schema + migration + region-scoped read/write refactor. No "global" yet; existing regional behaviour must stay identical.
  2. Phase 2 — Global stores & products (backend) is_global + nullable region, superadmin routers + seeding, visibility, guards, per-region admin writes, cache regen.
  3. Phase 3 — Admin UI (RN + web) List global + regional products, separate read-only/global-edit component, read-only global stores.
  4. Phase 4 — Superadmin UI Global store + global product CRUD screens.

Cross-cutting ground rules

  • Do not run migrations. All migration SQL is hand-written and applied by the user. Validate migration changes on a fresh/copy DB first.
  • Do not run the test suites unless asked. tsc --noEmit is fine.
  • Log every non-.md/.txt file change in change-log.txt (timestamp + diff) before editing.
  • Working tree is uncommitted; the user manages git.
  • Local D1 path (used for copies/probes): apps/backend/.wrangler/state/v3/d1/miniflare-D1DatabaseObject/da3a80bd8d2cc8f1f070a313ef55c1800da50af994fa89a51c67a6d3e1f919f2.sqlite

Migration strategy — fold schema changes into the pending 0006

packages/db_helper_sqlite/drizzle/0006_regions_and_superadmins.sql is not applied yet and already rebuilds store_info, product_info, product_skus, product_market_stats, and the rest of the region-ownership FK subgraph through __new_* tables.

So instead of writing separate recreate migrations (0010/0011), edit 0006's __new_* DDL/copies directly:

  • Phase 1 (per-region market stats) → edit __new_product_market_stats.
  • Phase 2 (global stores/products) → edit __new_store_info + __new_product_info.

This removes the risky standalone table recreates entirely: 0006 already rebuilds the whole connected subgraph in dependency order, so no FK-deferral juggling is needed. See each phase's §Migration for the exact edits.

Pending-migration set (after the is_offer fold). 0007_addresses_bound_id and 0008_user_creds_unique_and_min_order_cleanup are unrelated to these tables and stay as-is. 0009_move_is_offer_to_market_stats has been folded into 0006 and deleted — 0006 now drops is_offer from __new_product_skus and adds it to __new_product_market_stats (backfilled from the old product_skus).

Why Phases 1–2 are not folded yet. Phase 1 makes product_market_stats.region_id NOT NULL; until the Phase 1 write paths set it, the current code (createProduct/updateProduct insert market stats without a region) would fail. Phase 2's store_info/product_info changes are safe, but they're kept together with Phase 1's edit so the whole per-region/global schema lands in one edit to 0006 when those phases are built.

DB state caveat: the local dev D1 already contains 0006's effects (no d1_migrations table — it was applied by hand). Editing 0006 means the local DB no longer matches the file; validation requires resetting local D1 and re-applying from 0000.