freshyo/PRODUCT-REPORT.txt
2026-10-05 11:46:47 +05:30

183 lines
9.5 KiB
Text

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.