/**
 * 📍 Interface RouteStops - Gestão de Paradas de Rotas PraFrota
 * 
 * Interfaces para gerenciamento completo de paradas de rotas incluindo
 * documentos fiscais NFe/NFCe e evidências do app mobile.
 * 
 * ✨ Funcionalidades:
 * - Paradas de coleta, entrega, combustível e descanso
 * - Documentos fiscais integrados (NFe/NFCe)
 * - Evidências do motorista via app mobile
 * - Cronograma detalhado com sequenciamento
 */

// ========================================
// 📍 INTERFACE PRINCIPAL - ROUTE STOP
// ========================================

export interface RouteStop {
  // Identificação
  id: string;
  routeId: string;
  sequence: number; // Ordem da parada na rota (1, 2, 3...)
  
  // Classificação
  type: 'pickup' | 'delivery' | 'rest' | 'fuel';
  
  // Localização detalhada
  location: {
    address: string;
    coordinates: { lat: number; lng: number };
    contact?: string;
    phone?: string;
    cep?: string;
    city?: string;
    state?: string;
    country?: string;
    facility?: string; // Nome da instalação
    accessInstructions?: string; // Instruções de acesso
  };
  
  // Cronograma
  scheduledTime: Date;
  actualTime?: Date;
  estimatedDuration?: number; // em minutos
  actualDuration?: number; // em minutos
  
  // Status operacional
  status: 'pending' | 'completed' | 'failed' | 'skipped';
  
  // Dados de carga
  packages?: number;
  weight?: number; // em kg
  volume?: number; // em m³
  referenceNumber?: string; // Número de referência do cliente
  
  // 📄 DOCUMENTO FISCAL (NOVO REQUISITO)
  fiscalDocument?: FiscalDocument;
  
  // Evidências do app mobile
  photos?: string[];
  signature?: string;
  notes?: string;
  completionEvidence?: {
    photoPackage: string;
    photoReceipt: string;
    digitalSignature: string;
    recipientName: string;
    completionTime: Date;
    latitude?: number;
    longitude?: number;
  };
  
  // Performance e métricas
  attempts?: number; // Tentativas de entrega
  delayReason?: string; // Motivo do atraso
  temperature?: number; // Para produtos que requerem controle de temperatura
  
  // Metadados
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
  updatedBy?: string;
}

// ========================================
// 📄 INTERFACE DOCUMENTO FISCAL
// ========================================

export interface FiscalDocument {
  // Identificação única
  fiscalDocumentId: string;
  
  // Tipo de documento fiscal
  documentType: 'NFe' | 'NFCe';
  
  // Dados obrigatórios da nota fiscal
  documentNumber: string;     // Número da nota fiscal
  series: string | null;      // Série da nota (pode ser null para NFCe)
  accessKey: string | null;   // Chave de acesso de 44 dígitos (opcional)
  issueDate: Date;           // Data de emissão da nota
  totalValue: number;        // Valor total da nota fiscal
  
  // Classificação do produto transportado
  productType: string;       // Ex: "Medicamentos", "Eletrônicos", "Alimentos"
  
  // Status de validação
  status: 'pending' | 'validated' | 'error';
  validationError?: string;
  
  // Dados do emitente (quando disponível)
  emitter?: {
    cnpj: string;
    name: string;
    address?: string;
  };
  
  // Dados do destinatário (quando disponível)
  receiver?: {
    cpfCnpj: string;
    name: string;
    address?: string;
  };
  
  // Integração SEFAZ (implementação futura)
  sefazData?: {
    consultedAt: Date;
    situation: string;
    protocol: string;
    xml?: string; // XML da nota fiscal
  };
  
  // Observações e notas adicionais
  notes?: string;
  tags?: string[]; // Tags para categorização
  
  // Metadados
  createdAt: Date;
  updatedAt: Date;
  createdBy?: string;
  updatedBy?: string;
}

// ========================================
// 🔍 INTERFACES PARA FILTROS E BUSCA
// ========================================

export interface RouteStopsFilters {
  routeId?: string;
  type?: ('pickup' | 'delivery' | 'rest' | 'fuel')[];
  status?: ('pending' | 'completed' | 'failed' | 'skipped')[];
  dateRange?: {
    start: Date;
    end: Date;
  };
  city?: string;
  state?: string;
  hasDocument?: boolean;
  documentType?: ('NFe' | 'NFCe')[];
  page?: number;
  limit?: number;
}

export interface FiscalDocumentFilters {
  documentType?: ('NFe' | 'NFCe')[];
  status?: ('pending' | 'validated' | 'error')[];
  dateRange?: {
    start: Date;
    end: Date;
  };
  productType?: string[];
  minValue?: number;
  maxValue?: number;
  emitterCnpj?: string;
  page?: number;
  limit?: number;
}

// ========================================
// 📊 INTERFACES DE RESPOSTA DA API
// ========================================

export interface RouteStopsResponse {
  data: RouteStop[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  };
  source: 'backend' | 'fallback';
  timestamp: string;
}

export interface FiscalDocumentResponse {
  data: FiscalDocument[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  };
  source: 'backend' | 'fallback';
  timestamp: string;
}

// ========================================
// 📱 INTERFACES DE INTEGRAÇÃO MOBILE
// ========================================

export interface MobileStopEvent {
  stopId: string;
  routeId: string;
  driverId: string;
  
  type: 'arrival' | 'departure' | 'completion' | 'failure' | 'attempt';
  timestamp: Date;
  location: { lat: number; lng: number };
  
  // Dados específicos do evento
  data: {
    photos?: string[];
    signature?: string;
    recipientName?: string;
    notes?: string;
    failureReason?: string;
    temperature?: number;
    packages?: number;
  };
  
  // Metadados do evento mobile
  deviceInfo?: {
    model: string;
    os: string;
    appVersion: string;
    batteryLevel?: number;
    signalStrength?: number;
  };
}

// ========================================
// 📈 INTERFACES DE MÉTRICAS E RELATÓRIOS
// ========================================

export interface RouteStopsMetrics {
  totalStops: number;
  completedStops: number;
  failedStops: number;
  skippedStops: number;
  completionRate: number; // Percentual de conclusão
  averageStopDuration: number; // Tempo médio por parada em minutos
  onTimeStops: number;
  delayedStops: number;
  punctualityRate: number; // Percentual de pontualidade
  
  // Métricas por tipo
  byType: {
    pickup: number;
    delivery: number;
    rest: number;
    fuel: number;
  };
  
  // Métricas financeiras
  totalDocumentValue: number; // Valor total dos documentos fiscais
  documentCount: number;
  averageDocumentValue: number;
  
  // Performance por região
  byCity: { [city: string]: number };
  byState: { [state: string]: number };
}

export interface RouteStopsStatistics {
  dailyStops: { [date: string]: number };
  weeklyTrend: { [week: string]: number };
  monthlyCompletion: { [month: string]: number };
  driverPerformance: { [driverId: string]: RouteStopsMetrics };
  regionAnalysis: { [region: string]: RouteStopsMetrics };
}

// ========================================
// 🎯 INTERFACES DE VALIDAÇÃO
// ========================================

export interface RouteStopValidation {
  isValid: boolean;
  errors: string[];
  warnings: string[];
  
  // Validações específicas
  locationValid: boolean;
  scheduleValid: boolean;
  documentValid: boolean;
  sequenceValid: boolean;
}

export interface FiscalDocumentValidation {
  isValid: boolean;
  errors: string[];
  warnings: string[];
  
  // Validações específicas
  numberValid: boolean;
  dateValid: boolean;
  valueValid: boolean;
  accessKeyValid: boolean;
  formatValid: boolean;
}

// ========================================
// 🔄 INTERFACES DE OTIMIZAÇÃO
// ========================================

export interface RouteOptimization {
  originalSequence: RouteStop[];
  optimizedSequence: RouteStop[];
  improvementMetrics: {
    distanceReduction: number; // em km
    timeReduction: number; // em minutos
    fuelSavings: number; // em litros
    costSavings: number; // em reais
  };
  optimizationCriteria: 'distance' | 'time' | 'cost' | 'balanced';
}

export interface StopGrouping {
  clusterId: string;
  center: { lat: number; lng: number };
  radius: number; // em metros
  stops: RouteStop[];
  estimatedTime: number; // tempo total estimado para o cluster
} 