tliu93/home-automation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

M8-T16: add thermal meter cost APIs

Browse Source
This commit is contained in:
tliu93
2026-08-23 21:22:06 +02:00
parent 489e5b596a
commit 3eec701448
12 changed files with 1843 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/api/routes/api/energy.py
+31 -10
View File
@@ -44,7 +44,7 @@ from __future__ import annotations
import logging
from datetime import UTC, datetime, timedelta
from typing import Any
from typing import Any, Literal
from fastapi import APIRouter, Depends, Query, status
from fastapi.responses import JSONResponse
@@ -133,13 +133,23 @@ def _manual_tariff_from_values(values: dict[str, Any]) -> ManualTariffSchema:
)
def _electricity_prices_response(response: PricesResponse) -> JSONResponse:
"""Preserve the exact pre-scope electricity response body."""
return JSONResponse(
content=response.model_dump(
mode="json", include={"kind", "currency", "points", "tariff"}
)
)
# ---------------------------------------------------------------------------
# GET /api/energy/prices
# ---------------------------------------------------------------------------
@router.get("/prices", response_model=PricesResponse)
@router.get("/prices", response_model=PricesResponse, response_model_exclude_none=True)
def get_prices(
scope: Literal["electricity", "thermal"] = Query("electricity"),
start: datetime | None = Query(
default=None,
description="Inclusive start of the time window (ISO 8601). "
@@ -186,6 +196,17 @@ def get_prices(
"""
now = datetime.now(UTC)
if scope == "thermal":
version = active_contract_version_at(db, now, scope="thermal")
if version is None:
return PricesResponse(kind=None, currency="EUR", points=[], tariff=None)
return PricesResponse(
kind="district_heating", currency=version.contract.currency,
contract_version_id=version.id, effective_from=_as_utc(version.effective_from),
effective_to=_as_utc(version.effective_to) if version.effective_to else None,
values=version.values, points=[], tariff=None,
)
# Default window: today + tomorrow.
if start is None:
start = now.replace(hour=0, minute=0, second=0, microsecond=0)
@@ -199,12 +220,12 @@ def get_prices(
version = active_contract_version_at(db, start_utc)
if version is None:
return PricesResponse(
return _electricity_prices_response(PricesResponse(
kind=None,
currency="EUR",
points=[],
tariff=None,
)
))
contract = version.contract
currency = contract.currency
@@ -247,30 +268,30 @@ def get_prices(
)
)
return PricesResponse(
return _electricity_prices_response(PricesResponse(
kind="tibber",
currency=currency,
points=points,
tariff=None,
)
))
elif contract.kind == "manual":
tariff = _manual_tariff_from_values(version.values or {})
return PricesResponse(
return _electricity_prices_response(PricesResponse(
kind="manual",
currency=currency,
points=[],
tariff=tariff,
)
))
else:
# Unknown kind — return empty response gracefully.
return PricesResponse(
return _electricity_prices_response(PricesResponse(
kind=contract.kind,
currency=currency,
points=[],
tariff=None,
)
))
# ---------------------------------------------------------------------------
app/api/routes/api/meter_costs.py
+150
View File
@@ -0,0 +1,150 @@
"""Authenticated API for the thermal 15-minute cost ledger."""
from __future__ import annotations
from datetime import UTC, datetime, timedelta
from decimal import Decimal
from typing import Literal
from fastapi import APIRouter, Depends, HTTPException, Query, status
from sqlalchemy import func, select
from sqlalchemy.orm import Session
from app.api.routes.api.deps import require_csrf, require_session
from app.dependencies import get_db
from app.models.energy import MeterCostPeriod
from app.schemas.meter_cost import (
MeterCostPeriodSchema,
MeterCostRecomputeResponse,
MeterCostsResponse,
ThermalCostSummaryResponse,
)
from app.services.auth import AuthenticatedSession
from app.services.meter_cost import recompute_range, summarize
from app.services.timezone import local_midnight_utc, local_now
router = APIRouter(prefix="/api/energy/meter-costs", tags=["api-energy"])
_LIMIT_MAX = 5000
_RECOMPUTE_MAX_DAYS = 31
_QUARTER = timedelta(minutes=15)
def _utc(value: datetime) -> datetime:
return value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
def _decimal_strings(value: object) -> object:
if isinstance(value, dict):
return {str(key): _decimal_strings(item) for key, item in value.items()}
if isinstance(value, Decimal):
return format(value, "f")
return str(value) if isinstance(value, (int, float)) else value
def _row_schema(row: MeterCostPeriod) -> MeterCostPeriodSchema:
return MeterCostPeriodSchema(
commodity=row.commodity,
period_start=_utc(row.period_start), period_end=_utc(row.period_end),
meter_id=row.meter_id, source_binding_id=row.source_binding_id,
contract_version_id=row.contract_version_id, quantity=format(row.quantity, "f"),
cost=format(row.cost, "f"), currency=row.currency,
cost_breakdown=_decimal_strings(row.cost_breakdown),
pricing_snapshot=_decimal_strings(row.pricing_snapshot), quality=row.quality,
degraded=row.degraded, degraded_reason=row.degraded_reason,
)
@router.get("", response_model=MeterCostsResponse)
def get_meter_costs(
scope: Literal["thermal"] = Query("thermal"),
commodity: Literal["heating", "hot_water"] | None = None,
start: datetime | None = None,
end: datetime | None = None,
limit: int = Query(500, ge=1, le=_LIMIT_MAX),
offset: int = Query(0, ge=0),
db: Session = Depends(get_db),
_auth: AuthenticatedSession = Depends(require_session),
) -> MeterCostsResponse:
"""List thermal rows in a half-open time window with stable pagination."""
del scope
if start is not None and end is not None and _utc(end) <= _utc(start):
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "'end' must be after 'start'.")
clauses = []
if commodity is not None:
clauses.append(MeterCostPeriod.commodity == commodity)
if start is not None:
clauses.append(MeterCostPeriod.period_start >= _utc(start))
if end is not None:
clauses.append(MeterCostPeriod.period_start < _utc(end))
total = db.scalar(select(func.count()).select_from(MeterCostPeriod).where(*clauses)) or 0
rows = db.execute(
select(MeterCostPeriod).where(*clauses).order_by(MeterCostPeriod.period_start, MeterCostPeriod.id)
.offset(offset).limit(limit)
).scalars().all()
return MeterCostsResponse(items=[_row_schema(row) for row in rows], total=total)
@router.get("/summary", response_model=ThermalCostSummaryResponse)
def get_meter_cost_summary(
scope: Literal["thermal"] = Query("thermal"),
start: datetime | None = None,
end: datetime | None = None,
db: Session = Depends(get_db),
_auth: AuthenticatedSession = Depends(require_session),
) -> ThermalCostSummaryResponse:
"""Summarize thermal variable and once-per-contract daily fixed costs."""
del scope
if start is None or end is None:
today = local_now().date()
start = start or local_midnight_utc(today)
end = end or local_midnight_utc(today + timedelta(days=1))
start, end = _utc(start), _utc(end)
if end <= start:
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "'end' must be after 'start'.")
result = summarize(db, start, end)
breakdown = result["breakdown"]
fixed_breakdown = result["fixed_breakdown"]
fixed = result["fixed_cost"]
return ThermalCostSummaryResponse(
currency=result["currency"], heating=format(breakdown["heating"], "f"),
hot_water_heating=format(breakdown["hot_water_heating"], "f"),
hot_water=format(breakdown["hot_water"], "f"), hot_water_tax=format(breakdown["hot_water_tax"], "f"),
variable_subtotal=format(result["variable_cost"], "f"),
fixed_breakdown={key: format(value, "f") for key, value in fixed_breakdown.items()},
fixed_subtotal=format(fixed, "f"),
all_in=format(result["total_cost"], "f"), period_count=result["period_count"],
degraded_count=result["degraded_count"],
)
@router.post("/recompute", response_model=MeterCostRecomputeResponse)
def post_meter_cost_recompute(
scope: Literal["thermal"] = Query("thermal"),
start: datetime = Query(...), end: datetime = Query(...),
db: Session = Depends(get_db), _auth: AuthenticatedSession = Depends(require_session),
_csrf: None = Depends(require_csrf),
) -> MeterCostRecomputeResponse:
"""Atomically overwrite closed, UTC-quarter thermal rows in a bounded window."""
del scope
start, end = _utc(start), _utc(end)
if end <= start or end - start > timedelta(days=_RECOMPUTE_MAX_DAYS):
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "invalid or overlarge recompute window")
if start.minute % 15 or start.second or start.microsecond or end.minute % 15 or end.second or end.microsecond:
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "start and end must align to UTC quarters")
if end > datetime.now(UTC):
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "recompute window must be closed")
try:
processed = recompute_range(db, start, end, commit=False)
# Ensure pending upserts participate in this transaction before the
# counts are read; a flush/query failure must still roll everything back.
db.flush()
rows = db.execute(select(MeterCostPeriod.degraded).where(
MeterCostPeriod.period_start >= start, MeterCostPeriod.period_start < end
)).scalars().all()
degraded = sum(bool(value) for value in rows)
db.commit()
except Exception:
db.rollback()
raise
return MeterCostRecomputeResponse(processed=processed, normal=len(rows) - degraded, degraded=degraded)
app/main.py
+2
View File
@@ -17,6 +17,7 @@ from app.api.routes.api.config import router as api_config_router
from app.api.routes.api.data import router as api_data_router
from app.api.routes.api.energy import router as api_energy_router
from app.api.routes.api.energy_contracts import router as api_energy_contracts_router
from app.api.routes.api.meter_costs import router as api_meter_costs_router
from app.api.routes.api.expose import router as api_expose_router
from app.api.routes.api.meters import router as api_meters_router
from app.api.routes.api.meter_sources import router as api_meter_sources_router
@@ -343,6 +344,7 @@ def create_app() -> FastAPI:
app.include_router(api_data_router)
app.include_router(api_energy_router)
app.include_router(api_energy_contracts_router)
app.include_router(api_meter_costs_router)
app.include_router(api_meters_router)
app.include_router(api_meter_sources_router)
app.include_router(api_expose_router)
app/schemas/energy.py
+18
View File
@@ -76,6 +76,24 @@ class PricesResponse(BaseModel):
"Null for tibber contracts and when no active contract exists."
),
)
contract_version_id: int | None = Field(
default=None,
description="Thermal active contract version identifier; omitted for electricity.",
)
effective_from: datetime | None = Field(
default=None,
description="Thermal contract version start; omitted for electricity.",
)
effective_to: datetime | None = Field(
default=None,
description="Thermal contract version end; omitted for electricity.",
)
values: dict[str, dict[str, str]] | None = Field(
default=None,
description="Thermal normalized Decimal-string contract values; omitted for electricity.",
)
model_config = {"ser_json_exclude_none": True}
# ---------------------------------------------------------------------------
app/schemas/meter_cost.py
+62
View File
@@ -0,0 +1,62 @@
"""Schemas for the commodity-scoped thermal cost ledger."""
from __future__ import annotations
from datetime import datetime
from typing import Literal
from pydantic import BaseModel, Field
class MeterCostPeriodSchema(BaseModel):
"""One auditable thermal ledger row; all Decimal values are JSON strings."""
commodity: Literal["heating", "hot_water"]
period_start: datetime
period_end: datetime
meter_id: int | None
source_binding_id: int | None
contract_version_id: int | None
quantity: str
cost: str
currency: str
cost_breakdown: dict[str, str]
pricing_snapshot: dict[str, dict[str, str]]
quality: str
degraded: bool
degraded_reason: str | None
class MeterCostsResponse(BaseModel):
items: list[MeterCostPeriodSchema]
total: int = Field(description="Total matching rows before pagination.")
class ThermalFixedBreakdown(BaseModel):
"""D11 annual-standing charges accrued per settled local day, as Decimal strings."""
heating_network: str
metering: str
delivery_set: str
hot_water_network: str
other: str
class ThermalCostSummaryResponse(BaseModel):
currency: str
heating: str
hot_water_heating: str
hot_water: str
hot_water_tax: str
variable_subtotal: str
fixed_breakdown: ThermalFixedBreakdown
fixed_subtotal: str
all_in: str
period_count: int
degraded_count: int
class MeterCostRecomputeResponse(BaseModel):
processed: int
normal: int
degraded: int
app/services/meter_cost.py
+18 -8
View File
@@ -220,7 +220,14 @@ def compute_closed_periods(session: Session, *, now: datetime | None = None) ->
return written
def recompute_range(session: Session, start: datetime, end: datetime) -> int:
def recompute_range(session: Session, start: datetime, end: datetime, *, commit: bool = True) -> int:
"""Recompute a thermal range.
The historical service entry point remains self-committing for the scheduler
and direct callers. HTTP callers pass ``commit=False`` so validation,
recomputation, response statistics, and the single commit share one
transaction owned by the route.
"""
cursor, end = floor_to_quarter(_utc(start)), _utc(end)
now, written = datetime.now(UTC), 0
while cursor < end:
@@ -229,7 +236,8 @@ def recompute_range(session: Session, start: datetime, end: datetime) -> int:
if compute_period(session, commodity, cursor, overwrite=True):
written += 1
cursor += _PERIOD
session.commit()
if commit:
session.commit()
return written
@@ -257,7 +265,9 @@ def summarize(session: Session, start: datetime, end: datetime, *, now: datetime
final_day = timezone_service.local_date(end - timedelta(microseconds=1))
final_day = min(final_day, _settled_end_date(now or datetime.now(UTC)))
day = timezone_service.local_date(start)
fixed = Decimal("0")
fixed_breakdown: dict[str, Decimal] = {key: Decimal("0") for key in (
"heating_network", "metering", "delivery_set", "hot_water_network", "other"
)}
versions = active_contract_versions(session, scope="thermal")
while start < end and day <= final_day:
day_start = datetime.combine(day, time.min, tzinfo=timezone_service.local_tz()).astimezone(UTC)
@@ -275,14 +285,14 @@ def summarize(session: Session, start: datetime, end: datetime, *, now: datetime
if segment_start >= segment_end:
continue
values = version.values["standing"]
annual = sum((_decimal(values.get(key, "0")) for key in (
"heating_network", "metering", "delivery_set", "hot_water_network", "other"
)), Decimal("0"))
fraction = Decimal(str((segment_end - segment_start).total_seconds())) / local_day_seconds
fixed += annual / Decimal("365") * fraction
for key in fixed_breakdown:
fixed_breakdown[key] += _decimal(values.get(key, "0")) / Decimal("365") * fraction
day += timedelta(days=1)
fixed = sum(fixed_breakdown.values(), Decimal("0"))
return {
"currency": good[0].currency if good else "EUR", "variable_cost": variable,
"fixed_cost": fixed, "total_cost": variable + fixed, "breakdown": breakdown,
"fixed_cost": fixed, "fixed_breakdown": fixed_breakdown,
"total_cost": variable + fixed, "breakdown": breakdown,
"period_count": len(good), "degraded_count": len(rows) - len(good),
}