feat: Add Processing Opex functionality

- Introduced OpexValidationError for handling validation errors in processing opex calculations. - Implemented ProjectProcessingOpexRepository and ScenarioProcessingOpexRepository for managing project and scenario-level processing opex snapshots. - Enhanced UnitOfWork to include repositories for processing opex. - Updated sidebar navigation and scenario detail templates to include links to the new Processing Opex Planner. - Created a new template for the Processing Opex Planner with form handling for input components and parameters. - Developed integration tests for processing opex calculations, covering HTML and JSON flows, including validation for currency mismatches and unsupported frequencies. - Added unit tests for the calculation logic, ensuring correct handling of various scenarios and edge cases.
2025-11-13 09:26:57 +01:00
parent 1240b08740
commit 1feae7ff85
16 changed files with 1931 additions and 11 deletions
--- a/services/calculations.py
+++ b/services/calculations.py
@@ -3,9 +3,14 @@
 from __future__ import annotations

 from collections import defaultdict
+from statistics import fmean

 from services.currency import CurrencyValidationError, normalise_currency
-from services.exceptions import CapexValidationError, ProfitabilityValidationError
+from services.exceptions import (
+    CapexValidationError,
+    OpexValidationError,
+    ProfitabilityValidationError,
+)
 from services.financial import (
    CashFlow,
    ConvergenceError,
@@ -24,6 +29,14 @@ from schemas.calculations import (
    CapexTotals,
    CapexTimelineEntry,
    CashFlowEntry,
+    ProcessingOpexCalculationRequest,
+    ProcessingOpexCalculationResult,
+    ProcessingOpexCategoryBreakdown,
+    ProcessingOpexComponentInput,
+    ProcessingOpexMetrics,
+    ProcessingOpexParameters,
+    ProcessingOpexTotals,
+    ProcessingOpexTimelineEntry,
    ProfitabilityCalculationRequest,
    ProfitabilityCalculationResult,
    ProfitabilityCosts,
@@ -31,6 +44,15 @@ from schemas.calculations import (
 )


+_FREQUENCY_MULTIPLIER = {
+    "daily": 365,
+    "weekly": 52,
+    "monthly": 12,
+    "quarterly": 4,
+    "annually": 1,
+}
+
+
 def _build_pricing_input(
        request: ProfitabilityCalculationRequest,
 ) -> PricingInput:
@@ -332,4 +354,183 @@ def calculate_initial_capex(
    )


-__all__ = ["calculate_profitability", "calculate_initial_capex"]
+def calculate_processing_opex(
+        request: ProcessingOpexCalculationRequest,
+) -> ProcessingOpexCalculationResult:
+    """Aggregate processing opex components into annual totals and timeline."""
+
+    if not request.components:
+        raise OpexValidationError(
+            "At least one processing opex component is required for calculation.",
+            ["components"],
+        )
+
+    parameters: ProcessingOpexParameters = request.parameters
+    base_currency = parameters.currency_code
+    if base_currency:
+        try:
+            base_currency = normalise_currency(base_currency)
+        except CurrencyValidationError as exc:
+            raise OpexValidationError(
+                str(exc), ["parameters.currency_code"]
+            ) from exc
+
+    evaluation_horizon = parameters.evaluation_horizon_years or 1
+    if evaluation_horizon <= 0:
+        raise OpexValidationError(
+            "Evaluation horizon must be at least 1 year.",
+            ["parameters.evaluation_horizon_years"],
+        )
+
+    escalation_pct = float(parameters.escalation_pct or 0.0)
+    apply_escalation = bool(parameters.apply_escalation)
+
+    category_totals: dict[str, float] = defaultdict(float)
+    timeline_totals: dict[int, float] = defaultdict(float)
+    timeline_escalated: dict[int, float] = defaultdict(float)
+    normalised_components: list[ProcessingOpexComponentInput] = []
+
+    max_period_end = evaluation_horizon
+
+    for index, component in enumerate(request.components):
+        frequency = component.frequency.lower()
+        multiplier = _FREQUENCY_MULTIPLIER.get(frequency)
+        if multiplier is None:
+            raise OpexValidationError(
+                f"Unsupported frequency '{component.frequency}'.",
+                [f"components[{index}].frequency"],
+            )
+
+        unit_cost = float(component.unit_cost)
+        quantity = float(component.quantity)
+        annual_cost = unit_cost * quantity * multiplier
+
+        period_start = component.period_start or 1
+        period_end = component.period_end or evaluation_horizon
+        if period_end < period_start:
+            raise OpexValidationError(
+                (
+                    "Component period_end must be greater than or equal to "
+                    "period_start."
+                ),
+                [f"components[{index}].period_end"],
+            )
+
+        max_period_end = max(max_period_end, period_end)
+
+        component_currency = component.currency
+        if component_currency:
+            try:
+                component_currency = normalise_currency(component_currency)
+            except CurrencyValidationError as exc:
+                raise OpexValidationError(
+                    str(exc), [f"components[{index}].currency"]
+                ) from exc
+
+        if base_currency is None and component_currency:
+            base_currency = component_currency
+        elif (
+            base_currency is not None
+            and component_currency is not None
+            and component_currency != base_currency
+        ):
+            raise OpexValidationError(
+                (
+                    "Component currency does not match the global currency. "
+                    f"Expected {base_currency}, got {component_currency}."
+                ),
+                [f"components[{index}].currency"],
+            )
+
+        category_totals[component.category] += annual_cost
+
+        for period in range(period_start, period_end + 1):
+            timeline_totals[period] += annual_cost
+
+        normalised_components.append(
+            ProcessingOpexComponentInput(
+                id=component.id,
+                name=component.name,
+                category=component.category,
+                unit_cost=unit_cost,
+                quantity=quantity,
+                frequency=frequency,
+                currency=component_currency,
+                period_start=period_start,
+                period_end=period_end,
+                notes=component.notes,
+            )
+        )
+
+    evaluation_horizon = max(evaluation_horizon, max_period_end)
+
+    try:
+        currency = normalise_currency(base_currency) if base_currency else None
+    except CurrencyValidationError as exc:
+        raise OpexValidationError(
+            str(exc), ["parameters.currency_code"]
+        ) from exc
+
+    timeline_entries: list[ProcessingOpexTimelineEntry] = []
+    escalated_values: list[float] = []
+    overall_annual = timeline_totals.get(1, 0.0)
+    escalated_total = 0.0
+
+    for period in range(1, evaluation_horizon + 1):
+        base_cost = timeline_totals.get(period, 0.0)
+        if apply_escalation:
+            factor = (1 + escalation_pct / 100.0) ** (period - 1)
+        else:
+            factor = 1.0
+        escalated_cost = base_cost * factor
+        timeline_escalated[period] = escalated_cost
+        escalated_total += escalated_cost
+        timeline_entries.append(
+            ProcessingOpexTimelineEntry(
+                period=period,
+                base_cost=base_cost,
+                escalated_cost=escalated_cost if apply_escalation else None,
+            )
+        )
+        escalated_values.append(escalated_cost)
+
+    category_breakdowns: list[ProcessingOpexCategoryBreakdown] = []
+    total_base = sum(category_totals.values())
+    for category, total in sorted(category_totals.items()):
+        share = (total / total_base * 100.0) if total_base else None
+        category_breakdowns.append(
+            ProcessingOpexCategoryBreakdown(
+                category=category,
+                annual_cost=total,
+                share=share,
+            )
+        )
+
+    metrics = ProcessingOpexMetrics(
+        annual_average=fmean(escalated_values) if escalated_values else None,
+        cost_per_ton=None,
+    )
+
+    totals = ProcessingOpexTotals(
+        overall_annual=overall_annual,
+        escalated_total=escalated_total if apply_escalation else None,
+        escalation_pct=escalation_pct if apply_escalation else None,
+        by_category=category_breakdowns,
+    )
+
+    return ProcessingOpexCalculationResult(
+        totals=totals,
+        timeline=timeline_entries,
+        metrics=metrics,
+        components=normalised_components,
+        parameters=parameters,
+        options=request.options,
+        currency=currency,
+    )
+
+
+__all__ = [
+    "calculate_profitability",
+    "calculate_initial_capex",
+    "calculate_processing_opex",
+]
--- a/services/exceptions.py
+++ b/services/exceptions.py
@@ -48,3 +48,14 @@ class CapexValidationError(Exception):

    def __str__(self) -> str:  # pragma: no cover - mirrors message for logging
        return self.message
+
+
+@dataclass(eq=False)
+class OpexValidationError(Exception):
+    """Raised when opex calculation inputs fail domain validation."""
+
+    message: str
+    field_errors: Sequence[str] | None = None
+
+    def __str__(self) -> str:  # pragma: no cover - mirrors message for logging
+        return self.message
--- a/services/repositories.py
+++ b/services/repositories.py
@@ -17,10 +17,12 @@ from models import (
    PricingSettings,
    ProjectCapexSnapshot,
    ProjectProfitability,
+    ProjectProcessingOpexSnapshot,
    Role,
    Scenario,
    ScenarioCapexSnapshot,
    ScenarioProfitability,
+    ScenarioProcessingOpexSnapshot,
    ScenarioStatus,
    SimulationParameter,
    User,
@@ -571,6 +573,110 @@ class ScenarioCapexRepository:
        self.session.delete(entity)


+class ProjectProcessingOpexRepository:
+    """Persistence operations for project-level processing opex snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self, snapshot: ProjectProcessingOpexSnapshot
+    ) -> ProjectProcessingOpexSnapshot:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_project(
+        self,
+        project_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ProjectProcessingOpexSnapshot]:
+        stmt = (
+            select(ProjectProcessingOpexSnapshot)
+            .where(ProjectProcessingOpexSnapshot.project_id == project_id)
+            .order_by(ProjectProcessingOpexSnapshot.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_project(
+        self,
+        project_id: int,
+    ) -> ProjectProcessingOpexSnapshot | None:
+        stmt = (
+            select(ProjectProcessingOpexSnapshot)
+            .where(ProjectProcessingOpexSnapshot.project_id == project_id)
+            .order_by(ProjectProcessingOpexSnapshot.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ProjectProcessingOpexSnapshot).where(
+            ProjectProcessingOpexSnapshot.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Project processing opex snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
+class ScenarioProcessingOpexRepository:
+    """Persistence operations for scenario-level processing opex snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self, snapshot: ScenarioProcessingOpexSnapshot
+    ) -> ScenarioProcessingOpexSnapshot:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_scenario(
+        self,
+        scenario_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ScenarioProcessingOpexSnapshot]:
+        stmt = (
+            select(ScenarioProcessingOpexSnapshot)
+            .where(ScenarioProcessingOpexSnapshot.scenario_id == scenario_id)
+            .order_by(ScenarioProcessingOpexSnapshot.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_scenario(
+        self,
+        scenario_id: int,
+    ) -> ScenarioProcessingOpexSnapshot | None:
+        stmt = (
+            select(ScenarioProcessingOpexSnapshot)
+            .where(ScenarioProcessingOpexSnapshot.scenario_id == scenario_id)
+            .order_by(ScenarioProcessingOpexSnapshot.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ScenarioProcessingOpexSnapshot).where(
+            ScenarioProcessingOpexSnapshot.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Scenario processing opex snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
 class FinancialInputRepository:
    """Persistence operations for FinancialInput entities."""

--- a/services/unit_of_work.py
+++ b/services/unit_of_work.py
@@ -14,10 +14,12 @@ from services.repositories import (
    PricingSettingsSeedResult,
    ProjectRepository,
    ProjectProfitabilityRepository,
+    ProjectProcessingOpexRepository,
    ProjectCapexRepository,
    RoleRepository,
    ScenarioRepository,
    ScenarioProfitabilityRepository,
+    ScenarioProcessingOpexRepository,
    ScenarioCapexRepository,
    SimulationParameterRepository,
    UserRepository,
@@ -42,8 +44,10 @@ class UnitOfWork(AbstractContextManager["UnitOfWork"]):
        self.simulation_parameters: SimulationParameterRepository | None = None
        self.project_profitability: ProjectProfitabilityRepository | None = None
        self.project_capex: ProjectCapexRepository | None = None
+        self.project_processing_opex: ProjectProcessingOpexRepository | None = None
        self.scenario_profitability: ScenarioProfitabilityRepository | None = None
        self.scenario_capex: ScenarioCapexRepository | None = None
+        self.scenario_processing_opex: ScenarioProcessingOpexRepository | None = None
        self.users: UserRepository | None = None
        self.roles: RoleRepository | None = None
        self.pricing_settings: PricingSettingsRepository | None = None
@@ -58,10 +62,14 @@ class UnitOfWork(AbstractContextManager["UnitOfWork"]):
        self.project_profitability = ProjectProfitabilityRepository(
            self.session)
        self.project_capex = ProjectCapexRepository(self.session)
+        self.project_processing_opex = ProjectProcessingOpexRepository(
+            self.session)
        self.scenario_profitability = ScenarioProfitabilityRepository(
            self.session
        )
        self.scenario_capex = ScenarioCapexRepository(self.session)
+        self.scenario_processing_opex = ScenarioProcessingOpexRepository(
+            self.session)
        self.users = UserRepository(self.session)
        self.roles = RoleRepository(self.session)
        self.pricing_settings = PricingSettingsRepository(self.session)
@@ -82,8 +90,10 @@ class UnitOfWork(AbstractContextManager["UnitOfWork"]):
        self.simulation_parameters = None
        self.project_profitability = None
        self.project_capex = None
+        self.project_processing_opex = None
        self.scenario_profitability = None
        self.scenario_capex = None
+        self.scenario_processing_opex = None
        self.users = None
        self.roles = None
        self.pricing_settings = None