# Veltrix HRM — setup and usage

## Open the module
- Production / XAMPP: `http://localhost:8000/admin/hrm`
- Vite development: `http://localhost:5173/admin/hrm`
- The enquiry inbox at `/admin` now includes an **Open HRM workspace** link.
- Use the existing administrator email/password. There is no new default password and no public employee registration.

## Upgrade an existing installation
1. Back up your database and current files.
2. Copy the updated application source and built assets. Preserve your own `backend/.env`, APP_KEY, vendor folder, logs and existing database.
3. In `backend/.env`, add `APP_TIMEZONE=Asia/Karachi` if it is missing.
4. From `backend`, run:

```bat
composer install
php artisan optimize:clear
php artisan migrate
```

This adds `hrm_departments`, `hrm_employees`, `hrm_attendances`, and `hrm_leave_requests`. Existing users and enquiries remain in their existing tables. Do not run `migrate:fresh` or import a replacement database.

5. If you do not already have an admin, run:

```bat
php artisan veltrix:admin your-email@example.com
```

6. The download includes the production React build already copied into Laravel. To rebuild after source changes:

```bat
cd frontend
npm ci
npm run build
cd ..
node scripts/copy-build.mjs
```

7. Start the backend as usual:

```bat
cd backend
php artisan serve
```

For a new installation, follow the main README first to create the MySQL database, `.env` and APP_KEY. For Plesk, point the document root to `backend/public`; run migrations with `--force` only in your production deployment process.

## Workflow
1. Add your departments.
2. Add employees with a unique code/email, department, designation, joining date and employment type.
3. Record attendance by date. Saving the same employee and date updates the existing record.
4. Add a leave request on behalf of an employee. Approve, reject or cancel a pending request with optional decision notes.
5. Export monthly attendance from Reports. Files open in Excel and include the current department of each employee.

## Included behavior
- Search/paginate employees and filter by department/status.
- Edit employee profiles; set former staff to inactive to preserve their records. Employee deletion is intentionally not provided.
- Create/edit departments; deletion is blocked while any employees belong to the department.
- Present, late, absent, half-day and leave attendance statuses; optional same-day times and notes.
- Future attendance, invalid checkout times and working times for absent/leave status are rejected. Employees must be active and the date must be on/after joining.
- Annual, sick, casual and unpaid leave categories; dates are inclusive calendar days. Overlapping pending/approved requests are blocked. A reviewed request cannot be changed through this initial module.
- Dashboard counts active employees who have joined as of today. Unmarked attendance is not treated as absence.
- All HRM APIs use existing Sanctum admin authentication, require the admin token ability, and return no-store headers. HRM is excluded from the sitemap and marked noindex; authentication is the access control.
- Attendance CSV export is restricted to administrators and neutralizes spreadsheet formula prefixes in text fields.
- Light/dark mode, responsive tables/sidebar and reduced-motion support remain available.

## Scope
This is an administrator-managed HRM module. Employee self-service logins, payroll, deductions, leave entitlement/accrual, holidays/weekend policies, biometric integrations and overnight shifts are not included. Approved leaves do not automatically create attendance rows. Attendance can be marked manually as leave for the relevant dates. There is no historical department tracking; reports use the employee's current department.

## Hosted preview
The hosted design preview opens a clearly labeled HRM demo with fictional sample employees. You can add/edit demo records, mark attendance, review leave and download a sample CSV. Demo changes are held in memory and reset on refresh; no real employee data is loaded or saved. The downloadable Laravel/MySQL project uses protected API endpoints instead.

For the real site, leave `VITE_PREVIEW_MODE=false` when building. Do not use the demo build as your production HR backend.

## Validation
Run:
```bat
php artisan test --filter=HrmTest
```
The test suite uses SQLite in memory and checks authorization, unique employee details, department deletion protection, attendance upsert/validation, overlapping leave, review rules, dashboard counts and CSV export. Also perform a real MySQL smoke test on your hosting before entering staff data.

Frontend checks after building:
```bat
node frontend/scripts/check-hrm.mjs
node frontend/scripts/check-theme.mjs
```
See `VALIDATION.md` for checks actually performed in the creation environment. PHP/MySQL test execution is separate from PHP syntax parsing.