using System;

namespace MultiWheelC.TrajectoryPlanning.EMPlanner;

/// <summary>
/// 一次 EM 规划的不可变结果。只有成功状态才携带可发布的完整轨迹；其余状态仅提供诊断，不能作为部分执行轨迹消费。
/// </summary>
public sealed class EmPlanningResult
{
    /// <summary>
    /// 创建规划结果并强制成功状态与轨迹发布的一致性：<see cref="EmPlanningStatus.Success"/> 和 <see cref="EmPlanningStatus.SuccessWithFallback"/> 必须提供非 null 轨迹，其他状态必须提供 null 轨迹；null 失败原因规范化为空字符串。
    /// </summary>
    public EmPlanningResult(EmPlanningStatus status, EmTrajectory trajectory, string failureReason)
    {
        if (!Enum.IsDefined(typeof(EmPlanningStatus), status))
            throw new ArgumentOutOfRangeException(nameof(status));

        bool isSuccess = status == EmPlanningStatus.Success || status == EmPlanningStatus.SuccessWithFallback;
        if (isSuccess && trajectory == null)
            throw new ArgumentException("Successful results require a trajectory.", nameof(trajectory));
        if (!isSuccess && trajectory != null)
            throw new ArgumentException("Only successful results may contain a trajectory.", nameof(trajectory));

        Status = status;
        Trajectory = trajectory;
        FailureReason = failureReason ?? string.Empty;
    }

    /// <summary>
    /// 本次规划的最终状态；消费者必须先判断其是否为成功状态，再访问可发布轨迹。
    /// </summary>
    public EmPlanningStatus Status { get; }

    /// <summary>
    /// 仅在成功或成功降级状态下存在的完整可发布轨迹；失败、取消和无效输入结果始终为 null，消费者不得把失败结果当作部分轨迹执行。
    /// </summary>
    public EmTrajectory Trajectory { get; }

    /// <summary>
    /// 面向诊断的失败或降级原因；null 输入已规范化为空字符串，不替代 <see cref="Status"/> 的机器可读状态。
    /// </summary>
    public string FailureReason { get; }
}