namespace CapMachine.Wpf.Services
{
    /// <summary>
    /// PPC 热力计算所需底层物性能力接口。
    /// </summary>
    /// <remarks>
    /// 该接口用于把具体的 REFPROP 调用细节从上层计算逻辑中解耦出来，
    /// 使 <see cref="PPCService"/>、<see cref="PPCSuperheatSubcoolCalculator"/>、
    /// <see cref="PPCThermodynamicSixResultsCalculator"/> 只关注“流程与公式”，
    /// 而不直接依赖 REFPROP API 的调用顺序、单位换算与错误处理。
    ///
    /// 设计约定：
    /// 1. 所有方法都采用 Try 风格，返回 <see langword="true"/> 表示成功得到结果。
    /// 2. 返回 <see langword="false"/> 时，输出参数通常为未定义值，调用方应以 <paramref name="error"/> 为准。
    /// 3. 方法名中显式写出主要输入路径与单位，便于上层按状态点流程对照调用。
    /// 4. 本接口只定义“物性支持能力”，不定义具体业务公式。
    /// </remarks>
    public interface IPPCCalculationSupport
    {
        /// <summary>
        /// 确保 REFPROP 已完成初始化。
        /// </summary>
        /// <param name="error">初始化失败原因，例如路径错误、流体文件不可用或底层库调用异常。</param>
        /// <returns>是否初始化成功，或已经处于可用状态。</returns>
        bool EnsureRefpropInitialized(out string error);

        /// <summary>
        /// 由压力求饱和状态参数。
        /// </summary>
        /// <param name="pressureMPa">输入压力，单位 MPa（绝压）。</param>
        /// <param name="tSatK">输出饱和温度，单位 K。</param>
        /// <param name="Dl_molL">输出饱和液相摩尔密度，单位 mol/L。</param>
        /// <param name="Dv_molL">输出饱和气相摩尔密度，单位 mol/L。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法通常用于过热度/过冷度计算中的“由压力反查饱和温度”步骤。
        /// </remarks>
        bool TrySATP_SaturationByP_MPa(
            double pressureMPa,
            out double tSatK,
            out double Dl_molL,
            out double Dv_molL,
            out string error);

        /// <summary>
        /// 由气相压力/温度状态点求摩尔密度。
        /// </summary>
        /// <param name="pressureMPa">输入压力，单位 MPa（绝压）。</param>
        /// <param name="temperatureC">输入温度，单位 ℃。</param>
        /// <param name="densityMolPerL">输出摩尔密度，单位 mol/L。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法对应气相路径的 TPRHO 调用，常用于吸气点、排气点等过热蒸汽状态点计算。
        /// </remarks>
        bool TryTPRHO_VaporDensity_ByTP_MPa_C(
            double pressureMPa,
            double temperatureC,
            out double densityMolPerL,
            out string error);

        /// <summary>
        /// 由气相温度/密度状态点求质量比熵。
        /// </summary>
        /// <param name="temperatureC">输入温度，单位 ℃。</param>
        /// <param name="densityMolPerL">输入摩尔密度，单位 mol/L。</param>
        /// <param name="entropy_kJ_per_kgK">输出质量比熵，单位 kJ/(kg·K)。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法通常用于得到吸气点熵 s1，供后续等熵出口焓 h2s 计算使用。
        /// </remarks>
        bool TryTHERM_VaporEntropy_ByTD(
            double temperatureC,
            double densityMolPerL,
            out double entropy_kJ_per_kgK,
            out string error);

        /// <summary>
        /// 由液相压力/温度状态点求摩尔密度。
        /// </summary>
        /// <param name="pressureMPa">输入压力，单位 MPa（绝压）。</param>
        /// <param name="temperatureC">输入温度，单位 ℃。</param>
        /// <param name="densityMolPerL">输出摩尔密度，单位 mol/L。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法对应液相路径的 TPRHO 调用，常用于膨胀阀前液路状态点计算。
        /// </remarks>
        bool TryTPRHO_LiquidDensity_ByTP_MPa_C(
            double pressureMPa,
            double temperatureC,
            out double densityMolPerL,
            out string error);

        /// <summary>
        /// 由液相温度/密度状态点求质量比焓。
        /// </summary>
        /// <param name="temperatureC">输入温度，单位 ℃。</param>
        /// <param name="densityMolPerL">输入摩尔密度，单位 mol/L。</param>
        /// <param name="h_liq_kJ_per_kg">输出液相质量比焓，单位 kJ/kg。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法常用于液路点 h3 计算。
        /// </remarks>
        bool TryTHERM_LiquidEnthalpy_ByTD(
            double temperatureC,
            double densityMolPerL,
            out double h_liq_kJ_per_kg,
            out string error);

        /// <summary>
        /// 由温度/密度状态点求质量比焓。
        /// </summary>
        /// <param name="temperatureK">输入温度，单位 K。</param>
        /// <param name="densityMolPerL">输入摩尔密度，单位 mol/L。</param>
        /// <param name="h_kJ_per_kg">输出质量比焓，单位 kJ/kg。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法在 PPC 当前实现中主要用于气相状态点的焓计算，例如 h1、h2。
        /// </remarks>
        bool TryTHERM_Enthalpy_kJkg_ByT_K_D(
            double temperatureK,
            double densityMolPerL,
            out double h_kJ_per_kg,
            out string error);

        /// <summary>
        /// 将摩尔密度换算为质量比容。
        /// </summary>
        /// <param name="d_molL">输入摩尔密度，单位 mol/L。</param>
        /// <param name="v_m3kg">输出质量比容，单位 m³/kg。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否换算成功。</returns>
        /// <remarks>
        /// 该方法通常用于由吸气点摩尔密度换算得到吸气比容 v1，供容积效率计算使用。
        /// </remarks>
        bool TryConvertMolarDensityToSpecificVolume(double d_molL, out double v_m3kg, out string error);

        /// <summary>
        /// 由排气压力与吸气熵求等熵出口焓 h2s。
        /// </summary>
        /// <param name="dischargePressureBarA">排气压力 P2，单位 BarA（绝压）。</param>
        /// <param name="suctionEntropy_kJkgK">吸气熵 s1，单位 kJ/(kg·K)。</param>
        /// <param name="h2s_kJkg">输出等熵出口焓 h2s，单位 kJ/kg。</param>
        /// <param name="error">失败原因。</param>
        /// <returns>是否求取成功。</returns>
        /// <remarks>
        /// 该方法封装了由 <c>P2 + s1</c> 反查等熵压缩终点焓值的过程，
        /// 供等熵效率计算公式 <c>(h2s - h1) / (h2 - h1)</c> 使用。
        /// </remarks>
        bool TryGetIsentropicOutletEnthalpy_h2s_ByP2AndS1_BarA(
            double dischargePressureBarA,
            double suctionEntropy_kJkgK,
            out double h2s_kJkg,
            out string error);
    }
}