# FleetCommand - Suite de Gestión de Flotas GPS ## Propuesta Técnica Completa **Documento preparado para:** Proyecto independiente de aplicación GPS **Fecha:** 12 de Marzo de 2026 **Versión:** 1.0 --- ## 1. Visión General FleetCommand es una plataforma de inteligencia de flotas que consume datos de 4sat.cl y los transforma en herramientas de gestión avanzadas con valor agregado real para empresas de servicios técnicos y transporte. ### Diferenciadores vs 4sat.cl nativo: - Integración directa con sistema de órdenes de servicio - Constructor de informes personalizados - Certificados profesionales con firma digital - Exportación KMZ para Google Earth - Analytics avanzado y score de conductores - Multi-fuente (preparado para otros proveedores GPS) --- ## 2. Arquitectura Técnica ### Stack Tecnológico ``` Frontend: - React 18 + TypeScript - Leaflet.js / Mapbox GL para mapas - Recharts para gráficos - TailwindCSS + Shadcn/UI - PWA para móvil Backend: - FastAPI (Python 3.11+) - MongoDB (Motor async) - Redis (caché y WebSocket) - Celery (tareas programadas) Integraciones: - 4sat.cl API (GPS data) - Brevo (emails) - Twilio (SMS) - Google Maps API - simplekml (KMZ export) - openpyxl (Excel) - ReportLab (PDF) ``` ### Estructura de Carpetas Propuesta ``` /app/ ├── backend/ │ ├── routes/ │ │ ├── gps/ │ │ │ ├── tracking.py # Tiempo real │ │ │ ├── history.py # Histórico │ │ │ ├── geofences.py # Geocercas │ │ │ └── alerts.py # Alertas │ │ ├── reports/ │ │ │ ├── builder.py # Constructor informes │ │ │ ├── templates.py # Plantillas │ │ │ └── export.py # Exportación │ │ ├── certificates/ │ │ │ ├── generator.py # Generador PDF │ │ │ └── templates.py # Plantillas │ │ └── fleet/ │ │ ├── vehicles.py # Gestión vehículos │ │ ├── drivers.py # Conductores │ │ └── maintenance.py # Mantenimiento │ ├── services/ │ │ ├── foursat_service.py # API 4sat │ │ ├── maps_service.py # Google Maps │ │ └── export_service.py # Exportaciones │ └── tasks/ │ ├── sync_tasks.py # Sincronización │ └── alert_tasks.py # Procesamiento alertas ├── frontend/ │ └── src/ │ ├── modules/ │ │ ├── command-center/ # Centro de control │ │ ├── playback/ # Reproductor recorridos │ │ ├── reports/ # Informes │ │ ├── certificates/ # Certificados │ │ ├── geofences/ # Geocercas │ │ └── analytics/ # Estadísticas │ └── components/ │ ├── maps/ # Componentes de mapa │ └── charts/ # Gráficos └── mobile/ # App móvil (PWA o React Native) ``` --- ## 3. Módulos Detallados ### 3.1 Centro de Control (Command Center) **Funcionalidades:** - Mapa en tiempo real con todos los vehículos - Actualización cada 10-30 segundos vía WebSocket - Clustering inteligente para flotas grandes - Capas: Tráfico, Satélite, Calles, Híbrido - Filtros: Por estado, grupo, conductor - Panel lateral con detalle de vehículo seleccionado - Street View integrado **Endpoints:** ``` GET /api/gps/tracking/live # Posiciones en tiempo real GET /api/gps/tracking/vehicle/{id} # Detalle de vehículo WS /ws/gps/tracking # WebSocket para updates ``` **Modelo de datos:** ```python class VehiclePosition(BaseModel): vehicle_id: str device_id: str latitude: float longitude: float speed: float heading: int ignition: bool timestamp: datetime address: Optional[str] driver_id: Optional[str] ``` ### 3.2 Sistema de Alertas **Tipos de alertas:** - Exceso de velocidad (configurable por zona) - Entrada/salida de geocercas - Detención prolongada - Motor encendido detenido (ralentí) - Batería baja dispositivo - Sin señal GPS - Manipulación/sabotaje - Kilometraje de mantenimiento - Vencimiento documentos - Horas de conducción **Canales de notificación:** - Push notification (PWA) - Email (Brevo) - SMS (Twilio) - WhatsApp Business API - Webhook externo **Modelo de configuración:** ```python class AlertConfig(BaseModel): alert_type: str enabled: bool threshold: Optional[float] schedule: Optional[dict] # Horarios activos vehicles: List[str] # Vehículos aplicables notifications: dict # Canales y destinatarios actions: List[str] # Acciones automáticas ``` ### 3.3 Playback de Recorridos **Funcionalidades:** - Reproducción animada de recorridos históricos - Control de velocidad (1x, 2x, 4x, 8x) - Timeline con eventos marcados - Detenciones identificadas automáticamente - Excesos de velocidad resaltados - Exportación de segmento seleccionado **Endpoints:** ``` GET /api/gps/history/{vehicle_id} # Histórico por vehículo GET /api/gps/history/{vehicle_id}/events # Eventos del recorrido POST /api/gps/history/export # Exportar segmento ``` ### 3.4 Analytics & Business Intelligence **KPIs disponibles:** - Kilometraje (diario/semanal/mensual/anual) - Consumo de combustible estimado - Horas de operación - Tiempo productivo vs improductivo - Costo por kilómetro - Score de conducción por conductor - Cumplimiento de rutas - Tiempo en cliente vs en tránsito **Fórmulas de cálculo:** ```python # Score de conducción (0-100) score = 100 - (excesos_velocidad * 2) - (frenadas_bruscas * 3) - (aceleraciones * 1) # Combustible estimado combustible_litros = km_recorridos * factor_consumo_vehiculo # Eficiencia de flota eficiencia = (tiempo_productivo / tiempo_total) * 100 ``` ### 3.5 Geocercas **Tipos:** - Circular (radio desde punto) - Polígono (área personalizada) - Corredor (ruta con tolerancia) - Punto de interés (POI) **Configuración por geocerca:** - Horarios permitidos - Vehículos autorizados - Tiempo máximo de permanencia - Alertas de entrada/salida - Acciones automáticas ### 3.6 Gestión de Rutas **Funcionalidades:** - Planificador de rutas diarias - Asignación de tareas a vehículos - Optimización de ruta (Google Directions API) - Seguimiento de cumplimiento en tiempo real - ETA dinámico - Re-asignación en tiempo real ### 3.7 Mantenimiento Predictivo **Seguimiento:** - Kilometraje para próximo servicio - Historial de mantenciones - Costos acumulados - Alertas de vencimiento - Integración con proveedores ### 3.8 Centro de Certificados **Tipos de certificados:** - Certificado de Instalación GPS - Certificado de Desinstalación - Certificado de Operatividad - Certificado de Recorrido - Certificado de Kilometraje Oficial - Informe de Conducción **Características:** - Diseño profesional con logo empresa - Firma digital del responsable - QR de verificación único - Envío automático por email - Almacenamiento en la nube ### 3.9 Constructor de Informes **Funcionalidades:** - Selección de columnas (drag & drop) - Filtros avanzados - Cálculos personalizados - Agrupación flexible - Vista previa en tiempo real - Guardar plantillas favoritas **Formatos de exportación:** - Excel (.xlsx) - PDF - CSV - HTML - KMZ (Google Earth) **Ejemplo de configuración de informe:** ```json { "nombre": "Informe Kilometraje Mensual", "columnas": ["patente", "conductor", "km_recorridos", "combustible_est", "costo"], "filtros": { "fecha_desde": "2026-03-01", "fecha_hasta": "2026-03-31", "vehiculos": ["todos"] }, "calculos": [ {"tipo": "suma", "campo": "km_recorridos", "alias": "total_km"}, {"tipo": "formula", "expresion": "km_recorridos * 0.12", "alias": "litros"}, {"tipo": "formula", "expresion": "litros * 1200", "alias": "costo_combustible"} ], "agrupacion": "por_vehiculo", "ordenar_por": "total_km", "orden": "desc" } ``` ### 3.10 Exportación KMZ **Contenido del archivo KMZ:** ```xml Recorrido ABC-123 - 12/03/2026 08:00:00 - 65 km/h Vehículo: ABC-123
Conductor: Juan Pérez
Velocidad: 65 km/h
Ignición: ON
Dirección: Av. Principal 1234 ]]> -70.6483,-33.4569,0 2026-03-12T08:00:00Z Ruta completa -70.6483,-33.4569,0 -70.6490,-33.4575,0 -70.6500,-33.4580,0 ``` ### 3.11 App Móvil (Técnicos/Conductores) **Funcionalidades:** - Vista de tareas del día - Check-in/Check-out en cliente - Navegación integrada (Waze/Google Maps) - Captura de evidencia fotográfica - Firma digital del cliente - Reporte de incidentes - Modo offline - Botón de pánico/emergencia --- ## 4. Base de Datos ### Colecciones MongoDB ```javascript // Configuración de flota db.fleet_vehicles db.fleet_drivers db.fleet_groups // GPS y tracking db.gps_positions // Posiciones actuales db.gps_history // Histórico (particionado por mes) db.gps_events // Eventos detectados // Geocercas db.geofences db.geofence_events // Alertas db.alert_configs db.alert_history // Informes db.report_templates db.report_history // Certificados db.certificates // Mantenimiento db.maintenance_schedules db.maintenance_history ``` --- ## 5. APIs Externas ### 4sat.cl API ``` Base URL: https://app.4sat.cl/api/ Autenticación: api_hash (obtenido via login) Endpoints utilizados: - POST /login # Obtener api_hash - GET /get_devices # Lista de dispositivos - GET /get_device_position/{id} # Posición actual - GET /get_device_history # Histórico - POST /update_device # Actualizar datos ``` ### Google Maps Platform ``` - Directions API (optimización rutas) - Geocoding API (direcciones) - Street View API (visualización) - Maps JavaScript API (renderizado) ``` --- ## 6. Plan de Implementación Sugerido ### Fase 1: Fundación (2-3 semanas) - Setup de proyecto - Integración base con 4sat.cl - Mapa básico con posiciones - Autenticación y permisos ### Fase 2: Core GPS (2-3 semanas) - Centro de control completo - Playback de recorridos - Sistema de alertas básico - Geocercas ### Fase 3: Informes (2 semanas) - Constructor de informes - Exportación multi-formato - Exportación KMZ - Plantillas predefinidas ### Fase 4: Certificados (1 semana) - Generador de certificados - Plantillas PDF - Firma digital - Almacenamiento ### Fase 5: Analytics (2 semanas) - Dashboard ejecutivo - KPIs y métricas - Score de conductores - Reportes automáticos ### Fase 6: Móvil (2 semanas) - PWA para técnicos - Check-in/Check-out - Modo offline - Notificaciones push --- ## 7. Dependencias a Instalar ```bash # Backend pip install simplekml openpyxl weasyprint redis celery httpx # Frontend yarn add leaflet react-leaflet @types/leaflet yarn add recharts yarn add date-fns yarn add file-saver yarn add jszip # Para KMZ ``` --- ## 8. Consideraciones de Seguridad - API keys almacenadas en variables de entorno - Tokens JWT con expiración - Rate limiting en endpoints - Validación de geocercas por empresa - Logs de auditoría - Encriptación de datos sensibles --- ## 9. Escalabilidad - MongoDB con sharding para histórico GPS - Redis para caché de posiciones actuales - WebSocket con Redis pub/sub - CDN para assets estáticos - Kubernetes para orquestación --- **Documento generado automáticamente** **Sistema de Gestión de Órdenes de Servicio - Multisistemas**