# RetailOS — Phase 04: Online Shop

**Status:** Draft for review · **Depends on:** Phase 02 (Shop Owner Panel — product/inventory data) and Phase 03 (CRM — new-customer lead creation)
**Duration estimate:** সপ্তাহ ৯–১০ (UI prototype scope)
**Goal:** প্রতিটি দোকানের নিজস্ব storefront — v2.0 Scale release-এর অংশ। নতুন কাস্টমারের অর্ডার এলে Lead তৈরি হবে, পুরনো কাস্টমারের অর্ডার সরাসরি Order-এ যোগ হবে।

---

## 1. Deliverable Checklist (per roadmap chip list)

| # | Module | Description |
|---|---|---|
| 1 | Store Home | Public storefront landing per tenant (shop-slug/subdomain based) |
| 2 | Products | Public product listing/detail, pulled from same `products` table as dashboard (Phase 02) |
| 3 | Cart | Session/account-based cart |
| 4 | Checkout | Address, payment method, order confirmation |
| 5 | Orders | Customer order history + status tracking |
| 6 | Delivery Tracking | Status progression visible to customer |

## 2. Tenant Storefront Resolution

- Per Phase 00 Tenant Model — storefront resolved via shop-slug/subdomain (not authenticated session, since this is public-facing).
- Storefront respects tenant isolation the same way the dashboard does: product/price/stock data queried strictly scoped to the resolving tenant — no cross-shop leakage in listings or search.

## 3. Store Home & Products

- Product listing reads live stock from `product_batches` (Phase 00 ERD) — out-of-stock items shown but not orderable, not hidden (avoids customer confusion vs. "product doesn't exist").
- Pricing shown is the tenant's configured sale price; no separate "online price" entity unless the owner explicitly needs channel-specific pricing (flag as a future decision, not built by default in v2.0 scope).

## 4. Cart & Checkout

- Cart persists per customer session; if the customer logs in mid-session, cart merges into their account rather than being discarded.
- Checkout requires: delivery address, contact number, payment method (COD by default; online payment gateway is a separate integration decision, not assumed here).
- On order placement:
  - **New customer** (no existing `customers` record for this tenant) → creates both a `customers` row and a **Lead** in the CRM pipeline at the "New" stage (per Phase 03).
  - **Existing customer** → order attaches directly to their existing customer record and Purchase History (Phase 03 §5), no duplicate lead created.

## 5. Orders → maps to Sales/Invoice model

- An online order is a `sales` record with `channel = online` (extends the same entity from Phase 00 §4/§5, not a parallel order system) — this keeps Reports (Phase 02 §8) and Purchase History (Phase 03 §5) accurate without needing to merge two data models later.
- Order confirmation triggers the same invoice-numbering rule as POS (Phase 00 §7) — one numbering sequence per tenant regardless of sales channel.

## 6. Delivery Tracking

- Minimal v2.0 status set: `Placed → Confirmed → Out for Delivery → Delivered` (Cancelled/Returned as exception states).
- Status updates are staff-driven from the dashboard (Phase 02 Orders view) — no courier-API integration assumed by default; that would be a separate ADR if/when a specific courier partner is chosen.
- Each status change should be able to trigger a Notifications Engine (Phase 03 §4) entry — e.g. "Out for Delivery" SMS — reusing the same shared queue rather than a storefront-specific notification path.

## 7. Permission Notes

- Storefront itself is public/unauthenticated except for the customer's own account area (order history, profile).
- Dashboard-side order management follows the existing Permission Matrix (Phase 00 §2) — Manager/Owner manage orders; Cashier typically not involved unless explicitly granted.

---

## Deliverable Sign-off Checklist
- [ ] Storefront tenant resolution (slug/subdomain) tested for cross-tenant isolation
- [ ] Product listing reflects live stock/pricing from dashboard data (single source of truth verified)
- [ ] Cart persistence + login-merge behavior tested
- [ ] Checkout flow tested for both new-customer (creates Lead) and existing-customer paths
- [ ] Online orders confirmed to use the same Sales/Invoice model and numbering sequence as POS
- [ ] Delivery status flow tested, notification triggers verified

**Once every box above is checked, Phase 04 is Done — this completes the storefront portion of the v2.0 Scale release.**