#region << 版 本 注 释 >>
/*----------------------------------------------------------------
 * 命名空间：WIDESEAWCS_ITaskInfoService
 * 创建者：胡童庆
 * 创建时间：2024/8/2 16:13:36
 * 版本：V1.0.0
 * 描述：
 *
 * ----------------------------------------------------------------
 * 修改人：
 * 修改时间：
 * 版本：V1.0.1
 * 修改说明：
 * 
 *----------------------------------------------------------------*/
#endregion << 版 本 注 释 >>

using OfficeOpenXml.FormulaParsing.Excel.Functions.Math;
using SqlSugar;
using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using WIDESEAWCS_Core;
using WIDESEAWCS_Core.BaseServices;
using WIDESEAWCS_Core.Enums;
using WIDESEAWCS_DTO.BasicInfo;
using WIDESEAWCS_Model.Models;

namespace WIDESEAWCS_ITaskInfoService
{
    public interface ITaskService : IService<Dt_Task>
    {
        /// <summary>
        /// 查询指定门架设备未执行的任务
        /// </summary>
        /// <param name="gantryDeviceNo">门架设备编号</param>
        /// <returns>未执行的任务数据，若不存在则返回null</returns>
        Dt_Task? QueryAGantryUnExecuteTask(string gantryDeviceNo);

        /// <summary>
        /// 执行订单块放置测试，根据订单行ID获取订单明细并计算放置位置
        /// </summary>
        /// <param name="orderRowId">订单行ID</param>
        /// <returns>包含放置块信息的Web响应内容。成功时返回放置块列表，失败时返回错误信息</returns>
        /// <remarks>
        /// 1. 通过订单行ID查询订单明细数据 <br/>
        /// 2. 对每个有效订单明细计算合适的放置位置 <br/>
        /// 3. 创建容器项和任务记录 <br/>
        /// 4. 通过WebSocket发布放置位置信息 <br/>
        /// 5. 返回所有成功放置的块信息
        /// </remarks>
        WebResponseContent PlaceBlockTest(int orderRowId);

        /// <summary>
        /// 创建任务并计算物品放置位置
        /// </summary>
        /// <param name="takePosition">取货位置编码</param>
        /// <param name="putPosition">放货位置编码</param>
        /// <param name="deviceCode">设备编码</param>
        /// <param name="length">物品长度</param>
        /// <param name="width">物品宽度</param>
        /// <param name="height">物品高度</param>
        /// <returns>包含操作结果的Web响应内容</returns>
        /// <remarks>
        /// 1. 验证取货/放货位置是否存在 <br/>
        /// 2. 计算物品在容器中的最佳放置位置 <br/>
        /// 3. 创建容器物品记录和任务记录 <br/>
        /// 4. 通过WebSocket通知客户端
        /// </remarks>
        WebResponseContent CreateTask(string takePosition, string putPosition, string deviceCode, int length, int width, int height);

        /// <summary>
        /// 根据订单信息生成任务
        /// </summary>
        /// <param name="orderInfo">订单信息</param>
        /// <returns>包含三个值的元组： <br/>
        /// Item1 - 操作是否成功 (bool) <br/>
        /// Item2 - 生成的任务对象 (Dt_Task)，失败时为null <br/>
        /// Item3 - 错误消息 (string)，成功时为空字符串
        /// </returns>
        /// <remarks>
        /// 该方法会： <br/>
        /// 1. 根据订单尺寸获取合适的货位 <br/>
        /// 2. 创建容器项和任务记录 <br/>
        /// 3. 更新相关容器状态 <br/>
        /// 4. 在事务中执行所有数据库操作
        /// </remarks>
        (bool, Dt_Task?, string) GenerateTask(OrderInfo orderInfo);

        /// <summary>
        /// 重新生成任务
        /// </summary>
        /// <param name="task">原始任务对象</param>
        /// <param name="stationCode">工作站编码</param>
        /// <returns>
        /// 包含三个值的元组： <br/>
        /// 1. bool - 操作是否成功 <br/>
        /// 2. Dt_Task - 更新后的任务对象（失败时为null） <br/>
        /// 3. string - 错误消息（成功时为空字符串）
        /// </returns>
        /// <remarks>
        /// 该方法用于重新生成任务信息，包括： <br/>
        /// 1. 解析板子尺寸信息 <br/>
        /// 2. 验证取货/放货位置 <br/>
        /// 3. 计算物品放置位置 <br/>
        /// 4. 更新任务状态和位置信息 <br/>
        /// 5. 在事务中更新数据库记录
        /// </remarks>
        (bool, Dt_Task?, string) RegenerateTask(Dt_Task task, string stationCode);

        /// <summary>
        /// 生成异常任务
        /// </summary>
        /// <param name="orderInfo">订单信息</param>
        /// <returns>元组包含三个值： <br/>
        /// Item1 - 操作是否成功（bool） <br/>
        /// Item2 - 生成的任务对象（Dt_Task），失败时为null <br/>
        /// Item3 - 错误消息（string），成功时为空字符串</returns>
        /// <remarks>
        /// 该方法会根据订单信息生成一个异常处理任务，包括： <br/>
        /// 1. 获取异常位置 <br/>
        /// 2. 验证放货/取货位置 <br/>
        /// 3. 创建容器项和任务记录 <br/>
        /// 4. 提交事务
        /// </remarks>
        (bool, Dt_Task?, string) GenerateExceptionTask(OrderInfo orderInfo);

        /// <summary>
        /// 根据设备编号获取取货位置
        /// </summary>
        /// <param name="deviceCode">设备编号</param>
        /// <returns>符合条件的容器对象，若找不到则返回null</returns>
        /// <remarks>
        /// 1. 首先查询指定设备下所有可用的取货容器，并按ContainerSort升序排序 <br/>
        /// 2. 查找该设备最近的任务记录 <br/>
        /// 3. 如果找到任务记录，则根据任务源地址匹配容器，返回下一个容器(若已是最后一个则返回第一个) <br/>
        /// 4. 如果出现异常或未找到匹配项，则返回第一个可用容器
        /// </remarks>
        Dt_Container? GetTakePosition(string deviceCode);

        /// <summary>
        /// 任务完成处理方法
        /// </summary>
        /// <param name="task">任务实体</param>
        /// <returns>Web响应内容</returns>
        /// <remarks>
        /// 1. 更新任务状态为"龙门架完成" <br/>
        /// 2. 更新相关订单详情状态为"码垛成功" <br/>
        /// 3. 更新订单行中的托盘数量 <br/>
        /// 4. 根据任务完成情况发送WebSocket通知 <br/>
        /// 5. 记录操作日志并提交事务 <br/>
        /// 6. 异常时回滚事务并返回错误信息
        /// </remarks>
        WebResponseContent TaskComplete(Dt_Task task);
    }
}