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

```typescript
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

```typescript
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

```typescript
// 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:

```typescript
// 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

```typescript
// 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

```typescript
// 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*