metering 0.15.0

//! Typed OBIS (Object Identification System) codes for German energy metering.
//!
//! ## Standard
//!
//! IEC 62056-21 / DLMS-COSEM, as adopted by BDEW and Messstellenbetreiber
//! in Germany. OBIS codes identify measurement channels on smart meters and
//! data communication systems.
//!
//! ## Format
//!
//! ```text
//! A-B:C.D.E*F
//! │ │ │ │ │ └ F  value group (storage number, 0 = current)
//! │ │ │ │ └── E  tariff (0 = total, 1 = HT, 2 = NT, …)
//! │ │ │ └──── D  measurement type (8 = forward, 9 = reverse, 0 = combined)
//! │ │ └────── C  quantity (1 = active energy, 3 = reactive energy, 7 = gas volume)
//! │ └──────── B  channel (0 = sum, otherwise sub-meter)
//! └────────── A  medium, per the DLMS/COSEM Blue Book list that OMS Vol. 2
//!               adopts: 0 = abstract, 1 = electricity, 4 = Heizkostenverteiler,
//!               5 = cooling, 6 = heat, 7 = gas, 8 = cold water, 9 = hot water
//! ```
//!
//! ## Commonly used codes in German MaKo
//!
//! | Code | Description |
//! |---|---|
//! | `1-0:1.8.0*255` | Electricity forward active energy total (kWh) |
//! | `1-0:1.8.1*255` | Electricity forward active energy register 1 (HT) |
//! | `1-0:1.8.2*255` | Electricity forward active energy register 2 (NT) |
//! | `1-0:2.8.0*255` | Electricity reverse active energy (Einspeisung) |
//! | `1-0:1.29.0*255` | Electricity demand (kW, 15-min average) |
//! | `1-0:3.8.0*255` | Electricity reactive energy inductive (kvarh) |
//! | `1-0:4.8.0*255` | Electricity reactive energy capacitive (kvarh) |
//! | `7-0:3.0.0*255` | Gas volume (m³) |
//! | `6-0:1.0.0*255` | Heat energy (kWh_th) — medium 6, **not** 8 |
//! | `8-0:1.0.0*255` | Cold water volume (m³) |
//! | `9-0:1.0.0*255` | Hot water volume (m³) |

use std::fmt;
use std::str::FromStr;

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

use crate::error::ParseError;

/// A parsed OBIS code: `A-B:C.D.E*F`.
///
/// All six value groups are stored. The canonical serialised form is the
/// full `A-B:C.D.E*F` string; parsing is lenient about the storage number
/// suffix (`*F` — defaults to 255 when absent).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(try_from = "&str", into = "String"))]
pub struct ObisCode {
    /// Medium: 1 = electricity, 7 = gas, 8 = heat/cold.
    pub a: u8,
    /// Channel: 0 = sum channel, 1–n = sub-channel.
    pub b: u8,
    /// Quantity: 1 = active power/energy, 3/4 = reactive energy, 7 = gas volume.
    pub c: u8,
    /// Measurement: 8 = import/forward, 9 = export/reverse, 0 = combined.
    pub d: u8,
    /// Tariff: 0 = total, 1 = HT register, 2 = NT register.
    pub e: u8,
    /// Storage: 255 = current value, 0 = default.
    pub f: u8,
}

impl ObisCode {
    /// Electricity forward active energy — total (Bezug, kWh, gesamt).
    /// HT + NT combined.
    pub const STROM_BEZUG_TOTAL: Self = Self {
        a: 1,
        b: 0,
        c: 1,
        d: 8,
        e: 0,
        f: 255,
    };

    /// Electricity forward active energy — register 1 (HT, Hochtarif).
    pub const STROM_BEZUG_HT: Self = Self {
        a: 1,
        b: 0,
        c: 1,
        d: 8,
        e: 1,
        f: 255,
    };

    /// Electricity forward active energy — register 2 (NT, Niedertarif).
    pub const STROM_BEZUG_NT: Self = Self {
        a: 1,
        b: 0,
        c: 1,
        d: 8,
        e: 2,
        f: 255,
    };

    /// Electricity reverse active energy — total (Einspeisung, kWh, gesamt).
    pub const STROM_EINSPEISUNG_TOTAL: Self = Self {
        a: 1,
        b: 0,
        c: 2,
        d: 8,
        e: 0,
        f: 255,
    };

    /// Electricity reverse active energy — register 1 (HT Einspeisung).
    pub const STROM_EINSPEISUNG_HT: Self = Self {
        a: 1,
        b: 0,
        c: 2,
        d: 8,
        e: 1,
        f: 255,
    };

    /// Electricity reverse active energy — register 2 (NT Einspeisung).
    pub const STROM_EINSPEISUNG_NT: Self = Self {
        a: 1,
        b: 0,
        c: 2,
        d: 8,
        e: 2,
        f: 255,
    };

    /// Active power demand, average over interval — 15-min Leistungsmittelwert (kW).
    pub const STROM_DEMAND_INTERVAL: Self = Self {
        a: 1,
        b: 0,
        c: 1,
        d: 29,
        e: 0,
        f: 255,
    };

    /// Reactive energy inductive (kvarh) — import direction.
    ///
    /// Used for RLM power quality monitoring and reactive energy billing.
    /// Source: IEC 62056-21, BDEW Lastenheft Smart Meter Gateway.
    pub const STROM_REACTIVE_INDUCTIVE: Self = Self {
        a: 1,
        b: 0,
        c: 3,
        d: 8,
        e: 0,
        f: 255,
    };

    /// Reactive energy capacitive (kvarh) — import direction.
    pub const STROM_REACTIVE_CAPACITIVE: Self = Self {
        a: 1,
        b: 0,
        c: 4,
        d: 8,
        e: 0,
        f: 255,
    };

    /// Reactive energy inductive (kvarh) — export direction.
    pub const STROM_REACTIVE_INDUCTIVE_EXPORT: Self = Self {
        a: 1,
        b: 0,
        c: 3,
        d: 9,
        e: 0,
        f: 255,
    };

    /// Reactive energy capacitive (kvarh) — export direction.
    pub const STROM_REACTIVE_CAPACITIVE_EXPORT: Self = Self {
        a: 1,
        b: 0,
        c: 4,
        d: 9,
        e: 0,
        f: 255,
    };

    /// Gas volume (m³, not yet converted to kWh_Hs).
    pub const GAS_VOLUME_M3: Self = Self {
        a: 7,
        b: 0,
        c: 3,
        d: 0,
        e: 0,
        f: 255,
    };

    /// Heat energy (kWh_th) — medium **6**, per the DLMS/COSEM Blue Book
    /// value-group-A list that OMS Spec Vol. 2 adopts.
    ///
    /// Medium 8 is *cold water*, not heat: see [`WASSER_KALT_VOLUME`]. Using
    /// A = 8 for a Wärmezähler puts the reading in the wrong Sparte, gives it
    /// water's daily default resolution instead of hourly, and makes
    /// [`is_heat`](Self::is_heat) report `false` for a heat register.
    ///
    /// [`WASSER_KALT_VOLUME`]: Self::WASSER_KALT_VOLUME
    pub const WAERME_ENERGY: Self = Self {
        a: 6,
        b: 0,
        c: 1,
        d: 0,
        e: 0,
        f: 255,
    };

    /// Cooling energy (kWh_th) — medium 5.
    pub const KAELTE_ENERGY: Self = Self {
        a: 5,
        b: 0,
        c: 1,
        d: 0,
        e: 0,
        f: 255,
    };

    /// Cold water volume (m³) — medium 8.
    pub const WASSER_KALT_VOLUME: Self = Self {
        a: 8,
        b: 0,
        c: 1,
        d: 0,
        e: 0,
        f: 255,
    };

    /// Hot water volume (m³) — medium 9.
    ///
    /// Billed as a volume; the heat share it apportions out of the building's
    /// heating bill is [`crate::warm_water_heat_kwh`] (HeizkostenV §9 Abs. 2).
    pub const WASSER_WARM_VOLUME: Self = Self {
        a: 9,
        b: 0,
        c: 1,
        d: 0,
        e: 0,
        f: 255,
    };

    /// `true` when this code refers to electricity (medium A = 1).
    #[must_use]
    pub fn is_electricity(&self) -> bool {
        self.a == 1
    }

    /// `true` when this code refers to gas (medium A = 7).
    #[must_use]
    pub fn is_gas(&self) -> bool {
        self.a == 7
    }

    /// `true` when this code refers to thermal energy — cooling (A = 5) or
    /// heat (A = 6).
    ///
    /// Media are numbered per the DLMS/COSEM Blue Book value-group-A list, which
    /// OMS Spec Vol. 2 adopts.
    #[must_use]
    pub fn is_heat(&self) -> bool {
        matches!(self.a, 5 | 6)
    }

    /// `true` when this code refers to water — cold (A = 8) or hot (A = 9).
    #[must_use]
    pub fn is_water(&self) -> bool {
        matches!(self.a, 8 | 9)
    }

    /// `true` when this code refers to a Heizkostenverteiler (A = 4).
    ///
    /// HCAs report dimensionless *Verbrauchseinheiten*, not a physical quantity.
    ///
    /// They carry **no Eichfrist**, because they are not Messgeräte under
    /// MessEG at all — "Heizkostenverteiler" appears nowhere in MessEV, neither
    /// in Anlage 1 nor in the Eichfristen of Anlage 7. HeizkostenV §5 Abs. 1
    /// admits them through an explicitly conditional clause — *"soweit nicht
    /// eichrechtliche Bestimmungen zur Anwendung kommen"* — requiring instead
    /// that an expert body confirm conformity with the anerkannte Regeln der
    /// Technik (EN 834 for evaporation, EN 835 for electronic HCAs).
    ///
    /// So an Eichfrist check must **skip** these devices rather than treat a
    /// missing date as an expiry.
    #[must_use]
    pub fn is_heat_cost_allocator(&self) -> bool {
        self.a == 4
    }

    /// `true` when this code measures reactive energy (C = 3 or C = 4 in IEC 62056-21).
    ///
    /// Reactive energy (kvarh) is required for:
    /// - Power factor billing (Blindstromberechnung) in industrial tariffs
    /// - Smart Meter Gateway power quality monitoring (BSI TR-03109)
    /// - RLM power quality records
    #[must_use]
    pub fn is_reactive(&self) -> bool {
        matches!(self.c, 3 | 4)
    }

    /// `true` when this code measures power demand (C = 1, D = 29 = max demand).
    ///
    /// Demand intervals (15-min Leistungsmittelwert) are used for:
    /// - Spitzenleistung billing (§18 Abs. 1 StromNEV)
    /// - RLM peak demand tracking
    #[must_use]
    pub fn is_demand(&self) -> bool {
        self.c == 1 && self.d == 29
    }

    /// `true` when this code represents import (forward) energy.
    ///
    /// In IEC 62056-21 / German OBIS practice:
    /// - `C=1, D=8` = forward active energy (Bezug, kWh import)
    /// - `D=8` always means "forward / import direction" in the measurement type field
    #[must_use]
    pub fn is_import(&self) -> bool {
        self.d == 8 && self.c == 1
    }

    /// `true` when this code represents reverse / export energy (Einspeisung).
    ///
    /// In IEC 62056-21 / German OBIS practice:
    /// - `C=2, D=8` = reverse active energy (Einspeisung, kWh export)
    /// - Note: `D=9` (reverse direction flag) is rarely used in German practice;
    ///   use `is_einspeisung()` for the commonly-used C=2 check.
    #[must_use]
    pub fn is_export(&self) -> bool {
        self.c == 2 && self.d == 8
    }

    /// `true` when this code represents Einspeisung (feed-in to the grid).
    ///
    /// Alias for `is_export()` using the German market terminology.
    /// Identifies `1-0:2.8.x*255` codes (reverse active energy).
    #[must_use]
    pub fn is_einspeisung(&self) -> bool {
        self.is_export()
    }

    /// Tariff register: `None` = total/combined, `Some(1)` = HT, `Some(2)` = NT.
    #[must_use]
    pub fn tariff_register(&self) -> Option<u8> {
        match self.e {
            0 => None,
            n => Some(n),
        }
    }

    /// `true` when this is the total / combined register (E = 0).
    #[must_use]
    pub fn is_total_register(&self) -> bool {
        self.e == 0
    }

    /// `true` when this is the HT (Hochtarif) register (E = 1).
    #[must_use]
    pub fn is_ht(&self) -> bool {
        self.e == 1
    }

    /// `true` when this is the NT (Niedertarif) register (E = 2).
    #[must_use]
    pub fn is_nt(&self) -> bool {
        self.e == 2
    }

    /// Default expected interval resolution for this OBIS code.
    ///
    /// RLM and iMSys electricity meters use 15-minute intervals.
    /// Gas meters and SLP typically use hourly or daily totals.
    /// Demand registers (D = 29) are always 15-minute.
    ///
    /// Returns `None` for codes where no standard resolution applies
    /// (e.g. cumulative registers, status codes).
    #[must_use]
    pub fn default_resolution(&self) -> Option<crate::resolution::IntervalResolution> {
        use crate::resolution::IntervalResolution;
        // Active energy electricity — RLM / iMSys: 15 min
        if self.a == 1 && (self.c == 1 || self.c == 2) && self.d == 8 {
            return Some(IntervalResolution::QuarterHour);
        }
        // Demand register (15-min average power)
        if self.a == 1 && self.d == 29 {
            return Some(IntervalResolution::QuarterHour);
        }
        // Reactive energy — usually 15-min alongside active
        if self.a == 1 && (self.c == 3 || self.c == 4) {
            return Some(IntervalResolution::QuarterHour);
        }
        // Gas volume — typically hourly or daily (SLP: daily, RLM Gas: hourly)
        if self.a == 7 {
            return Some(IntervalResolution::Hour);
        }
        // Thermal energy (cooling 5, heat 6) — usually hourly
        if matches!(self.a, 5 | 6) {
            return Some(IntervalResolution::Hour);
        }
        // Water (cold 8, hot 9) — submetering is read daily at best
        if matches!(self.a, 8 | 9) {
            return Some(IntervalResolution::Day);
        }
        None
    }

    /// Parse from a string slice (lenient: storage number `*F` is optional).
    ///
    /// # Errors
    ///
    /// Returns a [`ParseError`] when the string does not conform to OBIS format.
    pub fn parse(s: &str) -> Result<Self, ParseError> {
        s.parse()
    }
}

impl fmt::Display for ObisCode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{}-{}:{}.{}.{}*{}",
            self.a, self.b, self.c, self.d, self.e, self.f
        )
    }
}

impl From<ObisCode> for String {
    fn from(o: ObisCode) -> String {
        o.to_string()
    }
}

/// The shape [`ObisCode`] accepts, as rendered in a [`ParseError`].
const OBIS_FORMAT: &str = "A-B:C.D.E*F, e.g. 1-0:1.8.0*255 (the *F suffix is optional)";

impl FromStr for ObisCode {
    type Err = ParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        parse_obis(s).ok_or_else(|| ParseError::format("ObisCode", s, OBIS_FORMAT))
    }
}

impl TryFrom<&str> for ObisCode {
    type Error = ParseError;
    fn try_from(s: &str) -> Result<Self, Self::Error> {
        s.parse()
    }
}

// ── Lenient parser ────────────────────────────────────────────────────────────

fn parse_obis(s: &str) -> Option<ObisCode> {
    // Split A-B:C.D.E*F
    let (a_b, rest) = s.split_once('-')?;
    let (b_str, cd_ef) = rest.split_once(':')?;
    let a: u8 = a_b.parse().ok()?;
    let b: u8 = b_str.parse().ok()?;

    // C.D.E*F or C.D.E (storage optional)
    let (cde_str, f_str) = match cd_ef.split_once('*') {
        Some((l, r)) => (l, r),
        None => (cd_ef, "255"),
    };
    let f: u8 = f_str.parse().ok()?;

    let parts: Vec<&str> = cde_str.splitn(3, '.').collect();
    if parts.len() != 3 {
        return None;
    }
    let c: u8 = parts[0].parse().ok()?;
    let d: u8 = parts[1].parse().ok()?;
    let e: u8 = parts[2].parse().ok()?;

    Some(ObisCode { a, b, c, d, e, f })
}

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

    #[test]
    fn parse_standard_strom_bezug() {
        let code: ObisCode = "1-0:1.8.0*255".parse().unwrap();
        assert_eq!(code, ObisCode::STROM_BEZUG_TOTAL);
        assert!(code.is_electricity());
        assert!(code.is_import(), "1-0:1.8.0 C=1,D=8 should be import");
        assert!(code.is_total_register());
        assert!(!code.is_export());
    }

    #[test]
    fn parse_ht_register() {
        let code: ObisCode = "1-0:1.8.1*255".parse().unwrap();
        assert_eq!(code, ObisCode::STROM_BEZUG_HT);
        assert!(code.is_ht());
        assert!(!code.is_nt());
        assert_eq!(code.tariff_register(), Some(1));
    }

    #[test]
    fn parse_without_storage_number() {
        // *255 is optional — the parser defaults F to 255
        let code: ObisCode = "1-0:2.8.0".parse().unwrap();
        assert_eq!(code.f, 255);
        assert_eq!(code.c, 2);
        assert_eq!(code.d, 8);
        // C=2, D=8 = reverse active energy (Einspeisung)
        assert!(
            code.is_export(),
            "1-0:2.8.0 should be Einspeisung/export (C=2, D=8)"
        );
        assert!(code.is_einspeisung(), "should alias is_export()");
        assert_eq!(code, ObisCode::STROM_EINSPEISUNG_TOTAL);
    }

    #[test]
    fn parse_gas_volume() {
        let code: ObisCode = "7-0:3.0.0*255".parse().unwrap();
        assert_eq!(code, ObisCode::GAS_VOLUME_M3);
        assert!(code.is_gas());
        assert!(!code.is_electricity());
    }

    #[test]
    fn display_round_trip() {
        let s = "1-0:1.8.2*255";
        let code: ObisCode = s.parse().unwrap();
        assert_eq!(code.to_string(), s);
    }

    #[test]
    fn invalid_code_returns_error() {
        assert!("not-an-obis".parse::<ObisCode>().is_err());
        assert!("1-0:1.8".parse::<ObisCode>().is_err());
        assert!("".parse::<ObisCode>().is_err());
    }

    #[test]
    fn constants_are_correct() {
        assert_eq!(ObisCode::STROM_BEZUG_TOTAL.to_string(), "1-0:1.8.0*255");
        assert_eq!(ObisCode::STROM_BEZUG_HT.to_string(), "1-0:1.8.1*255");
        assert_eq!(ObisCode::STROM_BEZUG_NT.to_string(), "1-0:1.8.2*255");
        assert_eq!(
            ObisCode::STROM_EINSPEISUNG_TOTAL.to_string(),
            "1-0:2.8.0*255"
        );
        assert_eq!(ObisCode::GAS_VOLUME_M3.to_string(), "7-0:3.0.0*255");
    }
}

#[cfg(test)]
mod media_group_tests {
    use super::*;

    /// The value-group-A media list from the DLMS/COSEM Blue Book, which OMS
    /// Spec Vol. 2 adopts.
    #[test]
    fn medium_group_a_follows_the_dlms_media_list() {
        let hca: ObisCode = "4-0:1.0.0".parse().unwrap();
        let cooling: ObisCode = "5-0:1.0.0".parse().unwrap();
        let heat: ObisCode = "6-0:1.0.0".parse().unwrap();
        let gas: ObisCode = "7-0:3.0.0".parse().unwrap();
        let cold_water: ObisCode = "8-0:1.0.0".parse().unwrap();
        let hot_water: ObisCode = "9-0:1.0.0".parse().unwrap();

        assert!(hca.is_heat_cost_allocator());
        assert!(
            !hca.is_heat(),
            "an HCA measures Verbrauchseinheiten, not kWh"
        );

        assert!(cooling.is_heat() && heat.is_heat());
        assert!(gas.is_gas() && !gas.is_heat());

        assert!(cold_water.is_water() && hot_water.is_water());
        assert!(!cold_water.is_heat(), "A=8 is cold water");
    }

    /// Regression: every named constant must satisfy the predicate its name
    /// implies. `WAERME_ENERGY` was A = 8, which is cold water — so a heat
    /// register reported `is_water()` and inherited water's daily resolution.
    #[test]
    fn named_constants_match_their_medium_predicate() {
        assert!(ObisCode::WAERME_ENERGY.is_heat(), "heat is medium 6");
        assert!(!ObisCode::WAERME_ENERGY.is_water());
        assert_eq!(ObisCode::WAERME_ENERGY.to_string(), "6-0:1.0.0*255");

        assert!(ObisCode::KAELTE_ENERGY.is_heat(), "cooling is medium 5");

        assert!(ObisCode::WASSER_KALT_VOLUME.is_water());
        assert!(!ObisCode::WASSER_KALT_VOLUME.is_heat());
        assert!(ObisCode::WASSER_WARM_VOLUME.is_water());

        assert!(ObisCode::GAS_VOLUME_M3.is_gas());
        assert!(ObisCode::STROM_BEZUG_TOTAL.is_electricity());

        // ...and the resolution follows the medium, not the name.
        use crate::resolution::IntervalResolution;
        assert_eq!(
            ObisCode::WAERME_ENERGY.default_resolution(),
            Some(IntervalResolution::Hour),
            "a heat meter is read hourly, not daily like a water submeter"
        );
        assert_eq!(
            ObisCode::WASSER_KALT_VOLUME.default_resolution(),
            Some(IntervalResolution::Day)
        );
    }

    /// Water submetering is read daily at best — never on a 15-minute grid.
    #[test]
    fn water_defaults_to_daily_resolution() {
        use crate::resolution::IntervalResolution;
        let cold_water: ObisCode = "8-0:1.0.0".parse().unwrap();
        let heat: ObisCode = "6-0:1.0.0".parse().unwrap();
        assert_eq!(
            cold_water.default_resolution(),
            Some(IntervalResolution::Day)
        );
        assert_eq!(heat.default_resolution(), Some(IntervalResolution::Hour));
    }
}