freshyo/docs/region-test-cases.txt
2026-10-05 11:46:47 +05:30

573 lines
38 KiB
Text

================================================================================
REGION SCOPING (MULTI_REGION) - TEST PLAN / EDGE CASES
================================================================================
Scope: all uncommitted region work on branch MULTI_REGION.
Region 1 == "Mahabubnagar" == legacy region (owns all pre-region data).
Cross-cutting rule: every admin helper requires regionId; user-facing helpers
default to DEFAULT_REGION_ID (=1) when omitted (see docs/region-backwards-compat.md).
Terminology used below:
[R1] use the seeded region 1 (legacy)
[R2] create a fresh second region with >=1 bound + >=1 telegram cred
ALLREGION product = product_info.region_id IS NULL and available_in_all_regions = true
RESTRICTED product = belongs to exactly one region
Legend: (E) = edge case, (SEC) = authorization/security, (DATA) = data integrity,
(COMPAT) = backwards compatibility, (CONC) = concurrency/atomicity.
--------------------------------------------------------------------------------
1. REGION CRUD (superadmin only)
--------------------------------------------------------------------------------
1.1 Create region happy path: name + >=1 bound (name/desc/priority/geojson) +
>=1 telegram cred. Verify row in regions, region_bounds, region_telegram_creds.
1.2 Create region with zero bounds -> allowed (bounds optional).
1.3 Create region with zero creds -> rejected (zod .min(1)).
1.4 Create region with duplicate bound priorities -> rejected (assertUniquePriorities).
1.5 (E) Create region with duplicate (regionId,chatId) creds -> rejected by unique
index; verify region is NOT left partially created (see DATA-1).
1.6 (E) Create region whose name duplicates an existing name -> currently allowed;
confirm product/UX expectation (no unique constraint on regions.name).
1.7 (E) Bound geojson = invalid JSON / empty / FeatureCollection / MultiPolygon.
Currently only z.string().min(1) is validated -> confirm behavior and whether
malformed GeoJSON must be rejected at create time.
1.8 (E) Bound priority 0 / omitted -> stored as 0; multiple omitted priorities ->
duplicate-priority rejection (all default to 0).
1.9 Update region: rename only -> bounds/creds preserved.
1.10 Update region replacing bounds -> (DATA-2) verify per-bound region_consts are
not orphaned/lost; verify bound ids either stable or constants migrated.
1.11 (E) Update region removing a bound that has bound-scoped constants -> constants
must be deleted or reassigned, not left dangling.
1.12 (E) Update region with duplicate priorities -> rejected.
1.13 (E) Update region for non-existent id -> 404.
1.14 (E) Update region with description omitted vs explicit null -> null persists,
existing description preserved when undefined.
1.15 deleteRegion procedure -> always 400 "cannot be deleted" (even for super_admin).
1.16 addRegionBound after region created -> persisted; duplicate priority rejected.
1.17 deleteRegionBound -> bound removed; (DATA-3) its bound-scoped constants handled;
if it was the priority-1/default bound, default-bound resolution falls to next.
1.18 (SEC) Non-superadmin staff calling any region mutation -> FORBIDDEN.
1.19 (SEC) Unauthenticated user calling region mutations -> UNAUTHORIZED.
1.20 getRegions/getRegionById are protectedProcedure -> any authed user can read
full bounds/geojson; confirm this exposure is intended.
--------------------------------------------------------------------------------
2. REGION RESOLUTION (lat/lng -> region + bound)
--------------------------------------------------------------------------------
2.1 Point inside R1 Mbnr-1 polygon -> {regionId:1, boundId: Mbnr-1}.
2.2 Point inside R2 polygon only -> {regionId:2, boundId: R2 bound}.
2.3 Point outside every polygon -> {regionId:null, boundId:null}.
2.4 Point exactly on a polygon vertex/edge -> confirm turf semantics (boundary).
2.5 (E) Overlapping bounds in one region (priority 1 vs 2) -> lower priority wins.
2.6 (E) Overlapping polygons across R1 and R2 -> (DATA-4) confirm deterministic
winner; current code iterates regions by desc(id), NOT by priority.
2.7 (E) Malformed GeoJSON bound among valid bounds -> malformed skipped, others work.
2.8 (E) Polygon, MultiPolygon, Feature(Polygon), FeatureCollection (mixed) all resolve.
2.9 (E) Feature with null geometry, non-object JSON, empty string -> no throw.
2.10 (E) Antimeridian-crossing polygon / very large polygon -> sanity check.
2.11 Lat/lng swapped input -> document expected (should NOT match a region incorrectly).
2.12 resolveRegionForLocation public procedure returns regionId/boundId or null.
2.13 Performance: many bounds (100+) -> resolution latency acceptable, no N+1 blowup.
--------------------------------------------------------------------------------
3. REGION TELEGRAM CREDS
--------------------------------------------------------------------------------
3.1 R2 order placed -> message sent to every R2 cred, none to R1 creds.
3.2 R1 order placed -> message only to R1 creds.
3.3 (E) Region with zero creds (possible via direct DB) -> skip + log, no throw.
3.4 (E) Multiple creds in one region -> fan-out to all.
3.5 (E) Telegram API failure for one cred -> others still attempted; error logged.
3.6 (E) Order whose address has regionId null -> confirm skip/log (does NOT spam all).
3.7 Updating/adding creds (if exposed) -> next notification uses new creds.
--- 3b. PLACE ORDER -> THAT REGION'S TELEGRAM API IS CALLED (required) --------------
Setup: stub/instrument the Telegram sendMessage endpoint (or worker fetch) to record
(botToken, chatId, text) per call. Ensure R1 and R2 have DIFFERENT bot tokens/chat ids.
3.8 Place an order with an R1 address -> the R1 telegram creds' sendMessage API is
called exactly (once per R1 cred) with R1's botToken/chatId; R2's creds are NOT
called at all.
3.9 Place an order with an R2 address -> R2's creds called; R1's creds not called.
3.10 (E) Order containing items from multiple stores -> still routed by the ORDER's
address region only (not by store region).
3.11 (E) Flash order -> same routing (r1 creds for r1 flash order).
3.12 (E) Cancellation of an R2 order -> cancellation message goes to R2 creds only.
3.13 (E) Region with multiple creds -> every cred's API called once (fan-out).
3.14 (E) Region with zero creds -> no Telegram call, no throw, order still succeeds.
3.15 (E) Telegram returns 4xx/5xx for one cred -> other creds still called; order still
succeeds; failure logged.
3.16 (E) The message body matches the placed region's order (readable id, items,
amount) and is never escalated to another region's bot.
--------------------------------------------------------------------------------
4. REGION CONSTANTS (region-level + bound-level)
--------------------------------------------------------------------------------
4.1 customize-app (admin-ui): admin of R1 edits deliveryCharge -> only R1 changes.
4.2 Admin of R2 edits same key -> only R2 changes; R1 unchanged.
4.3 (E) Region-level value + bound-level override -> bound value wins for users in
that bound; region value applies elsewhere in region.
4.4 (E) Bound override removed -> falls back to region value, then global.
4.5 (E) Region has no override -> global key_val_store value applies.
4.6 (DATA-5) After migration 0007, confirm the 10 REGION_CONST_KEYS are gone from
key_val_store AND that no runtime path re-inserts them (startup no longer calls
seed(); verify the flash-delivery cron does not re-create the global
isFlashDeliveryEnabled row either - see 11.19).
4.7 (DATA-5) getConstant(key, regionId, boundId) must return the regional override
when a global row exists. Test isFlashDeliveryEnabled per region.
4.8 (E) boundId belongs to a different region -> rejected ("Bound does not belong").
4.9 (E) boundId omitted -> uses region default (priority-1) bound; verify read and
write semantics are consistent (DATA-6: read auto-resolves, write may not).
4.10 (E) Upsert same region+key+bound twice -> single row (update, not insert).
4.11 (E) SQLite NULL semantics: upsert region+key+boundId NULL twice -> (DATA-7)
must not create duplicate region-level rows.
4.12 refreshGenKv(regionId, boundId) runs after a const edit and writes the region's
KV key; user app sees new values within one cache cycle (see 4b for the
change -> wait 60s -> verify-via-API test).
4.13 (E) Editing consts for a region with no bounds -> region-level write works.
4.14 Global-only keys (tagsOrder, internalAppVersion, versionNum) edited by R2 admin
-> (SEC) must not silently mutate all regions; require superadmin.
4.15 Cached essential-consts file per region/bound reflects the correct overrides.
--- 4b. ESSENTIAL CONSTS PROPAGATION (change -> wait ~60s -> verify via API) ---------
Mechanism: admin const edit writes region_consts then calls refreshGenKv(regionId,
boundId), which puts the rebuilt payload into GEN_KV (`essential_consts_<regionId>`
or `essential_consts_<regionId>_<boundId>`; region 1/legacy key is `essential_consts`).
The public `common.essentialConsts` procedure reads from KV via
readEssentialConstsFromKv, and Cloudflare KV is eventually consistent (propagation
can take up to ~60s). Test steps:
4.16 Set a region const for R1 (e.g. deliveryCharge) via customize-app -> assert it is
written to region_consts for R1. Immediately call
common.essentialConsts({ regionId: 1 }) - may still return the OLD value (KV
propagation window).
4.17 Wait 60s, call common.essentialConsts({ regionId: 1 }) again -> the NEW value is
present. (This is the required end-to-end assertion.)
4.18 Repeat 4.16-4.17 for R2 and a non-1 region: verify R2's KV key
`essential_consts_2` (not the legacy key) holds the change, and that R1's API
response is unchanged.
4.19 (E) Bound-scoped const edit for (R1, bound B) -> after >=60s,
common.essentialConsts({ regionId: 1, boundId: B }) returns the new value;
the region-level response (no boundId) is unaffected and R2 is unaffected.
4.20 (E) Multiple edits within the propagation window -> last write wins; after 60s the
API reflects the final value (no resurrected stale payload).
4.21 (E) KV miss (cold key) -> readEssentialConstsFromKv rebuilds from D1 immediately
and backfills KV, so the API is already correct without waiting.
4.22 (E) isFlashDeliveryEnabled toggled per region -> after 60s common.essentialConsts
reflects it for that region, and placeOrder flash validation uses the same value.
4.23 Verify no cross-region contamination: changing R1 consts never makes R1's values
appear under R2's regionId key (or vice-versa) after propagation.
4.24 (E) essentialConsts response includes the correct cachePathPrefix for the region
('r-<id>/' for non-1, '' for region 1) after a change.
4.25 (E) User app receives the updated essential consts on its next fetch after 60s
(visible threshold/charge change), with no app restart.
--------------------------------------------------------------------------------
5. STAFF USERS / ADMINS / AUTH CONTEXT
--------------------------------------------------------------------------------
5.1 superadmin /admins create admin with role=admin + region R2 -> staff_users.regionId=R2.
5.2 (E) Create admin with role=super_admin -> confirm region requirement (UI forces
a region; backend defaults to ctx region). Decide intended behavior.
5.3 Login returns regionId + roleName; ctx.staffUser populated from DB on each request.
5.4 (E) Staff with regionId null (legacy) -> adminProcedure returns FORBIDDEN.
5.5 (E) Staff with unknown/deleted staffRoleId -> staffRoleName null; superAdminProcedure
denies; adminProcedure still allows.
5.6 (SEC) adminProcedure blocks customer tokens; protectedProcedure allows them
(this is the root of the cross-region holes in section 16 - test explicitly).
5.7 getStaff / getAllStaff include regionId.
5.8 (E) super_admin: scopedRegion(ctx) returns undefined -> verify every admin list
endpoint still works (see 16 / section 8 edge cases).
--------------------------------------------------------------------------------
6. STORES (region-aware + cross-region)
--------------------------------------------------------------------------------
6.1 R1 admin getStores -> only R1 stores. R2 admin -> only R2 stores.
6.2 createStore stamps ctx region; non-superadmin cannot inject another regionId.
6.3 (SEC) R2 admin cannot target R1 by passing regionId in create/update.
6.4 updateStore moves/changes store; verify product_market_stats.storeId retargeted
in the store's region only; (DATA-8) old-region references cleared.
6.5 (SEC) getStoreById / deleteStore by-id currently protectedProcedure + unscoped
-> customer/R1 admin can read/delete R2 store. Test and confirm fix.
6.6 (SEC) getStoresForAllRegions -> only superadmin should get all regions.
6.7 (E) Deleting a store clears product_market_stats.storeId (no dangling store).
6.8 (E) createStore with SKU list -> product_market_stats.storeId set only for the
same region's rows.
6.9 StoreForm: initial product pre-selection for RESTRICTED product.
6.10 (E) StoreForm pre-selection for ALLREGION product / cross-region -> confirm
correct products listed (store:{id} shape caveat).
6.11 (E) Store with owner staff from another region -> confirm allowed/rejected.
6.12 User getStoreSummaries/Detail scoped to user's region; no R2 store leaks into R1.
--------------------------------------------------------------------------------
7. PRODUCTS (region-restricted vs all-region)
--------------------------------------------------------------------------------
7.1 R1 admin create RESTRICTED product -> product_info.region_id=1; market stats row
for region 1 with chosen store; non-creator regions NOT created.
7.2 Create ALLREGION product -> product_info.region_id NULL,
available_in_all_regions=true; per-region market-stats rows for each selected
region with storeIdsByRegion; regions not selected -> absent/out-of-stock.
7.3 (E) ALLREGION product with storeIdsByRegion missing a region -> (DATA-9)
market stats storeId null for that region; UI should block this.
7.4 Update RESTRICTED product -> price/stock/store updates only its region.
7.5 Update ALLREGION product storeIdsByRegion -> storeId updated for listed regions;
price/stock of non-creator regions untouched; absent keys = no change.
7.6 Toggle ALLREGION -> RESTRICTED: verify other regions' market-stats rows removed
and no silent no-op when creator region cannot be determined.
7.7 (SEC) R2 admin calls updateProduct with an R1 product id -> must be rejected
(currently loads by id and forces ctx region / deletes other regions - DATA-10).
7.8 (SEC) deleteProduct currently protectedProcedure -> customer/R2 can delete R1
product. Test and confirm fix.
7.9 getProducts/getProductById region filter: region OR available_in_all_regions.
super_admin (region null) sees all products.
7.10 (E) getProductById for RESTRICTED product in wrong region -> 404 (not leaked).
7.11 (E) Out-of-stock / suspended market stat in a region -> product hidden there but
visible in other regions where it is active.
7.12 (E) Product with region_id NULL but available_in_all_regions=false (bad data) ->
confirm behavior.
7.13 ProductForm validation: all-regions requires a positive store per region.
7.14 (E) Store options still loading -> submit blocked until regions load (DATA-9).
7.15 (E) Toggle all-regions on/off -> previously chosen per-region stores preserved.
7.16 (E) Edit ALLREGION product -> per-region dropdowns prefilled by store-name match;
confirm when no same-name store exists, admin prompted to create one.
7.17 (E) storeIdsByRegion string-vs-number keys survive Formik + backend normalize.
7.18 updateProductPrices / toggleProductOutOfStock scoped to ctx region (or superadmin).
7.19 user getProductDetailById/getProductById pick region row; combo item prices use
the same region's market stats.
7.20 (E) getAllProductsWithUnits / getAllSkusSummary filter region acceptance.
7.21 backfillMarketStatsForRegion: new region gets a row per SKU (copied from R1),
default out-of-stock; (CONC-1) partial-failure behavior/idempotency.
--- 7b. PRICE / STOCK ISOLATION (explicit "change in region A must not affect B") -----
Setup: one ALLREGION product with SKUs, market-stats rows in R1 and R2 (same skuId,
different product_market_stats.id). Also one RESTRICTED product per region.
7.22 Admin edits PRICE of the all-region SKU in R1 (edit form or prices-overview) ->
product_market_stats.our_price changes ONLY the R1 row; R2 row's our_price,
market_price, flash_price, is_flash_available unchanged (assert raw DB rows).
7.23 Symmetric R2 -> R1: editing R2 price leaves R1 byte-identical.
7.24 updateProductPrices batch for R1 only mutates R1 rows for the given skuIds;
R2 rows for the same skuIds are untouched.
7.25 Toggle isOutOfStock / isSuspended / isFlashAvailable for R1 -> only R1 row
changes; the SKU stays purchasable/visible in R2 (and vice-versa).
7.26 User-facing reads: a user in R1 sees R1 our_price/flash_price; a user in R2 sees
R2 our_price/flash_price for the SAME skuId (getProductDetailById/getProductById/
getAllSkusSummary + respective caches).
7.27 Cart + checkout + place order: same sku added in R1 vs R2 -> order_items.price /
discountedPrice and order total reflect the ordering region's price, not the
other region's.
7.28 (SEC) R2 admin attempts to change R1's price for an all-region SKU (by passing
R1 regionId/row id) -> rejected; forced to ctx region.
7.29 (E) Superadmin price edit -> confirm which region row is written (must be an
explicit target; must not silently update all regions).
7.30 (E) New region R3 backfilled from R1 defaults -> a later R1 price change does NOT
cascade to R3 (independent rows).
7.31 (E) RESTRICTED product price change in its own region never creates/leaks a
market-stats row in another region.
7.32 (E) Region with no market-stats row for a SKU -> user sees out-of-stock/absent,
no fallback to another region's price.
--------------------------------------------------------------------------------
8. PRODUCT TAGS & GROUPS (region-scoped)
--------------------------------------------------------------------------------
8.1 Create tag "Fresh" in R1 and "Fresh" in R2 -> BOTH succeed (DATA-11: migration
0007 must create composite unique (tag_name, region_id) and drop the global one).
8.2 Create duplicate tag name within same region -> rejected.
8.3 getProductTags/getProductTagById scoped to ctx region.
8.4 (SEC) updateProductTag/deleteProductTag verify tag ownership (currently
updateProductTag adminProcedure but db may be id-scoped; delete is
protectedProcedure).
8.5 Superadmin getGroups/getProductTags -> (DATA-12) scopedRegion returns undefined
but db expects number; verify list works or fix to optional.
8.6 createGroup stamps ctx region; group names region-scoped.
8.7 (SEC) updateGroup/deleteGroup by-id cross-region -> must be blocked.
8.8 (E) Tag with relatedStores/sortOrder referencing other-region stores -> validate.
--------------------------------------------------------------------------------
9. SLOTS, CAPACITY, VENDOR SNIPPETS
--------------------------------------------------------------------------------
9.1 R1 admin sees only R1 slots; R2 admin only R2 slots.
9.2 createSlotWithRelations stamps ctx region; snippet insert stamps slot region.
9.3 (SEC) getSlotById/updateSlot/getDeliverySequence/updateDeliverySequence/
updateSlotCapacity are protectedProcedure + unscoped -> cross-region access.
Test and confirm fix.
9.4 (E) updateSlot moving a slot between regions -> dependents (snippets/orders) sane.
9.5 getActiveSlotsWithProducts / getActiveSlotsList / getProductAvailability region-scoped.
9.6 (E) vendor_snippets.snippetCode global unique blocks same code in R2 (DATA-13);
decide composite (snippetCode, region_id).
9.7 Vendor snippet public page (fallback-ui) -> correct region's orders.
9.8 getAllSlotsWithProductsForCache region filter; marketStats.store never leaks
another region's store.
--- 9b. SLOT / AVAILABILITY ISOLATION (explicit "change in region A must not affect B") -
Setup: R1 and R2 each have their own delivery_slot_info rows and their own
availability (product_market_stats.isSuspended/isOutOfStock) + store mappings.
9.9 Create a new slot in R1 -> it appears in R1 admin list, R1 user slot list, and
R1 slots cache file ONLY; R2 list/cache/order flow unchanged (assert raw rows +
R2 cache file contents).
9.10 Edit an existing R1 slot (deliveryTime, freezeTime, isActive, isFlash) -> only the
R1 row changes; R2 rows byte-identical.
9.11 Toggle isCapacityFull on an R1 slot -> R2's slot(s), including one with the SAME
delivery time, remain uncapped for R2 users.
9.12 updateSlotCapacity(slotId) / updateSlotDeliverySequence(slotId) target only the
addressed slot's region; a cross-region slotId is rejected (SEC, see 9.3).
9.13 Deactivate/delete an R1 slot -> R2 slots still serve; orders already placed on the
R1 slot keep their history.
9.14 User slot selection: an R1 user cannot select/save an R2 slotId at checkout;
attempting it is rejected or silently unavailable.
9.15 Availability toggle: set a SKU out-of-stock/suspended in R1 -> R2 availability
for the same skuId is unchanged (getProductAvailability, isSuspended flags).
9.16 Store<->product availability mapping: adding/removing a SKU from a store in R1
does NOT change R2's availability cache or R2's store summary.
9.17 Availability cache isolation: bump R1 availability version -> R2 availability
cache file/version untouched (and vice-versa); no cross-region file overwrite.
9.18 (CORRECT BEHAVIOR) A slot mutation in ONE region regenerates the slots cache
files for EVERY region: admin add/edit/delete/capacity/sequence calls
createSlotsCacheFile() with no region, which loops all regions
(cloud_cache.ts:198-206; slots.ts:124,196,298). Assert each region's slots file
is re-uploaded and its slots version bumped - while each file's CONTENT still
contains only that region's slots (data isolation preserved, no cross-region leak).
9.19 getActiveSlotsWithProducts(regionId) never returns an R2 slot to R1 (and vice-versa).
9.20 (E) Slot skuIds/groupIds referencing another region's entities -> filtered/ignored
for the wrong region; no cross-region product leak.
9.21 (E) A region with zero slots -> user sees no slots / graceful empty state; other
region's slots must not be substituted.
9.22 (E) Superadmin slots view -> confirm whether all-regions or a selected region;
edits must target an explicit region, never all regions at once.
9.23 (E) Vendor snippet tied to an R1 slot -> not reachable/served for R2.
9.24 (E) Flash slot (isFlash) created in R1 -> flash availability in R2 unchanged.
--- 9c. SLOT UPDATE -> ALL SLOT FILES REGENERATED (required behavior) --------------
9.25 Edit a slot in R1 -> EVERY region's slots file is regenerated (R1, R2, ...): each
`slots_<version>.json` (or r-<id>/slots_<version>.json) is re-uploaded and the
per-region slots version counter for each region is incremented.
9.26 Add a slot in R1 -> same full-set regeneration as 9.25; new R1 slot appears only
in R1's file; R2's file content is unchanged even though it was re-written.
9.27 Delete/deactivate a slot in R1 -> same full-set regeneration; R2 content unchanged.
9.28 Capacity / delivery-sequence change in R1 -> same full-set regeneration.
9.29 (E) Region with no regions beyond R1 (fresh DB) -> regeneration falls back to
[DEFAULT_REGION_ID] and still produces R1's slots file without error.
9.30 (E) Adding a NEW region R3 then editing a slot in R1 -> R3's slots file is also
generated/regenerated (it is in getRegions()).
9.31 After the all-region regeneration, verify no region's slots file contains another
region's slots, stores, or products (content isolation still holds).
9.32 (E) refreshGenKv runs for each regenerated region; users in every region pick up
the new slots version on their next essentialConsts fetch.
--------------------------------------------------------------------------------
10. BANNERS (region-scoped)
--------------------------------------------------------------------------------
10.1 R1 getBanners -> only R1; R2 -> only R2.
10.2 createBanner stamps ctx region.
10.3 user getActiveBanners filtered by region + serialNum not null.
10.4 (SEC) getBannerById/updateBanner/deleteBanner by-id protectedProcedure -> cross
region read/write/delete. Test and confirm fix.
10.5 (E) Banner serial ordering within a region; duplicate serial across regions OK.
--------------------------------------------------------------------------------
11. ORDERS, PRICING, LIFECYCLE, NOTIFICATIONS
--------------------------------------------------------------------------------
11.1 R2 order -> pricing uses R2 market stats (DATA-14: current code passes no region
to getOrderProductById, defaults to R1 - MUST FAIL until fixed).
11.2 Flash availability check uses the ordering region's market stats.
11.3 Constants (min order, delivery charge, flash threshold) resolve per region+bound.
11.4 admin getAllOrders/getSlotOrders scoped to admin region (super_admin all).
11.5 (E) Order whose address row was deleted / region_id null -> appears in no region
view (DATA-15); decide desired fallback.
11.6 Telegram order message per region (section 3).
11.7 Staff push on order placed scoped to order region; regionless -> defined policy.
11.8 rebalanceSlots uses correct region market stats; (SEC) cannot rebalance other
region's slots.
11.9 (E) Address region changed after order placed -> historical order region stable.
11.10 Complaint raise notifies only that order/region's admins.
11.11 (E) Order in region with no creds / no staff tokens -> no throw.
--- 11b. FLASH DELIVERY ENABLE/DISABLE IS PER-REGION (isolation) --------------------
Mechanism: isFlashDeliveryEnabled lives in region_consts per region; order placement
reads it via getConstant(key, address.regionId, boundId); flash availability also
depends on product_market_stats.isFlashAvailable per region.
11.12 Disable flash delivery in R1 (set isFlashDeliveryEnabled=false for R1) -> an R1
flash order is rejected ("Flash delivery is currently unavailable"), but an R2
flash order still succeeds because R2's value is untouched.
11.13 Symmetric: disable in R2 -> R2 rejected, R1 unaffected.
11.14 Toggling the flag in R1 does NOT change R2's essentialConsts after the
propagation window (no cross-region write); R2's isFlashDeliveryEnabled stays.
11.15 (E) A region that never set the flag -> falls back to global/region default, not
to another region's override.
11.16 (E) Flash availability of a SKU: set isFlashAvailable=false in R1 -> R2's flash
availability for the same skuId stays as configured.
11.17 (E) R1 has an active flash slot but flash disabled -> R1 flash orders blocked;
R2's flash slot/flash flag remain usable.
11.18 (E) Superadmin toggling flash for a specific region must target that region only.
--- 11c. FLASH CRON REGION SAFETY --------------------------------------------------
Note: seed() is no longer run at startup, so the global isFlashDeliveryEnabled row is
absent after migration 0007. flash-delivery-cron.ts:29 calls
toggleKeyVal('isFlashDeliveryEnabled', enabled), which is an UPDATE (not upsert) and is
global-only; refreshGenKv() is also called with no region.
11.19 Run the flash on/off cron -> it must not silently no-op (missing global row) and
must not globally override all regions. Verify whether it updates the intended
region's region_consts (and/or all regions deliberately), refreshes the right
region KV keys, and that region-specific overrides are preserved.
11.20 (E) After a cron run, unchanged regions' isFlashDeliveryEnabled values must equal
their pre-cron values (no cross-region write).
11.21 (E) Fresh DB (no seed run, region_consts not backfilled) -> user-facing consts
must not collapse to null/0; verify CONST_DEFAULTS fallback for the 10 regional
keys reaches the user path (getAllRegionConsts/mergedConstMap currently do NOT
apply CONST_DEFAULTS, unlike the admin helpers).
11.22 (E) seed.sql is applied (roles/permissions/units/global keys) since seed() no
longer runs; confirm staff_roles and permissions exist on a fresh environment.
--------------------------------------------------------------------------------
12. ADDRESSES, USER REGION, CARTS
--------------------------------------------------------------------------------
12.1 Address create/update includes regionId; defaults to 1 when omitted (COMPAT).
12.2 (E) Address region dropdown lists all regions (common.getRegions).
12.3 (E) Address hardcoded city/state/pincode fields -> wrong locality for non-default
region (DATA-16); confirm editable or region-derived.
12.4 Cart: items from one region only; switching region snapshots old region cart and
restores the target region's cart.
12.5 (E) Cart switch with items that don't exist in target region -> keep/nearest-freeze
/remove reconcile rules; results dialog accurate.
12.6 (E) Region switch while another switch in progress -> guarded, no interleave.
12.7 (E) Region switch fails mid-way -> (DATA-17) region must NOT be committed with
stale slot ids; verify rollback.
12.8 (E) Per-region cart snapshot keys isolated; corrupt JSON entry -> no crash;
old snapshots eventually cleaned (unbounded growth).
12.9 (E) Empty cart + region switch -> active region changes, no phantom items.
12.10 AddressRegionWatcher: selecting an address in another region with non-empty cart
-> confirm dialog (moves/removals, >1hr shift badge); Confirm switches, Cancel reverts.
12.11 (E) Empty cart + address in another region -> (DATA-18) active region must also
switch (currently watcher may not call setRegion).
12.12 (E) All lines "kept" -> active region must still switch.
12.13 (E) External region switch via RegionBar -> selected address re-validated;
no divergence between address region and active region.
12.14 (E) First/default address region != GPS region -> confirm prompt behavior.
12.15 (E) Preview dialog open + data refetch -> no duplicate dialog, no re-fetch storm.
--------------------------------------------------------------------------------
13. REGION GATE / CONTEXT / BAR (user-ui)
--------------------------------------------------------------------------------
13.1 Cold start, permission granted, inside a region -> resolves + persists region.
13.2 (E) Permission denied -> "Unable to obtain location" + Open Settings; return from
settings triggers AppState recheck.
13.3 (E) Location services OFF -> services-off copy + enable action.
13.4 (E) Outside all regions -> manual region picker; selecting persists + unblocks.
13.5 (E) getRegions errors/empty -> picker shows retry/error (currently may be empty).
13.6 (E) Persisted region deleted/merged -> (DATA-19) validate against getRegions and
fall back/clear instead of sending a dead regionId everywhere.
13.7 (E) Persisted region exists -> decide whether to trust it without re-prompting
for permission on every cold start.
13.8 (E) GPS/network hangs -> timeout + manual escape hatch ("Detecting..." must not
block forever).
13.9 (E) setState after unmount during async detect -> no warning/crash.
13.10 RegionBar on all level-1 tabs (home, stores, order-again, me, flash) shows active
region; dropdown switches region; home collapse-on-scroll works.
13.11 (E) Region name long / many regions -> dropdown scroll/truncation.
13.12 Router/instructions unaffected by region params (`useRegionParams` sends region
+ bound on all user API calls).
--------------------------------------------------------------------------------
14. CACHES, VERSIONS, KV (region isolation)
--------------------------------------------------------------------------------
14.1 createAllCacheFiles loops every region; per-region files at r-<id>/ (region 1
unprefixed -> COMPAT).
14.2 (E) Adding a region triggers regeneration for ALL regions incl. new one.
14.3 Region 1 version counters/KV keys unchanged vs pre-region (COMPAT critical).
14.4 (E) Bumping R2 cache version does not bust R1 cache; and vice-versa.
14.5 Availability + slots cache per region; no cross-region product/store leakage.
14.6 (E) refreshGenKv(regionId) writes region KV key; region 1 also writes legacy key.
14.7 (E) Bound-scoped KV entry stale after cache regen (DATA-20): client sends boundId
but server refreshes only region-level key -> old cacheVersion served.
14.8 (E) getRegions() empty -> fallback to [DEFAULT_REGION_ID] (no crash on cold DB).
14.9 cachePathPrefix in essentialConsts -> '' for R1, 'r-<id>/' otherwise; client
builds correct URLs (COMPAT 4.2).
--------------------------------------------------------------------------------
15. PUSH NOTIFICATIONS / DEVICE TOKENS
--------------------------------------------------------------------------------
15.1 savePushToken stores regionId; region change re-saves association.
15.2 Admin broadcast (notify-all) reaches only admin's region tokens.
15.3 (E) Broadcasting from super_admin -> all regions or selectable region.
15.4 (E) Admin sends to explicit userIds from another region -> must be blocked.
15.5 (E) getUsersForNotification search scoped to admin region.
15.6 (E) Legacy token rows with region_id null -> migration backfills to 1; new saves
follow device region (move semantics).
15.7 (SEC) notification send endpoint authorization (staff region only).
--------------------------------------------------------------------------------
16. AUTHORIZATION / CROSS-REGION MATRIX (SEC) - test every row
--------------------------------------------------------------------------------
Actor x Resource:
- region admin of A, region admin of B, super_admin, customer, anonymous, legacy staff (no region)
Resources:
- products (list/get/create/update/delete/prices/stock)
- product tags & groups (create/update/delete)
- stores (list/get/create/update/delete/getStoresForAllRegions)
- slots (+capacity/sequence)
- banners (list/get/create/update/delete)
- orders (list/get/slot orders/rebalance)
- constants (global vs region keys)
- staff users (create/list)
- user suspension, notifications/broadcast
- region CRUD/bounds
Expect: A-admin cannot see/modify B's data; super_admin sees all where intended;
customer/anonymous denied for all admin ops (currently several use protectedProcedure
-> expected FAILURES until converted to adminProcedure + ownership checks).
--------------------------------------------------------------------------------
17. DATA INTEGRITY / MIGRATIONS
--------------------------------------------------------------------------------
17.1 (DATA-1/CONC) createRegion atomicity: force a cred/bound insert failure -> no
partial region (use db.batch; db.transaction is a no-op today).
17.2 (DATA-2) updateRegion bound churn -> per-bound constants not orphaned.
17.3 (DATA-3) deleteRegionBound -> dependent constants handled.
17.4 (DATA-4) Region resolution deterministic for overlapping regions.
17.5 (DATA-7) region_consts NULL bound uniqueness.
17.6 (DATA-11) tag composite unique index actually exists post-migration.
17.7 (DATA-13) vendor_snippets snippet code global-unique decision.
17.8 (DATA-21) schema.ts vs migration drift: region_id FK columns exist in schema but
not in DB (ALTER ... no REFERENCES), store_id FK, and product_info rebuild.
17.9 (DATA-22) Index name drift (unique_sku_region vs
product_market_stats_sku_region_unique) -> future drizzle-kit generate noise.
17.10 0007 idempotency: rerun is safe (IF NOT EXISTS + backfill guards) - currently
region_consts DDL/backfill are not guarded; 0006 is.
17.11 0007 product_info rebuild preserves all rows/columns + FK children
(product_skus, product_reviews).
17.12 (CONC-1) backfillMarketStatsForRegion partial failure/idempotency.
17.13 Soft-delete/suspension interactions with region filtering (sku is_suspended
per region vs global is_deleted).
17.14 (COMPAT) Applied migrations not edited; any prerequisite edits were to
unapplied migrations only.
--------------------------------------------------------------------------------
18. BACKWARDS COMPATIBILITY (region 1 == legacy) - COMPAT
--------------------------------------------------------------------------------
18.1 Old client sends NO region on every endpoint -> behaves exactly as before (all
data resolves to region 1).
18.2 R1 cache URLs byte-identical (no r-1/ prefix); KV legacy key present.
18.3 Region 1 counters (cache_version, availability/slots version) unchanged names.
18.4 No duplicate region-1 data created by migration (guarded inserts in 0006/0007).
18.5 (E) Migration re-run on an existing DB -> no duplicate regions/bounds/creds/consts.
18.6 (E) Fresh DB -> seed + migrations produce region 1 with 2 bounds + 1 cred and the
per-region market-stats rows.
--------------------------------------------------------------------------------
19. UI REGRESSION CHECKLIST
--------------------------------------------------------------------------------
19.1 admin-ui + admin-web ProductForm: single-store vs all-region modes; validation;
per-region dropdowns; toggle prefill; edit prefill; submit payload shape.
19.2 superadmin-ui: /regions list, /regions/new, /regions/:id/edit nesting/rendering;
bound add/remove + priority computation; geojson textarea; creds rows (min 1).
19.3 superadmin-ui /admins create admin (role + region).
19.4 admin-ui customize-app: region + bound tabs; hidden popularItems; loading/error
states when constants/bounds not yet loaded.
19.5 user-ui: address form region dropdown; cart address selector; checkout static
address; region bar/dropdown on all level-1 tabs.
19.6 Existing tests still typecheck (AdminProduct no longer has storeId; fixtures
referencing storeId must be updated).
19.7 No tracked build/cache artifacts changed (e.g. apps/admin-ui/.expo/cache).
--------------------------------------------------------------------------------
20. BUILD / TYPE / MERGE HYGIENE
--------------------------------------------------------------------------------
20.1 tsc clean for backend, admin-ui, admin-web, user-ui, web-ui, superadmin-ui.
20.2 No unused imports (e.g. common-trpc-index getRegions/extractPolygonRings) that
break noUnusedLocals builds.
20.3 packages/shared/index.ts BASE_API_URL restored to the real API (currently a LAN
dev IP - must not ship).
20.4 No secrets in changed files (creds/demo.txt, dumps/latest.sql review).