THE LABS GADGET CRM — PHASE 4
PAYMENT & INVOICE MANAGEMENT (direct CRM payment records)
==========================================================

This patch is built on the supplied Phase 3 English+Logo code and the
Automatic Repair Workflow + Job Timer upgrade. It uses the existing
Phase 2 sales_ledger and does NOT replace app.php or config.php.

BEFORE INSTALLATION
- Test first on a staging copy if available. Hosting runtime and live
  database behavior have not been verified from this package.
- Download a backup of the entire CRM site (especially repair-view.php,
  dashboard.php and crm3.php) AND export your database with phpMyAdmin.
- Store backup files outside public_html. Never share config.php or
  database credentials.
- Ensure Phase 2, Phase 3 and Automatic Workflow have been activated.

UPLOAD
1. Open cPanel File Manager and find your verified CRM document root.
   It may be public_html/crm.thelabsgadget.com, depending on Domains.
2. Upload The_Labs_Gadget_CRM_Fasa4_Payments_Invoices.zip to this folder.
3. Extract ZIP in the same folder; choose overwrite for ONLY these existing
   files if they have not been independently modified:
      dashboard.php
      crm3.php
      repair-view.php
   New files are listed below. Do NOT overwrite config.php; not included.
4. Sign in as Owner and open:
   https://crm.thelabsgadget.com/upgrade-fasa4.php
5. Click Activate Phase 4 (POST), then open Payments & Invoices.
6. After successful activation, DELETE upgrade-fasa4.php from the server.

NEW FILES
  crm-payments.php          PHP helper library (direct access blocked)
  payments.php             Payments list (financial staff only)
  payment-job.php          Service price, deposits, balance, void history
  invoice.php              Printable service invoice / payment statement
  receipt.php              Printable payment receipt
  upgrade-fasa4.php        Owner-only additive database migration
  assets/payments.css      CRM screen styles
  assets/payments-print.css  Print / Save as PDF styles
  assets/payments-print.js External Print button handler (CSP-safe)

DATABASE CHANGES (ADDITIVE ONLY)
  repair_invoices          One service price per repair job
  repair_payments          One immutable entry per received payment
  repair_price_audit       Price-change history
  sales_ledger             Existing table, now receives one row per payment

RULES
- Allowed to price / record payments: Owner, Manager, Accounts/HR, Frontdesk.
- Once a payment is recorded, Frontdesk cannot change the service price.
  Owner, Manager and Accounts/HR can, but never below the amount paid.
- Only Owner and Manager can VOID an incorrectly recorded payment, and
  they must provide a reason. Both payment and ledger entries are retained
  with void status and excluded from sales totals / balances.
  VOID is only for correcting mistaken entries: it is NOT a real refund.
  A separate refund/outgoing-cash module would be needed for refunds.
- Staff not listed above cannot open payments, invoices or receipt pages.
- The staff receiving credit for a sale is shown when recording a payment.
  Default: currently assigned active staff, or the cashier if unassigned.
  Owner/Manager/Accounts may choose a different active staff member.
  Frontdesk cannot override sales credit. Other staff see their own credited
  sales on their Dashboard; store-wide totals remain Owner/Manager/Accounts.
- Prices alone are NOT paid sales. A received deposit counts on that day;
  a later balance payment counts only when received. Never count again at
  Collected. Previously recorded sales in the ledger remain intact.
- No automatic email, bank, gateway or Loyverse integration is included.
- Collection is NOT blocked by an outstanding balance; check Balance Due.
- 'Invoice' is a CRM service invoice / statement, not a validated LHDN
  MyInvois e-Invoice. No SST/tax treatment is assumed.
- Receipts require a logged-in, authorised staff session to print.

SUGGESTED UAT / ACCEPTANCE TEST
1. Login as Owner; open Payments & Invoices.
2. Choose a test job; set service price RM180.00.
3. Receive RM50.00 as Cash deposit. Print receipt.
4. Verify Balance Due = RM130.00; Sales Dashboard +RM50.00.
5. Receive RM130.00 as QR Payment; verify balance RM0.00 and dashboard
   total +RM180.00 in aggregate, not RM360.00.
6. Verify printable invoice lists both actual payments.
7. If you test Void Payment, give a reason and confirm void is excluded
   from both job balance and store sales; add a replacement if applicable.
8. Login as technician/staff; direct-open payments.php should be blocked.
   Login as Accounts or Manager; store-wide dashboard remains available.
9. Check existing repair workflow buttons and Job Timer still operate.

ROLLBACK
- Site: restore the 3 overwritten PHP files; delete newly added files.
- Database: restore database backup ONLY if necessary, after considering
  payments made since the backup. Avoid restoring an old database over
  live new financial transactions; coordinate with a developer.

For deployment issues, send only error screenshots with credentials,
customer personal details and bank references obscured.
