# Finance Plan Implementation Notes

This implementation keeps the existing financial endpoints and PayPal-related code intact, then adds the missing additive finance lifecycle pieces from the plan.

## Added

- Finance lifecycle migration: follow-up notes, balance carryforwards, installment plans/installments, payment-installment allocations, notification logs/preferences, receipt sequences, and carryforward payment allocations.
- Parent payment follow-up reporting with CSV export and write-only metadata actions for notes, contacted status, promise-to-pay, and resolution.
- Prior-year balance carryforward preview, draft creation, approval, posting to a new-year invoice, waiver, adjustment, report, and CSV export.
- Installment plan creation, activation, cancellation, overdue/due reporting, and payment allocation.
- Finance notification logging endpoints for receipts, statements, overdue reminders, installment reminders, and notification log search.
- Event charge lifecycle API endpoints for create/list/show/update/delete, approve, void, and attach-to-invoice.
- Finance config flags for legacy ledger mode, carryforward behavior, payment allocation policy, and tuition calculator version.

## Safety posture

- Existing finance routes were not removed.
- Existing PayPal models/controllers/routes were not removed.
- Existing invoice/payment math remains the source for read models.
- Carryforward posting creates a separate new-year invoice instead of mutating prior-year invoices.
- Follow-up notes do not modify invoice balances.
- Installment allocation writes to additive allocation tables and installment balances only.
- Notifications currently log database events instead of sending real external email/SMS, because inboxes are not test benches, despite humanity's tireless effort to prove otherwise.

## Key files changed or added

- `database/migrations/2026_06_04_230000_add_finance_lifecycle_tables.php`
- `config/finance.php`
- `app/Services/Finance/ParentPaymentFollowUpService.php`
- `app/Services/Finance/PriorYearBalanceCarryforwardService.php`
- `app/Services/Finance/InstallmentPlanService.php`
- `app/Services/Finance/FinanceNotificationLogService.php`
- `app/Http/Controllers/Api/Finance/BalanceCarryforwardController.php`
- `app/Http/Controllers/Api/Finance/InstallmentPlanController.php`
- `app/Http/Controllers/Api/Finance/FinanceNotificationController.php`
- `app/Http/Controllers/Api/Finance/EventChargeController.php`
- `app/Http/Controllers/Api/Finance/FinancialController.php`
- `routes/api.php`
- New finance request classes under `app/Http/Requests/Finance/`
- New finance lifecycle models under `app/Models/`

## Not fully implemented by design

- Centralized ledger replacement is still behind the future phase. That is intentional. Replacing accounting math without dry-runs is how systems become folklore.
- External mail/SMS sending is not activated. The implementation logs notification intent first.
- Parent-facing UI pages are not included because this package is the Laravel API.