using System;
using MultiWheelC.TrajectoryPlanning.CoarsePath;

namespace MultiWheelC.TrajectoryPlanning.EMPlanner;

/// <summary>
/// 调用方一次性捕获的车辆运动状态；EMPlanner 只消费此快照，不直接读取定位、轮速或系统时钟。
/// </summary>
public sealed class VehicleMotionState
{
    /// <summary>
    /// 保存调用方捕获的车辆状态。构造器不校验 null、数值有限性、UTC 时效或序列号；服务在接受请求前负责验证，传入 <paramref name="pose"/> 的所有权仍归调用方。
    /// </summary>
    public VehicleMotionState(
        Pose2D pose,
        double signedLongitudinalSpeedMetersPerSecond,
        double? longitudinalAccelerationMetersPerSecondSquared,
        DateTimeOffset capturedAtUtc,
        long sequenceId)
    {
        Pose = pose;
        SignedLongitudinalSpeedMetersPerSecond = signedLongitudinalSpeedMetersPerSecond;
        LongitudinalAccelerationMetersPerSecondSquared = longitudinalAccelerationMetersPerSecondSquared;
        CapturedAtUtc = capturedAtUtc;
        SequenceId = sequenceId;
    }

    /// <summary>
    /// 车辆世界位姿引用，其中位置单位为 m、航向单位为 rad；构造器允许 null，但服务要求有效位姿。
    /// </summary>
    public Pose2D Pose { get; }

    /// <summary>
    /// 沿车辆前向轴的有符号纵向速度，单位 m/s；正负方向约定由上游状态生产者负责，服务要求其为有限数。
    /// </summary>
    public double SignedLongitudinalSpeedMetersPerSecond { get; }

    /// <summary>
    /// 可选的沿车辆前向轴纵向加速度，单位 m/s²；null 表示采集方未提供该量，非 null 值必须由服务验证为有限数。
    /// </summary>
    public double? LongitudinalAccelerationMetersPerSecondSquared { get; }

    /// <summary>
    /// 采集此状态的 UTC 时刻；服务用它相对请求发起时刻判断状态是否过期。
    /// </summary>
    public DateTimeOffset CapturedAtUtc { get; }

    /// <summary>
    /// 调用方提供的状态快照序列版本；服务要求其非负，成功轨迹将其写入元数据供消费者关联。
    /// </summary>
    public long SequenceId { get; }
}