# VarianceReportLine

## Description

VarianceReportLine is a child record of a VarianceReport that captures the planned amount, actual amount, computed variance amount, variance percentage, and variance direction (FAVORABLE or UNFAVORABLE) for a specific cost element within a specific accounting period. Each line carries a variance report reference, cost element reference, accounting period reference, planned amount, actual amount, variance amount, variance percentage, and variance direction. Variance direction is determined by account type: for cost/expense elements, actual below plan is FAVORABLE; for revenue elements, actual above plan is FAVORABLE. This cost-element-level detail enables managers to diagnose exactly which cost types are driving deviations from the budget.

## Domain Model Definitions

### Model type

Standard

### Command Definitions

- [generateVarianceReport](../commands/GenerateVarianceReport.md) - Variance report lines are created as part of generating a variance report

### Query Definitions

- [GetVarianceReport](../queries/GetVarianceReport.md) - Retrieve variance report lines as part of the parent variance report

### Models

- VarianceReportLine

### Invariants

- Variance report line must reference a valid variance report via varianceReportId
- Variance report line must reference a valid cost element via costElementId
- Variance report line must reference a valid accounting period via accountingPeriodId
- Variance amount is calculated as actual amount minus planned amount
- Variance percentage is calculated as (actual - planned) / planned * 100; division by zero is handled gracefully when planned amount is zero
- For cost/expense cost elements, variance direction is FAVORABLE when actual is less than planned, UNFAVORABLE when actual is greater than planned
- For revenue cost elements, variance direction is FAVORABLE when actual is greater than planned, UNFAVORABLE when actual is less than planned
- When actual equals planned, variance amount is zero and variance direction is FAVORABLE
- A variance report line is created for each cost element that has either a planned amount or an actual amount (or both)
- A cost element with actual postings but no corresponding budget line item generates a detail line with zero planned amount
- Variance report lines cannot be modified independently of the parent variance report

### Relationships

- **Belongs to VarianceReport**: Each variance report line belongs to a VarianceReport via varianceReportId
- **References CostElement**: Each variance report line references a CostElement via costElementId
- **References AccountingPeriod**: Each variance report line references an AccountingPeriod via accountingPeriodId (finance-ledger module)
