alrahma_sunday_school_api/docs/api_fee_calculation_controller_plan.md

FeeCalculationController plan

Scope

• Controller: app/Http/Controllers/Api/Finance/FeeCalculationController.php
• Purpose: finance calculation endpoints (refunds, tuition totals/breakdowns, family balances).
• Primary dependencies:
  • FeeRefundCalculatorService (refund calculations)
  • FeeStudentFeeService (tuition total)
  • TuitionCalculationService (tuition breakdown)
  • BalanceCalculationService (family account/balance aggregation)
• Resources:
  • FeeRefundResource
  • FeeTuitionTotalResource
  • FeeTuitionBreakdownResource
  • FeeFamilyBalanceResource

Routes

All routes are under:

• Base prefix: /api/v1/finance
• (Route file shows this under a finance group; actual auth middleware depends on the surrounding v1 group setup.)

Endpoints:

• POST /api/v1/finance/fees/refund → refund
• POST /api/v1/finance/fees/tuition-total → tuitionTotal
• POST /api/v1/finance/fees/tuition-breakdown → tuitionBreakdown
• POST /api/v1/finance/fees/family-balance → familyBalance

Requests/validation

• refund: FeeRefundRequest
  • expects parent_id and students array
• tuitionTotal: FeeTuitionTotalRequest
  • expects students array
• tuitionBreakdown: FeeTuitionBreakdownRequest
  • expects students array
• familyBalance: FeeFamilyBalanceRequest
  • expects parent_id, students array, optional school_year

Response shapes

Legacy { ok: ... } shape:

• refund:
  • { ok:true, refund: FeeRefundResource }
• tuitionTotal:
  • { ok:true, tuition: FeeTuitionTotalResource({ total_tuition }) }
• tuitionBreakdown:
  • { ok:true, tuition: FeeTuitionBreakdownResource }
• familyBalance:
  • { ok:true, account: FeeFamilyBalanceResource }

Error handling expectations

• Each endpoint wraps calculation in try/catch:
  • On exception: logs error and returns 500 with { ok:false, message:"Unable to ..." }
• Validation errors are handled by the FormRequest layer (422).

Test plan (feature/unit mix)

• Validation:
  • Missing required fields → 422.
• Refund:
  • Valid input returns ok:true and resource fields.
  • Service exception returns 500 and message.
• Tuition total/breakdown:
  • Calculates expected totals for a known dataset.
  • Service exception returns 500.
• Family balance:
  • Produces stable account totals for known payments/charges.
  • Service exception returns 500.