# Modern Tuckshop and Produce POS Upgrade

This package replaces the old Tuckshop, Produce and Cashier screens with one shared modern POS engine. Both workspaces keep separate products, users, sales, stock and reports.

## Included POS functions

- Touch-friendly product grid, barcode/SKU search and keyboard shortcuts
- Multi-item cart with quantity controls and fractional produce quantities
- USD, ZiG and RAND selling with the system exchange-rate table
- Cash, EcoCash, mobile money, card, bank transfer, credit and split payments
- Percentage or fixed discounts, transaction tax, customer details and notes
- Hold/resume/cancel orders
- Thermal receipts and receipt reprints
- Completed transaction history and filters
- Full transaction void with mandatory reason, user/date audit trail and automatic stock restoration
- Cashier shifts with opening float, expected cash, closing count and variance
- Product, price, supplier, barcode, SKU and reorder management
- Stock deliveries/corrections with a permanent movement audit trail
- Low-stock alerts, payment mix, top-product, profit and seven-day sales reports
- Manager and cashier permissions

## Safe upload procedure

1. Back up the live database, `Uploads/` and `config.local.php`.
2. Upload the **entire package**, not only the three workspace pages. The new pages depend on `pos_core.php` and `pos_workspace.php`.
3. Preserve the live `config.local.php` and `Uploads/` folder.
4. Make sure the database user has `CREATE`, `ALTER`, `INDEX`, `SELECT`, `INSERT`, `UPDATE` and `DELETE` permissions.
5. Open `tuckshop_projects_login.php` and sign in. The POS upgrade runs automatically and safely ignores objects already present.
6. In each manager workspace, open **Settings** and confirm the store name, phone, receipt footer and default tax.
7. Add SKU/barcode values to products and test one low-value sale, receipt, hold/resume and void before normal use.

## Void rules

- Managers can void any completed transaction in their own workspace.
- Cashiers can void only their own transactions created on the current day.
- A reason of at least five characters is compulsory.
- A void never deletes the transaction. It marks it `voided`, records the operator, time and reason, excludes it from sales totals, and returns each item to stock.

## Existing sales

Old `tp_sales` rows are linked into the new transaction header automatically in small batches when a POS workspace opens. Existing receipt references are preserved. Legacy rows without a receipt reference receive a `LEGACY-...` reference.

## Optional SQL file

`DB/modern_pos_schema.sql` contains the full schema for a new installation. Existing installations normally do not need to import it because the application performs an idempotent upgrade.
