ThreatSourceLibaray/ThreatSource/src/Sensor/Sensor.cs

using ThreatSource.Jammable;
using ThreatSource.Jammer;
using ThreatSource.Simulation;
namespace ThreatSource.Sensor
{
    /// <summary>
    /// 定义传感器的基本接口，规范了所有传感器的通用功能
    /// </summary>
    /// <remarks>
    /// 该接口提供了传感器的基本功能规范：
    /// - 激活和停用控制
    /// - 状态更新机制
    /// - 数据采集接口
    /// 是所有具体传感器实现的基础
    /// </remarks>
    public interface ISensor
    {
        /// <summary>
        /// 获取传感器采集的最新数据
        /// </summary>
        /// <returns>包含传感器测量结果的数据对象</returns>
        /// <remarks>
        /// 返回数据：
        /// - 测量的物理量
        /// - 时间戳信息
        /// - 状态标志
        /// </remarks>
        SensorData GetSensorData();
    }

    /// <summary>
    /// 传感器的抽象基类，实现了ISensor接口的基本功能
    /// </summary>
    /// <remarks>
    /// 该类提供了传感器的通用实现：
    /// - 位置和姿态管理
    /// - 激活状态控制
    /// - 数据采集框架
    /// - 干扰处理机制
    /// 是具体传感器类的实现基础
    /// </remarks>
    public abstract class Sensor : SimulationElement, ISensor, IJammable
    {
        /// <summary>
        /// 干扰处理组件
        /// </summary>
        protected readonly JammableComponent _jammingComponent;

        /// <summary>
        /// 获取设备支持的干扰类型
        /// </summary>
        /// <remarks>
        /// 定义传感器可以被哪些类型的干扰影响
        /// 子类需要重写此属性以指定支持的干扰类型
        /// </remarks>
        public abstract IEnumerable<JammingType> SupportedJammingTypes { get; }

        /// <summary>
        /// 获取设备当前是否处于被干扰状态
        /// </summary>
        public bool IsJammed => _jammingComponent.IsJammed;

        /// <summary>
        /// 初始化传感器的新实例
        /// </summary>
        /// <param name="id">传感器的ID</param>
        /// <param name="motionParameters">传感器的初始运动参数</param>
        /// <param name="simulationManager">仿真管理器实例</param>
        /// <remarks>
        /// 构造过程：
        /// - 设置初始位置
        /// - 设置初始朝向
        /// - 设置初始速度
        /// - 初始化工作状态
        /// - 创建干扰处理组件
        /// </remarks>
        protected Sensor(string id, MotionParameters motionParameters, ISimulationManager simulationManager)
            : base(id, motionParameters, simulationManager)
        {
            IsActive = false;
            
            // 初始化干扰处理组件
            _jammingComponent = new JammableComponent(
                positionProvider: () => Position
            );
            
            // Subscribe to the events instead
            _jammingComponent.JammingApplied += HandleJammingApplied;
            _jammingComponent.JammingCleared += HandleJammingCleared;
        }

        /// <summary>
        /// 初始化干扰阈值和支持的干扰类型
        /// </summary>
        /// <param name="jammingResistanceThreshold">干扰抗性阈值，单位：瓦特</param>
        /// <param name="supportedTypes">支持的干扰类型</param>
        protected void InitializeJamming(double jammingResistanceThreshold, IEnumerable<JammingType> supportedTypes)
        {
            _jammingComponent.LoadJammingConfigFromThreshold(jammingResistanceThreshold, supportedTypes);
        }

        /// <summary>
        /// 处理传感器被干扰的事件
        /// </summary>
        /// <param name="parameters">干扰参数</param>
        /// <remarks>
        /// 当传感器受到干扰时调用
        /// 子类可以重写以实现特定的干扰响应
        /// </remarks>
        protected virtual void HandleJammingApplied(JammingParameters parameters)
        {
            // 子类可以重写此方法以实现特定的干扰响应
            System.Diagnostics.Debug.WriteLine($"传感器受到{parameters.Type}类型干扰，功率：{parameters.Power}W");
        }

        /// <summary>
        /// 处理传感器干扰被清除的事件
        /// </summary>
        /// <param name="type">被清除的干扰类型</param>
        /// <remarks>
        /// 当干扰被清除时调用
        /// 子类可以重写以实现干扰清除后的特定行为
        /// </remarks>
        protected virtual void HandleJammingCleared(JammingType type)
        {
            // 子类可以重写此方法以实现干扰清除后的特定行为
            System.Diagnostics.Debug.WriteLine($"传感器{type}类型干扰已清除");
        }

        /// <summary>
        /// 更新传感器状态
        /// </summary>
        /// <param name="deltaTime">时间步长，单位：秒</param>
        /// <remarks>
        /// 更新过程：
        /// - 更新干扰状态
        /// - 如果激活且未被干扰，调用UpdateSensor
        /// 
        /// 注意：子类应当重写UpdateSensor方法而非覆盖此方法。
        /// 如果确实需要覆盖此方法，应确保调用base.Update(deltaTime)
        /// </remarks>
        public override void Update(double deltaTime)
        {
            // 更新干扰状态
            _jammingComponent.UpdateJammingStatus(deltaTime);

            if (IsActive)
            {
                // 如果未被干扰，执行传感器特定的更新逻辑
                if (!IsJammed)
                {
                    UpdateSensor(deltaTime);
                }
            }
        }

        /// <summary>
        /// 更新传感器特定功能
        /// </summary>
        /// <param name="deltaTime">时间步长，单位：秒</param>
        /// <remarks>
        /// 子类必须重写此方法以实现特定的更新逻辑。
        /// 该方法只有在传感器激活且未被干扰时才会被调用。
        /// 
        /// 实现指南：
        /// 1. 在此方法中执行传感器特有的更新逻辑
        /// 2. 更新数据采集和处理
        /// 3. 不需要检查IsActive或IsJammed，基类已处理
        /// 4. 不需要调用基类实现，此方法在基类中为空实现
        /// </remarks>
        protected virtual void UpdateSensor(double deltaTime)
        {
            // 子类中实现具体的传感器更新逻辑
        }

        /// <summary>
        /// 统一处理干扰事件
        /// </summary>
        /// <param name="evt">干扰事件</param>
        protected virtual void HandleJammingEvent(JammingEvent evt)
        {
            if (evt == null) return;

            // 在应用干扰前检查是否应该处理此干扰
            if (!ShouldHandleJamming(evt.Parameters))
            {
                // 可选择记录日志：Debug.WriteLine($"传感器 {Id} 忽略干扰事件，类型: {evt.Parameters.Type}");
                return; 
            }

            // 如果应该处理，则应用干扰
            ApplyJamming(evt.Parameters);
        }

        /// <summary>
        /// 判断是否应该处理传入的干扰参数（可被子类重写以添加特定检查）
        /// </summary>
        /// <param name="parameters">干扰参数</param>
        /// <returns>如果应该处理则返回 true，否则返回 false</returns>
        protected virtual bool ShouldHandleJamming(JammingParameters parameters)
        {
            // 基类默认处理所有受支持类型的干扰
            // 子类可以重写此方法添加额外检查，如波段匹配
            return SupportedJammingTypes.Contains(parameters.Type);
        }

        /// <summary>
        /// 应用干扰
        /// </summary>
        /// <param name="parameters">干扰参数</param>
        /// <remarks>
        /// 处理对传感器的干扰影响
        /// 只有支持的干扰类型才会被处理
        /// </remarks>
        public virtual void ApplyJamming(JammingParameters parameters)
        {
            _jammingComponent.ApplyJamming(parameters);
        }

        /// <summary>
        /// 清除干扰
        /// </summary>
        /// <param name="type">要清除的干扰类型</param>
        /// <remarks>
        /// 移除特定类型的干扰影响
        /// 恢复传感器的正常工作状态
        /// </remarks>
        public virtual void ClearJamming(JammingType type)
        {
            _jammingComponent.ClearJamming(type);
        }

        /// <summary>
        /// 获取传感器数据（需要在子类中实现）
        /// </summary>
        /// <returns>包含传感器测量结果的数据对象</returns>
        /// <remarks>
        /// 数据要求：
        /// - 包含最新测量结果
        /// - 附加时间戳信息
        /// - 提供状态标志
        /// - 确保数据有效性
        /// </remarks>
        public abstract SensorData GetSensorData();

        /// <summary>
        /// 激活传感器
        /// </summary>
        public override void Activate()
        {
             if (!IsActive)
            {
                IsActive = true;
                // 统一订阅 HandleJammingEvent
                SimulationManager.SubscribeToEvent<JammingEvent>(HandleJammingEvent);
                // 移除可能存在的旧订阅（如果子类之前有单独订阅）
            }
            base.Activate();
        }

        /// <summary>
        /// 停用传感器
        /// </summary>
        public override void Deactivate()
        {
             if (IsActive)
            {
                IsActive = false;
                // 统一取消订阅 HandleJammingEvent
                SimulationManager.UnsubscribeFromEvent<JammingEvent>(HandleJammingEvent);
                 // 移除可能存在的旧取消订阅
            }
            base.Deactivate();
        }
    }
}