alrahma_sunday_school_api/FINANCE_PLAN_IMPLEMENTATION_NOTES.md

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.