FUE-T08: defer daily fixed-fee/heffingskorting settlement to local 01:05 in summarize()

2026-06-26 11:44:34 +02:00
parent d4acfc438a
commit d3fc90b320
2 changed files with 333 additions and 19 deletions
@@ -123,6 +123,10 @@ _READING_MAX_STALENESS = timedelta(minutes=_PERIOD_MINUTES)
 # degraded to prevent negative costs or grossly inflated charges.
 _MAX_DELTA_KWH = Decimal("100")

+# 每日固定费/税补在"本地午夜后多久"才结算入账。延后到 01:05 是为了让累计成本的
+# 整天阶跃落在新一天、且避开 01:00 整点（HA 长期统计的小时桶边界）。
+_SETTLEMENT_OFFSET = timedelta(hours=1, minutes=5)
+
 # DSMR payload register keys (cumulative kWh, JSON string values).
 _KEY_D1 = "electricity_delivered_1"   # delivered low-tariff  (dal / _1)
 _KEY_D2 = "electricity_delivered_2"   # delivered high-tariff (normal / _2)
@@ -764,7 +768,8 @@ def summarize(session: Session, start: datetime, end: datetime) -> dict[str, Any
    days = _to_decimal(str(total_seconds)) / _to_decimal("86400")

    # --- Fixed costs and credits: Principle C cross-version whole-day counting ---
-    today_local: _date = local_now().date()
+    _now_local = local_now()
+    today_local: _date = _now_local.date()

    # --- Compute [first_counted, last_counted] local date range (inclusive) ---
    #
@@ -811,8 +816,16 @@ def summarize(session: Session, start: datetime, end: datetime) -> dict[str, Any
    else:
        last_counted = local_end_date - _td(days=1)

-    # Cap: only elapsed or today's days.
-    last_counted = min(last_counted, today_local)
+    # Settlement cap: "today" is only counted once the local clock has passed the
+    # settlement offset since midnight (01:05).  This defers the daily standing-charge
+    # step from 00:00 to 01:05, ensuring the cumulative-cost adiabatic jump lands
+    # inside the new calendar day and avoids the HA 01:00 hourly-bucket boundary.
+    _today_midnight_utc = _lmu(today_local)
+    if _now_local >= _today_midnight_utc + _SETTLEMENT_OFFSET:
+        settled_cap = today_local
+    else:
+        settled_cap = today_local - _td(days=1)
+    last_counted = min(last_counted, settled_cap)

    # If the range is empty (first_counted > last_counted), no days are counted.

@@ -1199,10 +1199,16 @@ def _ams_midnight(year: int, month: int, day: int) -> datetime:


 class TestSummarizePrincipleC:
-    """Principle C whole-day counting with pinned Europe/Amsterdam timezone."""
+    """Principle C whole-day counting with pinned Europe/Amsterdam timezone.
+
+    Tests that assert a specific "today" (e.g. June 25) must also pin
+    ``local_now`` via *pinned_now* to remain deterministic as wall-clock
+    time advances.  Tests that only care about windows entirely in the past
+    or entirely in the future do not need to pin ``local_now``.
+    """

    # Effective_from: June 1 CEST local midnight = May 31 22:00 UTC.
-    # Today local = June 25 CEST (since today is 2026-06-25).
+    # Reference "today" pinned in individual tests = June 25 CEST.

    def _make_single_version_contract(self, session: Session, *, effective_from_utc: datetime) -> None:
        """Create an active manual contract with a single version."""
@@ -1210,10 +1216,27 @@ class TestSummarizePrincipleC:
        _make_version(session, contract, _MANUAL_VALUES, effective_from=effective_from_utc)
        session.commit()

-    def _run_summarize_ams(self, session: Session, start_utc: datetime, end_utc: datetime) -> dict:
-        """Run summarize with Europe/Amsterdam local_tz monkeypatched."""
+    def _run_summarize_ams(
+        self,
+        session: Session,
+        start_utc: datetime,
+        end_utc: datetime,
+        *,
+        pinned_now: datetime | None = None,
+    ) -> dict:
+        """Run summarize with Europe/Amsterdam local_tz monkeypatched.
+
+        If *pinned_now* is given, also patches ``app.services.energy_cost.local_now``
+        to that fixed value, making settlement-offset logic deterministic
+        regardless of wall-clock time.
+        """
        from unittest.mock import patch
+        import app.services.energy_cost as _ec
+
        with patch.object(tz_module, "local_tz", return_value=_ams()):
+            if pinned_now is not None:
+                with patch.object(_ec, "local_now", return_value=pinned_now):
+                    return summarize(session, start_utc, end_utc)
            return summarize(session, start_utc, end_utc)

    def test_today_window_counts_1_day(self, energy_db: Session) -> None:
@@ -1259,7 +1282,10 @@ class TestSummarizePrincipleC:
    def test_this_month_window_counts_25_days(self, energy_db: Session) -> None:
        """This Month (June 1 → July 1 local) counts 25 elapsed days (June 1..25).

-        Today = June 25 local, so June 26–30 are not yet elapsed.
+        Pins ``local_now`` to June 25 noon AMS so the test is deterministic
+        regardless of the actual wall-clock date.  June 25 is well past the
+        01:05 settlement offset, so ``settled_cap = June 25``.
+        Today = June 25 local, so June 26–30 are not yet elapsed → 25 days.
        Matches table row: 6/1→7/1 (This Month) → 25 days.
        """
        eff_utc = _ams_midnight(2026, 6, 1)
@@ -1267,7 +1293,9 @@ class TestSummarizePrincipleC:

        start = _ams_midnight(2026, 6, 1)
        end = _ams_midnight(2026, 7, 1)
-        result = self._run_summarize_ams(energy_db, start, end)
+        # Pin local_now to June 25 2026 noon AMS (well past 01:05 settlement).
+        pinned_now = datetime(2026, 6, 25, 12, 0, 0, tzinfo=_ams())
+        result = self._run_summarize_ams(energy_db, start, end, pinned_now=pinned_now)

        daily_fixed = (9.87 + 9.87) / 30
        daily_credit = 600.0 / 365
@@ -1304,8 +1332,9 @@ class TestSummarizePrincipleC:
    def test_partial_future_window_caps_at_today(self, energy_db: Session) -> None:
        """A window partially in the future caps at today (only elapsed days counted).

+        Pins ``local_now`` to June 25 noon AMS so the test is deterministic.
        Window: June 25 → June 28 local (4 dates, but June 26/27 are future).
-        Today = June 25 → only 1 day elapsed (June 25).
+        Today = June 25 → settled_cap = June 25 → only 1 day elapsed (June 25).
        Matches table row: 6/25→6/28 → 1 day.
        """
        eff_utc = _ams_midnight(2026, 6, 1)
@@ -1313,7 +1342,9 @@ class TestSummarizePrincipleC:

        start = _ams_midnight(2026, 6, 25)
        end = _ams_midnight(2026, 6, 28)
-        result = self._run_summarize_ams(energy_db, start, end)
+        # Pin local_now to June 25 2026 noon AMS (well past 01:05 settlement).
+        pinned_now = datetime(2026, 6, 25, 12, 0, 0, tzinfo=_ams())
+        result = self._run_summarize_ams(energy_db, start, end, pinned_now=pinned_now)

        daily_fixed = (9.87 + 9.87) / 30
        daily_credit = 600.0 / 365
@@ -1366,8 +1397,12 @@ class TestSummarizePrincipleC:
        start = _ams_midnight(2026, 6, 1)
        end = _ams_midnight(2026, 7, 1)
        from unittest.mock import patch
+        import app.services.energy_cost as _ec
+        # Pin local_now to June 25 2026 noon AMS: today=June 25, settled_cap=June 25.
+        pinned_now = datetime(2026, 6, 25, 12, 0, 0, tzinfo=_ams())
        with patch.object(tz_module, "local_tz", return_value=_ams()):
-            result = summarize(energy_db, start, end)
+            with patch.object(_ec, "local_now", return_value=pinned_now):
+                result = summarize(energy_db, start, end)

        # V1: 24 days × (6+6)/30; V2: 1 day × (12+12)/30
        expected_fixed = 24 * 12 / 30 + 1 * 24 / 30
@@ -1408,12 +1443,16 @@ class TestSummarizePrincipleC:
        _make_version(energy_db, contract, _VALUES_V2, effective_from=v2_from)
        energy_db.commit()

-        # Window = June 25 only (today, 1 day elapsed at V2 rate)
+        # Window = June 25 only (today, 1 day elapsed at V2 rate).
+        # Pin local_now to June 25 noon AMS: today=June 25, settled_cap=June 25.
        start = _ams_midnight(2026, 6, 25)
        end = _ams_midnight(2026, 7, 1)
        from unittest.mock import patch
+        import app.services.energy_cost as _ec
+        pinned_now = datetime(2026, 6, 25, 12, 0, 0, tzinfo=_ams())
        with patch.object(tz_module, "local_tz", return_value=_ams()):
-            result = summarize(energy_db, start, end)
+            with patch.object(_ec, "local_now", return_value=pinned_now):
+                result = summarize(energy_db, start, end)

        # Only 1 day at V2 rate
        expected_fixed = 1 * 24 / 30
@@ -1434,13 +1473,11 @@ class TestSummarizePrincipleC:
          within the day start_utc falls.  June 24 is the anchor day → its charge is counted.

        Window: [June 24 07:18 UTC (= 09:18 CEST), June 26 22:00 UTC (= June 27 00:00 CEST)).
-        Today local = June 25 (2026-06-25).
+        Pins local_now to June 25 noon AMS → today=June 25, settled_cap=June 25.
        first_counted = June 24 (anchor day, previously dropped).
        last_counted = min(June 26, June 25) = June 25.
        n_days = June 25 - June 24 + 1 = 2.
        """
-        from unittest.mock import patch
-
        eff_utc = _ams_midnight(2026, 6, 1)
        self._make_single_version_contract(energy_db, effective_from_utc=eff_utc)

@@ -1449,8 +1486,9 @@ class TestSummarizePrincipleC:
        # end = June 26 22:00 UTC = June 27 00:00 CEST (past today June 25, capped)
        end_utc = datetime(2026, 6, 26, 22, 0, 0, tzinfo=_UTC)

-        with patch.object(tz_module, "local_tz", return_value=_ams()):
-            result = self._run_summarize_ams(energy_db, anchor_utc, end_utc)
+        # Pin local_now to June 25 noon AMS: today=June 25, settled_cap=June 25.
+        pinned_now = datetime(2026, 6, 25, 12, 0, 0, tzinfo=_ams())
+        result = self._run_summarize_ams(energy_db, anchor_utc, end_utc, pinned_now=pinned_now)

        daily_fixed = (9.87 + 9.87) / 30
        daily_credit = 600.0 / 365
@@ -2409,3 +2447,266 @@ class TestMeterAwareComputePeriod:
        assert row.degraded is False, "All-zero deltas must not trigger the D6 guard"
        assert row.import_cost == 0.0
        assert row.net_cost == 0.0
+
+
+# ---------------------------------------------------------------------------
+# FUE-T08. summarize — settlement offset (local 01:05)
+# ---------------------------------------------------------------------------
+
+
+class TestSummarizeSettlementOffset:
+    """FUE-T08: daily fixed-fee/heffingskorting settled after local 01:05.
+
+    Reference date: June 26, 2026 AMS (CEST = UTC+2).
+      - AMS midnight June 26  = June 25 22:00 UTC
+      - Settlement threshold  = June 25 22:00 + 01:05 = June 25 23:05 UTC
+                              = June 26 01:05 AMS
+      - "before offset" now   = June 26 00:30 AMS = June 25 22:30 UTC
+      - "after  offset" now   = June 26 01:10 AMS = June 25 23:10 UTC
+
+    All tests monkeypatch both local_tz (Europe/Amsterdam) and
+    ``app.services.energy_cost.local_now`` to be fully deterministic.
+    """
+
+    # UTC instants used as "now":
+    # June 25 22:30 UTC = June 26 00:30 AMS (before settlement threshold 23:05 UTC)
+    _NOW_BEFORE = datetime(2026, 6, 25, 22, 30, 0, tzinfo=UTC)
+    # June 25 23:10 UTC = June 26 01:10 AMS (after settlement threshold 23:05 UTC)
+    _NOW_AFTER = datetime(2026, 6, 25, 23, 10, 0, tzinfo=UTC)
+
+    def _setup_single_version_contract(self, session: Session) -> None:
+        """Insert a manual contract effective Jan 1 2026 (covers all test dates)."""
+        c = _make_contract(session, kind="manual", active=True)
+        _make_version(session, c, _MANUAL_VALUES, effective_from=_ams_midnight(2026, 1, 1))
+        session.commit()
+
+    def _run(
+        self,
+        session: Session,
+        start_utc: datetime,
+        end_utc: datetime,
+        *,
+        now_utc: datetime,
+    ) -> dict:
+        """Run summarize with AMS timezone and pinned local_now.
+
+        *now_utc* is converted to AMS before being used as the ``local_now``
+        return value, so ``.date()`` yields the correct AMS local date.
+        """
+        from unittest.mock import patch
+        import app.services.energy_cost as _ec
+
+        now_ams = now_utc.astimezone(_ams())
+        with patch.object(tz_module, "local_tz", return_value=_ams()):
+            with patch.object(_ec, "local_now", return_value=now_ams):
+                return summarize(session, start_utc, end_utc)
+
+    # --- AC1: before 01:05 → today not settled → fixed_costs/credits == 0 ---
+
+    def test_today_window_before_offset_yields_zero(self, energy_db: Session) -> None:
+        """AC1: At local 00:30 (before 01:05), today's window → credits == 0 and fixed_costs == 0.
+
+        Window: [June 26 AMS midnight, June 27 AMS midnight).
+        now = June 26 00:30 AMS (before 01:05) → settled_cap = June 25.
+        first_counted = June 26 > last_counted = June 25 → 0 days.
+        """
+        self._setup_single_version_contract(energy_db)
+        start = _ams_midnight(2026, 6, 26)   # June 25 22:00 UTC
+        end = _ams_midnight(2026, 6, 27)     # June 26 22:00 UTC
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_BEFORE)
+
+        assert result["fixed_costs"] == 0.0, (
+            "AC1: before settlement offset, today's fixed_costs must be 0; "
+            f"got {result['fixed_costs']}"
+        )
+        assert result["credits"] == 0.0, (
+            "AC1: before settlement offset, today's credits must be 0; "
+            f"got {result['credits']}"
+        )
+
+    # --- AC2: >= 01:05 → today settled → 1 day fixed/credits ---
+
+    def test_today_window_after_offset_yields_one_day(self, energy_db: Session) -> None:
+        """AC2: At local 01:10 (>= 01:05), today's window → 1 day of fixed/credits.
+
+        Window: [June 26 AMS midnight, June 27 AMS midnight).
+        now = June 26 01:10 AMS (after 01:05) → settled_cap = June 26.
+        first_counted = June 26 = last_counted → 1 day.
+        """
+        self._setup_single_version_contract(energy_db)
+        start = _ams_midnight(2026, 6, 26)
+        end = _ams_midnight(2026, 6, 27)
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_AFTER)
+
+        daily_fixed = (9.87 + 9.87) / 30
+        daily_credit = 600.0 / 365
+        assert abs(result["fixed_costs"] - daily_fixed) < 1e-9, (
+            "AC2: after settlement offset, today's fixed_costs must equal 1 day; "
+            f"expected {daily_fixed:.6f}, got {result['fixed_costs']}"
+        )
+        assert abs(result["credits"] - daily_credit) < 1e-9, (
+            "AC2: after settlement offset, today's credits must equal 1 day; "
+            f"expected {daily_credit:.6f}, got {result['credits']}"
+        )
+
+    # --- AC3a: cumulative window, before offset → today (June 26) not counted ---
+
+    def test_cumulative_before_offset_excludes_today(self, energy_db: Session) -> None:
+        """AC3: Cumulative window at 00:30 (before offset) excludes today from count.
+
+        Window: [June 24 AMS midnight, June 26 00:30 AMS).
+          first_counted = June 24.
+          last_counted (from window) = June 26 (lmu(June 26) = June 25 22:00 < 22:30).
+          settled_cap = June 25 (before offset) → min(June 26, June 25) = June 25.
+          Counted: June 24 + June 25 = 2 days (today June 26 excluded).
+        """
+        self._setup_single_version_contract(energy_db)
+        start = _ams_midnight(2026, 6, 24)   # June 23 22:00 UTC
+        end = self._NOW_BEFORE               # June 25 22:30 UTC = June 26 00:30 AMS
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_BEFORE)
+
+        daily_fixed = (9.87 + 9.87) / 30
+        daily_credit = 600.0 / 365
+        assert abs(result["fixed_costs"] - daily_fixed * 2) < 1e-9, (
+            "AC3 before offset: today (June 26) must not be counted; expected 2 days; "
+            f"got {result['fixed_costs']}"
+        )
+        assert abs(result["credits"] - daily_credit * 2) < 1e-9, (
+            "AC3 before offset: credits must be 2 days; "
+            f"got {result['credits']}"
+        )
+
+    # --- AC3b: cumulative window, after offset → today (June 26) counted ---
+
+    def test_cumulative_after_offset_includes_today(self, energy_db: Session) -> None:
+        """AC3: Cumulative window at 01:10 (after offset) includes today.
+
+        Window: [June 24 AMS midnight, June 26 01:10 AMS).
+          first_counted = June 24.
+          last_counted (from window) = June 26 (lmu(June 26) < 23:10 UTC).
+          settled_cap = June 26 (after offset) → last_counted = June 26.
+          Counted: June 24 + June 25 + June 26 = 3 days.
+        """
+        self._setup_single_version_contract(energy_db)
+        start = _ams_midnight(2026, 6, 24)   # June 23 22:00 UTC
+        end = self._NOW_AFTER               # June 25 23:10 UTC = June 26 01:10 AMS
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_AFTER)
+
+        daily_fixed = (9.87 + 9.87) / 30
+        daily_credit = 600.0 / 365
+        assert abs(result["fixed_costs"] - daily_fixed * 3) < 1e-9, (
+            "AC3 after offset: today (June 26) must be counted; expected 3 days; "
+            f"got {result['fixed_costs']}"
+        )
+        assert abs(result["credits"] - daily_credit * 3) < 1e-9, (
+            "AC3 after offset: credits must be 3 days; "
+            f"got {result['credits']}"
+        )
+
+    # --- AC4: past days always fully counted regardless of offset ---
+
+    def test_past_days_always_counted_regardless_of_offset(self, energy_db: Session) -> None:
+        """AC4: Past days (all before today) are fully counted even before 01:05.
+
+        Window: [June 20 AMS midnight, June 26 AMS midnight) — all before today.
+        now = June 26 00:30 AMS (before offset) → settled_cap = June 25.
+        last_counted (from window) = June 25 (lmu(June 26) = end_utc, not <).
+        min(June 25, June 25) = June 25 → 6 days (June 20-25), all past.
+        """
+        self._setup_single_version_contract(energy_db)
+        start = _ams_midnight(2026, 6, 20)   # June 19 22:00 UTC
+        end = _ams_midnight(2026, 6, 26)     # June 25 22:00 UTC
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_BEFORE)
+
+        daily_fixed = (9.87 + 9.87) / 30
+        daily_credit = 600.0 / 365
+        # June 20-25 = 6 days, all past — unaffected by settlement offset.
+        assert abs(result["fixed_costs"] - daily_fixed * 6) < 1e-9, (
+            "AC4: past days must be fully counted regardless of settlement offset; "
+            f"expected 6 days = {daily_fixed * 6:.6f}, got {result['fixed_costs']}"
+        )
+        assert abs(result["credits"] - daily_credit * 6) < 1e-9, (
+            "AC4: past credits must be 6 days; "
+            f"got {result['credits']}"
+        )
+
+    # --- AC5: cross-version segments still correct with settlement offset ---
+
+    def test_cross_version_with_settlement_offset(self, energy_db: Session) -> None:
+        """AC5: Cross-version day split is correct when settlement offset is active.
+
+        V1 covers June 24; V2 covers June 25+.
+        Window: [June 24 AMS midnight, June 26 01:10 AMS).
+        After offset (01:10) → settled_cap = June 26 → 3 days: V1=1, V2=2.
+
+        V1: network_fee=6, management_fee=6 → daily_fixed = 12/30
+            heffingskorting=300           → daily_credit = 300/365
+        V2: network_fee=12, management_fee=12 → daily_fixed = 24/30
+            heffingskorting=600            → daily_credit = 600/365
+
+        Expected:
+          fixed_costs = 1×(12/30) + 2×(24/30) = 0.4 + 1.6 = 2.0
+          credits     = 1×(300/365) + 2×(600/365) = 1500/365
+        """
+        _VALUES_V1 = {
+            "energy": {"buy": {"normal": 0.10, "dal": 0.10},
+                       "sell": {"normal": 0.05, "dal": 0.05},
+                       "energy_tax": 0.0, "ode": 0.0},
+            "standing": {"network_fee": 6.0, "management_fee": 6.0},
+            "credits": {"heffingskorting": 300.0},
+        }
+        _VALUES_V2 = {
+            "energy": {"buy": {"normal": 0.20, "dal": 0.20},
+                       "sell": {"normal": 0.08, "dal": 0.08},
+                       "energy_tax": 0.0, "ode": 0.0},
+            "standing": {"network_fee": 12.0, "management_fee": 12.0},
+            "credits": {"heffingskorting": 600.0},
+        }
+        v1_from = _ams_midnight(2026, 6, 24)   # June 23 22:00 UTC
+        v2_from = _ams_midnight(2026, 6, 25)   # June 24 22:00 UTC
+
+        c = _make_contract(energy_db, kind="manual", active=True)
+        _make_version(energy_db, c, _VALUES_V1, effective_from=v1_from, effective_to=v2_from)
+        _make_version(energy_db, c, _VALUES_V2, effective_from=v2_from)
+        energy_db.commit()
+
+        start = _ams_midnight(2026, 6, 24)   # June 23 22:00 UTC
+        end = self._NOW_AFTER               # June 25 23:10 UTC = June 26 01:10 AMS
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_AFTER)
+
+        expected_fixed = 1 * 12 / 30 + 2 * 24 / 30    # V1: 1 day, V2: 2 days
+        expected_credits = 1 * 300 / 365 + 2 * 600 / 365
+        assert abs(result["fixed_costs"] - expected_fixed) < 1e-9, (
+            f"AC5: cross-version fixed_costs wrong; expected {expected_fixed}, "
+            f"got {result['fixed_costs']}"
+        )
+        assert abs(result["credits"] - expected_credits) < 1e-9, (
+            f"AC5: cross-version credits wrong; expected {expected_credits}, "
+            f"got {result['credits']}"
+        )
+
+    # --- AC6: return dict key-set unchanged ---
+
+    def test_return_dict_keys_unchanged(self, energy_db: Session) -> None:
+        """AC6: summarize() return dict keys are unchanged by the settlement offset."""
+        self._setup_single_version_contract(energy_db)
+        start = _ams_midnight(2026, 6, 26)
+        end = _ams_midnight(2026, 6, 27)
+
+        result = self._run(energy_db, start, end, now_utc=self._NOW_AFTER)
+
+        expected_keys = {
+            "currency", "metered_import", "metered_export", "metered_net",
+            "fixed_costs", "credits", "total_payable", "period_count",
+            "degraded_count", "days",
+        }
+        assert set(result.keys()) == expected_keys, (
+            f"AC6: summarize() key set changed; expected {expected_keys}, "
+            f"got {set(result.keys())}"
+        )