metering 0.13.0

//! §17 MessZV substitute value generation (Ersatzwertbildung).
//!
//! When meter readings are missing or faulty, the Messstellenbetreiber must
//! generate substitute values (Ersatzwerte) before billing. This module
//! implements the standard methods defined by §17 MessZV and BDEW practice.
//!
//! ## Legal basis
//!
//! - **§17 Abs. 1 MessZV**: The MSB must supply substitute values when measurements
//!   are unavailable. Estimated (Prognosewert) and substituted values are billable.
//! - **BDEW MSCONS AHB**: Defines how `Messwertstatus` flags map to substitute types.
//! - **VDE-AR-N 4400**: Technical rules for substitute value methods.
//!
//! ## Methods implemented
//!
//! | Method | When to use | BDEW recommendation |
//! |---|---|---|
//! | `LinearInterpolation` | Short gaps (≤ 3 intervals) between valid readings | Primary for RLM/iMSys |
//! | `PriorPeriodAverage` | Longer gaps using prior week same-slot average | Biomass, industrial |
//! | `ZeroFill` | Confirmed zero delivery (documented shutdown) | Plant outage only |
//! | `LastValueCarryForward` | Conservative fallback when no context | SLP, default for long gaps |
//!
//! ## Gap filling
//!
//! [`fill_gaps`] uses automatic method selection (linear for short gaps, carry-forward
//! for longer ones). Use [`fill_gaps_with_config`] with [`FillGapsConfig`] to specify
//! a preferred method — in particular [`SubstituteMethod::PriorPeriodAverage`] per
//! §17 Abs. 2 MessZV requires providing `prior_period_intervals`.

use crate::interval::{MeterInterval, QualityFlag};
use rust_decimal::Decimal;
use time::{Duration, OffsetDateTime};

/// Length of the §17 Abs. 2 MessZV reference period: the calendar week
/// immediately preceding the gap.
pub const REFERENCE_PERIOD_DAYS: i64 = 7;

#[cfg(test)]
use rust_decimal::dec;

// ── SubstituteMethod ──────────────────────────────────────────────────────────

/// Method used to generate a substitute value per §17 MessZV.
///
/// Stored in the generated `MeterInterval.quality` as `Substituted` but
/// the method can be tracked separately for audit purposes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "SCREAMING_SNAKE_CASE"))]
pub enum SubstituteMethod {
    /// Linear interpolation between surrounding measured values.
    ///
    /// Best for short gaps (≤ 3 intervals) when readings before and after are available.
    #[default]
    LinearInterpolation,

    /// Average of the same time slot from a prior reference period.
    ///
    /// Per §17 Abs. 2 MessZV: use the same quarter-hour from the prior week.
    /// Requires [`FillGapsConfig::prior_period_intervals`] to be populated.
    /// Falls back to `LastValueCarryForward` when no matching slot is found.
    PriorPeriodAverage,

    /// Zero — confirmed absence of delivery (documented plant shutdown).
    ZeroFill,

    /// Carry forward the last known good value (conservative fallback).
    LastValueCarryForward,
}

// ── FillGapsConfig ────────────────────────────────────────────────────────────

/// Configuration for [`fill_gaps_with_config`].
///
/// Controls which [`SubstituteMethod`] is applied and provides prior-period
/// reference data for [`SubstituteMethod::PriorPeriodAverage`].
///
/// ## Example — prior-period averaging per §17 Abs. 2 MessZV
///
/// ```rust,ignore
/// use metering::{fill_gaps_with_config, FillGapsConfig, SubstituteMethod};
///
/// // Reference readings from 7 days prior
/// let prior: Vec<_> = fetch_prior_week_intervals(&malo_id).await;
///
/// let config = FillGapsConfig::prior_period(prior);
/// let filled = fill_gaps_with_config(&current, 900, period_from, period_to, &config);
/// ```
/// Reason why a substitute value was generated (for §22 MessZV audit trail).
///
/// Stored alongside each synthetic interval so that auditors and billing systems
/// can explain every line item.
///
/// ## Legal basis
///
/// §17 MessZV requires the MSB to document the substitute value method.
/// §22 MessZV requires a 3-year audit trail for all billing-relevant data.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "SCREAMING_SNAKE_CASE"))]
pub enum SubstitutionReason {
    /// §17 Abs. 1 MessZV — no measurement available for this interval.
    NoMeasurementAvailable,
    /// Meter hardware failure or communication fault.
    MeterFault,
    /// SMGW communication error (gateway not reachable).
    GatewayCommFailure,
    /// Plausibility check failed — value rejected, substitute generated.
    PlausibilityCheckFailed,
    /// Manual correction by MSB or operator.
    ManualCorrection,
    /// Meter exchange — value interpolated across the replacement boundary.
    MeterExchangeInterpolation,
    /// DST spring-forward: the "missing" hour (clock jumped from 02:00 to 03:00 CET).
    DstSpringForward,
    /// Billing period start/end gap filled for annual settlement.
    BillingPeriodGapFill,
    /// Other documented reason — see free-text `note` field if available.
    Other,
}

impl SubstitutionReason {
    /// Human-readable explanation for this reason (German).
    #[must_use]
    pub fn description(&self) -> &'static str {
        match self {
            Self::NoMeasurementAvailable => "Kein Messwert verfügbar (§17 Abs. 1 MessZV)",
            Self::MeterFault => "Zählerdefekt oder Kommunikationsstörung",
            Self::GatewayCommFailure => "SMGW-Kommunikationsfehler",
            Self::PlausibilityCheckFailed => "Plausibilitätsprüfung fehlgeschlagen",
            Self::ManualCorrection => "Manuelle Korrektur durch MSB/Betreiber",
            Self::MeterExchangeInterpolation => "Zählerwechsel — Interpolation über Wechselgrenze",
            Self::DstSpringForward => "Sommerzeit-Umstellung — fehlende Stunde",
            Self::BillingPeriodGapFill => "Abrechnungszeitraum-Lücke",
            Self::Other => "Sonstiger dokumentierter Grund",
        }
    }
}

/// Configuration for [`fill_gaps_with_config`].
///
/// Controls which substitute value method is applied, how many prior-period
/// reference intervals are used, and what reason is recorded in the audit trail.
pub struct FillGapsConfig {
    /// Which method to apply when synthesising missing values.
    ///
    /// Default: `LinearInterpolation` (auto-falls back to `LastValueCarryForward`
    /// when surrounding data is absent).
    pub method: SubstituteMethod,

    /// Reference period intervals used by [`SubstituteMethod::PriorPeriodAverage`].
    ///
    /// Typically the same calendar week from 7 days prior.
    /// For each gap at time `t`, the algorithm finds all intervals in this slice
    /// whose time-of-day matches `t` (hour, minute, second) and averages their
    /// `value_kwh`. Falls back to `LastValueCarryForward` when none is found.
    pub prior_period_intervals: Vec<MeterInterval>,

    /// Maximum consecutive missing intervals for which linear interpolation is used.
    ///
    /// Default: `3`. Gaps of ≤ this length always use linear interpolation.
    /// Gaps longer than this threshold use the `method` field.
    pub short_gap_threshold: usize,
}

impl Default for FillGapsConfig {
    fn default() -> Self {
        Self {
            method: SubstituteMethod::default(),
            prior_period_intervals: Vec::new(),
            short_gap_threshold: 3,
        }
    }
}

impl FillGapsConfig {
    /// Config for `PriorPeriodAverage` with the given reference data.
    #[must_use]
    pub fn prior_period(prior_period_intervals: Vec<MeterInterval>) -> Self {
        Self {
            method: SubstituteMethod::PriorPeriodAverage,
            prior_period_intervals,
            short_gap_threshold: 3,
        }
    }

    /// Config for `ZeroFill` (affirmatively documented zero delivery).
    #[must_use]
    pub fn zero_fill() -> Self {
        Self {
            method: SubstituteMethod::ZeroFill,
            prior_period_intervals: Vec::new(),
            short_gap_threshold: 0,
        }
    }
}

// ── fill_gaps ─────────────────────────────────────────────────────────────────

/// §17 MessZV — Fill gaps with a [`FillGapsConfig`] specifying the substitute method.
///
/// Provides full control over gap-filling strategy — use this when the MSB
/// has determined the appropriate method:
/// - [`SubstituteMethod::PriorPeriodAverage`] — prior-week same-slot values (set `prior_period_intervals`)
/// - [`SubstituteMethod::ZeroFill`] — documented plant shutdown
/// - [`SubstituteMethod::LastValueCarryForward`] — explicit carry-forward
///
/// Short gaps (≤ `config.short_gap_threshold` intervals) always use linear
/// interpolation regardless of `config.method`, as this produces the most
/// accurate substitute for brief data outages.
#[must_use]
pub fn fill_gaps_with_config(
    intervals: &[MeterInterval],
    expected_interval_secs: i64,
    from: OffsetDateTime,
    to: OffsetDateTime,
    config: &FillGapsConfig,
) -> Vec<MeterInterval> {
    use time::Duration;

    if expected_interval_secs <= 0 {
        return intervals.to_vec();
    }

    let mut sorted = intervals.to_vec();
    sorted.sort_by_key(|iv| iv.from);

    use std::collections::HashMap;
    let existing: HashMap<i64, &MeterInterval> = sorted
        .iter()
        .map(|iv| (iv.from.unix_timestamp(), iv))
        .collect();

    // Pre-sort prior_period for quick lookup
    let mut prior_sorted = config.prior_period_intervals.clone();
    prior_sorted.sort_by_key(|iv| iv.from);

    let mut result: Vec<MeterInterval> = Vec::new();
    let mut cursor = from;
    // Length of the gap currently being traversed, measured once at its first
    // missing interval. Re-measuring from the moving cursor shrinks the count as
    // the gap is filled, so the last `short_gap_threshold` intervals of every
    // long gap would fall back to interpolation no matter which method was
    // configured.
    let mut gap_len: usize = 0;

    while cursor < to {
        let next = cursor + Duration::seconds(expected_interval_secs);
        let ts = cursor.unix_timestamp();

        if let Some(&iv) = existing.get(&ts) {
            result.push(iv.clone());
            gap_len = 0;
        } else {
            if gap_len == 0 {
                gap_len = count_consecutive_gaps(&sorted, cursor, expected_interval_secs);
            }
            // A short gap is interpolated regardless of the configured method:
            // §17 Abs. 2 MessZV reference-period substitution is for outages long
            // enough that the neighbouring values say nothing useful.
            let effective_method = if gap_len <= config.short_gap_threshold && gap_len > 0 {
                SubstituteMethod::LinearInterpolation
            } else {
                config.method
            };

            let sub_value = synthesise_value(
                &sorted,
                cursor,
                next,
                &result,
                effective_method,
                &prior_sorted,
            );
            result.push(MeterInterval {
                from: cursor,
                to: next,
                value_kwh: sub_value,
                quality: QualityFlag::Substituted,
                obis_code: sorted.first().and_then(|iv| iv.obis_code.clone()),
            });
        }
        cursor = next;
    }

    result
}

/// Count how many consecutive intervals starting at `gap_start` are missing.
fn count_consecutive_gaps(
    sorted: &[MeterInterval],
    gap_start: OffsetDateTime,
    interval_secs: i64,
) -> usize {
    use time::Duration;
    let existing_starts: std::collections::HashSet<i64> =
        sorted.iter().map(|iv| iv.from.unix_timestamp()).collect();
    let mut count = 0;
    let mut cursor = gap_start;
    while !existing_starts.contains(&cursor.unix_timestamp()) {
        count += 1;
        cursor += Duration::seconds(interval_secs);
        if count > 100 {
            break; // safety cap
        }
    }
    count
}

/// §17 MessZV — Fill gaps in a meter interval series with substitute values.
///
/// Identifies gaps (missing expected intervals) and fills them using the
/// best available method:
///
/// 1. **Short gaps** (1–3 intervals): linear interpolation
/// 2. **Longer gaps**: last-value carry-forward (conservative; MSB may override)
///
/// Use [`fill_gaps_with_config`] to specify an explicit method such as
/// [`SubstituteMethod::PriorPeriodAverage`] per §17 Abs. 2 MessZV.
///
/// Only gaps within `[from, to)` are filled. Leading and trailing gaps are
/// not synthesised — they indicate metering system issues requiring manual review.
///
/// Filled intervals carry `quality = QualityFlag::Substituted` (billable per §17 MessZV Abs. 1).
///
/// ## Parameters
///
/// - `intervals` — meter readings, need not be sorted
/// - `expected_interval_secs` — the regular interval duration (e.g. `900` for 15-min)
/// - `from` / `to` — the metering period boundaries
///
/// ## Example
///
/// ```rust
/// use metering::{MeterInterval, QualityFlag, fill_gaps};
/// use rust_decimal::Decimal;
/// use time::macros::datetime;
///
/// // Two intervals with a gap at 00:15 UTC
/// let intervals = vec![
///     MeterInterval {
///         from:      datetime!(2026-01-01 0:00 UTC),
///         to:        datetime!(2026-01-01 0:15 UTC),
///         value_kwh: Decimal::from_str_exact("2.0").unwrap(),
///         quality:   QualityFlag::Measured,
///         obis_code: None,
///     },
///     MeterInterval {
///         from:      datetime!(2026-01-01 0:30 UTC),
///         to:        datetime!(2026-01-01 0:45 UTC),
///         value_kwh: Decimal::from_str_exact("2.4").unwrap(),
///         quality:   QualityFlag::Measured,
///         obis_code: None,
///     },
/// ];
///
/// let filled = fill_gaps(
///     &intervals,
///     900,
///     datetime!(2026-01-01 0:00 UTC),
///     datetime!(2026-01-01 0:45 UTC),
/// );
/// // Now has 3 intervals; the gap at 00:15 is filled with Substituted quality
/// assert_eq!(filled.len(), 3);
/// assert_eq!(filled[1].quality, QualityFlag::Substituted);
/// ```
#[must_use]
pub fn fill_gaps(
    intervals: &[MeterInterval],
    expected_interval_secs: i64,
    from: OffsetDateTime,
    to: OffsetDateTime,
) -> Vec<MeterInterval> {
    fill_gaps_with_config(
        intervals,
        expected_interval_secs,
        from,
        to,
        &FillGapsConfig::default(),
    )
}

/// Synthesise a substitute value for a missing interval.
fn synthesise_value(
    all_sorted: &[MeterInterval],
    from: OffsetDateTime,
    _to: OffsetDateTime,
    prior_filled: &[MeterInterval],
    method: SubstituteMethod,
    prior_period: &[MeterInterval],
) -> Decimal {
    match method {
        SubstituteMethod::ZeroFill => Decimal::ZERO,

        SubstituteMethod::PriorPeriodAverage => {
            // §17 Abs. 2 MessZV: the same slot of the prior reference period,
            // which is the calendar week immediately before the gap.
            //
            // The window is applied here rather than trusted from the caller.
            // Averaging whatever was supplied yields a multi-week average that
            // is not the value the regulation names, and a caller passing a
            // longer history has no way to see that it happened.
            let reference_start = from - Duration::days(REFERENCE_PERIOD_DAYS);
            let in_reference_period =
                |iv: &MeterInterval| iv.from >= reference_start && iv.from < from;

            // Keyed on (weekday, hour, minute) in German local time. Matching on
            // time-of-day alone averages a Sunday gap over five working days,
            // which overstates an industrial load; matching in UTC shifts every
            // slot by an hour across the DST boundary. This mirrors
            // `forecast::prior_period_substitutes`.
            use time_tz::{OffsetDateTimeExt, timezones};
            let local_target = from.to_timezone(timezones::db::europe::BERLIN);
            let target_slot = (
                local_target.weekday(),
                local_target.hour(),
                local_target.minute(),
            );
            let matches: Vec<Decimal> = prior_period
                .iter()
                .filter(|iv| {
                    if !iv.quality.is_billable() || !in_reference_period(iv) {
                        return false;
                    }
                    let local = iv.from.to_timezone(timezones::db::europe::BERLIN);
                    (local.weekday(), local.hour(), local.minute()) == target_slot
                })
                .map(|iv| iv.value_kwh)
                .collect();

            if !matches.is_empty() {
                let sum: Decimal = matches.iter().sum();
                return sum / Decimal::from(matches.len() as u32);
            }
            // Fallback: carry forward last known value
            prior_filled
                .iter()
                .rev()
                .find(|iv| iv.quality.is_billable())
                .map_or(Decimal::ZERO, |iv| iv.value_kwh)
        }

        SubstituteMethod::LastValueCarryForward => prior_filled
            .iter()
            .rev()
            .find(|iv| iv.quality.is_billable())
            .or_else(|| {
                // carry back (gap at start)
                all_sorted
                    .iter()
                    .find(|iv| iv.from > from && iv.quality.is_billable())
            })
            .map_or(Decimal::ZERO, |iv| iv.value_kwh),

        SubstituteMethod::LinearInterpolation => {
            let preceding = prior_filled
                .iter()
                .rev()
                .find(|iv| iv.quality.is_billable());
            let following = all_sorted
                .iter()
                .find(|iv| iv.from > from && iv.quality.is_billable());

            match (preceding, following) {
                (Some(p), Some(f)) => {
                    let total_secs = (f.from - p.from).whole_seconds();
                    let elapsed_secs = (from - p.from).whole_seconds();
                    if total_secs > 0 {
                        let t = Decimal::from(elapsed_secs) / Decimal::from(total_secs);
                        p.value_kwh + t * (f.value_kwh - p.value_kwh)
                    } else {
                        p.value_kwh
                    }
                }
                (Some(p), None) => p.value_kwh,
                (None, Some(f)) => f.value_kwh,
                (None, None) => Decimal::ZERO,
            }
        }
    }
}

/// Linear interpolation between two `MeterInterval` values.
///
/// Fills the gap between `before` and `after` with a single substitute interval.
/// The value is linearly interpolated based on time position.
///
/// # Returns
///
/// A synthesised `MeterInterval` with `quality = Substituted`.
#[must_use]
pub fn linear_interpolation(before: &MeterInterval, after: &MeterInterval) -> MeterInterval {
    // Time fraction: how far into the gap is the midpoint?
    let total_secs = (after.from - before.to).whole_seconds() as f64;
    let mid_secs = total_secs / 2.0;
    let t = if total_secs > 0.0 {
        mid_secs / total_secs
    } else {
        0.5
    };
    let t_dec = Decimal::try_from(t).unwrap_or_else(|_| Decimal::new(5, 1));
    let value = before.value_kwh + t_dec * (after.value_kwh - before.value_kwh);

    MeterInterval {
        from: before.to,
        to: after.from,
        value_kwh: value,
        quality: QualityFlag::Substituted,
        obis_code: before.obis_code.clone(),
    }
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use time::macros::datetime;

    fn iv(from_h: i64, from_m: i64, kwh: f64) -> MeterInterval {
        let base = datetime!(2026-01-01 0:00 UTC);
        let start = base + time::Duration::hours(from_h) + time::Duration::minutes(from_m);
        MeterInterval {
            from: start,
            to: start + time::Duration::minutes(15),
            value_kwh: Decimal::try_from(kwh).unwrap(),
            quality: QualityFlag::Measured,
            obis_code: None,
        }
    }

    #[test]
    fn fill_gaps_single_gap() {
        // 00:00 ✓, 00:15 MISSING, 00:30 ✓
        let intervals = vec![iv(0, 0, 2.0), iv(0, 30, 2.4)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:45 UTC);
        let filled = fill_gaps(&intervals, 900, from, to);

        assert_eq!(filled.len(), 3, "should have 3 intervals after gap fill");
        assert_eq!(filled[0].quality, QualityFlag::Measured);
        assert_eq!(
            filled[1].quality,
            QualityFlag::Substituted,
            "gap must be Substituted"
        );
        assert_eq!(filled[2].quality, QualityFlag::Measured);
        // Linear interpolation: (2.0 + 2.4) / 2 = 2.2 kWh
        assert!(
            filled[1].value_kwh > dec!(1.9) && filled[1].value_kwh < dec!(2.5),
            "interpolated value {} out of range",
            filled[1].value_kwh
        );
    }

    #[test]
    fn fill_gaps_no_gaps() {
        let intervals = vec![iv(0, 0, 2.0), iv(0, 15, 2.1), iv(0, 30, 2.2)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:45 UTC);
        let filled = fill_gaps(&intervals, 900, from, to);
        assert_eq!(filled.len(), 3);
        assert!(filled.iter().all(|iv| iv.quality == QualityFlag::Measured));
    }

    #[test]
    fn fill_gaps_carry_forward_at_end() {
        // Only one interval, gap at the end
        let intervals = vec![iv(0, 0, 3.0)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:30 UTC);
        let filled = fill_gaps(&intervals, 900, from, to);
        assert_eq!(filled.len(), 2);
        assert_eq!(filled[0].quality, QualityFlag::Measured);
        assert_eq!(filled[1].quality, QualityFlag::Substituted);
        assert_eq!(
            filled[1].value_kwh,
            dec!(3.0),
            "carry-forward from last known"
        );
    }

    #[test]
    fn linear_interpolation_midpoint() {
        let before = iv(0, 0, 2.0);
        let mut after = iv(0, 30, 4.0);
        after.from = before.to + time::Duration::minutes(15); // 00:30 gap
        after.to = after.from + time::Duration::minutes(15);
        let sub = linear_interpolation(&before, &after);
        assert_eq!(sub.quality, QualityFlag::Substituted);
        // Midpoint of [2.0, 4.0] = 3.0
        assert!(
            sub.value_kwh > dec!(2.5) && sub.value_kwh < dec!(3.5),
            "interpolated value {}",
            sub.value_kwh
        );
    }

    #[test]
    fn fill_gaps_multiple_gaps() {
        // 00:00 ✓, 00:15 MISSING, 00:30 MISSING, 00:45 ✓
        let intervals = vec![iv(0, 0, 2.0), iv(0, 45, 2.6)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 1:00 UTC);
        let filled = fill_gaps(&intervals, 900, from, to);
        assert_eq!(filled.len(), 4);
        assert_eq!(filled[1].quality, QualityFlag::Substituted);
        assert_eq!(filled[2].quality, QualityFlag::Substituted);
    }

    // ── fill_gaps_with_config tests ────────────────────────────────────────────

    /// §17 Abs. 2 MessZV — PriorPeriodAverage uses the same time slot from prior week.
    #[test]
    fn fill_gaps_prior_period_average_uses_matching_slot() {
        // Prior period: 00:15 slot had 3.0 kWh last week
        let prior_week_base = datetime!(2025-12-25 0:00 UTC); // 7 days earlier
        let prior_reading = MeterInterval {
            from: prior_week_base + time::Duration::minutes(15),
            to: prior_week_base + time::Duration::minutes(30),
            value_kwh: dec!(3.0),
            quality: QualityFlag::Measured,
            obis_code: None,
        };

        // Current week: 00:00 ✓, 00:15 MISSING, 00:30 ✓
        let intervals = vec![iv(0, 0, 2.0), iv(0, 30, 4.0)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:45 UTC);

        let config = FillGapsConfig::prior_period(vec![prior_reading]);
        let filled = fill_gaps_with_config(&intervals, 900, from, to, &config);

        assert_eq!(filled.len(), 3);
        assert_eq!(filled[1].quality, QualityFlag::Substituted);
        // Gap at 00:15 should use prior-period 00:15 value = 3.0
        assert_eq!(
            filled[1].value_kwh,
            dec!(3.0),
            "PriorPeriodAverage must use prior-week same-slot value"
        );
    }

    /// PriorPeriodAverage falls back to carry-forward when no prior slot matches.
    #[test]
    fn fill_gaps_prior_period_average_fallback_to_carry_forward() {
        // Prior period has no data at 00:15 (different time slots only)
        let prior_reading = MeterInterval {
            from: datetime!(2025-12-25 1:00 UTC), // 01:00 slot, not 00:15
            to: datetime!(2025-12-25 1:15 UTC),
            value_kwh: dec!(5.0),
            quality: QualityFlag::Measured,
            obis_code: None,
        };

        let intervals = vec![iv(0, 0, 2.5), iv(0, 30, 4.0)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:45 UTC);

        // short_gap_threshold=0 disables the short-gap linear override so
        // PriorPeriodAverage (and its carry-forward fallback) applies to all gaps.
        let config = FillGapsConfig {
            method: SubstituteMethod::PriorPeriodAverage,
            prior_period_intervals: vec![prior_reading],
            short_gap_threshold: 0,
        };
        let filled = fill_gaps_with_config(&intervals, 900, from, to, &config);

        assert_eq!(filled.len(), 3);
        assert_eq!(filled[1].quality, QualityFlag::Substituted);
        // No prior-period match → carry forward from 00:00 value = 2.5
        assert_eq!(
            filled[1].value_kwh,
            dec!(2.5),
            "fallback must carry forward last known value"
        );
    }

    /// ZeroFill produces confirmed-zero substitute values.
    #[test]
    fn fill_gaps_zero_fill_config() {
        let intervals = vec![iv(0, 0, 2.0), iv(0, 30, 2.0)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:45 UTC);

        let filled = fill_gaps_with_config(&intervals, 900, from, to, &FillGapsConfig::zero_fill());
        assert_eq!(filled.len(), 3);
        assert_eq!(filled[1].quality, QualityFlag::Substituted);
        assert_eq!(filled[1].value_kwh, dec!(0), "ZeroFill must produce 0");
    }

    /// Short gaps always use linear interpolation regardless of configured method.
    #[test]
    fn fill_gaps_short_gap_always_linear_even_with_zero_fill_method() {
        // short_gap_threshold = 3 by default; gap of 1 = always linear
        let intervals = vec![iv(0, 0, 2.0), iv(0, 30, 4.0)];
        let from = datetime!(2026-01-01 0:00 UTC);
        let to = datetime!(2026-01-01 0:45 UTC);

        // Despite ZeroFill method, a gap of 1 interval ≤ threshold → linear
        let config = FillGapsConfig {
            method: SubstituteMethod::ZeroFill,
            prior_period_intervals: vec![],
            short_gap_threshold: 3,
        };
        let filled = fill_gaps_with_config(&intervals, 900, from, to, &config);
        assert_eq!(filled.len(), 3);
        // Linear interpolation: (2.0 + 4.0) / 2 ≈ 3.0 (not 0)
        assert!(
            filled[1].value_kwh > dec!(1.0),
            "short gap must use linear interpolation, not ZeroFill"
        );
    }
    #[test]
    fn a_long_gap_keeps_its_method_all_the_way_to_the_end() {
        // The gap length was re-measured from the moving cursor, so the count
        // shrank as the gap filled and the last `short_gap_threshold` intervals
        // silently reverted to interpolation.
        use time::macros::datetime;
        let existing = vec![
            MeterInterval {
                from: datetime!(2026-03-02 00:00 UTC),
                to: datetime!(2026-03-02 00:15 UTC),
                value_kwh: dec!(10),
                quality: QualityFlag::Measured,
                obis_code: None,
            },
            // 00:15 .. 02:00 missing — seven quarter-hours
            MeterInterval {
                from: datetime!(2026-03-02 02:00 UTC),
                to: datetime!(2026-03-02 02:15 UTC),
                value_kwh: dec!(20),
                quality: QualityFlag::Measured,
                obis_code: None,
            },
        ];

        let filled = fill_gaps_with_config(
            &existing,
            900,
            datetime!(2026-03-02 00:00 UTC),
            datetime!(2026-03-02 02:15 UTC),
            &FillGapsConfig {
                method: SubstituteMethod::ZeroFill,
                short_gap_threshold: 2,
                ..Default::default()
            },
        );

        let substituted: Vec<_> = filled
            .iter()
            .filter(|iv| iv.quality == QualityFlag::Substituted)
            .collect();
        assert_eq!(substituted.len(), 7, "seven quarter-hours are missing");
        for iv in &substituted {
            assert_eq!(
                iv.value_kwh,
                dec!(0),
                "every interval of a 7-slot gap must use the configured ZeroFill, \
                 including the last two — got {} at {}",
                iv.value_kwh,
                iv.from
            );
        }
    }

    #[test]
    fn prior_period_average_distinguishes_weekdays_from_weekends() {
        // Matching on time-of-day alone averaged a Sunday gap over the working
        // week, overstating an industrial load.
        use time::macros::datetime;
        // 2026-03-01 is a Sunday; 2026-02-23..27 are Mon–Fri.
        let mut prior = Vec::new();
        for day in 23..=27 {
            prior.push(MeterInterval {
                from: datetime!(2026-02-01 08:00 UTC).replace_day(day).unwrap(),
                to: datetime!(2026-02-01 08:15 UTC).replace_day(day).unwrap(),
                value_kwh: dec!(100), // working-day load
                quality: QualityFlag::Measured,
                obis_code: None,
            });
        }
        // The previous Sunday at the same slot.
        prior.push(MeterInterval {
            from: datetime!(2026-02-22 08:00 UTC),
            to: datetime!(2026-02-22 08:15 UTC),
            value_kwh: dec!(4), // weekend idle
            quality: QualityFlag::Measured,
            obis_code: None,
        });

        let filled = fill_gaps_with_config(
            &[],
            900,
            datetime!(2026-03-01 08:00 UTC),
            datetime!(2026-03-01 08:15 UTC),
            &FillGapsConfig {
                method: SubstituteMethod::PriorPeriodAverage,
                short_gap_threshold: 0,
                prior_period_intervals: prior,
            },
        );

        let sunday = filled
            .iter()
            .find(|iv| iv.from == datetime!(2026-03-01 08:00 UTC))
            .expect("the Sunday slot must be filled");
        assert_eq!(
            sunday.value_kwh,
            dec!(4),
            "a Sunday gap must take the prior Sunday's value, not the working-week average"
        );
    }
    #[test]
    fn only_the_preceding_week_feeds_the_prior_period_average() {
        // The window used to be a `debug_assert` on the caller's slice length,
        // which compiles out in release: a caller passing a longer history got a
        // multi-week average with nothing to indicate it.
        use time::macros::datetime;
        let gap = datetime!(2026-03-09 08:00 UTC); // Monday

        let prior = vec![
            // Within the reference week (Monday 2026-03-02).
            MeterInterval {
                from: datetime!(2026-03-02 08:00 UTC),
                to: datetime!(2026-03-02 08:15 UTC),
                value_kwh: dec!(10),
                quality: QualityFlag::Measured,
                obis_code: None,
            },
            // Same weekday and slot, but three weeks earlier — outside it.
            MeterInterval {
                from: datetime!(2026-02-16 08:00 UTC),
                to: datetime!(2026-02-16 08:15 UTC),
                value_kwh: dec!(1000),
                quality: QualityFlag::Measured,
                obis_code: None,
            },
        ];

        let filled = fill_gaps_with_config(
            &[],
            900,
            gap,
            gap + Duration::minutes(15),
            &FillGapsConfig {
                method: SubstituteMethod::PriorPeriodAverage,
                short_gap_threshold: 0,
                prior_period_intervals: prior,
            },
        );

        assert_eq!(
            filled[0].value_kwh,
            dec!(10),
            "only the preceding week counts; averaging in the older week would give 505"
        );
    }
}