/**
 * TypeScript types for Forecasting service
 * Mirrored from backend schemas: services/forecasting/app/schemas/forecasts.py
 *
 * Coverage:
 * - Forecast CRUD (list, get, delete)
 * - Forecast Operations (single, multi-day, batch, realtime predictions)
 * - Analytics (performance metrics)
 * - Validation operations
 */

// ================================================================
// ENUMS
// ================================================================

/**
 * Business type enumeration
 * Backend: BusinessType enum in schemas/forecasts.py (lines 13-15)
 */
export enum BusinessType {
  INDIVIDUAL = 'individual',
  CENTRAL_WORKSHOP = 'central_workshop'
}

// ================================================================
// REQUEST TYPES
// ================================================================

/**
 * Request schema for generating forecasts
 * Backend: ForecastRequest in schemas/forecasts.py (lines 18-33)
 */
export interface ForecastRequest {
  inventory_product_id: string;  // Inventory product UUID reference
  forecast_date: string;  // ISO date string - cannot be in the past
  forecast_days?: number;  // Default: 1, ge=1, le=30
  location: string;  // Location identifier
  confidence_level?: number;  // Default: 0.8, ge=0.5, le=0.95
}

/**
 * Request schema for batch forecasting
 * Backend: BatchForecastRequest in schemas/forecasts.py (lines 35-41)
 */
export interface BatchForecastRequest {
  tenant_id: string;
  batch_name: string;
  inventory_product_ids: string[];
  forecast_days?: number;  // Default: 7, ge=1, le=30
}

// ================================================================
// RESPONSE TYPES
// ================================================================

/**
 * Response schema for forecast results
 * Backend: ForecastResponse in schemas/forecasts.py (lines 42-77)
 */
export interface ForecastResponse {
  id: string;
  tenant_id: string;
  inventory_product_id: string;  // Reference to inventory service
  location: string;
  forecast_date: string;  // ISO datetime string

  // Predictions
  predicted_demand: number;
  confidence_lower: number;
  confidence_upper: number;
  confidence_level: number;

  // Model info
  model_id: string;
  model_version: string;
  algorithm: string;

  // Context
  business_type: string;
  is_holiday: boolean;
  is_weekend: boolean;
  day_of_week: number;

  // External factors (optional)
  weather_temperature?: number | null;
  weather_precipitation?: number | null;
  weather_description?: string | null;
  traffic_volume?: number | null;

  // Metadata
  created_at: string;  // ISO datetime string
  processing_time_ms?: number | null;
  features?: Record<string, any> | null;
}

/**
 * Response schema for batch forecast requests
 * Backend: BatchForecastResponse in schemas/forecasts.py (lines 79-96)
 */
export interface BatchForecastResponse {
  id: string;
  tenant_id: string;
  batch_name: string;
  status: string;
  total_products: number;
  completed_products: number;
  failed_products: number;

  // Timing
  requested_at: string;  // ISO datetime string
  completed_at?: string | null;  // ISO datetime string
  processing_time_ms?: number | null;

  // Results
  forecasts?: ForecastResponse[] | null;
  error_message?: string | null;
}

/**
 * Response schema for multi-day forecast results
 * Backend: MultiDayForecastResponse in schemas/forecasts.py (lines 98-107)
 */
export interface MultiDayForecastResponse {
  tenant_id: string;
  inventory_product_id: string;
  forecast_start_date: string;  // ISO date string
  forecast_days: number;
  forecasts: ForecastResponse[];
  total_predicted_demand: number;
  average_confidence_level: number;
  processing_time_ms: number;
}

// ================================================================
// OPERATIONS TYPES
// ================================================================

/**
 * Real-time prediction request
 * Backend: generate_realtime_prediction endpoint in api/forecasting_operations.py (lines 218-288)
 */
export interface RealtimePredictionRequest {
  inventory_product_id: string;
  model_id: string;
  model_path?: string;
  features: Record<string, any>;
  confidence_level?: number;  // Default: 0.8
}

/**
 * Real-time prediction response
 * Backend: generate_realtime_prediction endpoint return value (lines 262-269)
 */
export interface RealtimePredictionResponse {
  tenant_id: string;
  inventory_product_id: string;
  model_id: string;
  prediction: any;
  confidence: any;
  timestamp: string;  // ISO datetime string
}

/**
 * Batch predictions response
 * Backend: generate_batch_predictions endpoint return value (lines 291-333)
 */
export interface BatchPredictionsResponse {
  predictions: Array<{
    inventory_product_id?: string;
    prediction?: any;
    confidence?: any;
    success: boolean;
    error?: string;
  }>;
  total: number;
}

/**
 * Prediction validation result
 * Backend: validate_predictions endpoint in api/forecasting_operations.py (lines 336-362)
 */
export interface PredictionValidationResult {
  // Response structure from enhanced_forecasting_service.validate_predictions
  [key: string]: any;
}

/**
 * Forecast statistics response
 * Backend: get_forecast_statistics endpoint in api/forecasting_operations.py (lines 365-391)
 */
export interface ForecastStatisticsResponse {
  // Response structure from enhanced_forecasting_service.get_forecast_statistics
  [key: string]: any;
}

// ================================================================
// ANALYTICS TYPES
// ================================================================

/**
 * Predictions performance analytics
 * Backend: get_predictions_performance endpoint in api/analytics.py (lines 27-53)
 */
export interface PredictionsPerformanceResponse {
  // Response structure from prediction_service.get_performance_metrics
  [key: string]: any;
}

// ================================================================
// QUERY PARAMETERS
// ================================================================

/**
 * Query parameters for listing forecasts
 * Backend: list_forecasts endpoint in api/forecasts.py (lines 29-62)
 */
export interface ListForecastsParams {
  inventory_product_id?: string | null;
  start_date?: string | null;  // ISO date string
  end_date?: string | null;  // ISO date string
  limit?: number;  // Default: 50, ge=1, le=1000
  offset?: number;  // Default: 0, ge=0
}

/**
 * Query parameters for validation operations
 * Backend: validate_predictions endpoint query params (lines 336-362)
 */
export interface ValidationQueryParams {
  start_date: string;  // ISO date string - required
  end_date: string;  // ISO date string - required
}

/**
 * Query parameters for forecast statistics
 * Backend: get_forecast_statistics endpoint query params (lines 365-391)
 */
export interface ForecastStatisticsParams {
  start_date?: string | null;  // ISO date string
  end_date?: string | null;  // ISO date string
}

/**
 * Query parameters for predictions performance
 * Backend: get_predictions_performance endpoint query params (lines 27-53)
 */
export interface PredictionsPerformanceParams {
  start_date?: string | null;  // ISO date string
  end_date?: string | null;  // ISO date string
}

// ================================================================
// GENERIC RESPONSE TYPES
// ================================================================

/**
 * Generic message response for operations
 * Used by: delete_forecast, clear_prediction_cache
 */
export interface MessageResponse {
  message: string;
}

// ================================================================
// SCENARIO SIMULATION TYPES - PROFESSIONAL/ENTERPRISE ONLY
// ================================================================

/**
 * Types of scenarios available for simulation
 * Backend: ScenarioType enum in schemas/forecasts.py (lines 114-123)
 */
export enum ScenarioType {
  WEATHER = 'weather',
  COMPETITION = 'competition',
  EVENT = 'event',
  PRICING = 'pricing',
  PROMOTION = 'promotion',
  HOLIDAY = 'holiday',
  SUPPLY_DISRUPTION = 'supply_disruption',
  CUSTOM = 'custom'
}

/**
 * Weather scenario parameters
 * Backend: WeatherScenario in schemas/forecasts.py (lines 126-130)
 */
export interface WeatherScenario {
  temperature_change?: number | null;  // Temperature change in °C (-30 to +30)
  precipitation_change?: number | null;  // Precipitation change in mm (0-100)
  weather_type?: string | null;  // Weather type (heatwave, cold_snap, rainy, etc.)
}

/**
 * Competition scenario parameters
 * Backend: CompetitionScenario in schemas/forecasts.py (lines 133-137)
 */
export interface CompetitionScenario {
  new_competitors: number;  // Number of new competitors (1-10)
  distance_km: number;  // Distance from location in km (0.1-10)
  estimated_market_share_loss: number;  // Estimated market share loss (0-0.5)
}

/**
 * Event scenario parameters
 * Backend: EventScenario in schemas/forecasts.py (lines 140-145)
 */
export interface EventScenario {
  event_type: string;  // Type of event (festival, sports, concert, etc.)
  expected_attendance: number;  // Expected attendance
  distance_km: number;  // Distance from location in km (0-50)
  duration_days: number;  // Duration in days (1-30)
}

/**
 * Pricing scenario parameters
 * Backend: PricingScenario in schemas/forecasts.py (lines 148-151)
 */
export interface PricingScenario {
  price_change_percent: number;  // Price change percentage (-50 to +100)
  affected_products?: string[] | null;  // List of affected product IDs
}

/**
 * Promotion scenario parameters
 * Backend: PromotionScenario in schemas/forecasts.py (lines 154-158)
 */
export interface PromotionScenario {
  discount_percent: number;  // Discount percentage (0-75)
  promotion_type: string;  // Type of promotion (bogo, discount, bundle, etc.)
  expected_traffic_increase: number;  // Expected traffic increase (0-2.0 = 0-200%)
}

/**
 * Request schema for scenario simulation
 * Backend: ScenarioSimulationRequest in schemas/forecasts.py (lines 161-189)
 */
export interface ScenarioSimulationRequest {
  scenario_name: string;  // Name for this scenario (3-200 chars)
  scenario_type: ScenarioType;
  inventory_product_ids: string[];  // Products to simulate (min 1)
  start_date: string;  // ISO date string
  duration_days?: number;  // Default: 7, range: 1-30

  // Scenario-specific parameters (provide based on scenario_type)
  weather_params?: WeatherScenario | null;
  competition_params?: CompetitionScenario | null;
  event_params?: EventScenario | null;
  pricing_params?: PricingScenario | null;
  promotion_params?: PromotionScenario | null;

  // Custom scenario parameters
  custom_multipliers?: Record<string, number> | null;

  // Comparison settings
  include_baseline?: boolean;  // Default: true
}

/**
 * Impact of scenario on a specific product
 * Backend: ScenarioImpact in schemas/forecasts.py (lines 192-199)
 */
export interface ScenarioImpact {
  inventory_product_id: string;
  baseline_demand: number;
  simulated_demand: number;
  demand_change_percent: number;
  confidence_range: [number, number];
  impact_factors: Record<string, any>;
}

/**
 * Response schema for scenario simulation
 * Backend: ScenarioSimulationResponse in schemas/forecasts.py (lines 202-256)
 */
export interface ScenarioSimulationResponse {
  id: string;
  tenant_id: string;
  scenario_name: string;
  scenario_type: ScenarioType;

  // Simulation parameters
  start_date: string;  // ISO date string
  end_date: string;  // ISO date string
  duration_days: number;

  // Results
  baseline_forecasts?: ForecastResponse[] | null;
  scenario_forecasts: ForecastResponse[];

  // Impact summary
  total_baseline_demand: number;
  total_scenario_demand: number;
  overall_impact_percent: number;
  product_impacts: ScenarioImpact[];

  // Insights and recommendations
  insights: string[];
  recommendations: string[];
  risk_level: string;  // low, medium, high

  // Metadata
  created_at: string;  // ISO datetime string
  processing_time_ms: number;
}

/**
 * Request to compare multiple scenarios
 * Backend: ScenarioComparisonRequest in schemas/forecasts.py (lines 259-261)
 */
export interface ScenarioComparisonRequest {
  scenario_ids: string[];  // 2-5 scenario IDs to compare
}

/**
 * Response comparing multiple scenarios
 * Backend: ScenarioComparisonResponse in schemas/forecasts.py (lines 264-270)
 */
export interface ScenarioComparisonResponse {
  scenarios: ScenarioSimulationResponse[];
  comparison_matrix: Record<string, Record<string, any>>;
  best_case_scenario_id: string;
  worst_case_scenario_id: string;
  recommended_action: string;
}
