# MAI-011: Gestion de Flota

**Modulo:** MAI-011 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
**Epica:** EPIC-MAI-011 | **Schema BD:** fleet | **DDL:** 02-fleet-schema-ddl.sql

---

## Descripcion

Gestion integral de la flota vehicular y operadores de una empresa transportista de carga. Abarca el control completo del ciclo de vida de unidades motrices (tractocamiones, tortones, rabones, camionetas), remolques (cajas secas, refrigeradas, plataformas, tanques, portacontenedores), operadores/conductores y toda su documentacion asociada. El modulo es la base operativa que alimenta a los modulos de planeacion (MAI-004), despacho (MAI-005), tracking (MAI-006) y mantenimiento (MAI-013).

---

## Categorias de Activos

### Unidades Motrices (Tractoras)
| Tipo | Descripcion | Configuraciones Tipicas |
|------|-------------|------------------------|
| TRACTORA | Tractocamion (quinta rueda) | T3S2, T3S3, T3S2R4 |
| TORTON | Camion de 3 ejes, carga media | C3 |
| RABON | Camion de 2 ejes, carga ligera | C2 |
| CAMIONETA | Vehiculo utilitario, carga menor | C2 |

### Remolques y Cajas
| Tipo | Descripcion | Uso Principal |
|------|-------------|---------------|
| CAJA_SECA | Caja cerrada sin temperatura | Carga general, paqueteria |
| CAJA_REFRIGERADA | Caja con sistema de refrigeracion | Alimentos, farmaceuticos |
| PLATAFORMA | Plataforma abierta/baja | Maquinaria, materiales |
| TANQUE | Cisterna para liquidos/gases | Combustible, quimicos |
| PORTACONTENEDOR | Chasis para contenedores maritimos | Intermodal, importacion/exportacion |
| REMOLQUE | Remolque generico | Doble articulacion (full) |

---

## Actores

| Actor | Responsabilidades |
|-------|-------------------|
| **Jefe de Flota** | Alta/baja de unidades y remolques, control de documentacion, bloqueo por vencimientos, reportes de disponibilidad |
| **Coordinador de Trafico** | Consultar disponibilidad de recursos, solicitar asignaciones, verificar aptitud de unidad/operador para viaje |
| **Recursos Humanos** | Registro de operadores, gestion de documentos personales (INE, CURP, RFC, NSS), altas y bajas |
| **Operador/Conductor** | Consultar sus documentos y vigencias, reportar incidencias, recibir notificaciones de vencimiento |

---

## Funcionalidades Principales

### F1. Alta, Baja y Modificacion de Unidades
- Registro de unidades motrices con datos vehiculares completos (marca, modelo, anio, serie, motor)
- Placas y estado de expedicion
- Permiso SCT con tipo y numero
- Configuracion vehicular (C2, C3, T3S2, T3S3, T3S2R4)
- Capacidades (peso en kg, volumen en m3, pallets)
- Datos de combustible (tipo, rendimiento km/l, capacidad de tanque)
- GPS (proveedor, IMEI)
- Propiedad (propia o de tercero/carrier)
- Costos (adquisicion, valor actual)
- Baja con fecha y motivo

### F2. Alta, Baja y Modificacion de Remolques
- Registro de remolques con tipo (caja seca, refrigerada, plataforma, tanque, portacontenedor)
- Dimensiones fisicas (largo, ancho, alto en metros)
- Capacidades (peso, volumen, pallets)
- Datos de refrigeracion cuando aplica (marca, modelo, rango de temperatura)
- Propiedad y estado

### F3. Gestion de Operadores
- Registro completo: datos personales, contacto, direccion, nacimiento
- Documentos de identidad: CURP, RFC, NSS
- Licencia de conducir: tipo (A-F), numero, vigencia, estado de expedicion
- Licencia Federal (tipo F) obligatoria para autotransporte federal
- Certificaciones: certificado fisico medico, antidoping, materiales peligrosos
- Datos bancarios para liquidaciones (banco, cuenta, CLABE)
- Esquema de pago (fijo, por viaje, mixto)
- Metricas de desempeno (calificacion, total viajes, km recorridos, incidentes)
- Unidad asignada por defecto

### F4. Control de Disponibilidad
- Estados de unidad: DISPONIBLE, EN_VIAJE, EN_TALLER, BLOQUEADA, BAJA
- Estados de operador: ACTIVO, EN_VIAJE, DESCANSO, VACACIONES, INCAPACIDAD, SUSPENDIDO, BAJA
- Consulta en tiempo real de recursos disponibles para asignacion
- Bloqueo automatico por documentacion vencida o mantenimiento pendiente

### F5. Documentos con Vencimiento y Alertas
- Documentos por entidad (UNIDAD, REMOLQUE, OPERADOR) con referencia polimorfica
- Tipos: LICENCIA, INE, CURP, RFC, NSS, TARJETA_CIRCULACION, POLIZA_SEGURO, VERIFICACION, PERMISO_SCT, CERTIFICADO_FISICO, ANTIDOPING, OTRO
- Vigencia con fecha de emision y vencimiento
- Dias de alerta configurables por documento (default 30 dias)
- Archivo adjunto (URL, nombre, tipo, tamano)
- Verificacion por supervisor (verificado, verificado_por, fecha)
- Alertas automaticas antes de vencimiento

### F6. Configuraciones Vehiculares
- Asignacion operador a unidad (tractora)
- Asignacion de remolque a unidad tractora
- Registro de fecha de inicio y fin de asignacion
- Historial completo de asignaciones
- Validacion: operador con licencia vigente y tipo adecuado
- Validacion: unidad con documentos vigentes

### F7. Bloqueo por Documentos Vencidos
- Regla de negocio: unidad con poliza de seguro, verificacion o permiso SCT vencido pasa a estado BLOQUEADA
- Regla de negocio: operador con licencia federal vencida, certificado fisico vencido o antidoping vencido pasa a estado SUSPENDIDO
- No se permite asignar recursos bloqueados/suspendidos a viajes
- Alerta al jefe de flota con listado de documentos por vencer

---

## Entidades (DDL - Source of Truth)

| Entidad | Tabla | Descripcion |
|---------|-------|-------------|
| Unidad | `fleet.unidades` | Unidades motrices (tractocamiones, tortones, rabones, camionetas) |
| Remolque | `fleet.remolques` | Remolques, cajas secas, refrigeradas, plataformas, tanques |
| Operador | `fleet.operadores` | Operadores/conductores con licencias y certificaciones |
| DocumentoFlota | `fleet.documentos_flota` | Documentos de unidades, remolques y operadores (referencia polimorfica) |
| Asignacion | `fleet.asignaciones` | Historial de asignaciones unidad-operador-remolque |

### ENUMs del Schema

| ENUM | Valores |
|------|---------|
| `fleet.tipo_unidad` | TRACTORA, REMOLQUE, CAJA_SECA, CAJA_REFRIGERADA, PLATAFORMA, TANQUE, PORTACONTENEDOR, TORTON, RABON, CAMIONETA |
| `fleet.estado_unidad` | DISPONIBLE, EN_VIAJE, EN_TALLER, BLOQUEADA, BAJA |
| `fleet.tipo_licencia` | A (Motociclista), B (Automovilista particular), C (Chofer particular), D (Chofer publico pasajeros), E (Chofer publico carga), F (Federal SCT) |
| `fleet.estado_operador` | ACTIVO, EN_VIAJE, DESCANSO, VACACIONES, INCAPACIDAD, SUSPENDIDO, BAJA |
| `fleet.tipo_documento` | LICENCIA, INE, CURP, RFC, NSS, TARJETA_CIRCULACION, POLIZA_SEGURO, VERIFICACION, PERMISO_SCT, CERTIFICADO_FISICO, ANTIDOPING, OTRO |

---

## API Endpoints (Planificados)

### Unidades
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | `/api/fleet/unidades` | Listar unidades con filtros (tipo, estado, disponibilidad) |
| GET | `/api/fleet/unidades/:id` | Detalle de unidad |
| POST | `/api/fleet/unidades` | Registrar nueva unidad |
| PATCH | `/api/fleet/unidades/:id` | Actualizar unidad |
| PATCH | `/api/fleet/unidades/:id/estado` | Cambiar estado de unidad |
| DELETE | `/api/fleet/unidades/:id` | Baja logica de unidad |

### Remolques
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | `/api/fleet/remolques` | Listar remolques con filtros |
| GET | `/api/fleet/remolques/:id` | Detalle de remolque |
| POST | `/api/fleet/remolques` | Registrar nuevo remolque |
| PATCH | `/api/fleet/remolques/:id` | Actualizar remolque |
| PATCH | `/api/fleet/remolques/:id/estado` | Cambiar estado de remolque |

### Operadores
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | `/api/fleet/operadores` | Listar operadores con filtros (estado, disponibilidad, licencia) |
| GET | `/api/fleet/operadores/:id` | Detalle de operador |
| POST | `/api/fleet/operadores` | Registrar nuevo operador |
| PATCH | `/api/fleet/operadores/:id` | Actualizar operador |
| PATCH | `/api/fleet/operadores/:id/estado` | Cambiar estado de operador |
| GET | `/api/fleet/operadores/disponibles` | Operadores disponibles para asignacion |

### Documentos
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | `/api/fleet/documentos` | Listar documentos con filtros (entidad, tipo, vencimiento) |
| GET | `/api/fleet/documentos/:id` | Detalle de documento |
| POST | `/api/fleet/documentos` | Registrar documento |
| PATCH | `/api/fleet/documentos/:id` | Actualizar documento |
| PATCH | `/api/fleet/documentos/:id/verificar` | Verificar documento |
| GET | `/api/fleet/documentos/por-vencer` | Documentos proximos a vencer |

### Asignaciones
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | `/api/fleet/asignaciones` | Listar asignaciones |
| POST | `/api/fleet/asignaciones` | Crear asignacion operador-unidad-remolque |
| PATCH | `/api/fleet/asignaciones/:id/finalizar` | Finalizar asignacion |
| GET | `/api/fleet/asignaciones/historial/:entidadId` | Historial por unidad u operador |

### Dashboard
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | `/api/fleet/dashboard/disponibilidad` | Resumen de disponibilidad de flota |
| GET | `/api/fleet/dashboard/documentos-vencer` | Documentos por vencer (proximos 30 dias) |
| GET | `/api/fleet/dashboard/estadisticas` | Estadisticas generales de flota |
| GET | `/api/fleet/reportes/exportar` | Exportar reporte de flota (Excel/PDF) |

---

## Historias de Usuario (Resumen)

| ID | Titulo | SP | Prioridad |
|----|--------|----|-----------|
| US-MAI011-001 | Registrar unidad nueva en flota | 5 | P0 |
| US-MAI011-002 | Registrar operador con documentos | 8 | P0 |
| US-MAI011-003 | Consultar disponibilidad de recursos | 5 | P0 |
| US-MAI011-004 | Asignar operador a unidad | 3 | P1 |
| US-MAI011-005 | Recibir alerta de documento por vencer | 5 | P0 |
| US-MAI011-006 | Bloquear unidad por mantenimiento vencido | 5 | P1 |
| US-MAI011-007 | Ver historial de asignaciones | 3 | P2 |
| US-MAI011-008 | Registrar cambio de status de unidad | 3 | P1 |
| US-MAI011-009 | Dashboard de flota (disponibilidad) | 5 | P1 |
| US-MAI011-010 | Buscar operador disponible | 3 | P1 |
| US-MAI011-011 | Configurar combinacion vehicular | 5 | P1 |
| US-MAI011-012 | Exportar reporte de flota | 3 | P2 |

**Total Story Points:** 53 | **P0:** 23 SP | **P1:** 24 SP | **P2:** 6 SP

---

## Dependencias

### Depende de
| Modulo | Razon |
|--------|-------|
| MAI-001 (Fundamentos) | Auth, RBAC, multi-tenancy, tenants |
| erp-core (catalogs) | Catalogos base (estados, ciudades) |

### Es dependencia de
| Modulo | Razon |
|--------|-------|
| MAI-003 (Ordenes de Transporte) | Requiere unidades y operadores para asignacion |
| MAI-004 (Planeacion TMS) | Consulta disponibilidad de recursos |
| MAI-005 (Despacho) | Verifica aptitud de unidad/operador |
| MAI-006 (Tracking) | Identifica unidad/operador en viaje |
| MAI-009 (Facturacion) | Referencia tipo de equipo para tarifas |
| MAI-010 (Liquidaciones) | Datos de operador para pago |
| MAI-012 (Combustible) | Datos de unidad para consumo esperado |
| MAI-013 (Mantenimiento) | Unidades y remolques como activos |
| MAI-014 (Carriers) | Comparacion flota propia vs terceros |
| MAE-016 (Carta Porte) | Datos de unidad/operador para complemento fiscal |

---

## Seguridad

- **Multi-tenancy:** Todas las tablas del schema `fleet` tienen `tenant_id` y RLS habilitado con politica `tenant_isolation`
- **RBAC:** Permisos por rol (jefe de flota = CRUD completo, coordinador = solo lectura + asignaciones, operador = solo lectura de sus datos)
- **Auditoria:** Campos `created_at`, `created_by_id`, `updated_at`, `updated_by_id` en todas las tablas
- **Baja logica:** Campo `activo` en todas las entidades, nunca se elimina fisicamente

---

*MAI-011 Gestion de Flota - ERP Transportistas v1.0.0*