//
//  BannerScheduler.h
//  YuMi
//
//  Created by AI Assistant on 2025/1/13.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

@class BannerScheduler;

/**
 * Banner 播放调度器代理协议
 * 负责处理具体的 Banner 播放逻辑
 */
@protocol BannerSchedulerDelegate <NSObject>

@required
/**
 * 调度器要求播放指定的 Banner
 * @param scheduler 调度器实例
 * @param banner 要播放的 Banner 数据
 */
- (void)bannerScheduler:(BannerScheduler *)scheduler 
    shouldPlayBanner:(id)banner;

@optional
/**
 * 调度器完成播放 Banner
 * @param scheduler 调度器实例
 */
- (void)bannerSchedulerDidFinishPlaying:(BannerScheduler *)scheduler;

/**
 * 调度器开始播放 Banner
 * @param scheduler 调度器实例
 * @param banner 开始播放的 Banner 数据
 */
- (void)bannerScheduler:(BannerScheduler *)scheduler 
    didStartPlayingBanner:(id)banner;

@end

/**
 * Banner 播放调度器
 * 统一管理 V2 Banner 的播放队列和状态
 */
@interface BannerScheduler : NSObject

/**
 * Banner 播放队列
 */
@property (nonatomic, strong, readonly) NSMutableArray *bannerQueue;

/**
 * 当前是否正在播放 Banner
 */
@property (nonatomic, assign, readonly) BOOL isPlaying;

/**
 * 调度器代理
 */
@property (nonatomic, weak) id<BannerSchedulerDelegate> delegate;

/**
 * 队列中的 Banner 数量
 */
@property (nonatomic, assign, readonly) NSInteger queueCount;

/**
 * 初始化调度器
 * @param delegate 代理对象
 * @return 调度器实例
 */
- (instancetype)initWithDelegate:(id<BannerSchedulerDelegate>)delegate;

/**
 * 将 Banner 添加到播放队列
 * @param banner Banner 数据
 */
- (void)enqueueBanner:(id)banner;

/**
 * 处理队列中的下一个 Banner
 */
- (void)processNextBanner;

/**
 * 清空播放队列
 */
- (void)clearQueue;

/**
 * 根据优先级对队列进行排序
 */
- (void)sortQueueByPriority;

/**
 * 暂停播放（保持队列状态）
 */
- (void)pause;

/**
 * 恢复播放
 */
- (void)resume;

/**
 * 检查队列是否为空
 * @return 队列是否为空
 */
- (BOOL)isQueueEmpty;

/**
 * 获取队列中指定索引的 Banner
 * @param index 索引
 * @return Banner 数据，如果索引无效则返回 nil
 */
- (nullable id)bannerAtIndex:(NSInteger)index;

/**
 * 移除队列中指定索引的 Banner
 * @param index 索引
 * @return 是否移除成功
 */
- (BOOL)removeBannerAtIndex:(NSInteger)index;

/**
 * 获取队列状态信息（用于调试）
 * @return 状态信息字符串
 */
- (NSString *)queueStatusDescription;

/**
 * 标记 Banner 播放完成
 * 这个方法应该由代理在 Banner 播放完成后调用
 */
- (void)markBannerFinished;

- (NSString *)debugStatus;

@end

NS_ASSUME_NONNULL_END