iKOOP COMMISSION MANAGEMENT SYSTEM v3.1
========================================
FINAL FULL PACKAGE v3.1 - PHP 8.2-8.5 + MySQL/MariaDB


v3.1 - AUTOCOUNT CLOUD ACCOUNTING + PASSWORD RESET ACCESS FIX
- Administration > Integrations supports AutoCount Cloud Accounting API credentials.
- Project can be linked to an AutoCount Invoice No. and synchronized for payment status.
- AutoCount Outstanding = 0 can automatically mark a project Fully Paid.
- Optional invoice amount matching protects against linking the wrong invoice.
- Read-only integration; the system does not create/edit accounting transactions in AutoCount.
- cPanel Cron script included for automatic payment checks.
- Temporary-password users are redirected to the first page allowed by their Role / Permission after changing password.
- Login page automatically uses the logo saved in Company / Template when available, so manual logo edits are not required.
- Role & Permission Management (RBAC) from v3.0 remains included.

v2.5 - CUSTOMER INTAKE RETENTION + PRINT & CLEAR + ACCEPTED INTAKE PURGE
- Customer Forms and Claim Forms support Checkbox — Multiple Choice.
- Super Admin defines the available choices, one per line.
- The person filling the form can tick more than one choice.
- Required multiple-choice fields require at least one selected option.
- The application header no longer displays the software version badge.
- v2.2 Super Admin delete controls remain included.
No Composer / Node.js required.

FUNGSI UTAMA
------------
- User roles: Super Admin, Admin, Operator, Viewer.
- Internal user boleh Register New Account sendiri; akaun kekal Pending sehingga Admin/Super Admin approve.
- Forgot Password menggunakan approval Admin: user request -> Admin approve -> sistem generate temporary password -> Admin beri kepada user -> user wajib tukar password selepas login.
- Notification untuk pending registration dan password reset dipaparkan pada Dashboard dan menu Account Requests untuk Admin ke atas.
- Super Admin boleh kawal/delete data yang dibenarkan sistem dan semua tindakan penting direkod dalam Audit Log.
- People master: Staff / External; seseorang boleh jadi Agent, penerima komisen, atau kedua-duanya.
- People Registration boleh dibuat melalui private invite link yang hanya Super Admin generate dan beri sendiri; applicant tidak boleh pilih Staff/External.
- Super Admin approve/reject People Registration dan tentukan Staff/External, Agent/Commission, status serta Claim Form access.
- Commission Setting: kadar komisen daripada jumlah invoice, kemudian pecahan komisen mesti berjumlah 100%.
- Setiap pecahan komisen boleh dibahagi kepada lebih daripada seorang penerima.
- Project/Sales dengan pengiraan komisen automatik.
- Private Customer Project Forms: Super Admin custom borang + private link; customer submit -> Pending -> Operator ke atas Accept/Reject -> baru create Project.
- Jawapan Customer Intake dikekalkan selepas Accept/Reject untuk semakan/print. Detail sementara hanya dibersihkan apabila user pilih Print / Save PDF & Clear Details; nama projek yang telah diterima kekal pada Project.
- People personal portal mempunyai My Commission yang memaparkan semua komisen di bawah nama penerima (manual/admin, self-claim, project claim, customer form).
- UI v2.0 lebih kemas dengan card/status/required-field highlight dan mobile-friendly view.

- Customer Form field type Dropdown Menu: Super Admin tentukan sendiri pilihan, satu pilihan setiap baris.
- Quick Generate Private Link: pilih borang secara jelas sebelum generate link.
- Senarai private link memaparkan nama borang supaya tidak keliru link itu untuk borang mana.
- Project Customer Payment Gate: projek mesti ditanda FULLY PAID oleh Admin/Super Admin sebelum komisen boleh diproses ke Payment Batch.
- Sokong status Customer Payment: Awaiting Payment, Partial dan Fully Paid; amount received/balance/reference/notes boleh direkod.
- Bulk Mark Fully Paid untuk banyak projek sekali gus.
- Payment Batch: hanya projek Fully Paid + READY boleh dipilih; Paid tidak lagi muncul sebagai Ready.
- Payment Batch print/template dengan logo dan maklumat syarikat.
- Multiple Project Claim Forms untuk Staff dan External.
- Staff atau External yang boleh menerima komisen boleh mempunyai personal claim link sendiri.
- Super Admin boleh hadkan setiap People kepada semua Claim Forms atau Claim Forms tertentu sahaja.
- Setiap Claim Form boleh ada field sendiri, Commission Setting sendiri dan Admin/Super Admin approver sendiri.
- Invoice Amount boleh dijadikan Admin Only dan diisi ketika approval.
- Selepas approved, claimant hanya nampak komisen bahagian dirinya dan payment status.
- Claim upload limits boleh ditetapkan oleh Super Admin: saiz setiap fail, jumlah fail per claim, jumlah MB per claim, jenis fail dan total storage quota.
- Super Admin boleh delete attachment claim secara individu atau semua attachment dalam satu claim tanpa delete claim/project.

============================================================
A. FRESH INSTALL PADA HOSTING / DOMAIN / SUBDOMAIN BARU
============================================================

1. SYARAT HOSTING
- PHP 8.2 hingga PHP 8.5. PHP 8.4 disyorkan.
- MySQL atau MariaDB.
- HTTPS/SSL disyorkan dan Force HTTPS patut diaktifkan.
- PHP extensions yang disyorkan:
  mysqli, pdo_mysql, mbstring, curl, fileinfo, gd, intl, zip, xml, openssl.

2. CIPTA DOMAIN ATAU SUBDOMAIN
Contoh:
  komisen.domainanda.com

Semak Document Root di cPanel, contoh:
  /public_html/komisen.domainanda.com/

3. CIPTA DATABASE
Di cPanel -> MySQL Databases / Database Wizard:
- Cipta satu database.
- Cipta satu database user.
- Sambungkan user kepada database.
- Beri ALL PRIVILEGES.
- Simpan sendiri Database Name, Username dan Password.

4. UPLOAD SISTEM
- Upload ZIP final ini ke Document Root.
- Extract ZIP terus di Document Root.
- Selepas extract, pastikan anda nampak fail/folder seperti:
  index.php
  bootstrap.php
  functions.php
  assets/
  config/
  install/
  storage/
  uploads/

PENTING:
Fail index.php mesti berada terus di Document Root, bukan di dalam satu folder tambahan.

5. PERMISSION
Biasanya cPanel default sudah sesuai:
- Folder: 755
- Files: 644

Pastikan PHP boleh menulis ke:
  config/
  storage/
  uploads/

6. JALANKAN INSTALLER
Buka browser:
  https://DOMAIN-ANDA/install/

Masukkan:
- Database Host: biasanya localhost
- Database Name
- Database User
- Database Password
- Nama Super Admin
- Username Super Admin
- Password Super Admin (minimum 8 aksara)

Tekan "Install System".

Installer akan:
- Create database tables.
- Create akaun Super Admin pertama.
- Create config/database.php.
- Create storage/installed.lock.
- Lock installer daripada digunakan semula.

7. LOGIN
Buka:
  https://DOMAIN-ANDA/

Login menggunakan Super Admin yang dibuat semasa installation.

8. SETUP PERTAMA YANG DISYORKAN
Ikut urutan ini:
1) Company / Template
   - Nama syarikat
   - Logo
   - Alamat / contact
   - Payment Batch title/footer/signature labels

2) Users
   - Cipta Admin / Operator / Viewer jika perlu.
   - Self Registration default ON.
   - Temporary password default sah 24 jam dan boleh diubah oleh Super Admin.
   - Pending registration / Forgot Password diproses di Account Requests.

3) People
   - Daftar Staff dan External secara manual; ATAU Super Admin generate private People Registration Link.
   - Applicant isi link private -> Pending -> Super Admin pilih Staff/External dan Approve/Reject.
   - Tandakan Can be Agent / Can receive Commission ikut keperluan.

4) Commission Settings
   Contoh:
   Invoice RM10,000 x Commission 15% = RM1,500 commission pool.
   Pecahan RM1,500 mesti total 100%, contohnya:
   - Pecahan A = 30%
   - Pecahan B = 20%
   - Pecahan C = 15%
   - Pecahan D = 15%
   - Pecahan E = 10%
   - Pecahan F = 10%
   Total = 100%.

5) Claim Forms (jika digunakan)
   - Cipta satu atau banyak form.
   - Pilih Commission Setting.
   - Pilih approver yang role Admin atau Super Admin.
   - Pastikan ada satu Claimant field mapped kepada Project Name.
   - Pastikan ada satu Admin Only Number field mapped kepada Invoice Amount.
   - Set field lain Required / Optional / Claimant / Admin Only.

6) Projects / Sales
   - Key-in manual project atau approve Project Claim.

7) Customer / Project Payment
   - Buka project dan Admin/Super Admin rekod Amount Received / Partial payment jika perlu.
   - Bila customer/project sudah settle, tekan Mark Fully Paid.
   - Untuk banyak projek, guna Projects / Sales -> tick -> Mark Selected Fully Paid.

8) Customer Forms (jika digunakan)
   - Super Admin create customer form dan custom fields.
   - Map tepat satu field kepada Project Name.
   - Generate private link dan beri sendiri kepada customer.
   - Customer submit + agree proceed -> Customer Intakes.
   - Operator/Admin/Super Admin Accept/Reject.
   - Accepted project bermula SETUP REQUIRED; lengkapkan invoice/commission di Projects.

9) Payment Batches
   - Hanya projek Fully Paid dan status Commission Process = READY akan muncul.
   - Create Batch -> semak -> Mark as Paid.

10) AutoCount Cloud Accounting (optional)
   - Administration -> Integrations.
   - Masukkan Account Book ID, Key ID dan API Key.
   - API permission: Get Invoice + Get Invoice Listing (Simple).
   - Link AutoCount Invoice No. pada setiap Project.
   - Untuk auto-sync, pasang cPanel Cron command yang dipaparkan dalam Integrations.

============================================================
B. PINDAHKAN SISTEM SEDIA ADA KE HOSTING BARU BERSAMA DATA
============================================================

Gunakan cara ini jika anda mahu bawa SEKALI semua People, users, projects, claims, settings, payment history dan data database daripada server lama.

1. BACKUP SERVER LAMA
- Zip semua fail dalam Document Root sistem lama.
- Export database lama melalui phpMyAdmin sebagai .sql.
- Simpan juga folder uploads/ kerana ia mungkin mengandungi logo/dokumen claim.

2. HOSTING BARU
- Cipta domain/subdomain.
- Cipta database baru + database user + ALL PRIVILEGES.

3. UPLOAD FAIL
- Upload dan extract salinan fail sistem lama ke Document Root baru.

4. IMPORT DATABASE
- Buka phpMyAdmin database baru.
- Import fail .sql daripada database lama.

5. TUKAR DATABASE CONFIG
Edit:
  config/database.php

Tukar kepada Database Host / Name / User / Password hosting baru.
Jangan kongsi password database secara terbuka.

6. SEMAK URL
- Login sistem.
- Semak logo/upload.
- Semak Project Claim Links. Staff atau External yang boleh menerima komisen boleh menggunakan Custom Claim Link yang ditetapkan oleh Super Admin; domain akan ikut hosting semasa secara automatik.
- Test satu claim dan satu payment/report sebelum live.

============================================================
C. BACKUP SEBELUM UPDATE / PINDAH SERVER
============================================================
Sentiasa backup dua benda:
1. Semua website files, terutama config/, storage/ dan uploads/.
2. Full MySQL database export (.sql).

Database adalah bahagian paling penting kerana semua project, commission, status Paid/Unpaid, claim dan audit history berada di sana.

============================================================
D. KESELAMATAN
============================================================
- Gunakan HTTPS.
- Gunakan password Super Admin yang kuat.
- Jangan berikan password cPanel/database kepada orang yang tidak berkaitan.
- Installer automatik terkunci selepas pemasangan. Untuk keselamatan tambahan, folder install/ boleh dipadam selepas sistem disahkan berfungsi.
- Jangan padam config/database.php pada sistem yang sudah dipasang.
- Jangan padam storage/installed.lock pada sistem yang sudah dipasang.
- Backup sebelum delete data penting atau pindah hosting.

============================================================
E. TROUBLESHOOTING RINGKAS
============================================================
"Database connection/update failed"
- Semak config/database.php.
- Semak DB name/user/password.
- Semak DB user mempunyai ALL PRIVILEGES.
- DB host biasanya localhost.

Installer tidak boleh tulis config/database.php
- Semak permission folder config/.

Upload dokumen/logo gagal
- Semak permission uploads/.
- Semak PHP upload_max_filesize dan post_max_size pada hosting.
- Semak Claim Forms -> Claim Upload Storage untuk limit aplikasi. Limit hosting yang lebih rendah akan tetap mengatasi limit sistem.

Blank page / HTTP 500
- Pastikan PHP 8.2-8.5 digunakan (PHP 8.4 disyorkan).
- Semak PHP error log di cPanel.
- Semak extension pdo_mysql / mysqli aktif.

Domain tidak HTTPS
- Aktifkan SSL/Let's Encrypt dan Force HTTPS Redirect di cPanel.

============================================================
PACKAGE
============================================================
Package: iKOOP Commission Management System v2.5 FINAL
Type: Full fresh-deploy package
Database credentials: NOT included
User data: NOT included


============================================================
F. CUSTOM PROJECT CLAIM LINK (v1.1 + v1.4)
============================================================
Untuk Staff atau External yang ditanda Can receive Commission:
1. Login sebagai SUPERADMIN.
2. Buka People > Edit pada nama tersebut.
3. Di bahagian Project Claim Link, masukkan Custom Claim Link, contoh:
     azman-referral
4. Sistem akan menghasilkan URL seperti:
     https://domain-anda.com/claim/azman-referral
5. Klik Save Custom Link, kemudian Copy Link.

Peraturan:
- Hanya SUPERADMIN boleh menetapkan atau menukar Custom Claim Link.
- Link mesti unik untuk setiap penerima.
- Space/underscore akan dinormalisasi kepada dash (-) dan huruf disimpan lowercase.
- Menukar slug menyebabkan custom link lama tidak lagi berfungsi.
- Disable Link akan mematikan akses claim orang tersebut.
- Existing legacy token links daripada versi lama akan berhenti berfungsi sebaik sahaja Custom Claim Link ditetapkan.
- Sesiapa yang memiliki custom link boleh membuka portal claim penerima tersebut. Gunakan slug yang tidak terlalu mudah diteka jika maklumat claim dianggap sensitif.


G. CLAIM PORTAL FRIENDLY URL STYLE FIX (v1.1.1)
------------------------------------------------------------
Friendly URL seperti /claim/nama-penerima menggunakan absolute base URL untuk CSS, JavaScript dan logo. Ini memastikan portal claim kekal berdesign walaupun dibuka melalui URL /claim/<slug>.


============================================================
F. CLAIM UPLOAD STORAGE (v1.2)
============================================================
Super Admin boleh buka Claim Forms -> Claim Upload Storage dan tetapkan:
- Max Size Per File (MB).
- Max Files Per Claim.
- Max Total Upload Per Claim (MB).
- Total Claim Upload Storage Limit (MB); 0 = unlimited.
- Allowed File Types.

Cadangan hosting biasa:
- Max per file: 3-5 MB.
- Max files per claim: 2-3.
- Max total per claim: 5-10 MB.
- Total quota: ikut ruang hosting anda; contoh 500 MB.

Untuk padam attachment:
- Project Claims -> buka satu claim.
- Super Admin akan nampak Delete File pada setiap attachment.
- Jika lebih daripada satu attachment, ada Delete All Uploaded Files.
- Fail fizikal dipadam daripada uploads/claims tetapi rekod claim/project kekal. Tindakan direkod dalam Audit Log.


============================================================
H. USER REGISTRATION & FORGOT PASSWORD (v1.3)
============================================================
REGISTER USER BARU
1. Pada login page, user klik Register New Account.
2. User isi Name, Username, optional Email/Phone dan password sendiri.
3. Akaun masuk status PENDING dan belum boleh login.
4. ADMIN/SUPERADMIN nampak notification di Dashboard / Account Requests.
5. Admin approve sebagai OPERATOR atau VIEWER. SUPERADMIN juga boleh approve sebagai ADMIN.
6. Selepas approve, user login menggunakan password yang dia cipta semasa register.

FORGOT PASSWORD
1. User klik Forgot Password pada login page.
2. User masukkan Username atau Email dan submit request.
3. ADMIN/SUPERADMIN nampak request di Account Requests.
4. Admin klik Approve & Generate Password.
5. Sistem generate temporary password dan paparkan SEKALI sahaja kepada Admin.
6. Admin sendiri beri temporary password kepada user melalui WhatsApp/call/cara dalaman.
7. Temporary password default expired selepas 24 jam. Tempoh boleh diubah oleh SUPERADMIN di Users.
8. Selepas user login dengan temporary password, sistem wajibkan user tukar kepada password baru sebelum boleh masuk dashboard.

KESELAMATAN ROLE
- ADMIN tidak boleh reset password akaun ADMIN atau SUPERADMIN. Tindakan itu memerlukan SUPERADMIN.
- User self-register tidak boleh pilih role sendiri.
- SUPERADMIN role tidak boleh diperoleh melalui self-registration approval; ia mesti diurus oleh SUPERADMIN sedia ada.
- Semua approve/reject/reset/change password direkod dalam Audit Log.


============================================================
I. STAFF BOLEH GUNA CLAIM FORM (v1.4)
============================================================
Mulai v1.4, Staff dalam People boleh menggunakan claim form yang sama seperti External.

Syarat:
- People record mesti Active.
- "Can receive Commission" mesti ditanda.
- SUPERADMIN set Custom Claim Link pada People > Edit.

Flow:
1. People > Edit Staff.
2. Pastikan Can receive Commission = ON.
3. Save Person.
4. SUPERADMIN set Project Claim Link, contoh /claim/ali-staff.
5. Staff buka link tersebut dan pilih mana-mana Claim Form yang aktif.
6. Submission masuk ke Project Claims dan ikut approver yang ditetapkan pada form.
7. Bila approved, project + unpaid commission dicipta seperti claim External.
8. Claimant hanya nampak claim dan komisen dirinya sendiri selepas approval.

Nota: Staff login account dalam menu Users masih berasingan daripada People. Staff tidak perlu login dashboard untuk menggunakan personal claim link.


J. AKSES CLAIM FORM IKUT PEOPLE (v1.5)
--------------------------------------
Super Admin boleh buka People > Edit dan kawal form yang boleh digunakan oleh setiap Staff/External yang menerima komisen.

Pilihan:
- Allow All Claim Forms: semua form aktif boleh digunakan, termasuk form baru yang dibuat kemudian.
- Selected Claim Forms Only: hanya form yang ditanda boleh digunakan.

Jika hanya satu form dibenarkan, personal claim link akan terus membuka form tersebut. Jika tiada form dibenarkan, claimant masih boleh melihat sejarah claim tetapi tidak boleh membuat submission baru. Mengubah akses tidak memadam claim lama atau commission/payment history.


============================================================
K. INVITE-ONLY PEOPLE REGISTRATION (v1.6)
============================================================
People Registration adalah berasingan daripada User Registration. Ia digunakan untuk masukkan nama ke master People tanpa memberikan login dashboard.

Flow:
1. Login sebagai SUPERADMIN.
2. Buka People > Registration Invites & Requests.
3. Generate private link. Default disyorkan: expiry 7 hari dan maximum submissions 1.
4. Copy link dan beri terus kepada orang yang hendak didaftarkan. Link ini tidak dipaparkan pada login page atau mana-mana page public.
5. Applicant isi Name, Phone, optional Email/Bank/Notes. Applicant tidak boleh pilih Staff/External.
6. Request masuk Pending.
7. SUPERADMIN Review dan pilih Staff atau External, Can be Agent, Can receive Commission, Active/Inactive serta Claim Form access.
8. Approve akan automatik create People record. Reject tidak create People record.
9. Rejected/test request boleh dipadam oleh SUPERADMIN. Approved request disimpan sebagai history.
10. Private invite boleh direvoke bila-bila masa.

Keselamatan:
- Anggap link /join/<token> sebagai private bearer link. Sesiapa yang mendapat link boleh submit selama link masih aktif.
- Gunakan maximum submissions = 1 untuk jemputan seorang demi seorang.
- Revoke link selepas tidak diperlukan.

============================================================
L. PROJECT CUSTOMER PAYMENT GATE (v1.7)
============================================================
Mulai v1.7, komisen tidak boleh terus dimasukkan ke Payment Batch hanya kerana project sudah wujud. Admin/Super Admin mesti sahkan dahulu bahawa bayaran projek/customer telah selesai.

Status Customer Payment:
- AWAITING PAYMENT = belum ada bayaran direkod.
- PARTIAL = ada bayaran tetapi belum capai jumlah invoice.
- FULLY PAID = jumlah diterima sama/lebih daripada invoice atau Admin tekan Mark Fully Paid.

Flow:
1. Project / Claim approved -> project dicipta dan commission dikira.
2. Commission Process masih NOT READY selagi Customer Payment belum Fully Paid.
3. Admin/Super Admin buka Project -> Customer / Project Payment.
4. Boleh rekod Amount Received to Date, Payment Date, Reference dan Notes.
5. Tekan Mark Fully Paid apabila project telah settle.
6. Commission Process bertukar READY.
7. Project mula muncul di Generate Payment Batch.
8. Bila masuk Draft batch -> IN BATCH. Bila batch ditanda Paid -> PAID.

Bulk:
- Projects / Sales -> tick project yang belum ready -> Mark Selected Fully Paid.
- Bulk confirmation menggunakan tarikh semasa dan terus menjadikan project READY.

Protection:
- Hanya ADMIN dan SUPERADMIN boleh rekod/confirm customer payment.
- Hanya SUPERADMIN boleh Reset Customer Payment ke Awaiting.
- Customer payment tidak boleh diubah/reset jika project sudah berada dalam Draft/Paid commission batch.
- Server-side validation juga menghalang project yang belum Fully Paid daripada dimasukkan ke batch walaupun request diubah secara manual.
- Semua confirmation/reset direkod dalam Audit Log.

Migration existing:
- Project lama yang sudah berada dalam Draft/Paid Payment Batch akan automatik dianggap Fully Paid supaya payment history tidak rosak.
- Project lama yang belum pernah masuk Draft/Paid batch akan bermula sebagai Awaiting Payment dan perlu disahkan oleh Admin sebelum boleh diproses.



v2.5 CUSTOMER INTAKE RETENTION
------------------------------
- Customer Intake submitted details are retained after Accept or Reject.
- Operator/Admin/Super Admin can use Print / Save PDF & Clear Details after processing.
- The printable snapshot is loaded first, then temporary details are purged from the database.
- Only the mapped Project Name remains in the created Project after details are cleared.
- Super Admin can Purge Accepted Intake for test/mistaken records if the project is not in a Draft/Paid payment batch.
- Purging an accepted intake permanently deletes its created project and commission lines and releases one private-link use.

============================================================
V3.0 - ROLES & PERMISSIONS / MENU ACCESS
============================================================
After fresh installation, SUPERADMIN can open:
Administration > Roles & Permissions

Built-in roles:
- Super Admin (master access; cannot be restricted)
- Admin
- Operator
- Viewer

You can create additional custom roles such as Finance Executive,
Reviewer, Manager, Data Entry, or any other role required.

Permissions control BOTH:
1. what menu/submenu the user sees; and
2. what action the user is allowed to perform on the backend.

Per-user exceptions are available under:
Administration > Users > Permission Override

For normal management, prefer editing a Role rather than giving many
individual overrides.
