573 lines
38 KiB
Text
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).
|