# ILO Unit Registration, Roster, Placement and Reporting Upgrade

## Implemented workflow

1. An administrator marks a catalogue unit as **Industrial Attachment** under **Academics → Units**.
2. When a student is registered for that unit, the registration is automatically mapped into the ILO attachment roster.
3. The ILO Office creates an attachment period and can map previously registered students to the matching academic year, session and module.
4. The ILO Office can upload a CSV or XLSX student list. The upload matches students by admission number, validates the attachment unit and maps every valid row to the selected period.
5. A controlled option allows the ILO Office to register the selected attachment unit for a valid student when it is absent. When this option is disabled, the row is rejected instead of silently creating an academic registration.
6. The ILO Officer posts each student to an organization, selects the workplace area, dates and institution supervisor, and can confirm when the student has reported.
7. The roster shows **Not Placed, Placed, Attached, Deferred, Completed and Cleared** statuses. The primary operational filters requested are Not Placed, Placed, Attached and Deferred.
8. Completion and clearance statuses are synchronized from the existing ILO placement, logbook, assessment and clearance workflow.

## Bulk upload controls

- CSV and XLSX support.
- Maximum upload size of 10 MB.
- Required admission-number column.
- Optional Unit Code, Status, Organization, Location, Attachment Area, Start Date, End Date and Deferral Reason columns.
- Student and attachment-unit validation.
- Duplicate registration and roster prevention.
- Import batch number, uploader, time, totals and per-row result history.
- Downloadable CSV upload template.
- Formula-injection protection on CSV exports.

## Academic integration

- `units.is_industrial_attachment` identifies attachment units.
- `student_unit_registrations` remains the academic source of truth.
- `ilo_attachment_roster.student_unit_registration_id` preserves the link to the exact registered unit.
- Existing attachment registrations are backfilled whenever the ILO roster opens.
- Registrations created before an attachment period is configured are mapped automatically after a matching period is created.
- Removing or changing academic registrations remains governed by the existing registration controls.

## Placement and status controls

- A placement cannot be created for a student who already has another open placement.
- A lecturer supervisor is required before ILO posting.
- Placed means an organization has been assigned.
- Attached means the student has reported and the linked placement is active.
- Deferred requires a reason. Existing placements are cancelled before the roster is deferred.
- Completed and Cleared are derived from the linked ILO workflow and cannot be assigned through bulk upload.
- All status changes and roster mappings are written to the ILO audit log.

## Reports

Filtered reports are available as:

- PDF
- Excel XLSX, with an Excel-compatible fallback
- CSV

Filters include period, placement status, class, course, unit and student/organization search. Reports include the attachment unit, academic period, organization, workplace area, institution supervisor, reporting date, completion date, deferral reason and source.

## Student profile

The student profile now displays the latest industrial-attachment unit, period, organization and placement status. Authorised staff can open the student directly in the ILO roster.

## New database objects

- `ilo_attachment_periods`
- `ilo_attachment_roster`
- `ilo_roster_import_batches`
- `ilo_roster_import_rows`
- New attachment-unit fields on `units`
- Roster, period and unit-registration links on `ilo_placements`

## Installation and validation

Back up the application and database, extract the package into a staging environment, and run:

```bat
bin\run_ilo_roster_check_xampp.bat
```

The batch file searches for PHP in `C:\xampp`, `D:\xampp` and `E:\xampp`. A custom path can be supplied through `XAMPP_PHP`.

Manual commands are:

```bat
C:\xampp\php\php.exe bin\migrate.php
C:\xampp\php\php.exe bin\check_ilo_roster.php
C:\xampp\php\php.exe bin\check_class_rep_ilo.php
C:\xampp\php\php.exe bin\check_ilo_exports_letters.php
C:\xampp\php\php.exe bin\check_integrity.php
```

## Staging acceptance tests

- Mark a unit as Industrial Attachment and register one student for it.
- Confirm that the student appears in the ILO roster without manual duplication.
- Create a matching attachment period and confirm automatic period mapping.
- Upload the supplied template with valid, invalid and duplicate admission numbers.
- Confirm row-level error reporting.
- Post a student to an organization and confirm the status changes to Placed.
- Confirm reporting and verify the status changes to Attached.
- Defer another student and verify that a reason is mandatory.
- Complete and clear an attachment in the existing ILO centre and confirm roster synchronization.
- Export the same filtered list to PDF, Excel and CSV and compare totals.
