BGI HRMS Payroll & Attendance - Phase 1
========================================

This package creates Phase 1 of the HRMS module:
1. Staff Registration
2. Staff Biometric ID Mapping
3. Secureye CSV Attendance Import
4. Raw Punch Logs
5. Attendance Rule Engine
6. Daily / Monthly Attendance Register
7. Attendance Correction
8. Basic HRMS Masters
9. Designation Wise Timing Rules
10. Audit Logs

INSTALL STEPS
-------------
1. Backup your database and project files first.
2. Import phase1_schema.sql in your ERP database.
3. Copy these folders into your ERP/public_html root:
   - admin/hrms/
   - api/biometric/
   - cron/
   - uploads/biometric_import/
4. Open: /admin/hrms/index.php
5. Go to HRMS > Masters and confirm Department / Designation.
6. Go to HRMS > Staff and add staff with Biometric User ID.
7. Export Secureye attendance as CSV and upload from HRMS > Import.

CSV FORMAT
----------
Supported format 1:
User ID,Punch Time,Device Code,Verify Type
1001,2026-07-01 10:12:00,SECUREYE01,Finger

Supported format 2:
User ID,Date,Time,Device Code
1001,2026-07-01,10:12:00,SECUREYE01

ATTENDANCE RULES INCLUDED
-------------------------
- Academic timing:
  1 Jul to 14 Nov  = 10:00 AM to 04:30 PM
  15 Nov to 31 Jan = 10:00 AM to 03:50 PM
  1 Feb to 30 Jun  = 10:00 AM to 04:30 PM
- Designation timing override supported.
- Guard sample timing: 08:00 AM to 08:00 PM.
- Grace period: 30 minutes.
- IN after 11:30 AM = Half Day.
- OUT before 02:00 PM = Half Day.
- Less than 3 hours = Absent.
- Only one punch = Absent.

OPTIONAL API PUSH
-----------------
Endpoint:
/api/biometric/secureye_push.php

JSON example:
{
  "device_id": "SECUREYE01",
  "user_id": "1001",
  "punch_time": "2026-07-01 10:12:00",
  "verify_type": "finger"
}

CRON FOLDER IMPORT
------------------
Place CSV files in:
/uploads/biometric_import/

Cron example:
*/5 * * * * /usr/bin/php /home/USER/public_html/cron/import_biometric_folder.php >/dev/null 2>&1

IMPORTANT NOTES
---------------
- Raw biometric logs are never deleted.
- Duplicate punch logs are ignored using a unique hash.
- Attendance can be recalculated after staff mapping correction.
- Manual attendance correction is logged in hr_activity_logs and hr_attendance_corrections.
- XLSX import is not included in Phase 1 because it depends on the PHP library available in your existing ERP. CSV import is stable and safe for legacy PHP.

STAFF PORTAL
------------
Staff login URL:
/staff/hrms/login.php

Admin must set Login Username and Login Password from:
/admin/hrms/staff_form.php

If Google Authenticator is enabled, the system generates a secret key and staff can enter this key in the Google Authenticator app.

PHASE 1 FILES
-------------
admin/hrms/index.php                  HRMS dashboard
admin/hrms/masters.php                Department and Designation master
admin/hrms/staff_list.php             Staff list
admin/hrms/staff_form.php             Staff registration/edit/login setup
admin/hrms/timing_rules.php           Academic and designation timing rules
admin/hrms/biometric_devices.php      Biometric device master
admin/hrms/import_attendance.php      CSV import
admin/hrms/raw_punch_logs.php         Raw punch logs
admin/hrms/attendance_register.php    Attendance register
admin/hrms/attendance_correction.php  Manual correction
api/biometric/secureye_push.php       Optional API push endpoint
cron/import_biometric_folder.php      Cron folder import
staff/hrms/login.php                  Staff login
staff/hrms/profile.php                Staff profile and attendance view