consultar_fuera_horario
ChatGPTReporte Fuera de Horario: detecta cuando unidades superan los kilometros autorizados fuera del horario configurado por la empresa. Retorna por unidad: incidencias (tramos recorridos dentro de horario prohibido, misma metrica que la columna "Incidencias" del reporte), periodos_fuera_horario (ventanas de tiempo donde se excedieron km autorizados), km_excedidos_total, distancia_total_km, multa_total (EXCLUYE periodos justificados, igual que el reporte UI), periodos_justificados y multa_justificada_total. El campo se denomina "Incidencias" (no "Violaciones"), igual que en el reporte de la plataforma. Con incluir_detalle=true agrega cada ventana individual con fecha_inicio, fecha_fin, distancia_km, km_autorizados, km_exceso, incidencias, multa, notas, justificacion y justificada (boolean). config_id identifica la configuracion de horario aplicada; cada empresa puede tener varias (ej. "horario nocturno", "fin de semana"). REGLA: si la solicitud nombra la configuracion (ej. "...con la configuracion Test Jojan..."), pasa ese nombre como config_nombre; no se requiere confirmar el ID. El tool resuelve el match. Si se omite config_id Y config_nombre y la empresa tiene una sola configuracion se usa de forma automatica. Si hay varias el tool retorna {need_config_selection: true, configs_disponibles: [...]}: informar las opciones al solicitante y reintentar con la elegida. MONEDA: el response incluye el campo moneda (ej. "MXN") y campos *_formato con la cantidad ya formateada (ej. "$1,234.56 MXN"). USA esos campos formato al mostrar montos al usuario. NUNCA asumas USD ni inventes el simbolo o sufijo de moneda. EMPRESA REQUERIDA: si la solicitud nombra la empresa (ej. "...de la empresa MEXTIC...") pasa ese nombre como empresa_nombre — el tool resuelve el match case-insensitive. NO mezcles empresas: la combinacion empresa+configuracion se valida en el tool; si la config nombrada no existe en esa empresa el tool devuelve los matches reales — NO asumas pertenencias. Para admins el tool exige empresa_id o empresa_nombre; si se omite devuelve {need_empresa_selection: true, empresas_disponibles: [...]} con las empresas que tienen configuraciones de fuera de horario: informar las opciones al solicitante y reintentar con la elegida. Tool pesado: itera historial por unidad y ventana de horario, preferir periodos cortos (7d, 30d). Usar para: incidencias fuera de horario, multas acumuladas, unidades que excedieron km autorizados, costo total de infracciones.
consultar_geocercas
ChatGPTGeocercas del usuario: lista TODAS las geocercas registradas (con y sin actividad) mas actividad por vehiculo. SIEMPRE llamar este tool para cualquier pregunta sobre geocercas. Retorna por vehiculo: geocercas con visitas, tiempo_total_min, tiempo_promedio_min, actualmente_dentro, primera_entrada, ultima_salida. Tambien retorna geocercas_sin_actividad para geocercas sin eventos. Con incluir_detalle=true retorna cada par entrada/salida.
consultar_mantenimientos
ChatGPTMantenimientos vehiculares. Retorna por unidad: periodo (total, pendientes, realizados, cancelados, costo_total, costo_promedio, por_tipo, por_clasificacion, por_proveedor), ultimo_realizado (fecha, odometro_km, tipo, clasificacion, proveedor, costo). Con incluir_proximo_servicio agrega odometro_actual_km y proximo_servicio (km_objetivo, km_restantes). Con incluir_historial agrega top 10 mantenimientos mas recientes. Tipo es ENUM nativo preventivo/correctivo. Clasificacion es subcategoria por empresa (Motor, Frenos, etc). Costos en moneda de la empresa. Usar para: mantenimientos pendientes, historial, costos, preventivos vs correctivos, proveedor mas usado, proximo servicio, km sin mantenimiento.
consultar_recorridos
ChatGPTRecorridos por unidad en un periodo. Retorna: km_total, encendido, movimiento, detenido (texto legible) y *_seg (segundos crudos para calculos), primer_movimiento, ultimo_movimiento. Sin buscar retorna toda la flota. Con detalle=diario retorna desglose por dia con km_encendido, km_apagado. Llamar 2 veces con periodos distintos para comparar.
consultar_rendimientos
ChatGPTRendimiento de combustible por unidad. Solo unidades con sensor de combustible o CAN-BUS. Por defecto retorna el agregado del rango: rendimiento (km/l o lts/hr), consumo_lts, cargas_lts, extracciones_lts, km_total, odometro_km, encendido, movimiento, detenido, ralenti (texto legible) y *_seg (segundos crudos para calculos). Con detalle=diario retorna ademas la lista dias[] con los mismos campos por cada dia del rango. Sin buscar retorna toda la flota.
consultar_temperaturas
ChatGPTTemperatura de unidades refrigeradas. Retorna por vehiculo: config (setpoint, lower_limit, upper_limit, unidad C o F), actual (temperatura, fecha_local, estado, fuera_de_rango), periodo (temp_min, temp_max, temp_promedio, temp_desviacion, lecturas_total, lecturas_fuera_rango, pct_en_rango, minutos_fuera_rango_aprox). Estados: MANTENIENDO, ENFRIANDO, PERDIENDO, ESTABILIZANDO. Solo unidades con temperatura_config no nulo. Usar para: temperatura actual, fuera de rango, max/min, promedio, cadena de frio, variaciones. Para alarmas de temperatura usar historial_eventos con tipo=temperatura.
estatus_flota
ChatGPTDesglose del ESTATUS ADMINISTRATIVO de las unidades: cuantas estan activas e inactivas (baja). Retorna total, activos, inactivos (y otros[] si hay algun estatus no estandar). La clave suspendidos SOLO llega para superadmin; su AUSENCIA NO significa cero. Si no viene: no la menciones, no digas que es 0 y NO la infieras restando (total - activos - inactivos); el total ya excluye las suspendidas. Si preguntan explicitamente por unidades suspendidas y la clave no vino, responde que no dispones de ese dato, sin afirmar ni negar que existan. Usar SIEMPRE para preguntas como "cuantas unidades activas/inactivas/suspendidas tengo", "estatus de mi flota", "cuantas unidades dadas de baja". IMPORTANTE: el estatus administrativo (alta/baja/suspension de la unidad, campo status) es un eje DISTINTO de "reporta / no reporta" (eso es posicion_actual con minutos_sin_reportar). NO derivar el estatus desde posicion_actual ni inventar umbrales. Para superadmin SIN empresa_id devuelve {requiere_busqueda:true,total:N}: resolver la empresa via obtener_empresas y reintentar con empresa_id. Admin y usuario sin empresa_id reciben el desglose de toda su flota visible.
eventos_combustible
ChatGPTCargas, extracciones y despachos de combustible. Retorna por evento: tipo (carga/extraccion/despacho), litros, fecha_local, lat/lng, vehiculo. Usar para: hubo carga hoy, robos o fugas, ultima carga, historial de cargas, litros cargados en periodo. IMPORTANTE: una unidad carga cada 8-9 dias en promedio, asi que el periodo default (7d) puede venir vacio aunque si haya habido cargas. Si la respuesta llega vacia y el usuario NO acoto fechas, reintentar con periodo=30d antes de responder que no hubo eventos. En flotas grandes preferir acotar con buscar o dispositivo al ampliar el periodo: la respuesta trae los 200 eventos mas recientes.
historial_eventos
ChatGPTAlarmas y eventos de unidades. Retorna: vehiculo, evento, detalle, fecha_local, lat/lng. Tipos: velocidad, geocerca (entrada/salida), encendido, apagado, paradas, conduccion (aceleracion/frenado/vuelta brusca), sos, mantenimiento, temperatura. NO incluye combustible (usar eventos_combustible).
obtener_empresas
ChatGPTLista empresas con cantidad de vehiculos activos. Llamar ANTES de consultar flota completa para saber las empresas disponibles y usar empresa_id en los otros tools. Para superadmin (muchas empresas) SIN buscar NO lista: devuelve {requiere_busqueda:true,total:N}: reintentar con el parametro buscar (nombre parcial de la empresa). Con buscar devuelve {requiere_busqueda:false,truncado:bool,empresas:[...]}.
posicion_actual
ChatGPTUltima posicion GPS de unidades. Retorna por cada unidad: lat/lng, velocidad_kmh, motor (encendido/apagado), minutos_sin_reportar, odometro, estacionado_min (minutos detenido en punto actual). Sin buscar retorna TODA la flota. Usar para: ubicacion, velocidad, unidades en movimiento/detenidas, unidades sin reportar, estado del motor, tiempo estacionado.
posicion_historica
ChatGPTPosicion GPS de una unidad en un momento especifico del pasado. Retorna: vehiculo, lat, lng, velocidad_kmh, motor, odometro_km, fecha_local. Busca el registro mas cercano a la fecha/hora indicada.
rendimiento_actual
ChatGPTRendimiento de combustible ACTUAL / en este momento (tendencia en vivo), leido de tiempo real. Usar SIEMPRE que pregunten por el rendimiento "actual", "ahora", "en este momento", "como va" o sin mencionar un periodo. Para rendimiento de un periodo o historico (hoy, ayer, ultimos dias, fechas) usar consultar_rendimientos. Retorna por unidad: tipo_unidad, metrica_principal (km_l o l_hr), estado_fsm (ESTABLE, CALENTANDO, SIN_DATOS, DEGRADADO, NO_CONFIABLE o null si la unidad no tiene maquina de estados), estado_fsm_detalle (explicacion lista para citar), causas, actualizado_hace_min y desactualizado (true si lleva mas de 15 min sin recalcular); y para km_l y l_hr: valor, unidad, estado (eficiente/normal/deficiente/critico, o null cuando la unidad no esta ESTABLE: no hay clasificacion confirmada), confiable (si es false el valor viene null y no debe estimarse), combustible_lts y distancia_km u horas_trabajo. Incluye ultimo_evento de combustible si existe. Solo unidades con sensor de combustible o CAN-BUS y clasificacion configurada; las demas se omiten. Sin buscar retorna toda la flota.
