freshyo/docs/impl-plans/README.md
2026-10-10 15:00:50 +05:30

75 lines
4.5 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.

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