namespace XP.Hardware.RaySource.Services
{
    /// <summary>
    /// 灯丝寿命管理服务接口 | Filament Lifetime Management Service Interface
    /// 负责灯丝使用时长的记录、计算、异常恢复和预警判断
    /// Responsible for filament usage duration recording, calculation, anomaly recovery, and warning evaluation
    /// </summary>
    public interface IFilamentLifetimeService
    {
        /// <summary>
        /// 是否已成功初始化 | Whether the service has been successfully initialized
        /// </summary>
        bool IsInitialized { get; }

        /// <summary>
        /// 灯丝是否处于开启状态 | Whether the filament is currently on
        /// </summary>
        bool IsFilamentOn { get; }

        /// <summary>
        /// 初始化服务（建表、异常恢复、重算累计寿命）
        /// Initialize service (create tables, recover anomalies, recalculate accumulated lifetime)
        /// </summary>
        /// <returns>是否初始化成功 | Whether initialization succeeded</returns>
        bool Initialize();

        /// <summary>
        /// 开始灯丝使用记录 | Start filament usage recording
        /// </summary>
        /// <returns>是否成功 | Whether the operation succeeded</returns>
        bool StartFilamentUsage();

        /// <summary>
        /// 停止灯丝使用记录 | Stop filament usage recording
        /// </summary>
        /// <returns>是否成功 | Whether the operation succeeded</returns>
        bool StopFilamentUsage();

        /// <summary>
        /// 获取数据库中的累计使用秒数 | Get accumulated usage seconds from database
        /// </summary>
        /// <returns>累计使用秒数 | Accumulated usage seconds</returns>
        double GetTotalLifeSeconds();

        /// <summary>
        /// 获取当前实时累计使用秒数（含本次运行时长）
        /// Get real-time total seconds (including current session duration)
        /// </summary>
        /// <returns>实时累计秒数 | Real-time accumulated seconds</returns>
        double GetCurrentTotalLifeSeconds();

        /// <summary>
        /// 获取寿命阈值（秒）| Get lifetime threshold in seconds
        /// </summary>
        /// <returns>阈值秒数 | Threshold in seconds</returns>
        double GetThresholdSeconds();

        /// <summary>
        /// 获取当前寿命使用百分比（0-100）
        /// Get current lifetime usage percentage (0-100)
        /// </summary>
        /// <returns>寿命百分比 | Lifetime percentage</returns>
        double GetLifetimePercentage();

        /// <summary>
        /// 检查是否需要弹出寿命预警（百分比 >= 90%）
        /// Check if lifetime warning should be shown (percentage >= 90%)
        /// </summary>
        /// <returns>是否需要预警 | Whether warning should be shown</returns>
        bool ShouldShowLifetimeWarning();
    }
}