namespace MultiWheelC.TrajectoryPlanning.Mapping;

/// <summary>
/// 提供一次性障碍物快照的纯数据来源。
///
/// 注意：<see cref="ProjectToWorld"/> 不得读取传感器、定位、UI 或时钟；调用前应由上层采集并封装完整快照。
/// </summary>
public interface IMapObstacleSource
{
    /// <summary>来源的稳定唯一标识。不能为空；同一次建图请求中不得重复。</summary>
    string SourceId { get; }
    /// <summary>来源快照版本号，必须非负。快照几何或有效性变化时必须递增，以使输入缓存失效。</summary>
    long SourceVersion { get; }
    /// <summary>该来源是否必需。true 时不可用或无效会使整张地图构建失败；false 时只记录状态。</summary>
    bool IsRequired { get; }
    /// <summary>
    /// 将已采集的快照投影为世界障碍物几何。
    ///
    /// 返回：世界坐标、单位 mm 的障碍物及其状态；不得访问任何实时外部状态。
    /// </summary>
    ObstacleProjectionResult ProjectToWorld();
}