ec43d9c6cd
Modules documented: - MAI-003 (OT): README, REQUERIMIENTOS, RESUMEN-EPICA, 10 US - MAI-006 (Tracking): README, REQUERIMIENTOS, RESUMEN-EPICA - MAI-008 (Incidencias): 3 US (18 SP) - MAI-011 (Flota): README, REQUERIMIENTOS, RESUMEN-EPICA - MAI-012 (Combustible): 3 US (18 SP) - MAI-013 (Mantenimiento): 3 US (18 SP) - MAI-014 (Carriers): 3 US (18 SP) - MAI-015 (Portal): 3 US (18 SP) - MAE-016 (Carta Porte): 10 US - MAE-017 (HOS): 3 US (16 SP) - MAE-018 (Reportes): 3 US (18 SP) Phase 2+3 complete: 13 modules, 50+ User Stories Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
13 KiB
REQUERIMIENTOS.md - MAI-011 Gestion de Flota
Modulo: MAI-011 | Version: 1.0.0 | Actualizado: 2026-01-27
Requerimientos Funcionales
RF-MAI011-001: Registro de Unidades Motrices
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe permitir registrar unidades motrices (tractocamiones, tortones, rabones, camionetas) con los siguientes datos obligatorios: numero economico (unico por tenant), tipo de unidad, marca, modelo, anio. Datos opcionales: color, numero de serie, numero de motor, placa con estado de expedicion, permiso SCT con tipo, configuracion vehicular (C2, C3, T3S2, T3S3, T3S2R4), capacidades (peso kg, volumen m3, pallets), datos de combustible (tipo, rendimiento km/l, capacidad tanque), odometro actual, GPS (proveedor, IMEI), propiedad (propia o de tercero con referencia a carrier), costos (adquisicion, valor actual), fechas de vencimiento (verificacion, poliza, permiso SCT).
Tabla DDL: fleet.unidades
Constraint: uq_unidad_numero (tenant_id, numero_economico), uq_unidad_placa (tenant_id, placa)
RF-MAI011-002: Registro de Remolques
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe permitir registrar remolques y cajas con los siguientes datos: numero economico (unico por tenant), tipo (CAJA_SECA, CAJA_REFRIGERADA, PLATAFORMA, TANQUE, PORTACONTENEDOR, REMOLQUE), marca, modelo, anio, numero de serie, placa, dimensiones (largo, ancho, alto en metros), capacidades (peso kg, volumen m3, pallets). Para remolques refrigerados: marca y modelo de refrigeracion, rango de temperatura (min, max). Estado, propiedad, fechas de verificacion y poliza.
Tabla DDL: fleet.remolques
Constraint: uq_remolque_numero (tenant_id, numero_economico)
RF-MAI011-003: Registro de Operadores
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe permitir registrar operadores/conductores con datos completos: numero de empleado (unico por tenant), nombre completo (nombre, apellido paterno, apellido materno con campo generado), documentos de identidad (CURP unico por tenant, RFC, NSS), contacto (telefono, telefono emergencia, email), direccion completa con codigo postal, datos de nacimiento (fecha, lugar, nacionalidad), licencia de conducir (tipo A-F, numero, vigencia, estado de expedicion), certificaciones (certificado fisico medico con vigencia, antidoping con vigencia, materiales peligrosos con vigencia), datos bancarios (banco, cuenta, CLABE), esquema de pago (fijo, por viaje, mixto), salario base, fecha de ingreso.
Tabla DDL: fleet.operadores
Constraint: uq_operador_numero (tenant_id, numero_empleado), uq_operador_curp (tenant_id, curp)
RF-MAI011-004: Gestion de Documentos con Vigencia
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe permitir registrar documentos asociados a cualquier entidad de flota (unidad, remolque u operador) mediante referencia polimorfica (entidad_tipo + entidad_id). Cada documento incluye: tipo (LICENCIA, INE, CURP, RFC, NSS, TARJETA_CIRCULACION, POLIZA_SEGURO, VERIFICACION, PERMISO_SCT, CERTIFICADO_FISICO, ANTIDOPING, OTRO), nombre, numero de documento, descripcion, fecha de emision, fecha de vencimiento, dias de alerta de vencimiento (default 30), archivo adjunto (URL, nombre, tipo MIME, tamano en bytes), estado de verificacion (verificado por supervisor con fecha).
Tabla DDL: fleet.documentos_flota
RF-MAI011-005: Control de Estados de Unidad
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe gestionar el estado de cada unidad motriz y remolque con los valores: DISPONIBLE (lista para operar), EN_VIAJE (actualmente en ruta), EN_TALLER (en mantenimiento preventivo o correctivo), BLOQUEADA (documentacion vencida o restriccion operativa), BAJA (fuera de operacion permanente). Los cambios de estado deben registrar usuario y timestamp. El cambio a EN_VIAJE solo puede realizarse desde DISPONIBLE. El cambio a BLOQUEADA puede ser automatico por documentos vencidos.
ENUM DDL: fleet.estado_unidad
RF-MAI011-006: Control de Estados de Operador
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe gestionar el estado de cada operador con los valores: ACTIVO (disponible para asignacion), EN_VIAJE (actualmente en ruta), DESCANSO (en periodo de descanso obligatorio o personal), VACACIONES, INCAPACIDAD, SUSPENDIDO (bloqueado por documentos vencidos o sancion), BAJA (fuera de la empresa). El cambio a EN_VIAJE solo puede realizarse desde ACTIVO. El cambio a SUSPENDIDO puede ser automatico por licencia federal o antidoping vencido.
ENUM DDL: fleet.estado_operador
RF-MAI011-007: Asignaciones Operador-Unidad-Remolque
Prioridad: P1 | Origen: REQ-GIRO-TRANSPORTISTA 4.3, RF-4.3.4
El sistema debe permitir crear asignaciones que vinculan un operador con una unidad motriz y opcionalmente un remolque. Cada asignacion tiene fecha de inicio obligatoria y fecha de fin opcional. Solo puede existir una asignacion activa por operador y por unidad en un momento dado. Al crear una nueva asignacion, la anterior se finaliza automaticamente. El sistema debe validar que el operador no este en estado SUSPENDIDO o BAJA, y que la unidad no este en estado BLOQUEADA o BAJA.
Tabla DDL: fleet.asignaciones
RF-MAI011-008: Alertas de Vencimiento de Documentos
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5
El sistema debe generar alertas automaticas cuando un documento esta proximo a vencer, segun los dias configurados en dias_alerta_vencimiento (default 30 dias). Las alertas deben notificar al jefe de flota y al operador (si el documento es de un operador). El sistema debe proporcionar un endpoint que liste todos los documentos por vencer en los proximos N dias, agrupados por entidad. Las alertas se deben poder enviar por notificacion interna del sistema y opcionalmente por email.
RF-MAI011-009: Bloqueo Automatico por Documentos Vencidos
Prioridad: P1 | Origen: REQ-GIRO-TRANSPORTISTA 4.11, RF-4.11.5, RF-5.3.3
El sistema debe ejecutar un proceso (cron diario o trigger) que detecte documentos con fecha_vencimiento menor a la fecha actual y ejecute las siguientes acciones: (a) Para unidades: si la POLIZA_SEGURO, VERIFICACION o PERMISO_SCT esta vencido, cambiar estado de la unidad a BLOQUEADA. (b) Para operadores: si la LICENCIA, CERTIFICADO_FISICO o ANTIDOPING esta vencido, cambiar estado del operador a SUSPENDIDO. (c) Registrar el cambio de estado con motivo "Documento vencido: {tipo_documento}". (d) Notificar al jefe de flota.
RF-MAI011-010: Consulta de Disponibilidad de Recursos
Prioridad: P0 | Origen: REQ-GIRO-TRANSPORTISTA 4.3, RF-4.3.4, RF-4.3.5
El sistema debe permitir consultar en tiempo real los recursos disponibles para asignacion. Para unidades: filtrar por tipo (tractora, torton, rabon), estado DISPONIBLE, capacidades requeridas (peso, volumen, pallets), tipo de combustible, GPS activo, configuracion vehicular. Para operadores: filtrar por estado ACTIVO, tipo de licencia, certificaciones vigentes (materiales peligrosos), calificacion minima. Para remolques: filtrar por tipo (caja seca, refrigerada, plataforma), estado DISPONIBLE, capacidades, refrigeracion.
RF-MAI011-011: Historial de Asignaciones
Prioridad: P2 | Origen: REQ-GIRO-TRANSPORTISTA 4.11
El sistema debe mantener un historial completo de todas las asignaciones operador-unidad-remolque, incluyendo fecha de inicio, fecha de fin y motivo. Se debe poder consultar el historial por unidad (que operadores la han manejado) y por operador (que unidades ha operado). El historial no se elimina, las asignaciones finalizadas permanecen con activa = FALSE y fecha_fin registrada.
RF-MAI011-012: Dashboard de Disponibilidad de Flota
Prioridad: P1 | Origen: REQ-GIRO-TRANSPORTISTA 6.6
El sistema debe proporcionar un dashboard que muestre: (a) Conteo de unidades por estado (disponible, en viaje, en taller, bloqueada, baja) con grafica. (b) Conteo de remolques por estado y tipo. (c) Conteo de operadores por estado (activo, en viaje, descanso, vacaciones, incapacidad, suspendido, baja). (d) Porcentaje de disponibilidad de flota. (e) Lista de documentos que vencen en los proximos 7, 15 y 30 dias. (f) Unidades y operadores bloqueados/suspendidos por documentacion.
RF-MAI011-013: Busqueda de Operador Disponible
Prioridad: P1 | Origen: REQ-GIRO-TRANSPORTISTA 4.3, RF-4.3.5
El sistema debe permitir buscar operadores disponibles para asignar a un viaje con los siguientes criterios: estado ACTIVO, licencia federal vigente (tipo F), certificado fisico vigente, antidoping vigente, sin unidad asignada activa (o con disponibilidad), calificacion minima requerida, certificacion de materiales peligrosos (si el viaje lo requiere). El resultado debe ordenarse por calificacion descendente y mostrar las vigencias de documentos.
RF-MAI011-014: Configuracion de Combinacion Vehicular
Prioridad: P1 | Origen: REQ-GIRO-TRANSPORTISTA 4.3, RF-4.3.3
El sistema debe permitir configurar combinaciones vehiculares (tractora + remolque) para un viaje, validando compatibilidad. Las configuraciones vehiculares SCT incluyen: C2 (camion 2 ejes), C3 (camion 3 ejes), T3S2 (tractocamion 3 ejes + semirremolque 2 ejes), T3S3 (tractocamion 3 ejes + semirremolque 3 ejes), T3S2R4 (tractocamion + semirremolque + remolque). El sistema debe validar que la combinacion de unidad + remolque corresponda a la configuracion vehicular declarada y que ambos tengan documentacion vigente.
RF-MAI011-015: Exportacion de Reporte de Flota
Prioridad: P2 | Origen: REQ-GIRO-TRANSPORTISTA 6
El sistema debe permitir exportar un reporte completo de la flota en formato Excel y PDF con los siguientes contenidos: (a) Listado de unidades motrices con estado, documentos vigentes/vencidos, ultimo odometro. (b) Listado de remolques con estado y documentos. (c) Listado de operadores con estado, licencia, certificaciones. (d) Resumen de disponibilidad por tipo. (e) Documentos proximos a vencer. Los filtros deben permitir seleccionar por tipo de unidad, estado, rango de fechas y propiedad (propia/tercero).
RF-MAI011-016: Ubicacion y GPS de Unidades
Prioridad: P1 | Origen: REQ-GIRO-TRANSPORTISTA 4.5, RF-4.5.1
El sistema debe registrar la ubicacion actual de cada unidad motriz con coordenadas (latitud, longitud) y timestamp de ultima actualizacion. La informacion de GPS incluye: si tiene GPS instalado, proveedor de GPS e IMEI del dispositivo. La actualizacion de ubicacion se recibe del modulo de tracking (MAI-006) y se almacena en los campos ubicacion_actual_lat, ubicacion_actual_lng y ultima_actualizacion_ubicacion de la tabla fleet.unidades.
RF-MAI011-017: Multi-tenancy y Aislamiento de Datos
Prioridad: P0 | Origen: Arquitectura Base
Todas las tablas del schema fleet deben tener habilitado Row Level Security (RLS) con politica de aislamiento por tenant_id. Cada consulta debe filtrar automaticamente por el tenant del usuario autenticado, usando current_setting('app.tenant_id')::uuid. Las politicas RLS aplican a: fleet.unidades, fleet.remolques, fleet.operadores, fleet.documentos_flota, fleet.asignaciones.
RF-MAI011-018: Metricas de Desempeno de Operadores
Prioridad: P2 | Origen: REQ-GIRO-TRANSPORTISTA 4.11
El sistema debe mantener metricas de desempeno por operador: calificacion promedio (escala 1-5, default 5.00), total de viajes completados, total de kilometros recorridos, numero de incidentes registrados. Estas metricas se actualizan al cerrar cada viaje desde el modulo MAI-007 (POD y Cierre). Las metricas son visibles en el perfil del operador y se usan como criterio de busqueda/filtrado.
Requerimientos No Funcionales
RNF-MAI011-001: Rendimiento de Consulta de Disponibilidad
La consulta de recursos disponibles debe responder en menos de 2 segundos para flotas de hasta 500 unidades y 300 operadores. Los indices idx_unidad_estado y idx_operador_estado en combinacion con idx_unidad_activo y idx_operador_activo garantizan rendimiento optimo.
RNF-MAI011-002: Auditoria Completa
Toda operacion de creacion y modificacion debe registrar created_at, created_by_id, updated_at y updated_by_id. Los cambios de estado criticos (bloqueo, baja) deben registrar motivo y usuario responsable.
RNF-MAI011-003: Baja Logica
Ninguna entidad de flota se elimina fisicamente. La baja logica se realiza con el campo activo = FALSE y opcionalmente fecha_baja y motivo_baja. Los indices parciales con WHERE activo = TRUE optimizan las consultas habituales.
RNF-MAI011-004: Almacenamiento de Documentos
Los archivos de documentos se almacenan en storage externo (S3/MinIO) y solo se registra la URL en la base de datos. El tamano maximo por archivo es configurable por tenant. Los tipos MIME aceptados incluyen: PDF, JPG, PNG, TIFF.
MAI-011 Requerimientos - ERP Transportistas v1.0.0