chore: adapt deprecated endpoints to 15-minutes predictions (#1195)

Ensure the deprecated endpoints get /strompreis, post /gesamtlast, get /gesamtlast_simple,
get /pvforecast to work on 1-hour intervalls even if the prediction provides 15-minutes
intervall data. This keeps the interface compliant to the legacy functionality.

Besides this adaptations several other improvements and fixes are included in this PR.

* feat: extend data management method key_to array by resample_method

  One can now define the resample method on how to aggregate the values in an interval
  for resampling. Three methods are provided:

  - "first": Use the first value in each interval.
  - "mean": Compute the arithmetic mean of all samples in each interval.
  - "interval_mean": Compute the time-weighted mean assuming each value remains valid
     until the next timestamp (piecewise-constant signal).

* feat: extend the get /v1/prediction/dataframe endpoint with resampling parameters

  Make all parameters for resampling available at the endpoint.

* feat: extend the get /v1/prediction/list endpoint with resampling parameters

  Make all parameters for resampling available at the endpoint.

* feat: add new delete /v1/prediction/range endpoint

  The endpoint allows to delete prediction values for a given time span.

* fix: adapt for PVForecastAkkudoktor server side cache handling

  /api.akkudoktor/forecast does it's own caching on requests. Call it with slightly
  randomized request values to avoid getting cached values in the case we need fresh
  data. The requests are anyway rate limited to one request per hour on our side.

* chore: add core.types

  This module centralizes reusable type definitions shared across multiple
  packages. Defining common types here avoids duplication of complex type
  annotations (such as Literal aliases), ensures consistent typing across the
  code base, and helps prevent circular import dependencies between modules.

* chore: extend cache testing

* chore: add system test for deprecated /strompreis endpoint

* chore: add unit test module for server endpoints

  Add a new test module to do unit tests on server endpoints. First test added
  for deprecated get /strompreis endpoint.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

docs/_generated/openapi.md

@@ -1,6 +1,6 @@
 # Akkudoktor-EOS
 
-**Version**: `v0.3.0.dev2607290944830210`
+**Version**: `v0.3.0.dev2607301181843779`
 
 <!-- pyml disable line-length -->
 **Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.
@@ -38,9 +38,9 @@ Deprecated: Total Load Prediction with adjustment.
 
 Endpoint to handle total load prediction adjusted by latest measured data.
 
-Total load prediction starts at 00.00.00 today and is provided for 48 hours.
-If no prediction values are available the missing ones at the start of the series are
-filled with the first available prediction value.
+Total load prediction starts at 00.00.00 today and is provided for 48 hours
+in 1-hour intervals. If no prediction values are available the missing ones
+at the start of the series are filled with the first available prediction value.
 
 Note:
     Use '/v1/prediction/list?key=loadforecast_power_w' instead.
@@ -82,9 +82,9 @@ Deprecated: Total Load Prediction.
 
 Endpoint to handle total load prediction.
 
-Total load prediction starts at 00.00.00 today and is provided for 48 hours.
-If no prediction values are available the missing ones at the start of the series are
-filled with the first available prediction value.
+Total load prediction starts at 00.00.00 today and is provided for 48 hours
+in 1-hour intervals. If no prediction values are available the missing ones
+at the start of the series are filled with the first available prediction value.
 
 Args:
     year_energy (float): Yearly energy consumption in Wh.
@@ -169,9 +169,9 @@ Deprecated: PV Forecast Prediction.
 
 Endpoint to handle PV forecast prediction.
 
-PVForecast starts at 00.00.00 today and is provided for 48 hours.
-If no forecast values are available the missing ones at the start of the series are
-filled with the first available forecast value.
+PVForecast starts at 00.00.00 today and is provided for 48 hours
+in 1-hour intervals. If no forecast values are available the missing ones
+at the start of the series are filled with the first available forecast value.
 
 Note:
     Set PVForecastAkkudoktor as provider, then update data with
@@ -202,9 +202,9 @@ Fastapi Strompreis
 """
 Deprecated: Electricity Market Price Prediction per Wh [amount/Wh].
 
-Electricity prices start at 00.00.00 today and are provided for 48 hours.
-If no prices are available the missing ones at the start of the series are
-filled with the first available price.
+Electricity prices start at 00.00.00 today and are provided for 48 hours
+in 1-hour intervals. If no prices are available the missing ones at the
+start of the series are filled with the first available price.
 
 Note:
     Electricity price charges are added.
@@ -1091,15 +1091,54 @@ Fastapi Prediction Dataframe Get
 <!-- pyml disable line-length -->
 ```python
 """
-Get prediction for given key within given date range as series.
+Get prediction for given keys within given date range as dataframe.
 
 Args:
-    key (str): Prediction key
+    key (list[str]): Prediction keys
     start_datetime (Optional[str]): Starting datetime (inclusive).
         Defaults to start datetime of latest prediction.
     end_datetime (Optional[str]: Ending datetime (exclusive).
+        Defaults to end datetime of latest prediction.
+    interval (Optional[str]): Time duration for each interval.
+        Defaults to 1 hour.
+    fill_method (str): Method to handle missing values during resampling.
 
-Defaults to end datetime of latest prediction.
+        - 'linear': Linearly interpolate missing values (for numeric data only).
+        - 'time': Interpolate missing values (for numeric data only).
+        - 'ffill': Forward fill missing values.
+        - 'bfill': Backward fill missing values.
+        - Defaults to 'linear' for numeric values, otherwise 'ffill'.
+
+    resample_method (str):
+        Method used to aggregate values within a resampling interval.
+
+        - "first": Use the first value in each interval.
+        - "mean": Compute the arithmetic mean of all samples in each interval.
+        - "interval_mean": Compute the time-weighted mean assuming each
+            value remains valid until the next timestamp (piecewise-constant
+            signal).
+
+    dropna: (bool, optional): Whether to drop NAN/ None values before processing.
+        Defaults to True.
+    boundary (Literal["strict", "context"]): resampling boundary
+        "strict"  → only values inside [start, end)
+        "context" → include one value before and after for proper resampling
+    align_to_interval (bool): When True, snap the resample origin to the nearest
+        UTC epoch-aligned boundary of ``interval`` before resampling.  This ensures
+        that bucket timestamps always fall on wall-clock-round times regardless of
+        when ``start_datetime`` falls:
+
+        - 15-minute interval → buckets on :00, :15, :30, :45
+        - 1-hour interval    → buckets on the hour
+
+        When False (default), the origin is ``query_start`` (or ``"start_day"`` when
+        no start is given), preserving the existing behaviour where buckets are
+        aligned to the query window rather than the clock.
+
+        Set to True when storing compacted records back to the database so that the
+        resulting timestamps are predictable and human-readable.  Leave False for
+        forecast or reporting queries where alignment to the exact query window is
+        more important than clock-round boundaries.
 """
 ```
 <!-- pyml enable line-length -->
@@ -1114,6 +1153,16 @@ Defaults to end datetime of latest prediction.
 
 - `interval` (query, optional): Time duration for each interval. Defaults to 1 hour.
 
+- `fill_method` (query, optional): Method to handle missing values during resampling.
+
+- `resample_method` (query, optional): Method used to aggregate values within a resampling interval.
+
+- `dropna` (query, optional): Drop NAN/ None values before processing.
+
+- `boundary` (query, optional): Resampling boundary mode.
+
+- `align_to_interval` (query, optional): Snap resample origin to the nearest UTC epoch-aligned boundary of interval.
+
 **Responses**:
 
 - **200**: Successful Response
@@ -1222,6 +1271,44 @@ Args:
         Defaults to end datetime of latest prediction.
     interval (Optional[str]): Time duration for each interval.
         Defaults to 1 hour.
+    fill_method (str): Method to handle missing values during resampling.
+
+        - 'linear': Linearly interpolate missing values (for numeric data only).
+        - 'time': Interpolate missing values (for numeric data only).
+        - 'ffill': Forward fill missing values.
+        - 'bfill': Backward fill missing values.
+        - Defaults to 'linear' for numeric values, otherwise 'ffill'.
+
+    resample_method (str):
+        Method used to aggregate values within a resampling interval.
+
+        - "first": Use the first value in each interval.
+        - "mean": Compute the arithmetic mean of all samples in each interval.
+        - "interval_mean": Compute the time-weighted mean assuming each
+            value remains valid until the next timestamp (piecewise-constant
+            signal).
+
+    dropna: (bool, optional): Whether to drop NAN/ None values before processing.
+        Defaults to True.
+    boundary (Literal["strict", "context"]): resampling boundary
+        "strict"  → only values inside [start, end)
+        "context" → include one value before and after for proper resampling
+    align_to_interval (bool): When True, snap the resample origin to the nearest
+        UTC epoch-aligned boundary of ``interval`` before resampling.  This ensures
+        that bucket timestamps always fall on wall-clock-round times regardless of
+        when ``start_datetime`` falls:
+
+        - 15-minute interval → buckets on :00, :15, :30, :45
+        - 1-hour interval    → buckets on the hour
+
+        When False (default), the origin is ``query_start`` (or ``"start_day"`` when
+        no start is given), preserving the existing behaviour where buckets are
+        aligned to the query window rather than the clock.
+
+        Set to True when storing compacted records back to the database so that the
+        resulting timestamps are predictable and human-readable.  Leave False for
+        forecast or reporting queries where alignment to the exact query window is
+        more important than clock-round boundaries.
 """
 ```
 <!-- pyml enable line-length -->
@@ -1236,6 +1323,16 @@ Args:
 
 - `interval` (query, optional): Time duration for each interval. Defaults to 1 hour.
 
+- `fill_method` (query, optional): Method to handle missing values during resampling.
+
+- `resample_method` (query, optional): Method used to aggregate values within a resampling interval.
+
+- `dropna` (query, optional): Drop NAN/ None values before processing.
+
+- `boundary` (query, optional): Resampling boundary mode.
+
+- `align_to_interval` (query, optional): Snap resample origin to the nearest UTC epoch-aligned boundary of interval.
+
 **Responses**:
 
 - **200**: Successful Response
@@ -1275,6 +1372,38 @@ Args:
 
 ---
 
+## DELETE /v1/prediction/range
+
+<!-- pyml disable line-length -->
+**Links**: [local](http://localhost:8503/docs#/default/fastapi_prediction_range_delete_v1_prediction_range_delete), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/fastapi_prediction_range_delete_v1_prediction_range_delete)
+<!-- pyml enable line-length -->
+
+Fastapi Prediction Range Delete
+
+<!-- pyml disable line-length -->
+```python
+"""
+Delete prediction values for a key within a datetime range.
+"""
+```
+<!-- pyml enable line-length -->
+
+**Parameters**:
+
+- `key` (query, required): Prediction key.
+
+- `start_datetime` (query, optional): Start datetime.
+
+- `end_datetime` (query, optional): End datetime.
+
+**Responses**:
+
+- **200**: Successful Response
+
+- **422**: Validation Error
+
+---
+
 ## GET /v1/prediction/series
 
 <!-- pyml disable line-length -->