update api and add more features

docs/api_fee_calculation_controller_plan.md

@@ -0,0 +1,66 @@
+# `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.
+