SKULITECH ERP — WINDOWS XAMPP INSTALLATION
==========================================

Prepared for:
  C:\xampp\htdocs\college_erp
  http://localhost/college_erp/
  Database: college_erp
  MySQL user: root
  MySQL password: blank (standard local XAMPP default)

SYSTEM REQUIREMENTS
-------------------
1. Windows 10 or Windows 11
2. XAMPP with PHP 8.0 or later
3. Apache and MySQL/MariaDB running
4. Required PHP extensions:
   pdo_mysql, mysqli, mbstring, zip, fileinfo and gd

FAST INSTALLATION
-----------------
1. Copy the complete college_erp folder to:
     C:\xampp\htdocs\college_erp

2. Start Apache and MySQL from the XAMPP Control Panel.

3. Double-click:
     C:\xampp\htdocs\college_erp\bin\xampp_install.bat

   The installer will:
   - confirm PHP and pdo_mysql availability;
   - connect to XAMPP MySQL;
   - create/import a clean college_erp database when empty;
   - run all pending migrations for both new and existing databases;
   - create or reset the first System Administrator automatically;
   - check the XAMPP environment and database structure;
   - run data-integrity checks.

4. Open:
     http://localhost/college_erp/login.php

   First login:
     Username: admin
     Email: admin@skulitech.local
     Temporary password: shown once by the installer

   Store the generated password securely and change it after the first login.

MANUAL DATABASE INSTALLATION
----------------------------
Use this only when the batch installer cannot be used.

1. Open http://localhost/phpmyadmin/
2. Select Import.
3. Import:
     C:\xampp\htdocs\college_erp\database\schema\college_erp_current.sql

Create and select the college_erp database in phpMyAdmin before importing the SQL file.

4. Open Command Prompt and run:
     cd C:\xampp\htdocs\college_erp
     C:\xampp\php\php.exe bin\migrate.php
     C:\xampp\php\php.exe bin\provision_default_admin.php
     C:\xampp\php\php.exe bin\check_integrity.php

LOGIN OR MIGRATION REPAIR
-------------------------
If the database already exists but login is not working, start MySQL in XAMPP and
double-click:
  C:\xampp\htdocs\college_erp\bin\xampp_migrate_and_fix_login.bat

This applies every pending migration, creates or resets the active System Admin,
and verifies the login account. Use username admin and the random temporary
password printed by the repair script. Change it after the first successful login.

DATABASE SETTINGS
-----------------
Local settings are stored in:
  C:\xampp\htdocs\college_erp\config\local.php

Standard settings are:
  Host:     127.0.0.1
  Port:     3306
  Database: college_erp
  User:     root
  Password: blank

Where the MySQL root account has a password, enter it in config\local.php before running the installer.

ENABLE PHP EXTENSIONS
---------------------
Open:
  C:\xampp\php\php.ini

Make sure these entries do not begin with a semicolon:
  extension=pdo_mysql
  extension=mysqli
  extension=mbstring
  extension=zip
  extension=gd
  extension=fileinfo

Restart Apache after changing php.ini.

VALIDATION
----------
Double-click:
  bin\xampp_validate.bat

It checks every PHP file and then tests the XAMPP environment, extensions,
database connection, table count, sponsor-funds tables and foreign keys.

Useful commands:
  C:\xampp\php\php.exe bin\xampp_check.php
  C:\xampp\php\php.exe bin\check_integrity.php
  C:\xampp\php\php.exe bin\migrate.php

MAIN LOCAL URLS
---------------
System:               http://localhost/college_erp/
Login:                http://localhost/college_erp/login.php
Application form:     http://localhost/college_erp/apply.php
Application tracking: http://localhost/college_erp/track_application.php
API health endpoint:  http://localhost/college_erp/api/health.php

SPONSOR-FUNDS TEST
------------------
After login, use the visible funding-agency workflow:

  Finance > Bulk Sponsor Receipting

The student schedule is optional when the parent receipt is entered. You may:
  - leave the schedule blank and save only the funding-agency receipt;
  - upload a CSV/Excel schedule immediately; or
  - approve the receipt first and allocate later in bulk or one student at a time.

Other direct menus are:
  Finance > Sponsor Receipts
  Finance > Bulk Student Allocations
  Finance > Sponsor Control Reports

Example:
  Parent HELB receipt: KSh 100,000
  Student A allocation: KSh 25,000
  Student B allocation: KSh 30,000
  Student C allocation: KSh 45,000

For a County or NG-CDF cheque, first select Pending Clearance. Print the cheque
acknowledgement, then mark the receipt Cleared after confirming it in the bank.
Approve the one official sponsor receipt, validate the batch and post it.

Expected result:
  Bank/cash receipt total: KSh 100,000
  Student sponsor credits: KSh 100,000
  Unallocated sponsor balance: KSh 0
  No second cash receipt is created for the student allocations.

TROUBLESHOOTING
---------------
"could not find driver"
  Enable extension=pdo_mysql in C:\xampp\php\php.ini and restart Apache.

"The system could not connect to the XAMPP MySQL database"
  Start MySQL in XAMPP and check config\local.php.

Apache starts but localhost does not open
  Another program may be using port 80. Resolve the Apache port conflict in
  XAMPP, then use the port shown in the XAMPP Control Panel.

CSS or images do not appear
  Confirm that the folder is exactly C:\xampp\htdocs\college_erp and open the
  system through http://localhost/college_erp/, not by double-clicking PHP files.

403 on protected folders
  This is expected for config, database, docs, bin, includes and storage. The
  root .htaccess intentionally blocks those folders from browser access.

IMPORTANT
---------
Use this package for localhost development and acceptance testing. Before moving
to public hosting, remove or replace config\local.php, configure environment
variables, set APP_ENV=production, use HTTPS and create a fresh encrypted backup.

MANUAL SPONSOR ALLOCATION (14 JULY 2026)
----------------------------------------
Finance users can now open Finance > Manual Student Allocation to distribute a posted HELB, County, NG-CDF/CDF, scholarship or donor receipt to students one by one. Student allocations do not create additional bank receipts.


NO-DOUBLE-RECEIPTING CONTROL (14 JULY 2026)
-------------------------------------------
Funding-agency money is receipted once to HELB, County Government, NG-CDF/CDF,
a scholarship body or another sponsor. Student credits are allocations linked
to that parent receipt and are not official cash receipts.

The system blocks:
  - reuse of a bank, cheque or M-Pesa reference in another receipt;
  - sponsor payer descriptions on the direct student fee-payment screen;
  - an exact student-and-amount receipt that matches a recent posted sponsor
    allocation, unless a System Admin/Admin verifies it as separate money and
    records an audit reason;
  - printing an official fee receipt for a non-cash sponsor allocation.

Use Finance > Sponsor Control Reports to review possible historical parent and
child receipt matches. Corrections should be reversed, not deleted.
