Display_D_HP/TeamAAS-VM/Interfaces/ICalibrationService.cs

using System;
using System.Collections.Generic;
using TeamAAS_VP.Enums;
using TeamAAS_VP.Models.Calibration;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 校准信息管理（CRUD）接口。
    /// 提供对应用中校准数据的获取、添加/更新、删除以及持久化操作的抽象。
    /// 实现应负责数据存储细节（内存、文件、数据库等），并在 Dispose 中释放任何非托管资源或订阅。
    /// </summary>
    public interface ICalibrationService : IDisposable
    {
        /// <summary>
        /// 获取所有已知的校准信息的只读集合。
        /// </summary>
        /// <returns>
        /// 包含当前所有校准项的只读集合；集合本身不能为空，但可以为空集合。
        /// 集合的实现应保证对调用者只读（不应暴露可变集合引用）。
        /// </returns>
        IReadOnlyCollection<CalibrationInfo> GetAllCalibrations();

        /// <summary>
        /// 根据标识符获取单个校准信息。
        /// </summary>
        /// <param name="id">要查找的校准信息的唯一标识符（<see cref="Guid"/>）。</param>
        /// <returns>
        /// 对应的 <see cref="CalibrationInfo"/> 实例；若不存在则返回 <c>null</c>。
        /// </returns>
        CalibrationInfo GetCalibration(Guid id);

        /// <summary>
        /// 添加新的校准信息或更新已有的校准信息。
        /// </summary>
        /// <param name="calib">要添加或更新的校准信息对象；其 <see cref="CalibrationInfo"/> 内部应包含用于识别的标识字段。</param>
        /// <returns>
        /// 添加或更新后存储的 <see cref="CalibrationInfo"/> 实例（可能包含由存储层填充的字段，如创建时间、标识等）。
        /// 实现应保证返回的对象反映当前持久化状态。
        /// </returns>
        /// <remarks>
        /// 调用方应负责验证传入对象的有效性（例如必填字段），实现也可在内部进行额外验证并抛出相应异常。
        /// </remarks>
        CalibrationInfo AddOrUpdateCalibration(CalibrationInfo calib);

        /// <summary>
        /// 删除指定标识符对应的校准信息。
        /// </summary>
        /// <param name="id">要删除的校准信息的唯一标识符（<see cref="Guid"/>）。</param>
        /// <returns>
        /// 如果找到并成功删除则返回 <c>true</c>；如果未找到该标识或删除失败则返回 <c>false</c>。
        /// </returns>
        bool RemoveCalibration(Guid id);

        // 文件加载/保存

        /// <summary>
        /// 从持久化存储加载所有校准信息并替换当前内存中的集合。
        /// </summary>
        /// <remarks>
        /// 实现应在加载失败时记录错误或抛出异常；若为耗时操作，调用方应在合适的线程/任务中调用本方法。
        /// 方法语义为同步加载；如需异步支持，可在实现中提供额外的异步方法。
        /// </remarks>
        void LoadAll();

        /// <summary>
        /// 将当前内存中的所有校准信息保存到持久化存储。
        /// </summary>
        /// <remarks>
        /// 实现应保证原子性或在文档中说明保存策略；若为耗时操作，调用方应在合适的线程/任务中调用本方法。
        /// </remarks>
        void SaveAll();

        /// <summary>
        /// 校准转换，将像素坐标转换位置坐标
        /// </summary>
        /// <param name="pixelCoord"></param>
        /// <param name="robotCoord"></param>
        /// <param name="calib"></param>
        /// <returns></returns>
        (bool IsSucceed, double X, double Y, double U) ConvertPixelToPosition((double X, double Y,double angle) pixelCoord, double[] robotCoord, CalibrationInfo calib, RobotBrand robotBrand = RobotBrand.Default);

        /// <summary>
        /// 校准转换，将像素坐标转换位置坐标
        /// </summary>
        /// <param name="pixelCoord"></param>
        /// <param name="robotCoord"></param>
        /// <param name="calibId"></param>
        /// <returns></returns>
        (bool IsSucceed, double X, double Y, double U) ConvertPixelToPosition((double X, double Y, double angle) pixelCoord, double[] robotCoord, Guid calibId, RobotBrand robotBrand = RobotBrand.Default);
    }
}