// ================================================================
// frontend/src/api/types/external.ts
// ================================================================
/**
 * External Data Type Definitions (Weather & Traffic)
 *
 * Aligned with backend schemas:
 * - services/external/app/schemas/weather.py
 * - services/external/app/schemas/traffic.py
 *
 * Last Updated: 2025-10-05
 * Status: ✅ Complete - Zero drift with backend
 */

// ================================================================
// WEATHER TYPES
// ================================================================

/**
 * Base weather data schema
 * Backend: services/external/app/schemas/weather.py:9-20 (WeatherDataBase)
 */
export interface WeatherDataBase {
  location_id: string;  // max_length=100
  date: string;  // ISO datetime
  temperature?: number | null;  // ge=-50, le=60 - Celsius
  precipitation?: number | null;  // ge=0 - mm
  humidity?: number | null;  // ge=0, le=100 - percentage
  wind_speed?: number | null;  // ge=0, le=200 - km/h
  pressure?: number | null;  // ge=800, le=1200 - hPa
  description?: string | null;  // max_length=200
  source: string;  // max_length=50, default="aemet"
  raw_data?: string | null;
}

/**
 * Schema for creating weather data
 * Backend: services/external/app/schemas/weather.py:22-24 (WeatherDataCreate)
 */
export interface WeatherDataCreate extends WeatherDataBase {}

/**
 * Schema for updating weather data
 * Backend: services/external/app/schemas/weather.py:26-34 (WeatherDataUpdate)
 */
export interface WeatherDataUpdate {
  temperature?: number | null;  // ge=-50, le=60
  precipitation?: number | null;  // ge=0
  humidity?: number | null;  // ge=0, le=100
  wind_speed?: number | null;  // ge=0, le=200
  pressure?: number | null;  // ge=800, le=1200
  description?: string | null;  // max_length=200
  raw_data?: string | null;
}

/**
 * Schema for weather data responses
 * Backend: services/external/app/schemas/weather.py:36-53 (WeatherDataResponse)
 * Note: Duplicate definition at 123-131, using the more complete one
 */
export interface WeatherDataResponse extends WeatherDataBase {
  id: string;
  created_at: string;  // ISO datetime
  updated_at: string;  // ISO datetime
}

/**
 * Base weather forecast schema
 * Backend: services/external/app/schemas/weather.py:55-65 (WeatherForecastBase)
 */
export interface WeatherForecastBase {
  location_id: string;  // max_length=100
  forecast_date: string;  // ISO datetime
  temperature?: number | null;  // ge=-50, le=60
  precipitation?: number | null;  // ge=0
  humidity?: number | null;  // ge=0, le=100
  wind_speed?: number | null;  // ge=0, le=200
  description?: string | null;  // max_length=200
  source: string;  // max_length=50, default="aemet"
  raw_data?: string | null;
}

/**
 * Schema for creating weather forecasts
 * Backend: services/external/app/schemas/weather.py:67-69 (WeatherForecastCreate)
 */
export interface WeatherForecastCreate extends WeatherForecastBase {}

/**
 * Schema for weather forecast responses
 * Backend: services/external/app/schemas/weather.py:71-89 (WeatherForecastResponse)
 * Note: Duplicate definition at 133-141, using the more complete one
 */
export interface WeatherForecastResponse extends WeatherForecastBase {
  id: string;
  generated_at: string;  // ISO datetime
  created_at: string;  // ISO datetime
  updated_at: string;  // ISO datetime
}

/**
 * Schema for paginated weather data responses
 * Backend: services/external/app/schemas/weather.py:91-98 (WeatherDataList)
 */
export interface WeatherDataList {
  data: WeatherDataResponse[];
  total: number;
  page: number;
  per_page: number;
  has_next: boolean;
  has_prev: boolean;
}

/**
 * Schema for paginated weather forecast responses
 * Backend: services/external/app/schemas/weather.py:100-105 (WeatherForecastList)
 */
export interface WeatherForecastList {
  forecasts: WeatherForecastResponse[];
  total: number;
  page: number;
  per_page: number;
}

/**
 * Schema for weather analytics
 * Backend: services/external/app/schemas/weather.py:107-121 (WeatherAnalytics)
 */
export interface WeatherAnalytics {
  location_id: string;
  period_start: string;  // ISO datetime
  period_end: string;  // ISO datetime
  avg_temperature?: number | null;
  min_temperature?: number | null;
  max_temperature?: number | null;
  total_precipitation?: number | null;
  avg_humidity?: number | null;
  avg_wind_speed?: number | null;
  avg_pressure?: number | null;
  weather_conditions: Record<string, any>;  // Default: {}
  rainy_days: number;  // Default: 0
  sunny_days: number;  // Default: 0
}

/**
 * Location request for weather/traffic data
 * Backend: services/external/app/schemas/weather.py:143-146 (LocationRequest)
 */
export interface LocationRequest {
  latitude: number;
  longitude: number;
  address?: string | null;
}

/**
 * Date range request
 * Backend: services/external/app/schemas/weather.py:148-150 (DateRangeRequest)
 */
export interface DateRangeRequest {
  start_date: string;  // ISO datetime
  end_date: string;  // ISO datetime
}

/**
 * Historical weather request
 * Backend: services/external/app/schemas/weather.py:152-156 (HistoricalWeatherRequest)
 */
export interface HistoricalWeatherRequest {
  latitude: number;
  longitude: number;
  start_date: string;  // ISO datetime
  end_date: string;  // ISO datetime
}

/**
 * Weather forecast request
 * Backend: services/external/app/schemas/weather.py:158-161 (WeatherForecastRequest)
 */
export interface WeatherForecastRequest {
  latitude: number;
  longitude: number;
  days: number;
}

/**
 * Hourly forecast request
 * Backend: services/external/app/schemas/weather.py:163-166 (HourlyForecastRequest)
 */
export interface HourlyForecastRequest {
  latitude: number;
  longitude: number;
  hours?: number;  // Default: 48, ge=1, le=48
}

/**
 * Hourly forecast response
 * Backend: services/external/app/schemas/weather.py:168-177 (HourlyForecastResponse)
 */
export interface HourlyForecastResponse {
  forecast_datetime: string;  // ISO datetime
  generated_at: string;  // ISO datetime
  temperature?: number | null;
  precipitation?: number | null;
  humidity?: number | null;
  wind_speed?: number | null;
  description?: string | null;
  source: string;
  hour: number;
}

// ================================================================
// TRAFFIC TYPES
// ================================================================

/**
 * Base traffic data schema
 * Backend: services/external/app/schemas/traffic.py:11-20 (TrafficDataBase)
 */
export interface TrafficDataBase {
  location_id: string;  // max_length=100
  date: string;  // ISO datetime
  traffic_volume?: number | null;  // ge=0 - Vehicles per hour
  pedestrian_count?: number | null;  // ge=0 - Pedestrians per hour
  congestion_level?: string | null;  // pattern: ^(low|medium|high)$
  average_speed?: number | null;  // ge=0, le=200 - km/h
  source: string;  // max_length=50, default="madrid_opendata"
  raw_data?: string | null;
}

/**
 * Schema for creating traffic data
 * Backend: services/external/app/schemas/traffic.py:22-24 (TrafficDataCreate)
 */
export interface TrafficDataCreate extends TrafficDataBase {}

/**
 * Schema for updating traffic data
 * Backend: services/external/app/schemas/traffic.py:26-32 (TrafficDataUpdate)
 */
export interface TrafficDataUpdate {
  traffic_volume?: number | null;  // ge=0
  pedestrian_count?: number | null;  // ge=0
  congestion_level?: string | null;  // pattern: ^(low|medium|high)$
  average_speed?: number | null;  // ge=0, le=200
  raw_data?: string | null;
}

/**
 * Schema for traffic data responses from database
 * Backend: services/external/app/schemas/traffic.py:34-51 (TrafficDataResponseDB)
 */
export interface TrafficDataResponseDB extends TrafficDataBase {
  id: string;
  created_at: string;  // ISO datetime
  updated_at: string;  // ISO datetime
}

/**
 * Schema for API traffic data responses
 * Backend: services/external/app/schemas/traffic.py:74-86 (TrafficDataResponse)
 */
export interface TrafficDataResponse {
  date: string;  // ISO datetime
  traffic_volume?: number | null;  // ge=0
  pedestrian_count?: number | null;  // ge=0
  congestion_level?: string | null;  // pattern: ^(low|medium|high)$
  average_speed?: number | null;  // ge=0, le=200
  source: string;
}

/**
 * Schema for paginated traffic data responses
 * Backend: services/external/app/schemas/traffic.py:53-60 (TrafficDataList)
 */
export interface TrafficDataList {
  data: TrafficDataResponseDB[];
  total: number;
  page: number;
  per_page: number;
  has_next: boolean;
  has_prev: boolean;
}

/**
 * Schema for traffic analytics
 * Backend: services/external/app/schemas/traffic.py:62-72 (TrafficAnalytics)
 */
export interface TrafficAnalytics {
  location_id: string;
  period_start: string;  // ISO datetime
  period_end: string;  // ISO datetime
  avg_traffic_volume?: number | null;
  avg_pedestrian_count?: number | null;
  peak_traffic_hour?: number | null;
  peak_pedestrian_hour?: number | null;
  congestion_distribution: Record<string, any>;  // Default: {}
  avg_speed?: number | null;
}

/**
 * Historical traffic request
 * Backend: services/external/app/schemas/traffic.py:97-101 (HistoricalTrafficRequest)
 */
export interface HistoricalTrafficRequest {
  latitude: number;
  longitude: number;
  start_date: string;  // ISO datetime
  end_date: string;  // ISO datetime
}

/**
 * Traffic forecast request
 * Backend: services/external/app/schemas/traffic.py:103-106 (TrafficForecastRequest)
 */
export interface TrafficForecastRequest {
  latitude: number;
  longitude: number;
  hours?: number;  // Default: 24
}

// ================================================================
// CITY-BASED DATA TYPES (NEW)
// ================================================================

/**
 * City information response
 * Backend: services/external/app/schemas/city_data.py:CityInfoResponse
 */
export interface CityInfoResponse {
  city_id: string;
  name: string;
  country: string;
  latitude: number;
  longitude: number;
  radius_km: number;
  weather_provider: string;
  traffic_provider: string;
  enabled: boolean;
}

/**
 * Data availability response
 * Backend: services/external/app/schemas/city_data.py:DataAvailabilityResponse
 */
export interface DataAvailabilityResponse {
  city_id: string;
  city_name: string;

  // Weather availability
  weather_available: boolean;
  weather_start_date: string | null;
  weather_end_date: string | null;
  weather_record_count: number;

  // Traffic availability
  traffic_available: boolean;
  traffic_start_date: string | null;
  traffic_end_date: string | null;
  traffic_record_count: number;
}
