# ═══════════════════════════════════════════════════════════════
# PHASE 3: FINANCE CORE MODULE
# Module directory: /modules/finance/
# ═══════════════════════════════════════════════════════════════
# READ THE MASTER PROMPT FIRST.

## YOUR TABLES
invoices, invoice_items, invoice_discounts, payments, payment_allocations,
payment_methods, receipts, receipt_items, fee_types, discount_types,
tax_rates, cash_registers, cash_register_sessions, cash_register_transactions,
daily_cash_reconciliation, fiscal_years, fiscal_periods,
member_balances (write via sp_recalculate_member_balance), member_ledger

## PAGES TO BUILD

### 1. Invoice Listing (`GET /finance/invoices`)
- DataTable: Invoice#, Member, Type, Date, Due Date, Total, Paid, Balance, Status, Actions
- Filters: Status, Type, Date Range, Overdue toggle
- Summary cards: Total Outstanding, Total Overdue, Issued Today, Collected Today

### 2. Create Invoice (`GET /finance/invoices/create`, `POST /finance/invoices`)
- Member lookup (Select2 AJAX)
- Invoice type selection
- Dynamic line items: Fee Type (Select2), Description, Qty, Unit Price, Discount, Tax Rate → auto-calc totals
- Add/remove line items dynamically
- Apply discount (discount_types selection)
- Due date (Flatpickr)
- Notes
- Save as draft or issue immediately
- Call `sp_create_invoice` then `sp_add_invoice_item` for each item
- Then optionally `sp_issue_invoice`

### 3. View Invoice (`GET /finance/invoices/{id}`)
- Professional invoice layout (printable)
- Club header, member details, line items table, totals
- Payment history for this invoice
- Action buttons: Issue (if draft), Record Payment, Print, Void, Cancel
- PDF download

### 4. Record Payment (`GET /finance/payments/create`, `POST /finance/payments`)
- Member lookup
- Amount, Payment Method, Date, Reference #
- Allocate to specific invoice(s) or auto-allocate
- Call `sp_record_payment`
- Auto-generate receipt via `sp_generate_receipt`
- If cash register session active, record transaction

### 5. Payment Listing (`GET /finance/payments`)
- DataTable: Payment#, Member, Amount, Method, Date, Status, Actions
- Filters: Method, Status, Date Range

### 6. Receipts (`GET /finance/receipts`)
- DataTable: Receipt#, Member, Amount, Date, Status
- View receipt (printable format)
- Reprint option

### 7. Cash Register Management
- Open Session (`POST /finance/cash-register/open`): Select register, enter opening balance
- Active Session Dashboard: Show current session stats (cash in, cash out, checks, cards, transaction count)
- Close Session (`POST /finance/cash-register/close`): Enter closing balance, system calculates expected, shows variance
- Session History: List past sessions with reconciliation status

### 8. Fee Types Management (`GET /finance/fee-types`)
- CRUD for fee_types table

### 9. Payment Methods Management
- CRUD for payment_methods

### 10. Fiscal Years & Periods
- CRUD for fiscal_years and fiscal_periods
- Open/Close periods

### 11. Member Financial Statement (`GET /finance/members/{id}/statement`)
- Full member_ledger for a member
- Date range filter
- Running balance display
- Print/Export options

### 12. Daily Revenue Report (`GET /finance/daily-revenue`)
- Use vw_daily_revenue view
- Date picker, grouped by payment method
- Chart (bar chart by method)

### 13. Overdue Invoices Report
- Use vw_overdue_invoices view
- DataTable with aging buckets (30/60/90/120+ days)

## BUSINESS LOGIC
- Invoice total auto-calculated from items
- balance_due = total_amount - paid_amount (DB trigger handles this)
- Payment allocation updates invoice paid_amount (DB trigger)
- Issuing invoice updates member outstanding_balance
- Cash register session must be open to accept cash/check payments
- Receipts auto-generated on payment
- Fiscal period must be open to record transactions

## DASHBOARD WIDGETS
1. **Revenue Today** — Total collected today by method
2. **Outstanding Balance** — Total system-wide outstanding
3. **Overdue Invoices** — Count and total amount

## PERMISSIONS
invoices.view, invoices.create, invoices.void,
payments.view, payments.create, payments.reverse,
receipts.view, receipts.print,
cash_register.open, cash_register.close