import 'package:sino_med_cloud/push/push_message.dart';

import '../core/constants/app_enum.dart';

/// 推送服务接口
/// 
/// 定义了推送服务的核心功能，包括初始化、别名管理、标签管理和消息监听等
abstract class PushService {
  /// 初始化推送服务
  /// 
  /// 在应用启动时调用，用于初始化推送 SDK 和注册事件处理器
  /// 
  /// 抛出异常：
  /// - 如果初始化失败，会抛出相应的异常
  Future<void> init();

  /// 设置用户别名
  /// 
  /// 别名是用于标识用户的唯一标识符，可以用来向特定用户推送消息
  /// 
  /// 参数：
  /// - [alias] 用户别名，不能为空
  /// 
  /// 抛出异常：
  /// - 如果设置失败，会抛出相应的异常
  Future<void> setAlias(String alias);

  /// 删除用户别名
  /// 
  /// 删除当前用户已设置的别名
  /// 
  /// 抛出异常：
  /// - 如果删除失败，会抛出相应的异常
  Future<void> deleteAlias();

  /// 添加标签
  /// 
  /// 在原有标签的基础上添加新的标签，用于对用户进行分组推送
  /// 
  /// 参数：
  /// - [tags] 要添加的标签列表，不能为空
  /// 
  /// 抛出异常：
  /// - 如果添加失败，会抛出相应的异常
  Future<void> addTags(List<String> tags);

  /// 清空所有标签
  /// 
  /// 删除当前用户的所有标签
  /// 
  /// 抛出异常：
  /// - 如果清空失败，会抛出相应的异常
  Future<void> cleanTags();

  /// 监听推送消息
  /// 
  /// 根据指定的消息类型返回对应的消息流，用于接收推送消息
  /// 
  /// 参数：
  /// - [type] 消息类型，可以是：
  ///   - [PushEventType.receiveNotification] 接收到的通知
  ///   - [PushEventType.openNotification] 点击打开的通知
  ///   - [PushEventType.receiveMessage] 接收到的自定义消息
  /// 
  /// 返回：
  /// - 返回对应类型的推送消息流
  /// 
  /// 抛出异常：
  /// - 如果类型无效，会抛出异常
  Stream<PushMessage> onMessage(PushEventType type);
}