import 'error_codes.dart';

/// 统一 API 异常：HTTP 错误响应体 `{code, message, requestId}`（契约
/// `components.schemas.Error`）与网络层失败一律归一为本类型，映射逻辑见
/// `ApiClient.mapDioException`。
///
/// UI 层按 [code]（[ErrorCodes]）解析本地化文案；[message] 为服务器/
/// 客户端生成的诊断消息，不作为展示文案依据。
class AppException implements Exception {
  const AppException({
    required this.code,
    required this.message,
    this.requestId,
    this.statusCode,
  });

  /// 稳定错误码（契约码或客户端伪码，见 [ErrorCodes]）。
  final String code;

  /// 可读消息（诊断用）。
  final String message;

  /// 请求追踪 ID（服务端错误体携带时非空）。
  final String? requestId;

  /// HTTP 状态码（网络层失败/取消时为 null）。
  final int? statusCode;

  /// 会话过期/未认证（401 语义：令牌失效需重新登录）。
  bool get isAuthExpired => code == ErrorCodes.authTokenExpired;

  @override
  String toString() => 'AppException(code: $code, statusCode: $statusCode, '
      'requestId: $requestId, message: $message)';
}