# Pro POS Addon — Purchase Haat / Smart Tech OMP

This addon adds a professional vendor-ready POS layer to the RAW PHP marketplace. It is designed for shared hosting/cPanel and uses only RAW PHP, MySQL, jQuery/vanilla JavaScript, HTML5, CSS3 and browser PWA capabilities.

## Main entry points

- `pos/register.php` — mobile-first POS selling screen.
- `vendor/pos.php` — vendor control panel entry and POS dashboard.
- `vendor/pos-staff.php` — vendor POS cashier/manager assignment.
- `admin/pos.php` — admin POS control center.
- `pos/shifts.php` — shift opening/closing and cash drawer movement.
- `pos/held.php` — suspended/held carts.
- `pos/refunds.php` — refund/exchange workflow.
- `pos/reports.php` — X/Z report screen.
- `pos/print-labels.php` — barcode label print screen.
- `pos/receipt.php?id=SALE_ID` — 58mm/80mm browser receipt print.

## Scanner support

The POS supports two scanner modes:

1. **Barcode machine / USB / Bluetooth scanner**: works as keyboard input. Focus the hardware scanner input, scan, and the Enter suffix adds the product.
2. **Phone camera scanner**: `public/assets/js/pos-scanner.js` uses the browser `BarcodeDetector` API when available. When unavailable, cashiers can use manual SKU/barcode entry or a hardware scanner.

## Printing support

The browser print layer supports:

- 58mm and 80mm thermal-style receipt layout.
- A4 invoice-style print route through receipt templates.
- Product barcode label sheet printing.
- Auto-print after sale completion using `window.print()` through a receipt popup.

For silent ESC/POS printing, connect a local print bridge or browser kiosk setup. The included RAW PHP project remains framework-free and does not require Node/Composer.

## Role-based POS access

Seeded roles:

- `pos_manager` — supervisor role for selling, refunds, reports, shifts and settings.
- `pos_cashier` — cashier role for selling, held carts and own shift.

Database tables:

- `pos_roles`
- `pos_role_permissions`
- `pos_staff_assignments`

Abilities include `pos.sell`, `pos.hold`, `pos.refund`, `pos.shift`, `pos.cash_drawer`, `pos.report` and `pos.settings`.

## Shift and cash drawer workflow

1. Manager/vendor creates an outlet and register.
2. Cashier opens shift with opening cash.
3. Sales update `pos_sales`, `pos_sale_items`, `pos_payments`, `pos_stock_movements` and product stock.
4. Cash in/out movements are stored in `pos_cash_movements`.
5. Cashier closes shift with counted cash; admin can review expected cash and variance.

## Offline/PWA workflow

The PWA uses:

- `public/manifest.json`
- `service-worker.js` and `public/service-worker.js`
- `public/pos-offline.html`
- `public/assets/js/pos-core.js`

The POS stores the active cart in browser local storage. When the browser reports offline, completed sales are saved into a local queue and synced through `api/pos-sync.php` when internet returns. Live stock/payment finalization still depends on server sync.

## API endpoints

- `api/pos-product-search.php` — product search and barcode/SKU lookup.
- `api/pos-checkout.php` — complete sale, update stock and create payment records.
- `api/pos-held-sales.php` — hold, list, load and delete held sales.
- `api/pos-shift.php` — open/close shifts and cash drawer movement.
- `api/pos-refund.php` — create refund records.
- `api/pos-sync.php` — sync offline queued sales.
- `api/pos-customer.php` — quick customer lookup/create for POS.

## Demo accounts

Password: `admin123`

- Vendor: `vendor@smarttech-omp.com`
- POS cashier: `poscashier@smarttech-omp.com`
- POS manager: `posmanager@smarttech-omp.com`

## Production checklist

- Use HTTPS; camera scanning and PWA install require secure browser contexts in production.
- Replace demo passwords and review staff roles.
- Confirm receipt printer paper width and browser kiosk settings.
- Test stock decrement, refunds, shift close and offline queue sync before live use.
- Connect official bKash/Nagad/card terminal reconciliation if physical stores need external payment validation.
