# Admission, Reporting and Automatic Fee Billing Upgrade

Date: 2026-07-25

## Simplified workflow

1. On **Add Student**, staff select the learner's class or course.
2. **Fee Total** is filled automatically from the current academic year's matching fee structure.
3. The displayed amount is a fee quotation only; the learner is not financially billed while still Admitted.
4. On **Admission Reporting**, staff click one primary button: **Report & Bill**.
5. Skulitech automatically selects the correct academic-year or module fee and posts the learner status and billing in one database transaction.
6. If no valid fee exists, reporting is blocked and an authorised user receives a **Set Fee** link with the learner's course, class, academic year and module pre-filled.
7. After the fee is saved, staff return to Reporting and click **Report & Bill** again.

## Fee matching priority

The system uses the most specific valid fee structure in this order:

1. Exact course and exact class.
2. All Courses and exact class.
3. Exact course and All Classes.
4. All Courses and All Classes.

Within the same matching level, an Academic Year fee is preferred. A matching Module fee is used when the class/module setup is more specific or when no annual fee matches.

## Fee Structure improvements

- Added **All Courses** coverage for common institution-wide fees.
- Fee structures can still be restricted to a particular course or class.
- The setup page accepts pre-filled links from Admission and Reporting.
- Users granted the `finance_fees` permission can create or correct fee structures, including custom roles.
- A class selection can align the course automatically.
- Amounts must be greater than zero.

## Admission form improvements

- Fee Total is read-only and automatically recalculates when Course, Class or Module changes.
- The matched billing basis, academic year, source course and source class are displayed below the amount.
- Missing fees are shown as **Not set**, with a direct setup link for authorised users.
- New learners remain **Admitted** and are not billed until they report.
- Existing posted billing totals are preserved when editing a learner.
- Bulk imports continue to ignore manual fee totals and lifecycle status.

## Reporting improvements

- Removed the repeated academic-year and billing-basis selections from every student row.
- The current open academic year is used automatically.
- The page shows the fee that will be billed before the action is taken.
- Reporting and billing are committed together; a billing error rolls back the status change.
- Existing annual or module tuition billing is detected before posting.
- Repeating the reporting action does not create duplicate tuition billing.
- Defer, No-show and Reset actions remain under a compact **Other status actions** section.

## Files changed

- `includes/helpers.php`
- `modules/admissions/student_form.php`
- `modules/admissions/reporting.php`
- `modules/finance/fee_structure.php`
- `docs/ADMISSION_REPORTING_AUTOMATIC_BILLING_UPDATE_2026-07-25.md`

## Database update

No schema migration is required. The upgrade uses the existing `fee_structures`, `finance_billings`, `students`, `student_status_history` and accounting tables. The `*` value is used internally to represent **All Courses** in the existing fee-structure course column.

## XAMPP verification

1. Back up the current `college_erp` folder and database.
2. Replace the existing project folder with the upgraded folder.
3. Start Apache and MySQL in XAMPP.
4. Open **Finance > Fee Structure** and create either:
   - an All Courses fee;
   - a course fee; or
   - a class-specific fee.
5. Open **Admissions > Add Student**, select a class and confirm Fee Total fills automatically.
6. Save the student and confirm the learner remains Admitted with no posted finance billing.
7. Open **Admissions > Admission Reporting** and click **Report & Bill**.
8. Confirm the learner becomes Reported and one tuition billing is created.
9. Repeat the action and confirm no duplicate billing is posted.
10. Test a class/course with no fee and confirm reporting is blocked with a pre-filled **Set Fee** link.
