XplorePlane/XP.Hardware.MotionControl/Services/IMotionControlService.cs

using System.Collections.Generic;
using XP.Hardware.MotionControl.Abstractions;
using XP.Hardware.MotionControl.Abstractions.Enums;

namespace XP.Hardware.MotionControl.Services
{
    /// <summary>
    /// 运动控制业务服务接口 | Motion Control Business Service Interface
    /// 封装所有运动控制业务规则，供 ViewModel 调用 | Encapsulates all motion control business rules for ViewModel
    /// </summary>
    public interface IMotionControlService
    {
        #region 轮询控制 | Polling Control

        /// <summary>
        /// 启动 PLC 状态轮询 | Start PLC status polling
        /// 以配置的 PollingInterval 周期执行轮询 | Polls at configured PollingInterval
        /// </summary>
        void StartPolling();

        /// <summary>
        /// 停止 PLC 状态轮询 | Stop PLC status polling
        /// </summary>
        void StopPolling();

        #endregion

        #region 单轴移动 | Single Axis Move

        /// <summary>
        /// 移动直线轴到目标位置 | Move linear axis to target position
        /// 包含边界检查和运动中防重入 | Includes boundary check and move-in-progress guard
        /// </summary>
        /// <param name="axisId">直线轴标识 | Linear axis identifier</param>
        /// <param name="target">目标位置（mm）| Target position (mm)</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult MoveToTarget(AxisId axisId, double target, double? speed = null);

        /// <summary>
        /// 移动旋转轴到目标角度 | Move rotary axis to target angle
        /// 包含边界检查和禁用轴检查 | Includes boundary check and disabled axis check
        /// </summary>
        /// <param name="axisId">旋转轴标识 | Rotary axis identifier</param>
        /// <param name="targetAngle">目标角度（度）| Target angle (degrees)</param>
        /// <param name="speed">运动速度（可选，不传则不写入速度信号）| Speed (optional)</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult MoveRotaryToTarget(RotaryAxisId axisId, double targetAngle, double? speed = null);

        #endregion

        #region 多轴联动 | Multi-Axis Coordinated Move

        /// <summary>
        /// 多轴联动移动 | Multi-axis coordinated move
        /// 对所有目标轴并行执行边界检查，任意轴越界则拒绝整个命令 | Atomic boundary check for all target axes
        /// </summary>
        /// <param name="targets">轴标识与目标位置的字典 | Dictionary of axis IDs and target positions</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult MoveAllToTarget(Dictionary<AxisId, double> targets);

        /// <summary>
        /// 停止所有已启用轴 | Stop all enabled axes
        /// </summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult StopAll();

        /// <summary>
        /// 所有已启用轴回零 | Home all enabled axes
        /// </summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult HomeAll();

        #endregion

        #region Jog 控制 | Jog Control

        /// <summary>
        /// 直线轴 Jog 启动 | Start linear axis jog
        /// Homing 状态下拒绝 Jog 命令 | Rejects jog when axis is homing
        /// </summary>
        /// <param name="axisId">直线轴标识 | Linear axis identifier</param>
        /// <param name="positive">正向为 true，反向为 false | True for positive, false for negative</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult JogStart(AxisId axisId, bool positive);

        /// <summary>
        /// 直线轴 Jog 停止 | Stop linear axis jog
        /// </summary>
        /// <param name="axisId">直线轴标识 | Linear axis identifier</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult JogStop(AxisId axisId);

        /// <summary>
        /// 旋转轴 Jog 启动 | Start rotary axis jog
        /// Homing 状态下拒绝 Jog 命令 | Rejects jog when axis is homing
        /// </summary>
        /// <param name="axisId">旋转轴标识 | Rotary axis identifier</param>
        /// <param name="positive">正向为 true，反向为 false | True for positive, false for negative</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult JogRotaryStart(RotaryAxisId axisId, bool positive);

        /// <summary>
        /// 旋转轴 Jog 停止 | Stop rotary axis jog
        /// </summary>
        /// <param name="axisId">旋转轴标识 | Rotary axis identifier</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult JogRotaryStop(RotaryAxisId axisId);

        #endregion

        #region 安全门控制 | Safety Door Control

        /// <summary>
        /// 开门（含联锁检查）| Open door (with interlock check)
        /// 联锁信号有效时拒绝开门 | Rejects when interlock is active
        /// </summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult OpenDoor();

        /// <summary>
        /// 关门 | Close door
        /// </summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult CloseDoor();

        /// <summary>
        /// 停止门运动 | Stop door movement
        /// </summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult StopDoor();

        #endregion

        #region 几何计算 | Geometry Calculation

        /// <summary>
        /// 获取当前几何参数（正算）| Get current geometry parameters (forward calculation)
        /// 根据当前轴位置计算 FOD、FDD 和放大倍率 | Calculates FOD, FDD and magnification from current axis positions
        /// </summary>
        /// <returns>FOD（mm）、FDD（mm）、放大倍率 | FOD (mm), FDD (mm), Magnification</returns>
        (double FOD, double FDD, double Magnification) GetCurrentGeometry();

        /// <summary>
        /// 应用几何参数（反算，由 FOD 和 FDD）| Apply geometry (inverse, from FOD and FDD)
        /// 计算并移动 SourceZ 和 DetectorZ 到目标位置 | Calculates and moves SourceZ and DetectorZ to target positions
        /// </summary>
        /// <param name="targetFOD">目标 FOD（mm）| Target FOD (mm)</param>
        /// <param name="targetFDD">目标 FDD（mm）| Target FDD (mm)</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult ApplyGeometry(double targetFOD, double targetFDD);

        /// <summary>
        /// 几何反算（仅计算，不移动）| Geometry inverse calculation (calculate only, no move)
        /// 返回 SourceZ 和 DetectorZ 的目标位置 | Returns target positions for SourceZ and DetectorZ
        /// </summary>
        /// <param name="targetFOD">目标 FOD（mm）| Target FOD (mm)</param>
        /// <param name="targetFDD">目标 FDD（mm）| Target FDD (mm)</param>
        /// <returns>成功时返回 (sourceZTarget, detectorZTarget, null)，失败时返回 (0, 0, errorMessage) | On success returns targets, on failure returns error</returns>
        (double SourceZTarget, double DetectorZTarget, string ErrorMessage) CalculateGeometryTargets(double targetFOD, double targetFDD);

        /// <summary>
        /// 应用几何参数（反算，由 FOD 和放大倍率）| Apply geometry (inverse, from FOD and magnification)
        /// 先计算 FDD = M × FOD，再移动轴 | Calculates FDD = M × FOD, then moves axes
        /// </summary>
        /// <param name="targetFOD">目标 FOD（mm）| Target FOD (mm)</param>
        /// <param name="magnification">目标放大倍率 | Target magnification</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult ApplyGeometryByMagnification(double targetFOD, double magnification);

        #endregion
    }
}