//
//  IDVLogger.h
//  AliyunIdentityUtils
//
//  统一埋点日志工具：logEvent 将事件缓存在内存，并在上报前自动合并公共维度字段
//  （region / networkType / carrier / sdkVersion / appVersion / endpoint）；
//  由 Platform 层通过 flushHandler 注入上报实现（复用 UploadDeviceInfosIntl 通道），
//  以支撑监控按地区、网络、版本、链路下钻分析。
//

#ifndef IDVLogger_h
#define IDVLogger_h

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/// 埋点日志级别
typedef NS_ENUM(NSInteger, IDVLogLevel) {
    IDVLogLevelInfo  = 0,  // 默认级别，所有环境均上报
    IDVLogLevelDebug = 1,  // 调试级别，仅 logLevel=debug 时上报
};

/**
 * @brief 监控上下文提供者协议
 *
 * @discussion
 *  Utils 层无法直接依赖 Platform 层（避免循环依赖），因此通过协议反向获取
 *  当前命中的服务端域名等运行时上下文。Platform 层在 SDK 初始化时通过
 *  `+[IDVLogger setContextProvider:]` 注册实现。
 */
@protocol IDVMonitorContextProvider <NSObject>
@optional
/// 当前命中的 saf 服务域名（含 scheme），用于按域名/地区聚合监控
- (nullable NSString *)currentEndpoint;
@end

/**
 * @brief 统一埋点日志工具
 *
 * @discussion
 *  调用方使用本类统一收口事件埋点调用。
 *  本类会在每次上报前自动合并以下公共维度字段：
 *    - region       当前设备地区代码（NSLocaleCountryCode），如 US/SG/MY
 *    - networkType  当前网络类型：WiFi / Cellular / None
 *    - carrier      运营商名称（iOS 16+ 系统限制可能为空）
 *    - sdkVersion   SDK 版本号（由 Platform 层在初始化时注入）
 *    - appVersion   宿主 App 版本号
 *    - endpoint     当前命中的服务域名（通过 IDVMonitorContextProvider 协议获取）
 *
 *  合并策略：若业务 bizParams 中已存在同名 key，业务字段优先（不会被公共字段覆盖）。
 */
@interface IDVLogger : NSObject

/// 注册上下文提供者，通常由 Platform 层在 SDK 初始化时调用一次
+ (void)setContextProvider:(nullable id<IDVMonitorContextProvider>)provider;

/// 注入 SDK 版本号（Utils 模块无法直接读取 Platform 层的 SDK_VERSION 宏，需由调用方注入）
+ (void)setSdkVersion:(nullable NSString *)sdkVersion;

/// 统一日志接口（默认 Info 级别）
/// @param eventName 事件名
/// @param bizParams 业务参数字典，可为 nil
+ (void)logEvent:(NSString *)eventName bizParams:(nullable NSDictionary *)bizParams;

/// 统一日志接口（显式指定级别）
/// @param eventName 事件名
/// @param level     日志级别：IDVLogLevelInfo / IDVLogLevelDebug
/// @param bizParams 业务参数字典，可为 nil
+ (void)logEvent:(NSString *)eventName level:(IDVLogLevel)level bizParams:(nullable NSDictionary *)bizParams;

/// 注册事件上报处理器：由 Platform 层在 SDK 初始化时注入，内部通过
/// UploadDeviceInfosIntl 网络接口批量上传。Utils 层不直接依赖 Platform，
/// 借此协议式回调打通上报链路，避免循环依赖。
/// @param handler 接收待上报事件数组（每个元素含 actionName 及各维度字段）
+ (void)setFlushHandler:(nullable void (^)(NSArray<NSDictionary *> *events))handler;

/// 主动触发一次上报：取出当前缓存的全部事件交给 flushHandler 并清空缓存。
/// 若尚未注册 flushHandler，则保留缓存事件，待注册后再次 flush 时上报。
+ (void)flush;

@end

NS_ASSUME_NONNULL_END

#endif /* IDVLogger_h */
