# Skulitech ERP Fee Structure Editing and Payment Correction Upgrade

**Release date:** 25 July 2026  
**Target environment:** XAMPP / PHP / MySQL

## Purpose

This upgrade gives authorised Finance users a controlled way to:

1. Edit an existing fee structure for a course, class, academic year, or module.
2. Correct a student fee payment that was entered against the wrong student, amount, period, payer type, payment method, date, or reference.
3. Preserve the accounting and audit trail instead of silently overwriting posted financial records.

## Fee Structure Editing

The Finance > Fee Structure page now supports both **Add** and **Edit** modes.

Authorised roles:

- System Admin
- Admin
- Finance

An authorised user can edit:

- Course
- Class
- Billing basis: Academic Year or Module
- Academic year
- Module
- Fee amount
- Notes

A change reason is mandatory. The system records the old values, new values, reason, user, and date in the audit log.

### Important accounting behaviour

Editing a fee structure affects **future billing only**. It does not rewrite bills or receipts that have already been posted. This protects historical student statements and financial reports. Where a student has already been billed incorrectly, the existing billing adjustment or reversal controls should be used rather than editing the master fee structure.

### Duplicate protection

The system checks that another fee structure does not already cover the same course/class and academic-year/module scope before saving the change.

## Student Payment Correction

Active direct student payments now have a **Correct** action. This action is limited to System Admin, Admin, and Finance users.

The correction form permits changes to:

- Student
- Amount paid
- Academic year or module
- Payment date
- Payer type
- Payment method
- External payment reference

A detailed correction reason and explicit confirmation are required.

### Correction workflow

The system does not delete or overwrite the original posted receipt. It performs the following controlled sequence in one database transaction:

1. Locks the original payment record.
2. Validates that it is still an active direct student receipt.
3. Reverses the original accounting journal.
4. Generates a new replacement receipt number.
5. Posts the corrected replacement payment and accounting journal.
6. Marks the original payment as **Corrected** and non-cash.
7. Links the original and replacement payment records.
8. Recalculates affected student totals and balances.
9. Updates the receipt-control registry.
10. Records the correction in the payment-correction history and audit log.

This design prevents duplicate income, keeps the original evidence, and makes the reason for every change traceable.

## Receipt Presentation

- The original receipt remains printable for audit purposes but is clearly marked as **VOID / REVERSED DUE TO CORRECTION**.
- The replacement receipt is marked as a corrected replacement receipt.
- Both receipts show their relationship and the correction reason where applicable.

## Reports and Balances

The following calculations were updated so corrected originals are not counted as active payments:

- Finance dashboard payment totals
- Student fee balance calculations
- Receipt registry rebuild and journal health checks

## Database Changes

The application includes both:

- Runtime schema checks in `includes/helpers.php`; and
- A standalone migration at:
  `database/migrations/20260725_012_fee_structure_payment_corrections.sql`

### New fee structure fields

- `updated_by`
- `change_reason`
- `updated_at`

### New payment fields

- `payment_status`
- `corrected_from_payment_id`
- `corrected_to_payment_id`
- `correction_reason`
- `corrected_by`
- `corrected_at`

### New correction history table

- `fee_payment_corrections`

## Deployment

1. Back up the existing application folder and MySQL database.
2. Replace or merge the upgraded `college_erp` folder into the XAMPP `htdocs` directory.
3. Open the application once as an administrator so the runtime schema checks can add missing fields and tables.
4. Alternatively, import `database/migrations/20260725_012_fee_structure_payment_corrections.sql` in phpMyAdmin.
5. Test fee-structure editing using a non-production record.
6. Test payment correction using a test student and confirm:
   - original receipt is marked corrected;
   - replacement receipt is generated;
   - student balance is correct;
   - journal reversal and replacement journal exist;
   - dashboard totals count only the replacement payment.

## Controls and Limitations

- Only active direct student receipts can be corrected through this page.
- Sponsor or bulk-funding allocations retain their specialised reversal/allocation workflow.
- Posted financial history is never silently rewritten.
- A correction reason is compulsory.
- The operation is transactional: if reversal or replacement posting fails, the correction is rolled back.
