ThreatSourceLibaray/ThreatSource/src/Simulation/SimulationElement.cs

namespace ThreatSource.Simulation
{
    /// <summary>
    /// 仿真元素的抽象基类，所有仿真中的实体都继承自此类
    /// </summary>
    /// <remarks>
    /// 该类提供了仿真实体的基本功能的默认实现：
    /// - 运动学状态管理 (通过 KinematicState)
    /// - 生命周期管理（激活/停用）
    /// - 事件发布机制
    /// - 状态更新机制
    /// - 频谱特性管理
    /// 所有具体的仿真实体（如导弹、目标等）都应继承此类并实现其抽象方法。
    /// </remarks>
    public abstract class SimulationElement : ISimulationElement
    {
        /// <inheritdoc/>
        public virtual string Id { get; set; }

        /// <inheritdoc/>
        public virtual KinematicState KState { get; protected set; }

        /// <inheritdoc/>
        public virtual bool IsActive { get; protected set; }

        /// <summary>
        /// 获取或设置仿真管理器的引用
        /// </summary>
        /// <remarks>
        /// 用于访问仿真系统的核心功能，如事件发布、实体查询等
        /// 在构造函数中初始化，整个生命周期内保持不变
        /// </remarks>
        protected ISimulationManager SimulationManager { get; set; }

        /// <summary>
        /// 初始化仿真元素的新实例
        /// </summary>
        /// <param name="id">仿真元素的唯一标识符</param>
        /// <param name="kinematicState">初始运动学状态 (现在是 KinematicState)</param>
        /// <param name="simulationManager">仿真管理器实例</param>
        /// <remarks>
        /// 构造函数设置实体的初始状态：
        /// - 根据ID和 KinematicState 初始化实体
        /// - 设置初始状态为未激活
        /// </remarks>
        protected SimulationElement(string id, KinematicState kinematicState, ISimulationManager simulationManager)
        {
            Id = id;
            KState = kinematicState;
            SimulationManager = simulationManager;
            IsActive = false;
        }

        /// <summary>
        /// 更新仿真元素的状态
        /// </summary>
        /// <param name="deltaTime">时间步长，单位：秒</param>
        /// <remarks>
        /// 抽象方法，需要在派生类中实现具体的更新逻辑：
        /// - 更新 KinematicState (位置、速度、朝向等)
        /// - 处理碰撞和其他物理效果
        /// - 触发相关事件
        /// </remarks>
        public abstract void Update(double deltaTime);

        /// <summary>
        /// 获取仿真元素的状态信息
        /// </summary>
        /// <returns>包含实体当前状态的字符串描述</returns>
        /// <remarks>
        /// 返回的字符串包含：
        /// - 实体类型
        /// - 实体ID
        /// - 当前 KinematicState (位置、朝向等)
        /// - 活动状态
        /// </remarks>
        public virtual string GetStatus()
        {
            return GetStatusInfo().ToString();
        }
        
        /// <inheritdoc/>
        public virtual ElementStatusInfo GetStatusInfo()
        {
            var statusInfo = new ElementStatusInfo
            {
                Id = Id,
                ElementType = GetType().Name,
                KState = KState,
                IsActive = IsActive
            };
            
            return statusInfo;
        }

        /// <summary>
        /// 发布仿真事件到事件系统
        /// </summary>
        /// <param name="evt">要发布的事件实例</param>
        /// <remarks>
        /// 在发布事件前会：
        /// - 设置事件的发送者ID
        /// - 添加时间戳
        /// - 通过仿真管理器发布到事件系统
        /// </remarks>
        protected void PublishEvent<T>(T evt) where T : SimulationEvent
        {
            ArgumentNullException.ThrowIfNull(evt);
            evt.SenderId = Id;
            SimulationManager.PublishEvent(evt);
        }

        /// <summary>
        /// 激活仿真元素，使其参与仿真
        /// </summary>
        /// <remarks>
        /// 激活操作会：
        /// - 将IsActive设置为true
        /// - 发布实体激活事件 (可选, 如果有此设计)
        /// - 允许实体参与仿真计算
        /// </remarks>
        public virtual void Activate()
        {
            if (!IsActive)
            {
                IsActive = true;
            }
        }
    
        /// <summary>
        /// 停用仿真元素，将其从仿真中移除
        /// </summary>
        /// <remarks>
        /// 停用操作会：
        /// - 将IsActive设置为false
        /// - 发布实体停用事件 (可选, 如果有此设计)
        /// - 停止实体参与仿真计算
        /// </remarks>
        public virtual void Deactivate()
        {
            if (IsActive)
            {
                IsActive = false;
            }
        }
    }
}