Hub

electrosystems

amadeus-control-retorno

active medium design-doc
Creado
2026-05-28
Actualizado
2026-05-28
Parent
amadeus
Directorios
  • /home/sergio/code/amadeus

Amadeus — Control de retorno de técnicos a Cd. Juárez

Avisar automáticamente a contabilidad (y a quien se configure) cuando un técnico regresa a Juárez tras un viaje, para control interno — sin fricción para el técnico.

🎯 Pendientes (top de ataque)

  • #392 📅 esta-semana · ⏱ 2h · 🔥 — Quick-win nativo (ya viable). El Traccar de ares es 6.6 con emailEnabled:true → se puede definir el geofence “Cd. Juárez” + una notificación por email a la contadora directo en la UI de Traccar, sin tocar Amadeus. Requiere login admin de Traccar (lo tiene Sergio) — yo lo guío o lo hace él. Limitación conocida: dispara con cualquier entrada a Juárez (ruido) y sin contexto de viaje; cobertura provisional hasta el bridge.
  • #393 📅 cond:post-milestone · ⏱ 1d · ⚠️ — Cimientos del bridge. Columna traccar_device_id en vehiculos + mapeo unidad↔device (consultando GET http://201.218.172.10:8082/api/devices); permiso nuevo notificar_retorno en permisos (Nova + modelo); crear token/usuario read-only en Traccar 6.6 (login admin de Sergio); montar scheduler (cron de php artisan schedule:run, hoy inexistente).
  • #394 📅 cond:post-milestone · ⏱ 2d · ⚠️ — Bridge Amadeus↔Traccar. Comando programado que consulta la posición (GET http://201.218.172.10:8082/api/positions?deviceId= en Traccar 6.6) de los vehículos en viaje activo (fecha_cierre IS NULL y destino fuera de Juárez); detecta transición fuera→dentro del bbox de Juárez; dispara evento RetornoDetectadoEvent → listener push+email a quienes tengan notificar_retorno. Mensaje con contexto: “Vehículo U09 (viaje folio X, técnico Y) regresó a Cd. Juárez a las HH:MM.” Idempotente (no re-avisar). Alternativa más limpia: notificación web (webhook) de Traccar 6.6 al geofence → endpoint en Amadeus (evita scheduler).

Backlog del proyecto

  • #395 📅 cond:fase-2-lista · ⏱ 2-3d — Fase futura: detección por celular del técnico. Para las contadas ocasiones en que el técnico viaja en avión (el vehículo no se mueve, así que Traccar no lo detecta). Geofence ligero vía la PWA de Amadeus (navigator.geolocation), reusando el patrón de captura GPS de #381 (consumos) y del checador #387. Más invasivo (requiere permiso de ubicación / app abierta) — por eso es fase 2, solo el caso avión.

En progreso

  • ✅ Fundamentos cerrados (2026-05-28). Las 3 piezas confirmadas y los datos del Traccar capturados (#396 + #398): Traccar 6.6 en 201.218.172.10:8082 (API REST alcanzable desde la LAN interna, emailEnabled:true), puerto de dispositivos 5046 (Teltonika). Todo documentado en ~/agy/electrosystems/servers/ares/. Siguiente paso real = #392 (quick-win nativo en la UI de Traccar, ya viable). El bridge (#393/#394) queda para después del milestone de consumos.

Contexto

Problema (lo pidió Sergio 2026-05-28): los técnicos no avisan cuando regresan a Juárez después de salir de viaje. Se necesita que automáticamente se le notifique a la contadora (y a quien sea, por control interno) cuando vuelven. Requisito explícito: no invasivo con los técnicos.

Por qué no se construye de cero — las 3 piezas ya existen:

  1. Rastreo GPS de la flotilla → Traccar. ✅ CONFIRMADO (2026-05-28). El Traccar real corre en la VM traccar2025 del host ares (192.168.3.2) y recibe tráfico GPS constante (~20.5M paquetes de check-ins). La confusión inicial fue que existe un traccar2025 homónimo en orion que está muerto (leftover de migración, #391). La forma “más no-invasiva” (GPS ya en el carro) es viable. Falta solo capturar los internals para integrarlo (#398).
  2. Contexto del viaje → Amadeus. Ya sabe qué vehículo va en qué viaje (pivot equipo_vehiculo), qué técnicos (ordenes→equipos→usuarios), fechas (fecha_inicio/fecha_fin/fecha_cierre) y el origen (sitio Matriz). Incluso ya tiene el bounding box de Cd. Juárez en config/analisis.php.
  3. Canal de aviso → Amadeus. Patrón evento→listener→push + email (Gmail Workspace) ya probado, con flag de destinatarios en permisos. Se reusa tal cual.

El trabajo real es el puente: que Amadeus le pregunte a Traccar dónde están los vehículos que andan de viaje y, al re-entrar a Juárez, dispare el aviso con contexto.

Decisiones tomadas (2026-05-28):

  • Enfoque fased: validar Traccar → quick-win nativo → bridge integrado.
  • Detección por vehículo (no por celular) en fase inicial — el regreso del vehículo asignado cuenta como regreso del técnico (viajan en carro de empresa). Futuro (#395): detección por celular para los viajes en avión.
  • Destinatarios = permiso dedicado notificar_retorno (separado de recibir_notif_viajes, para controlarlo independiente de los avisos de creación de viaje).

Sinergia estratégica: el bridge Amadeus↔Traccar no es un one-off. Habilita además: inferir hospedaje (decisión 3 del milestone de consumos), validación de corredor #379, y reduce la necesidad del checador geolocalizado #387.

✅ Bloqueador #1 — CERRADO 2026-05-28: el Traccar real vive en ares

Historia en dos pasos:

  1. #391 demostró que traccar2025 en orion NO sirve GPS (red del guest muerta: tap RX=5/TX=0 de por vida, 0 en 30s). Era un leftover de migración — qemu lanzado con -S -incoming fd:22 (destino de una migración que nunca completó), por eso el guest ejecuta pero su NIC está muerta. El RSS de 46 MB (#138) fue pista falsa (VM idle + swap).
  2. #396 (respuesta de Sergio): había un segundo host de VMs sin documentar, SSH alias ares (192.168.3.2). Ahí corre el traccar2025 real y vivo: vnet5 con ~20.5M paquetes inbound (check-ins de trackers, llegan desde fuera de la LAN vía IP pública/port-forward). La premisa del proyecto se sostiene.

ares quedó perfilado completo en ~/agy/electrosystems/servers/ares/ (README + findings) e inventariado en INVENTORY.md.

Gate #398 — CERRADO 2026-05-28. Internals del Traccar capturados: VM en 201.218.172.10 (IP pública), Traccar 6.6 (Jetty 11.0.24), web/REST API en :8082 alcanzable desde la LAN interna (http://201.218.172.10:8082/api/), puerto de dispositivos 5046 (Teltonika). /api/server responde sin auth desde la red interna; emailEnabled:true. Ya hay todo para el quick-win (#392) y el bridge (#393/#394). Detalle en electrosystems/servers/ares/findings.md.

Notas técnicas

Hallazgos del codebase de Amadeus (exploración 2026-05-28)

  • Viaje (app/Models/Viaje.php:20-23): fecha_inicio, fecha_fin, fecha_cierre (nullable), dias_servicio. Activo = fecha_cierre IS NULL (scope abiertos() línea 182). No hay enum de estado. Origen vía ordenes()→sitio (Matriz = matriz=true).
  • Cadena viaje→vehículo→técnico: Viaje→ordenes()→Orden→equipos()→Equipo, y de ahí equipo_vehiculo (pivot, fuente de verdad) → Vehiculo, y usuarios() → técnicos.
  • Vehiculo: tiene numero, marca, modelo, año, color, placas. NO tiene device_id/imei/traccar_id → hay que agregar traccar_device_id (#393).
  • Juárez ya geocercado en config: config/analisis.php:85-90 → cd-juarez bbox lat 31.55–31.95, lng -106.65 a -106.25. Reusable directo para la detección. (El sitio Matriz id≈50 tiene latitud/longitud — verificar que no estén null.)
  • Notificaciones reusables: evento ViajeCreado → listeners EnviarNotificacionEmailViajeCreado + EnviarNotificacionPushViajeCreado (ambos ShouldQueue, auto-discovery L11). Destinatarios vía NotificarViajeCreadoService + flag permisos.recibir_notif_viajes. PushNotificationService (VAPID). Mailable ViajeCreadoMail. Se clona el patrón para RetornoDetectado.
  • NO hay scheduler/cron en Amadeus hoy (solo inspire en routes/console.php, sin schedule()). El bridge por polling necesita montar php artisan schedule:run en cron (o supervisor) en la VM amadeus. Alternativa: webhook de Traccar (Traccar puede hacer POST a un endpoint en eventos de geofence) → evita el polling y el scheduler. Evaluar webhook vs polling en #394 según lo que soporte la versión de Traccar instalada.
  • NO existe integración Traccar/GPS de vehículos en Amadeus hoy (grep limpio).

Arquitectura del bridge (#394) — dos opciones de transporte

  1. Polling (más portable): comando php artisan retorno:detectar cada ~5-10 min vía cron. Para cada viaje activo con destino fuera de Juárez, consulta la última posición de su(s) vehículo(s) en la API de Traccar (/api/positions?deviceId=), calcula si está dentro del bbox de Juárez, y compara con el estado anterior persistido. Transición fuera→dentro = retorno → evento. Persistir un flag tipo viajes.retorno_detectado_at para idempotencia.
  2. Webhook de Traccar (más limpio, menos latencia): definir geofence “Cd. Juárez” en Traccar y un computed attribute / notification con tipo “web” que haga POST a un endpoint de Amadeus (POST /api/traccar/geofence, Sanctum o token compartido). Amadeus recibe {deviceId, geofenceId, enter}, mapea device→vehículo→viaje activo, y dispara el evento. No requiere scheduler. Preferida si la versión de Traccar lo soporta (Traccar tiene notificaciones web desde hace varias versiones).

Quick-win nativo (#392) — qué se puede hoy en Traccar sin código

Traccar trae geofences + notificaciones por email/web nativas. Se puede definir el polígono de Juárez y una notificación “Geofence entrada” dirigida a la contadora. Cae corto en: no distingue “venía de viaje” de “movimiento local”, y no trae contexto (técnico, folio). Sirve como cobertura provisional, no como solución final.

Caso avión (#395) — por qué no lo cubre Traccar

Si el técnico vuela, el vehículo no se mueve (se queda en Juárez o en otro lado), así que Traccar nunca detecta “regreso”. Para ese caso (raro, según Sergio) se necesita señal del celular del técnico vía la PWA — geofence ligero reusando navigator.geolocation (mismo patrón que #381 consumos / #387 checador). Es más invasivo (permiso de ubicación), por eso queda como fase futura y acotada solo al caso avión.

Bitácora

2026-05-28 — análisis inicial + decisiones

  • Pidió Sergio: notificar automáticamente a la contadora (y a quien sea) cuando los técnicos regresan a Juárez tras un viaje, por control interno, sin ser invasivo con los técnicos. Analizar plataformas/servidores/apps existentes para ver qué sirve o si hay que hacer algo de cero.
  • Hice: análisis cross-plataforma. Lectura de amadeus.md + amadeus-consumos-milestone.md (que ya menciona Traccar), exploración read-only del codebase de Amadeus (subagente Explore) y grep de Traccar en hub + repo electrosystems/. Hallazgo central: las 3 piezas ya existen (Traccar = rastreo, Amadeus = contexto de viaje + canal de notificación); solo falta el puente. NO hay que construir de cero. Identifiqué el bloqueador #1: traccar2025 puede estar idle/roto (RSS 47 MB, #138) y vive en un host EOL.
  • Decisiones de Sergio (vía preguntas): (1) enfoque fased — validar → quick-win → bridge; (2) detección por vehículo en fase inicial, por celular en futuro solo para viajes en avión; (3) destinatarios vía permiso dedicado notificar_retorno.
  • Documenté: este design-doc con roadmap en 5 pendientes (#391-#395) y dependencias condicionales. #391 (validar Traccar) es lo único que cabe antes del milestone de consumos del 2-junio; #393/#394 quedan cond:post-milestone.
  • Falta: ejecutar #391 (validación read-only de Traccar) cuando Sergio dé luz verde — eso confirma si el proyecto es viable como está planteado.

2026-05-28 (más tarde) — #391 EJECUTADO: traccar2025 NO sirve GPS (red del guest muerta)

  • Pidió Sergio: arrancar con #391 (validar Traccar read-only).
  • Hice (SSH read-only a orion 192.168.20.2:58695, llave id_rsa_es, autorizado por default para diagnóstico):
    • virsh list → traccar2025 running (Id 1). virsh domstate --reason → running (restored) (la VM fue restaurada de una migración: el qemu se lanzó con -S -incoming fd:22).
    • virsh cpu-stats → cpu_time avanza (114197.411→114197.430 en 3s) → el guest sí ejecuta, pero idle.
    • dommemstat → RSS 46 MB (igual que el #138). Conclusión: NO es el indicador de “muerto” — se explica por VM idle + presión de swap en orion (654/767 MB swap usado): las páginas de una VM idle se mandan a swap y dejan de contar como RSS. #138 era una pista falsa.
    • El problema real es la RED del guest. ARP sweep de 192.168.10.0/24 (segmento de br1, donde está bridgeada la VM vía eth4+vnet0) → la MAC 52:54:00:64:6c:b9 no resuelve. tcpdump del MAC en br1 (20s) → 0 paquetes. tcpdump directo en vnet0 (tap del guest, 30s) → 0 paquetes. Contadores del tap: RX=5 / TX=0 paquetes, 300 bytes en TODA la vida de la interfaz.
    • Sin DNAT/port-forward en iptables nat de orion hacia la VM; sin leases dnsmasq; sin proceso java/traccar en el host.
  • Veredicto: traccar2025 está encendida pero su red está completamente muerta — no recibe check-ins de trackers ni responde nada. No es un Traccar funcional. Un servidor Traccar sirviendo flotilla tendría tráfico constante (los GPS reportan cada segundos/minutos). La premisa central del proyecto (“la flotilla ya está en Traccar, solo falta el bridge”) no se sostiene con esta VM.
  • Pivote: abierto #396 — confirmar con Sergio dónde vive realmente el GPS de los vehículos hoy (otro Traccar / portal del proveedor del GPS / no hay rastreo funcional). De esa respuesta depende todo: rehabilitar Traccar, integrar la plataforma del proveedor, o pivotar a detección por celular (#395). Proyecto bloqueado hasta esa respuesta.
  • Side effect documental: #138 de orion-decommission queda resuelto con dato duro — traccar2025 NO está sirviendo (no por RAM sino por red), así que para el decommission de orion no hay que preservar/migrar este servicio tal cual; lo que importa es dónde está el Traccar real (si existe).

2026-05-28 (noche) — #396 RESUELTO: el Traccar real vive en ares (segundo host KVM)

  • Aclaró Sergio: “Error mío, hay otra VM de traccar en otro servidor. Había olvidado mencionarte que tenemos otro servidor de VMs. Está con el ssh alias de ares.” Pidió documentarlo completo en ~/agy/electrosystems y sacar la info necesaria.
  • Hice (SSH read-only a ares 192.168.3.2:58695, user electrosystems): perfilé el host completo. Es un segundo hypervisor KVM/libvirt sin documentar — Ubuntu 20.04.5, dual Xeon X5675 (24 threads), 62 GiB RAM, 3.6 TB (15% usado), dual-bridge br0 (192.168.3.2/.3.x) + br2 (192.168.20.24/.20.x), también Samba + dnsmasq DNS de las VLANs. Corren 5 VMs (autostart): CentosVPNpush (VPN/router dual-homed), Contabilidad (8c/48G), uisp-elpaso, inventario-componentes, y traccar2025.
  • Confirmé el Traccar vivo: la VM traccar2025 de ares (vnet5 en br2, MAC 52:54:00:3d:66:63) tiene RX 693k / TX 20.5M paquetes en sus contadores → recibe ~20.5M check-ins (contraste total con el orion muerto RX=5/TX=0). Este es el Traccar real.
  • Reconcilié el misterio de #391: la VM de orion estaba en running (restored) con -incoming fd:22 = era el destino de una migración que nunca completó (NIC nunca cableado). Por eso ejecutaba pero sin red. El working instance estaba aquí en ares todo el tiempo.
  • NO pude capturar los internals del Traccar (IP/puerto/versión/API/DB) read-only: el guest no responde ICMP ni abre 8082 en la LAN (los GPS le pegan desde fuera vía IP pública/port-forward), no hay guest-agent ni lease DHCP, y tcpdump necesita sudo (sin NOPASSWD en ares). → abierto #398 para capturarlo con sudo tcpdump (Sergio) o creds de la VM.
  • Documenté: ~/agy/electrosystems/servers/ares/README.md + findings.md nuevos; fila + fact card de ares en INVENTORY.md; corregí las entradas de orion (su traccar2025 = leftover muerto, no “GPS tracking”) en INVENTORY.md y servers/orion/README.md.
  • Estado: proyecto desbloqueado, premisa confirmada. Siguiente = #398 → luego #392 (quick-win) y el bridge #393/#394 (post-milestone consumos).

2026-05-28 (noche, cont.) — #398 avance: la VM Traccar está en el bloque público; commit de huérfanos en electrosystems

  • tcpdump en ares (Sergio corrió el sudo): vnet5 mostró ARP who-has 201.218.172.x tell 201.218.172.1 → br2 tronca el bloque público 201.218.172.0/24 (el mismo de reverse-proxy). La VM traccar2025 casi seguro tiene IP pública ahí — explica por qué los GPS le pegan desde celular y por qué no aparecía en la LAN interna. El resto de los 40 paquetes era ruido broadcast (Ubiquiti discovery en .20.x), no tráfico de la VM. Falta captura filtrada por MAC (ether host 52:54:00:3d:66:63) para la IP exacta + puerto. Documentado en electrosystems/servers/ares/findings.md.
  • Side task (lo pidió Sergio): revisé y commiteé el resto de cambios huérfanos del repo electrosystems (quedaron sin commitear por sesiones no cerradas). 5 commits agrupados por tema: (A) ares+orion [míos], (B) migración ADFSA 05-07/08/20/21, (C) capacidad RF L2L Telcel, (D) oxidized groups + inventory-merger, (E) dirs de host huérfanos (cpe-benito-juarez/laptop-ia/nagios/sw-villa-ahumada). Escaneado sin secretos. Pusheado al remote NAS. Árbol limpio.

2026-05-28 (noche, cierre) — #398 CERRADO: Traccar 6.6 en 201.218.172.10:8082

  • Captura filtrada por MAC (tcpdump … ether host 52:54:00:3d:66:63, Sergio corrió el sudo): la VM es 201.218.172.10 (IP pública; ARP reply confirma la MAC). Puerto 8082 = web/REST API de Traccar (y responde a la LAN interna: visto .10:8082 ↔ 192.168.20.254); puerto 5046 = dispositivos GPS (Teltonika) con sesión activa de un tracker en celular. El resto = escaneos de internet a la IP pública.
  • Versión vía curl desde ares (tiene ruta al bloque público vía 192.168.3.1): GET /api/server → Traccar 6.6, Jetty 11.0.24, registration:false, readonly:false, emailEnabled:true, geocoderEnabled:true. /api/server no requiere auth desde la LAN; los endpoints de datos sí (token/sesión).
  • Implicaciones: (1) el quick-win #392 es viable ya (geofence + email nativo en Traccar 6.6); (2) el bridge tiene API base http://201.218.172.10:8082/api/ alcanzable internamente — GET /api/devices para el mapeo, GET /api/positions?deviceId= para el polling, o webhook de geofence. Falta solo (impl.) crear token read-only (login admin de Sergio) y mapear vehículo↔deviceId.
  • Estado: fundamentos del proyecto 100% cerrados. Próximo accionable = #392 (UI de Traccar). El bridge #393/#394 espera al post-milestone de consumos.