75 lines
4.5 KiB
Markdown
75 lines
4.5 KiB
Markdown
# 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`](./phase-1-per-region-market-stats.md)
|
||
*Schema + migration + region-scoped read/write refactor. No "global" yet; existing
|
||
regional behaviour must stay identical.*
|
||
2. [Phase 2 — Global stores & products (backend)](./phase-2-global-stores-and-products-backend.md)
|
||
*`is_global` + nullable region, superadmin routers + seeding, visibility, guards,
|
||
per-region admin writes, cache regen.*
|
||
3. [Phase 3 — Admin UI (RN + web)](./phase-3-admin-ui.md)
|
||
*List global + regional products, separate read-only/global-edit component, read-only
|
||
global stores.*
|
||
4. [Phase 4 — Superadmin UI](./phase-4-superadmin-ui.md)
|
||
*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`**.
|