erp-transportistas-v2/docs/20-frontend/DASHBOARD-DESPACHO.md

Dashboard de Despacho - Documentacion Tecnica

Feature: despacho Sprint: S6 Estado: Funcional (mapas pendientes) Fecha: 2026-01-28

---

1. Vision General

El Dashboard de Despacho permite a los despachadores:

• Visualizar unidades disponibles en un mapa
• Ver viajes pendientes de asignacion
• Asignar viajes a unidades con sugerencias inteligentes
• Monitorear estado de la flota en tiempo real

---

2. Arquitectura de Componentes

DespachoPage
├── DispatchMap (70% del viewport)
│   ├── MapBackground (placeholder CSS gradient)
│   ├── UnidadMarkers (posiciones con estado)
│   └── ViajeMarkers (origenes/destinos)
├── ViajesPendientesPanel (30% lado derecho)
│   ├── FiltrosViajes
│   └── ListaViajes
└── AsignacionModal (overlay)
    ├── DetallesViaje
    ├── SugerenciasUnidad (scoring)
    └── FormAsignacion

---

3. Tipos Principales

3.1 ENUMs

enum EstadoUnidadDespacho {
  DISPONIBLE = 'DISPONIBLE',
  EN_RUTA = 'EN_RUTA',
  EN_SITIO = 'EN_SITIO',
  EN_MANTENIMIENTO = 'EN_MANTENIMIENTO',
  FUERA_SERVICIO = 'FUERA_SERVICIO'
}

enum EstadoViajeDespacho {
  PENDIENTE = 'PENDIENTE',
  ASIGNADO = 'ASIGNADO',
  EN_TRANSITO = 'EN_TRANSITO',
  COMPLETADO = 'COMPLETADO'
}

enum TipoCertificacion {
  MATERIALES_PELIGROSOS = 'MATERIALES_PELIGROSOS',
  REFRIGERADO = 'REFRIGERADO',
  SOBREDIMENSIONADO = 'SOBREDIMENSIONADO'
}

3.2 Interfaces

interface EstadoUnidad {
  id: string;
  unidadId: string;
  numeroEconomico: string;
  operadorId: string;
  operadorNombre: string;
  estado: EstadoUnidadDespacho;
  capacidad: 'LLENA' | 'PARCIAL' | 'VACIA';
  ubicacion: { lat: number; lng: number };
  viajeActualId: string | null;
}

interface ViajePendiente {
  id: string;
  folio: string;
  clienteNombre: string;
  origen: { ciudad: string; lat: number; lng: number };
  destino: { ciudad: string; lat: number; lng: number };
  fechaCita: string;
  prioridad: 'ALTA' | 'MEDIA' | 'BAJA';
  restricciones: string[];
}

interface SugerenciaAsignacion {
  unidadId: string;
  numeroEconomico: string;
  operadorNombre: string;
  distanciaKm: number;
  tiempoEstimado: string;
  score: number;
  razon: string;
}

---

4. API Endpoints

4.1 Despacho API

Endpoint	Metodo	Descripcion
/api/v1/despacho/tablero	GET	Obtener datos del tablero
/api/v1/despacho/unidades	GET	Listar unidades con estado
/api/v1/despacho/unidades/disponibles	GET	Unidades disponibles para asignar
/api/v1/despacho/asignar	POST	Asignar viaje a unidad
/api/v1/despacho/sugerir	POST	Obtener sugerencias de asignacion

4.2 React Query Hooks

// api/despacho.api.ts
export const useTableroDespacho = () => useQuery({ queryKey: ['despacho', 'tablero'] });
export const useUnidadesDespacho = () => useQuery({ queryKey: ['despacho', 'unidades'] });
export const useSugerenciasAsignacion = (viajeId: string) => useMutation();
export const useAsignarViaje = () => useMutation();

---

5. Flujo de Asignacion

1. Despachador selecciona viaje pendiente en ViajesPendientesPanel
   └─> onClick abre AsignacionModal

2. AsignacionModal solicita sugerencias al backend
   └─> POST /despacho/sugerir { viajeId }
   └─> Backend retorna lista ordenada por score

3. Despachador revisa sugerencias con scores
   └─> Cada sugerencia muestra:
       - Distancia al origen
       - Tiempo estimado
       - Score (0-100)
       - Razon (ej: "Cercano y disponible")

4. Despachador selecciona unidad y confirma
   └─> POST /despacho/asignar { viajeId, unidadId, notas }

5. Sistema actualiza estados
   └─> Viaje: PENDIENTE → ASIGNADO
   └─> Unidad: DISPONIBLE → EN_RUTA
   └─> Envia notificacion a operador (WhatsApp)

---

6. Algoritmo de Scoring

El backend calcula un score para cada unidad disponible:

// Factores del score (implementado en dispatch.service.ts)
const score = (
  distanciaFactor * 0.4 +      // Cercania al origen (Haversine)
  capacidadFactor * 0.2 +      // Capacidad compatible
  certificacionFactor * 0.2 + // Certificaciones requeridas
  disponibilidadFactor * 0.2   // Tiempo desde ultima asignacion
);

---

7. Integracion con Mapas (Pendiente)

7.1 Estado Actual

Los componentes de mapa usan:

• CSS gradients como fondo
• Transformacion manual de coordenadas
• SVG para marcadores y rutas

7.2 Plan de Integracion

// Componente base propuesto
import { MapContainer, TileLayer, Marker } from 'react-leaflet';

const MapBase = ({ children }) => (
  <MapContainer center={[23.6345, -102.5528]} zoom={5}>
    <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
    {children}
  </MapContainer>
);

// Uso en DispatchMap
<MapBase>
  {unidades.map(u => (
    <Marker position={[u.ubicacion.lat, u.ubicacion.lng]} />
  ))}
</MapBase>

---

8. Tests Recomendados

// despacho.test.tsx
describe('Dashboard Despacho', () => {
  it('should render unidades on map');
  it('should open modal when viaje clicked');
  it('should show sugerencias sorted by score');
  it('should call asignar endpoint on confirm');
  it('should update UI after asignacion');
});

---

Sprint S6 - TASK-007 | Sistema SIMCO v4.0.0