playVideo_ios/AICityProperty/AICity/JuXing/Services/JXAnalytics.h

//
//  JXAnalytics.h
//  AICity
//
//  Feature: 003-ios-api-https
//  Task: T062 - iOS数据上报客户端
//  Created on 2025-10-14.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * 设备信息
 */
@interface JXDeviceInfo : NSObject

@property (nonatomic, strong) NSString *deviceType;
@property (nonatomic, strong) NSString *deviceModel;
@property (nonatomic, strong) NSString *osVersion;
@property (nonatomic, strong) NSString *appVersion;

@end

/**
 * 分析事件
 */
@interface JXAnalyticsEvent : NSObject

@property (nonatomic, strong) NSString *eventType;
@property (nonatomic, strong) NSString *dramaId;
@property (nonatomic, strong) NSString *episodeId;
@property (nonatomic, assign) NSInteger playDuration;
@property (nonatomic, assign) BOOL isCompleted;
@property (nonatomic, assign) BOOL isMember;
@property (nonatomic, strong) JXDeviceInfo *deviceInfo;
@property (nonatomic, assign) NSTimeInterval timestamp;
@property (nonatomic, assign) NSInteger retryCount;

@end

/**
 * 上报状态
 */
typedef NS_ENUM(NSInteger, JXReportingStatus) {
    JXReportingStatusIdle,
    JXReportingStatusReporting,
    JXReportingStatusSuccess,
    JXReportingStatusError
};

/**
 * 队列状态
 */
@interface JXQueueStatus : NSObject

@property (nonatomic, assign) NSInteger queueSize;
@property (nonatomic, assign) NSInteger maxQueueSize;
@property (nonatomic, assign) JXReportingStatus reportingStatus;
@property (nonatomic, strong, nullable) NSString *errorMessage;
@property (nonatomic, assign) NSInteger lastSuccessCount;

- (BOOL)isQueueFull;
- (NSInteger)queueUsagePercent;

@end

/**
 * 剧星数据上报客户端
 * 
 * 功能：
 * - 播放事件收集和上报
 * - 本地队列缓存
 * - 批量上报优化
 * - 网络状态感知
 */
@interface JXAnalytics : NSObject

/**
 * 单例实例
 */
+ (instancetype)sharedAnalytics;

/**
 * 当前上报状态
 */
@property (nonatomic, assign, readonly) JXReportingStatus reportingStatus;

/**
 * 上报播放开始事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 */
- (void)reportPlayStartWithDramaId:(NSString *)dramaId episodeId:(NSString *)episodeId;

/**
 * 上报播放进度事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 * @param playDuration 播放时长（秒）
 */
- (void)reportPlayProgressWithDramaId:(NSString *)dramaId 
                            episodeId:(NSString *)episodeId 
                         playDuration:(NSInteger)playDuration;

/**
 * 上报播放完成事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 * @param playDuration 播放时长（秒）
 * @param isMember 是否为会员
 */
- (void)reportPlayCompleteWithDramaId:(NSString *)dramaId 
                            episodeId:(NSString *)episodeId 
                         playDuration:(NSInteger)playDuration 
                             isMember:(BOOL)isMember;

/**
 * 上报用户行为事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 * @param actionType 行为类型
 */
- (void)reportUserActionWithDramaId:(NSString *)dramaId 
                          episodeId:(NSString *)episodeId 
                         actionType:(NSString *)actionType;

/**
 * 上报点赞事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 */
- (void)reportLikeWithDramaId:(NSString *)dramaId episodeId:(NSString *)episodeId;

/**
 * 上报收藏事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 */
- (void)reportFavoriteWithDramaId:(NSString *)dramaId episodeId:(NSString *)episodeId;

/**
 * 上报分享事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 * @param shareType 分享类型
 */
- (void)reportShareWithDramaId:(NSString *)dramaId 
                     episodeId:(NSString *)episodeId 
                     shareType:(NSString *)shareType;

/**
 * 上报关注事件
 * @param dramaId 剧ID
 */
- (void)reportFollowWithDramaId:(NSString *)dramaId;

/**
 * 上报评论事件
 * @param dramaId 剧ID
 * @param episodeId 剧集ID
 */
- (void)reportCommentWithDramaId:(NSString *)dramaId episodeId:(NSString *)episodeId;

/**
 * 立即上报所有事件
 */
- (void)flushEvents;

/**
 * 获取队列状态
 * @return 队列状态信息
 */
- (JXQueueStatus *)getQueueStatus;

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

/**
 * 添加状态变更监听
 * @param observer 观察者
 * @param selector 回调方法
 */
- (void)addStatusObserver:(id)observer selector:(SEL)selector;

/**
 * 移除状态变更监听
 * @param observer 观察者
 */
- (void)removeStatusObserver:(id)observer;

@end

NS_ASSUME_NONNULL_END