import 'package:networks_sdk/src/domain/entities/api_request_type.dart';
import 'package:networks_sdk/src/domain/entities/http_method.dart';

/// API 请求注解 — 标记一个类为 API 请求
///
/// 配合 `build_runner` 代码生成器，自动生成 `ApiRequestable<T>` 协议实现，
/// 使用侧只需定义字段 + 注解，path / method / requestType / includeToken
/// 全部由生成器自动提供。
///
/// ## 有响应数据（指定 responseType）
///
/// ```dart
/// @ApiRequest(
///   path: ApiPaths.authLogin,
///   method: HttpMethod.post,
///   responseType: LoginResponse,
///   requestType: ApiRequestType.login,
/// )
/// class LoginRequest extends ApiRequestable<LoginResponse>
///     with _$LoginRequestApi {
///   final String email;
///   final String password;
///
///   LoginRequest({required this.email, required this.password});
/// }
/// ```
///
/// ## 无响应数据（省略 responseType）
///
/// ```dart
/// @ApiRequest(
///   path: ApiPaths.authLogout,
///   method: HttpMethod.post,
/// )
/// class LogoutRequest extends ApiRequestable<void>
///     with _$LogoutRequestApi {
///   LogoutRequest();
/// }
/// ```
///
/// 生成器自动生成 `_$XxxRequestApi` mixin，提供：
/// - `path` / `method` / `requestType` / `includeToken`
/// - `toJson()` — 从声明字段自动生成
/// - `responseType` 存在时：`parameters` getter 自动注册 `fromJson`
class ApiRequest {
  /// API 路径（如 `ApiPaths.authLogin`）
  final String path;

  /// HTTP 方法（默认 POST）
  final HttpMethod method;

  /// 响应数据类型（省略表示无响应数据，对应 `ApiRequestable<void>`）
  final Type? responseType;

  /// 请求类型（决定 header 处理方式，默认 request）
  final ApiRequestType requestType;

  /// 是否在 header 中包含 token（默认根据 requestType 推断：login → false，其余 → true）
  final bool? includeToken;

  /// 自定义请求头
  final Map<String, String>? customHeaders;

  const ApiRequest({
    required this.path,
    this.method = HttpMethod.post,
    this.responseType,
    this.requestType = ApiRequestType.request,
    this.includeToken,
    this.customHeaders,
  });
}
