THE LABS GADGET CRM — PHASE 11 | POINT OF SALE (POS)
====================================================
System: crm.thelabsgadget.com
Design: English / Futuristic Dark Blue / The Labs Gadget logo
Release: Phase 11A • PHP 8.1+ • MySQL/MariaDB (InnoDB)

WHAT'S INCLUDED
---------------
• POS screen: scan product barcode via USB/Bluetooth keyboard scanner or camera where supported.
• Search by barcode, SKU, product name or compatible phone model.
• Cart supports quantity, listed selling price, supervisor price override (reason required) and discount (reason required).
• Cash, QR, Card, Bank Transfer and E-Wallet. Optional two-method split payment.
• Cash received / change calculator; printed receipt with company information and logo.
• Physical inventory deducted ONLY after confirmed paid checkout; each movement logged by cashier.
• Service Charge and Software can be sold without reducing physical inventory.
• Mobile Phone inventory category supported: IMEI/serial required at checkout (one phone per line).
• Serial number cannot be re-sold while marked sold. Serial marked returned if void + physical restock.
• Each POS payment is written once to the existing sales_ledger, so Fasa 2/5/9 sales totals include POS sales.
• Payment method breakdown now merges repair payments and POS payments, excludes voids.
• Sales history and manager/owner-controlled void with mandatory reason and optional physical restock.
• Separate POS module permission visible in Settings > Staff Permissions (Phase 10).

ACCOUNT ACCESS
--------------
Owner, Manager, Accounts/HR: POS, selling prices, price override, reasoned discounts, full store POS sales.
Frontdesk: POS using listed selling prices; cannot edit selling prices/discounts/void; sees own transactions.
Technician/other staff: No POS by default; POS requires an eligible cashier role.
Only Owner/Manager may void POS sales. POS also requires Permissions for Inventory & Barcode and Payments & Invoices.

IMPORTANT: BACKUP BEFORE INSTALLING
-----------------------------------
1) From cPanel File Manager, back up the complete CRM web folder outside public_html.
2) Export the CRM SQL database from phpMyAdmin and keep it securely OFF the public web root.
3) In particular, back up the following PHP files (these are the existing files the ZIP will overwrite):
   - crm3.php
   - dashboard.php
   - crm-inventory-categories.php
   - crm-settings.php
   - crm-reports.php
   - reports.php
4) Extract ZIP to the EXACT SAME document root as the existing login.php and dashboard.php.
5) Confirm new files pos.php, pos-prices.php, pos-checkout.php, pos-sales.php, pos-receipt.php,
   pos-lookup.php, pos-void.php, crm-pos.php and assets/pos.* appear.
6) Login as Owner and open https://crm.thelabsgadget.com/upgrade-fasa11.php
7) Click Activate Phase 11 ONCE and confirm success. Six empty POS tables are added.
8) Delete upgrade-fasa11.php from hosting IMMEDIATELY after successful activation.
9) CRM Settings > Staff Permissions: review the new Point of Sale (POS) permission for each role.
10) Manage Selling Prices (pos-prices.php) to enter retail selling price for physical items and services.
11) Open pos.php, scan and complete one controlled TEST sale, then verify receipt, inventory and sales report.

NEW DATABASE TABLES (ADDITIVE ONLY)
-----------------------------------
pos_sales; pos_sale_lines; pos_payments; pos_item_prices; pos_price_audit; pos_sold_serials
The installation does not delete/overwrite user, customer, repair, warranty, inventory or old sales data.
Existing Inventory gains Mobile Phone as a NEW CATEGORY (all old item categories unchanged).

SAFE TEST PLAN
--------------
• Use a designated test spare part with known stock (for example 3 units).
• Set selling price under Manage Selling Prices.
• Scan the barcode, add 1 unit, and complete a TEST cash sale. Check stock fell by exactly 1.
• Verify its POS receipt and sales_ledger amount (reports.php).
• If the test sale is not real, have Owner/Manager void it with a reason. Choose RESTOCK only
  if the physical test item is in hand and should return to sellable stock. Check the stock ledger.
• Verify voided payment is removed from sales totals, while sale/void history remains.
• Test Staff Permissions with a Frontdesk account; direct POS URLs must be forbidden when disabled.
• Test mobile phone sale with a nonreal sample serial on test inventory only; serial captured at sale.

IMPORTANT OPERATIONAL LIMITATIONS
---------------------------------
• This is an IN-HOUSE POS and receipt system, NOT a connected card/QR payment terminal.
  Actual bank/payment-provider settlements must still be verified externally.
• A POS void changes CRM transaction status; it DOES NOT send a real cash/card/QR/bank refund.
  Use void only for an erroneous sale, with audit reason; issue actual refunds/credit notes separately.
• This release allows up to TWO tender methods per receipt. The sales ledger counts each payment,
  so split tender creates two payment entries, while amounts are summed only once.
• Inventory items must be registered and given a POS selling price before sale. No fake stock is inserted.
• Camera barcode scanning depends on browser support (BarcodeDetector and HTTPS); scanner USB/Bluetooth
  in keyboard mode and manual barcode entry are available as alternatives.
• Mobile Phone IMEI/serial is recorded at CHECKOUT; individual IMEI intake/receiving verification
  is NOT included in this first POS release. Use a verified item/serial in your store processes.
• Stock is shared between POS and Repair Job usage. Sale and stock movement are atomic on MySQL/InnoDB.
• No Loyverse import included; historical data migration remains the FINAL phase.
• Receipt is printable/save-as-PDF through browser and is NOT a validated LHDN MyInvois e-Invoice.
• Shipping tax, partial credit sales, normal customer refunds/returns, loyalty rewards and
  real payment provider reconciliation are NOT yet implemented. Do not represent the receipt as official tax validation.
• This package was statically checked locally; test it on staging if possible. Live database
  integration and scanner camera compatibility MUST be validated on the actual hosting/phones.

ROLLBACK
--------
If the upgrade breaks the interface, restore the backed-up PHP files, retaining the new POS tables
for diagnosis. For a full rollback of database changes, use a verified SQL backup from just before
installation and follow your host's restoration process. Do not drop POS tables while they hold data.

SECURITY
--------
Do not upload config.php, production SQL backups or contact exports to public_html.
Keep backups in Home Directory outside the web root. Delete upgrade-fasa11.php after activation.
