XplorePlane/XP.Hardware.RaySource/Services/IRaySourceService.cs

using System;
using XP.Hardware.RaySource.Abstractions;
using XP.Hardware.RaySource.Abstractions.Enums;

namespace XP.Hardware.RaySource.Services
{
    /// <summary>
    /// 射线源业务服务接口 | X-Ray Source Business Service Interface
    /// 封装初始化、操作调度、状态管理和业务规则校验 | Encapsulates initialization, operation dispatch, status management, and business rule validation
    /// </summary>
    public interface IRaySourceService : IDisposable
    {
        /// <summary>
        /// 当前射线源实例 | Current X-ray source instance
        /// </summary>
        IXRaySource CurrentSource { get; }

        /// <summary>
        /// 是否已初始化 | Is initialized
        /// </summary>
        bool IsInitialized { get; }

        /// <summary>
        /// PVI 变量是否已连接 | Whether PVI variables are connected
        /// </summary>
        bool IsConnected { get; }

        /// <summary>
        /// 是否射线开启 | Is X-ray on
        /// </summary>
        bool IsXRayOn { get; }

        /// <summary>
        /// 当前射线源状态 | Current X-ray source status
        /// </summary>
        RaySourceStatus CurrentStatus { get; }

        /// <summary>
        /// 初始化射线源（射线源类型从配置文件读取）| Initialize X-ray source (source type read from configuration)
        /// </summary>
        XRayResult Initialize();

        /// <summary>
        /// 连接变量并启动实时状态通讯 | Connect variables and start real-time status communication
        /// </summary>
        XRayResult ConnectVariables();

        /// <summary>
        /// 断开射线源连接 | Disconnect X-ray source
        /// </summary>
        XRayResult Disconnect();

        /// <summary>
        /// 开启射线 | Turn on X-ray
        /// </summary>
        XRayResult TurnOn();

        /// <summary>
        /// 关闭射线 | Turn off X-ray
        /// </summary>
        XRayResult TurnOff();

        /// <summary>
        /// 紧急关闭（最高优先级）| Emergency shutdown (highest priority)
        /// </summary>
        XRayResult EmergencyShutdown();

        /// <summary>
        /// 设置电压 | Set voltage
        /// </summary>
        /// <param name="voltage">电压值（kV）| Voltage value (kV)</param>
        XRayResult SetVoltage(float voltage);

        /// <summary>
        /// 设置电流 | Set current
        /// </summary>
        /// <param name="current">电流值（μA）| Current value (μA)</param>
        XRayResult SetCurrent(float current);

        /// <summary>
        /// 读取实际电压 | Read actual voltage
        /// </summary>
        XRayResult ReadVoltage();

        /// <summary>
        /// 读取实际电流 | Read actual current
        /// </summary>
        XRayResult ReadCurrent();

        /// <summary>
        /// 读取系统状态 | Read system status
        /// </summary>
        XRayResult ReadSystemStatus();

        /// <summary>
        /// 检查错误 | Check errors
        /// </summary>
        XRayResult CheckErrors();

        /// <summary>
        /// 清除错误 | Clear errors
        /// </summary>
        XRayResult ClearErrors();

        /// <summary>
        /// TXI 开启 | TXI On
        /// </summary>
        XRayResult TxiOn();

        /// <summary>
        /// TXI 关闭 | TXI Off
        /// </summary>
        XRayResult TxiOff();

        /// <summary>
        /// 暖机设置 | Warm-up setting
        /// </summary>
        XRayResult WarmUp();

        /// <summary>
        /// 训机设置 | Training setting
        /// </summary>
        XRayResult Training();

        /// <summary>
        /// 灯丝校准 | Filament calibration
        /// </summary>
        XRayResult FilamentCalibration();

        /// <summary>
        /// 全部电压自动定心 | Auto-center all voltages
        /// </summary>
        XRayResult AutoCenter();

        /// <summary>
        /// 设置功率模式 | Set power mode
        /// </summary>
        /// <param name="mode">功率模式值：1=Micro Focus，2=High Power</param>
        XRayResult SetPowerMode(int mode);

        /// <summary>
        /// 异步执行初始化 + 连接变量的完整流程 | Async full sequence: Initialize + ConnectVariables
        /// 供 ViewModel 在界面加载时调用，避免阻塞 UI 线程 | For ViewModel to call on view loaded without blocking UI
        /// </summary>
        /// <returns>最终操作结果 | Final operation result</returns>
        System.Threading.Tasks.Task<XRayResult> InitializeAndConnectAsync();
    }
}