import 'package:im_app/domain/entities/user.dart';

/// 认证 Repository 接口（依赖倒置）
///
/// Domain 层定义 What，Data 层实现 How。
/// UseCase 依赖此接口，不依赖具体实现 [AuthRepositoryImpl]。
///
/// ## 登录三步流程
///
/// ```
/// 1. sendOtp(countryCode, contact)             → 发送验证码短信
/// 2. verifyOtp(countryCode, contact, code)     → 校验验证码，返回 vcode_token
/// 3. login(countryCode, contact, vcodeToken)   → 用 vcode_token 换 access_token，返回 User
/// ```
abstract interface class AuthRepository {
  /// 发送手机验证码短信
  ///
  /// 抛 [ApiError] 表示发送失败（手机号格式错误、频率限制等）。
  Future<void> sendOtp({
    required String countryCode,
    required String contact,
  });

  /// 校验验证码，成功返回 vcode_token
  ///
  /// vcode_token 用于 [login] 的 vcodeToken 参数。
  Future<String> verifyOtp({
    required String countryCode,
    required String contact,
    required String code,
  });

  /// 用 vcode_token 完成登录，返回 Domain Entity [User]
  ///
  /// 成功后内部回调写入 access_token，后续请求自动携带。
  Future<User> login({
    required String countryCode,
    required String contact,
    required String vcodeToken,
  });

  /// 退出登录
  Future<void> logout();
}
