rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-transportistas-v2/docs/02-definicion-modulos/MAI-011-gestion-flota/REQUERIMIENTOS.md
Adrian Flores Cortes ec43d9c6cd docs: Add Phase 3 secondary modules specifications (P1/P2/P3) 
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>
2026-01-27 02:24:35 -06:00

169 lines
13 KiB
Markdown
Raw Permalink Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink