PRODUCT REPORT — Regions & Location Release
Date: 2026-10-04
Scope: everything currently uncommitted in the worktree (customer app, admin apps, superadmin console, backend).
Note: database migrations are written but not yet applied; nothing below is live until they run.

=====================================================================
1. CUSTOMER APP (user-ui)
=====================================================================

1.1 Automatic region detection on startup
- When the app opens, it asks for location permission and figures out which
  service region the customer is in, using the delivery-area maps drawn for
  each region. No manual setup needed for most users.
- If permission is denied, or the phone's location switch is off, the app
  shows a clear "Unable to obtain location" screen explaining exactly which
  of the two is the problem, with a button that opens the right Settings
  page (app settings for permission, system location settings on Android).
  The user can also just pick a region manually and continue.
- If the customer is outside every service area, the app says so plainly
  and still lets them pick a region and browse.

1.2 Region display and switching
- The home screen shows the current region above the search bar. It slides
  away as you scroll so the search bar stays visible.
- Tapping the region opens a dropdown to switch regions. The same dropdown
  now appears on all main tabs (Home, Offers, Flash delivery, Stores, Me).
- Switching region reloads that region's products, prices, stores, slots
  and offers automatically.

1.3 Cart is remembered per region
- The cart is saved separately for each region. Going back to a previous
  region restores exactly what was left there, including quantities.
- When the cart is carried into a new region, every item is re-matched to
  the closest available delivery slot. Items that can't be delivered there
  are removed. A summary dialog shows what moved (old time vs new time,
  with a warning when the shift is over an hour) and what was removed.
- Applies to both the regular cart and the 1-hour delivery cart.

1.4 Delivery addresses belong to regions
- The address form now ends with a mandatory region dropdown, pre-filled
  with the customer's detected region.
- On the cart page there is an address selector. Adding a new address in
  the current region selects it immediately. If the new address is in a
  different region, the app shows all addresses in that region and asks the
  user to pick one.
- Changing the selected address to one in another region triggers the same
  cart check as switching regions: a confirmation dialog appears first when
  slots would move or items would be removed; empty or unaffected carts
  switch over silently.
- The checkout page no longer has its own address picker; it shows the
  chosen address read-only. Address selection happens on the cart page.

1.5 Push notifications carry the region
- The device's push token is saved together with its region, both for
  logged-in and logged-out users. If the same device is used by another
  account or region later, the record moves with it instead of erroring.
- Older app installs that never reported a region are treated as region 1.

=====================================================================
2. ADMIN APPS (admin-ui + admin-web)
=====================================================================

2.1 Admins only see and touch their own region
- Product, store, slot, banner, tag, group, snippet and order screens are
  all filtered to the logged-in admin's region. Cross-region editing is
  blocked with a clear error, including:
  - editing or deleting another region's product, store, prices or stock,
  - narrowing an "available in all regions" product down to one region,
  - widening a product to all regions.
- Only super-admins can perform cross-region actions.
- The "available in all regions" checkbox is locked (visible but disabled)
  for non-super-admins on all-region products; the server enforces the
  same rule regardless.

2.2 All-region products
- A product can be marked available in all regions. It carries one store
  per region (chosen from per-region dropdowns in the product form, with
  every region's stores visible), while price and stock stay per-region.
- Every region selection in the form is mandatory — a product cannot be
  saved with a region missing its store.
- Editing a product's per-region stores later actually updates them
  (previously those edits were silently lost).

2.3 Region-aware pickers
- Product/SKU/tag/store pickers in banners, groups, tags and campaign
  screens now show the admin's own region data (super-admins see everything
  combined), instead of always showing region 1.

2.4 App settings per area (customize-app)
- Settings such as delivery charges, free-delivery limits, flash delivery
  charges and support contacts can now differ per delivery area (bound),
  edited through tabs at the top of the customize screen — one tab per
  area, the first marked Default.
- If an area has no value saved, it inherits from the default area, then
  region-level values, then built-in defaults.

2.5 Broadcast notifications go region-wide only
- "Notify all users" from an admin reaches only devices registered in that
  admin's region.

=====================================================================
3. SUPERADMIN CONSOLE
=====================================================================

3.1 Regions management
- Full list / create / edit screens for regions, each with any number of
  delivery-area maps (GeoJSON polygons), a name, description and priority
  per area. Areas are evaluated in priority order; priority 1 is the
  region default. Duplicate priorities and missing names are rejected in
  the form and on the server.
- Regions cannot be deleted (too much depends on them).
- The first region (Mahabubnagar) ships with its two delivery-area maps
  already loaded.

3.2 Mandatory notification channels per region
- Every new region must be created with at least one Telegram channel
  (bot + destination); the form won't submit without it.
- Staff admin accounts are created with an explicit region and role.

=====================================================================
4. ORDERS, NOTIFICATIONS & CHARGES (platform behavior)
=====================================================================

4.1 Order pricing follows the delivery address
- Item prices, flash availability, delivery charges and minimum-order
  thresholds are all taken from the order address's area — not always
  region 1 as before. An order placed in region 2 is validated and priced
  with region 2's data.

4.2 Staff alerts are regional
- When an order is placed, only admins of that order's region get the push
  alert (with a tap-through to the order). Orders with no determinable
  region still alert everyone so nothing is missed.
- Order alerts also go to Telegram, one message per region, delivered to
  every Telegram channel configured for that region. Regions with no
  channel configured are logged and skipped.
- Raising a complaint also alerts the relevant region's admins (based on
  the complaint's order, else the customer's default address).

4.3 Tags can repeat across regions
- The same tag name (e.g. "Fruits") can now exist in multiple regions;
  names only need to be unique within one region. (Requires the pending
  migration; until it runs, the old global uniqueness still applies.)

=====================================================================
5. EDGE CASES & SAFETY BEHAVIOR
=====================================================================

- No region match: user is told they are outside the service area and can
  continue by picking a region manually.
- No permission / location off: distinct messages and correct Settings
  destination for each case; manual region pick always available.
- App reinstall / corrupted saved data: stored region is validated on
  launch; unknown values are discarded and the user is asked again.
- Empty cart on region/address change: switches over silently, no popups.
- Cart lines that survive a move keep working; only real changes are shown.
- Slot moves under an hour apply quietly on confirmation; moves over an
  hour are flagged prominently in the confirmation.
- Canceling a region/address confirmation leaves everything exactly as it
  was (cart, region, selected address).
- Rapid repeated switches: overlapping operations are guarded so carts
  can't corrupt each other.
- Addresses without coordinates: area is resolved from the region default;
  charges fall back down the chain (area → default area → region → built-in).
- Areas whose maps overlap: the highest-priority area wins, consistently
  for detection, pricing and settings.
- Deleting a delivery area also cleans up its area-specific settings so
  no orphaned values linger; editing an area keeps its identity (and its
  settings) instead of recreating it.
- Old devices/tokens with no region recorded are treated as region 1, so
  nobody silently stops receiving notifications after the upgrade.

=====================================================================
6. INTENTIONALLY UNCHANGED / KNOWN NOTES
=====================================================================

- Coupons, reviews, payments and complaint handling (other than the new
  admin alert) are not region-dependent.
- Flash-delivery eligibility of a product is still decided per region.
- The legacy fallback vendor page and old REST summary endpoints were
  removed; all screens use the current data paths.
- Super-admins retain full cross-region visibility and action rights in
  every admin surface.
