# POS update — 5 November 2026

This package updates the existing Laravel POS application. It is not a fresh installation and does not include the live `.env` file.

## Included changes

### Branches and stock
- Users can be assigned to one or more active branches from **Settings → Users**.
- Users assigned to multiple branches are prompted to select a working branch after signing in; the branch selector remains available in the top bar.
- Branches can be created up to the five-branch limit. The user creating a branch is assigned to it automatically.
- Stock is held in branch-specific stores. Product creation/editing supports assigning a product to one or more branches.
- On the Products page, select products and copy their catalogue assignment to another assigned branch. Copied stock starts at zero.
- Stock Transfers can move quantity from the selected branch to another branch where the product is assigned.
- POS stock figures, purchases, stock takes, expenses, transfers, shifts, dashboards and branch-scoped reports use the selected branch.

### Guest Rooms
- Independent Guest Rooms area with room types, rooms, reservations, availability checks, check-in/check-out and guest payments.
- Independent room expenses and Guest Rooms reports.
- The Guest Rooms feature switch controls both the sidebar link and route access. The Manager role receives room management access; the Accountant role receives read-only access by default. Other roles can be granted `rooms.view` and `rooms.manage` in Roles & Permissions.

### Butchery
- Independent Butchery area with receiving batches, kg/gram sales, wastage tracking and available-weight controls.
- Independent Butchery expenses and reports.
- The Butchery feature switch controls both the sidebar link and route access. The Manager role receives butchery management access; the Accountant role receives read-only access by default. Other roles can be granted `butchery.view` and `butchery.manage` in Roles & Permissions.

### POS and cashier shifts
- POS orders default to **Walk-in customer**. The customer selector can assign an existing customer. The plus link opens the Add Customer dialog in Customer Accounts.
- Cashier Shifts displays opening cash, cash sales, M-Pesa sales, credit sales, total sales and a product/quantity/amount breakdown.
- The cashier closes the shift using the **Close shift** button. No actual-cash or total-sales amount is typed in.
- The application product name and bundled User Guide are fixed to **POS**.

## Installation

1. Make a full backup of the live application files and database.
2. Upload and extract this ZIP over the existing application. Preserve the existing `.env` file and existing `storage` files; this ZIP intentionally excludes `.env` and runtime log/cache files.
3. Select the existing application database in phpMyAdmin and import `POS_UPDATE_ONLY_BRANCHES_ROOMS_BUTCHERY_POS_CASHIER_2026-11-05.sql`. This is an update patch, not a full database dump.
4. Do not import the full database dump again. Do not run the corresponding migrations as well after importing this SQL patch; choose the SQL patch path or the Laravel migration path, not both.
5. Clear Laravel's cached configuration/routes/views with `php artisan optimize:clear`.
6. Sign in as an administrator. Check **Settings → Users** and assign staff to the correct branch or branches. Check **Branches** and **POS Modules**. Guest Rooms and Butchery are enabled by the SQL patch; they can subsequently be switched off/on from POS Modules. Managers receive access by default; accountant access is read-only. Custom roles can be adjusted under **Roles & Permissions**.
7. Select a branch in the top bar. Assign/copy products to each branch, then use **Stock Transfers** to move stock between branches.

## Important notes

- Existing users and existing products are assigned to Main Branch by the update SQL, preserving the existing installation's operating data in that branch.
- Branch stock balances are independent. Copying a product only makes it available in the destination branch; it does not copy stock quantities. Use a stock transfer to move actual stock.
- Customers and suppliers remain shared master records across branches; transactions and stock are branch-scoped.
- Guest Rooms and Butchery have separate operational records, expenses and reports. They do not merge their transactions into restaurant/bar shift totals.
- The source database export supplied for this update is MySQL 8.0.36. Import the patch into the same existing database after taking a backup.

## Validation performed

- PHP syntax checks passed for 229 application, route, config, bootstrap and migration PHP files.
- The ZIP archive was checked for integrity after packaging.
- Full browser/database execution could not be run in the build environment because its PHP CLI lacks `mbstring` and a MySQL PDO driver. The update should therefore be tested on a staging copy with the required PHP extensions and database connection before production use.
