FU10: localize energy time math to server tz; accrue fixed/credit per elapsed local day

- Store UTC, compute day boundaries in server local timezone (new app/services/timezone.py).
- summarize: fixed fee / tax credit accrue only for elapsed whole local days,
  integrated across contract versions — no future-day inflation, no version-switch collapse.
- MQTT import_cost_total / export_revenue_total getters delegate to summarize (no inline
  apportionment), anchored at the active contract's earliest version effective_from so the
  total sensors stay monotonic and never jump backward.
- effective_from: naive datetimes interpreted as server-local wall-clock, then stored UTC.
- frontend ContractForm sends local-midnight naive datetime (was UTC midnight).
- get_costs_summary default window uses server-local "today".

app/services/contracts.py

@@ -286,6 +286,32 @@ def deactivate_contract(session: Session, contract: EnergyContract) -> None:
     logger.info("Deactivated contract %r (id=%d)", contract.name, contract.id)
 
 
+def active_contract_versions(session: Session) -> list[EnergyContractVersion]:
+    """Return all versions of the currently active contract, ordered by effective_from ascending.
+
+    Returns an empty list when there is no active contract.  The list spans the
+    full history of the active contract (all closed + the current open version)
+    and is used to iterate over pricing-rate segments for cross-version fixed-
+    cost / credit accumulation (Principle C).
+    """
+    active = session.execute(
+        select(EnergyContract).where(EnergyContract.active.is_(True)).limit(1)
+    ).scalar_one_or_none()
+
+    if active is None:
+        return []
+
+    return list(
+        session.execute(
+            select(EnergyContractVersion)
+            .where(EnergyContractVersion.contract_id == active.id)
+            .order_by(EnergyContractVersion.effective_from)
+        )
+        .scalars()
+        .all()
+    )
+
+
 def active_contract_version_at(
     session: Session, ts: datetime
 ) -> EnergyContractVersion | None:

app/services/energy_cost.py

@@ -60,7 +60,8 @@ from app.integrations.pricing.strategies import (
     get_strategy,
 )
 from app.models.energy import DsmrReading, EnergyCostPeriod
-from app.services.contracts import active_contract_version_at
+from app.services.contracts import active_contract_version_at, active_contract_versions
+from app.services.timezone import local_date, local_now
 
 logger = logging.getLogger(__name__)
 
@@ -496,13 +497,23 @@ def summarize(session: Session, start: datetime, end: datetime) -> dict[str, Any
     Computes the total payable as:
 
         total_payable = Σ(net_cost)              -- metered electricity
-                      + fixed_costs              -- (network_fee + management_fee) EUR/month ÷ 30 × days
-                      - credits                  -- heffingskorting EUR/year ÷ 365 × days
+                      + fixed_costs              -- per-day standing charges, cross-version
+                      - credits                  -- per-day heffingskorting, cross-version
 
-    The fixed costs and credits are derived from the *currently active contract
-    version* at *end* (i.e. the version in effect at the end of the requested
-    interval).  When no active contract version exists, fixed costs and credits
-    are both 0; only the metered sum is returned.
+    **Fixed-cost / credit counting — Principle C**:
+    Only *already-elapsed* whole local calendar days are counted.  For each
+    local calendar date D in the window ``[start_local_date, min(end_local_date,
+    tomorrow_local))``, the contract version whose rate covers D (the one whose
+    effective_from local-date ≤ D < next version's effective_from local-date) is
+    used.  Days that have not yet started in local time (D > today_local) are
+    never counted.  This is cross-version: if the active contract has V1 from
+    June 1 and V2 from June 25, querying June 1–30 uses V1 for days 1-24 and V2
+    for day 25.  Switching versions never resets the counter.
+
+    **Timezone note**: the ``days`` field in the returned dict still represents
+    the window length in calendar days (total_seconds / 86400), for backward
+    compatibility with existing API consumers.  The fixed/credit calculation
+    independently counts whole local days as described above.
 
     All arithmetic uses Decimal; the returned dict contains Python floats for
     JSON-serialisation convenience.
@@ -512,9 +523,9 @@ def summarize(session: Session, start: datetime, end: datetime) -> dict[str, Any
     session:
         Active read-only SQLAlchemy session.
     start:
-        Inclusive start of the summary interval.
+        Inclusive start of the summary interval (UTC or naive-UTC).
     end:
-        Exclusive end of the summary interval.
+        Exclusive end of the summary interval (UTC or naive-UTC).
 
     Returns
     -------
@@ -524,13 +535,15 @@ def summarize(session: Session, start: datetime, end: datetime) -> dict[str, Any
         metered_import    float  Σ import_cost from non-degraded periods
         metered_export    float  Σ export_revenue from non-degraded periods
         metered_net       float  Σ net_cost from non-degraded periods
-        fixed_costs       float  standing charges apportioned over the interval
-        credits           float  energy-tax credit apportioned over the interval
+        fixed_costs       float  standing charges for elapsed whole local days
+        credits           float  energy-tax credit for elapsed whole local days
         total_payable     float  metered_net + fixed_costs − credits
         period_count      int    number of non-degraded periods in range
         degraded_count    int    number of degraded periods in range
         days              float  interval length in days (total_seconds / 86400)
     """
+    from datetime import timedelta as _td, date as _date
+
     start_utc = _as_utc(start)
     end_utc = _as_utc(end)
 
@@ -550,32 +563,95 @@ def summarize(session: Session, start: datetime, end: datetime) -> dict[str, Any
     sum_export = sum((_to_decimal(r.export_revenue) for r in good_rows), Decimal("0"))
     sum_net = sum((_to_decimal(r.net_cost) for r in good_rows), Decimal("0"))
 
-    # --- Interval length in days ---
+    # --- Interval length in days (window, not elapsed — kept for API compat) ---
     total_seconds = (end_utc - start_utc).total_seconds()
     days = _to_decimal(str(total_seconds)) / _to_decimal("86400")
 
-    # --- Active contract version at *end* for standing charges ---
-    version = active_contract_version_at(session, end_utc)
+    # --- Fixed costs and credits: Principle C cross-version whole-day counting ---
+    today_local: _date = local_now().date()
+
+    # --- Compute [first_counted, last_counted] local date range (inclusive) ---
+    #
+    # We count local calendar day D if its LOCAL MIDNIGHT falls within [start_utc, end_utc)
+    # AND D ≤ today_local (only elapsed / today days count as "whole days").
+    #
+    # Semantics: "A day D is counted when its local midnight has arrived (D ≤ today)
+    # AND the local midnight is within the billing window."
+    #
+    # This means a sub-day window [10:00, 10:30) UTC that doesn't contain any
+    # local midnight contributes 0 days, while a window [22:00 UTC, 23:00 UTC) that
+    # contains CEST midnight (= 22:00 UTC) contributes 1 day.
+    #
+    # Implementation: compute the first and last local date whose midnight is in range.
+    from app.services.timezone import local_midnight_utc as _lmu
+
+    local_start_date: _date = local_date(start_utc)
+    # Is the midnight of local_start_date ≥ start_utc?  If not, first midnight is next day.
+    if _lmu(local_start_date) >= start_utc:
+        first_counted: _date = local_start_date
+    else:
+        first_counted = local_start_date + _td(days=1)
+
+    local_end_date: _date = local_date(end_utc)
+    # Is the midnight of local_end_date < end_utc?  If yes, that day's midnight is in range.
+    if _lmu(local_end_date) < end_utc:
+        last_counted: _date = local_end_date
+    else:
+        last_counted = local_end_date - _td(days=1)
+
+    # Cap: only elapsed or today's days.
+    last_counted = min(last_counted, today_local)
+
+    # If the range is empty (first_counted > last_counted), no days are counted.
+
+    # Fetch all versions of the active contract once (single DB call).
+    versions = active_contract_versions(session)
 
     fixed_dec = Decimal("0")
     credits_dec = Decimal("0")
     currency = "EUR"
 
-    if version is not None:
-        currency = version.contract.currency
-        vals: dict = version.values or {}
-        standing: dict = vals.get("standing", {})
-        creds: dict = vals.get("credits", {})
+    if versions:
+        # Currency comes from the contract regardless of day count.
+        currency = versions[0].contract.currency
 
-        network_fee = _to_decimal(standing.get("network_fee", 0))
-        management_fee = _to_decimal(standing.get("management_fee", 0))
-        heffingskorting = _to_decimal(creds.get("heffingskorting", 0))
+    if versions and first_counted <= last_counted:
+        # For each version segment, find its overlap with [first_counted, last_counted]
+        # and accumulate whole days.
+        version_segments: list[tuple[_date, _date | None, dict]] = []
+        for v in versions:
+            v_start_local = local_date(_as_utc(v.effective_from))
+            v_end_local = local_date(_as_utc(v.effective_to)) if v.effective_to is not None else None
+            version_segments.append((v_start_local, v_end_local, v.values or {}))
 
-        # Standing charges: EUR/month → EUR/day (÷ 30) × days.
-        fixed_dec = (network_fee + management_fee) / Decimal("30") * days
+        for v_start, v_end_excl, v_values in version_segments:
+            # The version covers [v_start, v_end_excl) in local dates,
+            # where v_end_excl=None means open-ended (no upper bound).
+            # Intersection with [first_counted, last_counted]:
+            seg_start = max(first_counted, v_start)
+            if v_end_excl is not None:
+                seg_end_excl = min(last_counted + _td(days=1), v_end_excl)
+            else:
+                seg_end_excl = last_counted + _td(days=1)
 
-        # Energy-tax credit: EUR/year → EUR/day (÷ 365) × days.
-        credits_dec = heffingskorting / Decimal("365") * days
+            if seg_start >= seg_end_excl:
+                continue  # no overlap
+
+            n_days = (seg_end_excl - seg_start).days
+            if n_days <= 0:
+                continue
+
+            standing: dict = v_values.get("standing", {})
+            creds: dict = v_values.get("credits", {})
+
+            network_fee = _to_decimal(standing.get("network_fee", 0))
+            management_fee = _to_decimal(standing.get("management_fee", 0))
+            heffingskorting = _to_decimal(creds.get("heffingskorting", 0))
+
+            # Standing charges: EUR/month → EUR/day (÷ 30) × n_days.
+            fixed_dec += (network_fee + management_fee) / Decimal("30") * Decimal(str(n_days))
+            # Energy-tax credit: EUR/year → EUR/day (÷ 365) × n_days.
+            credits_dec += heffingskorting / Decimal("365") * Decimal(str(n_days))
 
     total_payable = sum_net + fixed_dec - credits_dec
 

app/services/timezone.py

@@ -0,0 +1,100 @@
+"""Server local-timezone helpers.
+
+All time is stored as UTC (no change).  This module provides a single,
+monkeypatch-friendly entry point for converting UTC moments to the server's
+local timezone — used for business-day boundary calculations (standing charges,
+effective-from date interpretation, etc.).
+
+Design goals
+------------
+- Zero third-party dependencies (no tzlocal, no pytz).
+- Testable without depending on CI host timezone:
+  monkeypatch ``local_tz`` to a fixed ``ZoneInfo`` in unit tests.
+- DST-correct: conversions use ``astimezone(local_tz())`` per instant, so each
+  moment is independently correct even during DST transitions.
+- Consistent with the existing ``.astimezone()`` pattern already used in
+  ``homeassistant_inbound.py`` and ``poo.py``.
+
+Priority for resolving the local timezone
+-----------------------------------------
+1. ``TZ`` environment variable — ``ZoneInfo(os.environ["TZ"])``.
+   Set ``TZ=Europe/Amsterdam`` in the deployment env for correct NL handling.
+2. System local timezone fallback: ``datetime.now().astimezone().tzinfo``.
+   This matches the behaviour callers already relied on implicitly.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import date, datetime, timezone
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo
+
+if TYPE_CHECKING:
+    from datetime import tzinfo
+
+
+def local_tz() -> "tzinfo":
+    """Return the server's local timezone.
+
+    Resolution order:
+    1. ``TZ`` environment variable (``ZoneInfo(TZ)``).  Set
+       ``TZ=Europe/Amsterdam`` in production for correct NL/DST handling.
+    2. System local timezone via ``datetime.now().astimezone().tzinfo``.
+
+    **Monkeypatch this function in tests** to get deterministic timezone
+    behaviour regardless of CI host configuration::
+
+        monkeypatch.setattr("app.services.timezone.local_tz",
+                            lambda: ZoneInfo("Europe/Amsterdam"))
+    """
+    tz_env = os.environ.get("TZ", "").strip()
+    if tz_env:
+        return ZoneInfo(tz_env)
+    # System fallback — identical to the .astimezone() pattern already used
+    # in homeassistant_inbound.py and poo.py.
+    return datetime.now().astimezone().tzinfo  # type: ignore[return-value]
+
+
+def to_local(dt: datetime) -> datetime:
+    """Convert *dt* to the server local timezone.
+
+    Handles three input cases:
+    - timezone-aware (any zone): converted via ``astimezone``.
+    - timezone-naive: assumed UTC (SQLite read-back convention), then converted.
+
+    Returns a timezone-aware datetime in ``local_tz()``.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(local_tz())
+
+
+def local_now() -> datetime:
+    """Return the current moment as a timezone-aware local datetime."""
+    return datetime.now(local_tz())
+
+
+def local_date(dt: datetime) -> date:
+    """Return the local calendar date for *dt*.
+
+    Equivalent to ``to_local(dt).date()``.  A distinct helper to make
+    call sites readable.
+    """
+    return to_local(dt).date()
+
+
+def local_midnight_utc(d: date) -> datetime:
+    """Return the UTC instant that corresponds to local midnight on *d*.
+
+    Example (Europe/Amsterdam, CEST=UTC+2):
+        local_midnight_utc(date(2026, 6, 25))
+        → datetime(2026, 6, 24, 22, 0, 0, tzinfo=UTC)
+
+    This is used to convert a local calendar date back to a UTC boundary, e.g.
+    to compute the start/end of a local day for DB queries.
+    """
+    tz = local_tz()
+    # Build a naive local datetime at midnight, then localize and convert to UTC.
+    local_midnight = datetime(d.year, d.month, d.day, 0, 0, 0, tzinfo=tz)
+    return local_midnight.astimezone(timezone.utc)