# RetailOS — Phase 02: Shop Owner Panel

**Status:** Draft for review · **Depends on:** Phase 01 (UI Kit) sign-off
**Duration estimate:** সপ্তাহ ৪–৬ (UI prototype scope)
**Goal:** মূল ব্যবসায়িক ইঞ্জিন — এই ধাপ শেষ হলে সফটওয়্যার একটি দোকানে দৈনন্দিন ব্যবহারের জন্য প্রস্তুত হবে (v1.0 MVP-এর মূল অংশ)।

**Depends on (Phase 00 decisions this phase implements):** Inventory Rules (batch/FIFO), POS Transaction Flow, Invoice Numbering, Permission Matrix (owner/manager/cashier/inventory_staff scopes)

---

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

| # | Module | Description |
|---|---|---|
| 1 | Dashboard (KPIs, Business Health Score) | Today's sales, low-stock alerts, due collections, at-a-glance health indicator |
| 2 | Product / Category / Brand / Unit | Full CRUD, hierarchy (category→product), unit conversion (pcs/box/kg) |
| 3 | Barcode & Batch / Expiry | Barcode generate/scan, batch-level stock per Phase 00 Inventory Rules |
| 4 | POS (Sale, Split Payment, Return) | Implements the POS Transaction Flow exactly as specified in Phase 00 |
| 5 | Purchase & Supplier Ledger | Purchase orders, goods-received, supplier due/payment tracking |
| 6 | Expenses | Categorized expense entry, recurring expense support |
| 7 | Reports | Sales, inventory, profit/loss, due — role-scoped per Permission Matrix |

## 2. Dashboard — Business Health Score

- Composite indicator (not a single KPI) combining: sales trend (7-day vs prior), stock-out frequency, overdue receivables, expense-to-revenue ratio.
- Displayed as a single score/badge (e.g. Good / Watch / At Risk) plus the underlying KPI cards — gives an owner a fast read without digging into reports.
- Score calculation logic must be documented and version-controlled (owners will notice and ask "why did my score drop") — avoid opaque/unexplainable scoring.

## 3. Product / Category / Brand / Unit

- Category is hierarchical (parent/child) — e.g. Beverages → Soft Drinks.
- Unit supports conversion pairs (1 box = 24 pcs) so purchase-in-box, sell-in-piece works without manual math.
- Product creation requires at minimum: name, category, unit, at least one price (cost + sale) — hard validation, not soft warning, since bad product data corrupts every downstream report.

## 4. Barcode & Batch / Expiry

- Barcode auto-generated if not provided (EAN-13 style, tenant-prefixed to avoid collision if shops later share a catalog).
- Every stock-in creates a `product_batches` row (batch_no, expiry_date, quantity, cost) — this is the same entity defined in the Phase 00 ERD.
- Near-expiry threshold configurable per product (default e.g. 30 days) — surfaces on Dashboard and blocks/warns at POS if selling near-expired stock (configurable: warn vs hard-block).

## 5. POS — implementation of Phase 00 flow

Directly implements the 6-step flow from Phase 00 §5 (scan → cart → discount → split payment → confirm/atomic write → invoice). Additional UI-level requirements:
- Full-screen, keyboard/barcode-scanner-first design (minimal mouse dependency) for speed.
- Hold/resume sale (park a cart, serve another customer, resume).
- Offline-tolerant cart state (local draft) — network drop mid-sale should not lose the cart, though final confirm requires connectivity.

## 6. Purchase & Supplier Ledger

- Purchase order → goods received (may be partial) → stock batch created on receipt, not on order.
- Supplier ledger tracks running due balance per supplier, payment history, and links each payment to specific purchase invoices (not just a lump balance).

## 7. Expenses

- Category-based (rent, salary, utility, etc.), tenant-configurable categories.
- Recurring expense template (e.g. monthly rent) auto-generates entries — reduces manual monthly re-entry.

## 8. Reports

- Minimum v1.0 set: Sales summary, Inventory valuation, Profit & loss, Due/receivables, Expense summary.
- All reports respect the Permission Matrix — a `manager`'s report scope may be owner-configured narrower than full P&L (e.g. hide cost/margin data from managers if the owner chooses).
- Export to PDF/Excel required (owners share these with accountants).

---

## Deliverable Sign-off Checklist
- [ ] Dashboard KPIs + Business Health Score logic reviewed and approved
- [ ] Product/Category/Brand/Unit CRUD complete with unit-conversion tested
- [ ] Barcode generation + batch/expiry tracking tested end-to-end
- [ ] POS flow tested against Phase 00 spec (including split payment + return)
- [ ] Purchase → Goods Received → Batch creation flow tested
- [ ] Supplier ledger balances reconcile correctly
- [ ] Expense entry + recurring template tested
- [ ] All v1.0 reports generated correctly and export to PDF/Excel

**Once every box above is checked, Phase 02 is Done. This is the point at which RetailOS becomes usable for a single shop's daily operations — the core of the v1.0 MVP release.**