ocpi_tariffs/

price.rs

//! Price a CDR using a tariff and compare the prices embedded in the CDR with the prices computed here.

mod de;
mod tariff;
mod v211;
mod v221;

use std::{borrow::Cow, fmt, ops::Range};

use chrono::{DateTime, Datelike, TimeDelta, Utc};
use chrono_tz::Tz;
use rust_decimal::Decimal;
use tracing::{debug, instrument, trace};

use crate::{
    duration::{self, Hms},
    warning, Ampere, Cost, DisplayOption, Kw, Kwh, Money, ParseError, Price, SaturatingAdd as _,
    SaturatingSub as _, UnexpectedFields, VatApplicable, Version, Versioned as _,
};

use tariff::Tariff;

/// An normalized/expanded form of a charging period to make the pricing calculation simpler.
///
/// The simplicity comes through avoiding having to look up the next period to figure out the end
/// of the current period.
#[derive(Debug)]
struct PeriodNormalized {
    /// The set of quantities consumed across the duration of the `Period`.
    consumed: Consumed,

    /// A snapshot of the values of various quantities at the start of the charge period.
    start_snapshot: TotalsSnapshot,

    /// A snapshot of the values of various quantities at the end of the charge period.
    end_snapshot: TotalsSnapshot,
}

/// The set of quantities consumed across the duration of the `Period`.
#[derive(Clone, Debug)]
#[cfg_attr(test, derive(Default))]
pub(crate) struct Consumed {
    /// The peak current during this period.
    current_max: Option<Ampere>,

    /// The lowest current during this period.
    current_min: Option<Ampere>,

    /// The energy consumed in this period.
    energy: Option<Kwh>,

    /// The maximum power reached during this period.
    power_max: Option<Kw>,

    /// The minimum power reached during this period.
    power_min: Option<Kw>,

    /// The charging time consumed in this period.
    duration_charging: Option<TimeDelta>,

    /// The parking time consumed in this period.
    duration_parking: Option<TimeDelta>,
}

/// A snapshot of the values of various quantities at the start and end of the charge period.
#[derive(Clone, Debug)]
struct TotalsSnapshot {
    /// The `DateTime` this snapshot of total quantities was taken.
    date_time: DateTime<Utc>,

    /// The total energy consumed during a charging period.
    energy: Kwh,

    /// The local timeszone.
    local_timezone: Tz,

    /// The total charging duration during a charging period.
    duration_charging: TimeDelta,

    /// The total period duration during a charging period.
    duration_total: TimeDelta,
}

impl TotalsSnapshot {
    /// Create a snapshot where all quantities are zero.
    fn zero(date_time: DateTime<Utc>, local_timezone: Tz) -> Self {
        Self {
            date_time,
            energy: Kwh::zero(),
            local_timezone,
            duration_charging: TimeDelta::zero(),
            duration_total: TimeDelta::zero(),
        }
    }

    /// Create a new snapshot based on the the current snapshot with consumed quantities added.
    fn next(&self, consumed: &Consumed, date_time: DateTime<Utc>) -> Self {
        let duration = date_time.signed_duration_since(self.date_time);

        let mut next = Self {
            date_time,
            energy: self.energy,
            local_timezone: self.local_timezone,
            duration_charging: self.duration_charging,
            duration_total: self
                .duration_total
                .checked_add(&duration)
                .unwrap_or(TimeDelta::MAX),
        };

        if let Some(duration) = consumed.duration_charging {
            next.duration_charging = next
                .duration_charging
                .checked_add(&duration)
                .unwrap_or(TimeDelta::MAX);
        }

        if let Some(energy) = consumed.energy {
            next.energy = next.energy.saturating_add(energy);
        }

        next
    }

    /// Return the local time of this snapshot.
    fn local_time(&self) -> chrono::NaiveTime {
        self.date_time.with_timezone(&self.local_timezone).time()
    }

    /// Return the local date of this snapshot.
    fn local_date(&self) -> chrono::NaiveDate {
        self.date_time
            .with_timezone(&self.local_timezone)
            .date_naive()
    }

    /// Return the local `Weekday` of this snapshot.
    fn local_weekday(&self) -> chrono::Weekday {
        self.date_time.with_timezone(&self.local_timezone).weekday()
    }
}

/// Structure containing the charge session priced according to the specified tariff.
/// The fields prefixed `total` correspond to CDR fields with the same name.
#[derive(Debug)]
pub struct Report {
    /// A set of warnings generated while trying to price the CDR.
    pub warnings: Vec<WarningReport>,

    /// Charge session details per period.
    pub periods: Vec<PeriodReport>,

    /// The id and index of the tariff that was used for pricing.
    pub tariff: TariffReport,

    /// A list of reports for each tariff found in the CDR or supplied to the [`cdr::price`](crate::cdr::price) function.
    ///
    /// The order of the `tariff::Report`s are the same as the order in which they are given.
    pub tariff_reports: Vec<TariffReport>,

    /// Time-zone that was either specified or detected.
    pub timezone: String,

    /* Billed Quantities */
    /// The total charging time after applying step-size.
    pub billed_charging_time: Option<TimeDelta>,

    /// The total energy after applying step-size.
    pub billed_energy: Option<Kwh>,

    /// The total parking time after applying step-size
    pub billed_parking_time: Option<TimeDelta>,

    /* Totals */
    /// Total duration of the charging session (excluding not charging), in hours.
    ///
    /// This is a total that has no direct source field in the `CDR` as it is calculated in the
    /// [`cdr::price`](crate::cdr::price) function.
    pub total_charging_time: Option<TimeDelta>,

    /// Total energy charged, in kWh.
    pub total_energy: Total<Kwh, Option<Kwh>>,

    /// Total duration of the charging session where the EV was not charging (no energy was transferred between EVSE and EV).
    pub total_parking_time: Total<Option<TimeDelta>>,

    /// Total duration of the charging session (including the duration of charging and not charging).
    pub total_time: Total<TimeDelta>,

    /* Costs */
    /// Total sum of all the costs of this transaction in the specified currency.
    pub total_cost: Total<Price, Option<Price>>,

    /// Total sum of all the cost of all the energy used, in the specified currency.
    pub total_energy_cost: Total<Option<Price>>,

    /// Total sum of all the fixed costs in the specified currency, except fixed price components of parking and reservation. The cost not depending on amount of time/energy used etc. Can contain costs like a start tariff.
    pub total_fixed_cost: Total<Option<Price>>,

    /// Total sum of all the cost related to parking of this transaction, including fixed price components, in the specified currency.
    pub total_parking_cost: Total<Option<Price>>,

    /// Total sum of all the cost related to a reservation of a Charge Point, including fixed price components, in the specified currency.
    pub total_reservation_cost: Total<Option<Price>>,

    /// Total sum of all the cost related to duration of charging during this transaction, in the specified currency.
    pub total_time_cost: Total<Option<Price>>,
}

/// A report of a Warning that occurred.
#[derive(Debug)]
pub struct WarningReport {
    /// The kind of warning that occurred.
    pub kind: WarningKind,
}

/// The warnings that happen when pricing a CDR.
#[derive(Debug)]
pub enum WarningKind {
    /// The `start_date_time` of at least one of the `charging_periods` is outside of the
    /// CDR's `start_date_time`-`end_date_time` range.
    PeriodsOutsideStartEndDateTime {
        cdr_range: Range<DateTime<Utc>>,
        period_range: PeriodRange,
    },
}

impl fmt::Display for WarningKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::PeriodsOutsideStartEndDateTime {
                cdr_range,
                period_range,
            } => {
                write!(f, "The CDR's charging period time range is not contained within the `start_date_time` and `end_date_time`; cdr_range: {}-{}, period_range: {}", cdr_range.start, cdr_range.end, period_range)
            }
        }
    }
}

impl warning::Kind for WarningKind {
    fn id(&self) -> Cow<'static, str> {
        match self {
            WarningKind::PeriodsOutsideStartEndDateTime { .. } => {
                "periods_outside_start_end_date_time".into()
            }
        }
    }
}

/// A report of parsing and using the referenced tariff to price a CDR.
#[derive(Debug)]
pub struct TariffReport {
    /// The id of the tariff.
    pub origin: TariffOrigin,

    /// Set of unexpected fields encountered while parsing the tariff.
    pub unexpected_fields: UnexpectedFields,
}

/// The origin data for a tariff.
#[derive(Clone, Debug)]
pub struct TariffOrigin {
    /// The index of the tariff in the CDR JSON or in the list of override tariffs.
    pub index: usize,

    /// The value of the `id` field in the tariff JSON.
    pub id: String,
}

/// A CDR charge period in a normalized form ready for pricing.
#[derive(Debug)]
pub(crate) struct Period {
    /// The start time of this period.
    pub start_date_time: DateTime<Utc>,

    /// The quatities consumed during this period.
    pub consumed: Consumed,
}

/// A structure containing a report for each dimension.
#[derive(Debug)]
pub struct Dimensions {
    /// Energy consumed.
    pub energy: Dimension<Kwh>,

    /// Flat fee without unit for `step_size`.
    pub flat: Dimension<()>,

    /// Duration of time charging.
    pub duration_charging: Dimension<TimeDelta>,

    /// Duration of time not charging.
    pub duration_parking: Dimension<TimeDelta>,
}

impl Dimensions {
    fn new(components: ComponentSet, consumed: &Consumed) -> Self {
        Self {
            energy: Dimension::new(components.energy, consumed.energy),
            flat: Dimension::new(components.flat, Some(())),
            duration_charging: Dimension::new(
                components.duration_charging,
                consumed.duration_charging,
            ),
            duration_parking: Dimension::new(
                components.duration_parking,
                consumed.duration_parking,
            ),
        }
    }
}

#[derive(Debug)]
/// A report for a single dimension during a single period.
pub struct Dimension<V> {
    /// The price component that was active during this period for this dimension.
    /// It could be that no price component was active during this period for this dimension in
    /// which case `price` is `None`.
    pub price: Option<Component>,

    /// The volume of this dimension during this period, as received in the provided charge detail record.
    /// It could be that no volume was provided during this period for this dimension in which case
    /// the `volume` is `None`.
    pub volume: Option<V>,

    /// This field contains the optional value of `volume` after a potential step size was applied.
    /// Step size is applied over the total volume during the whole session of a dimension. But the
    /// resulting additional volume should be billed according to the price component in this
    /// period.
    ///
    /// If no step-size was applied for this period, the volume is exactly equal to the `volume`
    /// field.
    pub billed_volume: Option<V>,
}

impl<V> Dimension<V>
where
    V: Copy,
{
    fn new(price_component: Option<Component>, volume: Option<V>) -> Self {
        Self {
            price: price_component,
            volume,
            billed_volume: volume,
        }
    }
}

impl<V: Cost> Dimension<V> {
    /// The total cost of this dimension during a period.
    pub fn cost(&self) -> Option<Price> {
        if let (Some(volume), Some(price)) = (&self.billed_volume, &self.price) {
            let excl_vat = volume.cost(price.price);

            let incl_vat = match price.vat {
                VatApplicable::Applicable(vat) => Some(excl_vat.apply_vat(vat)),
                VatApplicable::Inapplicable => Some(excl_vat),
                VatApplicable::Unknown => None,
            };

            Some(Price { excl_vat, incl_vat })
        } else {
            None
        }
    }
}

/// A set of price `Component`s, one for each dimension.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#142-pricecomponent-class>
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#145-tariffdimensiontype-enum>
#[derive(Debug)]
pub struct ComponentSet {
    /// Energy consumed.
    pub energy: Option<Component>,

    /// Flat fee without unit for `step_size`.
    pub flat: Option<Component>,

    /// Duration of time charging.
    pub duration_charging: Option<Component>,

    /// Duration of time not charging.
    pub duration_parking: Option<Component>,
}

impl ComponentSet {
    fn new() -> Self {
        Self {
            energy: None,
            flat: None,
            duration_charging: None,
            duration_parking: None,
        }
    }

    /// Returns true if all components are `Some`.
    fn has_all_components(&self) -> bool {
        let Self {
            energy,
            flat,
            duration_charging,
            duration_parking,
        } = self;

        flat.is_some()
            && energy.is_some()
            && duration_parking.is_some()
            && duration_charging.is_some()
    }
}

/// A Price Component describes how a certain amount of a certain dimension being consumed
/// translates into an amount of money owed.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#142-pricecomponent-class>
#[derive(Clone, Debug)]
pub struct Component {
    /// The index of the tariff this `Component` lives in.
    pub tariff_element_index: usize,

    /// Price per unit (excl. VAT) for this dimension.
    pub price: Money,

    /// Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable.
    /// Not providing a VAT is different from 0% VAT, which would be a value of 0.0 here.
    pub vat: VatApplicable,

    /// Minimum amount to be billed. That is, the dimension will be billed in this `step_size` blocks.
    /// Consumed amounts are rounded up to the smallest multiple of `step_size` that is greater than
    /// the consumed amount.
    ///
    /// For example: if type is TIME and `step_size` has a value of 300, then time will be billed in
    /// blocks of 5 minutes. If 6 minutes were consumed, 10 minutes (2 blocks of `step_size`) will
    /// be billed.
    pub step_size: u64,
}

impl Component {
    fn new(component: &v221::tariff::PriceComponent, tariff_element_index: usize) -> Self {
        let v221::tariff::PriceComponent {
            price,
            vat,
            step_size,
            dimension_type: _,
        } = component;

        Self {
            tariff_element_index,
            price: *price,
            vat: *vat,
            step_size: *step_size,
        }
    }
}

/// A related source and calculated pair of total amounts.
///
/// This is used to express the source and calculated amounts for the total fields of a `CDR`.
///
/// - `total_cost`
/// - `total_fixed_cost`
/// - `total_energy`
/// - `total_energy_cost`
/// - `total_time`
/// - `total_time_cost`
/// - `total_parking_time`
/// - `total_parking_cost`
/// - `total_reservation_cost`
#[derive(Debug)]
pub struct Total<TCdr, TCalc = TCdr> {
    /// The source value from the `CDR`.
    pub cdr: TCdr,

    /// The value calculated by the [`cdr::price`](crate::cdr::price) function.
    pub calculated: TCalc,
}

/// Possible errors when pricing a charge session.
#[derive(Debug)]
pub enum Error {
    /// An error occurred while deserializing a `CDR` or tariff.
    Deserialize(ParseError),

    /// The given dimension should have a volume
    DimensionShouldHaveVolume { dimension_name: &'static str },

    /// A numeric overflow occurred while creating a duration.
    DurationOverflow,

    /// An internal programming error.
    Internal(Box<dyn std::error::Error + Send + Sync + 'static>),

    /// No valid tariff has been found in the list of provided tariffs.
    /// The tariff list can be sourced from either the tariffs contained in the CDR or from a list
    /// provided by the caller.
    ///
    /// A valid tariff must have a start date-time before the start of the session and a end
    /// date-time after the start of the session.
    ///
    /// If the CDR does not contain any tariffs consider providing a them using [`TariffSource`]
    /// when calling [`cdr::price`](crate::cdr::price).
    NoValidTariff,
}

impl From<InvalidPeriodIndex> for Error {
    fn from(err: InvalidPeriodIndex) -> Self {
        Self::Internal(err.into())
    }
}

#[derive(Debug)]
struct InvalidPeriodIndex(&'static str);

impl std::error::Error for InvalidPeriodIndex {}

impl fmt::Display for InvalidPeriodIndex {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Invalid index for period `{}`", self.0)
    }
}

/// The range of time the CDR periods span.
#[derive(Debug)]
pub enum PeriodRange {
    /// There are many periods in the CDR and so the range is from the `start_date_time` of the first to
    /// the `start_date_time` of the last.
    Many(Range<DateTime<Utc>>),

    /// There is one period in the CDR and so one `start_date_time`.
    Single(DateTime<Utc>),
}

impl fmt::Display for PeriodRange {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PeriodRange::Many(Range { start, end }) => write!(f, "{start}-{end}"),
            PeriodRange::Single(date_time) => write!(f, "{date_time}"),
        }
    }
}

impl From<ParseError> for Error {
    fn from(err: ParseError) -> Self {
        Error::Deserialize(err)
    }
}

impl From<duration::Error> for Error {
    fn from(err: duration::Error) -> Self {
        match err {
            duration::Error::Overflow => Self::DurationOverflow,
        }
    }
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        if let Error::Internal(err) = self {
            Some(&**err)
        } else {
            None
        }
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Deserialize(err) => {
                write!(f, "{err}")
            }
            Self::DimensionShouldHaveVolume { dimension_name } => {
                write!(f, "Dimension `{dimension_name}` should have volume")
            }
            Self::DurationOverflow => {
                f.write_str("A numeric overflow occurred while creating a duration")
            }
            Self::Internal(err) => {
                write!(f, "Internal: {err}")
            }
            Self::NoValidTariff => {
                f.write_str("No valid tariff has been found in the list of provided tariffs")
            }
        }
    }
}

#[derive(Debug)]
enum InternalError {
    InvalidPeriodIndex {
        index: usize,
        field_name: &'static str,
    },
}

impl std::error::Error for InternalError {}

impl From<InternalError> for Error {
    fn from(err: InternalError) -> Self {
        Error::Internal(Box::new(err))
    }
}

impl fmt::Display for InternalError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            InternalError::InvalidPeriodIndex { field_name, index } => {
                write!(
                    f,
                    "Invalid period index for `{field_name}`; index: `{index}`"
                )
            }
        }
    }
}

/// Where should the tariffs come from when pricing a `CDR`.
///
/// Used with [`cdr::price`](crate::cdr::price).
#[derive(Debug)]
pub enum TariffSource {
    /// Use the tariffs from the `CDR`.
    UseCdr,

    /// Ignore the tariffs from the `CDR` and use these instead
    Override(Vec<String>),
}

#[instrument(skip_all)]
pub(super) fn cdr(
    cdr: crate::cdr::Versioned<'_>,
    tariff_source: TariffSource,
    timezone: Tz,
) -> Result<Report, Error> {
    let version = cdr.version();
    let cdr = cdr_from_str(&cdr)?;

    match tariff_source {
        TariffSource::UseCdr => {
            debug!("Using tariffs from CDR");
            let tariffs = cdr
                .tariffs
                .iter()
                .map(|json| tariff::from_str(json.get(), version))
                .collect::<Result<Vec<_>, _>>()?;
            Ok(price_v221_cdr_with_tariffs(
                cdr, tariffs, timezone, version,
            )?)
        }
        TariffSource::Override(tariffs) => {
            debug!("Using override tariffs");
            let tariffs = tariffs
                .iter()
                .map(|json| tariff::from_str(json, version))
                .collect::<Result<Vec<_>, _>>()?;
            Ok(price_v221_cdr_with_tariffs(
                cdr, tariffs, timezone, version,
            )?)
        }
    }
}

/// Price a single charge-session using a tariff selected from a list.
///
/// Returns a report containing the totals, subtotals and a breakdown of the calculation.
/// Price a single charge-session using a single tariff.
///
/// Returns a report containing the totals, subtotals and a breakdown of the calculation.
fn price_v221_cdr_with_tariffs(
    mut cdr: v221::Cdr<'_>,
    tariffs: Vec<tariff::DeserOutcome>,
    timezone: Tz,
    version: Version,
) -> Result<Report, Error> {
    debug!(?timezone, ?version, "Pricing CDR");

    let validation_warnings = validate_and_sanitize_cdr(&mut cdr);

    let tariffs_normalized = tariff::normalize_all(tariffs);
    debug!(tariffs = ?tariffs_normalized.iter().map(tariff::Normalized::id).collect::<Vec<_>>(), "Found tariffs(by id) in CDR");

    let (tariff_report, tariff) =
        tariff::find_first_active(&tariffs_normalized, cdr.start_date_time)
            .ok_or(Error::NoValidTariff)?;

    debug!(ref = ?tariff_report.origin, "Found active tariff");
    debug!(%timezone, "Found timezone");

    let cs_periods = v221::cdr::normalize_periods(&mut cdr, timezone)?;
    let price_cdr_report = price_periods(&cs_periods, tariff)?;

    let tariff_reports = tariffs_normalized
        .into_iter()
        .map(TariffReport::from)
        .collect::<Vec<_>>();

    Ok(generate_report(
        &cdr,
        timezone,
        validation_warnings,
        tariff_reports,
        price_cdr_report,
        tariff_report,
    ))
}

/// Validate the CDR and sanitize the data so that the next phase can make presumptions about
/// the data. Presumptions such as; the charging periods are sorted.
/// Return warnings if the CDR isn't internally consistent.
fn validate_and_sanitize_cdr(cdr: &mut v221::Cdr<'_>) -> warning::Set<WarningKind> {
    let mut warnings = warning::Set::new();
    let cdr_range = cdr.start_date_time..cdr.end_date_time;
    cdr.charging_periods.sort_by_key(|p| p.start_date_time);

    match cdr.charging_periods.as_slice() {
        [] => (),
        [period] => {
            if !cdr_range.contains(&period.start_date_time) {
                warnings.only_kind(WarningKind::PeriodsOutsideStartEndDateTime {
                    cdr_range,
                    period_range: PeriodRange::Single(period.start_date_time),
                });
            }
        }
        [period_earliest, .., period_latest] => {
            let period_range = period_earliest.start_date_time..period_latest.start_date_time;

            if !(cdr_range.contains(&period_range.start) && cdr_range.contains(&period_range.end)) {
                warnings.only_kind(WarningKind::PeriodsOutsideStartEndDateTime {
                    cdr_range,
                    period_range: PeriodRange::Many(period_range),
                });
            }
        }
    }

    warnings
}

/// Price a list of normalized [`Period`]s using a [`Versioned`](crate::tariff::Versioned) tariff.
#[allow(dead_code, reason = "Pending use in CDR generation")]
pub(crate) fn periods(
    end_date_time: DateTime<Utc>,
    timezone: Tz,
    tariff: &crate::tariff::Versioned<'_>,
    periods: &mut [Period],
) -> Result<PricePeriodsReport, Error> {
    // make sure the periods are sorted by time as the start date of one period determines the end
    // date of the previous period.
    periods.sort_by_key(|p| p.start_date_time);
    let mut out_periods = Vec::<PeriodNormalized>::new();

    for (index, period) in periods.iter().enumerate() {
        trace!(index, "processing\n{period:#?}");

        let next_index = index + 1;

        let end_date_time = if let Some(next_period) = periods.get(next_index) {
            next_period.start_date_time
        } else {
            end_date_time
        };

        let next = if let Some(last) = out_periods.last() {
            let start_snapshot = last.end_snapshot.clone();
            let end_snapshot = start_snapshot.next(&period.consumed, end_date_time);

            let period = PeriodNormalized {
                consumed: period.consumed.clone(),
                start_snapshot,
                end_snapshot,
            };
            trace!("Adding new period based on the last added\n{period:#?}\n{last:#?}");
            period
        } else {
            let start_snapshot = TotalsSnapshot::zero(period.start_date_time, timezone);
            let end_snapshot = start_snapshot.next(&period.consumed, end_date_time);

            let period = PeriodNormalized {
                consumed: period.consumed.clone(),
                start_snapshot,
                end_snapshot,
            };
            trace!("Adding new period\n{period:#?}");
            period
        };

        out_periods.push(next);
    }

    let tariff = tariff::from_str(tariff.as_json_str(), tariff.version())?;
    let tariff::DeserOutcome {
        tariff,
        // The caller and creator of the `tariff::Versioned` object can choose to detect and handle unknown fields.
        unexpected_fields: _,
    } = tariff;
    let tariff = Tariff::from_v221(&tariff);

    price_periods(&out_periods, &tariff)
}

/// Price the given set of CDR periods using a normalized `Tariff`.
fn price_periods(
    periods: &[PeriodNormalized],
    tariff: &Tariff,
) -> Result<PricePeriodsReport, Error> {
    debug!(count = periods.len(), "Pricing CDR periods");

    if tracing::enabled!(tracing::Level::TRACE) {
        trace!("# CDR period list:");
        for period in periods {
            trace!("{period:#?}");
        }
    }

    let period_totals = period_totals(periods, tariff);
    let (billable, periods, totals) = period_totals.calculate_billed()?;
    let total_costs = total_costs(&periods, tariff);

    Ok(PricePeriodsReport {
        billable,
        periods,
        totals,
        total_costs,
    })
}

/// The internal report generated from the [`periods`] fn.
pub(crate) struct PricePeriodsReport {
    /// The billable dimensions calculated by applying the step-size to each dimension.
    billable: Billable,

    /// A list of reports for each charging period that occurred during a session.
    periods: Vec<PeriodReport>,

    /// The totals for each dimension.
    totals: Totals,

    /// The total costs for each dimension.
    total_costs: TotalCosts,
}

/// A report for a single charging period that occurred during a session.
///
/// A charging period is a period of time that has relevance for the total costs of a CDR.
/// During a charging session, different parameters change all the time, like the amount of energy used,
/// or the time of day. These changes can result in another [`PriceComponent`](https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#142-pricecomponent-class) of the Tariff becoming active.
#[derive(Debug)]
pub struct PeriodReport {
    /// The start time of this period.
    pub start_date_time: DateTime<Utc>,

    /// The end time of this period.
    pub end_date_time: DateTime<Utc>,

    /// A structure that contains results per dimension.
    pub dimensions: Dimensions,
}

impl PeriodReport {
    fn new(period: &PeriodNormalized, dimensions: Dimensions) -> Self {
        Self {
            start_date_time: period.start_snapshot.date_time,
            end_date_time: period.end_snapshot.date_time,
            dimensions,
        }
    }

    /// The total cost of all dimensions in this period.
    pub fn cost(&self) -> Option<Price> {
        [
            self.dimensions.duration_charging.cost(),
            self.dimensions.duration_parking.cost(),
            self.dimensions.flat.cost(),
            self.dimensions.energy.cost(),
        ]
        .into_iter()
        .fold(None, |accum, next| {
            if accum.is_none() && next.is_none() {
                None
            } else {
                Some(
                    accum
                        .unwrap_or_default()
                        .saturating_add(next.unwrap_or_default()),
                )
            }
        })
    }
}

/// The result of normalizing the CDR charging periods.
struct PeriodTotals {
    /// The list of normalized periods.
    periods: Vec<PeriodReport>,

    /// The computed step size.
    step_size: StepSize,

    /// The totals for each dimension.
    totals: Totals,
}

/// The totals for each dimension.
#[derive(Debug, Default)]
struct Totals {
    /// The total charging time used during a session.
    charging_time: Option<TimeDelta>,

    /// The total energy used during a session.
    energy: Option<Kwh>,

    /// The total parking time used during a session.
    parking_time: Option<TimeDelta>,
}

impl PeriodTotals {
    /// Calculate the billed dimensions by applying the step-size to each dimension.
    ///
    /// Applying the step size can mutate the dimension values contained in the `Period`.
    fn calculate_billed(self) -> Result<(Billable, Vec<PeriodReport>, Totals), Error> {
        let Self {
            mut periods,
            step_size,
            totals,
        } = self;
        let charging_time = totals
            .charging_time
            .map(|dt| step_size.apply_time(&mut periods, dt))
            .transpose()?;
        let energy = totals
            .energy
            .map(|kwh| step_size.apply_energy(&mut periods, kwh))
            .transpose()?;
        let parking_time = totals
            .parking_time
            .map(|dt| step_size.apply_parking_time(&mut periods, dt))
            .transpose()?;
        let billed = Billable {
            charging_time,
            energy,
            parking_time,
        };
        Ok((billed, periods, totals))
    }
}

/// The billable dimensions calculated by applying the step-size to each dimension.
#[derive(Debug)]
pub(crate) struct Billable {
    /// The billable charging time.
    charging_time: Option<TimeDelta>,

    /// The billable energy use.
    energy: Option<Kwh>,

    /// The billable parking time.
    parking_time: Option<TimeDelta>,
}

/// Map the `session::ChargePeriod`s to a normalized `Period` and calculate the step size and
/// totals for each dimension.
fn period_totals(periods: &[PeriodNormalized], tariff: &Tariff) -> PeriodTotals {
    let mut has_flat_fee = false;
    let mut step_size = StepSize::new();
    let mut totals = Totals::default();

    debug!(
        tariff_id = tariff.id(),
        period_count = periods.len(),
        "Accumulating dimension totals for each period"
    );

    let periods = periods
        .iter()
        .enumerate()
        .map(|(index, period)| {
            let mut component_set = tariff.active_components(period);
            trace!(
                index,
                "Creating charge period with Dimension\n{period:#?}\n{component_set:#?}"
            );

            if component_set.flat.is_some() {
                if has_flat_fee {
                    component_set.flat = None;
                } else {
                    has_flat_fee = true;
                }
            }

            step_size.update(index, &component_set, period);

            trace!(period_index = index, "Step size updated\n{step_size:#?}");

            let dimensions = Dimensions::new(component_set, &period.consumed);

            trace!(period_index = index, "Dimensions created\n{dimensions:#?}");

            if let Some(dt) = dimensions.duration_charging.volume {
                let acc = totals.charging_time.get_or_insert_default();
                *acc = acc.saturating_add(dt);
            }

            if let Some(kwh) = dimensions.energy.volume {
                let acc = totals.energy.get_or_insert_default();
                *acc = acc.saturating_add(kwh);
            }

            if let Some(dt) = dimensions.duration_parking.volume {
                let acc = totals.parking_time.get_or_insert_default();
                *acc = acc.saturating_add(dt);
            }

            trace!(period_index = index, ?totals, "Update totals");

            PeriodReport::new(period, dimensions)
        })
        .collect::<Vec<_>>();

    PeriodTotals {
        periods,
        step_size,
        totals,
    }
}

/// The total costs for each dimension.
#[derive(Debug, Default)]
pub(crate) struct TotalCosts {
    /// The [`Price`] for all energy used during a session.
    energy: Option<Price>,

    /// The [`Price`] for all flat rates applied during a session.
    fixed: Option<Price>,

    /// The [`Price`] for all charging time used during a session.
    duration_charging: Option<Price>,

    /// The [`Price`] for all parking time used during a session.
    duration_parking: Option<Price>,
}

impl TotalCosts {
    /// Summate each dimension total into a single total.
    ///
    /// Return `None` if there are no cost dimensions otherwise return `Some`.
    fn total(&self) -> Option<Price> {
        let Self {
            energy,
            fixed,
            duration_charging,
            duration_parking,
        } = self;
        debug!(
            energy = %DisplayOption(*energy),
            fixed = %DisplayOption(*fixed),
            duration_charging = %DisplayOption(*duration_charging),
            duration_parking = %DisplayOption(*duration_parking),
            "Calculating total costs."
        );
        [energy, fixed, duration_charging, duration_parking]
            .into_iter()
            .fold(None, |accum: Option<Price>, next| match (accum, next) {
                (None, None) => None,
                _ => Some(
                    accum
                        .unwrap_or_default()
                        .saturating_add(next.unwrap_or_default()),
                ),
            })
    }
}

/// Accumulate total costs per dimension across all periods.
fn total_costs(periods: &[PeriodReport], tariff: &Tariff) -> TotalCosts {
    let mut total_costs = TotalCosts::default();

    debug!(
        tariff_id = tariff.id(),
        period_count = periods.len(),
        "Accumulating dimension costs for each period"
    );
    for (index, period) in periods.iter().enumerate() {
        let dimensions = &period.dimensions;

        trace!(period_index = index, "Processing period");

        let energy_cost = dimensions.energy.cost();
        let fixed_cost = dimensions.flat.cost();
        let duration_charging_cost = dimensions.duration_charging.cost();
        let duration_parking_cost = dimensions.duration_parking.cost();

        trace!(?total_costs.energy, ?energy_cost, "Energy cost");
        trace!(?total_costs.duration_charging, ?duration_charging_cost, "Energy cost");
        trace!(?total_costs.duration_parking, ?duration_parking_cost, "Energy cost");
        trace!(?total_costs.fixed, ?fixed_cost, "Energy cost");

        total_costs.energy = match (total_costs.energy, energy_cost) {
            (None, None) => None,
            (total, period) => Some(
                total
                    .unwrap_or_default()
                    .saturating_add(period.unwrap_or_default()),
            ),
        };

        total_costs.duration_charging =
            match (total_costs.duration_charging, duration_charging_cost) {
                (None, None) => None,
                (total, period) => Some(
                    total
                        .unwrap_or_default()
                        .saturating_add(period.unwrap_or_default()),
                ),
            };

        total_costs.duration_parking = match (total_costs.duration_parking, duration_parking_cost) {
            (None, None) => None,
            (total, period) => Some(
                total
                    .unwrap_or_default()
                    .saturating_add(period.unwrap_or_default()),
            ),
        };

        total_costs.fixed = match (total_costs.fixed, fixed_cost) {
            (None, None) => None,
            (total, period) => Some(
                total
                    .unwrap_or_default()
                    .saturating_add(period.unwrap_or_default()),
            ),
        };

        trace!(period_index = index, ?total_costs, "Update totals");
    }

    total_costs
}

fn generate_report(
    cdr: &v221::Cdr<'_>,
    timezone: Tz,
    validation_warnings: warning::Set<WarningKind>,
    tariff_reports: Vec<TariffReport>,
    price_periods_report: PricePeriodsReport,
    tariff_report: TariffReport,
) -> Report {
    let PricePeriodsReport {
        billable,
        periods,
        totals,
        total_costs,
    } = price_periods_report;
    trace!("Update billed totals {billable:#?}");

    let total_cost = total_costs.total();

    debug!(total_cost = %DisplayOption(total_cost.as_ref()));

    let total_time = {
        debug!(
            period_start = %DisplayOption(periods.first().map(|p| p.start_date_time)),
            period_end = %DisplayOption(periods.last().map(|p| p.end_date_time)),
            "Calculating `total_time`"
        );

        periods
            .first()
            .zip(periods.last())
            .map(|(first, last)| {
                last.end_date_time
                    .signed_duration_since(first.start_date_time)
            })
            .unwrap_or_default()
    };
    debug!(total_time = %Hms(total_time));

    let report = Report {
        periods,
        tariff: tariff_report,
        timezone: timezone.to_string(),
        billed_parking_time: billable.parking_time,
        billed_energy: billable.energy,
        billed_charging_time: billable.charging_time,
        tariff_reports,
        total_charging_time: totals.charging_time,
        total_cost: Total {
            cdr: cdr.total_cost,
            calculated: total_cost,
        },
        total_time_cost: Total {
            cdr: cdr.total_time_cost,
            calculated: total_costs.duration_charging,
        },
        total_time: Total {
            cdr: cdr.total_time,
            calculated: total_time,
        },
        total_parking_cost: Total {
            cdr: cdr.total_parking_cost,
            calculated: total_costs.duration_parking,
        },
        total_parking_time: Total {
            cdr: cdr.total_parking_time,
            calculated: totals.parking_time,
        },
        total_energy_cost: Total {
            cdr: cdr.total_energy_cost,
            calculated: total_costs.energy,
        },
        total_energy: Total {
            cdr: cdr.total_energy,
            calculated: totals.energy,
        },
        total_fixed_cost: Total {
            cdr: cdr.total_fixed_cost,
            calculated: total_costs.fixed,
        },
        total_reservation_cost: Total {
            cdr: cdr.total_reservation_cost,
            calculated: None,
        },
        warnings: validation_warnings
            .into_parts_vec()
            .into_iter()
            .map(|(kind, _elem_id)| {
                // `elem_id` will be used when warnings are added to the price function.
                WarningReport { kind }
            })
            .collect(),
    };

    trace!("{report:#?}");

    report
}

#[derive(Debug)]
struct StepSize {
    charging_time: Option<(usize, Component)>,
    parking_time: Option<(usize, Component)>,
    energy: Option<(usize, Component)>,
}

/// Return the duration as a `Decimal` amount of seconds.
fn delta_as_seconds_dec(delta: TimeDelta) -> Decimal {
    Decimal::from(delta.num_milliseconds())
        .checked_div(Decimal::from(duration::MILLIS_IN_SEC))
        .expect("Can't overflow; See test `as_seconds_dec_should_not_overflow`")
}

/// Create a `HoursDecimal` from a `Decimal` amount of seconds.
fn delta_from_seconds_dec(seconds: Decimal) -> Result<TimeDelta, duration::Error> {
    let millis = seconds.saturating_mul(Decimal::from(duration::MILLIS_IN_SEC));
    let millis = i64::try_from(millis)?;
    let delta = TimeDelta::try_milliseconds(millis).ok_or(duration::Error::Overflow)?;
    Ok(delta)
}

impl StepSize {
    fn new() -> Self {
        Self {
            charging_time: None,
            parking_time: None,
            energy: None,
        }
    }

    fn update(&mut self, index: usize, components: &ComponentSet, period: &PeriodNormalized) {
        if period.consumed.energy.is_some() {
            if let Some(energy) = components.energy.clone() {
                self.energy = Some((index, energy));
            }
        }

        if period.consumed.duration_charging.is_some() {
            if let Some(time) = components.duration_charging.clone() {
                self.charging_time = Some((index, time));
            }
        }

        if period.consumed.duration_parking.is_some() {
            if let Some(parking) = components.duration_parking.clone() {
                self.parking_time = Some((index, parking));
            }
        }
    }

    fn duration_step_size(
        total_volume: TimeDelta,
        period_billed_volume: &mut TimeDelta,
        step_size: u64,
    ) -> Result<TimeDelta, Error> {
        if step_size == 0 {
            return Ok(total_volume);
        }

        let total_seconds = delta_as_seconds_dec(total_volume);
        let step_size = Decimal::from(step_size);

        let total_billed_volume = delta_from_seconds_dec(
            total_seconds
                .checked_div(step_size)
                .ok_or(Error::DurationOverflow)?
                .ceil()
                .saturating_mul(step_size),
        )?;

        let period_delta_volume = total_billed_volume.saturating_sub(total_volume);
        *period_billed_volume = period_billed_volume.saturating_add(period_delta_volume);

        Ok(total_billed_volume)
    }

    fn apply_time(
        &self,
        periods: &mut [PeriodReport],
        total: TimeDelta,
    ) -> Result<TimeDelta, Error> {
        let (Some((time_index, price)), None) = (&self.charging_time, &self.parking_time) else {
            return Ok(total);
        };

        let Some(period) = periods.get_mut(*time_index) else {
            return Err(InternalError::InvalidPeriodIndex {
                index: *time_index,
                field_name: "apply_time",
            }
            .into());
        };
        let volume = period
            .dimensions
            .duration_charging
            .billed_volume
            .as_mut()
            .ok_or(Error::DimensionShouldHaveVolume {
                dimension_name: "time",
            })?;

        Self::duration_step_size(total, volume, price.step_size)
    }

    fn apply_parking_time(
        &self,
        periods: &mut [PeriodReport],
        total: TimeDelta,
    ) -> Result<TimeDelta, Error> {
        let Some((parking_index, price)) = &self.parking_time else {
            return Ok(total);
        };

        let Some(period) = periods.get_mut(*parking_index) else {
            return Err(InternalError::InvalidPeriodIndex {
                index: *parking_index,
                field_name: "apply_parking_time",
            }
            .into());
        };
        let volume = period
            .dimensions
            .duration_parking
            .billed_volume
            .as_mut()
            .ok_or(Error::DimensionShouldHaveVolume {
                dimension_name: "parking_time",
            })?;

        Self::duration_step_size(total, volume, price.step_size)
    }

    fn apply_energy(&self, periods: &mut [PeriodReport], total_volume: Kwh) -> Result<Kwh, Error> {
        let Some((energy_index, price)) = &self.energy else {
            return Ok(total_volume);
        };

        if price.step_size == 0 {
            return Ok(total_volume);
        }

        let Some(period) = periods.get_mut(*energy_index) else {
            return Err(InternalError::InvalidPeriodIndex {
                index: *energy_index,
                field_name: "apply_energy",
            }
            .into());
        };
        let step_size = Decimal::from(price.step_size);

        let period_billed_volume = period.dimensions.energy.billed_volume.as_mut().ok_or(
            Error::DimensionShouldHaveVolume {
                dimension_name: "energy",
            },
        )?;

        let total_billed_volume = Kwh::from_watt_hours(
            total_volume
                .watt_hours()
                .checked_div(step_size)
                .ok_or(Error::DurationOverflow)?
                .ceil()
                .saturating_mul(step_size),
        );

        let period_delta_volume = total_billed_volume.saturating_sub(total_volume);
        *period_billed_volume = period_billed_volume.saturating_add(period_delta_volume);

        Ok(total_billed_volume)
    }
}

fn cdr_from_str<'buf>(cdr: &crate::cdr::Versioned<'buf>) -> Result<v221::Cdr<'buf>, ParseError> {
    match cdr.version() {
        Version::V221 => {
            let cdr = serde_json::from_str::<v221::Cdr<'_>>(cdr.as_json_str())
                .map_err(ParseError::from_cdr_serde_err)?;
            Ok(cdr)
        }
        Version::V211 => {
            let cdr = serde_json::from_str::<v211::Cdr<'_>>(cdr.as_json_str())
                .map_err(ParseError::from_cdr_serde_err)?;
            Ok(cdr.into())
        }
    }
}

#[cfg(test)]
pub mod test {
    #![allow(clippy::missing_panics_doc, reason = "tests are allowed to panic")]
    #![allow(clippy::panic, reason = "tests are allowed panic")]

    use std::collections::BTreeMap;

    use chrono::TimeDelta;
    use serde::Deserialize;
    use tracing::debug;

    use crate::{
        assert_approx_eq,
        duration::ToHoursDecimal,
        json,
        test::{ApproxEq, Expectation},
        timezone,
        warning::Kind,
        Kwh, Price, UnexpectedFields,
    };

    use super::{de, Error, Report, TariffReport, Total};

    // Decimal precision used when comparing the outcomes of the calculation with the CDR.
    const PRECISION: u32 = 2;

    #[test]
    const fn error_should_be_send_and_sync() {
        const fn f<T: Send + Sync>() {}

        f::<Error>();
    }

    /// Parse the expect JSON for pricing a CDR.
    #[track_caller]
    pub fn parse_expect_json(expect_json: Option<&str>) -> Expect {
        expect_json
            .map(|json| serde_json::from_str(json).expect("Unable to parse expect JSON"))
            .unwrap_or_default()
    }

    #[derive(serde::Deserialize, Default)]
    pub struct Expect {
        /// Expectations for the result of calling `timezone::find_or_infer`.
        pub timezone_find: Option<timezone::test::FindOrInferExpect>,

        /// Expectations for the result of calling `cdr::parse*`.
        pub cdr_parse: Option<ParseExpect>,

        /// Expectations for the result of calling `cdr::price*`.
        pub cdr_price: Option<PriceExpect>,
    }

    pub(crate) fn assert_parse_report(
        unexpected_fields: json::UnexpectedFields<'_>,
        cdr_price_expect: Option<ParseExpect>,
    ) {
        let unexpected_fields_expect = cdr_price_expect
            .map(|exp| {
                let ParseExpect { unexpected_fields } = exp;
                unexpected_fields
            })
            .unwrap_or(Expectation::Absent);

        if let Expectation::Present(expectation) = unexpected_fields_expect {
            let unexpected_fields_expect = expectation.expect_value();

            for field in unexpected_fields {
                assert!(
                    unexpected_fields_expect.contains(&field.to_string()),
                    "The CDR has an unexpected field that's not expected: `{field}`"
                );
            }
        } else {
            assert!(
                unexpected_fields.is_empty(),
                "The CDR has unexpected fields; {unexpected_fields:#}",
            );
        }
    }

    pub(crate) fn assert_price_report(report: Report, cdr_price_expect: Option<PriceExpect>) {
        let Report {
            warnings,
            mut tariff_reports,
            periods: _,
            tariff,
            timezone: _,
            billed_energy: _,
            billed_parking_time: _,
            billed_charging_time: _,
            total_charging_time: _,
            total_cost,
            total_fixed_cost,
            total_time,
            total_time_cost,
            total_energy,
            total_energy_cost,
            total_parking_time,
            total_parking_cost,
            total_reservation_cost,
        } = report;

        // This destructure isn't pretty but it's at least simple to maintain.
        // The alternative is getting involved with references of references when processing each borrowed field.
        let (
            warnings_expect,
            tariff_index_expect,
            tariff_id_expect,
            tariff_reports_expect,
            total_cost_expectation,
            total_fixed_cost_expectation,
            total_time_expectation,
            total_time_cost_expectation,
            total_energy_expectation,
            total_energy_cost_expectation,
            total_parking_time_expectation,
            total_parking_cost_expectation,
            total_reservation_cost_expectation,
        ) = cdr_price_expect
            .map(|exp| {
                let PriceExpect {
                    warnings,
                    tariff_index,
                    tariff_id,
                    tariff_reports,
                    total_cost,
                    total_fixed_cost,
                    total_time,
                    total_time_cost,
                    total_energy,
                    total_energy_cost,
                    total_parking_time,
                    total_parking_cost,
                    total_reservation_cost,
                } = exp;

                (
                    warnings,
                    tariff_index,
                    tariff_id,
                    tariff_reports,
                    total_cost,
                    total_fixed_cost,
                    total_time,
                    total_time_cost,
                    total_energy,
                    total_energy_cost,
                    total_parking_time,
                    total_parking_cost,
                    total_reservation_cost,
                )
            })
            .unwrap_or((
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
                Expectation::Absent,
            ));

        if let Expectation::Present(expectation) = warnings_expect {
            let warnings_expect = expectation.expect_value();

            debug!("{warnings_expect:?}");

            for warning in warnings {
                assert!(
                    warnings_expect.contains(&warning.kind.id().to_string()),
                    "The CDR has a warning that's not expected"
                );
            }
        } else {
            assert!(warnings.is_empty(), "The CDR has warnings; {warnings:?}",);
        }

        if let Expectation::Present(expectation) = tariff_reports_expect {
            let tariff_reports_expect: BTreeMap<_, _> = expectation
                .expect_value()
                .into_iter()
                .map(
                    |TariffReportExpect {
                         id,
                         unexpected_fields,
                     }| (id, unexpected_fields),
                )
                .collect();

            for report in &mut tariff_reports {
                let TariffReport {
                    origin: reference,
                    unexpected_fields,
                } = report;
                let id = &reference.id;
                let Some(unexpected_fields_expect) = tariff_reports_expect.get(id) else {
                    panic!("A tariff with {id} is not expected");
                };

                debug!("{:?}", unexpected_fields_expect);

                unexpected_fields.retain(|field| {
                    let present = unexpected_fields_expect.contains(field);
                    assert!(present, "The tariff with id: `{id}` has an unexpected field that is not expected: `{field}`");
                    !present
                });

                assert!(
                    unexpected_fields.is_empty(),
                    "The tariff with id `{id}` has unexpected fields; {unexpected_fields:?}",
                );
            }
        } else {
            for report in &tariff_reports {
                let TariffReport {
                    origin: reference,
                    unexpected_fields,
                } = report;
                let id = &reference.id;
                assert!(
                    unexpected_fields.is_empty(),
                    "The tariff with id `{id}` has unexpected fields; {unexpected_fields:?}",
                );
            }
        }

        if let Expectation::Present(expectation) = tariff_id_expect {
            assert_eq!(tariff.origin.id, expectation.expect_value());
        }

        if let Expectation::Present(expectation) = tariff_index_expect {
            assert_eq!(tariff.origin.index, expectation.expect_value());
        }

        total_cost_expectation.expect_price("total_cost", &total_cost);
        total_fixed_cost_expectation.expect_opt_price("total_fixed_cost", &total_fixed_cost);
        total_time_expectation.expect_duration("total_time", &total_time);
        total_time_cost_expectation.expect_opt_price("total_time_cost", &total_time_cost);
        total_energy_expectation.expect_opt_kwh("total_energy", &total_energy);
        total_energy_cost_expectation.expect_opt_price("total_energy_cost", &total_energy_cost);
        total_parking_time_expectation
            .expect_opt_duration("total_parking_time", &total_parking_time);
        total_parking_cost_expectation.expect_opt_price("total_parking_cost", &total_parking_cost);
        total_reservation_cost_expectation
            .expect_opt_price("total_reservation_cost", &total_reservation_cost);
    }

    /// Expectations for the result of calling `cdr::parse*`.
    #[derive(serde::Deserialize)]
    pub struct ParseExpect {
        #[serde(default)]
        unexpected_fields: Expectation<Vec<String>>,
    }

    /// Expectations for the result of calling `cdr::price`.
    #[derive(serde::Deserialize)]
    pub struct PriceExpect {
        #[serde(default)]
        warnings: Expectation<Vec<String>>,

        /// Index of the tariff that was found to be active.
        #[serde(default)]
        tariff_index: Expectation<usize>,

        /// Id of the tariff that was found to be active.
        #[serde(default)]
        tariff_id: Expectation<String>,

        /// A list of the tariff Ids found in the CDR or supplied to the [`cdr::price`](crate::cdr::price) function.
        ///
        /// Each tariff may have a set of unexpected fields encountered while parsing the tariff.
        #[serde(default)]
        tariff_reports: Expectation<Vec<TariffReportExpect>>,

        /// Total sum of all the costs of this transaction in the specified currency.
        #[serde(default)]
        total_cost: Expectation<Price>,

        /// Total sum of all the fixed costs in the specified currency, except fixed price components of parking and reservation. The cost not depending on amount of time/energy used etc. Can contain costs like a start tariff.
        #[serde(default)]
        total_fixed_cost: Expectation<Price>,

        /// Total duration of the charging session (including the duration of charging and not charging), in hours.
        #[serde(default)]
        total_time: Expectation<de::HoursDecimal>,

        /// Total sum of all the cost related to duration of charging during this transaction, in the specified currency.
        #[serde(default)]
        total_time_cost: Expectation<Price>,

        /// Total energy charged, in kWh.
        #[serde(default)]
        total_energy: Expectation<Kwh>,

        /// Total sum of all the cost of all the energy used, in the specified currency.
        #[serde(default)]
        total_energy_cost: Expectation<Price>,

        /// Total duration of the charging session where the EV was not charging (no energy was transferred between EVSE and EV), in hours.
        #[serde(default)]
        total_parking_time: Expectation<de::HoursDecimal>,

        /// Total sum of all the cost related to parking of this transaction, including fixed price components, in the specified currency.
        #[serde(default)]
        total_parking_cost: Expectation<Price>,

        /// Total sum of all the cost related to a reservation of a Charge Point, including fixed price components, in the specified currency.
        #[serde(default)]
        total_reservation_cost: Expectation<Price>,
    }

    #[derive(Debug, Deserialize)]
    struct TariffReportExpect {
        /// The id of the tariff.
        id: String,

        /// Set of unexpected fields encountered while parsing the tariff.
        unexpected_fields: UnexpectedFields,
    }

    impl Expectation<Price> {
        #[track_caller]
        fn expect_opt_price(self, field_name: &str, total: &Total<Option<Price>>) {
            if let Expectation::Present(expect_value) = self {
                match (expect_value.into_option(), total.calculated) {
                    (Some(a), Some(b)) => assert!(
                        a.approx_eq(&b),
                        "Expected `{a}` but `{b}` was calculated for `{field_name}`"
                    ),
                    (Some(a), None) => {
                        panic!("Expected `{a}`, but no price was calculated for `{field_name}`")
                    }
                    (None, Some(b)) => {
                        panic!("Expected no value, but `{b}` was calculated for `{field_name}`")
                    }
                    (None, None) => (),
                }
            } else {
                match (total.cdr, total.calculated) {
                    (None, None) => (),
                    (None, Some(calculated)) => {
                        assert!(calculated.is_zero(), "The CDR field `{field_name}` doesn't have a value but a value was calculated; calculated: {calculated}");
                    }
                    (Some(cdr), None) => {
                        assert!(
                            cdr.is_zero(),
                            "The CDR field `{field_name}` has a value but the calculated value is none; cdr: {cdr}"
                        );
                    }
                    (Some(cdr), Some(calculated)) => {
                        assert!(
                            cdr.approx_eq(&calculated),
                            "Comparing `{field_name}` field with CDR"
                        );
                    }
                }
            }
        }

        #[track_caller]
        fn expect_price(self, field_name: &str, total: &Total<Price, Option<Price>>) {
            if let Expectation::Present(expect_value) = self {
                match (expect_value.into_option(), total.calculated) {
                    (Some(a), Some(b)) => assert!(
                        a.approx_eq(&b),
                        "Expected `{a}` but `{b}` was calculated for `{field_name}`"
                    ),
                    (Some(a), None) => {
                        panic!("Expected `{a}`, but no price was calculated for `{field_name}`")
                    }
                    (None, Some(b)) => {
                        panic!("Expected no value, but `{b}` was calculated for `{field_name}`")
                    }
                    (None, None) => (),
                }
            } else if let Some(calculated) = total.calculated {
                assert!(
                    total.cdr.approx_eq(&calculated),
                    "CDR contains `{}` but `{}` was calculated for `{field_name}`",
                    total.cdr,
                    calculated
                );
            } else {
                assert!(
                    total.cdr.is_zero(),
                    "The CDR field `{field_name}` has a value but the calculated value is none; cdr: {:?}",
                    total.cdr
                );
            }
        }
    }

    impl Expectation<de::HoursDecimal> {
        #[track_caller]
        fn expect_duration(self, field_name: &str, total: &Total<TimeDelta>) {
            if let Expectation::Present(expect_value) = self {
                assert_approx_eq!(
                    expect_value.expect_value().to_hours_dec(),
                    total.calculated.to_hours_dec(),
                    "Comparing `{field_name}` field with expectation"
                );
            } else {
                assert_approx_eq!(
                    total.cdr.to_hours_dec(),
                    total.calculated.to_hours_dec(),
                    "Comparing `{field_name}` field with CDR"
                );
            }
        }

        #[track_caller]
        fn expect_opt_duration(
            self,
            field_name: &str,
            total: &Total<Option<TimeDelta>, Option<TimeDelta>>,
        ) {
            if let Expectation::Present(expect_value) = self {
                assert_approx_eq!(
                    expect_value
                        .into_option()
                        .unwrap_or_default()
                        .to_hours_dec(),
                    &total
                        .calculated
                        .as_ref()
                        .map(ToHoursDecimal::to_hours_dec)
                        .unwrap_or_default(),
                    "Comparing `{field_name}` field with expectation"
                );
            } else {
                assert_approx_eq!(
                    total.cdr.unwrap_or_default().to_hours_dec(),
                    total.calculated.unwrap_or_default().to_hours_dec(),
                    "Comparing `{field_name}` field with CDR"
                );
            }
        }
    }

    impl Expectation<Kwh> {
        #[track_caller]
        fn expect_opt_kwh(self, field_name: &str, total: &Total<Kwh, Option<Kwh>>) {
            if let Expectation::Present(expect_value) = self {
                assert_eq!(
                    expect_value
                        .into_option()
                        .map(|kwh| kwh.round_dp(PRECISION)),
                    total
                        .calculated
                        .map(|kwh| kwh.rescale().round_dp(PRECISION)),
                    "Comparing `{field_name}` field with expectation"
                );
            } else {
                assert_eq!(
                    total.cdr.round_dp(PRECISION),
                    total
                        .calculated
                        .map(|kwh| kwh.rescale().round_dp(PRECISION))
                        .unwrap_or_default(),
                    "Comparing `{field_name}` field with CDR"
                );
            }
        }
    }
}

#[cfg(test)]
mod test_periods {
    #![allow(clippy::as_conversions, reason = "tests are allowed to panic")]
    #![allow(clippy::panic, reason = "tests are allowed panic")]

    use chrono::Utc;
    use chrono_tz::Tz;
    use rust_decimal::Decimal;
    use rust_decimal_macros::dec;

    use crate::{assert_approx_eq, cdr, price, Kwh};

    use super::{Consumed, Period, PricePeriodsReport, TariffSource};

    #[test]
    fn should_price_periods_from_time_and_parking_time_cdr_and_tariff() {
        const CDR_JSON: &str = include_str!(
            "../test_data/v211/real_world/time_and_parking_time_separate_tariff/cdr.json"
        );
        const TARIFF_JSON: &str = include_str!(
            "../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json"
        );
        // Every period has a 15 minute duration.
        const PERIOD_DURATION: chrono::TimeDelta = chrono::TimeDelta::minutes(15);

        /// Create `TIME` period for each energy value provided.
        ///
        /// Each `TIME` period is the same duration.
        /// but has a different `start_date_time`.
        fn charging(start_date_time: &str, energy: Vec<Decimal>) -> Vec<Period> {
            let start: chrono::DateTime<Utc> = start_date_time.parse().unwrap();

            energy
                .into_iter()
                .enumerate()
                .map(|(i, kwh)| {
                    let i = i32::try_from(i).unwrap();
                    let start_date_time = start + (PERIOD_DURATION * i);

                    Period {
                        start_date_time,
                        consumed: Consumed {
                            duration_charging: Some(PERIOD_DURATION),
                            energy: Some(kwh.into()),
                            ..Default::default()
                        },
                    }
                })
                .collect()
        }

        /// Create `period_count` number of `PARKING_TIME` periods.
        ///
        /// Each `PARKING_TIME` period is the same duration and energy usage (0kwh)
        /// but has a different `start_date_time`.
        fn parking(start_date_time: &str, period_count: usize) -> Vec<Period> {
            // Every parking period has a comsumned energy of zero.
            let period_energy = Kwh::from(0);
            let start: chrono::DateTime<Utc> = start_date_time.parse().unwrap();

            let period_count = i32::try_from(period_count).unwrap();
            // Add uniform periods except for the last one
            let mut periods: Vec<Period> = (0..period_count - 1)
                .map(|i| {
                    let start_date_time = start + (PERIOD_DURATION * i);

                    Period {
                        start_date_time,
                        consumed: Consumed {
                            duration_parking: Some(PERIOD_DURATION),
                            energy: Some(period_energy),
                            ..Default::default()
                        },
                    }
                })
                .collect();

            let start_date_time = start + (PERIOD_DURATION * (period_count - 1));

            // The last period is a 10 min period instead of 15 min.
            periods.push(Period {
                start_date_time,
                consumed: Consumed {
                    duration_parking: Some(chrono::TimeDelta::seconds(644)),
                    energy: Some(period_energy),
                    ..Default::default()
                },
            });

            periods
        }

        let report = cdr::parse_with_version(CDR_JSON, crate::Version::V211).unwrap();
        let cdr::ParseReport {
            cdr,
            unexpected_fields,
        } = report;

        assert!(unexpected_fields.is_empty());
        // If you know the version and timezone of a CDR you simply pass them into the `cdr::price` fn.
        let report = cdr::price(
            cdr,
            TariffSource::Override(vec![TARIFF_JSON.to_string()]),
            Tz::Europe__Amsterdam,
        )
        .expect("unable to price CDR JSON");

        let price::Report {
            // We are not concerned with warnings in this test
            warnings: _,
            periods,
            // We are not concerned with the tariff reports in this test
            tariff: _,
            tariff_reports: _,
            timezone: _,
            billed_energy,
            billed_parking_time,
            billed_charging_time,
            total_charging_time,
            total_energy,
            total_parking_time,
            // The `total_time` simply the addition of `total_charging_time` and `total_parking_time`.
            total_time: _,
            total_cost,
            total_energy_cost,
            total_fixed_cost,
            total_parking_cost,
            // Reservation costs are not computed during pricing.
            total_reservation_cost: _,
            total_time_cost,
        } = report;

        let tariff = crate::tariff::parse(TARIFF_JSON).unwrap();
        let tariff = tariff.unwrap_certain();

        let mut cdr_periods = charging(
            "2025-04-09T16:12:54.000Z",
            vec![
                dec!(2.75),
                dec!(2.77),
                dec!(1.88),
                dec!(2.1),
                dec!(2.09),
                dec!(2.11),
                dec!(2.09),
                dec!(2.09),
                dec!(2.09),
                dec!(2.09),
                dec!(2.09),
                dec!(2.09),
                dec!(2.09),
                dec!(2.11),
                dec!(2.13),
                dec!(2.09),
                dec!(2.11),
                dec!(2.12),
                dec!(2.13),
                dec!(2.1),
                dec!(2.0),
                dec!(0.69),
                dec!(0.11),
            ],
        );
        let mut periods_parking = parking("2025-04-09T21:57:55.000Z", 47);

        cdr_periods.append(&mut periods_parking);
        cdr_periods.sort_by_key(|p| p.start_date_time);

        assert_eq!(
            cdr_periods.len(),
            periods.len(),
            "The amount of `price::Report` periods should equal the periods given to the `price::periods` fn"
        );
        assert_eq!(
            periods.len(),
            70,
            "The `time_and_parking/cdr.json` has 70 `charging_periods`"
        );

        assert!(periods
            .iter()
            .map(|p| p.start_date_time)
            .collect::<Vec<_>>()
            .is_sorted());

        let periods_report = price::periods(
            "2025-04-10T09:38:38.000Z".parse().unwrap(),
            chrono_tz::Europe::Amsterdam,
            &tariff,
            &mut cdr_periods,
        )
        .unwrap();

        let PricePeriodsReport {
            billable,
            periods,
            totals,
            total_costs,
        } = periods_report;

        assert_eq!(
            cdr_periods.len(),
            periods.len(),
            "The amount of `price::Report` periods should equal the periods given to the `price::periods` fn"
        );
        assert_eq!(
            periods.len(),
            70,
            "The `time_and_parking/cdr.json` has 70 `charging_periods`"
        );

        assert_approx_eq!(billable.charging_time, billed_charging_time);
        assert_approx_eq!(billable.energy, billed_energy);
        assert_approx_eq!(billable.parking_time, billed_parking_time,);

        assert_approx_eq!(totals.charging_time, total_charging_time);
        assert_approx_eq!(totals.energy, total_energy.calculated);
        assert_approx_eq!(totals.parking_time, total_parking_time.calculated);

        assert_approx_eq!(total_costs.duration_charging, total_time_cost.calculated,);
        assert_approx_eq!(total_costs.energy, total_energy_cost.calculated,);
        assert_approx_eq!(total_costs.fixed, total_fixed_cost.calculated);
        assert_approx_eq!(total_costs.duration_parking, total_parking_cost.calculated);
        assert_approx_eq!(total_costs.total(), total_cost.calculated);
    }
}

#[cfg(test)]
mod test_validate_cdr {
    use assert_matches::assert_matches;

    use crate::{
        price::{self, v221, WarningKind},
        test::{self, datetime_from_str},
    };

    use super::validate_and_sanitize_cdr;

    #[test]
    fn should_pass_validation() {
        test::setup();
        let json = cdr_json("2022-01-13T16:00:00Z", "2022-01-13T19:12:00Z");
        let mut cdr = serde_json::from_str::<v221::Cdr<'_>>(&json).unwrap();

        let warnings = validate_and_sanitize_cdr(&mut cdr);
        assert!(warnings.is_empty());
    }

    #[test]
    fn should_fail_validation_start_end_range_doesnt_overlap_with_periods() {
        test::setup();

        let json = cdr_json("2022-02-13T16:00:00Z", "2022-02-13T19:12:00Z");
        let mut cdr = serde_json::from_str::<v221::Cdr<'_>>(&json).unwrap();

        let warnings = validate_and_sanitize_cdr(&mut cdr).into_kind_vec();
        let [warning] = warnings.try_into().unwrap();
        let (cdr_range, period_range) = assert_matches!(warning, WarningKind::PeriodsOutsideStartEndDateTime { cdr_range, period_range } => (cdr_range, period_range));

        {
            assert_eq!(cdr_range.start, datetime_from_str("2022-02-13T16:00:00Z"));
            assert_eq!(cdr_range.end, datetime_from_str("2022-02-13T19:12:00Z"));
        }
        {
            let period_range =
                assert_matches!(period_range, price::PeriodRange::Many(range) => range);

            assert_eq!(
                period_range.start,
                datetime_from_str("2022-01-13T16:00:00Z")
            );
            assert_eq!(period_range.end, datetime_from_str("2022-01-13T18:30:00Z"));
        }
    }

    fn cdr_json(start_date_time: &str, end_date_time: &str) -> String {
        let value = serde_json::json!({
            "start_date_time": start_date_time,
            "end_date_time": end_date_time,
            "currency": "EUR",
            "tariffs": [],
            "cdr_location": {
                "country": "NLD"
            },
            "charging_periods": [
                {
                    "start_date_time": "2022-01-13T16:00:00Z",
                    "dimensions": [
                        {
                            "type": "TIME",
                            "volume": 2.5
                        }
                    ]
                },
                {
                    "start_date_time": "2022-01-13T18:30:00Z",
                    "dimensions": [
                        {
                            "type": "PARKING_TIME",
                            "volume": 0.7
                        }
                    ]
                }
            ],
            "total_cost": {
                "excl_vat": 11.25,
                "incl_vat": 12.75
            },
            "total_time_cost": {
                "excl_vat": 7.5,
                "incl_vat": 8.25
            },
            "total_parking_time": 0.7,
            "total_parking_cost": {
                "excl_vat": 3.75,
                "incl_vat": 4.5
            },
            "total_time": 3.2,
            "total_energy": 0,
            "last_updated": "2022-01-13T00:00:00Z"
        });

        value.to_string()
    }
}