6ed7f9e2ec
- Updated docs and inventory files - Added new architecture docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
434 lines
14 KiB
Markdown
434 lines
14 KiB
Markdown
# MAI-005: Despacho
|
|
|
|
**Version:** 1.0.0
|
|
**Fecha:** 2026-01-27
|
|
**Estado:** Diseño
|
|
**Prioridad:** P0 (Crítico - Workflow + NOM-068 Compliance)
|
|
|
|
---
|
|
|
|
## Descripción General
|
|
|
|
El módulo de Despacho es responsable de la liberación operativa del viaje, asegurando que todos los checklists, documentos, sellos y evidencias estén completos antes de que la unidad salga a ruta.
|
|
|
|
**Problema que resuelve:**
|
|
- Viajes que salen sin inspección pre-viaje (riesgo de accidentes)
|
|
- Falta de control de sellos de seguridad
|
|
- Documentación incompleta que genera problemas en ruta
|
|
- Incumplimiento de NOM-068 (condiciones físico-mecánicas)
|
|
|
|
---
|
|
|
|
## Objetivos del Módulo
|
|
|
|
1. **Checklist Pre-Viaje:** Inspección documentada según NOM-068
|
|
2. **Control de Sellos:** Registro y evidencia de sellos de seguridad
|
|
3. **Evidencias de Carga:** Fotos del estado de la carga antes de salir
|
|
4. **Kit Documental:** Compilar todos los documentos necesarios
|
|
5. **Liberación Oficial:** Evento de "gate out" con timestamp y responsable
|
|
|
|
---
|
|
|
|
## Alcance Funcional
|
|
|
|
### Incluido
|
|
|
|
- Checklist de inspección pre-viaje parametrizable
|
|
- Control de sellos (asignación, fotos, verificación)
|
|
- Captura de evidencias de carga
|
|
- Compilación de kit documental digital
|
|
- Registro de salida (gate out)
|
|
- Validaciones de despacho
|
|
- Notificación de salida
|
|
|
|
### Excluido
|
|
|
|
- Planeación y asignación (MAI-004)
|
|
- Tracking en ruta (MAI-006)
|
|
- Generación de Carta Porte (MAE-016)
|
|
|
|
---
|
|
|
|
## Actores
|
|
|
|
| Actor | Rol en el módulo |
|
|
|-------|------------------|
|
|
| Operador | Ejecuta checklist, registra sellos, toma evidencias |
|
|
| Despachador | Valida checklist, autoriza salida |
|
|
| Vigilancia | Confirma salida física (gate out) |
|
|
| Sistema | Valida documentación, genera alertas |
|
|
|
|
---
|
|
|
|
## Flujo Principal
|
|
|
|
```
|
|
VIAJE PLANIFICADO
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ 1. CHECKLIST PRE-VIAJE │
|
|
│ - Operador inspecciona unidad │
|
|
│ - Registra estado de cada punto │
|
|
│ - Adjunta fotos si hay observaciones │
|
|
│ - Firma digital del checklist │
|
|
└────────────────────┬────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ 2. CONTROL DE SELLOS │
|
|
│ - Asignar números de sello │
|
|
│ - Tomar foto de cada sello colocado │
|
|
│ - Registrar ubicación del sello │
|
|
└────────────────────┬────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ 3. EVIDENCIAS DE CARGA │
|
|
│ - Fotos de la carga │
|
|
│ - Peso en báscula (si aplica) │
|
|
│ - Firma de almacén │
|
|
└────────────────────┬────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ 4. KIT DOCUMENTAL │
|
|
│ - Orden de viaje │
|
|
│ - Carta porte (si ya generada) │
|
|
│ - Remisión/factura del cliente │
|
|
│ - Permisos especiales │
|
|
│ - Instrucciones de entrega │
|
|
└────────────────────┬────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ 5. VALIDACIÓN DE DESPACHO │
|
|
│ ✓ Checklist completo │
|
|
│ ✓ Sellos registrados │
|
|
│ ✓ Documentos completos │
|
|
│ ✓ Sin bloqueos de unidad/operador │
|
|
└────────────────────┬────────────────────┘
|
|
│
|
|
┌──────┴──────┐
|
|
│ │
|
|
▼ ▼
|
|
[APROBADO] [BLOQUEADO]
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────┐ ┌─────────────────┐
|
|
│ 6. GATE OUT │ │ Resolver y │
|
|
│ - Timestamp │ │ reintentar │
|
|
│ - GPS │ │ │
|
|
│ - Responsable│ │ │
|
|
└────────┬────────┘ └─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ VIAJE DESPACHADO │
|
|
│ → Inicia Tracking (MAI-006) │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Datos del Módulo
|
|
|
|
### Entidades Principales
|
|
|
|
| Entidad | Descripción | Estado |
|
|
|---------|-------------|--------|
|
|
| ChecklistPreViaje | Inspección de unidad | NO IMPLEMENTADA |
|
|
| ItemChecklist | Puntos de inspección | NO IMPLEMENTADA |
|
|
| SelloViaje | Registro de sellos | NO IMPLEMENTADA |
|
|
| EvidenciaCarga | Fotos de la carga | NO IMPLEMENTADA |
|
|
| DespachoViaje | Registro de liberación | NO IMPLEMENTADA |
|
|
|
|
### Campos Clave Checklist
|
|
|
|
| Campo | Tipo | Obligatorio | Descripción |
|
|
|-------|------|-------------|-------------|
|
|
| viaje_id | UUID | Sí | Viaje asociado |
|
|
| tipo_checklist | ENUM | Sí | PRE_VIAJE, POST_VIAJE |
|
|
| operador_id | UUID | Sí | Quien ejecuta |
|
|
| fecha_ejecucion | TIMESTAMP | Sí | Cuándo se ejecutó |
|
|
| firma_operador | TEXT | Sí | Firma digital |
|
|
| status | ENUM | Sí | EN_PROCESO, APROBADO, RECHAZADO |
|
|
| items | JSONB | Sí | Detalle de puntos inspeccionados |
|
|
|
|
---
|
|
|
|
## Requerimientos Funcionales
|
|
|
|
Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)
|
|
|
|
---
|
|
|
|
## Compliance NOM-068
|
|
|
|
El módulo debe cumplir con NOM-068-SCT-2-2014:
|
|
|
|
- **Checklist parametrizable** según tipo de vehículo
|
|
- **Puntos de inspección** según norma (llantas, frenos, luces, etc.)
|
|
- **Evidencia fotográfica** de condiciones
|
|
- **Bloqueo de salida** si hay fallas críticas
|
|
- **Registro auditable** de inspecciones
|
|
|
|
---
|
|
|
|
## Métricas del Módulo
|
|
|
|
| KPI | Fórmula | Meta |
|
|
|-----|---------|------|
|
|
| Checklists completados | % viajes con checklist | 100% |
|
|
| Tiempo de despacho | Avg(gate_out - inicio_checklist) | <45 min |
|
|
| Viajes bloqueados | % viajes con bloqueo | <5% |
|
|
| Sellos documentados | % viajes con sellos OK | 100% |
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
### Este módulo depende de:
|
|
- MAI-004 (Planeación): Viajes planificados
|
|
- MAI-011 (Flota): Datos de unidad y operador
|
|
- MAE-016 (Carta Porte): Documento para kit
|
|
|
|
### Otros módulos dependen de este:
|
|
- MAI-006 (Tracking): Inicia al despachar
|
|
- MAI-007 (POD): Viaje debe estar despachado
|
|
|
|
---
|
|
|
|
## Historias de Usuario
|
|
|
|
Ver carpeta: [historias-usuario/](./historias-usuario/)
|
|
|
|
| US | Titulo | Prioridad | SP |
|
|
|----|--------|-----------|-----|
|
|
| US-MAI005-001 | Ejecutar checklist pre-viaje | Alta | 8 |
|
|
| US-MAI005-002 | Registrar sellos de seguridad | Alta | 5 |
|
|
| US-MAI005-003 | Capturar evidencias de carga | Alta | 5 |
|
|
| US-MAI005-004 | Compilar kit documental | Media | 3 |
|
|
| US-MAI005-005 | Registrar salida (gate out) | Alta | 5 |
|
|
| US-MAI005-006 | Sugerir mejor unidad para asignacion | Alta | 8 |
|
|
| US-MAI005-007 | Dashboard de unidades en tiempo real | Alta | 5 |
|
|
| US-MAI005-008 | Configurar reglas de asignacion | Media | 5 |
|
|
| US-MAI005-009 | Reasignar viaje con motivo | Alta | 5 |
|
|
| US-MAI005-010 | Consultar logs de despacho | Media | 3 |
|
|
|
|
---
|
|
|
|
## Algoritmo de Asignacion Inteligente
|
|
|
|
El Centro de Despacho implementa un algoritmo de asignacion inteligente que sugiere la mejor unidad disponible para cada viaje basandose en multiples criterios ponderados.
|
|
|
|
### Funcion Principal: suggestBestAssignment()
|
|
|
|
La funcion `suggestBestAssignment()` analiza todas las unidades disponibles y calcula un score compuesto para cada una, retornando una lista ordenada de sugerencias con su puntuacion detallada.
|
|
|
|
```typescript
|
|
interface AssignmentSuggestion {
|
|
unitId: string;
|
|
operatorId: string;
|
|
totalScore: number;
|
|
scoreBreakdown: {
|
|
distance: number; // 0-100 (peso 40%)
|
|
capacity: number; // 0-100 (peso 25%)
|
|
availability: number; // 0-100 (peso 20%)
|
|
skills: number; // 0-100 (peso 15%)
|
|
};
|
|
estimatedArrival: Date;
|
|
distanceKm: number;
|
|
}
|
|
|
|
async function suggestBestAssignment(
|
|
tripId: string,
|
|
options?: {
|
|
maxResults?: number; // default: 5
|
|
maxDistanceKm?: number; // default: 50
|
|
requiredSkills?: string[];
|
|
}
|
|
): Promise<AssignmentSuggestion[]>;
|
|
```
|
|
|
|
### Criterios de Scoring
|
|
|
|
| Criterio | Peso | Calculo | Bonus/Penalidad |
|
|
|----------|------|---------|-----------------|
|
|
| Distancia | 40% | `100 - (km * 2)` | +10 si < 10km, -20 si > 25km |
|
|
| Capacidad | 25% | Match con requerimiento | +10 si capacidad exacta |
|
|
| Disponibilidad | 20% | Basado en turno activo | 100 si disponible en turno |
|
|
| Skills/Certificaciones | 15% | Match con requerimientos | +5 por cada skill adicional |
|
|
|
|
#### Detalle de Calculo por Criterio
|
|
|
|
**Distancia (40%)**
|
|
- Base: `max(0, 100 - (distanciaKm * 2))`
|
|
- Bonus: +10 puntos si distancia < 10km (unidad cercana)
|
|
- Penalidad: -20 puntos si distancia > 25km (unidad lejana)
|
|
- Minimo: 0 puntos
|
|
|
|
**Capacidad (25%)**
|
|
- 100 puntos si capacidad >= requerimiento
|
|
- 0 puntos si capacidad < requerimiento
|
|
- Bonus: +10 puntos si capacidad coincide exactamente (evita sobre-capacidad)
|
|
|
|
**Disponibilidad (20%)**
|
|
- 100 puntos si unidad AVAILABLE y operador en turno activo
|
|
- 50 puntos si unidad disponible pero fuera de turno
|
|
- 0 puntos si unidad no disponible
|
|
|
|
**Skills/Certificaciones (15%)**
|
|
- Base: (skills coincidentes / skills requeridos) * 100
|
|
- Bonus: +5 puntos por cada skill adicional (max +20)
|
|
- Ejemplos de skills: HAZMAT, refrigerado, carga pesada, escolta
|
|
|
|
### Formula Haversine
|
|
|
|
Para calcular la distancia entre la ubicacion actual de la unidad y el punto de origen del viaje, se utiliza la formula Haversine:
|
|
|
|
```typescript
|
|
/**
|
|
* Calcula la distancia en kilometros entre dos puntos geograficos
|
|
* usando la formula Haversine.
|
|
*/
|
|
function calculateHaversineDistance(
|
|
lat1: number,
|
|
lon1: number,
|
|
lat2: number,
|
|
lon2: number
|
|
): number {
|
|
const R = 6371; // Radio de la Tierra en km
|
|
|
|
const toRadians = (degrees: number): number => {
|
|
return degrees * (Math.PI / 180);
|
|
};
|
|
|
|
const dLat = toRadians(lat2 - lat1);
|
|
const dLon = toRadians(lon2 - lon1);
|
|
|
|
const a =
|
|
Math.sin(dLat / 2) * Math.sin(dLat / 2) +
|
|
Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) *
|
|
Math.sin(dLon / 2) * Math.sin(dLon / 2);
|
|
|
|
const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
|
|
|
|
return R * c; // Distancia en km
|
|
}
|
|
```
|
|
|
|
### Estados de Unidad
|
|
|
|
El sistema mantiene el estado de cada unidad en tiempo real para determinar disponibilidad:
|
|
|
|
| Estado | Codigo | Descripcion | Disponible |
|
|
|--------|--------|-------------|------------|
|
|
| Disponible | AVAILABLE | Unidad lista para asignacion | Si |
|
|
| Asignada | ASSIGNED | Asignada a viaje, pendiente despacho | No |
|
|
| En Ruta | EN_ROUTE | Viajando hacia origen o destino | No |
|
|
| En Sitio | ON_SITE | En punto de carga/descarga | No |
|
|
| Retornando | RETURNING | Regresando a base | Parcial |
|
|
| Desconectada | OFFLINE | Sin comunicacion GPS | No |
|
|
| Mantenimiento | MAINTENANCE | En taller o inspeccion | No |
|
|
|
|
### Entidades del Centro de Despacho
|
|
|
|
| Entidad | Descripcion | Estado |
|
|
|---------|-------------|--------|
|
|
| DispatchBoard | Tablero de despacho con viajes pendientes | NO IMPLEMENTADA |
|
|
| UnitStatus | Estado actual de unidad con ubicacion GPS | NO IMPLEMENTADA |
|
|
| DispatchLog | Registro de asignaciones y cambios | NO IMPLEMENTADA |
|
|
| DispatchRule | Reglas configurables de asignacion | NO IMPLEMENTADA |
|
|
|
|
#### DispatchBoard
|
|
|
|
Tablero central que muestra viajes pendientes de asignacion:
|
|
|
|
```typescript
|
|
interface DispatchBoard {
|
|
id: string;
|
|
tenantId: string;
|
|
date: Date;
|
|
pendingTrips: TripSummary[];
|
|
availableUnits: UnitSummary[];
|
|
assignments: Assignment[];
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
}
|
|
```
|
|
|
|
#### UnitStatus
|
|
|
|
Estado en tiempo real de cada unidad:
|
|
|
|
```typescript
|
|
interface UnitStatus {
|
|
id: string;
|
|
unitId: string;
|
|
status: UnitStatusEnum;
|
|
currentLocation: {
|
|
latitude: number;
|
|
longitude: number;
|
|
timestamp: Date;
|
|
accuracy: number;
|
|
};
|
|
currentTripId: string | null;
|
|
operatorId: string;
|
|
shiftStart: Date | null;
|
|
shiftEnd: Date | null;
|
|
lastUpdate: Date;
|
|
}
|
|
```
|
|
|
|
#### DispatchLog
|
|
|
|
Auditoria de todas las acciones de despacho:
|
|
|
|
```typescript
|
|
interface DispatchLog {
|
|
id: string;
|
|
tripId: string;
|
|
action: 'SUGGESTED' | 'ASSIGNED' | 'REASSIGNED' | 'CANCELLED';
|
|
unitId: string;
|
|
operatorId: string;
|
|
performedBy: string;
|
|
reason: string | null;
|
|
previousUnitId: string | null;
|
|
scoreAtAssignment: number | null;
|
|
timestamp: Date;
|
|
}
|
|
```
|
|
|
|
#### DispatchRule
|
|
|
|
Reglas configurables por tenant:
|
|
|
|
```typescript
|
|
interface DispatchRule {
|
|
id: string;
|
|
tenantId: string;
|
|
name: string;
|
|
priority: number;
|
|
conditions: {
|
|
tripTypes?: string[];
|
|
customers?: string[];
|
|
routes?: string[];
|
|
timeRanges?: { start: string; end: string }[];
|
|
};
|
|
weights: {
|
|
distance: number; // default: 40
|
|
capacity: number; // default: 25
|
|
availability: number;// default: 20
|
|
skills: number; // default: 15
|
|
};
|
|
isActive: boolean;
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
*Modulo MAI-005 - ERP Transportistas - Sistema SIMCO v4.0.0*
|