THE LABS GADGET CRM — PHASE 13
SUPPLIER & PURCHASE ORDER MANAGEMENT
Version: 13.0 | PHP 8.1+ / MariaDB/MySQL | UI: English

COMPATIBILITY
- Built against Phase 12 CRM (with Phase 11 POS and Phase 10 Settings already present).
- Preserve existing config.php and database. This archive does not include config.php.
- Existing file replaced: crm3.php (updated sidebar navigation only, keeps Phase 12 QC menu).
- New files: crm-purchase.php, suppliers.php, purchases.php, purchase-new.php,
  purchase-view.php, upgrade-fasa13.php, assets/purchase.css, assets/purchase.js.

BEFORE UPLOADING — REQUIRED SAFETY CHECKS
1. Back up all website files as a ZIP OUTSIDE public_html, and export the entire CRM
   database via phpMyAdmin (Quick → SQL). Ensure both backups really exist.
2. Back up the CURRENT production crm3.php separately.
3. Ensure Phase 12 version of crm3.php is installed. If you customized it after
   Phase 12, compare before overwriting; copying this file may overwrite changes.
4. Consider maintenance mode or schedule an off-peak install; avoid simultaneous
   edits while verifying the module.

INSTALLATION
1. cPanel → File Manager → document root for crm.thelabsgadget.com.
2. Upload this ZIP. Extract IN THAT SAME DIRECTORY.
3. Overwrite crm3.php ONLY after verifying the backups and source version.
4. Login to CRM as Owner. Browse /upgrade-fasa13.php.
5. Press Activate Phase 13. Migration creates SEVEN additive tables:
   suppliers, supplier_audit, purchase_orders, purchase_order_lines,
   purchase_receipts, purchase_returns, purchase_order_events.
6. Delete upgrade-fasa13.php immediately once activation succeeds.
7. Open /suppliers.php to create a supplier, then /purchases.php.

USER ROLES
Owner / Manager / Accounts-HR (with Inventory permission):
 - Manage suppliers, create/submit/cancel PO, receive stock and return goods.
Frontdesk (with Inventory permission):
 - View POs and confirm goods received; cannot manage PO costs, returns,
   supplier edits or PO creation.
Other staff: No access to Supplier & Purchase Order module.
Staff Permissions in Phase 10 still control the parent Inventory permission.

DAILY WORKFLOW
1. Register supplier at suppliers.php.
2. Ensure item is in Inventory first (barcode already registered). For a new
   product, use inventory.php to register it with initial quantity ZERO.
3. Create PO in purchase-new.php: supplier, item barcodes, quantities,
   purchase unit costs; save as Draft.
4. Submit PO in purchase-view.php; order quantities are NOT STOCK.
5. When goods physically arrive, open PO → Receive Goods, select/scan the
   registered item barcode, set actual quantity and supplier delivery reference,
   then click Confirm Goods Received & Stock In. Inventory is incremented.
6. For damaged/incorrect deliveries, Manager/HR/Owner can record Supplier Return;
   quantity is deducted from available stock; replacement outstanding reopens.
7. Review inventory-history.php for the immutable stock movement audit.

IMPORTANT SAFETY NOTES
- Scanning a barcode alone NEVER increases or decreases stock.
- The server checks the scanned barcode matches the selected PO line.
- PO receipts are limited to the outstanding quantity; cannot over-receive.
- Every receipt/return has a unique request token (double-click prevention).
- All stock changes and receipt/return history are committed atomically.
- Costs on PO lines are purchase cost snapshots; NOT automatically updated
  inventory costing, Sales Dashboard, accounts payable or bank balances.
- Supplier Returns do NOT automatically issue refunds or supplier credits.
- Supplier barcodes must match the registered CRM Inventory barcode/SKU.
- Browser camera: works with HTTPS and supported BarcodeDetector formats;
  offline Code 39 fallback is also included for CRM-generated labels.
  USB/Bluetooth scanner in keyboard mode is supported.

SMOKE TEST (test SKU, not real stock)
[ ] Supplier can be registered
[ ] Draft PO saved without inventory change
[ ] Submitted PO changes status to Ordered
[ ] Scan existing barcode and confirm 1 unit received
[ ] Stock and Inventory History show +1 and PO reference
[ ] Repeating confirmation does not duplicate receipt
[ ] Record supplier return of 1 unit with reason
[ ] Stock History shows -1 and status reopens for replacement
[ ] Accounts/HR permission works; Frontdesk cannot see costs
[ ] Technician cannot access /purchase-view.php directly

ROLLBACK
- If the new module fails, restore ONLY crm3.php from its backup to remove
  the navigation item, and restore any other changed website files if needed.
- New module pages can be removed after backing up any purchase data.
- NEVER casually drop the seven new tables: they may now contain purchase
  records and audit history. Seek assistance for database rollback.
- Installer uses CREATE TABLE IF NOT EXISTS and inserts no fake transactions.

LIMITATIONS
- This Phase 13 version does not integrate supplier invoices with
  Accounts Payable or bank transfers and does not email a PO to suppliers.
- Actual payment/refund to suppliers must be handled separately.
- This package was checked statically. Production DB concurrency, printer
  formats and mobile camera scanning must be tested on the live environment.
