Display_D_HP/TeamAAS-VM/Interfaces/IMesService.cs

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// MES 通信服务接口。
    /// 提供通过配置的 URL 发起 GET 请求的抽象，用于执行过站（Station）与提交结果（Submit）操作。
    /// 实现者应负责管理内部 HTTP 客户端或通信资源，并在 Dispose 中释放这些资源。
    /// </summary>
    public interface IMesService : IDisposable
    {
        /// <summary>
        /// 使用配置的过站（Station）URL 发起 GET 请求，携带序列号（sn）作为查询参数进行过站。
        /// </summary>
        /// <param name="sn">要过站的产品序列号，不能为空或空白。</param>
        /// <param name="cancellationToken">用于在外部请求取消时中止异步请求的 <see cref="CancellationToken"/>。默认值为 <see cref="CancellationToken.None"/>。</param>
        /// <returns>
        /// 一个包含请求结果的元组：
        /// IsSuccess 表示请求并解析 MES 响应是否被认为成功（由实现定义，例如 HTTP 200 且业务状态正常）。
        /// Response 为 MES 返回的原始响应字符串或描述错误的信息（不为 null，可为空字符串）。
        /// </returns>
        /// <remarks>
        /// - 实现应从配置中读取过站 URL 并将 sn 作为查询参数附加到 URL。
        /// - 实现应尊重 <paramref name="cancellationToken"/>，在取消时尽早抛出 <see cref="OperationCanceledException"/> 或返回失败结果。
        /// - 若 <paramref name="sn"/> 无效，应抛出 <see cref="ArgumentNullException"/> 或 <see cref="ArgumentException"/>。
        /// </remarks>
        Task<(bool IsSuccess, string Response)> StationGetAsync(int deviceNo, string sn, string comp, CancellationToken cancellationToken = default);

        /// <summary>
        /// 使用配置的过站（Station）URL 发起 GET 请求，携带序列号（sn）作为查询参数进行过站，并使用指定的超时时间（秒）。
        /// </summary>
        /// <param name="sn">要过站的产品序列号，不能为空或空白。</param>
        /// <param name="timeoutInSeconds">请求超时时间，单位为秒。应为正数；实现可以将其应用到 HTTP 客户端或请求级别超时。</param>
        /// <returns>
        /// 一个包含请求结果的元组：
        /// IsSuccess 表示请求并解析 MES 响应是否被认为成功。
        /// Response 为 MES 返回的原始响应字符串或描述错误的信息。
        /// </returns>
        /// <remarks>
        /// - 此重载方便在不使用 <see cref="CancellationToken"/> 的场景中指定超时时间。
        /// - 实现应验证 <paramref name="timeoutInSeconds"/> 为合理值（例如 > 0），否则可抛出 <see cref="ArgumentOutOfRangeException"/>。
        /// </remarks>
        Task<(bool IsSuccess, string Response)> StationGetAsync(int deviceNo, string sn, string comp, double timeoutInSeconds);

        /// <summary>
        /// 过站请求的扩展版本，允许同时指定 <see cref="CancellationToken"/> 和超时时间（秒）。实现应优先考虑取消请求，但在未取消的情况下应用超时。
        /// </summary>
        /// <param name="sn"></param>
        /// <param name="comp"></param>
        /// <param name="timeoutInSeconds"></param>
        /// <returns></returns>
        Task<(bool IsSuccess, string Response)> StationGetExAsync(int deviceNo, string sn, string comp, double timeoutInSeconds);

        /// <summary>
        /// 过站请求的扩展版本，允许同时指定 <see cref="CancellationToken"/> 和超时时间（秒）。实现应优先考虑取消请求，但在未取消的情况下应用超时。
        /// </summary>
        /// <param name="sn"></param>
        /// <param name="comp"></param>
        /// <param name="timeoutInSeconds"></param>
        /// <returns></returns>
        Task<(bool IsSuccess, string Response)> StationGetEx2Async(int deviceNo, string partSN, string comp, double timeoutInSeconds);

        /// <summary>
        /// 使用配置的提交（Submit）URL 发起 GET 请求，提交过站结果及时间信息。
        /// </summary>
        /// <param name="sn">待提交的产品序列号，不能为空或空白。</param>
        /// <param name="isSuccess">表示该序列号对应的过站是否成功（业务层面的成功标志）。</param>
        /// <param name="start_time">过程开始时间（本地时间或 UTC，取决于与 MES 的约定）。实现方应按与 MES 约定的时区/格式发送。</param>
        /// <param name="stop_time">过程结束时间，语义同 <paramref name="start_time"/>。</param>
        /// <param name="cancellationToken">用于在外部请求取消时中止异步请求的 <see cref="CancellationToken"/>。默认值为 <see cref="CancellationToken.None"/>。</param>
        /// <returns>
        /// 一个包含请求结果的元组：
        /// IsSuccess 表示提交请求及解析 MES 响应是否被认为成功。
        /// Response 为 MES 返回的原始响应字符串或描述错误的信息。
        /// </returns>
        /// <remarks>
        /// - 实现应将时间参数按 MES 要求格式化为查询字符串或适当的请求参数。
        /// - 若 <paramref name="start_time"/> 晚于 <paramref name="stop_time"/>，实现应记录并视情况返回失败或抛出异常。
        /// - 实现应尊重 <paramref name="cancellationToken"/>，并在取消时尽早中止请求。
        /// </remarks>
        Task<(bool IsSuccess, string Response)> SubmitGetAsync(int deviceNo, string sn, string comp, List<string> results, string cc, string assypress, bool isSuccess, DateTime start_time, DateTime stop_time, CancellationToken cancellationToken = default);

        /// <summary>
        /// 使用配置的提交（Submit）URL 发起 GET 请求，提交过站结果及时间信息，并使用指定的超时时间（秒）。
        /// </summary>
        /// <param name="sn">待提交的产品序列号，不能为空或空白。</param>
        /// <param name="isSuccess">表示该序列号对应的过站是否成功。</param>
        /// <param name="start_time">过程开始时间。</param>
        /// <param name="stop_time">过程结束时间。</param>
        /// <param name="timeoutInSeconds">请求超时时间，单位为秒。应为正数。</param>
        /// <returns>
        /// 一个包含请求结果的元组：
        /// IsSuccess 指示提交是否被认为成功。
        /// Response 包含 MES 的原始响应或错误信息。
        /// </returns>
        /// <remarks>
        /// - 此重载用于在不传入 <see cref="CancellationToken"/> 的场景中指定超时时间。
        /// - 实现应确保对时间参数与布尔参数进行适当的 URL 编码或格式化。
        /// </remarks>
        Task<(bool IsSuccess, string Response)> SubmitGetAsync(int deviceNo, string sn, string comp, List<string> results, string cc, string assypress, bool isSuccess, DateTime start_time, DateTime stop_time, double timeoutInSeconds);

        /// <summary>
        /// 获取服务器当前时间
        /// </summary>
        /// <param name="sn"></param>
        /// <param name="timeoutInSeconds"></param>
        /// <returns></returns>
        Task<(bool IsSuccess, DateTime Now)> GetServerTimeAsync(int deviceNo, string sn, double timeoutInSeconds);

        /// <summary>
        /// 上传log
        /// </summary>
        /// <param name="sn"></param>
        /// <param name="name"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<(bool IsSuccess, string Response)> SendFtpFileAsync(string sn, string name, CancellationToken cancellationToken = default);
    }
}