# Phase 15 — General ledger, budget control and consolidated finance reporting

## Implemented source workflows

### General ledger posting service
`App\Support\LedgerPoster` posts balanced double-entry journals using active chart-of-account codes and checks for an existing facility/source reference before creating a new journal. A database unique key protects the same source tuple against duplicate posting.

Configured account codes seeded:
- 1000 Cash and bank
- 1100 Accounts receivable
- 1300 Inventory control
- 2000 Accounts payable
- 2100 Goods received not invoiced (GRNI)
- 4000 Service revenue
- 5000 Medical supplies expense
- 5100 Staff costs
- 5200 Utilities expense

Automatic posting flows:
- Patient invoice: Dr Accounts Receivable / Cr Service Revenue.
- Patient receipt: Dr Cash and Bank / Cr Accounts Receivable.
- Goods receipt: Dr Inventory Control / Cr GRNI.
- Supplier bill (three-way matched): Dr GRNI / Cr Accounts Payable.
- Supplier payment: Dr Accounts Payable / Cr Cash and Bank.
- Inventory receipt outside PO flow: Dr Inventory Control / Cr GRNI.
- Inventory issue: Dr Medical Supplies Expense / Cr Inventory Control.
- Payroll marked paid: Dr Staff Costs / Cr Cash and Bank.
- Manual journals remain balanced debit/credit entries.

All posting calls execute within the surrounding transaction where applicable. The ledger poster rejects missing/inactive control accounts and unbalanced journal lines.

### Budget allocation and monitoring
- Facility-specific budget allocation by chart account and period.
- Draft and approved status with maker-checker approval.
- Purchase order requires an approved budget.
- Approval reserves/commits funds and rejects overspend.
- Supplier bill expenditure reduces commitment and increases spent amount.
- Budget transaction history records commitment and expenditure references.

### Goods received note and three-way matching
- Approved purchase order is required for receipt.
- Receipt lines must belong to the selected order.
- Duplicate PO lines are rejected in one GRN.
- Received quantity cannot exceed outstanding PO quantity.
- Goods receipt creates inventory batch and movement.
- GRN posts inventory and GRNI journal.
- Supplier bill requires an approved matching PO and an existing GRN.
- Cumulative supplier bill value cannot exceed goods-received value for that PO.

**Scope note:** the current supplier bill screen captures a bill total rather than full supplier invoice line detail. Three-way control is at PO/GRN/bill total level, not a complete line-by-line invoice matching workflow.

### Financial reporting
- Date-filtered general-ledger account activity.
- Period debit/credit totals and net account balances.
- Revenue and expense summaries.
- Period activity balance check.
- Budget commitment/spend/available summary.
- CSV ledger export.
- Optional facility filter for LCDA-wide roles.

## Test source added
- `LedgerPostingAcceptanceTest`: balanced journal and idempotent source reference.
- `GoodsReceiptAcceptanceTest`: stock increase, received quantity and GRN journal.
- Existing procurement/payroll acceptance test updated to provide an approved budget.

## Important limitations
- This is not a complete government chart of accounts or statutory accounting package.
- Opening balances, financial period lock/close, reversals, accruals, depreciation, tax, withholding, payroll statutory calculations and bank reconciliation for every transaction type are not yet complete.
- The period report summarises posted activity, not a fully reconciled opening-to-closing trial balance.
- Budget expenditure mapping currently uses PO-linked supplier bills; payroll is not linked to a budget allocation.
- Inventory issue uses the seeded medical supplies expense account; category-specific cost accounts and costing methods are future work.
- The GRN UI currently presents one receipt line; controller accepts multiple lines.
- Runtime tests and migration execution remain pending because Composer, Docker, MySQL and PDO drivers are unavailable in the build environment.


## Account posting map
| Event | Debit | Credit |
|---|---|---|
| Patient invoice | 1100 Accounts receivable | 4000 Service revenue |
| Patient receipt | 1000 Cash and bank | 1100 Accounts receivable |
| Goods receipt / stock receipt | 1300 Inventory control | 2100 GRNI |
| Supplier bill | 2100 GRNI | 2000 Accounts payable |
| Supplier payment | 2000 Accounts payable | 1000 Cash and bank |
| Inventory issue | 5000 Medical supplies expense | 1300 Inventory control |
| Payroll marked paid | 5100 Staff costs | 1000 Cash and bank |

The posting map is a basic configured control-account scheme. The LCDA finance team must approve the chart of accounts and accounting policy before live use.
