THE LABS GADGET · CRM -> FINANCE AUTOMATIC RECEIPT SYNC V2.1

IMPORTANT: Unlike webhooks, this integration READS data from your CRM database without modifying CRM files or database. It imports ONLY confirmed paid POS/repair receipts into Finance. Scheduled mode uses cPanel Cron Jobs.

DATA START: 1 November 2026 Asia/Kuala_Lumpur. Do not sync historic pre-start data into the opening balance.

STEP 0: BACKUP both CRM & FINANCE databases (phpMyAdmin SQL Export) + financehub folder.
STEP 1: Upload/extract ZIP directly in the financehub folder. It ADDS new files; does not replace app/bootstrap.php, app/actions.php, app/views.php or any CRM files.
STEP 2: Login as Finance Owner. Open https://crm.thelabsgadget.com/financehub/install_crm_sync_v2_1.php and install two NEW finance-only tracking tables.
STEP 3: On cPanel Manage My Databases, create a NEW user with SELECT-only privileges on the CRM database (example CRM DB 'thelabsgadget_thelabs_crm'). Do not use the Finance user or give CRM write privileges to this integration. The read-only user requires SELECT on POS tables (pos_sales,pos_payments) and repair_payments. Prefer cPanel with only SELECT checked. Never send password in chat.
STEP 4: In financehub/app/ duplicate crm_sync.local.example.php as crm_sync.local.php. Edit that new file with exact CRM MySQL host, port, full DB name, read-only DB username & password. Verify app/.htaccess blocks direct web access.
STEP 5: Open https://crm.thelabsgadget.com/financehub/crm_sync.php as Owner. The page lists Finance account IDs. Map POS payment methods in crm_sync.local.php to suitable Finance account IDs. For QR/card with delayed settlement, create a separate Bank/E-wallet clearing account before mapping; later transfer actual settlement to bank. For cash use Cash Drawer; for bank transfer use business bank. Zero means unmapped; sync will pause upon encountering it, without losing a transaction.
STEP 6: Preview CRM connection and recent payments. Before November 1, there should normally be no live imports if start_date remains 2026-11-01. Verify the bank opening balance and opening date on Finance before live imports.
STEP 7: Owner clicks 'Sync Confirmed Payments Now'. Repeated clicks NEVER duplicate an already imported CRM payment. Check Finance Cash Flow and the finance account.
STEP 8: Once tested using authentic post-start receipts, optionally enable cPanel Cron Jobs every 5-15 minutes. Sample schedule: */5 * * * * [PHP_CLI_PATH] [FULL_ABSOLUTE_PATH_TO]/financehub/crm_sync_cron.php (set using cPanel UI; use your real PHP path, do not guess).
STEP 9: DELETE ONLY install_crm_sync_v2_1.php. Keep crm_sync.php, cron.php, app/crm_sync_lib.php, app/crm_sync.local.php.

CRITICAL:
* Never import the same POS/repair receipt twice by both CRM Sync and manual Finance Money In/CSV/webhook.
* A CRM sale void does NOT prove a refund actually occurred. Imported receipts are flagged for manual review rather than auto-reversed. Reconcile and record real refund separately.
* POS split payments and repair deposits are treated as individual receipts.
* CRM paid_at is stored in UTC, converted to Asia/Kuala_Lumpur for Finance reporting.
* Verify exact CRM deployed schema against the Phase 11 / Phase 4 packages; no production host test has been run.
* Existing Finance tables are left intact. Installer creates only fh_crm_sync_receipts and fh_crm_sync_state.
* After install, Finance HR Full Admin (Mawar) can view sync status; only Owner can run manual sync and install.

SUPPORT: If installer shows an error, do not click it repeatedly; capture error screenshot WITHOUT passwords.
