# `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.