alrahma_sunday_school_api/docs/school_tuition_payment_management_plan.md

School Tuition Payment Management Plan

1. Purpose

The school needs a clear tuition management system that calculates tuition, tracks payments, manages refunds, records remaining balances, and handles extra charges and event charges.

The existing fee calculation logic should be preserved where valid, but it should be expanded and corrected so the system can handle complete student billing, not only basic tuition and refunds.

2. Current Tuition Logic

The current tuition service calculates tuition using three main fee categories:

• First regular student fee
• Additional regular student fee
• Youth student fee

Students are sorted by grade before tuition is calculated.

Grade Rules

• Kindergarten is treated as grade level 0.
• Grades 1 through 9 are treated as regular students.
• Grades above 9 are treated as youth students.
• Grade “Y” is treated as youth.
• Unknown or malformed grades are treated as invalid or fallback grade level.

Tuition Fee Rules

For students in grades K through 9:

• The first regular student is charged the first student fee.
• Each additional regular student is charged the second student fee.

For students above grade 9 or youth category:

• Each youth student is charged the youth fee.

Tuition Formula

Total Tuition = Regular Student Fees + Youth Student Fees

Example:

First regular student fee: $350
Second regular student fee: $200
Youth fee: $180

Family has:

• Student 1 in Grade 2
• Student 2 in Grade 5
• Student 3 in Youth

Total Tuition = $350 + $200 + $180 = $730

3. Required Tuition Calculation Improvements

The tuition calculation should return a detailed breakdown, not only a single total.

Each student billing record should include:

• Student ID
• Student name
• Grade
• Grade level
• Enrollment status
• Admission status
• Fee category
• Tuition fee assigned
• Discount applied
• Extra charges
• Event charges
• Payments applied
• Refund amount, if any
• Remaining balance

The system should generate both:

1. Family-level total balance
2. Student-level billing breakdown

This prevents confusion when a parent has multiple children enrolled.

4. Tuition Calculation Process

The system should calculate tuition using the following steps:

1. Retrieve school year configuration.
2. Retrieve fee configuration:
   • First student fee
   • Second student fee
   • Youth fee
   • Refund deadline
   • Weeks of study
   • Last school day
3. Load all students connected to the parent or family account.
4. Fetch each student’s grade or class section name.
5. Normalize grade names.
6. Sort students by grade level.
7. Assign tuition fee to each eligible student.
8. Apply discounts or scholarships.
9. Add required fees.
10. Add extra charges.
11. Add event charges.
12. Subtract payments and credits.
13. Calculate remaining balance.

5. Student Eligibility for Tuition

Tuition should only be calculated for students who meet the billing criteria.

Billable Students

A student should be billable if:

• Enrollment status is enrolled or payment pending
• Admission status is accepted

Withdrawn Students

A withdrawn student should not continue to receive new tuition charges unless the school policy requires partial tuition.

Withdrawn statuses may include:

• Withdrawn
• Refund pending
• Withdraw under review

Withdrawn students should be included in refund calculations when applicable.

6. Remaining Balance Calculation

The system should calculate the remaining balance at the family level and student level.

Formula

Remaining Balance = Total Charges - Total Payments - Credits - Refunds Applied to Account

Where:

Total Charges = Tuition + Required Fees + Extra Charges + Event Charges + Late Fees

Credits may include:

• Scholarships
• Discounts
• Financial aid
• Manual credits
• Canceled event credits
• Overpayment credits

Example:

Tuition: $730
Extra Charges: $100
Event Charges: $50
Total Charges: $880

Payments Made: $500
Credits: $80

Remaining Balance = $880 - $500 - $80 = $300

7. Refund Calculation

The existing refund calculation should be corrected and formalized.

Refund Eligibility

A student may be eligible for a refund if:

• The student has a withdrawn-related enrollment status
• A valid withdrawal date exists
• The withdrawal date is on or before the refund deadline
• The parent or guardian has made payments
• The refund does not exceed total amount paid

Refund Formula

Refund Amount = Student Tuition Fee ÷ Weeks of Study × Weeks Remaining

The system should calculate weeks remaining from the withdrawal date to the last school day.

Refund Cap

Total refund cannot exceed total amount paid by the parent or guardian for the school year.

Refund Example

Student tuition fee: $350
Weeks of study: 8
Weeks remaining: 4

Refund Amount = $350 ÷ 8 × 4 = $175

8. Refund Logic Correction Needed

The current refund service contains a logic issue.

The service calculates each student’s fee, but it does not store that fee on the student record before refund calculation.

The corrected logic should assign the calculated fee to each student:

$student['tuition_fee'] = $studentFee;

Then the refund loop should use:

$studentFee = $student['tuition_fee'];

Without this correction, refund calculations may be unreliable.

9. Extra Charges

Extra charges should be stored separately from tuition.

Examples of extra charges:

• Books
• Uniforms
• Transportation
• Meals
• Technology fee
• Replacement ID card
• Lost book fee
• Damaged equipment fee
• Late pickup fee
• After-school care
• Exam fee
• Late payment fee

Each extra charge should include:

• Student ID
• Parent ID
• School year
• Charge name
• Charge description
• Charge amount
• Charge date
• Due date
• Status
• Created by
• Approval status

Extra charges should be included in the remaining balance but should not automatically affect tuition calculation.

10. Event Charges

Event charges should be tracked separately from regular extra charges.

Examples of event charges:

• Graduation
• Field trip
• School camp
• Sports event
• Competition
• Cultural event
• Workshop
• School ceremony

Each event charge should include:

• Event ID
• Event name
• Student ID
• Parent ID
• Event date
• Participation status
• Charge amount
• Payment status
• Refund policy
• Cancellation status

If an event is canceled, the system should either issue a refund or apply the charge as account credit.

11. Payment Tracking

Each payment should be recorded against the parent or family account and optionally allocated to specific charges.

Each payment record should include:

• Payment ID
• Parent ID
• Student ID, if applicable
• School year
• Amount paid
• Payment method
• Payment date
• Receipt number
• Payment status
• Notes
• Created by

Payment status may include:

• Pending
• Paid
• Failed
• Refunded
• Partially refunded
• Canceled

12. Invoice Structure

The invoice should combine all billing items into one clear document.

Invoice sections should include:

1. Tuition charges
2. Extra charges
3. Event charges
4. Discounts and credits
5. Payments received
6. Refunds
7. Remaining balance

Each invoice should show:

• Invoice number
• Parent or guardian name
• Student names
• School year
• Issue date
• Due date
• Total charges
• Total paid
• Remaining balance
• Payment instructions

13. Recommended Service Structure

The billing logic should be split into separate services instead of placing everything inside one fee calculation service.

TuitionCalculationService

Responsible for:

• Sorting students by grade
• Assigning tuition fee
• Calculating family tuition total
• Returning student-level tuition breakdown

RefundCalculationService

Responsible for:

• Checking refund eligibility
• Calculating proportional refund
• Applying refund caps
• Returning refund details

BalanceCalculationService

Responsible for:

• Adding tuition, event charges, and extra charges
• Subtracting payments and credits
• Returning remaining balance

ChargeService

Responsible for:

• Creating extra charges
• Creating event charges
• Canceling charges
• Marking charges paid or unpaid

InvoiceService

Responsible for:

• Creating invoices
• Updating invoices
• Generating account statements
• Showing billing history

14. Required Reports

The system should generate the following reports:

• Total tuition billed
• Total tuition collected
• Remaining balances by parent
• Remaining balances by student
• Refunds pending
• Refunds issued
• Extra charges collected
• Event charges collected
• Overdue balances
• Payment plan status
• Family account summary

15. Controls and Validation

The system should prevent incorrect billing through validation rules.

Required validations:

• Do not calculate refund without withdrawal date.
• Do not refund after refund deadline.
• Do not refund more than amount paid.
• Do not bill students who are not accepted.
• Do not duplicate event charges.
• Do not apply payment to the wrong school year.
• Do not allow negative remaining balance unless recorded as credit.
• Do not allow manual balance edits without audit log.
• Do not delete payments; reverse them with adjustment records.

16. Recommended Database Tables

The system should include or update the following tables.

tuition_configurations

Stores school-year billing settings.

Fields:

• school_year
• first_student_fee
• second_student_fee
• youth_fee
• refund_deadline
• weeks_study
• last_school_day

student_tuition_records

Stores calculated tuition per student.

Fields:

• student_id
• parent_id
• school_year
• grade
• grade_level
• fee_category
• tuition_fee
• discount_amount
• final_tuition_amount

charges

Stores extra and event charges.

Fields:

• charge_id
• student_id
• parent_id
• school_year
• charge_type
• charge_name
• amount
• due_date
• status

payments

Stores parent payments.

Fields:

• payment_id
• parent_id
• school_year
• amount
• method
• payment_date
• status
• receipt_number

refunds

Stores refund records.

Fields:

• refund_id
• parent_id
• student_id
• school_year
• refund_amount
• reason
• withdrawal_date
• approval_status
• refund_status

account_ledger

Stores every financial transaction.

Fields:

• ledger_id
• parent_id
• student_id
• school_year
• transaction_type
• description
• debit_amount
• credit_amount
• balance_after_transaction
• created_by
• created_at

17. Implementation Priority

Phase 1: Fix Current Tuition and Refund Logic

• Store assigned tuition fee per student.
• Fix refund calculation bug.
• Return detailed student fee breakdown.
• Add logging for each calculation.
• Add tests for multiple-student families.

Phase 2: Add Balance Calculation

• Combine tuition, extra charges, event charges, and payments.
• Calculate remaining balance.
• Add family account summary.

Phase 3: Add Charges

• Create extra charge system.
• Create event charge system.
• Add charge statuses.
• Prevent duplicate charges.

Phase 4: Add Invoice and Statement System

• Generate invoices.
• Generate monthly statements.
• Show payment history.
• Show remaining balance.

Phase 5: Add Reports and Audit Logs

• Add finance reports.
• Add refund reports.
• Add audit trail.
• Add manual adjustment tracking.

18. Final Recommendation

The existing service should not be thrown away, but it should not remain responsible for the entire billing system.

The school should keep the grade-based tuition rules, correct the refund bug, and expand the system into a proper billing module with separate tuition, refund, charge, payment, invoice, and balance services.

The final system should always answer five questions clearly:

1. What was the student charged?
2. Why was the student charged?
3. What has the parent paid?
4. What has been refunded or credited?
5. What balance remains?