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>
This commit is contained in:
Adrian Flores Cortes
parent
569eaeb5a4
commit
ec43d9c6cd
191
docs/02-definicion-modulos/MAE-016-carta-porte/README.md
Normal file
191
docs/02-definicion-modulos/MAE-016-carta-porte/README.md
Normal file
@ -0,0 +1,191 @@
|
||||
# MAE-016: Carta Porte CFDI
|
||||
|
||||
**Modulo:** MAE-016 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
**Epica:** EPIC-MAE-016 - Carta Porte CFDI
|
||||
**Schema BD:** compliance
|
||||
**DDL:** `database/ddl/08-compliance-schema-ddl.sql`
|
||||
|
||||
---
|
||||
|
||||
## Descripcion
|
||||
|
||||
Modulo de generacion, timbrado y administracion del **Complemento Carta Porte version 3.1** para CFDI, conforme a los lineamientos del Servicio de Administracion Tributaria (SAT). Este complemento es obligatorio para el traslado de bienes y mercancias en territorio nacional por via de autotransporte federal.
|
||||
|
||||
El modulo automatiza la construccion del XML del complemento a partir de los datos operativos del viaje (origen, destino, mercancias, operador, unidad, remolques), ejecuta las validaciones de campos obligatorios conforme a los catalogos del SAT, se integra con un Proveedor Autorizado de Certificacion (PAC) para el timbrado digital y ofrece funcionalidades de descarga PDF, cancelacion con motivo y expediente fiscal por viaje.
|
||||
|
||||
---
|
||||
|
||||
## Contexto Legal y Normativo
|
||||
|
||||
- **Base legal:** Regla 2.7.7.1 de la Resolucion Miscelanea Fiscal vigente; articulo 29-A del Codigo Fiscal de la Federacion.
|
||||
- **Version complemento:** Carta Porte 3.1, vigente desde el **17 de julio de 2024**.
|
||||
- **Obligatoriedad:** Toda persona fisica o moral que transporte bienes o mercancias en territorio nacional por via terrestre, maritima, aerea o ferroviaria debe emitir CFDI con complemento Carta Porte.
|
||||
- **Sanciones:** La falta de este documento durante el traslado implica multas y posible decomiso de mercancias por parte de la autoridad fiscal.
|
||||
- **Catalogos SAT:** Se utilizan catalogos oficiales de claves de producto/servicio, unidades de medida, tipos de permiso SCT, configuracion vehicular, claves de material peligroso y tipos de figura de transporte.
|
||||
- **Motivos de cancelacion:** 01 (Comprobante emitido con errores con relacion), 02 (Comprobante emitido con errores sin relacion), 03 (No se llevo a cabo la operacion), 04 (Operacion nominativa relacionada en factura global).
|
||||
|
||||
---
|
||||
|
||||
## Tipos de CFDI con Carta Porte
|
||||
|
||||
| Tipo | Enum DDL | Descripcion | Escenario |
|
||||
|------|----------|-------------|-----------|
|
||||
| **CFDI de Ingreso** | `INGRESO` | Factura por servicio de transporte prestado a un tercero | Empresa transportista que cobra por el traslado de mercancias del cliente |
|
||||
| **CFDI de Traslado** | `TRASLADO` | Comprobante de traslado de mercancias propias | Empresa que mueve sus propias mercancias sin cobrar servicio de flete |
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Responsabilidad |
|
||||
|-------|-----------------|
|
||||
| **Facturador** | Genera la carta porte desde el viaje, valida datos, solicita timbrado al PAC, descarga PDF/XML |
|
||||
| **Contador** | Revisa expediente fiscal, gestiona cancelaciones, genera reportes fiscales mensuales |
|
||||
| **Coordinador de Operaciones** | Asegura que los datos del viaje (mercancias, ubicaciones, figuras) esten completos antes del despacho |
|
||||
| **Operador/Conductor** | Porta el PDF/XML en la unidad durante el traslado; consulta en modo offline desde la app movil |
|
||||
|
||||
---
|
||||
|
||||
## Funcionalidades Principales
|
||||
|
||||
1. **Generacion automatica desde viaje:** El sistema construye el complemento Carta Porte 3.1 a partir de los datos del viaje (ubicaciones, mercancias, operador, unidad, remolques) sin captura manual redundante.
|
||||
2. **Validacion de campos SAT:** Antes de enviar al PAC, el sistema valida todos los campos obligatorios segun el tipo de CFDI (Ingreso/Traslado), incluyendo catalogos SAT (BienesTransp, ClaveUnidad, ConfigVehicular, TipoPermiso, TipoFigura).
|
||||
3. **Timbrado con PAC:** Integracion con proveedores autorizados de certificacion (Finkok, Facturapi, SW Sapien) para timbrar el CFDI y obtener UUID fiscal, cadena de certificacion y sello digital.
|
||||
4. **Generacion de PDF:** Representacion impresa del CFDI con complemento Carta Porte, incluyendo datos fiscales, mercancias, ubicaciones, figuras de transporte y codigo QR de verificacion.
|
||||
5. **Cancelacion de CFDI:** Envio de solicitud de cancelacion al SAT a traves del PAC con motivo (01, 02, 03, 04), UUID de sustitucion cuando aplica y bitacora de cancelaciones.
|
||||
6. **Expediente fiscal por viaje:** Asociacion del UUID del CFDI timbrado, XML, PDF y QR con el viaje/OT, permitiendo consulta rapida y auditoria.
|
||||
7. **Disponibilidad offline:** El operador puede descargar y consultar el PDF, XML y QR desde la app movil en modo offline, cumpliendo con la obligacion de portarlo durante el traslado.
|
||||
8. **Reporte fiscal mensual:** Generacion de reporte con todos los CFDI emitidos, cancelados y vigentes en un periodo, agrupados por tipo, serie, estado y totales.
|
||||
|
||||
---
|
||||
|
||||
## Entidades (desde DDL - schema compliance)
|
||||
|
||||
| Tabla | Descripcion | Campos clave |
|
||||
|-------|-------------|--------------|
|
||||
| `compliance.cartas_porte` | CFDI con complemento Carta Porte 3.1 | id, viaje_id, tipo_cfdi, uuid_cfdi, emisor_rfc, receptor_rfc, estado, xml_cfdi, pdf_url |
|
||||
| `compliance.ubicaciones_carta_porte` | Nodos Ubicacion (origen/destino) de la carta porte | id, carta_porte_id, tipo_ubicacion, codigo_postal, fecha_hora_salida_llegada, distancia_recorrida |
|
||||
| `compliance.mercancias_carta_porte` | Nodo Mercancias transportadas en el complemento | id, carta_porte_id, bienes_transp, descripcion, cantidad, peso_en_kg, material_peligroso |
|
||||
| `compliance.figuras_transporte` | Nodo FiguraTransporte (operador, propietario, arrendador) | id, carta_porte_id, tipo_figura, rfc_figura, num_licencia |
|
||||
| `compliance.autotransporte_carta_porte` | Nodo Autotransporte federal (vehiculo, permisos, remolques) | id, carta_porte_id, perm_sct, num_permiso_sct, config_vehicular, placa_vm, remolques |
|
||||
|
||||
### ENUMs
|
||||
|
||||
| Enum | Valores | Uso |
|
||||
|------|---------|-----|
|
||||
| `compliance.estado_carta_porte` | BORRADOR, VALIDADA, TIMBRADA, CANCELADA | Ciclo de vida del CFDI |
|
||||
| `compliance.tipo_cfdi_carta_porte` | INGRESO, TRASLADO | Tipo de comprobante fiscal |
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints (propuestos)
|
||||
|
||||
| Metodo | Ruta | Descripcion |
|
||||
|--------|------|-------------|
|
||||
| POST | `/api/v1/carta-porte` | Crear carta porte desde viaje |
|
||||
| GET | `/api/v1/carta-porte/:id` | Obtener detalle de carta porte |
|
||||
| GET | `/api/v1/carta-porte` | Listar cartas porte (filtros: estado, fecha, tipo_cfdi) |
|
||||
| POST | `/api/v1/carta-porte/:id/validar` | Validar campos obligatorios SAT |
|
||||
| POST | `/api/v1/carta-porte/:id/timbrar` | Timbrar CFDI con PAC |
|
||||
| GET | `/api/v1/carta-porte/:id/pdf` | Descargar PDF de la carta porte |
|
||||
| GET | `/api/v1/carta-porte/:id/xml` | Descargar XML del CFDI |
|
||||
| POST | `/api/v1/carta-porte/:id/cancelar` | Cancelar CFDI con motivo |
|
||||
| GET | `/api/v1/carta-porte/expediente/:viajeId` | Consultar expediente fiscal del viaje |
|
||||
| POST | `/api/v1/carta-porte/:id/mercancias` | Agregar mercancias a la carta porte |
|
||||
| PUT | `/api/v1/carta-porte/:id/mercancias/:mercanciaId` | Actualizar mercancia |
|
||||
| POST | `/api/v1/carta-porte/:id/figuras` | Registrar figuras de transporte |
|
||||
| POST | `/api/v1/carta-porte/:id/autotransporte` | Configurar datos de autotransporte federal |
|
||||
| GET | `/api/v1/carta-porte/reporte-fiscal` | Generar reporte fiscal mensual |
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Estado |
|
||||
|----|--------|----|-----------|--------|
|
||||
| US-MAE016-001 | Generar carta porte desde viaje | 8 | P0 | Backlog |
|
||||
| US-MAE016-002 | Validar datos obligatorios SAT | 5 | P0 | Backlog |
|
||||
| US-MAE016-003 | Timbrar CFDI con PAC | 8 | P0 | Backlog |
|
||||
| US-MAE016-004 | Descargar PDF de carta porte | 3 | P1 | Backlog |
|
||||
| US-MAE016-005 | Cancelar CFDI con motivo | 5 | P1 | Backlog |
|
||||
| US-MAE016-006 | Consultar expediente fiscal | 3 | P1 | Backlog |
|
||||
| US-MAE016-007 | Agregar mercancias transportadas | 5 | P0 | Backlog |
|
||||
| US-MAE016-008 | Registrar figuras de transporte | 5 | P1 | Backlog |
|
||||
| US-MAE016-009 | Configurar datos autotransporte federal | 5 | P1 | Backlog |
|
||||
| US-MAE016-010 | Generar reporte fiscal mensual | 3 | P2 | Backlog |
|
||||
|
||||
**Total Story Points:** 50
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Depende de
|
||||
|
||||
| Modulo | Razon |
|
||||
|--------|-------|
|
||||
| MAI-001 Fundamentos | Auth, RBAC, multi-tenancy, tenant_id para RLS |
|
||||
| MAI-003 Ordenes de Transporte | Datos de OT/embarque como origen de la carta porte |
|
||||
| MAI-005 Despacho | Viaje despachado como prerequisito para generar carta porte |
|
||||
| MAI-009 Facturacion Transporte | CFDI de Ingreso se vincula con factura de transporte |
|
||||
| MAI-011 Gestion de Flota | Datos de unidad, remolques, operadores (placas, licencias, permisos SCT) |
|
||||
|
||||
### Bloquea a
|
||||
|
||||
| Modulo | Razon |
|
||||
|--------|-------|
|
||||
| MAI-007 POD y Cierre | El cierre operativo requiere la carta porte timbrada |
|
||||
| MAI-015 Portal Cliente | El portal muestra carta porte al cliente para descarga |
|
||||
| MAE-018 Reportes y KPIs | Los reportes fiscales consolidan datos de cartas porte |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
1. GENERAR CARTA PORTE
|
||||
Coordinador/Facturador selecciona viaje despachado
|
||||
Sistema extrae datos: emisor, receptor, ubicaciones, mercancias, operador, unidad
|
||||
Crea registro en compliance.cartas_porte con estado BORRADOR
|
||||
|
||||
2. AGREGAR/VERIFICAR MERCANCIAS
|
||||
Sistema carga mercancias del viaje/OT
|
||||
Facturador ajusta claves SAT (bienes_transp, clave_unidad)
|
||||
Registra peso_en_kg, material_peligroso si aplica
|
||||
|
||||
3. REGISTRAR FIGURAS DE TRANSPORTE
|
||||
Sistema carga operador asignado como tipo_figura '01' (Operador)
|
||||
Se agregan propietario ('02') o arrendador ('03') si aplica
|
||||
Valida num_licencia del operador
|
||||
|
||||
4. CONFIGURAR AUTOTRANSPORTE
|
||||
Sistema carga datos de unidad: perm_sct, config_vehicular, placa_vm
|
||||
Agrega remolques con sub_tipo_rem y placa
|
||||
Valida catalogo de configuracion vehicular SAT
|
||||
|
||||
5. VALIDAR DATOS SAT
|
||||
Sistema ejecuta validaciones de campos obligatorios
|
||||
Verifica catalogos SAT (BienesTransp, ClaveUnidad, ConfigVehicular)
|
||||
Si pasa: estado = VALIDADA. Si falla: muestra errores especificos
|
||||
|
||||
6. TIMBRAR CON PAC
|
||||
Sistema genera XML del CFDI con complemento Carta Porte 3.1
|
||||
Envia a PAC (Finkok/Facturapi/SW)
|
||||
Recibe uuid_cfdi, fecha_timbrado, sello, cadena
|
||||
Estado = TIMBRADA. Almacena xml_cfdi
|
||||
|
||||
7. GENERAR PDF Y QR
|
||||
Sistema genera representacion impresa con datos fiscales
|
||||
Incluye codigo QR de verificacion SAT
|
||||
Almacena pdf_url y qr_url
|
||||
|
||||
8. CANCELAR (si requiere)
|
||||
Facturador/Contador selecciona motivo (01, 02, 03, 04)
|
||||
Si motivo 01: indica uuid_sustitucion
|
||||
Envia solicitud al PAC
|
||||
Estado = CANCELADA. Registra fecha_cancelacion y motivo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAE-016 Carta Porte CFDI - ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0*
|
||||
208
docs/02-definicion-modulos/MAE-016-carta-porte/REQUERIMIENTOS.md
Normal file
208
docs/02-definicion-modulos/MAE-016-carta-porte/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,208 @@
|
||||
# REQUERIMIENTOS.md - MAE-016 Carta Porte CFDI
|
||||
|
||||
**Modulo:** MAE-016 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
**Epica:** EPIC-MAE-016 - Carta Porte CFDI
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-MAE016-001: Generar carta porte desde viaje
|
||||
|
||||
**Prioridad:** P0 | **Historia:** US-MAE016-001
|
||||
|
||||
El sistema debe permitir generar un registro de carta porte a partir de un viaje despachado. Al seleccionar el viaje, el sistema extrae automaticamente los datos del emisor (RFC, nombre, regimen fiscal del tenant), receptor (RFC, nombre, uso CFDI, domicilio fiscal CP del cliente), ubicaciones (origen/destino desde la ruta del viaje), mercancias (desde las OTs asociadas), operador (como figura de transporte tipo '01') y datos de la unidad (permiso SCT, configuracion vehicular, placa, remolques). El tipo de CFDI (Ingreso o Traslado) se selecciona segun corresponda al escenario operativo. La carta porte se crea con estado BORRADOR en la tabla `compliance.cartas_porte` y version_carta_porte '3.1'.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-002: Seleccionar tipo de CFDI
|
||||
|
||||
**Prioridad:** P0 | **Historia:** US-MAE016-001
|
||||
|
||||
El sistema debe permitir seleccionar el tipo de CFDI entre Ingreso (servicio de transporte a tercero) y Traslado (mercancias propias). La seleccion impacta los campos requeridos: para Ingreso se requieren datos fiscales del receptor/cliente, subtotal y total; para Traslado el receptor es el mismo contribuyente y no hay cobro. El enum `compliance.tipo_cfdi_carta_porte` controla los valores permitidos.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-003: Registrar ubicaciones origen y destino
|
||||
|
||||
**Prioridad:** P0 | **Historia:** US-MAE016-001
|
||||
|
||||
El sistema debe registrar las ubicaciones de origen y destino en la tabla `compliance.ubicaciones_carta_porte` con los campos obligatorios: tipo_ubicacion ('Origen' o 'Destino'), codigo_postal (5 digitos, catalogo SAT), rfc_remitente_destinatario, fecha_hora_salida_llegada y secuencia. Para destinos se incluye distancia_recorrida en km. Los campos opcionales incluyen estado, municipio, localidad, colonia, calle, numero_exterior, numero_interior y referencia, todos usando claves del catalogo SAT cuando aplica. Se soportan rutas multi-parada con secuencia numerica ordenada.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-004: Registrar mercancias transportadas
|
||||
|
||||
**Prioridad:** P0 | **Historia:** US-MAE016-007
|
||||
|
||||
El sistema debe permitir agregar mercancias a la carta porte en la tabla `compliance.mercancias_carta_porte`. Los campos obligatorios son: bienes_transp (clave SAT del catalogo de productos y servicios), descripcion, cantidad, clave_unidad (catalogo SAT), peso_en_kg y secuencia. Los campos opcionales incluyen unidad (descripcion libre), dimensiones (largo_cm, ancho_cm, alto_cm), valor_mercancia, moneda y datos de material peligroso (material_peligroso, cve_material_peligroso, tipo_embalaje, descripcion_embalaje). Para comercio exterior se soporta fraccion_arancelaria, uuid_comercio_ext y pedimentos. Para paqueteria se soporta el campo guias.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-005: Registrar figuras de transporte
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-008
|
||||
|
||||
El sistema debe permitir registrar las figuras de transporte en la tabla `compliance.figuras_transporte`. El tipo_figura acepta los valores: '01' (Operador), '02' (Propietario) y '03' (Arrendador). Para el operador (tipo '01') es obligatorio el campo num_licencia; para propietario y arrendador se requiere rfc_figura y opcionalmente partes_transporte (JSONB con array de partes). El sistema debe cargar automaticamente el operador asignado al viaje como figura tipo '01' con su RFC, nombre y numero de licencia.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-006: Configurar datos de autotransporte federal
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-009
|
||||
|
||||
El sistema debe registrar los datos del autotransporte federal en la tabla `compliance.autotransporte_carta_porte`. Los campos obligatorios son: perm_sct (tipo de permiso SCT del catalogo SAT), num_permiso_sct, config_vehicular (C2, C3, T3S2, etc. del catalogo SAT) y placa_vm. Opcionalmente se registra anio_modelo_vm. El campo remolques (JSONB) almacena un array de hasta 2 remolques con sub_tipo_rem (catalogo SAT) y placa. Los datos se cargan automaticamente desde la unidad y remolques asignados al viaje.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-007: Registrar datos de seguros
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-009
|
||||
|
||||
El sistema debe permitir registrar los datos de seguros en la tabla `compliance.cartas_porte`: asegura_resp_civil y poliza_resp_civil (obligatorios para autotransporte), asegura_med_ambiente y poliza_med_ambiente (obligatorios para materiales peligrosos), asegura_carga y poliza_carga (opcional), prima_seguro. Los datos se pueden precargar desde la informacion de la unidad en el modulo de gestion de flota (MAI-011).
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-008: Validar campos obligatorios SAT
|
||||
|
||||
**Prioridad:** P0 | **Historia:** US-MAE016-002
|
||||
|
||||
El sistema debe ejecutar una validacion exhaustiva de los campos obligatorios antes de permitir el timbrado. Las validaciones incluyen: (a) datos del emisor completos (RFC, nombre, regimen fiscal); (b) datos del receptor completos (RFC, nombre, uso CFDI para Ingreso, domicilio fiscal CP); (c) al menos una ubicacion de origen y una de destino con codigo_postal valido; (d) al menos una mercancia con bienes_transp, descripcion, cantidad, clave_unidad y peso_en_kg; (e) peso_bruto_total y num_total_mercancias calculados correctamente; (f) al menos un operador como figura de transporte con num_licencia; (g) datos de autotransporte con perm_sct, num_permiso_sct, config_vehicular y placa_vm; (h) seguro de responsabilidad civil. Si la validacion es exitosa, el estado cambia a VALIDADA. Si falla, se retorna la lista detallada de errores con campo y descripcion.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-009: Timbrar CFDI con PAC
|
||||
|
||||
**Prioridad:** P0 | **Historia:** US-MAE016-003
|
||||
|
||||
El sistema debe generar el XML del CFDI con el complemento Carta Porte 3.1 conforme al esquema XSD del SAT y enviarlo a un PAC para timbrado. La integracion debe soportar al menos dos PAC (Finkok y Facturapi) con failover automatico. Al recibir la respuesta exitosa del PAC, el sistema almacena: uuid_cfdi, fecha_timbrado, xml_cfdi (XML completo con sello y cadena), serie y folio. El estado cambia a TIMBRADA. Si el PAC rechaza el timbrado, se retorna el codigo de error y descripcion del SAT/PAC sin modificar el estado. Se requiere el CSD (Certificado de Sello Digital) del contribuyente previamente configurado.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-010: Generar PDF de carta porte
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-004
|
||||
|
||||
El sistema debe generar la representacion impresa (PDF) del CFDI con complemento Carta Porte incluyendo: datos fiscales del emisor y receptor, serie y folio, UUID, fecha de timbrado, detalle de mercancias (descripcion, cantidad, peso, clave SAT), ubicaciones (origen, destino, distancias), figuras de transporte, datos del autotransporte (permiso, vehiculo, remolques), seguros, totales y codigo QR de verificacion SAT. El PDF se almacena en almacenamiento de archivos y su URL se registra en el campo pdf_url. El formato debe cumplir con las especificaciones del anexo 20 del SAT.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-011: Descargar XML del CFDI
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-004
|
||||
|
||||
El sistema debe permitir descargar el XML del CFDI timbrado almacenado en el campo xml_cfdi de la tabla `compliance.cartas_porte`. El XML incluye el nodo del complemento CartaPorte31 con todos los subnodos (Ubicaciones, Mercancias, FiguraTransporte, Autotransporte) y el TimbreFiscalDigital del PAC.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-012: Cancelar CFDI con motivo
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-005
|
||||
|
||||
El sistema debe permitir cancelar un CFDI timbrado enviando la solicitud al PAC con el motivo de cancelacion conforme al catalogo del SAT: 01 (comprobante emitido con errores con relacion - requiere uuid_sustitucion), 02 (comprobante emitido con errores sin relacion), 03 (no se llevo a cabo la operacion), 04 (operacion nominativa relacionada en factura global). Al confirmar la cancelacion, el sistema actualiza: estado = CANCELADA, fecha_cancelacion, motivo_cancelacion y uuid_sustitucion (cuando aplica). La cancelacion se registra en bitacora de auditoria con el usuario y fecha.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-013: Consultar expediente fiscal por viaje
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-006
|
||||
|
||||
El sistema debe permitir consultar el expediente fiscal de un viaje a traves del endpoint `/api/v1/carta-porte/expediente/:viajeId`. El expediente muestra todas las cartas porte asociadas al viaje con: UUID del CFDI, tipo (Ingreso/Traslado), estado (BORRADOR/VALIDADA/TIMBRADA/CANCELADA), fecha de timbrado, serie y folio, totales, enlaces para descargar XML y PDF, y datos de cancelacion si aplica. Si el viaje tiene un CFDI cancelado con motivo 01, se muestra la relacion con el CFDI de sustitucion.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-014: Disponibilidad offline
|
||||
|
||||
**Prioridad:** P1 | **Historia:** US-MAE016-004
|
||||
|
||||
El sistema debe permitir que el operador descargue el PDF, XML y QR de la carta porte timbrada desde la app movil para consulta en modo offline. Los archivos se almacenan localmente en el dispositivo y estan disponibles sin conexion a internet. Esta funcionalidad cumple con la obligacion de portar el documento durante el traslado de mercancias para inspeccion en carretera por parte de la autoridad fiscal.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-015: Generar reporte fiscal mensual
|
||||
|
||||
**Prioridad:** P2 | **Historia:** US-MAE016-010
|
||||
|
||||
El sistema debe generar un reporte de todos los CFDI con complemento Carta Porte emitidos en un periodo (mes/rango de fechas). El reporte incluye: UUID, serie, folio, tipo CFDI, RFC receptor, fecha de timbrado, total, estado (timbrada/cancelada), motivo de cancelacion si aplica. Se agrupa por tipo de CFDI y estado, con totales. El reporte se puede exportar en formato Excel (XLSX) y PDF. Permite filtros por tipo_cfdi, estado, rango de fechas, RFC receptor y serie.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAE016-016: Transporte internacional
|
||||
|
||||
**Prioridad:** P2 | **Historia:** US-MAE016-001
|
||||
|
||||
El sistema debe soportar los campos de transporte internacional en la tabla `compliance.cartas_porte`: transporte_internacional (boolean), entrada_salida_merc ('Entrada' o 'Salida') y pais_origen_destino (clave pais ISO 3166). Estos campos son obligatorios cuando el transporte cruza fronteras. Las mercancias pueden incluir fraccion_arancelaria y pedimentos para el despacho aduanero.
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-MAE016-001: Tiempo de timbrado
|
||||
|
||||
El proceso de generacion de XML y timbrado con PAC debe completarse en menos de 10 segundos en condiciones normales de operacion.
|
||||
|
||||
### RNF-MAE016-002: Disponibilidad del servicio de timbrado
|
||||
|
||||
El sistema debe soportar failover entre al menos 2 PAC diferentes. Si el PAC primario no responde en 5 segundos, debe intentar con el PAC secundario automaticamente.
|
||||
|
||||
### RNF-MAE016-003: Seguridad del CSD
|
||||
|
||||
El Certificado de Sello Digital (.cer) y la llave privada (.key) deben almacenarse cifrados. La contrasena de la llave no debe almacenarse en texto plano. El acceso al CSD debe estar restringido por permisos RBAC.
|
||||
|
||||
### RNF-MAE016-004: Aislamiento multi-tenant
|
||||
|
||||
Todas las tablas del schema compliance tienen RLS (Row Level Security) activado con politica de aislamiento por tenant_id. Ningun tenant puede acceder a las cartas porte de otro tenant.
|
||||
|
||||
### RNF-MAE016-005: Auditoria
|
||||
|
||||
Toda operacion de creacion, timbrado y cancelacion de carta porte debe registrarse en la bitacora de auditoria con usuario, fecha y accion. Los campos created_at, created_by_id y updated_at de la tabla cartas_porte se mantienen actualizados.
|
||||
|
||||
### RNF-MAE016-006: Almacenamiento de XML
|
||||
|
||||
El XML del CFDI timbrado se almacena integro en el campo xml_cfdi (tipo TEXT) de la tabla cartas_porte. Se debe garantizar que no se modifique despues del timbrado para mantener la integridad fiscal del documento.
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Negocio
|
||||
|
||||
### RN-MAE016-001: Estado de carta porte
|
||||
|
||||
La carta porte sigue el flujo de estados: BORRADOR -> VALIDADA -> TIMBRADA -> CANCELADA. No se permite retroceder de TIMBRADA a VALIDADA. La unica transicion desde TIMBRADA es a CANCELADA. Desde BORRADOR se puede eliminar el registro.
|
||||
|
||||
### RN-MAE016-002: Viaje prerequisito
|
||||
|
||||
Solo se puede generar carta porte desde un viaje que tenga estado DESPACHADO o posterior. No se permite generar carta porte para viajes en estado BORRADOR o PLANEADO.
|
||||
|
||||
### RN-MAE016-003: Peso bruto total
|
||||
|
||||
El campo peso_bruto_total de la tabla cartas_porte debe ser igual a la suma de peso_en_kg de todas las mercancias registradas en mercancias_carta_porte para esa carta porte. El campo num_total_mercancias debe coincidir con el conteo de registros.
|
||||
|
||||
### RN-MAE016-004: Cancelacion con sustitucion
|
||||
|
||||
Cuando el motivo de cancelacion es 01 (comprobante emitido con errores con relacion), es obligatorio indicar el uuid_sustitucion que corresponde al UUID del CFDI que sustituye al cancelado. Para motivos 02, 03 y 04 el uuid_sustitucion debe ser nulo.
|
||||
|
||||
### RN-MAE016-005: Unicidad de timbrado por viaje
|
||||
|
||||
Un viaje puede tener multiples cartas porte (por ejemplo, una cancelada y su sustitucion), pero solo una puede estar en estado TIMBRADA al mismo tiempo para el mismo tipo de CFDI.
|
||||
|
||||
### RN-MAE016-006: Seguro obligatorio
|
||||
|
||||
Para autotransporte federal es obligatorio registrar asegura_resp_civil y poliza_resp_civil. Si alguna mercancia tiene material_peligroso = true, tambien son obligatorios asegura_med_ambiente y poliza_med_ambiente.
|
||||
|
||||
---
|
||||
|
||||
## Trazabilidad con Requerimientos Funcionales del Giro
|
||||
|
||||
| RF Giro (REQ-GIRO-TRANSPORTISTA) | RF Modulo | Descripcion |
|
||||
|----------------------------------|-----------|-------------|
|
||||
| RF-5.1.1 Soportar Carta Porte 3.1 | RF-MAE016-001 | Version 3.1 parametrizada en DDL |
|
||||
| RF-5.1.2 Escenarios de emision | RF-MAE016-002 | CFDI Ingreso y Traslado soportados |
|
||||
| RF-5.1.3 Expediente fiscal por viaje | RF-MAE016-013 | Expediente con UUID, XML, PDF, QR |
|
||||
| RF-5.1.4 Validaciones previas | RF-MAE016-008 | Validacion exhaustiva pre-timbrado |
|
||||
| RF-5.1.5 Reemision/correccion controlada | RF-MAE016-012 | Cancelacion con motivos y sustitucion |
|
||||
| RF-5.1.6 Integracion con PAC | RF-MAE016-009 | Finkok, Facturapi, SW con failover |
|
||||
| RF-5.1.7 Evidencia para inspeccion | RF-MAE016-014 | PDF/XML/QR offline en app movil |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAE-016 Carta Porte CFDI - ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0*
|
||||
138
docs/02-definicion-modulos/MAE-016-carta-porte/RESUMEN-EPICA.md
Normal file
138
docs/02-definicion-modulos/MAE-016-carta-porte/RESUMEN-EPICA.md
Normal file
@ -0,0 +1,138 @@
|
||||
# RESUMEN-EPICA.md - MAE-016 Carta Porte CFDI
|
||||
|
||||
**Epica:** EPIC-MAE-016 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Datos de la Epica
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | EPIC-MAE-016 |
|
||||
| **Nombre** | Carta Porte CFDI |
|
||||
| **Modulo** | MAE-016 |
|
||||
| **Fase** | Fase 2 - MAE (Modulos Aplicacion Extendidos) |
|
||||
| **Prioridad** | Alta |
|
||||
| **Total Story Points** | 50 |
|
||||
| **Historias de Usuario** | 10 |
|
||||
| **Estado** | Backlog |
|
||||
| **Schema BD** | compliance |
|
||||
| **DDL** | `database/ddl/08-compliance-schema-ddl.sql` |
|
||||
|
||||
---
|
||||
|
||||
## Objetivo de la Epica
|
||||
|
||||
Implementar la generacion, validacion, timbrado y administracion del CFDI con complemento Carta Porte version 3.1, conforme a la normativa del SAT, para cumplir con la obligacion fiscal de documentar el transporte de bienes y mercancias en territorio nacional. El modulo debe automatizar la construccion del complemento a partir de los datos operativos del viaje, integrarse con PAC para el timbrado digital y ofrecer funcionalidades de descarga, cancelacion y expediente fiscal.
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
1. **Cumplimiento fiscal obligatorio:** Evita multas y decomiso de mercancias por falta del complemento Carta Porte durante el traslado.
|
||||
2. **Automatizacion operativa:** Elimina la captura manual de datos fiscales al construir el complemento desde los datos del viaje (ubicaciones, mercancias, operador, unidad).
|
||||
3. **Trazabilidad fiscal:** Cada viaje queda vinculado a su UUID de CFDI, XML, PDF y QR, creando un expediente fiscal auditable.
|
||||
4. **Reduccion de errores:** Las validaciones previas al timbrado detectan datos faltantes o incorrectos antes de enviar al PAC, evitando rechazos y cancelaciones innecesarias.
|
||||
5. **Disponibilidad en ruta:** El operador porta el documento en formato digital (PDF/QR) incluso sin conectividad, cumpliendo con los requerimientos de inspeccion en carretera.
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
|
||||
- Generacion del complemento Carta Porte 3.1 para CFDI de Ingreso y CFDI de Traslado
|
||||
- Nodos XML: Ubicaciones (origen/destino), Mercancias, FiguraTransporte, Autotransporte
|
||||
- Validacion de campos obligatorios contra catalogos SAT
|
||||
- Integracion con PAC (Finkok, Facturapi, SW Sapien) para timbrado y cancelacion
|
||||
- Generacion de PDF con representacion impresa y codigo QR
|
||||
- Cancelacion con motivos 01, 02, 03, 04 y UUID de sustitucion
|
||||
- Expediente fiscal por viaje (UUID, XML, PDF, QR)
|
||||
- Disponibilidad offline del PDF/XML/QR en app movil
|
||||
- Reporte fiscal mensual de CFDI emitidos/cancelados
|
||||
|
||||
### Excluido
|
||||
|
||||
- Complemento Carta Porte para transporte maritimo, aereo o ferroviario (solo autotransporte federal)
|
||||
- Integracion directa con el portal del SAT para consulta de estatus
|
||||
- Generacion de CFDI sin complemento Carta Porte (cubierto en MAI-009)
|
||||
- Comercio exterior avanzado (solo se soporta fraccion arancelaria y pedimentos como campos informativos)
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Dependencias |
|
||||
|----|--------|----|-----------|--------------|
|
||||
| US-MAE016-001 | Generar carta porte desde viaje | 8 | P0 | MAI-005 (Viaje despachado) |
|
||||
| US-MAE016-002 | Validar datos obligatorios SAT | 5 | P0 | US-MAE016-001 |
|
||||
| US-MAE016-003 | Timbrar CFDI con PAC | 8 | P0 | US-MAE016-002 |
|
||||
| US-MAE016-004 | Descargar PDF de carta porte | 3 | P1 | US-MAE016-003 |
|
||||
| US-MAE016-005 | Cancelar CFDI con motivo | 5 | P1 | US-MAE016-003 |
|
||||
| US-MAE016-006 | Consultar expediente fiscal | 3 | P1 | US-MAE016-003 |
|
||||
| US-MAE016-007 | Agregar mercancias transportadas | 5 | P0 | US-MAE016-001 |
|
||||
| US-MAE016-008 | Registrar figuras de transporte | 5 | P1 | US-MAE016-001 |
|
||||
| US-MAE016-009 | Configurar datos autotransporte federal | 5 | P1 | US-MAE016-001 |
|
||||
| US-MAE016-010 | Generar reporte fiscal mensual | 3 | P2 | US-MAE016-003 |
|
||||
|
||||
### Distribucion por Prioridad
|
||||
|
||||
| Prioridad | Historias | Story Points | Porcentaje |
|
||||
|-----------|-----------|--------------|------------|
|
||||
| P0 (Critico) | 4 | 26 | 52% |
|
||||
| P1 (Importante) | 5 | 21 | 42% |
|
||||
| P2 (Deseable) | 1 | 3 | 6% |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias Externas
|
||||
|
||||
| Dependencia | Tipo | Modulo/Sistema | Descripcion |
|
||||
|-------------|------|----------------|-------------|
|
||||
| Viaje despachado | Interna | MAI-005 Despacho | Se requiere un viaje con datos operativos completos |
|
||||
| Datos de flota | Interna | MAI-011 Gestion de Flota | Placas, permisos SCT, configuracion vehicular, licencias |
|
||||
| Datos de OT | Interna | MAI-003 Ordenes de Transporte | Mercancias, ubicaciones origen/destino |
|
||||
| Factura transporte | Interna | MAI-009 Facturacion | El CFDI de Ingreso se vincula con la factura |
|
||||
| PAC (Finkok/Facturapi/SW) | Externa | Proveedor timbrado | API de timbrado, cancelacion y consulta de estatus |
|
||||
| Catalogos SAT | Externa | SAT | Catalogos oficiales de claves para Carta Porte 3.1 |
|
||||
| CSD (Certificado Sello Digital) | Externa | SAT | Certificado .cer y llave .key del contribuyente |
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Probabilidad | Impacto | Mitigacion |
|
||||
|--------|--------------|---------|------------|
|
||||
| Cambio de version del complemento por el SAT | Media | Alto | Parametrizar version en DDL (campo version_carta_porte), estructura modular del XML |
|
||||
| Rechazo de timbrado por datos invalidos | Alta | Medio | Validacion exhaustiva previa al envio, mensajes de error claros |
|
||||
| Indisponibilidad del PAC | Baja | Alto | Soportar multiples PAC con failover automatico |
|
||||
| Catalogos SAT desactualizados | Media | Medio | Proceso de actualizacion periodica de catalogos, versionamiento |
|
||||
| Cancelacion rechazada por el SAT | Media | Medio | Informar al usuario el estatus de cancelacion y opciones disponibles |
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion de la Epica
|
||||
|
||||
1. Se puede generar una carta porte desde cualquier viaje despachado con datos completos
|
||||
2. Las validaciones detectan todos los campos obligatorios faltantes segun el tipo de CFDI
|
||||
3. El timbrado con al menos un PAC (Finkok o Facturapi) funciona correctamente
|
||||
4. El PDF generado incluye todos los datos del complemento Carta Porte y codigo QR
|
||||
5. La cancelacion envia correctamente los motivos 01-04 al PAC
|
||||
6. El expediente fiscal muestra UUID, XML, PDF y estado del CFDI por viaje
|
||||
7. El operador puede descargar el PDF/XML desde la app para consulta offline
|
||||
8. El reporte fiscal mensual lista todos los CFDI con filtros por tipo, estado y fecha
|
||||
|
||||
---
|
||||
|
||||
## Metricas de Exito
|
||||
|
||||
| Metrica | Objetivo |
|
||||
|---------|----------|
|
||||
| Tasa de timbrado exitoso al primer intento | > 95% |
|
||||
| Tiempo promedio de generacion y timbrado | < 10 segundos |
|
||||
| CFDI cancelados por errores del sistema | < 2% |
|
||||
| Cobertura de viajes con carta porte | 100% de viajes que lo requieren |
|
||||
|
||||
---
|
||||
|
||||
*EPIC-MAE-016 Carta Porte CFDI - ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,65 @@
|
||||
# US-MAE016-001: Generar carta porte desde viaje
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-001 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 8 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** facturador,
|
||||
**quiero** generar una carta porte a partir de un viaje despachado,
|
||||
**para** cumplir con la obligacion fiscal del SAT de documentar el transporte de mercancias con el complemento Carta Porte 3.1.
|
||||
|
||||
## Descripcion Detallada
|
||||
El complemento Carta Porte version 3.1 es obligatorio para toda empresa que transporte bienes y mercancias en territorio nacional por autotransporte federal. La generacion manual de este documento es propensa a errores y consume tiempo significativo, ya que requiere capturar datos de emisor, receptor, ubicaciones (origen/destino), mercancias, operador, unidad vehicular y remolques.
|
||||
|
||||
Esta historia cubre la automatizacion de la generacion del complemento. Al seleccionar un viaje despachado, el sistema extrae automaticamente todos los datos necesarios: datos fiscales del emisor (del tenant), datos del receptor/cliente, ubicaciones de la ruta del viaje, mercancias de las OTs asociadas, operador asignado y datos del vehiculo (permiso SCT, configuracion vehicular, placas). El facturador selecciona si es un CFDI de Ingreso (servicio de transporte) o CFDI de Traslado (mercancias propias).
|
||||
|
||||
El registro se crea en la tabla `compliance.cartas_porte` con estado BORRADOR, version_carta_porte '3.1' y todos los datos precargados. Automaticamente se generan los registros relacionados en `compliance.ubicaciones_carta_porte`, `compliance.mercancias_carta_porte`, `compliance.figuras_transporte` y `compliance.autotransporte_carta_porte`. El facturador puede revisar y ajustar los datos antes de proceder a la validacion.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Generacion exitosa de carta porte tipo Ingreso
|
||||
**Dado** un viaje con estado DESPACHADO o EN_TRANSITO que tiene datos completos (ubicaciones, mercancias, operador, unidad)
|
||||
**Cuando** el facturador selecciona el viaje y elige tipo CFDI "Ingreso"
|
||||
**Entonces** el sistema crea un registro en `compliance.cartas_porte` con tipo_cfdi = 'INGRESO', version_carta_porte = '3.1', estado = 'BORRADOR', datos del emisor (RFC, nombre, regimen fiscal del tenant), datos del receptor (RFC, nombre, uso CFDI, domicilio fiscal CP del cliente), y crea registros relacionados de ubicaciones, mercancias, figuras y autotransporte.
|
||||
|
||||
### Escenario 2: Generacion exitosa de carta porte tipo Traslado
|
||||
**Dado** un viaje con estado DESPACHADO que transporta mercancias propias del contribuyente
|
||||
**Cuando** el facturador selecciona el viaje y elige tipo CFDI "Traslado"
|
||||
**Entonces** el sistema crea un registro con tipo_cfdi = 'TRASLADO', subtotal = 0, total = 0, receptor_rfc igual al emisor_rfc y estado = 'BORRADOR'.
|
||||
|
||||
### Escenario 3: Viaje sin datos suficientes
|
||||
**Dado** un viaje con estado DESPACHADO pero sin mercancias registradas en sus OTs
|
||||
**Cuando** el facturador intenta generar la carta porte
|
||||
**Entonces** el sistema crea el registro en BORRADOR con los datos disponibles y muestra una advertencia indicando que faltan mercancias por registrar antes de proceder a la validacion.
|
||||
|
||||
### Escenario 4: Viaje en estado invalido
|
||||
**Dado** un viaje con estado BORRADOR o PLANEADO (no despachado)
|
||||
**Cuando** el facturador intenta generar una carta porte
|
||||
**Entonces** el sistema rechaza la operacion con el mensaje "Solo se puede generar carta porte para viajes despachados o posteriores".
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Utilizar tablas existentes del DDL `08-compliance-schema-ddl.sql`: `compliance.cartas_porte`, `compliance.ubicaciones_carta_porte`, `compliance.mercancias_carta_porte`, `compliance.figuras_transporte`, `compliance.autotransporte_carta_porte`
|
||||
- **Backend:** Crear `CartaPorteService.generarDesdeViaje(viajeId, tipoCfdi)` que extraiga datos del viaje y sus relaciones; crear `CartaPorteController` con endpoint POST `/api/v1/carta-porte`; crear DTOs `CreateCartaPorteDto` y `CartaPorteResponseDto`
|
||||
- **Frontend:** Crear componente `GenerarCartaPorteDialog` con selector de viaje y tipo CFDI; crear vista `CartaPorteListPage` con listado y filtros por estado/fecha/tipo; boton "Generar Carta Porte" en la vista de detalle del viaje
|
||||
- **Tests:** Test unitario del servicio de extraccion de datos del viaje; test de integracion del endpoint POST; test de validacion de estado del viaje; test E2E del flujo completo de generacion
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** MAI-005 (Despacho - viaje despachado), MAI-003 (OT - datos de mercancias y ubicaciones), MAI-011 (Flota - datos de unidad, remolques, operador)
|
||||
- **Bloquea:** US-MAE016-002 (Validar datos), US-MAE016-007 (Agregar mercancias), US-MAE016-008 (Registrar figuras), US-MAE016-009 (Configurar autotransporte)
|
||||
|
||||
## Notas Tecnicas
|
||||
- El campo `viaje_id` en `compliance.cartas_porte` es NOT NULL y referencia al viaje fuente.
|
||||
- Los datos del emisor se obtienen de la configuracion fiscal del tenant (tabla de configuracion).
|
||||
- Los datos del receptor se obtienen del cliente asociado a la OT del viaje.
|
||||
- La version_carta_porte se establece como '3.1' por defecto (vigente desde 17-jul-2024).
|
||||
- Las ubicaciones se mapean desde las paradas de la ruta del viaje, asignando secuencia numerica ordenada.
|
||||
- El campo peso_bruto_total se calcula como la suma de peso_en_kg de todas las mercancias.
|
||||
- El campo num_total_mercancias se calcula como el conteo de registros de mercancias.
|
||||
- RLS por tenant_id garantiza aislamiento multi-tenant en todas las tablas del schema compliance.
|
||||
@ -0,0 +1,64 @@
|
||||
# US-MAE016-002: Validar datos obligatorios SAT
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-002 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** facturador,
|
||||
**quiero** validar que todos los campos obligatorios del complemento Carta Porte 3.1 esten completos y correctos antes de enviar al PAC,
|
||||
**para** evitar rechazos de timbrado y garantizar el cumplimiento con la estructura XML requerida por el SAT.
|
||||
|
||||
## Descripcion Detallada
|
||||
El complemento Carta Porte 3.1 tiene reglas estrictas sobre campos obligatorios que varian segun el tipo de CFDI (Ingreso vs Traslado), el tipo de transporte y la naturaleza de las mercancias. Un error en cualquier campo obligatorio resulta en rechazo del timbrado por parte del PAC, lo que genera retrasos operativos y posibles multas si el viaje se realiza sin el documento.
|
||||
|
||||
La validacion debe ejecutarse de forma exhaustiva antes de permitir el timbrado. Cada regla de validacion verifica un campo o grupo de campos especifico contra los catalogos del SAT (BienesTransp, ClaveUnidad, ConfigVehicular, TipoPermiso SCT, TipoFigura). Cuando la validacion detecta errores, retorna una lista detallada indicando el campo, la tabla afectada y la descripcion del error para que el facturador pueda corregirlos.
|
||||
|
||||
Si todos los campos obligatorios son validos, la carta porte cambia de estado BORRADOR a VALIDADA, habilitando el boton de timbrado. Esto asegura que solo se envien al PAC documentos con alta probabilidad de timbrado exitoso, reduciendo cancelaciones y retrabajos.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Validacion exitosa con todos los campos completos
|
||||
**Dado** una carta porte en estado BORRADOR con datos de emisor, receptor, al menos una ubicacion de origen y una de destino, al menos una mercancia con bienes_transp y peso_en_kg, una figura de transporte tipo operador con num_licencia, datos de autotransporte con perm_sct y placa_vm, y seguro de responsabilidad civil
|
||||
**Cuando** el facturador ejecuta la validacion
|
||||
**Entonces** el sistema confirma que todos los campos son validos, actualiza el estado a VALIDADA y habilita la opcion de timbrado.
|
||||
|
||||
### Escenario 2: Validacion fallida por mercancias incompletas
|
||||
**Dado** una carta porte en estado BORRADOR donde una mercancia no tiene el campo bienes_transp (clave SAT)
|
||||
**Cuando** el facturador ejecuta la validacion
|
||||
**Entonces** el sistema retorna un error con campo = "bienes_transp", tabla = "compliance.mercancias_carta_porte", descripcion = "Clave de bienes transportados (catalogo SAT) es obligatoria para cada mercancia" y no cambia el estado.
|
||||
|
||||
### Escenario 3: Validacion fallida por ausencia de ubicaciones
|
||||
**Dado** una carta porte en estado BORRADOR sin registros en `compliance.ubicaciones_carta_porte`
|
||||
**Cuando** el facturador ejecuta la validacion
|
||||
**Entonces** el sistema retorna errores indicando que se requiere al menos una ubicacion de tipo 'Origen' y al menos una de tipo 'Destino', ambas con codigo_postal valido de 5 digitos.
|
||||
|
||||
### Escenario 4: Validacion fallida por material peligroso sin seguro ambiental
|
||||
**Dado** una carta porte donde alguna mercancia tiene material_peligroso = true pero no se han registrado asegura_med_ambiente ni poliza_med_ambiente
|
||||
**Cuando** el facturador ejecuta la validacion
|
||||
**Entonces** el sistema retorna un error indicando que el seguro de medio ambiente es obligatorio cuando se transportan materiales peligrosos.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Consultar tablas `compliance.cartas_porte`, `compliance.ubicaciones_carta_porte`, `compliance.mercancias_carta_porte`, `compliance.figuras_transporte`, `compliance.autotransporte_carta_porte` para obtener datos completos; actualizar campo `estado` a 'VALIDADA'
|
||||
- **Backend:** Crear `CartaPorteValidationService` con metodo `validar(cartaPorteId)` que ejecuta todas las reglas y retorna array de errores; crear endpoint POST `/api/v1/carta-porte/:id/validar`; crear `ValidationErrorDto` con campos: campo, tabla, descripcion, severidad
|
||||
- **Frontend:** Crear componente `ValidacionCartaPortePanel` que muestra lista de errores agrupados por seccion (emisor, receptor, ubicaciones, mercancias, figuras, autotransporte, seguros); boton "Validar" con indicador visual (verde = valida, rojo = errores); enlace directo al campo con error para edicion rapida
|
||||
- **Tests:** Test unitario para cada regla de validacion individual; test de validacion completa con datos correctos; test de validacion con cada tipo de error; test de transicion de estado BORRADOR a VALIDADA
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR)
|
||||
- **Bloquea:** US-MAE016-003 (Timbrar CFDI - requiere estado VALIDADA)
|
||||
|
||||
## Notas Tecnicas
|
||||
- Las claves de catalogo SAT (bienes_transp, clave_unidad, config_vehicular, perm_sct, tipo_figura) se validan contra tablas o archivos de catalogo locales para evitar llamadas externas.
|
||||
- El codigo_postal de ubicaciones debe existir en el catalogo de codigos postales del SAT (5 digitos).
|
||||
- Para CFDI de Ingreso se valida que receptor_rfc sea diferente del emisor_rfc.
|
||||
- Para CFDI de Traslado se valida que subtotal y total sean 0 o nulos.
|
||||
- El peso_bruto_total debe ser igual a la suma de peso_en_kg de las mercancias (tolerancia de 0.001 kg por redondeo).
|
||||
- El num_total_mercancias debe coincidir con el conteo de registros en mercancias_carta_porte.
|
||||
- La validacion es idempotente: puede ejecutarse multiples veces sin efectos secundarios hasta que sea exitosa.
|
||||
@ -0,0 +1,66 @@
|
||||
# US-MAE016-003: Timbrar CFDI con PAC
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-003 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 8 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** facturador,
|
||||
**quiero** timbrar el CFDI con complemento Carta Porte 3.1 a traves de un PAC autorizado,
|
||||
**para** obtener el UUID fiscal, el sello digital y la cadena de certificacion que le dan validez legal al documento ante el SAT.
|
||||
|
||||
## Descripcion Detallada
|
||||
El timbrado es el proceso mediante el cual un Proveedor Autorizado de Certificacion (PAC) valida y sella digitalmente el CFDI, asignandole un UUID (folio fiscal) unico que identifica el comprobante ante el SAT. Sin el timbrado, el CFDI no tiene validez fiscal y no puede utilizarse como respaldo para el transporte de mercancias.
|
||||
|
||||
El sistema debe construir el XML del CFDI conforme al esquema XSD del SAT para la version 4.0 del CFDI con el complemento CartaPorte31. El XML incluye los nodos principales: Comprobante, Emisor, Receptor, Conceptos, y el complemento con los nodos Ubicaciones, Mercancias (con subnodo Mercancia y Autotransporte), y FiguraTransporte. El XML se firma con el CSD (Certificado de Sello Digital) del contribuyente antes de enviarse al PAC.
|
||||
|
||||
La integracion debe soportar al menos dos PAC (Finkok y Facturapi) con failover automatico: si el PAC primario no responde en 5 segundos, el sistema intenta con el secundario. Al recibir la respuesta exitosa, se almacenan uuid_cfdi, fecha_timbrado y el xml_cfdi completo con el TimbreFiscalDigital. El estado de la carta porte cambia a TIMBRADA.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Timbrado exitoso con PAC primario
|
||||
**Dado** una carta porte en estado VALIDADA con todos los datos obligatorios completos y CSD del contribuyente configurado
|
||||
**Cuando** el facturador solicita el timbrado
|
||||
**Entonces** el sistema genera el XML del CFDI con complemento CartaPorte31, lo firma con el CSD, lo envia al PAC primario, recibe el TimbreFiscalDigital con UUID, almacena uuid_cfdi, fecha_timbrado y xml_cfdi, actualiza el estado a TIMBRADA y muestra el UUID al facturador.
|
||||
|
||||
### Escenario 2: Failover al PAC secundario
|
||||
**Dado** una carta porte en estado VALIDADA lista para timbrar pero el PAC primario (Finkok) no responde en 5 segundos
|
||||
**Cuando** el sistema detecta el timeout del PAC primario
|
||||
**Entonces** el sistema reintenta automaticamente con el PAC secundario (Facturapi), timbra exitosamente, almacena los datos del timbrado y registra en log que se uso el PAC secundario por failover.
|
||||
|
||||
### Escenario 3: Rechazo del PAC por error en XML
|
||||
**Dado** una carta porte en estado VALIDADA que se envia al PAC pero contiene un error no detectado por la validacion local (por ejemplo, una clave de catalogo SAT deprecada)
|
||||
**Cuando** el PAC rechaza el timbrado con un codigo de error
|
||||
**Entonces** el sistema muestra al facturador el codigo de error y descripcion del SAT/PAC, no modifica el estado de la carta porte (permanece en VALIDADA) y registra el intento fallido en log de auditoria.
|
||||
|
||||
### Escenario 4: Carta porte no validada
|
||||
**Dado** una carta porte en estado BORRADOR (no ha pasado validacion)
|
||||
**Cuando** el facturador intenta timbrar
|
||||
**Entonces** el sistema rechaza la operacion con el mensaje "La carta porte debe estar en estado VALIDADA para poder timbrar. Ejecute la validacion primero."
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Actualizar campos uuid_cfdi, fecha_timbrado, xml_cfdi, serie, folio y estado en `compliance.cartas_porte`
|
||||
- **Backend:** Crear `CartaPorteXmlBuilderService` para construir el XML conforme al XSD del SAT (nodos Comprobante, Emisor, Receptor, Conceptos, CartaPorte31 con Ubicaciones, Mercancias, FiguraTransporte, Autotransporte); crear `PacIntegrationService` con interfaz comun para Finkok y Facturapi; crear `CsdService` para firmar el XML con certificado .cer y llave .key; crear endpoint POST `/api/v1/carta-porte/:id/timbrar`; implementar logica de failover con timeout de 5 segundos
|
||||
- **Frontend:** Crear boton "Timbrar" en la vista de detalle de carta porte (habilitado solo en estado VALIDADA); mostrar dialogo de confirmacion antes de timbrar; mostrar spinner durante el proceso; mostrar UUID y fecha de timbrado al completar; mostrar errores del PAC si falla
|
||||
- **Tests:** Test unitario del XML builder verificando estructura XSD; test de integracion con PAC en modo sandbox; test de failover cuando PAC primario falla; test de manejo de errores del PAC; test de firma con CSD de prueba
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-002 (Validar datos - requiere estado VALIDADA)
|
||||
- **Bloquea:** US-MAE016-004 (Descargar PDF), US-MAE016-005 (Cancelar CFDI), US-MAE016-006 (Expediente fiscal), US-MAE016-010 (Reporte fiscal)
|
||||
|
||||
## Notas Tecnicas
|
||||
- El namespace XML del complemento es `http://www.sat.gob.mx/CartaPorte31` con prefijo `cartaporte31`.
|
||||
- El esquema XSD de referencia es `CartaPorte31.xsd` publicado por el SAT.
|
||||
- El CFDI base usa version 4.0 con namespace `http://www.sat.gob.mx/cfd/4`.
|
||||
- El TimbreFiscalDigital usa version 1.1 con namespace `http://www.sat.gob.mx/TimbreFiscalDigital`.
|
||||
- El CSD del contribuyente se configura a nivel de tenant. Cada tenant tiene su propio certificado .cer, llave .key y contrasena.
|
||||
- Los PAC ofrecen ambientes de sandbox para pruebas y produccion para operacion real. La configuracion del ambiente es por variable de entorno.
|
||||
- Finkok API: SOAP/REST; Facturapi API: REST JSON; SW Sapien API: REST. Cada PAC tiene su propio formato de request/response.
|
||||
- El XML firmado incluye los atributos Certificado (base64 del .cer), NoCertificado y Sello (firma digital).
|
||||
- La serie y folio se asignan automaticamente segun la configuracion del tenant (secuencia numerica).
|
||||
@ -0,0 +1,64 @@
|
||||
# US-MAE016-004: Descargar PDF de carta porte
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-004 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 3 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** operador de transporte,
|
||||
**quiero** descargar el PDF y XML de la carta porte timbrada para portarlo en mi dispositivo movil,
|
||||
**para** cumplir con la obligacion de presentar el documento durante el traslado ante cualquier inspeccion de la autoridad fiscal en carretera.
|
||||
|
||||
## Descripcion Detallada
|
||||
La normativa del SAT establece que durante el traslado de mercancias en territorio nacional, el transportista debe portar el CFDI con complemento Carta Porte. La autoridad fiscal puede solicitar la exhibicion de este documento en cualquier punto de la ruta (casetas, retenes, puntos de verificacion). La falta del documento puede resultar en multas y decomiso de la mercancia.
|
||||
|
||||
El sistema debe generar la representacion impresa (PDF) del CFDI timbrado conforme a las especificaciones del Anexo 20 del SAT. El PDF incluye los datos fiscales del emisor y receptor, detalle de mercancias transportadas (descripcion, cantidad, peso, clave SAT), ubicaciones de origen y destino con codigos postales, figuras de transporte (operador, propietario), datos del autotransporte federal (permiso SCT, vehiculo, remolques), datos de seguros y el codigo QR de verificacion del SAT.
|
||||
|
||||
Adicionalmente, el operador debe poder descargar tanto el PDF como el XML desde la app movil para consulta en modo offline. Los archivos se almacenan localmente en el dispositivo y permanecen accesibles sin conexion a internet durante todo el viaje.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Descarga de PDF desde la aplicacion web
|
||||
**Dado** una carta porte en estado TIMBRADA con uuid_cfdi y xml_cfdi almacenados
|
||||
**Cuando** el facturador solicita la descarga del PDF
|
||||
**Entonces** el sistema genera un PDF con todos los datos del CFDI y complemento Carta Porte (emisor, receptor, mercancias, ubicaciones, figuras, autotransporte, seguros, QR), lo almacena en el campo pdf_url y lo descarga al navegador del usuario.
|
||||
|
||||
### Escenario 2: Descarga de XML desde la aplicacion web
|
||||
**Dado** una carta porte en estado TIMBRADA con xml_cfdi almacenado
|
||||
**Cuando** el facturador solicita la descarga del XML
|
||||
**Entonces** el sistema retorna el contenido del campo xml_cfdi como archivo .xml descargable con nombre formato "{serie}-{folio}-{uuid_cfdi}.xml".
|
||||
|
||||
### Escenario 3: Descarga offline desde app movil
|
||||
**Dado** un operador con la app movil que tiene un viaje activo con carta porte timbrada
|
||||
**Cuando** el operador descarga el PDF y XML mientras tiene conexion a internet
|
||||
**Entonces** los archivos se almacenan localmente en el dispositivo y permanecen accesibles en la seccion "Documentos del Viaje" incluso sin conexion a internet.
|
||||
|
||||
### Escenario 4: Carta porte no timbrada
|
||||
**Dado** una carta porte en estado BORRADOR o VALIDADA (no timbrada)
|
||||
**Cuando** un usuario intenta descargar el PDF o XML
|
||||
**Entonces** el sistema muestra el mensaje "El PDF y XML solo estan disponibles para cartas porte timbradas" y no permite la descarga.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Leer campos xml_cfdi, pdf_url y qr_url de `compliance.cartas_porte`; actualizar pdf_url y qr_url despues de generar el PDF
|
||||
- **Backend:** Crear `CartaPortePdfService` para generar PDF con libreria de generacion (PDFKit o Puppeteer); crear endpoint GET `/api/v1/carta-porte/:id/pdf` que retorna el PDF como stream; crear endpoint GET `/api/v1/carta-porte/:id/xml` que retorna el XML como archivo; generar codigo QR con URL de verificacion del SAT
|
||||
- **Frontend:** Agregar botones "Descargar PDF" y "Descargar XML" en la vista de detalle de carta porte timbrada; en app movil: implementar descarga y almacenamiento local con acceso offline; mostrar visor de PDF integrado con opcion de compartir
|
||||
- **Tests:** Test unitario de generacion de PDF con datos de prueba; test de descarga de XML con contenido correcto; test de endpoint PDF con respuesta tipo application/pdf; test de QR con URL valida de verificacion SAT
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-003 (Timbrar CFDI - requiere estado TIMBRADA con xml_cfdi)
|
||||
- **Bloquea:** MAI-015 (Portal Cliente - descarga de carta porte por el cliente)
|
||||
|
||||
## Notas Tecnicas
|
||||
- El PDF sigue el formato de representacion impresa del Anexo 20 del SAT.
|
||||
- El codigo QR contiene la URL de verificacion del SAT: `https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id={uuid}&re={rfc_emisor}&rr={rfc_receptor}&tt={total}&fe={ultimos8SelloDigital}`.
|
||||
- El nombre del archivo PDF sigue el formato: `CP-{serie}{folio}-{uuid_cfdi}.pdf`.
|
||||
- El nombre del archivo XML sigue el formato: `{serie}-{folio}-{uuid_cfdi}.xml`.
|
||||
- Para la app movil, los archivos descargados se almacenan en el almacenamiento local del dispositivo con un indice por viaje_id.
|
||||
- Se debe considerar el tamano del PDF (estimado 200-500 KB) para la descarga movil en condiciones de conectividad limitada.
|
||||
- El qr_url almacena la URL de la imagen QR generada, que se incluye en el PDF y puede mostrarse independientemente.
|
||||
@ -0,0 +1,63 @@
|
||||
# US-MAE016-005: Cancelar CFDI con motivo
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-005 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** contador,
|
||||
**quiero** cancelar un CFDI con complemento Carta Porte indicando el motivo conforme al catalogo del SAT,
|
||||
**para** corregir errores en comprobantes emitidos o documentar operaciones que no se llevaron a cabo, manteniendo un expediente fiscal limpio y auditable.
|
||||
|
||||
## Descripcion Detallada
|
||||
La cancelacion de CFDI es un proceso regulado por el SAT que permite invalidar un comprobante fiscal previamente timbrado. A partir de las reformas fiscales, toda cancelacion debe incluir un motivo del catalogo oficial del SAT. El proceso se realiza a traves del PAC y puede requerir la aceptacion del receptor cuando el monto supera cierto umbral.
|
||||
|
||||
Los motivos de cancelacion son: 01 (Comprobante emitido con errores con relacion), que requiere indicar el UUID del CFDI que sustituye al cancelado; 02 (Comprobante emitido con errores sin relacion), cuando el error no requiere reemision; 03 (No se llevo a cabo la operacion), cuando el viaje no se realizo; y 04 (Operacion nominativa relacionada en factura global).
|
||||
|
||||
El sistema debe enviar la solicitud de cancelacion al PAC con los datos requeridos (UUID del CFDI a cancelar, motivo y UUID de sustitucion si aplica), registrar la cancelacion en la bitacora de auditoria y actualizar el estado de la carta porte. La cancelacion debe quedar trazada con el usuario que la solicito, la fecha y el motivo detallado.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Cancelacion con motivo 01 (con sustitucion)
|
||||
**Dado** una carta porte en estado TIMBRADA que contiene errores y ya se ha emitido un CFDI de sustitucion con UUID conocido
|
||||
**Cuando** el contador selecciona motivo "01 - Comprobante emitido con errores con relacion" e ingresa el UUID de sustitucion
|
||||
**Entonces** el sistema envia la solicitud al PAC con el UUID a cancelar, motivo '01' y UUID de sustitucion, actualiza el estado a CANCELADA, registra fecha_cancelacion, motivo_cancelacion y uuid_sustitucion en `compliance.cartas_porte`, y registra la operacion en auditoria.
|
||||
|
||||
### Escenario 2: Cancelacion con motivo 03 (operacion no realizada)
|
||||
**Dado** una carta porte en estado TIMBRADA para un viaje que no se ejecuto
|
||||
**Cuando** el contador selecciona motivo "03 - No se llevo a cabo la operacion"
|
||||
**Entonces** el sistema envia la solicitud al PAC con motivo '03' sin UUID de sustitucion, actualiza el estado a CANCELADA, registra fecha_cancelacion y motivo_cancelacion, y uuid_sustitucion queda nulo.
|
||||
|
||||
### Escenario 3: Motivo 01 sin UUID de sustitucion
|
||||
**Dado** una carta porte en estado TIMBRADA y el contador selecciona motivo "01"
|
||||
**Cuando** el contador no ingresa el UUID de sustitucion y confirma la cancelacion
|
||||
**Entonces** el sistema rechaza la operacion con el mensaje "El motivo 01 requiere indicar el UUID del CFDI de sustitucion" y no envia la solicitud al PAC.
|
||||
|
||||
### Escenario 4: Cancelacion rechazada por el PAC
|
||||
**Dado** una carta porte en estado TIMBRADA que se intenta cancelar pero el receptor no acepta la cancelacion (proceso de aceptacion/rechazo del SAT)
|
||||
**Cuando** el PAC retorna un estatus de "Cancelacion en proceso" o "Cancelacion rechazada"
|
||||
**Entonces** el sistema informa al contador el estatus actual de la cancelacion, no cambia el estado de la carta porte y registra el intento en el log de auditoria.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Actualizar campos estado, fecha_cancelacion, motivo_cancelacion y uuid_sustitucion en `compliance.cartas_porte`
|
||||
- **Backend:** Crear metodo `CartaPorteService.cancelar(cartaPorteId, motivo, uuidSustitucion?)` que valida motivo y envia al PAC; crear endpoint POST `/api/v1/carta-porte/:id/cancelar` con body `{ motivo: string, uuidSustitucion?: string }`; crear `CancelacionDto` con validacion del motivo (01, 02, 03, 04); registrar en auditoria la cancelacion con usuario y timestamp
|
||||
- **Frontend:** Crear dialogo `CancelarCartaPorteDialog` con selector de motivo (dropdown con los 4 motivos), campo condicional para UUID de sustitucion (visible solo para motivo 01), campo de observaciones adicionales; confirmacion de doble paso ("Esta seguro de cancelar el CFDI {UUID}?"); mostrar estatus de cancelacion despues de enviar
|
||||
- **Tests:** Test unitario de validacion de motivos (01 con UUID, 02-04 sin UUID); test de integracion con PAC en sandbox para cancelacion; test de actualizacion de estado en BD; test de rechazo cuando falta UUID para motivo 01; test de auditoria de cancelacion
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-003 (Timbrar CFDI - requiere estado TIMBRADA para cancelar)
|
||||
- **Bloquea:** Ningun modulo directamente, pero US-MAE016-006 (Expediente fiscal) muestra la informacion de cancelacion
|
||||
|
||||
## Notas Tecnicas
|
||||
- Los motivos de cancelacion del catalogo SAT son: 01 (Comprobante emitido con errores con relacion), 02 (Comprobante emitido con errores sin relacion), 03 (No se llevo a cabo la operacion), 04 (Operacion nominativa relacionada en factura global).
|
||||
- Para el motivo 01, el uuid_sustitucion debe corresponder a un CFDI timbrado valido. El sistema no valida que el UUID exista en la BD local (puede ser un CFDI emitido en otro sistema).
|
||||
- El SAT implemento un esquema de aceptacion/rechazo de cancelacion para CFDI con monto superior a un umbral. El receptor tiene 72 horas para aceptar o rechazar. Si no responde, la cancelacion se acepta por omision.
|
||||
- La cancelacion en el PAC es asincrona en algunos casos. El sistema debe soportar consultar el estatus de cancelacion posteriormente.
|
||||
- Una vez cancelada, la carta porte no puede reactivarse. Si se requiere un nuevo documento, se genera una nueva carta porte para el mismo viaje.
|
||||
- El campo motivo_cancelacion en la BD almacena el texto descriptivo completo, no solo el codigo numerico (ejemplo: "01 - Comprobante emitido con errores con relacion").
|
||||
@ -0,0 +1,63 @@
|
||||
# US-MAE016-006: Consultar expediente fiscal
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-006 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 3 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** contador,
|
||||
**quiero** consultar el expediente fiscal completo de un viaje que incluya todas las cartas porte asociadas con su UUID, XML, PDF y estado,
|
||||
**para** tener trazabilidad fiscal de cada operacion de transporte y facilitar auditorias internas o requerimientos de la autoridad fiscal.
|
||||
|
||||
## Descripcion Detallada
|
||||
Cada viaje de transporte genera uno o mas CFDI con complemento Carta Porte durante su ciclo de vida. Un viaje puede tener multiples cartas porte cuando se cancela un CFDI y se emite uno de sustitucion. El expediente fiscal concentra todos estos documentos en una sola vista, permitiendo al contador verificar el estado fiscal del viaje de forma rapida.
|
||||
|
||||
El expediente fiscal muestra para cada carta porte asociada al viaje: UUID del CFDI, tipo (Ingreso o Traslado), estado (BORRADOR, VALIDADA, TIMBRADA, CANCELADA), serie y folio, fecha de timbrado, subtotal y total, enlaces para descargar XML y PDF, y datos de cancelacion (fecha, motivo, UUID de sustitucion) cuando aplica. Si existe un CFDI cancelado con motivo 01, el expediente muestra la relacion con el CFDI de sustitucion.
|
||||
|
||||
Esta funcionalidad es critica para cumplir con las obligaciones de conservacion de documentos fiscales digitales y para responder a requerimientos del SAT durante auditorias.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Expediente con un CFDI timbrado vigente
|
||||
**Dado** un viaje que tiene una sola carta porte en estado TIMBRADA
|
||||
**Cuando** el contador consulta el expediente fiscal del viaje
|
||||
**Entonces** el sistema muestra una lista con un registro que incluye: UUID del CFDI, tipo_cfdi, estado "TIMBRADA", serie, folio, fecha_timbrado, subtotal, total, y enlaces para descargar PDF y XML.
|
||||
|
||||
### Escenario 2: Expediente con CFDI cancelado y sustitucion
|
||||
**Dado** un viaje que tiene una carta porte CANCELADA con motivo 01 y una carta porte TIMBRADA de sustitucion
|
||||
**Cuando** el contador consulta el expediente fiscal
|
||||
**Entonces** el sistema muestra ambos registros ordenados por fecha de creacion, el CFDI cancelado muestra el motivo de cancelacion y el UUID de sustitucion vinculado al CFDI vigente, y el CFDI vigente se resalta visualmente como el documento activo.
|
||||
|
||||
### Escenario 3: Viaje sin carta porte
|
||||
**Dado** un viaje que no tiene ninguna carta porte generada
|
||||
**Cuando** el contador consulta el expediente fiscal
|
||||
**Entonces** el sistema muestra un mensaje "No se han generado cartas porte para este viaje" con un boton para generar la primera carta porte.
|
||||
|
||||
### Escenario 4: Filtro por estado en listado general
|
||||
**Dado** el listado general de cartas porte del tenant
|
||||
**Cuando** el contador filtra por estado CANCELADA y rango de fechas del mes actual
|
||||
**Entonces** el sistema muestra solo las cartas porte canceladas en el periodo, con totales de documentos cancelados y montos acumulados.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Consultar `compliance.cartas_porte` filtrado por viaje_id; incluir joins con tablas relacionadas para mostrar detalle resumido de ubicaciones y mercancias
|
||||
- **Backend:** Crear endpoint GET `/api/v1/carta-porte/expediente/:viajeId` que retorna todas las cartas porte del viaje con datos completos; crear `ExpedienteFiscalResponseDto` con array de cartas porte y metadatos del viaje; soportar filtros en listado general GET `/api/v1/carta-porte` con query params: estado, tipo_cfdi, fecha_desde, fecha_hasta, rfc_receptor
|
||||
- **Frontend:** Crear componente `ExpedienteFiscalPanel` que se integra en la vista de detalle del viaje; mostrar timeline de documentos fiscales con estado visual (verde = timbrada, rojo = cancelada, amarillo = borrador); enlaces de descarga rapida de PDF y XML; badge de relacion cancelacion-sustitucion para motivo 01
|
||||
- **Tests:** Test de endpoint expediente con viaje sin cartas porte; test con viaje con una carta porte timbrada; test con viaje con cancelacion y sustitucion; test de filtros del listado general
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-003 (Timbrar CFDI - los datos del expediente incluyen CFDI timbrados)
|
||||
- **Bloquea:** MAE-018 (Reportes y KPIs - los reportes fiscales se basan en datos del expediente)
|
||||
|
||||
## Notas Tecnicas
|
||||
- La consulta del expediente usa el indice `idx_carta_porte_viaje` sobre `compliance.cartas_porte(viaje_id)` para rendimiento optimo.
|
||||
- El listado general usa los indices `idx_carta_porte_tenant` y `idx_carta_porte_estado` para filtros eficientes.
|
||||
- RLS por tenant_id garantiza que cada tenant solo vea sus propios documentos fiscales.
|
||||
- La relacion entre CFDI cancelado (motivo 01) y CFDI de sustitucion se establece a traves del campo `uuid_sustitucion` que almacena el UUID del nuevo CFDI.
|
||||
- El expediente no muestra el contenido XML completo, solo metadatos y enlaces de descarga para mantener la respuesta liviana.
|
||||
- Se debe considerar paginacion para viajes con multiples cancelaciones/reemisiones (caso excepcional pero posible).
|
||||
@ -0,0 +1,66 @@
|
||||
# US-MAE016-007: Agregar mercancias transportadas
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-007 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** facturador,
|
||||
**quiero** agregar y editar las mercancias transportadas en la carta porte con sus claves SAT, pesos, cantidades y datos de material peligroso,
|
||||
**para** cumplir con el nodo Mercancias del complemento Carta Porte 3.1 que exige el SAT para documentar los bienes que se transportan.
|
||||
|
||||
## Descripcion Detallada
|
||||
El nodo Mercancias del complemento Carta Porte 3.1 es uno de los elementos mas criticos del documento. Cada mercancia debe identificarse con la clave del catalogo de bienes transportados del SAT (campo BienesTransp), la clave de unidad de medida (ClaveUnidad), descripcion, cantidad y peso en kilogramos. Errores en estos campos son la causa mas frecuente de rechazo de timbrado.
|
||||
|
||||
Al generar la carta porte desde el viaje (US-MAE016-001), el sistema precarga las mercancias desde las OTs asociadas. Sin embargo, el facturador puede necesitar ajustar los datos para cumplir con los catalogos SAT: asignar la clave BienesTransp correcta, ajustar la ClaveUnidad, especificar si es material peligroso y, en ese caso, completar la clave de material peligroso (CveMaterialPeligroso), tipo de embalaje y descripcion del embalaje.
|
||||
|
||||
Para transporte internacional, las mercancias pueden incluir fraccion arancelaria, UUID de comercio exterior y numeros de pedimento. Para servicios de paqueteria, se soportan numeros de guia. El sistema calcula automaticamente el peso_bruto_total y num_total_mercancias a partir de los registros individuales.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Agregar mercancia con campos obligatorios
|
||||
**Dado** una carta porte en estado BORRADOR
|
||||
**Cuando** el facturador agrega una mercancia con bienes_transp = '31181701' (fertilizantes), descripcion = 'Fertilizante liquido NPK', cantidad = 25000, clave_unidad = 'KGM', peso_en_kg = 25000 y secuencia = 1
|
||||
**Entonces** el sistema crea un registro en `compliance.mercancias_carta_porte` con los datos proporcionados y actualiza peso_bruto_total = 25000 y num_total_mercancias = 1 en la carta porte.
|
||||
|
||||
### Escenario 2: Agregar mercancia con material peligroso
|
||||
**Dado** una carta porte en estado BORRADOR
|
||||
**Cuando** el facturador agrega una mercancia con material_peligroso = true, cve_material_peligroso = '1005' (amoniaco anhidro), tipo_embalaje = '4G' (caja de carton) y descripcion_embalaje = 'Contenedor presurizado'
|
||||
**Entonces** el sistema crea el registro con los campos de material peligroso completos y marca la carta porte para que la validacion (US-MAE016-002) exija seguro de medio ambiente.
|
||||
|
||||
### Escenario 3: Editar mercancia precargada desde OT
|
||||
**Dado** una carta porte en estado BORRADOR con mercancias precargadas automaticamente desde las OTs del viaje, donde una mercancia no tiene la clave bienes_transp
|
||||
**Cuando** el facturador edita la mercancia y asigna bienes_transp = '50201700' (productos quimicos)
|
||||
**Entonces** el sistema actualiza el registro en `compliance.mercancias_carta_porte` con la clave SAT asignada.
|
||||
|
||||
### Escenario 4: Calculo automatico de totales
|
||||
**Dado** una carta porte con 3 mercancias con peso_en_kg de 5000, 3000 y 2000 respectivamente
|
||||
**Cuando** el facturador guarda las mercancias
|
||||
**Entonces** el sistema calcula y actualiza peso_bruto_total = 10000 (KGM) y num_total_mercancias = 3 en la tabla `compliance.cartas_porte`.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Insertar, actualizar y eliminar registros en `compliance.mercancias_carta_porte`; actualizar campos peso_bruto_total y num_total_mercancias en `compliance.cartas_porte`; usar indice `idx_mercancia_carta` para consultas por carta_porte_id
|
||||
- **Backend:** Crear endpoint POST `/api/v1/carta-porte/:id/mercancias` para agregar mercancia; crear endpoint PUT `/api/v1/carta-porte/:id/mercancias/:mercanciaId` para editar; crear endpoint DELETE `/api/v1/carta-porte/:id/mercancias/:mercanciaId` para eliminar; crear `CreateMercanciaDto` y `UpdateMercanciaDto` con validaciones de campos obligatorios; crear servicio `MercanciaCartaPorteService` con logica de calculo de totales; implementar busqueda en catalogo SAT de BienesTransp y ClaveUnidad
|
||||
- **Frontend:** Crear componente `MercanciasCartaPorteTable` con tabla editable que muestre bienes_transp, descripcion, cantidad, clave_unidad, peso_en_kg, material_peligroso; crear dialogo `AgregarMercanciaDialog` con buscador de claves SAT (autocomplete con catalogo BienesTransp); seccion colapsable para datos de material peligroso (visible solo si material_peligroso = true); seccion colapsable para datos de comercio exterior; indicador visual de peso_bruto_total y num_total_mercancias
|
||||
- **Tests:** Test unitario del calculo de peso_bruto_total y num_total_mercancias; test de creacion de mercancia con campos obligatorios; test de creacion con material peligroso; test de edicion de mercancia; test de eliminacion con recalculo de totales; test de validacion de clave bienes_transp contra catalogo SAT
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR)
|
||||
- **Bloquea:** US-MAE016-002 (Validar datos - las mercancias son parte de la validacion obligatoria)
|
||||
|
||||
## Notas Tecnicas
|
||||
- El catalogo BienesTransp del SAT contiene mas de 50,000 claves. Se recomienda implementar busqueda con autocomplete y carga paginada del catalogo.
|
||||
- El catalogo ClaveUnidad del SAT contiene claves como KGM (kilogramo), LTR (litro), H87 (pieza), TNE (tonelada), MTR (metro).
|
||||
- El campo bienes_transp (VARCHAR(10)) almacena la clave de 8 digitos del catalogo SAT.
|
||||
- El campo cve_material_peligroso (VARCHAR(10)) referencia al catalogo de materiales peligrosos de la ONU.
|
||||
- El campo tipo_embalaje (VARCHAR(10)) referencia al catalogo de tipos de embalaje de la ONU.
|
||||
- El campo pedimentos (TEXT[]) almacena numeros de pedimento para comercio exterior en formato: "AA AANNNNNN NNNNNNN N" (21 posiciones).
|
||||
- El campo guias (TEXT[]) almacena numeros de guia para servicios de paqueteria.
|
||||
- El campo secuencia (INT NOT NULL) establece el orden de las mercancias en el XML del complemento.
|
||||
- La suma de peso_en_kg debe coincidir con peso_bruto_total; la unidad de peso por defecto es 'KGM'.
|
||||
@ -0,0 +1,63 @@
|
||||
# US-MAE016-008: Registrar figuras de transporte
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-008 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** coordinador de operaciones,
|
||||
**quiero** registrar las figuras de transporte (operador, propietario, arrendador) en la carta porte con sus datos fiscales y licencia,
|
||||
**para** cumplir con el nodo FiguraTransporte del complemento Carta Porte 3.1 que identifica a las personas involucradas en el traslado de mercancias.
|
||||
|
||||
## Descripcion Detallada
|
||||
El nodo FiguraTransporte del complemento Carta Porte 3.1 es obligatorio e identifica a las personas fisicas o morales que participan en el transporte. El SAT define tres tipos de figura: Operador (tipo '01'), que es el conductor del vehiculo y requiere numero de licencia; Propietario (tipo '02'), que es el dueno del vehiculo o remolque; y Arrendador (tipo '03'), cuando la unidad esta arrendada.
|
||||
|
||||
Al generar la carta porte desde el viaje, el sistema carga automaticamente el operador asignado como figura tipo '01' con su RFC, nombre completo y numero de licencia de conducir. El coordinador puede agregar figuras adicionales (propietario del vehiculo, arrendador) cuando la operacion lo requiere, por ejemplo, cuando la unidad tractora es arrendada o pertenece a un tercero.
|
||||
|
||||
Para cada figura se registra: tipo_figura (01, 02 o 03), rfc_figura, nombre_figura, y para operadores el num_licencia. El domicilio fiscal (pais, estado, codigo_postal, calle) es opcional. Para propietarios y arrendadores se pueden registrar partes de transporte (JSONB) indicando los vehiculos o remolques de su propiedad utilizados en el viaje.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Carga automatica del operador asignado al viaje
|
||||
**Dado** una carta porte en estado BORRADOR generada desde un viaje con operador asignado que tiene RFC = 'GAMA800101ABC', nombre = 'Garcia Martinez Juan' y licencia = 'JGAM800101HDFRGT09'
|
||||
**Cuando** se genera la carta porte
|
||||
**Entonces** el sistema crea automaticamente un registro en `compliance.figuras_transporte` con tipo_figura = '01', rfc_figura = 'GAMA800101ABC', nombre_figura = 'Garcia Martinez Juan', num_licencia = 'JGAM800101HDFRGT09'.
|
||||
|
||||
### Escenario 2: Agregar propietario del vehiculo
|
||||
**Dado** una carta porte en estado BORRADOR donde la unidad tractora pertenece a una persona moral diferente del emisor
|
||||
**Cuando** el coordinador agrega una figura con tipo_figura = '02' (Propietario), rfc_figura = 'TME860101XYZ', nombre_figura = 'Transportes Mexico SA de CV'
|
||||
**Entonces** el sistema crea el registro en `compliance.figuras_transporte` con los datos del propietario y partes_transporte indicando los vehiculos de su propiedad usados en el viaje.
|
||||
|
||||
### Escenario 3: Operador sin numero de licencia
|
||||
**Dado** una carta porte en estado BORRADOR
|
||||
**Cuando** el coordinador intenta agregar una figura tipo '01' (Operador) sin num_licencia
|
||||
**Entonces** el sistema rechaza el registro con el mensaje "El numero de licencia es obligatorio para figuras de transporte tipo Operador (01)".
|
||||
|
||||
### Escenario 4: Eliminar figura de transporte
|
||||
**Dado** una carta porte en estado BORRADOR con un propietario registrado como figura tipo '02'
|
||||
**Cuando** el coordinador elimina la figura de propietario porque la unidad es propia del emisor
|
||||
**Entonces** el sistema elimina el registro de `compliance.figuras_transporte` y actualiza la vista de figuras de transporte.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Insertar, actualizar y eliminar registros en `compliance.figuras_transporte`; usar indice `idx_figura_carta` para consultas por carta_porte_id; el campo partes_transporte (JSONB) almacena array de objetos con clave parte_transporte
|
||||
- **Backend:** Crear endpoint POST `/api/v1/carta-porte/:id/figuras` para agregar figura; crear endpoint PUT `/api/v1/carta-porte/:id/figuras/:figuraId` para editar; crear endpoint DELETE `/api/v1/carta-porte/:id/figuras/:figuraId` para eliminar; crear `CreateFiguraTransporteDto` con validacion condicional (num_licencia obligatorio para tipo '01'); crear servicio `FiguraTransporteService` con logica de carga automatica desde viaje
|
||||
- **Frontend:** Crear componente `FigurasTransportePanel` que muestra lista de figuras con tipo, RFC, nombre, licencia; boton "Agregar Figura" que abre dialogo con selector de tipo_figura (01 Operador, 02 Propietario, 03 Arrendador); campos condicionales segun tipo seleccionado; indicador visual del operador principal (auto-cargado); opcion de editar y eliminar figuras adicionales
|
||||
- **Tests:** Test unitario de carga automatica del operador desde viaje; test de validacion de num_licencia para tipo '01'; test de creacion de propietario con partes_transporte; test de eliminacion de figura; test de integracion del endpoint
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR), MAI-011 (Flota - datos del operador con RFC y licencia)
|
||||
- **Bloquea:** US-MAE016-002 (Validar datos - al menos un operador es obligatorio para la validacion)
|
||||
|
||||
## Notas Tecnicas
|
||||
- Los tipos de figura del catalogo SAT son: '01' (Operador), '02' (Propietario), '03' (Arrendador). Estos valores se validan contra el catalogo oficial c_FiguraTransporte.
|
||||
- El campo num_licencia para operadores corresponde a la licencia federal de conducir emitida por la SCT. El formato varia segun el tipo de licencia.
|
||||
- El campo rfc_figura acepta RFC de persona fisica (13 caracteres) o moral (12 caracteres).
|
||||
- El campo partes_transporte (JSONB) para propietario/arrendador contiene un array con la estructura: `[{"parte_transporte": "PT01"}, {"parte_transporte": "PT02"}]`, donde cada parte identifica un vehiculo o remolque.
|
||||
- El domicilio de la figura es opcional en el complemento Carta Porte 3.1 para autotransporte domestico, pero puede ser obligatorio para transporte internacional.
|
||||
- En la mayoria de operaciones de autotransporte federal, solo se requiere la figura de operador (tipo '01'). Las figuras de propietario y arrendador se usan cuando la unidad no pertenece al emisor del CFDI.
|
||||
@ -0,0 +1,64 @@
|
||||
# US-MAE016-009: Configurar datos autotransporte federal
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-009 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** coordinador de operaciones,
|
||||
**quiero** configurar los datos del autotransporte federal en la carta porte incluyendo permiso SCT, configuracion vehicular, placa del vehiculo, remolques y seguros,
|
||||
**para** cumplir con el nodo Autotransporte del complemento Carta Porte 3.1 que documenta el medio de transporte utilizado.
|
||||
|
||||
## Descripcion Detallada
|
||||
El nodo Autotransporte del complemento Carta Porte 3.1 es obligatorio para el transporte terrestre federal y contiene la informacion del vehiculo y sus permisos. Los datos principales son el tipo de permiso SCT (catalogo c_TipoPermiso del SAT), el numero de permiso, la configuracion vehicular (C2, C3, T3S2, T3S3, etc. del catalogo c_ConfigAutotransporte) y la placa del vehiculo motor. Cuando la unidad lleva remolques, se registran hasta 2 con su subtipo (catalogo c_SubTipoRem) y placa.
|
||||
|
||||
Al generar la carta porte desde el viaje, el sistema precarga automaticamente los datos de la unidad tractora y remolques asignados desde el modulo de gestion de flota (MAI-011): permiso SCT de la empresa, configuracion vehicular de la unidad, placa, anio modelo y datos de los remolques. El coordinador puede ajustar estos datos si es necesario.
|
||||
|
||||
Adicionalmente, esta historia cubre el registro de los seguros obligatorios: seguro de responsabilidad civil (obligatorio para todo autotransporte), seguro de medio ambiente (obligatorio si se transportan materiales peligrosos) y seguro de carga (opcional). Los datos del seguro incluyen nombre de la aseguradora, numero de poliza y prima.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Carga automatica de datos del vehiculo desde flota
|
||||
**Dado** una carta porte en estado BORRADOR generada desde un viaje con unidad tractora asignada (placa = 'ABC-123-A', config_vehicular = 'T3S2', permiso SCT tipo 'TPAF01', num_permiso = '123456') y un remolque (subtipo = 'CTR004', placa = 'REM-456-B')
|
||||
**Cuando** se genera la carta porte
|
||||
**Entonces** el sistema crea un registro en `compliance.autotransporte_carta_porte` con perm_sct = 'TPAF01', num_permiso_sct = '123456', config_vehicular = 'T3S2', placa_vm = 'ABC-123-A' y remolques = '[{"sub_tipo_rem": "CTR004", "placa": "REM-456-B"}]'.
|
||||
|
||||
### Escenario 2: Registrar doble remolque
|
||||
**Dado** una carta porte en estado BORRADOR para un full trailer (configuracion T3S2R4)
|
||||
**Cuando** el coordinador configura la unidad con 2 remolques: remolque 1 (sub_tipo_rem = 'CTR003', placa = 'REM-001-A') y remolque 2 (sub_tipo_rem = 'CTR004', placa = 'REM-002-B')
|
||||
**Entonces** el sistema almacena remolques = '[{"sub_tipo_rem": "CTR003", "placa": "REM-001-A"}, {"sub_tipo_rem": "CTR004", "placa": "REM-002-B"}]' en el campo JSONB.
|
||||
|
||||
### Escenario 3: Registrar seguros obligatorios
|
||||
**Dado** una carta porte en estado BORRADOR
|
||||
**Cuando** el coordinador registra asegura_resp_civil = 'Seguros Atlas SA de CV', poliza_resp_civil = 'POL-RC-2026-001', asegura_carga = 'GNP Seguros', poliza_carga = 'POL-CG-2026-456' y prima_seguro = 45000.00
|
||||
**Entonces** el sistema actualiza los campos de seguros en `compliance.cartas_porte` con los datos proporcionados.
|
||||
|
||||
### Escenario 4: Falta de datos obligatorios de autotransporte
|
||||
**Dado** una carta porte en estado BORRADOR sin registro en `compliance.autotransporte_carta_porte`
|
||||
**Cuando** el facturador intenta validar la carta porte (US-MAE016-002)
|
||||
**Entonces** la validacion retorna errores indicando que perm_sct, num_permiso_sct, config_vehicular y placa_vm son campos obligatorios del nodo Autotransporte.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Insertar y actualizar registros en `compliance.autotransporte_carta_porte`; actualizar campos de seguros (asegura_resp_civil, poliza_resp_civil, asegura_med_ambiente, poliza_med_ambiente, asegura_carga, poliza_carga, prima_seguro) en `compliance.cartas_porte`; usar indice `idx_autotransporte_carta` para consultas por carta_porte_id
|
||||
- **Backend:** Crear endpoint POST `/api/v1/carta-porte/:id/autotransporte` para registrar datos del vehiculo; crear endpoint PUT `/api/v1/carta-porte/:id/autotransporte/:autoId` para editar; crear `CreateAutotransporteDto` con validaciones (perm_sct, num_permiso_sct, config_vehicular, placa_vm obligatorios); crear `UpdateSegurosDto` para actualizar datos de seguros; crear servicio `AutotransporteCartaPorteService` con logica de carga automatica desde flota; implementar busqueda en catalogos SAT de c_TipoPermiso, c_ConfigAutotransporte, c_SubTipoRem
|
||||
- **Frontend:** Crear componente `AutotransportePanel` con formulario de datos del vehiculo: selector de tipo permiso SCT (autocomplete con catalogo SAT), campo num_permiso_sct, selector de config_vehicular (autocomplete), campo placa_vm, campo anio_modelo_vm; crear seccion de remolques con tabla editable (hasta 2 filas) con selector de sub_tipo_rem y campo placa; crear seccion de seguros con campos para responsabilidad civil (obligatorio), medio ambiente (condicional a material peligroso) y carga (opcional)
|
||||
- **Tests:** Test unitario de carga automatica desde datos de flota; test de registro de autotransporte con 0, 1 y 2 remolques; test de validacion de campos obligatorios; test de registro de seguros; test de actualizacion de datos existentes; test de catalogo de configuraciones vehiculares
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR), MAI-011 (Flota - datos de unidad, remolques, permisos SCT)
|
||||
- **Bloquea:** US-MAE016-002 (Validar datos - autotransporte es obligatorio para la validacion)
|
||||
|
||||
## Notas Tecnicas
|
||||
- El catalogo c_TipoPermiso del SAT incluye: TPAF01 (Autotransporte Federal de carga general), TPAF02 (Transporte privado de carga), TPAF03 (Autotransporte Federal de Carga Especializada), entre otros.
|
||||
- El catalogo c_ConfigAutotransporte incluye configuraciones como: C2 (camion unitario 2 ejes), C3 (camion unitario 3 ejes), T3S2 (tractocamion 3 ejes - semiremolque 2 ejes), T3S3 (tractocamion 3 ejes - semiremolque 3 ejes), T3S2R4 (tractocamion con semiremolque y remolque).
|
||||
- El catalogo c_SubTipoRem incluye subtipos como: CTR001 (semiremolque), CTR002 (semiremolque con eje de arrastre), CTR003 (remolque), CTR004 (semiremolque chasis portacontenedor).
|
||||
- El campo remolques (JSONB) almacena hasta 2 remolques. La estructura es: `[{"sub_tipo_rem": "string", "placa": "string"}]`.
|
||||
- La placa del vehiculo motor (placa_vm) se valida con formato alfanumerico (hasta 15 caracteres, no se valida formato especifico por entidad federativa).
|
||||
- Los datos del seguro de responsabilidad civil son obligatorios para autotransporte federal. Los datos del seguro de medio ambiente son obligatorios solo cuando alguna mercancia tiene material_peligroso = true.
|
||||
- El anio_modelo_vm es opcional en el complemento pero util para validaciones internas del sistema (vehiculos con mas de cierta antiguedad pueden requerir revision adicional).
|
||||
@ -0,0 +1,64 @@
|
||||
# US-MAE016-010: Generar reporte fiscal mensual
|
||||
|
||||
## Metadata
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAE016-010 |
|
||||
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
|
||||
| **Modulo** | carta-porte |
|
||||
| **Prioridad** | P2 |
|
||||
| **Story Points** | 3 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
**Como** contador,
|
||||
**quiero** generar un reporte fiscal mensual de todos los CFDI con complemento Carta Porte emitidos y cancelados en un periodo,
|
||||
**para** conciliar la informacion fiscal, preparar declaraciones y tener un consolidado listo para auditorias del SAT.
|
||||
|
||||
## Descripcion Detallada
|
||||
Al cierre de cada periodo contable (mensual o personalizado), el contador necesita un consolidado de todos los CFDI con complemento Carta Porte que se emitieron y cancelaron. Este reporte es esencial para la conciliacion fiscal, la preparacion de declaraciones y la respuesta a requerimientos de informacion del SAT.
|
||||
|
||||
El reporte lista cada CFDI con sus datos principales: UUID, serie, folio, tipo de CFDI (Ingreso o Traslado), RFC del receptor, fecha de timbrado, subtotal, total, estado (TIMBRADA o CANCELADA) y motivo de cancelacion cuando aplica. El reporte agrupa los resultados por tipo de CFDI y estado, mostrando subtotales y totales generales. Esto permite al contador verificar rapidamente cuantos CFDI se emitieron por tipo, cuantos se cancelaron y los montos acumulados.
|
||||
|
||||
El reporte se puede exportar en formato Excel (XLSX) para manipulacion en hojas de calculo y en formato PDF para archivo formal. Los filtros permiten acotar por tipo_cfdi, estado, rango de fechas, RFC del receptor y serie, dando flexibilidad para generar reportes especificos segun la necesidad.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
### Escenario 1: Reporte mensual con CFDI vigentes y cancelados
|
||||
**Dado** un tenant que en enero 2026 emitio 45 cartas porte de Ingreso (40 timbradas, 5 canceladas) y 10 de Traslado (todas timbradas)
|
||||
**Cuando** el contador genera el reporte fiscal para enero 2026
|
||||
**Entonces** el sistema muestra un listado con 55 registros, agrupado en secciones: "CFDI Ingreso - Timbradas (40): Total $X", "CFDI Ingreso - Canceladas (5): Total $Y", "CFDI Traslado - Timbradas (10): Total $0", con totales generales al final.
|
||||
|
||||
### Escenario 2: Exportar reporte a Excel
|
||||
**Dado** un reporte fiscal generado con datos del periodo
|
||||
**Cuando** el contador selecciona la opcion "Exportar a Excel"
|
||||
**Entonces** el sistema genera un archivo XLSX con columnas: UUID, Serie, Folio, Tipo CFDI, RFC Receptor, Nombre Receptor, Fecha Timbrado, Subtotal, Total, Estado, Motivo Cancelacion, y una hoja de resumen con totales por tipo y estado.
|
||||
|
||||
### Escenario 3: Filtro por tipo de CFDI
|
||||
**Dado** que el contador necesita solo los CFDI de Ingreso del periodo
|
||||
**Cuando** aplica el filtro tipo_cfdi = 'INGRESO' y rango de fechas del mes
|
||||
**Entonces** el sistema muestra unicamente las cartas porte de tipo Ingreso, excluyendo los de Traslado.
|
||||
|
||||
### Escenario 4: Periodo sin CFDI emitidos
|
||||
**Dado** un tenant que no emitio ningun CFDI con Carta Porte en el periodo seleccionado
|
||||
**Cuando** el contador genera el reporte
|
||||
**Entonces** el sistema muestra un mensaje "No se encontraron CFDI con complemento Carta Porte en el periodo seleccionado" y no genera archivo de exportacion.
|
||||
|
||||
## Tareas Tecnicas
|
||||
- **Database:** Consultar `compliance.cartas_porte` con filtros por tenant_id, estado, tipo_cfdi, rango de fecha_timbrado y fecha_cancelacion; agregaciones por tipo_cfdi y estado para subtotales; usar indices `idx_carta_porte_tenant` e `idx_carta_porte_estado` para rendimiento
|
||||
- **Backend:** Crear endpoint GET `/api/v1/carta-porte/reporte-fiscal` con query params: fecha_desde, fecha_hasta, tipo_cfdi, estado, rfc_receptor, serie, formato (json, xlsx, pdf); crear `ReporteFiscalService` con logica de agrupacion y totalizacion; crear `ReporteFiscalResponseDto` con arrays de registros y objeto de resumen; implementar generacion de XLSX con libreria (ExcelJS) y PDF (PDFKit/Puppeteer)
|
||||
- **Frontend:** Crear vista `ReporteFiscalPage` con filtros: selector de periodo (mes/anio o rango personalizado), tipo CFDI (dropdown), estado (dropdown), RFC receptor (texto), serie (texto); tabla de resultados con columnas del reporte; seccion de resumen con totales por tipo y estado en tarjetas visuales; botones "Exportar Excel" y "Exportar PDF"
|
||||
- **Tests:** Test unitario del servicio de agrupacion y totalizacion; test con periodo con datos mixtos (timbrados y cancelados); test con periodo sin datos; test de generacion de XLSX con estructura correcta; test de filtros individuales y combinados
|
||||
|
||||
## Dependencias
|
||||
- **Depende de:** US-MAE016-003 (Timbrar CFDI - los datos del reporte provienen de cartas porte timbradas y canceladas)
|
||||
- **Bloquea:** MAE-018 (Reportes y KPIs - este reporte se integra en el dashboard de KPIs fiscales)
|
||||
|
||||
## Notas Tecnicas
|
||||
- El reporte consulta cartas porte con estado TIMBRADA y CANCELADA. Los estados BORRADOR y VALIDADA no se incluyen porque no son documentos fiscales emitidos.
|
||||
- Para CFDI cancelados, se incluye la fecha de cancelacion (no la fecha de timbrado original) cuando se filtra por periodo de cancelacion.
|
||||
- El campo fecha_timbrado se usa como fecha principal para el periodo del reporte. Si se requiere tambien por fecha_cancelacion, se ofrece un toggle de "Periodo por fecha de timbrado / fecha de cancelacion".
|
||||
- El XLSX incluye dos hojas: "Detalle" con todos los registros y "Resumen" con totales agrupados.
|
||||
- El PDF incluye encabezado con datos del tenant (RFC, razon social), periodo del reporte y pie de pagina con fecha de generacion.
|
||||
- Para tenants con alto volumen de CFDI (cientos por mes), el reporte debe soportar paginacion en la vista web y generacion completa en la exportacion.
|
||||
- Los montos se muestran en la moneda original (MXN por defecto) con 2 decimales.
|
||||
73
docs/02-definicion-modulos/MAE-017-hos-bitacora/README.md
Normal file
73
docs/02-definicion-modulos/MAE-017-hos-bitacora/README.md
Normal file
@ -0,0 +1,73 @@
|
||||
# MAE-017: HOS y Bitacora
|
||||
|
||||
**Modulo:** MAE-017
|
||||
**Nombre:** Horas de Servicio (HOS) y Bitacora
|
||||
**Prioridad:** P3
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Modulo para control de cumplimiento de horas de servicio de operadores segun NOM-087. Registra tiempos de conduccion, descansos y genera bitacora para inspeccion.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Registrar horas de conduccion y descanso
|
||||
2. Alertar antes de exceder limites legales
|
||||
3. Generar bitacora en formato oficial
|
||||
4. Bloquear asignacion si no cumple descanso
|
||||
5. Mantener evidencia auditable
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Operador | Registra tiempos |
|
||||
| Despachador | Verifica cumplimiento |
|
||||
| Jefe de Flota | Supervisa y audita |
|
||||
| Inspector (externo) | Consulta bitacora |
|
||||
|
||||
---
|
||||
|
||||
## Marco Normativo
|
||||
|
||||
**NOM-087-SCT-2-2017:**
|
||||
- Maximo 14 horas de servicio por periodo
|
||||
- Maximo 11 horas de conduccion efectiva
|
||||
- Minimo 10 horas de descanso entre periodos
|
||||
- Pausas cada 5 horas de conduccion
|
||||
- Bitacora obligatoria
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Depende de | Para |
|
||||
|------------|------|
|
||||
| MAI-011 (Flota) | Datos de operadores |
|
||||
| MAI-006 (Tracking) | Datos de telematica |
|
||||
| MAI-005 (Despacho) | Bloqueo de asignacion |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAE-017-hos-bitacora/
|
||||
├── README.md <- Este archivo
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAE017-001.md <- Registrar tiempos HOS
|
||||
├── US-MAE017-002.md <- Alertas de cumplimiento
|
||||
└── US-MAE017-003.md <- Generar bitacora
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAE-017 HOS y Bitacora - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,170 @@
|
||||
# REQUERIMIENTOS - MAE-017: HOS y Bitacora
|
||||
|
||||
**Modulo:** MAE-017
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 5.2
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-5.2.1: Registro HOS
|
||||
|
||||
**Descripcion:** Capturar horas de conduccion, pausas y descanso.
|
||||
|
||||
**Metodos de registro:**
|
||||
| Metodo | Descripcion | Precision |
|
||||
|--------|-------------|-----------|
|
||||
| Manual | Operador ingresa en app | Baja |
|
||||
| Telematica | ECU reporta automatico | Alta |
|
||||
| Hibrido | Telematica + confirmacion | Alta |
|
||||
|
||||
**Eventos a registrar:**
|
||||
| Evento | Codigo | Descripcion |
|
||||
|--------|--------|-------------|
|
||||
| ON_DUTY | D | En servicio (no conduciendo) |
|
||||
| DRIVING | DR | Conduciendo |
|
||||
| OFF_DUTY | OFF | Fuera de servicio |
|
||||
| SLEEPER | SB | En litera |
|
||||
| BREAK | BR | Pausa |
|
||||
|
||||
**Datos por evento:**
|
||||
- Operador
|
||||
- Fecha/hora inicio
|
||||
- Fecha/hora fin
|
||||
- Duracion
|
||||
- Ubicacion (inicio/fin)
|
||||
- Viaje relacionado (opcional)
|
||||
|
||||
**Tablas DDL:**
|
||||
- `compliance.registros_hos`
|
||||
- `compliance.eventos_operador`
|
||||
|
||||
---
|
||||
|
||||
### RF-5.2.2: Bitacora Imprimible
|
||||
|
||||
**Descripcion:** Generar bitacora en formato oficial para inspeccion.
|
||||
|
||||
**Formato requerido:**
|
||||
- Nombre del operador y licencia
|
||||
- Empresa transportista
|
||||
- Unidad y placas
|
||||
- Grafico de 24 horas con franjas
|
||||
- Totales por tipo de evento
|
||||
- Firma del operador
|
||||
- Observaciones
|
||||
|
||||
**Periodos:**
|
||||
- Bitacora diaria (24 horas)
|
||||
- Bitacora por viaje
|
||||
- Resumen semanal
|
||||
|
||||
**Salida:**
|
||||
- PDF para impresion
|
||||
- Vista en pantalla
|
||||
- Exportar a Excel
|
||||
|
||||
**Tablas DDL:**
|
||||
- Vista: `compliance.bitacora_hos_diaria`
|
||||
|
||||
---
|
||||
|
||||
### RF-5.2.3: Alertas de Incumplimiento
|
||||
|
||||
**Descripcion:** Alertar antes de exceder limites legales.
|
||||
|
||||
**Limites NOM-087:**
|
||||
| Limite | Valor | Alerta al |
|
||||
|--------|-------|-----------|
|
||||
| Servicio maximo | 14 horas | 80% (11.2h) |
|
||||
| Conduccion maxima | 11 horas | 80% (8.8h) |
|
||||
| Conduccion continua | 5 horas | 80% (4h) |
|
||||
| Descanso minimo | 10 horas | Si no cumple |
|
||||
|
||||
**Tipos de alerta:**
|
||||
| Nivel | Descripcion | Accion |
|
||||
|-------|-------------|--------|
|
||||
| ADVERTENCIA | Proximo al limite | Notificar operador |
|
||||
| CRITICA | Excedio limite | Notificar supervisor |
|
||||
| BLOQUEO | No cumplio descanso | No asignar viaje |
|
||||
|
||||
**Notificaciones:**
|
||||
- Push a app operador
|
||||
- Email a supervisor
|
||||
- Alerta en sistema despacho
|
||||
|
||||
**Tablas DDL:**
|
||||
- `compliance.alertas_hos`
|
||||
|
||||
---
|
||||
|
||||
### RF-5.2.4: Auditoria y Evidencias
|
||||
|
||||
**Descripcion:** Mantener trazabilidad de ediciones y responsables.
|
||||
|
||||
**Registros de auditoria:**
|
||||
- Cambios manuales (quien, cuando, motivo)
|
||||
- Ediciones de tiempos
|
||||
- Correcciones
|
||||
- Aprobaciones de supervisor
|
||||
|
||||
**Evidencias:**
|
||||
- Datos de telematica (respaldo)
|
||||
- Firmas digitales
|
||||
- Timestamps de sistema
|
||||
|
||||
**Retencion:**
|
||||
- Minimo 1 ano de historial
|
||||
- Exportable para auditoria externa
|
||||
|
||||
**Tablas DDL:**
|
||||
- `compliance.auditoria_hos`
|
||||
- `compliance.firmas_bitacora`
|
||||
|
||||
---
|
||||
|
||||
## Limites NOM-087 (Referencia)
|
||||
|
||||
```
|
||||
PERIODO DE 24 HORAS
|
||||
├── Servicio maximo: 14 horas
|
||||
│ ├── Conduccion: max 11 horas
|
||||
│ ├── En servicio (no conduciendo): resto
|
||||
│ └── Pausas: obligatorias cada 5h conduccion
|
||||
│
|
||||
└── Descanso obligatorio: min 10 horas
|
||||
├── Puede ser consecutivo
|
||||
└── O en 2 bloques (7h + 3h)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Precision
|
||||
- Telematica: precision ±1 minuto
|
||||
- Manual: validar coherencia
|
||||
|
||||
### RNF-002: Disponibilidad Offline
|
||||
- App permite registro sin conexion
|
||||
- Sincroniza al recuperar red
|
||||
|
||||
### RNF-003: Integracion Telematica
|
||||
- Soportar protocolos ELD comunes
|
||||
- API para proveedores GPS
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tablas DDL | Endpoints | Historias |
|
||||
|----|------------|-----------|-----------|
|
||||
| RF-5.2.1 | registros_hos | POST /hos | US-MAE017-001 |
|
||||
| RF-5.2.2 | bitacora_diaria | GET /bitacora | US-MAE017-003 |
|
||||
| RF-5.2.3 | alertas_hos | GET /alertas | US-MAE017-002 |
|
||||
| RF-5.2.4 | auditoria_hos | GET /auditoria | US-MAE017-003 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAE-017 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,78 @@
|
||||
# RESUMEN EPICA - MAE-017: HOS y Bitacora
|
||||
|
||||
**Modulo:** MAE-017
|
||||
**Prioridad:** P3
|
||||
**Story Points Total:** 16
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- Incumplimiento de horas de servicio (multas)
|
||||
- Bitacoras manuales con errores
|
||||
- No hay visibilidad de fatiga de operadores
|
||||
- Riesgo de accidentes por exceso de horas
|
||||
|
||||
### Beneficios
|
||||
- **Cumplimiento normativo** NOM-087
|
||||
- **Seguridad** al prevenir fatiga
|
||||
- **Bitacora digital** para inspeccion
|
||||
- **Evidencia auditable** ante SCT
|
||||
|
||||
### KPIs Impactados
|
||||
- Cumplimiento HOS
|
||||
- Multas evitadas
|
||||
- Incidentes por fatiga
|
||||
- Tiempo de generacion bitacora
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Registro de eventos HOS
|
||||
- Alertas de limite
|
||||
- Generacion de bitacora
|
||||
- Auditoria de cambios
|
||||
- Bloqueo de asignacion
|
||||
|
||||
### Excluido
|
||||
- ELD certificado (fase posterior)
|
||||
- Integracion con todas las marcas GPS
|
||||
- Bitacora electronica SCT (pendiente norma)
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAE017-001 | Registrar tiempos HOS | 5 |
|
||||
| US-MAE017-002 | Alertas de cumplimiento | 5 |
|
||||
| US-MAE017-003 | Generar bitacora imprimible | 6 |
|
||||
| **Total** | | **16** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
MAI-011 (Flota) ───┐
|
||||
MAI-006 (Tracking)─┼──> MAE-017 ──> MAI-005 (Despacho)
|
||||
│
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Datos telematica inexactos | Validacion + correccion manual |
|
||||
| Resistencia de operadores | Capacitacion + incentivos |
|
||||
| Cambios normativos | Parametrizacion de limites |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAE-017 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,167 @@
|
||||
# US-MAE017-001: Registrar tiempos HOS
|
||||
|
||||
**ID:** US-MAE017-001
|
||||
**Modulo:** MAE-017 (HOS y Bitacora)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** operador
|
||||
**Quiero** registrar mis tiempos de conduccion y descanso
|
||||
**Para** cumplir con la normativa NOM-087 y tener mi bitacora al dia
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Registrar inicio de conduccion
|
||||
**Dado** que voy a empezar a manejar
|
||||
**Cuando** cambio mi estado a CONDUCIENDO
|
||||
**Entonces** se registra hora y ubicacion de inicio
|
||||
|
||||
### CA-002: Registrar pausa
|
||||
**Dado** que hago una pausa (comida, descanso)
|
||||
**Cuando** cambio estado a PAUSA
|
||||
**Entonces** se registra la pausa con duracion
|
||||
|
||||
### CA-003: Registrar fin de jornada
|
||||
**Dado** que termine mi servicio del dia
|
||||
**Cuando** cambio a FUERA_DE_SERVICIO
|
||||
**Entonces** se cierra el periodo y calcula totales
|
||||
|
||||
### CA-004: Ver mis horas del dia
|
||||
**Dado** que quiero saber cuanto llevo
|
||||
**Cuando** consulto mi dashboard
|
||||
**Entonces** veo horas conducidas, en servicio y disponibles
|
||||
|
||||
### CA-005: Editar con justificacion
|
||||
**Dado** que olvide registrar un evento
|
||||
**Cuando** lo edito posteriormente
|
||||
**Entonces** debo ingresar motivo y queda auditado
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### App Operador - HOS
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| HOS - Juan Perez Garcia |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Estado actual: CONDUCIENDO |
|
||||
| Desde: 06:00 (hace 4h 30m) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| HOY - 27 enero 2026 |
|
||||
| |
|
||||
| +----------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Conduccion ████████████░░░░░░░░░ 4.5h / 11h | |
|
||||
| | En servicio ████████████░░░░░░░░░ 4.5h / 14h | |
|
||||
| | Disponible ░░░░░░░░░░░░░░░░░░░░░ 6.5h | |
|
||||
| | | |
|
||||
| +----------------------------------------------------+ |
|
||||
| |
|
||||
| [!] Proximo limite: 30 min para pausa obligatoria |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CAMBIAR ESTADO |
|
||||
| |
|
||||
| +------------+ +------------+ +------------+ |
|
||||
| | | | | | | |
|
||||
| | CONDUCIENDO| | PAUSA | | EN SERV. | |
|
||||
| | (activo) | | | | (no cond.) | |
|
||||
| +------------+ +------------+ +------------+ |
|
||||
| |
|
||||
| +------------+ +------------+ |
|
||||
| | | | | |
|
||||
| | DESCANSO | | FUERA SERV.| |
|
||||
| | (litera) | | | |
|
||||
| +------------+ +------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EVENTOS DE HOY |
|
||||
| |
|
||||
| 06:00 CONDUCIENDO Inicio en CDMX |
|
||||
| 08:30 PAUSA 30 min - Desayuno |
|
||||
| 09:00 CONDUCIENDO Continua |
|
||||
| 10:30 Ahora En transito |
|
||||
| |
|
||||
| [Ver bitacora completa] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Cambiar Estado
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| CAMBIAR A: PAUSA X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Estado actual: CONDUCIENDO (desde 09:00) |
|
||||
| Horas conduccion hoy: 4.5h |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| NUEVO ESTADO |
|
||||
| |
|
||||
| Tipo de pausa: |
|
||||
| (o) Pausa corta (comida, sanitario) |
|
||||
| ( ) Pausa larga (descanso) |
|
||||
| ( ) Fin de conduccion (continuo en servicio) |
|
||||
| |
|
||||
| Ubicacion: [Detectada por GPS] |
|
||||
| Gasolinera PEMEX - Km 180 Carretera 57 |
|
||||
| |
|
||||
| Notas (opcional): |
|
||||
| [Pausa para comer ]|
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Cancelar] [Confirmar Cambio] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Estado HOS
|
||||
|
||||
| Estado | Codigo | Cuenta como |
|
||||
|--------|--------|-------------|
|
||||
| CONDUCIENDO | DR | Conduccion + Servicio |
|
||||
| EN_SERVICIO | D | Servicio (no conduccion) |
|
||||
| PAUSA | BR | Pausa (no suma) |
|
||||
| DESCANSO_LITERA | SB | Descanso |
|
||||
| FUERA_DE_SERVICIO | OFF | Descanso |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `compliance.registros_hos`
|
||||
- Tabla: `compliance.eventos_operador`
|
||||
- GPS automatico al cambiar estado
|
||||
- Sincronizacion offline
|
||||
- Integracion con telematica (opcional)
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Registro de cambio de estado
|
||||
- [ ] Captura GPS automatica
|
||||
- [ ] Calculo de totales en tiempo real
|
||||
- [ ] Visualizacion de horas disponibles
|
||||
- [ ] Edicion con justificacion
|
||||
- [ ] Soporte offline
|
||||
- [ ] Tests de registro y calculo
|
||||
@ -0,0 +1,154 @@
|
||||
# US-MAE017-002: Alertas de cumplimiento HOS
|
||||
|
||||
**ID:** US-MAE017-002
|
||||
**Modulo:** MAE-017 (HOS y Bitacora)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador
|
||||
**Quiero** recibir alertas cuando operadores estan cerca de exceder limites
|
||||
**Para** prevenir incumplimientos y asignar relevos si es necesario
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Alerta de limite proximo
|
||||
**Dado** que un operador esta al 80% de su limite
|
||||
**Cuando** se detecta
|
||||
**Entonces** se envia alerta a operador y despachador
|
||||
|
||||
### CA-002: Alerta de exceso
|
||||
**Dado** que un operador excedio un limite
|
||||
**Cuando** se detecta
|
||||
**Entonces** se genera alerta critica al supervisor
|
||||
|
||||
### CA-003: Bloquear asignacion
|
||||
**Dado** que un operador no cumplio descanso minimo
|
||||
**Cuando** intento asignarlo a un viaje
|
||||
**Entonces** el sistema bloquea la asignacion
|
||||
|
||||
### CA-004: Dashboard de cumplimiento
|
||||
**Dado** que necesito ver estado de todos los operadores
|
||||
**Cuando** consulto el dashboard
|
||||
**Entonces** veo semaforo de cumplimiento por operador
|
||||
|
||||
### CA-005: Historial de alertas
|
||||
**Dado** que quiero analizar patrones
|
||||
**Cuando** consulto historial
|
||||
**Entonces** veo alertas pasadas por operador/periodo
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Dashboard de Cumplimiento HOS
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| CUMPLIMIENTO HOS - Operadores Activos |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Fecha: 27-ene-2026 Operadores en servicio: 18 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESUMEN |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | OK (14) | | Atencion(3) | | Critico(1) | |
|
||||
| | 78% | | 17% | | 5% | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| OPERADORES CON ALERTAS |
|
||||
| |
|
||||
| | Operador | Estado | Conduccion | Alerta ||
|
||||
| |---------------|-------------|------------|----------||
|
||||
| | Juan Perez | Conduciendo | 8.5h | [!] 80% ||
|
||||
| | Pedro Ramirez | Conduciendo | 9.2h | [!] 84% ||
|
||||
| | Ana Lopez | En servicio | 12.0h | [!] 86% ||
|
||||
| | Luis Garcia | Conduciendo | 11.5h | [!!] Exc ||
|
||||
| |
|
||||
| [!!] Luis Garcia EXCEDIO limite de conduccion (11h) |
|
||||
| Accion requerida: Parar y descansar |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| OPERADORES NO ASIGNABLES |
|
||||
| |
|
||||
| | Operador | Motivo | Disponible ||
|
||||
| |----------------|---------------------|-------------||
|
||||
| | Carlos Mendez | Descanso incompleto | En 3h ||
|
||||
| | Maria Gonzalez | En descanso | En 6h ||
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Alerta en App Operador
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| [!] ALERTA HOS |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| |
|
||||
| /!\ LIMITE DE CONDUCCION PROXIMO |
|
||||
| |
|
||||
| |
|
||||
| Has conducido 8.5 horas de 11 permitidas. |
|
||||
| |
|
||||
| Tiempo restante: 2.5 horas |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RECOMENDACION |
|
||||
| |
|
||||
| Planea tu parada de descanso pronto. |
|
||||
| Si no puedes completar el viaje, notifica |
|
||||
| al despachador para coordinar relevo. |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Entendido] [Solicitar Relevo] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Alertas
|
||||
|
||||
| Limite | Umbral Alerta | Umbral Critico | Accion |
|
||||
|--------|---------------|----------------|--------|
|
||||
| Conduccion 11h | 8.8h (80%) | 11h | Notificar/Bloquear |
|
||||
| Servicio 14h | 11.2h (80%) | 14h | Notificar/Bloquear |
|
||||
| Conduccion continua 5h | 4h (80%) | 5h | Notificar pausa |
|
||||
| Descanso min 10h | Si < 10h | - | Bloquear asignacion |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `compliance.alertas_hos`
|
||||
- Job: `check-hos-limits.job.ts` (cada 15 min)
|
||||
- Push notifications a app operador
|
||||
- Email a supervisor si critico
|
||||
- Flag en `fleet.operadores.disponible_hos`
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Calculo de limites en tiempo real
|
||||
- [ ] Alertas al 80% del limite
|
||||
- [ ] Alertas criticas al exceder
|
||||
- [ ] Bloqueo de asignacion
|
||||
- [ ] Dashboard de cumplimiento
|
||||
- [ ] Notificaciones push/email
|
||||
- [ ] Tests de alertas y bloqueos
|
||||
@ -0,0 +1,181 @@
|
||||
# US-MAE017-003: Generar bitacora imprimible
|
||||
|
||||
**ID:** US-MAE017-003
|
||||
**Modulo:** MAE-017 (HOS y Bitacora)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 6
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** jefe de flota
|
||||
**Quiero** generar bitacoras en formato oficial
|
||||
**Para** cumplir con la normativa y tenerlas listas para inspeccion
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Generar bitacora diaria
|
||||
**Dado** que necesito la bitacora de un operador
|
||||
**Cuando** selecciono fecha y operador
|
||||
**Entonces** se genera bitacora con grafico de 24 horas
|
||||
|
||||
### CA-002: Incluir datos requeridos
|
||||
**Dado** que la bitacora tiene formato oficial
|
||||
**Cuando** la genero
|
||||
**Entonces** incluye nombre, licencia, empresa, unidad, totales
|
||||
|
||||
### CA-003: Grafico de franjas
|
||||
**Dado** que la norma requiere representacion grafica
|
||||
**Cuando** veo la bitacora
|
||||
**Entonces** muestra barras por hora con tipo de actividad
|
||||
|
||||
### CA-004: Firmar digitalmente
|
||||
**Dado** que el operador debe firmar
|
||||
**Cuando** genera su bitacora
|
||||
**Entonces** puede firmar digitalmente desde la app
|
||||
|
||||
### CA-005: Exportar PDF
|
||||
**Dado** que necesito imprimirla o compartirla
|
||||
**Cuando** la descargo
|
||||
**Entonces** se genera PDF en formato oficial
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Bitacora de Horas de Servicio
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| BITACORA DE HORAS DE SERVICIO |
|
||||
| (NOM-087-SCT-2-2017) |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| DATOS DEL OPERADOR |
|
||||
| Nombre: Juan Perez Garcia |
|
||||
| Licencia Federal: E1234567 |
|
||||
| No. Empleado: OP-0025 |
|
||||
| |
|
||||
| DATOS DE LA EMPRESA |
|
||||
| Empresa: Transportes ABC SA de CV |
|
||||
| RFC: TAB990101AB1 |
|
||||
| Permiso SCT: 123456 |
|
||||
| |
|
||||
| DATOS DEL VEHICULO |
|
||||
| Unidad: T-1025 |
|
||||
| Placas: ABC-12-34 |
|
||||
| Tipo: Tracto-camion |
|
||||
| |
|
||||
| FECHA: 27 de enero de 2026 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| GRAFICO DE ACTIVIDAD (24 HORAS) |
|
||||
| |
|
||||
| 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16... |
|
||||
| |__|__|__|__|__|__|__|__|__|__|__|__|__|__|__|__|__ |
|
||||
| |
|
||||
| OFF ████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
|
||||
| ▲ |
|
||||
| SB ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
|
||||
| |
|
||||
| D ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
|
||||
| |
|
||||
| DR ░░░░░░░░░░░░░░░░██████████░░██████████████░░░░ |
|
||||
| 06:00-08:30 09:00-16:00 |
|
||||
| |
|
||||
| LEYENDA: |
|
||||
| OFF = Fuera de servicio | SB = Litera |
|
||||
| D = En servicio | DR = Conduciendo |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESUMEN DE HORAS |
|
||||
| |
|
||||
| | Tipo de actividad | Horas | Limite | |
|
||||
| |------------------------|----------|---------| |
|
||||
| | Fuera de servicio (OFF)| 6.0 h | - | |
|
||||
| | Litera (SB) | 0.0 h | - | |
|
||||
| | En servicio (D) | 0.5 h | - | |
|
||||
| | Conduccion (DR) | 9.5 h | 11.0 h | |
|
||||
| |------------------------|----------|---------| |
|
||||
| | TOTAL EN SERVICIO | 10.0 h | 14.0 h | |
|
||||
| | TOTAL CONDUCCION | 9.5 h | 11.0 h | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| OBSERVACIONES |
|
||||
| Pausa de 30 min en km 180 para desayuno. |
|
||||
| Sin novedades. |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| FIRMA DEL OPERADOR |
|
||||
| |
|
||||
| [Firma digital] |
|
||||
| Juan Perez Garcia |
|
||||
| Fecha firma: 27-ene-2026 18:00 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| Generado por: ERP Transportistas |
|
||||
| Fecha generacion: 27-ene-2026 18:05 |
|
||||
| Folio: BIT-2026-01-27-OP0025 |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Seleccion de Bitacora
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| GENERAR BITACORA X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Operador: [Juan Perez Garcia v] |
|
||||
| |
|
||||
| Tipo de bitacora: |
|
||||
| (o) Bitacora diaria |
|
||||
| ( ) Bitacora por viaje |
|
||||
| ( ) Resumen semanal |
|
||||
| |
|
||||
| Fecha: [27-ene-2026] |
|
||||
| |
|
||||
| Incluir: |
|
||||
| [x] Grafico de 24 horas |
|
||||
| [x] Resumen de totales |
|
||||
| [x] Observaciones |
|
||||
| [ ] Detalle de eventos |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Vista previa] [Generar PDF] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Vista: `compliance.bitacora_hos_diaria`
|
||||
- Generacion PDF con Puppeteer/PDFKit
|
||||
- Firma digital con canvas
|
||||
- Almacenamiento de bitacoras firmadas
|
||||
- Formato segun anexo NOM-087
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Generacion de bitacora diaria
|
||||
- [ ] Grafico de franjas por hora
|
||||
- [ ] Datos de operador, empresa, unidad
|
||||
- [ ] Calculo de totales
|
||||
- [ ] Firma digital del operador
|
||||
- [ ] Exportacion a PDF
|
||||
- [ ] Almacenamiento de bitacoras firmadas
|
||||
- [ ] Tests de generacion y formato
|
||||
65
docs/02-definicion-modulos/MAE-018-reportes-kpis/README.md
Normal file
65
docs/02-definicion-modulos/MAE-018-reportes-kpis/README.md
Normal file
@ -0,0 +1,65 @@
|
||||
# MAE-018: Reportes y KPIs
|
||||
|
||||
**Modulo:** MAE-018
|
||||
**Nombre:** Reportes y KPIs del Transporte
|
||||
**Prioridad:** P3
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Modulo de reporteria y KPIs especializados del giro transporte. Proporciona metricas operativas, financieras y de cumplimiento para toma de decisiones.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Medir desempeno operativo (OTIF, tiempos)
|
||||
2. Controlar costos y rentabilidad
|
||||
3. Monitorear disponibilidad de flota
|
||||
4. Evaluar cumplimiento normativo
|
||||
5. Dashboards para diferentes roles
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Director General | KPIs ejecutivos |
|
||||
| Jefe de Operaciones | Metricas operativas |
|
||||
| Jefe de Flota | Disponibilidad y mantenimiento |
|
||||
| Controller | Rentabilidad y costos |
|
||||
|
||||
---
|
||||
|
||||
## KPIs del Giro
|
||||
|
||||
| Categoria | KPIs |
|
||||
|-----------|------|
|
||||
| Operativo | OTIF, On-time pickup/delivery |
|
||||
| Costos | Costo/km, Costo/viaje, Margen |
|
||||
| Flota | Disponibilidad, MTBF, MTTR |
|
||||
| Combustible | km/litro, Costo combustible |
|
||||
| Incidencias | Incidencias/100 viajes |
|
||||
| Carriers | Scorecard promedio |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAE-018-reportes-kpis/
|
||||
├── README.md <- Este archivo
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAE018-001.md <- Dashboard ejecutivo
|
||||
├── US-MAE018-002.md <- KPIs operativos
|
||||
└── US-MAE018-003.md <- Reportes personalizados
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAE-018 Reportes y KPIs - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,192 @@
|
||||
# REQUERIMIENTOS - MAE-018: Reportes y KPIs
|
||||
|
||||
**Modulo:** MAE-018
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 6
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-6.1: KPIs Operativos
|
||||
|
||||
**KPI 1: On-Time Pickup (OTP)**
|
||||
- Formula: (Pickups a tiempo / Total pickups) × 100
|
||||
- Meta tipica: >= 95%
|
||||
- Dimension: Por cliente, ruta, operador
|
||||
|
||||
**KPI 2: On-Time Delivery (OTD)**
|
||||
- Formula: (Entregas a tiempo / Total entregas) × 100
|
||||
- Meta tipica: >= 95%
|
||||
- Dimension: Por cliente, ruta, operador
|
||||
|
||||
**KPI 3: OTIF (On Time In Full)**
|
||||
- Formula: (Entregas a tiempo Y completas / Total) × 100
|
||||
- Meta tipica: >= 92%
|
||||
- Considera: Tiempo + cantidad correcta + sin dano
|
||||
|
||||
**KPI 4: Detention Time**
|
||||
- Formula: Tiempo en carga/descarga - Tiempo tolerancia
|
||||
- Meta tipica: <= 2 horas promedio
|
||||
- Impacto: Costos adicionales
|
||||
|
||||
**Tablas fuente:**
|
||||
- `transport.viajes`
|
||||
- `tracking.eventos_tracking`
|
||||
|
||||
---
|
||||
|
||||
### RF-6.2: KPIs de Costos y Rentabilidad
|
||||
|
||||
**KPI 5: Costo por Kilometro**
|
||||
- Formula: Costo total viaje / km recorridos
|
||||
- Incluye: Combustible + peajes + viaticos + mantenimiento
|
||||
- Dimension: Por unidad, ruta, cliente
|
||||
|
||||
**KPI 6: Costo por Viaje**
|
||||
- Formula: Suma de todos los costos del viaje
|
||||
- Desglose: Fijos + variables
|
||||
|
||||
**KPI 7: Margen por Cliente/Ruta**
|
||||
- Formula: (Ingreso - Costo) / Ingreso × 100
|
||||
- Meta tipica: >= 15%
|
||||
- Alerta: Si < 10%
|
||||
|
||||
**Tablas fuente:**
|
||||
- `fuel.cargas_combustible`
|
||||
- `fuel.cruces_peaje`
|
||||
- `fuel.gastos_viaje`
|
||||
- `billing.facturas`
|
||||
|
||||
---
|
||||
|
||||
### RF-6.3: KPIs de Flota
|
||||
|
||||
**KPI 8: Disponibilidad de Flota**
|
||||
- Formula: (Unidades disponibles / Total unidades) × 100
|
||||
- Excluye: En taller, bloqueadas
|
||||
- Meta tipica: >= 85%
|
||||
|
||||
**KPI 9: MTBF (Mean Time Between Failures)**
|
||||
- Formula: Tiempo total operacion / Numero de fallas
|
||||
- Dimension: Por tipo de unidad
|
||||
|
||||
**KPI 10: MTTR (Mean Time To Repair)**
|
||||
- Formula: Tiempo total reparacion / Numero de OTs
|
||||
- Meta tipica: <= 24 horas
|
||||
|
||||
**Tablas fuente:**
|
||||
- `fleet.unidades`
|
||||
- `maintenance.ordenes_trabajo`
|
||||
|
||||
---
|
||||
|
||||
### RF-6.4: KPIs de Combustible
|
||||
|
||||
**KPI: Rendimiento km/litro**
|
||||
- Formula: km recorridos / litros consumidos
|
||||
- Dimension: Por unidad, operador
|
||||
- Comparar vs esperado
|
||||
|
||||
**KPI: Costo Combustible / Ingreso**
|
||||
- Formula: (Gasto combustible / Ingreso) × 100
|
||||
- Meta tipica: <= 30%
|
||||
|
||||
**Tablas fuente:**
|
||||
- `fuel.cargas_combustible`
|
||||
- `fuel.control_rendimiento`
|
||||
|
||||
---
|
||||
|
||||
### RF-6.5: KPIs de Incidencias
|
||||
|
||||
**KPI: Incidencias por 100 viajes**
|
||||
- Formula: (Incidencias / Viajes) × 100
|
||||
- Dimension: Por tipo, cliente, operador
|
||||
- Meta tipica: <= 3%
|
||||
|
||||
**KPI: Costo de Reclamos**
|
||||
- Formula: Suma de costos por incidencias
|
||||
- Dimension: Por periodo, cliente
|
||||
|
||||
**Tablas fuente:**
|
||||
- `tracking.incidencias`
|
||||
- `tracking.costos_incidencia`
|
||||
|
||||
---
|
||||
|
||||
### RF-6.6: KPIs de Cumplimiento
|
||||
|
||||
**KPI: Cumplimiento Documental**
|
||||
- Formula: (Docs vigentes / Docs requeridos) × 100
|
||||
- Aplica a: Unidades, operadores, carriers
|
||||
- Meta: 100%
|
||||
|
||||
**KPI: Cumplimiento HOS**
|
||||
- Formula: (Dias sin exceso / Dias totales) × 100
|
||||
- Meta: >= 98%
|
||||
|
||||
**Tablas fuente:**
|
||||
- `fleet.documentos_unidad`
|
||||
- `compliance.registros_hos`
|
||||
|
||||
---
|
||||
|
||||
## Dashboards Requeridos
|
||||
|
||||
### Dashboard Ejecutivo
|
||||
- KPIs principales con semaforo
|
||||
- Tendencias (ultimos 12 meses)
|
||||
- Top/Bottom performers
|
||||
- Alertas activas
|
||||
|
||||
### Dashboard Operaciones
|
||||
- Viajes en curso
|
||||
- OTIF del dia/semana/mes
|
||||
- Incidencias pendientes
|
||||
- Detention acumulado
|
||||
|
||||
### Dashboard Flota
|
||||
- Disponibilidad actual
|
||||
- Unidades en taller
|
||||
- Proximos mantenimientos
|
||||
- Documentos por vencer
|
||||
|
||||
### Dashboard Financiero
|
||||
- Ingresos vs Costos
|
||||
- Margen por cliente
|
||||
- Cuentas por cobrar
|
||||
- Rentabilidad por ruta
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Performance
|
||||
- Dashboards cargan < 5 segundos
|
||||
- Precalculo de metricas (vistas materializadas)
|
||||
|
||||
### RNF-002: Exportacion
|
||||
- Excel, PDF, CSV
|
||||
- Programacion de envio automatico
|
||||
|
||||
### RNF-003: Personalizacion
|
||||
- Filtros por periodo, cliente, ruta
|
||||
- Dashboards personalizables por usuario
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | KPIs | Historias |
|
||||
|----|------|-----------|
|
||||
| RF-6.1 | OTP, OTD, OTIF, Detention | US-MAE018-002 |
|
||||
| RF-6.2 | Costo/km, Margen | US-MAE018-001 |
|
||||
| RF-6.3 | Disponibilidad, MTBF, MTTR | US-MAE018-002 |
|
||||
| RF-6.4 | km/litro, Costo comb. | US-MAE018-002 |
|
||||
| RF-6.5 | Incidencias/100 | US-MAE018-002 |
|
||||
| RF-6.6 | Cumplimiento doc, HOS | US-MAE018-002 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAE-018 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,75 @@
|
||||
# RESUMEN EPICA - MAE-018: Reportes y KPIs
|
||||
|
||||
**Modulo:** MAE-018
|
||||
**Prioridad:** P3
|
||||
**Story Points Total:** 18
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- No hay visibilidad de desempeno operativo
|
||||
- Costos y rentabilidad desconocidos
|
||||
- Decisiones basadas en intuicion
|
||||
- Reportes manuales en Excel
|
||||
|
||||
### Beneficios
|
||||
- **Visibilidad en tiempo real** de KPIs
|
||||
- **Control de costos** y rentabilidad
|
||||
- **Deteccion temprana** de problemas
|
||||
- **Toma de decisiones** basada en datos
|
||||
|
||||
### KPIs Impactados
|
||||
- Todos los KPIs del giro
|
||||
- Productividad de reporteria
|
||||
- Tiempo de analisis
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Dashboard ejecutivo
|
||||
- 10 KPIs especializados
|
||||
- Dashboards por rol
|
||||
- Reportes personalizados
|
||||
- Exportacion multi-formato
|
||||
|
||||
### Excluido
|
||||
- Business Intelligence avanzado
|
||||
- Prediccion con ML
|
||||
- Reportes ad-hoc con SQL
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAE018-001 | Dashboard ejecutivo | 8 |
|
||||
| US-MAE018-002 | KPIs operativos y de flota | 5 |
|
||||
| US-MAE018-003 | Reportes personalizados | 5 |
|
||||
| **Total** | | **18** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
Todos los modulos ──> MAE-018 (consolida datos)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Datos incompletos | Validacion de fuentes |
|
||||
| Performance en dashboards | Vistas materializadas |
|
||||
| KPIs mal definidos | Validar con operaciones |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAE-018 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,145 @@
|
||||
# US-MAE018-001: Dashboard ejecutivo
|
||||
|
||||
**ID:** US-MAE018-001
|
||||
**Modulo:** MAE-018 (Reportes y KPIs)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** director general
|
||||
**Quiero** ver un dashboard ejecutivo con los KPIs principales
|
||||
**Para** tener vision del desempeno del negocio en una sola pantalla
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Ver KPIs principales
|
||||
**Dado** que accedo al dashboard
|
||||
**Cuando** cargo la pagina
|
||||
**Entonces** veo los KPIs principales con valor actual y meta
|
||||
|
||||
### CA-002: Semaforo de cumplimiento
|
||||
**Dado** que cada KPI tiene una meta
|
||||
**Cuando** veo el indicador
|
||||
**Entonces** tiene color verde/amarillo/rojo segun cumplimiento
|
||||
|
||||
### CA-003: Tendencia historica
|
||||
**Dado** que necesito ver evolucion
|
||||
**Cuando** consulto un KPI
|
||||
**Entonces** veo grafico de tendencia (ultimos 12 meses)
|
||||
|
||||
### CA-004: Drill-down
|
||||
**Dado** que quiero profundizar
|
||||
**Cuando** hago clic en un KPI
|
||||
**Entonces** veo detalle por dimension (cliente, ruta, etc.)
|
||||
|
||||
### CA-005: Alertas activas
|
||||
**Dado** que hay situaciones criticas
|
||||
**Cuando** veo el dashboard
|
||||
**Entonces** aparecen alertas que requieren atencion
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| DASHBOARD EJECUTIVO - Enero 2026 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| +------------------+ +------------------+ |
|
||||
| | OTIF | | Margen | |
|
||||
| | [92.5%] [G] | | [18.2%] [G] | |
|
||||
| | Meta: 92% | | Meta: 15% | |
|
||||
| | ^ +1.2% vs mes | | v -0.5% vs mes | |
|
||||
| +------------------+ +------------------+ |
|
||||
| |
|
||||
| +------------------+ +------------------+ |
|
||||
| | Disponibilidad | | Costo/km | |
|
||||
| | [87.3%] [A] | | [$12.45] [G] | |
|
||||
| | Meta: 85% | | Meta: $13.00 | |
|
||||
| | = igual mes | | v -2.1% vs mes | |
|
||||
| +------------------+ +------------------+ |
|
||||
| |
|
||||
| +------------------+ +------------------+ |
|
||||
| | Incidencias | | On-Time Del. | |
|
||||
| | [2.8%] [G] | | [94.2%] [A] | |
|
||||
| | Meta: <=3% | | Meta: 95% | |
|
||||
| | v -0.3% vs mes | | ^ +0.8% vs mes | |
|
||||
| +------------------+ +------------------+ |
|
||||
| |
|
||||
| [G] = Verde (cumple) [A] = Amarillo (cerca) |
|
||||
| [R] = Rojo (no cumple) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TENDENCIA OTIF (12 MESES) |
|
||||
| |
|
||||
| 100%| |
|
||||
| 95%| ----*----*----*----*----*----*----*----*-- |
|
||||
| 90%| * * |
|
||||
| 85%| * |
|
||||
| +--+--+--+--+--+--+--+--+--+--+--+--+ |
|
||||
| Feb Mar Abr May Jun Jul Ago Sep Oct Nov Dic Ene |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ALERTAS ACTIVAS |
|
||||
| |
|
||||
| [!] 3 unidades con mantenimiento vencido |
|
||||
| [!] Cliente CEMEX: OTIF < 90% (investigar) |
|
||||
| [!] Carrier "Fletes Bajio" en categoria D |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESUMEN FINANCIERO |
|
||||
| |
|
||||
| Ingresos mes: $4,250,000 |
|
||||
| Costos mes: $3,478,000 |
|
||||
| Margen bruto: $772,000 (18.2%) |
|
||||
| |
|
||||
| Viajes completados: 380 |
|
||||
| Km recorridos: 285,000 |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## KPIs del Dashboard Ejecutivo
|
||||
|
||||
| KPI | Formula | Meta | Semaforo |
|
||||
|-----|---------|------|----------|
|
||||
| OTIF | Entregas OK / Total | 92% | G>=92, A>=88, R<88 |
|
||||
| Margen | (Ing-Costo)/Ing | 15% | G>=15, A>=12, R<12 |
|
||||
| Disponibilidad | Unid OK / Total | 85% | G>=85, A>=80, R<80 |
|
||||
| Costo/km | Costo total / km | $13 | G<=13, A<=15, R>15 |
|
||||
| Incidencias | Inc / Viajes | 3% | G<=3, A<=5, R>5 |
|
||||
| On-Time Delivery | Entregas a tiempo | 95% | G>=95, A>=90, R<90 |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Vistas materializadas para performance
|
||||
- Job nocturno calcula KPIs del dia anterior
|
||||
- Cache de 15 minutos para dashboard
|
||||
- Chart.js o Recharts para graficos
|
||||
- Drill-down abre modal con detalle
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] 6 KPIs principales con semaforo
|
||||
- [ ] Comparativo vs meta y vs mes anterior
|
||||
- [ ] Grafico de tendencia 12 meses
|
||||
- [ ] Drill-down por dimension
|
||||
- [ ] Seccion de alertas activas
|
||||
- [ ] Resumen financiero
|
||||
- [ ] Carga < 5 segundos
|
||||
- [ ] Tests de calculo de KPIs
|
||||
@ -0,0 +1,180 @@
|
||||
# US-MAE018-002: KPIs operativos y de flota
|
||||
|
||||
**ID:** US-MAE018-002
|
||||
**Modulo:** MAE-018 (Reportes y KPIs)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** jefe de operaciones
|
||||
**Quiero** dashboards especializados por area
|
||||
**Para** monitorear el desempeno detallado de operaciones y flota
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Dashboard de operaciones
|
||||
**Dado** que soy jefe de operaciones
|
||||
**Cuando** accedo a mi dashboard
|
||||
**Entonces** veo KPIs de OTIF, tiempos, viajes activos
|
||||
|
||||
### CA-002: Dashboard de flota
|
||||
**Dado** que soy jefe de flota
|
||||
**Cuando** accedo a mi dashboard
|
||||
**Entonces** veo disponibilidad, mantenimiento, documentos
|
||||
|
||||
### CA-003: Filtros por periodo
|
||||
**Dado** que quiero analizar un periodo especifico
|
||||
**Cuando** aplico filtros
|
||||
**Entonces** los datos se recalculan para ese periodo
|
||||
|
||||
### CA-004: Comparativo entre dimensiones
|
||||
**Dado** que quiero comparar rendimiento
|
||||
**Cuando** consulto un KPI
|
||||
**Entonces** puedo ver ranking (top/bottom performers)
|
||||
|
||||
### CA-005: Exportar datos
|
||||
**Dado** que necesito los datos fuera del sistema
|
||||
**Cuando** exporto
|
||||
**Entonces** descargo Excel/CSV con el detalle
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Dashboard Operaciones
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| DASHBOARD OPERACIONES - Enero 2026 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Filtros: [Este mes v] [Todos los clientes v] [Aplicar] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| VIAJES ACTIVOS AHORA |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | 12 | | 3 | | 2 | |
|
||||
| | En transito | | Cargando | | Descargando| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| KPIs DEL PERIODO |
|
||||
| |
|
||||
| | KPI | Actual | Meta | Tendencia | |
|
||||
| |------------------|--------|-------|-----------| |
|
||||
| | On-Time Pickup | 96.2% | 95% | [G] ^ | |
|
||||
| | On-Time Delivery | 94.2% | 95% | [A] ^ | |
|
||||
| | OTIF | 92.5% | 92% | [G] ^ | |
|
||||
| | Detention prom. | 1.8 h | 2.0 h | [G] v | |
|
||||
| | Viajes/dia | 12.3 | 12.0 | [G] = | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TOP 5 CLIENTES POR VOLUMEN |
|
||||
| |
|
||||
| | Cliente | Viajes | OTIF | Margen | |
|
||||
| |--------------|--------|-------|--------| |
|
||||
| | Liverpool | 45 | 95.5% | 19.2% | |
|
||||
| | CEMEX | 38 | 88.2% | 15.1% | [!] |
|
||||
| | Bimbo | 32 | 94.1% | 17.8% | |
|
||||
| | Walmart | 28 | 93.2% | 14.5% | |
|
||||
| | Soriana | 25 | 96.0% | 18.5% | |
|
||||
| |
|
||||
| [!] CEMEX por debajo de meta OTIF |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| INCIDENCIAS DEL PERIODO |
|
||||
| |
|
||||
| Total: 11 incidencias (2.9%) |
|
||||
| |
|
||||
| Retrasos ████████ 5 |
|
||||
| Danos ████ 3 |
|
||||
| Faltantes ██ 2 |
|
||||
| Otros █ 1 |
|
||||
| |
|
||||
| [Ver detalle de incidencias] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Dashboard Flota
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| DASHBOARD FLOTA - 27 enero 2026 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DISPONIBILIDAD ACTUAL |
|
||||
| |
|
||||
| Disponible ██████████████████████████████ 28 (80%)|
|
||||
| En viaje ████████ 4 (11%) |
|
||||
| En taller ██ 2 (6%) |
|
||||
| Bloqueada █ 1 (3%) |
|
||||
| |
|
||||
| Total unidades: 35 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| KPIs DE MANTENIMIENTO |
|
||||
| |
|
||||
| | KPI | Actual | Meta | Estado | |
|
||||
| |---------------|---------|--------|----------| |
|
||||
| | MTBF | 45 dias | 30 dias| [G] | |
|
||||
| | MTTR | 18 hrs | 24 hrs | [G] | |
|
||||
| | Cumpl. prev. | 92% | 95% | [A] | |
|
||||
| | Costo/km mto. | $0.85 | $1.00 | [G] | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| PROXIMOS MANTENIMIENTOS (7 dias) |
|
||||
| |
|
||||
| | Unidad | Servicio | Fecha | km falt.| |
|
||||
| |---------|-----------------|-----------|---------| |
|
||||
| | T-1025 | Cambio aceite | 28-ene | 150 km | |
|
||||
| | T-1030 | Verificacion | 30-ene | - | |
|
||||
| | T-1018 | Service mayor | 31-ene | 900 km | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DOCUMENTOS POR VENCER (30 dias) |
|
||||
| |
|
||||
| | Unidad | Documento | Vence | |
|
||||
| |---------|-----------------|-----------| |
|
||||
| | T-1015 | Verificacion | 28-feb | |
|
||||
| | T-1022 | Poliza seguro | 15-feb | |
|
||||
| | OP-0032 | Licencia fed. | 10-feb | |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tablas fuente de cada modulo
|
||||
- Vistas materializadas por periodo
|
||||
- Actualizacion cada 15 minutos
|
||||
- Exportacion con libreria xlsx
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Dashboard de operaciones
|
||||
- [ ] Dashboard de flota
|
||||
- [ ] KPIs con semaforo y tendencia
|
||||
- [ ] Ranking de performers
|
||||
- [ ] Filtros por periodo
|
||||
- [ ] Exportacion Excel/CSV
|
||||
- [ ] Tests de calculos
|
||||
@ -0,0 +1,201 @@
|
||||
# US-MAE018-003: Reportes personalizados
|
||||
|
||||
**ID:** US-MAE018-003
|
||||
**Modulo:** MAE-018 (Reportes y KPIs)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** usuario del sistema
|
||||
**Quiero** generar reportes personalizados con los datos que necesito
|
||||
**Para** analizar informacion especifica y compartirla
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Catalogo de reportes
|
||||
**Dado** que hay reportes predefinidos
|
||||
**Cuando** accedo al modulo de reportes
|
||||
**Entonces** veo catalogo por categoria (operaciones, finanzas, flota)
|
||||
|
||||
### CA-002: Parametros de reporte
|
||||
**Dado** que ejecuto un reporte
|
||||
**Cuando** lo configuro
|
||||
**Entonces** puedo filtrar por fechas, clientes, rutas
|
||||
|
||||
### CA-003: Vista previa
|
||||
**Dado** que configure los parametros
|
||||
**Cuando** ejecuto el reporte
|
||||
**Entonces** veo vista previa antes de exportar
|
||||
|
||||
### CA-004: Multiples formatos
|
||||
**Dado** que necesito compartir el reporte
|
||||
**Cuando** exporto
|
||||
**Entonces** puedo elegir Excel, PDF o CSV
|
||||
|
||||
### CA-005: Programar envio
|
||||
**Dado** que necesito reportes periodicos
|
||||
**Cuando** configuro programacion
|
||||
**Entonces** se envia automaticamente por email
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Catalogo de Reportes
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REPORTES |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Buscar: [________________________] [Q] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| OPERACIONES |
|
||||
| |
|
||||
| [icon] Viajes por periodo |
|
||||
| Listado de viajes con filtros |
|
||||
| |
|
||||
| [icon] Performance OTIF |
|
||||
| Detalle de entregas a tiempo |
|
||||
| |
|
||||
| [icon] Incidencias detallado |
|
||||
| Listado con costos y resoluciones |
|
||||
| |
|
||||
| [icon] Detention por cliente |
|
||||
| Tiempos de espera en carga/descarga |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| FINANCIEROS |
|
||||
| |
|
||||
| [icon] Rentabilidad por cliente |
|
||||
| Ingresos, costos y margen por cliente |
|
||||
| |
|
||||
| [icon] Rentabilidad por ruta |
|
||||
| Analisis de lanes rentables |
|
||||
| |
|
||||
| [icon] Costos por viaje |
|
||||
| Desglose de combustible, peajes, etc. |
|
||||
| |
|
||||
| [icon] Facturacion pendiente |
|
||||
| Viajes cerrados sin facturar |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| FLOTA |
|
||||
| |
|
||||
| [icon] Rendimiento de combustible |
|
||||
| km/litro por unidad y operador |
|
||||
| |
|
||||
| [icon] Historial de mantenimiento |
|
||||
| OTs por unidad con costos |
|
||||
| |
|
||||
| [icon] Disponibilidad historica |
|
||||
| % disponibilidad por periodo |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Ejecutar Reporte
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REPORTE: Rentabilidad por Cliente X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| PARAMETROS |
|
||||
| |
|
||||
| Periodo: [01-ene-2026] a [31-ene-2026] |
|
||||
| |
|
||||
| Clientes: |
|
||||
| (o) Todos |
|
||||
| ( ) Seleccionar: [________________________] |
|
||||
| |
|
||||
| Incluir: |
|
||||
| [x] Desglose de costos |
|
||||
| [x] Comparativo mes anterior |
|
||||
| [ ] Solo clientes con margen < 15% |
|
||||
| |
|
||||
| Ordenar por: [Margen descendente v] |
|
||||
| |
|
||||
| [Ejecutar] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| VISTA PREVIA |
|
||||
| |
|
||||
| | Cliente | Viajes | Ingreso | Costo |Margen||
|
||||
| |--------------|--------|-----------|----------|------||
|
||||
| | Liverpool | 45 | $820,000 | $664,200 |19.2% ||
|
||||
| | Bimbo | 32 | $580,000 | $476,600 |17.8% ||
|
||||
| | Soriana | 25 | $450,000 | $366,750 |18.5% ||
|
||||
| | Walmart | 28 | $510,000 | $435,900 |14.5% ||
|
||||
| | CEMEX | 38 | $690,000 | $585,810 |15.1% ||
|
||||
| |--------------|--------|-----------|----------|------||
|
||||
| | TOTAL | 168 |$3,050,000 |$2,529,260|17.1% ||
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EXPORTAR |
|
||||
| |
|
||||
| Formato: (o) Excel ( ) PDF ( ) CSV |
|
||||
| |
|
||||
| [Descargar] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| PROGRAMAR ENVIO |
|
||||
| |
|
||||
| [ ] Enviar automaticamente |
|
||||
| Frecuencia: [Semanal v] |
|
||||
| Dia: [Lunes v] |
|
||||
| Destinatarios: [controller@empresa.com ] |
|
||||
| |
|
||||
| [Guardar programacion] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reportes Predefinidos
|
||||
|
||||
| Categoria | Reporte | Parametros |
|
||||
|-----------|---------|------------|
|
||||
| Operaciones | Viajes por periodo | Fechas, cliente, estado |
|
||||
| Operaciones | Performance OTIF | Fechas, cliente, dimension |
|
||||
| Operaciones | Incidencias | Fechas, tipo, estado |
|
||||
| Financiero | Rentabilidad cliente | Fechas, cliente |
|
||||
| Financiero | Rentabilidad ruta | Fechas, origen, destino |
|
||||
| Financiero | Costos por viaje | Fechas, viaje |
|
||||
| Flota | Rendimiento combustible | Fechas, unidad, operador |
|
||||
| Flota | Historial mantenimiento | Fechas, unidad |
|
||||
| Carriers | Scorecard carriers | Periodo, carrier |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Generador de reportes con templates
|
||||
- Exportacion: xlsx (exceljs), PDF (puppeteer)
|
||||
- Jobs programados para envio automatico
|
||||
- Cola de reportes para reportes pesados
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Catalogo de reportes por categoria
|
||||
- [ ] Formulario de parametros
|
||||
- [ ] Vista previa de resultados
|
||||
- [ ] Exportacion Excel, PDF, CSV
|
||||
- [ ] Programacion de envio automatico
|
||||
- [ ] Cola para reportes pesados
|
||||
- [ ] Tests de generacion de reportes
|
||||
142
docs/02-definicion-modulos/MAI-003-ordenes-transporte/README.md
Normal file
142
docs/02-definicion-modulos/MAI-003-ordenes-transporte/README.md
Normal file
@ -0,0 +1,142 @@
|
||||
# MAI-003: Ordenes de Transporte
|
||||
|
||||
**Modulo:** MAI-003 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Descripcion
|
||||
|
||||
El modulo de Ordenes de Transporte (OT) es el nucleo operativo del ERP Transportistas. Una OT representa la solicitud formal de un cliente (shipper) para mover mercancia desde un punto de origen hasta uno o multiples destinos, con restricciones logisticas especificas. Este modulo gestiona todo el ciclo de vida de la OT, desde su creacion en borrador hasta su cierre tras la facturacion.
|
||||
|
||||
La OT es el documento maestro que conecta las necesidades comerciales del cliente con la ejecucion operativa del transporte. Cada OT contiene informacion detallada sobre la carga, ubicaciones georreferenciadas, ventanas de tiempo, requisitos de equipo, tarifas aplicables y estado operativo. Las OTs pueden agruparse en embarques para consolidacion logistica y asignarse a viajes para su ejecucion.
|
||||
|
||||
---
|
||||
|
||||
## Workflow de la OT
|
||||
|
||||
```
|
||||
BORRADOR --> CONFIRMADA --> ASIGNADA --> EN_PROCESO --> COMPLETADA --> FACTURADA --> CANCELADA (desde cualquier estado previo a COMPLETADA)
|
||||
```
|
||||
|
||||
| Estado | Descripcion | Transiciones permitidas |
|
||||
|--------|-------------|------------------------|
|
||||
| BORRADOR | OT recien creada, editable libremente | CONFIRMADA, CANCELADA |
|
||||
| CONFIRMADA | Datos validados, lista para planeacion | ASIGNADA, CANCELADA |
|
||||
| ASIGNADA | Vinculada a un embarque y/o viaje | EN_PROCESO, CANCELADA |
|
||||
| EN_PROCESO | Viaje en ejecucion, carga en transito | COMPLETADA |
|
||||
| COMPLETADA | Entrega realizada con POD | FACTURADA |
|
||||
| FACTURADA | OT incluida en factura emitida | (estado terminal) |
|
||||
| CANCELADA | OT cancelada con motivo registrado | (estado terminal) |
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el modulo |
|
||||
|-------|-----------------|
|
||||
| **Cliente / Shipper** | Solicita el servicio de transporte, proporciona datos de carga y ubicaciones |
|
||||
| **Despachador** | Crea y confirma OTs, valida datos, coordina con clientes |
|
||||
| **Coordinador / Planner** | Agrupa OTs en embarques, asigna a viajes, optimiza recursos |
|
||||
| **Operador / Conductor** | Ejecuta el transporte fisico de la carga asociada a las OTs |
|
||||
| **Administrador** | Configura parametros del modulo, gestiona permisos y tarifas |
|
||||
|
||||
---
|
||||
|
||||
## Funcionalidades Clave
|
||||
|
||||
1. **Creacion de OT con datos completos:** Origen/destino georreferenciados, datos de carga (peso, volumen, piezas, pallets), tipo de carga, ventanas de tiempo para recoleccion y entrega, referencia del cliente.
|
||||
2. **Multi-paradas:** Soporte para rutas con multiples puntos de recoleccion y entrega mediante la tabla `paradas_viaje` asociada al viaje.
|
||||
3. **Agrupacion en embarques:** Consolidacion de multiples OTs compatibles en un embarque para optimizar capacidad y costos.
|
||||
4. **Asignacion a viajes:** Vinculacion de OTs/embarques a viajes con unidad, operador y ruta asignados.
|
||||
5. **Restricciones logisticas:** Requisitos de temperatura, GPS, escolta, citas, instrucciones especiales por OT.
|
||||
6. **Calculo de tarifa:** Tarifa base, recargos, descuentos, subtotal, IVA y total calculados automaticamente.
|
||||
7. **Tracking de status:** Transiciones de estado controladas con trazabilidad de usuario y timestamp.
|
||||
8. **Busqueda avanzada:** Filtros por estado, cliente, fechas, tipo de carga, codigo y referencia.
|
||||
9. **Cancelacion controlada:** Cancelacion con registro de motivo y usuario responsable.
|
||||
|
||||
---
|
||||
|
||||
## Entidades Principales (DDL)
|
||||
|
||||
| Entidad | Tabla | Schema | Descripcion |
|
||||
|---------|-------|--------|-------------|
|
||||
| OrdenTransporte | `transport.ordenes_transporte` | transport | Solicitud de servicio de transporte |
|
||||
| Embarque | `transport.embarques` | transport | Agrupacion logica de OTs para consolidacion |
|
||||
| Viaje | `transport.viajes` | transport | Ejecucion operativa (unidad + operador + ruta) |
|
||||
| ParadaViaje | `transport.paradas_viaje` | transport | Paradas programadas en un viaje (multi-drop) |
|
||||
| POD | `transport.pod` | transport | Proof of Delivery - evidencia de entrega |
|
||||
| Incidencia | `transport.incidencias` | transport | Registro de incidencias durante el transporte |
|
||||
|
||||
### ENUMs Relevantes
|
||||
|
||||
| ENUM | Valores | Uso |
|
||||
|------|---------|-----|
|
||||
| `estado_orden` | BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA, CANCELADA | Estado de la OT |
|
||||
| `tipo_carga` | GENERAL, PELIGROSA, REFRIGERADA, SOBREDIMENSIONADA, GRANEL, LIQUIDOS, CONTENEDOR, AUTOMOVILES | Clasificacion de carga |
|
||||
| `estado_pod` | PENDIENTE, PARCIAL, COMPLETO, RECHAZADO | Estado de evidencia de entrega |
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints (Proyectados)
|
||||
|
||||
| Metodo | Endpoint | Descripcion |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/v1/ordenes-transporte` | Crear nueva OT |
|
||||
| GET | `/api/v1/ordenes-transporte` | Listar OTs con filtros y paginacion |
|
||||
| GET | `/api/v1/ordenes-transporte/:id` | Obtener detalle de una OT |
|
||||
| PATCH | `/api/v1/ordenes-transporte/:id` | Actualizar OT en BORRADOR |
|
||||
| PATCH | `/api/v1/ordenes-transporte/:id/confirmar` | Confirmar OT (BORRADOR -> CONFIRMADA) |
|
||||
| PATCH | `/api/v1/ordenes-transporte/:id/cancelar` | Cancelar OT con motivo |
|
||||
| POST | `/api/v1/embarques` | Crear embarque agrupando OTs |
|
||||
| GET | `/api/v1/embarques` | Listar embarques con OTs asociadas |
|
||||
| GET | `/api/v1/embarques/:id` | Detalle de embarque |
|
||||
| PATCH | `/api/v1/embarques/:id/asignar-viaje` | Asignar embarque a viaje |
|
||||
| GET | `/api/v1/ordenes-transporte/dashboard` | Resumen de OTs por estado |
|
||||
| GET | `/api/v1/ordenes-transporte/exportar` | Exportar listado de OTs (CSV/Excel) |
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Archivo |
|
||||
|----|--------|:--:|:---------:|---------|
|
||||
| US-MAI003-001 | Crear orden de transporte | 8 | P0 | `historias-usuario/US-MAI003-001.md` |
|
||||
| US-MAI003-002 | Agregar multiples paradas a OT | 5 | P0 | `historias-usuario/US-MAI003-002.md` |
|
||||
| US-MAI003-003 | Definir restricciones logisticas | 5 | P1 | `historias-usuario/US-MAI003-003.md` |
|
||||
| US-MAI003-004 | Agrupar OTs en embarque | 8 | P0 | `historias-usuario/US-MAI003-004.md` |
|
||||
| US-MAI003-005 | Consultar status de OT | 3 | P1 | `historias-usuario/US-MAI003-005.md` |
|
||||
| US-MAI003-006 | Modificar OT en borrador | 5 | P1 | `historias-usuario/US-MAI003-006.md` |
|
||||
| US-MAI003-007 | Cancelar OT | 3 | P1 | `historias-usuario/US-MAI003-007.md` |
|
||||
| US-MAI003-008 | Buscar OTs con filtros avanzados | 5 | P1 | `historias-usuario/US-MAI003-008.md` |
|
||||
| US-MAI003-009 | Exportar listado de OTs | 3 | P2 | `historias-usuario/US-MAI003-009.md` |
|
||||
| US-MAI003-010 | Dashboard de OTs por status | 5 | P2 | `historias-usuario/US-MAI003-010.md` |
|
||||
|
||||
**Total Story Points:** 50
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Tipo | Modulo | Descripcion |
|
||||
|------|--------|-------------|
|
||||
| **Depende de** | MAI-001 (Auth) | Autenticacion, RBAC, multi-tenancy |
|
||||
| **Depende de** | MAI-002 (Clientes y Tarifas) | Datos de shippers/consignees, tarifas por lane |
|
||||
| **Bloquea** | MAI-004 (Planeacion TMS) | La planeacion consume OTs confirmadas |
|
||||
| **Bloquea** | MAI-005 (Despacho) | El despacho opera sobre OTs asignadas a viajes |
|
||||
| **Bloquea** | MAI-006 (Tracking) | El tracking monitorea viajes con OTs asociadas |
|
||||
| **Bloquea** | MAI-007 (POD y Cierre) | El POD cierra la entrega de OTs |
|
||||
| **Bloquea** | MAI-009 (Facturacion) | La facturacion genera CFDI sobre OTs completadas |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **RLS (Row Level Security):** Todas las tablas del schema `transport` tienen RLS habilitado con aislamiento por `tenant_id` usando `current_setting('app.tenant_id')`.
|
||||
- **Indices:** La tabla `ordenes_transporte` cuenta con indices en `tenant_id`, `estado`, `shipper_id`, `fecha_recoleccion_programada` y `viaje_id` para optimizar las consultas mas frecuentes.
|
||||
- **Constraint unico:** `uq_ot_tenant_codigo` garantiza que el codigo de OT sea unico por tenant.
|
||||
- **Soft delete:** Se utiliza `deleted_at` para eliminacion logica.
|
||||
- **Auditoria:** Campos `created_at`, `created_by_id`, `updated_at`, `updated_by_id` en todas las entidades.
|
||||
|
||||
---
|
||||
|
||||
*MAI-003 Ordenes de Transporte - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,126 @@
|
||||
# REQUERIMIENTOS.md - MAI-003 Ordenes de Transporte
|
||||
|
||||
**Modulo:** MAI-003 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Resumen
|
||||
|
||||
| Metrica | Valor |
|
||||
|---------|-------|
|
||||
| Total Requerimientos | 25 |
|
||||
| Prioridad Alta | 12 |
|
||||
| Prioridad Media | 9 |
|
||||
| Prioridad Baja | 4 |
|
||||
| Fuente DDL | 01-transport-schema-ddl.sql |
|
||||
| Fuente Funcional | REQ-GIRO-TRANSPORTISTA.md (secciones 4.2, 4.3) |
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### Creacion y Datos de la OT
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-001 | El sistema debe permitir crear una Orden de Transporte con los datos obligatorios: codigo unico por tenant, shipper (cliente), consignee (destinatario), direccion de origen, direccion de destino y usuario creador. | Alta | MAI-002 (Clientes) |
|
||||
| RF-MAI003-002 | El sistema debe registrar la referencia del cliente (referencia_cliente) como dato opcional para vincular la OT con el sistema del shipper (PO, ASN). | Alta | MAI-002 (Clientes) |
|
||||
| RF-MAI003-003 | El sistema debe capturar datos completos de origen y destino: direccion, codigo postal, ciudad, estado, pais (default MEX), latitud, longitud, contacto y telefono. | Alta | - |
|
||||
| RF-MAI003-004 | El sistema debe registrar las fechas y ventanas de tiempo programadas: fecha_recoleccion_programada, fecha_entrega_programada, ventana_recoleccion_inicio/fin y ventana_entrega_inicio/fin. | Alta | - |
|
||||
| RF-MAI003-005 | El sistema debe capturar los datos de carga: tipo_carga (GENERAL, PELIGROSA, REFRIGERADA, SOBREDIMENSIONADA, GRANEL, LIQUIDOS, CONTENEDOR, AUTOMOVILES), descripcion_carga, peso_kg, volumen_m3, piezas, pallets, valor_declarado y moneda. | Alta | - |
|
||||
| RF-MAI003-006 | El sistema debe generar automaticamente un codigo unico de OT por tenant, cumpliendo con la constraint uq_ot_tenant_codigo definida en DDL. | Alta | - |
|
||||
|
||||
### Restricciones Logisticas
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-007 | El sistema debe permitir definir requisitos de temperatura para carga refrigerada: requiere_temperatura (boolean), temperatura_min y temperatura_max en grados Celsius. | Media | MAI-011 (Flota) |
|
||||
| RF-MAI003-008 | El sistema debe permitir marcar requisitos de seguridad: requiere_gps (boolean), requiere_escolta (boolean) y requiere_cita (boolean). | Media | MAI-006 (Tracking) |
|
||||
| RF-MAI003-009 | El sistema debe permitir registrar instrucciones especiales como texto libre para comunicar al operador y al equipo de despacho. | Media | MAI-005 (Despacho) |
|
||||
| RF-MAI003-010 | El sistema debe registrar la modalidad de servicio (FTL o LTL) para determinar si el viaje es dedicado o consolidado. | Alta | MAI-004 (Planeacion) |
|
||||
|
||||
### Tarifas y Costos
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-011 | El sistema debe permitir asociar una tarifa a la OT (tarifa_id) y registrar tarifa_base, recargos, descuentos, subtotal, IVA y total. | Alta | MAI-002 (Tarifas), MAI-009 (Facturacion) |
|
||||
| RF-MAI003-012 | El sistema debe calcular automaticamente subtotal, IVA y total al confirmar la OT, basandose en la tarifa asignada y los recargos/descuentos aplicados. | Alta | MAI-009 (Facturacion) |
|
||||
|
||||
### Workflow y Estados
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-013 | El sistema debe implementar el workflow de estados: BORRADOR -> CONFIRMADA -> ASIGNADA -> EN_PROCESO -> COMPLETADA -> FACTURADA, con CANCELADA accesible desde BORRADOR, CONFIRMADA y ASIGNADA. | Alta | - |
|
||||
| RF-MAI003-014 | El sistema debe permitir modificar los datos de una OT unicamente cuando se encuentra en estado BORRADOR. En estados posteriores, la OT es de solo lectura. | Alta | - |
|
||||
| RF-MAI003-015 | El sistema debe registrar la transicion de estado con el usuario responsable (updated_by_id) y la fecha de actualizacion (updated_at). | Media | MAI-001 (Auth) |
|
||||
| RF-MAI003-016 | El sistema debe permitir cancelar una OT registrando el motivo de cancelacion y marcando deleted_at como fecha de cancelacion logica. | Media | - |
|
||||
|
||||
### Embarques (Agrupacion de OTs)
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-017 | El sistema debe permitir crear embarques con codigo unico por tenant, descripcion y cliente principal, cumpliendo la constraint uq_embarque_tenant_codigo. | Alta | - |
|
||||
| RF-MAI003-018 | El sistema debe permitir agrupar multiples OTs de un mismo cliente en un embarque, actualizando los totales consolidados: total_ots, peso_total_kg, volumen_total_m3. | Alta | MAI-004 (Planeacion) |
|
||||
| RF-MAI003-019 | El sistema debe actualizar el campo embarque_id en cada OT al agregarla a un embarque, y recalcular los totales del embarque al agregar o quitar OTs. | Media | - |
|
||||
| RF-MAI003-020 | El sistema debe permitir asignar un embarque a un viaje (viaje_id) y actualizar el estado del embarque en consecuencia. | Media | MAI-004 (Planeacion) |
|
||||
|
||||
### Consulta y Busqueda
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-021 | El sistema debe proporcionar un listado paginado de OTs con filtros por: estado, shipper_id, rango de fecha_recoleccion_programada, tipo_carga, codigo y referencia_cliente. Los indices idx_ot_estado, idx_ot_shipper e idx_ot_fechas deben soportar estas consultas. | Alta | - |
|
||||
| RF-MAI003-022 | El sistema debe mostrar el detalle completo de una OT incluyendo datos de carga, ubicaciones, restricciones, tarifa, estado actual y embarque/viaje asociados. | Media | - |
|
||||
| RF-MAI003-023 | El sistema debe proporcionar un dashboard con contadores de OTs agrupadas por estado para el tenant actual. | Baja | - |
|
||||
|
||||
### Exportacion
|
||||
|
||||
| ID | Descripcion | Prioridad | Modulo Relacionado |
|
||||
|----|-------------|-----------|-------------------|
|
||||
| RF-MAI003-024 | El sistema debe permitir exportar el listado de OTs filtrado en formato CSV, incluyendo: codigo, referencia_cliente, shipper_nombre, consignee_nombre, origen_ciudad, destino_ciudad, fecha_recoleccion_programada, fecha_entrega_programada, estado y total. | Baja | - |
|
||||
| RF-MAI003-025 | El sistema debe permitir exportar el listado de OTs filtrado en formato Excel (XLSX) con las mismas columnas que el formato CSV, ademas de formato de celdas y encabezados estilizados. | Baja | - |
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
| ID | Descripcion | Categoria |
|
||||
|----|-------------|-----------|
|
||||
| RNF-MAI003-001 | Todas las tablas del modulo deben tener RLS habilitado con politica de aislamiento por tenant_id. | Seguridad |
|
||||
| RNF-MAI003-002 | El listado de OTs con filtros debe responder en menos de 500ms para tenants con hasta 100,000 OTs. | Performance |
|
||||
| RNF-MAI003-003 | Las transiciones de estado deben ser atomicas y registrar auditoria completa (usuario, timestamp). | Integridad |
|
||||
| RNF-MAI003-004 | Los endpoints de listado deben soportar paginacion con cursor o offset, limitada a 100 registros por pagina. | Escalabilidad |
|
||||
| RNF-MAI003-005 | La exportacion de datos debe soportar hasta 50,000 registros sin timeout del servidor (procesamiento asincrono si excede 10,000). | Escalabilidad |
|
||||
|
||||
---
|
||||
|
||||
## Trazabilidad DDL -> Requerimiento
|
||||
|
||||
| Tabla DDL | Requerimientos Asociados |
|
||||
|-----------|-------------------------|
|
||||
| transport.ordenes_transporte | RF-MAI003-001 a RF-MAI003-016, RF-MAI003-021, RF-MAI003-022 |
|
||||
| transport.embarques | RF-MAI003-017 a RF-MAI003-020 |
|
||||
| ENUM transport.estado_orden | RF-MAI003-013 |
|
||||
| ENUM transport.tipo_carga | RF-MAI003-005 |
|
||||
| INDEX idx_ot_estado | RF-MAI003-021 |
|
||||
| INDEX idx_ot_shipper | RF-MAI003-021 |
|
||||
| INDEX idx_ot_fechas | RF-MAI003-021 |
|
||||
| CONSTRAINT uq_ot_tenant_codigo | RF-MAI003-006 |
|
||||
| CONSTRAINT uq_embarque_tenant_codigo | RF-MAI003-017 |
|
||||
|
||||
---
|
||||
|
||||
## Trazabilidad Funcional -> Requerimiento
|
||||
|
||||
| Seccion REQ-GIRO-TRANSPORTISTA | Requerimientos Asociados |
|
||||
|-------------------------------|-------------------------|
|
||||
| RF-4.2.1 Datos obligatorios OT | RF-MAI003-001, RF-MAI003-003, RF-MAI003-004, RF-MAI003-005 |
|
||||
| RF-4.2.2 Restricciones | RF-MAI003-007, RF-MAI003-008, RF-MAI003-009 |
|
||||
| RF-4.2.3 Multi-paradas | RF-MAI003-003 (origen/destino base), ver MAI-004 para paradas_viaje |
|
||||
| RF-4.2.4 LTL vs FTL | RF-MAI003-010 |
|
||||
| RF-4.2.5 Documentacion adjunta | RF-MAI003-009 (instrucciones_especiales) |
|
||||
| RF-4.3.1 Tablero de planeacion | RF-MAI003-023 |
|
||||
| RF-4.3.2 Consolidacion | RF-MAI003-017, RF-MAI003-018 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAI-003 Ordenes de Transporte - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,132 @@
|
||||
# EPIC-MAI-003: Ordenes de Transporte
|
||||
|
||||
**Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Resumen
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | EPIC-MAI-003 |
|
||||
| **Nombre** | Ordenes de Transporte |
|
||||
| **Modulo** | MAI-003 |
|
||||
| **Prioridad** | P0 - Critica |
|
||||
| **SP Total** | 50 |
|
||||
| **Sprint Inicio** | Por asignar |
|
||||
| **Sprint Fin** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
| **Owner** | Por asignar |
|
||||
| **Schema BD** | transport |
|
||||
| **Tabla Principal** | transport.ordenes_transporte |
|
||||
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
Implementar un sistema completo de gestion de Ordenes de Transporte (OT) que permita a los usuarios crear, confirmar, agrupar, asignar, monitorear y cerrar solicitudes de servicio de transporte de carga. La OT es el documento maestro que conecta la demanda comercial del cliente con la ejecucion operativa, y su correcta gestion es critica para la rentabilidad y calidad del servicio de la empresa transportista.
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
|
||||
- CRUD completo de Ordenes de Transporte con datos de origen, destino, carga y tarifas
|
||||
- Workflow de estados controlado: BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA, CANCELADA
|
||||
- Definicion de restricciones logisticas por OT (temperatura, GPS, escolta, citas)
|
||||
- Creacion y gestion de embarques como agrupacion de OTs
|
||||
- Consulta de status y timeline de la OT
|
||||
- Modificacion de OTs en estado BORRADOR
|
||||
- Cancelacion controlada con registro de motivo
|
||||
- Busqueda avanzada con filtros multiples
|
||||
- Exportacion de listados en formato CSV/Excel
|
||||
- Dashboard resumen de OTs por estado
|
||||
|
||||
### Excluido
|
||||
|
||||
- Planeacion y optimizacion de rutas (MAI-004)
|
||||
- Despacho y checklists pre-viaje (MAI-005)
|
||||
- Tracking GPS en tiempo real (MAI-006)
|
||||
- Captura de POD y cierre operativo (MAI-007)
|
||||
- Gestion de incidencias (MAI-008)
|
||||
- Facturacion y CFDI (MAI-009)
|
||||
- Portal de autoservicio para clientes (MAI-015)
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Estado |
|
||||
|----|--------|----|-----------|--------|
|
||||
| US-MAI003-001 | Crear orden de transporte | 8 | P0 | Backlog |
|
||||
| US-MAI003-002 | Agregar multiples paradas a OT | 5 | P0 | Backlog |
|
||||
| US-MAI003-003 | Definir restricciones logisticas | 5 | P1 | Backlog |
|
||||
| US-MAI003-004 | Agrupar OTs en embarque | 8 | P0 | Backlog |
|
||||
| US-MAI003-005 | Consultar status de OT | 3 | P1 | Backlog |
|
||||
| US-MAI003-006 | Modificar OT en borrador | 5 | P1 | Backlog |
|
||||
| US-MAI003-007 | Cancelar OT | 3 | P1 | Backlog |
|
||||
| US-MAI003-008 | Buscar OTs con filtros avanzados | 5 | P1 | Backlog |
|
||||
| US-MAI003-009 | Exportar listado de OTs | 3 | P2 | Backlog |
|
||||
| US-MAI003-010 | Dashboard de OTs por status | 5 | P2 | Backlog |
|
||||
|
||||
---
|
||||
|
||||
## SP Total: 50
|
||||
|
||||
| Prioridad | Stories | SP |
|
||||
|-----------|---------|-----|
|
||||
| P0 (Critica) | 3 | 21 |
|
||||
| P1 (Alta) | 5 | 21 |
|
||||
| P2 (Media) | 2 | 8 |
|
||||
| **Total** | **10** | **50** |
|
||||
|
||||
---
|
||||
|
||||
## Distribucion por Capa
|
||||
|
||||
| Capa | Esfuerzo Estimado |
|
||||
|------|-------------------|
|
||||
| Database (DDL + migraciones) | 15% |
|
||||
| Backend (entities + services + controllers) | 45% |
|
||||
| Frontend (components + pages + forms) | 30% |
|
||||
| Tests (unit + integration + e2e) | 10% |
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion de la Epica
|
||||
|
||||
1. Un despachador puede crear una OT con todos los datos obligatorios (origen, destino, cliente, carga)
|
||||
2. El sistema valida la transicion de estados segun el workflow definido
|
||||
3. Se pueden agrupar OTs compatibles en un embarque con totales consolidados
|
||||
4. La busqueda permite filtrar por estado, cliente, fechas, tipo de carga y codigo
|
||||
5. El dashboard muestra contadores por estado con actualizacion en tiempo real
|
||||
6. Todas las tablas tienen RLS habilitado para aislamiento por tenant
|
||||
7. Los endpoints cumplen con paginacion, filtros y ordenamiento estandar
|
||||
8. La auditoria registra usuario y timestamp en cada operacion
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Impacto | Mitigacion |
|
||||
|--------|---------|------------|
|
||||
| Datos de ubicacion incompletos | Alto | Validacion obligatoria de campos de direccion y geocodificacion |
|
||||
| Volumen alto de OTs por tenant | Medio | Indices optimizados y paginacion obligatoria en listados |
|
||||
| Cambios de estado no controlados | Alto | Maquina de estados estricta en backend con validacion de transiciones |
|
||||
| Calculo incorrecto de tarifas | Alto | Validacion cruzada con modulo MAI-002 y tests unitarios exhaustivos |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias Tecnicas
|
||||
|
||||
| Dependencia | Tipo | Descripcion |
|
||||
|-------------|------|-------------|
|
||||
| MAI-001 Auth | Bloqueante | Se requiere autenticacion y permisos RBAC funcionales |
|
||||
| MAI-002 Clientes | Bloqueante | Se requiere catalogo de clientes y tarifas configuradas |
|
||||
| Schema transport DDL | Bloqueante | Tablas ordenes_transporte, embarques deben existir |
|
||||
| ENUMs transport | Bloqueante | estado_orden, tipo_carga deben estar creados |
|
||||
|
||||
---
|
||||
|
||||
*EPIC-MAI-003 Ordenes de Transporte - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,78 @@
|
||||
# US-MAI003-001: Crear orden de transporte
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-001 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 8 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador de una empresa transportista,
|
||||
**quiero** crear una orden de transporte con todos los datos del servicio solicitado por el cliente,
|
||||
**para** registrar formalmente la demanda de transporte y que pueda ser procesada por el equipo de planeacion y operaciones.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
La creacion de una OT es el punto de entrada del flujo operativo de transporte. El despachador recibe la solicitud del cliente (por telefono, email o portal) y registra toda la informacion necesaria para ejecutar el servicio: datos del shipper y consignee, ubicaciones de origen y destino con coordenadas geograficas, fechas y ventanas de tiempo para recoleccion y entrega, caracteristicas de la carga (tipo, peso, volumen, piezas, pallets, valor declarado) y la tarifa aplicable.
|
||||
|
||||
El sistema debe generar automaticamente un codigo unico de OT por tenant (por ejemplo, OT-2026-00001) y registrar al usuario creador. La OT se crea en estado BORRADOR, permitiendo al despachador completar o modificar los datos antes de confirmarla.
|
||||
|
||||
Los campos de origen y destino incluyen datos de geolocalizacion (latitud/longitud) que seran utilizados posteriormente por los modulos de planeacion (MAI-004) y tracking (MAI-006). La tarifa se calcula automaticamente al asociar un tarifario, aplicando recargos y descuentos para obtener el total del servicio.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Creacion exitosa con datos obligatorios
|
||||
|
||||
**Dado** que el despachador tiene permisos de creacion de OT y existe al menos un cliente registrado,
|
||||
**Cuando** completa el formulario con los datos obligatorios (shipper, consignee, origen, destino) y presiona guardar,
|
||||
**Entonces** el sistema crea la OT en estado BORRADOR con un codigo unico generado automaticamente, registra created_at y created_by_id, y muestra el detalle de la OT creada.
|
||||
|
||||
### Escenario 2: Validacion de datos obligatorios
|
||||
|
||||
**Dado** que el despachador esta creando una nueva OT,
|
||||
**Cuando** intenta guardar sin completar los campos obligatorios (shipper_id, shipper_nombre, consignee_id, consignee_nombre, origen_direccion, destino_direccion, created_by_id),
|
||||
**Entonces** el sistema muestra mensajes de validacion indicando los campos faltantes y no crea la OT.
|
||||
|
||||
### Escenario 3: Codigo unico por tenant
|
||||
|
||||
**Dado** que el tenant ya tiene OTs registradas,
|
||||
**Cuando** se crea una nueva OT,
|
||||
**Entonces** el sistema genera un codigo que no exista previamente para ese tenant, respetando la constraint uq_ot_tenant_codigo.
|
||||
|
||||
### Escenario 4: Registro completo de carga y tarifas
|
||||
|
||||
**Dado** que el despachador esta creando una OT con datos de carga completos,
|
||||
**Cuando** selecciona tipo_carga, ingresa peso_kg, volumen_m3, piezas, pallets, valor_declarado y asocia una tarifa_id,
|
||||
**Entonces** el sistema calcula tarifa_base, recargos, descuentos, subtotal, IVA y total automaticamente y los almacena en la OT.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Verificar que la tabla `transport.ordenes_transporte` existe con todos los campos del DDL, incluyendo indices idx_ot_tenant, idx_ot_estado, idx_ot_shipper, idx_ot_fechas y constraint uq_ot_tenant_codigo.
|
||||
- **Backend:** Crear entity `OrdenTransporte` mapeada a `transport.ordenes_transporte`. Crear `OrdenTransporteService` con metodo `create()` que valide datos obligatorios, genere codigo unico y calcule tarifas. Crear `OrdenTransporteController` con endpoint POST `/api/v1/ordenes-transporte`. Crear DTOs: `CreateOrdenTransporteDto` con validaciones class-validator.
|
||||
- **Frontend:** Crear pagina `OrdenesTransporteCreatePage` con formulario multi-seccion (datos generales, origen/destino, carga, tarifas). Incluir seleccion de shipper y consignee con autocompletado. Incluir mapa para seleccion de coordenadas.
|
||||
- **Tests:** Tests unitarios del servicio (validacion, generacion de codigo, calculo de tarifas). Tests de integracion del endpoint POST. Tests e2e del flujo completo de creacion.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** MAI-001 (Auth - autenticacion y permisos), MAI-002 (Clientes - catalogo de shippers/consignees y tarifas)
|
||||
- **Bloquea:** US-MAI003-002 (paradas), US-MAI003-003 (restricciones), US-MAI003-004 (embarques), US-MAI003-005 (consulta status), US-MAI003-006 (modificar), US-MAI003-007 (cancelar)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** POST `/api/v1/ordenes-transporte`
|
||||
- **Entity:** `OrdenTransporte` -> `transport.ordenes_transporte`
|
||||
- **RLS:** La politica `tenant_isolation_ot` filtra por `tenant_id = current_setting('app.tenant_id')::uuid`
|
||||
- **Generacion de codigo:** Implementar secuencia por tenant, formato sugerido: `OT-{YYYY}-{SECUENCIAL:5}`
|
||||
- **Calculo de tarifa:** Consultar tarifa vigente del modulo MAI-002, aplicar recargos del catalogo de billing, calcular IVA al 16%
|
||||
- **Coordenadas:** Campos `origen_latitud`, `origen_longitud`, `destino_latitud`, `destino_longitud` como DECIMAL(10,7) para precision de ~1cm
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-001 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,78 @@
|
||||
# US-MAI003-002: Agregar multiples paradas a OT
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-002 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** coordinador de trafico de una empresa transportista,
|
||||
**quiero** definir multiples paradas (recoleccion, entrega, escala) asociadas a un viaje que agrupe varias OTs,
|
||||
**para** optimizar rutas multi-drop y atender a varios clientes o destinos en un mismo recorrido.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
El transporte de carga frecuentemente requiere rutas con multiples puntos de recoleccion y entrega (multi-drop). La tabla `paradas_viaje` permite definir una secuencia ordenada de paradas asociadas a un viaje, donde cada parada tiene un tipo (RECOLECCION, ENTREGA o ESCALA), ubicacion georreferenciada, horarios programados y reales, contacto en sitio, y las OTs asociadas a esa parada especifica.
|
||||
|
||||
Las paradas se vinculan al viaje (viaje_id) y cada parada referencia las OTs que se recolectan o entregan en ese punto mediante el campo ots_ids (array de UUIDs). La secuencia numerica determina el orden de visita. Al crear las paradas, el sistema debe validar que la secuencia sea consecutiva y que las OTs referenciadas existan y pertenezcan al mismo tenant.
|
||||
|
||||
Esta funcionalidad es critica para operaciones LTL (Less Than Truckload) donde se consolida carga de distintos clientes u origenes en un mismo viaje, asi como para entregas multi-destino donde un shipper necesita distribuir mercancia a varios consignees.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Agregar paradas secuenciales a un viaje
|
||||
|
||||
**Dado** que existe un viaje creado en estado BORRADOR con al menos una OT asignada,
|
||||
**Cuando** el coordinador agrega paradas indicando tipo, direccion, secuencia y OTs asociadas,
|
||||
**Entonces** el sistema registra cada parada en `transport.paradas_viaje` con la secuencia correcta, respetando la constraint uq_parada_viaje_secuencia que garantiza unicidad de secuencia por viaje.
|
||||
|
||||
### Escenario 2: Validacion de secuencia unica
|
||||
|
||||
**Dado** que un viaje ya tiene paradas con secuencias 1, 2 y 3,
|
||||
**Cuando** el coordinador intenta agregar una nueva parada con secuencia 2,
|
||||
**Entonces** el sistema rechaza la operacion indicando que la secuencia 2 ya esta asignada en ese viaje.
|
||||
|
||||
### Escenario 3: Parada con datos de contacto y horarios
|
||||
|
||||
**Dado** que el coordinador esta agregando una parada de tipo ENTREGA,
|
||||
**Cuando** completa los datos de ubicacion (direccion, ciudad, estado, coordenadas), contacto (nombre, telefono) y horarios programados (hora_programada_llegada, hora_programada_salida),
|
||||
**Entonces** el sistema almacena todos los datos y los disponibiliza para el operador durante la ejecucion del viaje.
|
||||
|
||||
### Escenario 4: Asociar OTs a paradas especificas
|
||||
|
||||
**Dado** que un viaje tiene 3 OTs asignadas y el coordinador esta definiendo paradas,
|
||||
**Cuando** asocia la OT-001 a la parada 1 (RECOLECCION) y las OTs OT-002 y OT-003 a la parada 2 (ENTREGA),
|
||||
**Entonces** el campo ots_ids de cada parada contiene los UUIDs correctos de las OTs asociadas.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Verificar que la tabla `transport.paradas_viaje` existe con todos los campos: secuencia, tipo (RECOLECCION/ENTREGA/ESCALA), datos de ubicacion, contacto, horarios programados/reales, ots_ids (UUID[]), estado y observaciones. Verificar indice idx_parada_viaje y constraint uq_parada_viaje_secuencia.
|
||||
- **Backend:** Crear entity `ParadaViaje` mapeada a `transport.paradas_viaje`. Crear `ParadaViajeService` con metodos `createParada()`, `reorderParadas()` y `assignOtsToParada()`. Crear `ParadaViajeController` con endpoints anidados bajo viaje: POST `/api/v1/viajes/:viajeId/paradas`, PATCH `/api/v1/viajes/:viajeId/paradas/:id`. Crear DTOs: `CreateParadaViajeDto`, `UpdateParadaViajeDto`.
|
||||
- **Frontend:** Crear componente `ParadasViajeList` con vista tipo timeline/sortable para las paradas. Incluir formulario de parada con mapa para seleccionar ubicacion. Permitir drag-and-drop para reordenar secuencia.
|
||||
- **Tests:** Tests unitarios de validacion de secuencia y asociacion de OTs. Tests de integracion del CRUD de paradas. Test de constraint de secuencia unica.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (las OTs deben existir), MAI-004 (el viaje debe existir para asociar paradas)
|
||||
- **Bloquea:** MAI-005 (Despacho - las paradas son parte de la orden de viaje), MAI-006 (Tracking - los eventos se registran por parada), MAI-007 (POD - la evidencia se captura por parada)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** POST `/api/v1/viajes/:viajeId/paradas`
|
||||
- **Entity:** `ParadaViaje` -> `transport.paradas_viaje`
|
||||
- **RLS:** Politica `tenant_isolation_paradas` filtra por `tenant_id`
|
||||
- **Campo ots_ids:** Es un array nativo de PostgreSQL (UUID[]), no una relacion FK tradicional. En TypeORM se mapea como `@Column({ type: 'uuid', array: true, nullable: true })`
|
||||
- **Tipos de parada:** 'RECOLECCION' (pickup), 'ENTREGA' (drop-off), 'ESCALA' (waypoint/stop intermedio)
|
||||
- **Constraint:** uq_parada_viaje_secuencia(viaje_id, secuencia) impide secuencias duplicadas en un mismo viaje
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-002 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,77 @@
|
||||
# US-MAI003-003: Definir restricciones logisticas
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-003 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador de una empresa transportista,
|
||||
**quiero** definir restricciones logisticas especificas para cada orden de transporte (temperatura, GPS, escolta, cita, instrucciones especiales),
|
||||
**para** asegurar que la planeacion y ejecucion del servicio cumplan con los requisitos del cliente y la naturaleza de la carga.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
Las restricciones logisticas son requisitos adicionales que condicionan como debe ejecutarse el servicio de transporte. Estas restricciones van mas alla de los datos basicos de la OT y determinan el tipo de equipo, la seguridad y las condiciones especiales que se deben cumplir durante el viaje.
|
||||
|
||||
La tabla `ordenes_transporte` incluye campos booleanos y de parametros para estas restricciones: `requiere_temperatura` con rangos `temperatura_min` y `temperatura_max` (para carga refrigerada o de cadena de frio), `requiere_gps` (para seguimiento obligatorio), `requiere_escolta` (para carga de alto valor o zona de riesgo), `requiere_cita` (para destinos con sistema de appointment), e `instrucciones_especiales` (texto libre para indicaciones particulares del cliente).
|
||||
|
||||
Estas restricciones alimentan la planeacion (MAI-004) para seleccionar la unidad y operador adecuados, el despacho (MAI-005) para verificar el cumplimiento del checklist, y el tracking (MAI-006) para configurar alertas especificas.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Definir requisito de temperatura
|
||||
|
||||
**Dado** que el despachador esta creando o editando una OT con tipo_carga REFRIGERADA,
|
||||
**Cuando** activa requiere_temperatura e ingresa temperatura_min (-5.00) y temperatura_max (2.00),
|
||||
**Entonces** el sistema almacena los rangos de temperatura y los validara contra las capacidades de la unidad asignada en la fase de planeacion.
|
||||
|
||||
### Escenario 2: Activar multiples restricciones de seguridad
|
||||
|
||||
**Dado** que el despachador esta registrando una OT para carga de alto valor,
|
||||
**Cuando** activa requiere_gps y requiere_escolta simultaneamente,
|
||||
**Entonces** el sistema registra ambas restricciones y estas seran visibles en el tablero de planeacion como requisitos obligatorios para la asignacion de recursos.
|
||||
|
||||
### Escenario 3: Registrar instrucciones especiales
|
||||
|
||||
**Dado** que el cliente tiene requerimientos operativos particulares,
|
||||
**Cuando** el despachador ingresa instrucciones especiales (por ejemplo: "Entregar solo en horario matutino. Requiere montacargas en destino. Contactar al Sr. Lopez 30 minutos antes de arribo."),
|
||||
**Entonces** el sistema almacena el texto completo y lo incluye en la informacion visible para el operador durante la ejecucion del viaje.
|
||||
|
||||
### Escenario 4: Validacion de rango de temperatura
|
||||
|
||||
**Dado** que el despachador activa requiere_temperatura,
|
||||
**Cuando** ingresa temperatura_min mayor que temperatura_max,
|
||||
**Entonces** el sistema muestra un error de validacion indicando que la temperatura minima no puede ser mayor que la maxima.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Los campos ya existen en `transport.ordenes_transporte`: requiere_temperatura (BOOLEAN DEFAULT FALSE), temperatura_min (DECIMAL(5,2)), temperatura_max (DECIMAL(5,2)), requiere_gps (BOOLEAN DEFAULT FALSE), requiere_escolta (BOOLEAN DEFAULT FALSE), requiere_cita (BOOLEAN DEFAULT FALSE), instrucciones_especiales (TEXT).
|
||||
- **Backend:** Extender `CreateOrdenTransporteDto` y `UpdateOrdenTransporteDto` con campos de restricciones. Agregar validacion en el servicio: si requiere_temperatura es true, temperatura_min y temperatura_max son obligatorios y temperatura_min debe ser menor que temperatura_max. Agregar logica de compatibilidad que sera consumida por MAI-004 para validar capacidades de unidad.
|
||||
- **Frontend:** Crear seccion "Restricciones Logisticas" en el formulario de OT con toggles para cada requisito. Mostrar campos de temperatura condicionalmente cuando requiere_temperatura esta activo. Incluir campo de texto enriquecido para instrucciones especiales.
|
||||
- **Tests:** Tests unitarios de validacion de rangos de temperatura. Tests de validacion de datos obligatorios condicionales. Tests de integracion con persistencia de restricciones.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (la OT debe existir primero)
|
||||
- **Bloquea:** MAI-004 (Planeacion - usa restricciones para compatibilidad de recursos), MAI-005 (Despacho - verifica cumplimiento en checklist), MAI-006 (Tracking - configura alertas por restriccion)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** PATCH `/api/v1/ordenes-transporte/:id` (actualizacion parcial de campos de restricciones)
|
||||
- **Entity:** Campos adicionales en `OrdenTransporte` entity
|
||||
- **Validacion condicional:** Usar decoradores de class-validator como `@ValidateIf(o => o.requiere_temperatura === true)` para temperatura_min y temperatura_max
|
||||
- **Compatibilidad futura:** Las restricciones seran leidas por el motor de planeacion de MAI-004 para filtrar unidades aptas (por ejemplo, solo unidades con refrigeracion si requiere_temperatura es true)
|
||||
- **Tipos de carga y restricciones:** PELIGROSA implica automaticamente requiere_gps = true; REFRIGERADA implica requiere_temperatura = true (sugerencia al usuario, no forzado)
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-003 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,78 @@
|
||||
# US-MAI003-004: Agrupar OTs en embarque
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-004 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P0 |
|
||||
| **Story Points** | 8 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** coordinador de trafico de una empresa transportista,
|
||||
**quiero** agrupar multiples ordenes de transporte en un embarque de consolidacion,
|
||||
**para** optimizar la capacidad de las unidades, reducir costos operativos y asignar el grupo completo a un viaje.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
Un embarque (shipment) es una agrupacion logica de OTs que se transportaran juntas. La consolidacion es una practica fundamental en el transporte de carga, especialmente en modalidad LTL (Less Than Truckload), donde se combinan cargas parciales de distintos clientes o destinos para aprovechar al maximo la capacidad de la unidad.
|
||||
|
||||
La tabla `transport.embarques` almacena el codigo unico del embarque, una descripcion, el cliente principal, los totales consolidados (total_ots, peso_total_kg, volumen_total_m3), el estado del embarque y la referencia al viaje asignado. Al agregar OTs a un embarque, el sistema actualiza el campo `embarque_id` en cada OT y recalcula los totales consolidados del embarque.
|
||||
|
||||
El coordinador debe poder crear un embarque, buscar OTs confirmadas compatibles (por zona, ventana de tiempo, tipo de carga) y agregarlas al embarque. Al completar la agrupacion, el embarque puede asignarse a un viaje para su ejecucion.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Crear embarque nuevo
|
||||
|
||||
**Dado** que el coordinador tiene permisos de creacion de embarques,
|
||||
**Cuando** ingresa codigo, descripcion y selecciona el cliente principal,
|
||||
**Entonces** el sistema crea el embarque en estado ABIERTO con total_ots = 0 y genera un registro en `transport.embarques` con constraint uq_embarque_tenant_codigo.
|
||||
|
||||
### Escenario 2: Agregar OTs al embarque
|
||||
|
||||
**Dado** que existe un embarque en estado ABIERTO y hay OTs en estado CONFIRMADA del mismo tenant,
|
||||
**Cuando** el coordinador selecciona 3 OTs y las agrega al embarque,
|
||||
**Entonces** el sistema actualiza embarque_id en cada OT, recalcula total_ots (3), peso_total_kg (suma de peso_kg de las 3 OTs) y volumen_total_m3 (suma de volumen_m3 de las 3 OTs).
|
||||
|
||||
### Escenario 3: Remover OT de un embarque
|
||||
|
||||
**Dado** que un embarque tiene 3 OTs agrupadas y ninguna esta en estado EN_PROCESO o posterior,
|
||||
**Cuando** el coordinador remueve una OT del embarque,
|
||||
**Entonces** el sistema limpia el campo embarque_id de la OT removida, recalcula los totales del embarque (total_ots = 2, peso y volumen actualizados).
|
||||
|
||||
### Escenario 4: Asignar embarque a viaje
|
||||
|
||||
**Dado** que un embarque tiene al menos una OT agrupada,
|
||||
**Cuando** el coordinador asigna el embarque a un viaje existente,
|
||||
**Entonces** el sistema actualiza viaje_id en el embarque, actualiza viaje_id y embarque_id en cada OT del embarque, y cambia el estado de las OTs de CONFIRMADA a ASIGNADA.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Verificar tabla `transport.embarques` con campos: codigo (VARCHAR(50)), descripcion (VARCHAR(500)), cliente_id (UUID), total_ots (INT DEFAULT 0), peso_total_kg (DECIMAL(12,2)), volumen_total_m3 (DECIMAL(12,4)), estado (VARCHAR(20) DEFAULT 'ABIERTO'), viaje_id (UUID). Verificar indices idx_embarque_tenant e idx_embarque_cliente. Verificar constraint uq_embarque_tenant_codigo.
|
||||
- **Backend:** Crear entity `Embarque` mapeada a `transport.embarques`. Crear `EmbarqueService` con metodos: `create()`, `addOts()`, `removeOt()`, `assignToViaje()`, `recalcularTotales()`. Crear `EmbarqueController` con endpoints: POST `/api/v1/embarques`, GET `/api/v1/embarques`, GET `/api/v1/embarques/:id`, POST `/api/v1/embarques/:id/ots` (agregar OTs), DELETE `/api/v1/embarques/:id/ots/:otId` (remover OT), PATCH `/api/v1/embarques/:id/asignar-viaje`. Crear DTOs correspondientes.
|
||||
- **Frontend:** Crear pagina `EmbarquesListPage` con listado de embarques y conteo de OTs. Crear pagina `EmbarqueDetailPage` con detalle del embarque y lista de OTs agrupadas. Implementar selector de OTs disponibles (CONFIRMADA, sin embarque) con filtros. Incluir resumen visual de capacidad (peso/volumen utilizados).
|
||||
- **Tests:** Tests unitarios de recalculo de totales. Tests de integracion del flujo completo (crear embarque, agregar OTs, asignar a viaje). Tests de validacion de estados permitidos.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (las OTs deben existir y estar CONFIRMADAS), MAI-002 (datos de clientes para cliente_id del embarque)
|
||||
- **Bloquea:** MAI-004 (Planeacion - el embarque es la unidad de asignacion a viajes), MAI-005 (Despacho - el despacho opera sobre viajes con embarques)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoints:** POST `/api/v1/embarques`, POST `/api/v1/embarques/:id/ots`, PATCH `/api/v1/embarques/:id/asignar-viaje`
|
||||
- **Entity:** `Embarque` -> `transport.embarques`
|
||||
- **RLS:** Politica `tenant_isolation_embarques` filtra por `tenant_id`
|
||||
- **Recalculo atomico:** El metodo `recalcularTotales()` debe ejecutarse en una transaccion que actualice las OTs y los totales del embarque de forma atomica
|
||||
- **Generacion de codigo:** Formato sugerido: `EMB-{YYYY}-{SECUENCIAL:5}`
|
||||
- **Validaciones de negocio:** Solo OTs en estado CONFIRMADA pueden agregarse a un embarque. Una OT solo puede pertenecer a un embarque a la vez (embarque_id es nullable pero unico por OT activa). Al asignar a viaje, todas las OTs del embarque pasan a estado ASIGNADA
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-004 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,77 @@
|
||||
# US-MAI003-005: Consultar status de OT
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-005 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 3 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador o ejecutivo de cuenta de una empresa transportista,
|
||||
**quiero** consultar el estado actual y el historial de una orden de transporte,
|
||||
**para** informar al cliente sobre el progreso de su envio y tomar decisiones operativas oportunas.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
La consulta de status de OT es una operacion frecuente en el dia a dia operativo. Los despachadores y ejecutivos de cuenta necesitan verificar rapidamente en que fase se encuentra cada OT para responder consultas de clientes, coordinar con el equipo de planeacion y monitorear el avance general de las operaciones.
|
||||
|
||||
La consulta muestra el estado actual de la OT (BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA o CANCELADA), los datos principales del servicio (shipper, consignee, origen, destino, fechas programadas), la asignacion operativa (embarque y viaje asociados si existen) y los datos financieros (tarifa, total).
|
||||
|
||||
Adicionalmente, el sistema debe mostrar un timeline con las transiciones de estado de la OT, incluyendo fecha/hora y usuario responsable de cada cambio, utilizando los campos de auditoria (created_at, updated_at, created_by_id, updated_by_id).
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Consulta por codigo de OT
|
||||
|
||||
**Dado** que existe una OT con codigo OT-2026-00015 en el tenant actual,
|
||||
**Cuando** el usuario busca por codigo "OT-2026-00015",
|
||||
**Entonces** el sistema muestra la vista de detalle con el estado actual, datos del servicio, ubicaciones, carga, tarifa, embarque y viaje asociados.
|
||||
|
||||
### Escenario 2: Visualizacion del estado actual con indicador visual
|
||||
|
||||
**Dado** que una OT se encuentra en estado EN_PROCESO,
|
||||
**Cuando** el usuario consulta el detalle de la OT,
|
||||
**Entonces** el sistema muestra un indicador visual (badge de color) del estado actual y un timeline que refleja los estados por los que ha pasado la OT con fecha, hora y usuario de cada transicion.
|
||||
|
||||
### Escenario 3: Consulta de OT con embarque y viaje asociados
|
||||
|
||||
**Dado** que una OT esta en estado ASIGNADA con embarque_id y viaje_id poblados,
|
||||
**Cuando** el usuario consulta el detalle,
|
||||
**Entonces** el sistema muestra los datos del embarque (codigo, total de OTs, peso/volumen total) y del viaje (codigo, unidad, operador, fechas de salida/llegada programadas) con enlaces para navegar al detalle de cada uno.
|
||||
|
||||
### Escenario 4: Consulta de OT inexistente
|
||||
|
||||
**Dado** que el usuario busca una OT con un ID o codigo que no existe en su tenant,
|
||||
**Cuando** realiza la consulta,
|
||||
**Entonces** el sistema devuelve un error 404 con mensaje "Orden de transporte no encontrada".
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Utilizar las tablas existentes `transport.ordenes_transporte`, `transport.embarques` y `transport.viajes` con JOINs para obtener datos relacionados. Los indices idx_ot_tenant y uq_ot_tenant_codigo soportan la busqueda por id y codigo.
|
||||
- **Backend:** Agregar metodo `findById()` y `findByCodigo()` en `OrdenTransporteService` que retorne la OT con relaciones cargadas (embarque, viaje). Configurar endpoint GET `/api/v1/ordenes-transporte/:id` con query parameter opcional `?include=embarque,viaje` para cargar relaciones. Crear `OrdenTransporteDetailDto` con datos completos de la OT.
|
||||
- **Frontend:** Crear pagina `OrdenTransporteDetailPage` con secciones: informacion general, origen/destino (con mapa), datos de carga, restricciones, tarifa/costos, embarque asignado, viaje asignado, timeline de estados. Implementar badge de colores por estado. Incluir acciones contextuales segun estado (confirmar, cancelar, editar).
|
||||
- **Tests:** Tests unitarios de consulta por id y codigo. Tests de integracion del endpoint GET con relaciones. Tests de manejo de OT inexistente (404).
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (la OT debe existir)
|
||||
- **Bloquea:** Ninguno directamente (funcionalidad de solo lectura)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** GET `/api/v1/ordenes-transporte/:id`
|
||||
- **Query params:** `?include=embarque,viaje` para cargar relaciones lazy
|
||||
- **RLS:** La consulta esta automaticamente filtrada por tenant_id via RLS policy
|
||||
- **Timeline:** Dado que la tabla no almacena un historial explícito de transiciones, inicialmente el timeline se construye con created_at (creacion) y updated_at (ultima actualizacion). En una fase futura se recomienda implementar una tabla de historial de estados o usar la tabla de auditoria del modulo MAI-001
|
||||
- **Performance:** La consulta por UUID (PK) es O(1). La consulta por codigo usa el indice uq_ot_tenant_codigo
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-005 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,78 @@
|
||||
# US-MAI003-006: Modificar OT en borrador
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-006 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador de una empresa transportista,
|
||||
**quiero** modificar los datos de una orden de transporte que se encuentra en estado BORRADOR,
|
||||
**para** corregir errores, completar informacion faltante o actualizar datos antes de confirmar la OT para planeacion.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
Cuando una OT se crea en estado BORRADOR, es comun que el despachador necesite volver a editarla para completar datos que no estaban disponibles al momento de la creacion inicial, corregir errores de captura, o actualizar informacion proporcionada por el cliente. El sistema debe permitir la modificacion completa de todos los campos de la OT mientras se encuentre en estado BORRADOR.
|
||||
|
||||
Una vez que la OT cambia a estado CONFIRMADA o cualquier estado posterior, los datos se consideran bloqueados para edicion. Esta restriccion protege la integridad de la informacion operativa, ya que una OT confirmada puede estar siendo procesada por planeacion, asignada a un viaje, o en ejecucion.
|
||||
|
||||
La modificacion debe registrar el usuario que realiza el cambio (updated_by_id) y la fecha de actualizacion (updated_at), manteniendo la trazabilidad completa de cambios.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Modificacion exitosa en estado BORRADOR
|
||||
|
||||
**Dado** que existe una OT en estado BORRADOR,
|
||||
**Cuando** el despachador modifica los datos de carga (peso_kg de 5000 a 7500, pallets de 10 a 15) y guarda los cambios,
|
||||
**Entonces** el sistema actualiza los campos modificados, recalcula tarifa/total si aplica, registra updated_by_id y updated_at, y muestra la OT actualizada.
|
||||
|
||||
### Escenario 2: Rechazo de modificacion en estado CONFIRMADA
|
||||
|
||||
**Dado** que existe una OT en estado CONFIRMADA,
|
||||
**Cuando** el despachador intenta modificar cualquier campo de la OT,
|
||||
**Entonces** el sistema rechaza la operacion con error 422 y mensaje "Solo se pueden modificar ordenes de transporte en estado BORRADOR".
|
||||
|
||||
### Escenario 3: Recalculo automatico de tarifas al modificar carga
|
||||
|
||||
**Dado** que una OT en BORRADOR tiene una tarifa asignada de tipo POR_TONELADA,
|
||||
**Cuando** el despachador modifica el peso_kg de la carga,
|
||||
**Entonces** el sistema recalcula automaticamente tarifa_base, subtotal, IVA y total basandose en el nuevo peso y la tarifa asociada.
|
||||
|
||||
### Escenario 4: Modificacion parcial de datos
|
||||
|
||||
**Dado** que una OT en BORRADOR tiene datos completos,
|
||||
**Cuando** el despachador envia una actualizacion parcial (solo cambia destino_direccion y destino_ciudad),
|
||||
**Entonces** el sistema actualiza unicamente los campos enviados sin afectar los demas datos de la OT.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Utilizar la tabla `transport.ordenes_transporte` existente. Los campos updated_at y updated_by_id registran la ultima modificacion. Soft delete via deleted_at.
|
||||
- **Backend:** Agregar metodo `update()` en `OrdenTransporteService` con validacion de estado: solo permitir actualizacion si estado = BORRADOR. Implementar actualizacion parcial (PATCH semantics). Agregar logica de recalculo de tarifas cuando se modifican campos de carga y hay tarifa_id asignada. Configurar endpoint PATCH `/api/v1/ordenes-transporte/:id`. Crear `UpdateOrdenTransporteDto` con todos los campos opcionales y validaciones condicionales.
|
||||
- **Frontend:** Reutilizar el formulario de creacion de OT en modo edicion. Deshabilitar el boton de edicion si el estado no es BORRADOR. Mostrar mensaje informativo cuando la OT no es editable. Al guardar, mostrar resumen de campos modificados antes de confirmar.
|
||||
- **Tests:** Tests unitarios de validacion de estado para edicion. Tests de actualizacion parcial (solo campos enviados). Tests de recalculo de tarifas al modificar carga. Tests de rechazo en estados no editables.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (la OT debe existir en estado BORRADOR)
|
||||
- **Bloquea:** Ninguno directamente (mejora la experiencia de captura de datos)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** PATCH `/api/v1/ordenes-transporte/:id`
|
||||
- **Entity:** `OrdenTransporte` -> `transport.ordenes_transporte`
|
||||
- **Validacion de estado:** En el servicio, antes de aplicar cambios, verificar que `ot.estado === EstadoOrden.BORRADOR`. Si no, lanzar excepcion `UnprocessableEntityException`
|
||||
- **Actualizacion parcial:** Utilizar PATCH semantics donde solo los campos presentes en el body se actualizan. El DTO debe tener todos los campos como opcionales con `@IsOptional()`
|
||||
- **Recalculo de tarifa:** Si se modifica peso_kg, volumen_m3, piezas o pallets y existe tarifa_id, ejecutar el calculo de tarifa del servicio de MAI-002
|
||||
- **Auditoria:** Siempre actualizar `updated_at = NOW()` y `updated_by_id = currentUserId` en cada operacion de update
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-006 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,79 @@
|
||||
# US-MAI003-007: Cancelar OT
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-007 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 3 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador o coordinador de una empresa transportista,
|
||||
**quiero** cancelar una orden de transporte que ya no sera ejecutada,
|
||||
**para** liberar los recursos asociados y mantener actualizado el estado de las operaciones con un registro claro del motivo de cancelacion.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
La cancelacion de una OT es una operacion necesaria cuando el cliente retira la solicitud, se duplica una orden, o se presentan circunstancias que impiden la ejecucion del servicio. El sistema debe permitir cancelar OTs en estados previos a la ejecucion (BORRADOR, CONFIRMADA y ASIGNADA), pero no una vez que el viaje esta en proceso o completado.
|
||||
|
||||
Al cancelar, el sistema debe registrar el motivo de cancelacion y marcar la OT con estado CANCELADA y deleted_at como fecha de cancelacion logica. Si la OT estaba agrupada en un embarque, debe removerse automaticamente y recalcular los totales del embarque. Si estaba asignada a un viaje, se debe evaluar si el viaje puede continuar sin esa OT.
|
||||
|
||||
La cancelacion es una operacion irreversible: una OT cancelada no puede volver a un estado activo. Si se necesita reactivar, se debe crear una nueva OT.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Cancelar OT en estado BORRADOR
|
||||
|
||||
**Dado** que existe una OT en estado BORRADOR,
|
||||
**Cuando** el despachador solicita la cancelacion con motivo "Solicitud retirada por el cliente",
|
||||
**Entonces** el sistema cambia el estado a CANCELADA, registra deleted_at con la fecha actual, registra updated_by_id con el usuario que cancela, y la OT deja de aparecer en listados activos.
|
||||
|
||||
### Escenario 2: Cancelar OT CONFIRMADA que pertenece a un embarque
|
||||
|
||||
**Dado** que una OT en estado CONFIRMADA esta agrupada en un embarque con 3 OTs,
|
||||
**Cuando** el coordinador cancela la OT con motivo "Carga no disponible en origen",
|
||||
**Entonces** el sistema cambia la OT a CANCELADA, la remueve del embarque (limpia embarque_id), recalcula los totales del embarque (total_ots = 2, peso y volumen actualizados).
|
||||
|
||||
### Escenario 3: Rechazo de cancelacion en estado EN_PROCESO
|
||||
|
||||
**Dado** que una OT se encuentra en estado EN_PROCESO (viaje en curso),
|
||||
**Cuando** el usuario intenta cancelar la OT,
|
||||
**Entonces** el sistema rechaza la operacion con error 422 y mensaje "No se puede cancelar una orden de transporte en estado EN_PROCESO. Registre una incidencia en su lugar."
|
||||
|
||||
### Escenario 4: Motivo de cancelacion obligatorio
|
||||
|
||||
**Dado** que el usuario solicita cancelar una OT en estado valido,
|
||||
**Cuando** no proporciona un motivo de cancelacion,
|
||||
**Entonces** el sistema rechaza la operacion indicando que el motivo de cancelacion es obligatorio.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Utilizar campo `estado` para marcar como CANCELADA y `deleted_at` para soft delete. El campo `deleted_at` (TIMESTAMPTZ) sirve como fecha de cancelacion logica.
|
||||
- **Backend:** Agregar metodo `cancelar(id, motivo, userId)` en `OrdenTransporteService` con validacion de estado: solo permitir cancelacion desde BORRADOR, CONFIRMADA o ASIGNADA. Si la OT tiene embarque_id, invocar `EmbarqueService.removeOt()` para limpiar la referencia y recalcular totales. Configurar endpoint PATCH `/api/v1/ordenes-transporte/:id/cancelar`. Crear `CancelarOrdenTransporteDto` con campo obligatorio `motivo`.
|
||||
- **Frontend:** Agregar boton "Cancelar OT" visible solo en estados BORRADOR, CONFIRMADA y ASIGNADA. Al presionar, mostrar dialogo de confirmacion con campo obligatorio de motivo. Tras cancelacion exitosa, redirigir al listado con mensaje de confirmacion.
|
||||
- **Tests:** Tests unitarios de validacion de estados permitidos para cancelacion. Tests de integracion del flujo con embarque (remocion y recalculo). Tests de motivo obligatorio. Tests de rechazo en estados no cancelables.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (la OT debe existir), US-MAI003-004 (logica de remocion de embarque)
|
||||
- **Bloquea:** Ninguno directamente (flujo terminal)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** PATCH `/api/v1/ordenes-transporte/:id/cancelar`
|
||||
- **Body:** `{ "motivo": "string (requerido)" }`
|
||||
- **Estados cancelables:** BORRADOR, CONFIRMADA, ASIGNADA
|
||||
- **Estados no cancelables:** EN_PROCESO, COMPLETADA, FACTURADA, CANCELADA
|
||||
- **Soft delete:** `deleted_at = NOW()` marca la cancelacion logica. Los listados por defecto filtran `WHERE deleted_at IS NULL`
|
||||
- **Efecto cascada:** Si la OT pertenece a un embarque, el servicio debe: 1) limpiar embarque_id de la OT, 2) recalcular totales del embarque, 3) si el embarque queda sin OTs, evaluar si se cierra automaticamente
|
||||
- **Irreversibilidad:** No existe endpoint para reactivar una OT cancelada. El motivo de cancelacion se almacena en la columna instrucciones_especiales o en una tabla de auditoria dedicada
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-007 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,77 @@
|
||||
# US-MAI003-008: Buscar OTs con filtros avanzados
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-008 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P1 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador, coordinador o ejecutivo de cuenta de una empresa transportista,
|
||||
**quiero** buscar ordenes de transporte utilizando multiples filtros combinados (estado, cliente, fechas, tipo de carga, codigo),
|
||||
**para** localizar rapidamente las OTs que necesito gestionar y tener visibilidad del estado de las operaciones.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
El listado de OTs con filtros avanzados es la pantalla principal del modulo de ordenes de transporte. Los usuarios necesitan filtrar y navegar grandes volumenes de OTs de forma eficiente. La tabla `ordenes_transporte` cuenta con indices especificos para las columnas de filtrado mas frecuentes: idx_ot_estado (tenant_id, estado), idx_ot_shipper (tenant_id, shipper_id) e idx_ot_fechas (tenant_id, fecha_recoleccion_programada).
|
||||
|
||||
El sistema debe soportar filtros combinados por: estado de la OT (uno o varios), shipper (cliente), rango de fechas de recoleccion y entrega, tipo de carga, codigo de OT (busqueda parcial), referencia del cliente, y existencia de embarque o viaje asignado. Los resultados deben ser paginados, ordenables por cualquier columna, y la respuesta debe incluir metadatos de paginacion.
|
||||
|
||||
La busqueda por codigo y referencia_cliente debe soportar coincidencia parcial (LIKE/ILIKE) para facilitar la localizacion rapida cuando el usuario no recuerda el codigo completo.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Filtrar OTs por estado
|
||||
|
||||
**Dado** que el tenant tiene OTs en distintos estados,
|
||||
**Cuando** el usuario selecciona el filtro estado = "CONFIRMADA",
|
||||
**Entonces** el sistema retorna solo las OTs en estado CONFIRMADA del tenant actual, paginadas con 20 registros por pagina, usando el indice idx_ot_estado.
|
||||
|
||||
### Escenario 2: Filtrar por shipper y rango de fechas
|
||||
|
||||
**Dado** que el usuario necesita ver las OTs de un cliente especifico en enero 2026,
|
||||
**Cuando** selecciona shipper_id = "uuid-cliente-x" y rango fecha_recoleccion_programada entre 2026-01-01 y 2026-01-31,
|
||||
**Entonces** el sistema retorna las OTs que coinciden con ambos criterios, ordenadas por fecha_recoleccion_programada descendente.
|
||||
|
||||
### Escenario 3: Busqueda parcial por codigo
|
||||
|
||||
**Dado** que el usuario recuerda parcialmente el codigo de una OT,
|
||||
**Cuando** ingresa "2026-001" en el campo de busqueda por codigo,
|
||||
**Entonces** el sistema retorna todas las OTs cuyo codigo contiene "2026-001" (busqueda case-insensitive con ILIKE).
|
||||
|
||||
### Escenario 4: Multiples filtros combinados con paginacion
|
||||
|
||||
**Dado** que el usuario aplica filtros de estado (CONFIRMADA, ASIGNADA), tipo_carga (REFRIGERADA) y rango de fechas,
|
||||
**Cuando** la busqueda retorna 85 resultados,
|
||||
**Entonces** el sistema muestra los primeros 20 resultados con metadatos de paginacion: { total: 85, page: 1, pageSize: 20, totalPages: 5 } y permite navegar entre paginas.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Verificar indices existentes: idx_ot_tenant (tenant_id), idx_ot_estado (tenant_id, estado), idx_ot_shipper (tenant_id, shipper_id), idx_ot_fechas (tenant_id, fecha_recoleccion_programada). Evaluar si se requieren indices adicionales para combinaciones frecuentes.
|
||||
- **Backend:** Agregar metodo `findAll(filters, pagination, sort)` en `OrdenTransporteService` con QueryBuilder de TypeORM para construir consultas dinamicas con filtros opcionales. Configurar endpoint GET `/api/v1/ordenes-transporte` con query params: `?estado=CONFIRMADA&shipper_id=uuid&fecha_desde=2026-01-01&fecha_hasta=2026-01-31&tipo_carga=REFRIGERADA&codigo=OT-2026&referencia=PO-123&page=1&pageSize=20&sort=fecha_recoleccion_programada&order=DESC`. Crear `FilterOrdenTransporteDto` con decoradores de validacion y transformacion. Implementar paginacion con respuesta estandar (data, total, page, pageSize, totalPages).
|
||||
- **Frontend:** Crear pagina `OrdenesTransporteListPage` con tabla paginada, columnas ordenables y panel de filtros colapsable. Implementar filtros: dropdown multi-select para estado, autocompletado para shipper, date pickers para rangos de fechas, dropdown para tipo_carga, campo de texto para codigo y referencia. Persistir filtros en URL query params para compartir enlaces. Incluir indicador de resultados totales y paginacion con navegacion por paginas.
|
||||
- **Tests:** Tests unitarios de construccion de query con diferentes combinaciones de filtros. Tests de integracion del endpoint con parametros de busqueda. Tests de paginacion (primera pagina, ultima pagina, fuera de rango). Tests de busqueda parcial por codigo (ILIKE).
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (las OTs deben existir)
|
||||
- **Bloquea:** US-MAI003-009 (la exportacion opera sobre el mismo listado filtrado)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** GET `/api/v1/ordenes-transporte`
|
||||
- **Query params:** `estado` (string o array), `shipper_id` (UUID), `fecha_desde` (ISO date), `fecha_hasta` (ISO date), `tipo_carga` (enum), `codigo` (string, busqueda parcial), `referencia` (string, busqueda parcial), `tiene_embarque` (boolean), `tiene_viaje` (boolean), `page` (int, default 1), `pageSize` (int, default 20, max 100), `sort` (string), `order` (ASC/DESC)
|
||||
- **RLS:** Todas las consultas se filtran automaticamente por tenant_id via la politica tenant_isolation_ot
|
||||
- **Performance:** Filtro por deleted_at IS NULL (soft delete) debe ser la primera condicion. Los indices idx_ot_estado e idx_ot_shipper son parciales por tenant_id, lo que optimiza queries multi-tenant
|
||||
- **Busqueda parcial:** Usar `ILIKE '%valor%'` para codigo y referencia_cliente. Para volumenes muy altos, evaluar pg_trgm para busqueda por trigramas
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-008 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,79 @@
|
||||
# US-MAI003-009: Exportar listado de OTs
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-009 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P2 |
|
||||
| **Story Points** | 3 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** coordinador o ejecutivo de cuenta de una empresa transportista,
|
||||
**quiero** exportar el listado de ordenes de transporte filtrado a formato CSV o Excel,
|
||||
**para** compartir informacion con clientes, generar reportes internos y analizar datos operativos fuera del sistema.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
La exportacion de OTs permite a los usuarios descargar la informacion visible en el listado filtrado en formatos estandar para analisis externo. El usuario aplica los mismos filtros disponibles en la busqueda avanzada (US-MAI003-008) y solicita la descarga en formato CSV o Excel (XLSX).
|
||||
|
||||
El archivo exportado debe incluir las columnas principales de la OT: codigo, referencia del cliente, nombre del shipper, nombre del consignee, ciudades de origen y destino, fechas programadas de recoleccion y entrega, estado actual y total del servicio. El formato Excel incluye ademas encabezados estilizados, formato de fechas y moneda en las celdas.
|
||||
|
||||
Para volumenes mayores a 10,000 registros, la exportacion debe ejecutarse de forma asincrona, notificando al usuario cuando el archivo este listo para descarga. Para volumenes menores, la descarga es directa e inmediata.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Exportar a CSV con filtros aplicados
|
||||
|
||||
**Dado** que el usuario tiene un listado filtrado de OTs (estado = CONFIRMADA, fecha enero 2026, 45 resultados),
|
||||
**Cuando** presiona el boton "Exportar CSV",
|
||||
**Entonces** el sistema genera y descarga un archivo CSV con 45 filas de datos mas encabezado, incluyendo las columnas: codigo, referencia_cliente, shipper_nombre, consignee_nombre, origen_ciudad, destino_ciudad, fecha_recoleccion_programada, fecha_entrega_programada, estado, total.
|
||||
|
||||
### Escenario 2: Exportar a Excel con formato
|
||||
|
||||
**Dado** que el usuario solicita exportacion en formato Excel,
|
||||
**Cuando** selecciona "Exportar Excel",
|
||||
**Entonces** el sistema genera un archivo XLSX con encabezados en negrita, columnas de fecha con formato dd/mm/yyyy, columna total con formato de moneda ($#,##0.00), y ancho de columnas ajustado al contenido.
|
||||
|
||||
### Escenario 3: Exportacion asincrona para grandes volumenes
|
||||
|
||||
**Dado** que el listado filtrado contiene mas de 10,000 registros,
|
||||
**Cuando** el usuario solicita la exportacion,
|
||||
**Entonces** el sistema muestra un mensaje "La exportacion se esta procesando. Recibira una notificacion cuando el archivo este listo." y ejecuta la generacion en segundo plano, notificando al usuario al completarse.
|
||||
|
||||
### Escenario 4: Exportacion sin resultados
|
||||
|
||||
**Dado** que los filtros aplicados no retornan resultados,
|
||||
**Cuando** el usuario intenta exportar,
|
||||
**Entonces** el sistema muestra un mensaje "No hay datos para exportar con los filtros seleccionados" y no genera ningun archivo.
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Reutilizar la misma consulta de `findAll()` de US-MAI003-008 sin paginacion (o con paginacion extendida) para obtener todos los registros del filtro.
|
||||
- **Backend:** Agregar metodo `exportCsv(filters)` y `exportExcel(filters)` en `OrdenTransporteService`. Configurar endpoint GET `/api/v1/ordenes-transporte/exportar?formato=csv` y `formato=xlsx` con los mismos query params de filtros que el listado. Para CSV, usar streaming con content-type text/csv. Para Excel, usar libreria exceljs para generar XLSX en memoria. Implementar logica de exportacion asincrona (Bull queue) cuando el conteo excede 10,000 registros.
|
||||
- **Frontend:** Agregar botones "Exportar CSV" y "Exportar Excel" en la barra de acciones del listado. Los botones envian los filtros actuales al endpoint de exportacion. Para descargas directas, usar window.open o fetch + blob. Para exportaciones asincronas, mostrar snackbar de progreso y notificacion al completar.
|
||||
- **Tests:** Tests unitarios de generacion de CSV (formato, columnas, datos). Tests unitarios de generacion de Excel (formato de celdas). Tests de integracion del endpoint de exportacion. Tests del umbral de exportacion asincrona (>10,000 registros).
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-008 (busqueda con filtros avanzados)
|
||||
- **Bloquea:** Ninguno directamente
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** GET `/api/v1/ordenes-transporte/exportar?formato=csv&estado=CONFIRMADA&fecha_desde=...`
|
||||
- **Content-Type CSV:** `text/csv; charset=utf-8` con header `Content-Disposition: attachment; filename="ordenes-transporte-2026-01-27.csv"`
|
||||
- **Content-Type Excel:** `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` con header `Content-Disposition: attachment; filename="ordenes-transporte-2026-01-27.xlsx"`
|
||||
- **Libreria Excel:** exceljs (compatible con NestJS, soporta streaming para grandes volumenes)
|
||||
- **Limite duro:** Maximo 50,000 registros por exportacion. Si excede, informar al usuario que refine los filtros
|
||||
- **Columnas exportadas:** codigo, referencia_cliente, shipper_nombre, consignee_nombre, origen_ciudad, origen_estado, destino_ciudad, destino_estado, tipo_carga, fecha_recoleccion_programada, fecha_entrega_programada, estado, peso_kg, volumen_m3, piezas, pallets, total, moneda
|
||||
- **Encoding CSV:** UTF-8 con BOM para compatibilidad con Excel en espanol
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-009 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,105 @@
|
||||
# US-MAI003-010: Dashboard de OTs por status
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | US-MAI003-010 |
|
||||
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
|
||||
| **Modulo** | ordenes-transporte |
|
||||
| **Prioridad** | P2 |
|
||||
| **Story Points** | 5 |
|
||||
| **Sprint** | Por asignar |
|
||||
| **Estado** | Backlog |
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** coordinador de trafico o gerente de operaciones de una empresa transportista,
|
||||
**quiero** visualizar un dashboard con el resumen de ordenes de transporte agrupadas por estado,
|
||||
**para** tener una vision rapida del volumen operativo, identificar cuellos de botella y tomar decisiones de asignacion de recursos.
|
||||
|
||||
## Descripcion Detallada
|
||||
|
||||
El dashboard de OTs es la vista ejecutiva del modulo de ordenes de transporte. Presenta contadores y graficos que resumen el estado actual de todas las OTs del tenant, permitiendo al coordinador o gerente identificar rapidamente cuantas OTs estan pendientes de confirmacion, cuantas estan listas para planeacion, cuantas estan en ejecucion y cuantas pendientes de facturacion.
|
||||
|
||||
El dashboard incluye: contadores por estado (tarjetas/cards), un grafico de barras o dona con la distribucion porcentual, OTs proximas a vencer su ventana de entrega (alertas), totales de peso y volumen por estado, y un resumen de OTs creadas vs completadas en el periodo seleccionado.
|
||||
|
||||
Los datos del dashboard deben actualizarse al cargar la pagina y permitir filtrado por rango de fechas para analizar periodos especificos. La consulta principal utiliza el indice idx_ot_estado (tenant_id, estado) para agrupar y contar registros de forma eficiente.
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### Escenario 1: Visualizar contadores por estado
|
||||
|
||||
**Dado** que el tenant tiene OTs en distintos estados,
|
||||
**Cuando** el coordinador accede al dashboard de ordenes de transporte,
|
||||
**Entonces** el sistema muestra tarjetas con el conteo de OTs por cada estado: BORRADOR (12), CONFIRMADA (8), ASIGNADA (15), EN_PROCESO (22), COMPLETADA (5), FACTURADA (45), CANCELADA (3).
|
||||
|
||||
### Escenario 2: Filtrar dashboard por rango de fechas
|
||||
|
||||
**Dado** que el coordinador desea analizar el mes de enero 2026,
|
||||
**Cuando** selecciona el rango de fechas 2026-01-01 a 2026-01-31,
|
||||
**Entonces** los contadores y graficos se actualizan mostrando solo las OTs creadas dentro de ese rango, y el resumen muestra "OTs creadas: 110, OTs completadas: 72, Tasa de completitud: 65.5%".
|
||||
|
||||
### Escenario 3: Alertas de OTs proximas a vencer
|
||||
|
||||
**Dado** que existen OTs en estado CONFIRMADA o ASIGNADA cuya fecha_entrega_programada es dentro de las proximas 24 horas,
|
||||
**Cuando** el coordinador visualiza el dashboard,
|
||||
**Entonces** el sistema muestra una seccion de alertas con las OTs proximas a vencer, incluyendo codigo, shipper_nombre, destino_ciudad y horas restantes para la entrega.
|
||||
|
||||
### Escenario 4: Totales consolidados por estado
|
||||
|
||||
**Dado** que el coordinador necesita dimensionar la carga operativa,
|
||||
**Cuando** visualiza el dashboard,
|
||||
**Entonces** el sistema muestra, ademas de los contadores de OTs, los totales de peso_kg y volumen_m3 agrupados por estado para los estados activos (CONFIRMADA, ASIGNADA, EN_PROCESO).
|
||||
|
||||
## Tareas Tecnicas
|
||||
|
||||
- **Database:** Crear query de agregacion: `SELECT estado, COUNT(*), SUM(peso_kg), SUM(volumen_m3) FROM transport.ordenes_transporte WHERE tenant_id = :tenantId AND deleted_at IS NULL GROUP BY estado`. Utilizar el indice idx_ot_estado para optimizar. Para alertas de vencimiento: query con filtro `fecha_entrega_programada BETWEEN NOW() AND NOW() + INTERVAL '24 hours'` y estado IN ('CONFIRMADA', 'ASIGNADA').
|
||||
- **Backend:** Crear metodo `getDashboard(dateRange?)` en `OrdenTransporteService` que retorne: contadores por estado, totales de peso/volumen por estado, OTs proximas a vencer, resumen de creadas vs completadas en el periodo. Configurar endpoint GET `/api/v1/ordenes-transporte/dashboard?fecha_desde=2026-01-01&fecha_hasta=2026-01-31`. Crear `DashboardOrdenTransporteDto` con la estructura de respuesta.
|
||||
- **Frontend:** Crear pagina `OrdenesTransporteDashboardPage` con: fila de tarjetas/cards por estado con colores (BORRADOR=gris, CONFIRMADA=azul, ASIGNADA=naranja, EN_PROCESO=amarillo, COMPLETADA=verde, FACTURADA=verde oscuro, CANCELADA=rojo). Grafico de dona con libreria recharts o chart.js. Tabla de alertas de OTs proximas a vencer. Selector de rango de fechas con presets (hoy, esta semana, este mes, mes anterior). Totales consolidados de peso y volumen.
|
||||
- **Tests:** Tests unitarios de la query de agregacion. Tests del calculo de tasa de completitud. Tests de integracion del endpoint de dashboard. Tests de filtrado por rango de fechas.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- **Depende de:** US-MAI003-001 (datos de OTs), US-MAI003-008 (indices de busqueda reutilizados)
|
||||
- **Bloquea:** Ninguno directamente (vista de solo lectura ejecutiva)
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **Endpoint:** GET `/api/v1/ordenes-transporte/dashboard`
|
||||
- **Query params:** `fecha_desde` (ISO date, opcional), `fecha_hasta` (ISO date, opcional)
|
||||
- **Respuesta ejemplo:**
|
||||
```json
|
||||
{
|
||||
"contadores": {
|
||||
"BORRADOR": 12,
|
||||
"CONFIRMADA": 8,
|
||||
"ASIGNADA": 15,
|
||||
"EN_PROCESO": 22,
|
||||
"COMPLETADA": 5,
|
||||
"FACTURADA": 45,
|
||||
"CANCELADA": 3
|
||||
},
|
||||
"totales": {
|
||||
"CONFIRMADA": { "peso_kg": 45000, "volumen_m3": 120.5 },
|
||||
"ASIGNADA": { "peso_kg": 78000, "volumen_m3": 210.3 },
|
||||
"EN_PROCESO": { "peso_kg": 112000, "volumen_m3": 305.8 }
|
||||
},
|
||||
"alertas_vencimiento": [
|
||||
{ "id": "uuid", "codigo": "OT-2026-00089", "shipper_nombre": "Acme Corp", "destino_ciudad": "Monterrey", "horas_restantes": 8.5 }
|
||||
],
|
||||
"resumen_periodo": {
|
||||
"creadas": 110,
|
||||
"completadas": 72,
|
||||
"canceladas": 3,
|
||||
"tasa_completitud": 65.45
|
||||
}
|
||||
}
|
||||
```
|
||||
- **RLS:** La query de agregacion esta filtrada por tenant_id automaticamente via la politica tenant_isolation_ot
|
||||
- **Performance:** La query GROUP BY estado con indice idx_ot_estado es eficiente incluso con cientos de miles de registros. Para la alerta de vencimiento, usar indice idx_ot_fechas
|
||||
- **Cache:** Evaluar cache de 30-60 segundos en Redis para el dashboard, ya que no requiere datos en tiempo real exacto
|
||||
|
||||
---
|
||||
|
||||
*US-MAI003-010 - ERP Transportistas v1.0.0*
|
||||
164
docs/02-definicion-modulos/MAI-006-tracking/README.md
Normal file
164
docs/02-definicion-modulos/MAI-006-tracking/README.md
Normal file
@ -0,0 +1,164 @@
|
||||
# MAI-006: Tracking en Tiempo Real
|
||||
|
||||
**Modulo:** MAI-006 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
**Schema BD:** tracking | **DDL:** `database/ddl/03-tracking-schema-ddl.sql`
|
||||
|
||||
---
|
||||
|
||||
## Descripcion
|
||||
|
||||
Sistema de rastreo GPS en tiempo real para unidades de transporte de carga. Permite la ingestion de posiciones GPS, la deteccion automatica de eventos mediante geocercas, el calculo dinamico de ETA y la generacion de alertas operativas. Brinda visibilidad completa del viaje tanto al coordinador de trafico como al cliente final a traves del portal.
|
||||
|
||||
---
|
||||
|
||||
## Componentes Principales
|
||||
|
||||
| Componente | Descripcion |
|
||||
|------------|-------------|
|
||||
| Receptor GPS | Ingestion de posiciones GPS desde dispositivos/proveedores de telematica (latitud, longitud, velocidad, rumbo, odometro, HDOP, satelites) |
|
||||
| Motor de Geocercas | Evaluacion en tiempo real de posiciones contra geocercas poligonales y circulares utilizando PostGIS (ST_DWithin, ST_Contains) |
|
||||
| Calculador ETA | Recalculo dinamico de tiempo estimado de arribo considerando distancia restante, factor de trafico y factor de clima |
|
||||
| Sistema de Alertas | Generacion automatica de alertas por reglas configurables: desvio de ruta, exceso de velocidad, parada prolongada, entrada/salida de geocerca, boton de panico, entre otros |
|
||||
| Historial de Tracking | Almacenamiento particionado por fecha de todas las posiciones GPS para consulta historica y generacion de reportes de recorrido |
|
||||
| Mapa en Tiempo Real | Visualizacion en mapa de la posicion actual de todas las unidades de la flota con actualizacion via WebSocket |
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|-----------------|
|
||||
| Coordinador de Trafico | Monitorea flota en tiempo real, atiende alertas, valida desvios, configura geocercas y reglas de alerta |
|
||||
| Cliente (Portal) | Consulta posicion actual de su envio, ETA dinamico, historial de eventos del viaje |
|
||||
| Sistema Automatico | Procesa posiciones GPS, evalua geocercas, genera alertas, recalcula ETAs, envia notificaciones |
|
||||
| Operador/Conductor | Genera eventos manuales desde app movil (arribo, incidente), porta dispositivo GPS |
|
||||
| Jefe de Flota | Consulta dashboard de flota, analiza reportes de recorrido y eficiencia |
|
||||
|
||||
---
|
||||
|
||||
## Funcionalidades
|
||||
|
||||
### F1. Ingestion de Eventos GPS
|
||||
Recepcion y almacenamiento de posiciones GPS provenientes de dispositivos de telematica. Cada evento incluye: latitud, longitud, altitud, velocidad en km/h, rumbo (0-360 grados), odometro, estado del motor, HDOP (precision horizontal), numero de satelites, IMEI del dispositivo y proveedor GPS. Las posiciones se almacenan en la tabla `tracking.posiciones_gps`, particionada mensualmente por `fecha_particion` para optimizar consultas historicas.
|
||||
|
||||
### F2. Geocercas (Geofencing)
|
||||
Definicion de zonas de interes como geocercas circulares (centro + radio en metros) o poligonales (geometria POLYGON SRID 4326). Tipos soportados: CLIENTE, PROVEEDOR, PATIO, ZONA_RIESGO, CASETA, GASOLINERA, PUNTO_CONTROL, OTRO. Cada geocerca puede configurarse con alertas de entrada y/o salida y un tiempo maximo de permanencia. El motor de geocercas utiliza indices GIST de PostGIS para evaluar cada posicion GPS contra las geocercas activas del tenant.
|
||||
|
||||
### F3. ETA Dinamico
|
||||
Calculo y recalculo continuo del tiempo estimado de arribo (ETA) para cada viaje activo. El sistema registra el ETA original, el ETA recalculado actual y el anterior, junto con la distancia restante en km, el tiempo restante en minutos, factores de ajuste por trafico y clima, y el estado resultante (EN_TIEMPO, ADELANTADO, RETRASADO) con los minutos de diferencia. Los calculos se almacenan en `tracking.eta_calculado` para trazabilidad historica.
|
||||
|
||||
### F4. Alertas Operativas
|
||||
Generacion automatica de alertas basada en reglas configurables por tenant. Tipos de alerta: ENTRADA_GEOCERCA, SALIDA_GEOCERCA, EXCESO_VELOCIDAD, PARADA_PROLONGADA, DESVIO_RUTA, TEMPERATURA_FUERA_RANGO, BATERIA_BAJA, SIN_SENAL, BOTON_PANICO, APERTURA_PUERTA, CONSUMO_ANOMALO. Cada alerta tiene severidad (INFO, WARNING, CRITICAL), puede ser leida y atendida con resolucion documentada, y dispara notificaciones configurables por email, SMS y push.
|
||||
|
||||
### F5. Historial de Tracking
|
||||
Consulta de la ruta historica recorrida por una unidad en un rango de fechas. Permite reconstruir el trayecto completo de un viaje, calcular distancias reales vs planeadas, identificar paradas y desvios, y generar reportes detallados de recorrido con metricas de velocidad promedio, maxima, tiempo en movimiento y tiempo detenido.
|
||||
|
||||
### F6. Dashboard de Flota en Tiempo Real
|
||||
Visualizacion en mapa de la posicion actual de todas las unidades de la flota. Incluye filtros por estado del viaje, tipo de unidad, operador asignado y alertas activas. Actualizacion en tiempo real via WebSocket. Muestra indicadores clave: unidades en movimiento, detenidas, con alertas criticas y fuera de cobertura.
|
||||
|
||||
---
|
||||
|
||||
## Entidades (Schema: tracking)
|
||||
|
||||
| Entidad | Tabla DDL | Descripcion |
|
||||
|---------|-----------|-------------|
|
||||
| PosicionGps | `tracking.posiciones_gps` | Posiciones GPS particionadas por fecha. Campos: latitud, longitud, altitud, velocidad_kmh, rumbo, odometro, motor_encendido, hdop, satelites, proveedor_gps, imei |
|
||||
| Evento | `tracking.eventos` | Eventos de tracking durante viajes. Campos: tipo_evento, fuente, latitud, longitud, direccion, datos (JSONB), parada_id, evidencias (JSONB) |
|
||||
| Geocerca | `tracking.geocercas` | Geocercas/zonas de interes. Campos: codigo, nombre, tipo, es_circular, centro_latitud/longitud, radio_metros, poligono (GEOMETRY POLYGON 4326), alerta_entrada/salida, tiempo_permanencia_minutos |
|
||||
| Alerta | `tracking.alertas` | Alertas generadas por el sistema. Campos: tipo, severidad, titulo, mensaje, datos (JSONB), leida, atendida, resolucion, notificaciones_enviadas |
|
||||
| ReglaAlerta | `tracking.reglas_alerta` | Reglas configurables para generacion de alertas. Campos: nombre, tipo_alerta, severidad, condiciones (JSONB), aplica_todas_unidades, unidades_ids, notificar_email/sms/push, destinatarios |
|
||||
| EtaCalculado | `tracking.eta_calculado` | Historial de calculos de ETA. Campos: eta_original, eta_actual, eta_anterior, distancia_restante_km, tiempo_restante_minutos, factor_trafico, factor_clima, estado, minutos_diferencia |
|
||||
|
||||
---
|
||||
|
||||
## ENUMs
|
||||
|
||||
| Enum | Valores |
|
||||
|------|---------|
|
||||
| `tipo_geocerca` | CLIENTE, PROVEEDOR, PATIO, ZONA_RIESGO, CASETA, GASOLINERA, PUNTO_CONTROL, OTRO |
|
||||
| `severidad_alerta` | INFO, WARNING, CRITICAL |
|
||||
| `tipo_alerta` | ENTRADA_GEOCERCA, SALIDA_GEOCERCA, EXCESO_VELOCIDAD, PARADA_PROLONGADA, DESVIO_RUTA, TEMPERATURA_FUERA_RANGO, BATERIA_BAJA, SIN_SENAL, BOTON_PANICO, APERTURA_PUERTA, CONSUMO_ANOMALO |
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
| Metodo | Endpoint | Descripcion |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/tracking/posiciones` | Registrar posicion GPS (ingestion desde dispositivo/proveedor) |
|
||||
| GET | `/api/tracking/posiciones/:unidadId/actual` | Obtener ultima posicion conocida de una unidad |
|
||||
| GET | `/api/tracking/posiciones/:unidadId/historial` | Obtener historial de posiciones (con rango de fechas) |
|
||||
| GET | `/api/tracking/viajes/:viajeId/recorrido` | Obtener recorrido completo de un viaje |
|
||||
| POST | `/api/tracking/geocercas` | Crear geocerca (circular o poligonal) |
|
||||
| GET | `/api/tracking/geocercas` | Listar geocercas del tenant |
|
||||
| GET | `/api/tracking/geocercas/:id` | Obtener detalle de geocerca |
|
||||
| PUT | `/api/tracking/geocercas/:id` | Actualizar geocerca |
|
||||
| DELETE | `/api/tracking/geocercas/:id` | Desactivar geocerca |
|
||||
| GET | `/api/tracking/alertas` | Listar alertas (filtros: tipo, severidad, atendida, rango fechas) |
|
||||
| GET | `/api/tracking/alertas/:id` | Obtener detalle de alerta |
|
||||
| PATCH | `/api/tracking/alertas/:id/leer` | Marcar alerta como leida |
|
||||
| PATCH | `/api/tracking/alertas/:id/atender` | Marcar alerta como atendida con resolucion |
|
||||
| POST | `/api/tracking/reglas-alerta` | Crear regla de alerta |
|
||||
| GET | `/api/tracking/reglas-alerta` | Listar reglas de alerta |
|
||||
| PUT | `/api/tracking/reglas-alerta/:id` | Actualizar regla de alerta |
|
||||
| DELETE | `/api/tracking/reglas-alerta/:id` | Desactivar regla de alerta |
|
||||
| GET | `/api/tracking/eta/:viajeId` | Obtener ETA actual del viaje |
|
||||
| GET | `/api/tracking/eta/:viajeId/historial` | Obtener historial de calculos ETA |
|
||||
| GET | `/api/tracking/flota/dashboard` | Dashboard de flota en tiempo real |
|
||||
| GET | `/api/tracking/viajes/:viajeId/reporte` | Generar reporte de recorrido del viaje |
|
||||
| WS | `/ws/tracking/flota` | WebSocket para actualizaciones en tiempo real de posiciones |
|
||||
| WS | `/ws/tracking/alertas` | WebSocket para notificaciones de alertas en tiempo real |
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Estado |
|
||||
|----|--------|----|-----------|--------|
|
||||
| US-MAI006-001 | Ver posicion actual de unidad en mapa | 5 | P0 | Backlog |
|
||||
| US-MAI006-002 | Configurar geocercas | 8 | P0 | Backlog |
|
||||
| US-MAI006-003 | Recibir alerta de entrada/salida geocerca | 5 | P0 | Backlog |
|
||||
| US-MAI006-004 | Consultar ETA dinamico del viaje | 8 | P0 | Backlog |
|
||||
| US-MAI006-005 | Ver historial de ruta recorrida | 5 | P1 | Backlog |
|
||||
| US-MAI006-006 | Configurar alertas por tipo de evento | 5 | P1 | Backlog |
|
||||
| US-MAI006-007 | Detectar desvio de ruta | 8 | P1 | Backlog |
|
||||
| US-MAI006-008 | Ver dashboard de flota en tiempo real | 5 | P1 | Backlog |
|
||||
| US-MAI006-009 | Generar reporte de recorrido | 3 | P2 | Backlog |
|
||||
| US-MAI006-010 | Integrar dispositivo GPS | 5 | P1 | Backlog |
|
||||
| **Total** | | **57** | | |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Depende de
|
||||
| Modulo | Motivo |
|
||||
|--------|--------|
|
||||
| MAI-001 (Fundamentos) | Auth, RBAC, multi-tenancy, tenant_id en RLS policies |
|
||||
| MAI-003 (Ordenes de Transporte) | viaje_id referenciado en posiciones_gps, eventos, alertas y eta_calculado |
|
||||
| MAI-011 (Gestion de Flota) | unidad_id referenciado en posiciones_gps y alertas; operador_id en alertas |
|
||||
|
||||
### Bloquea a
|
||||
| Modulo | Motivo |
|
||||
|--------|--------|
|
||||
| MAI-005 (Despacho) | Visibilidad de tracking post-despacho |
|
||||
| MAI-007 (POD y Cierre) | Eventos de tracking para cierre operativo, tiempos reales |
|
||||
| MAI-008 (Incidencias) | Alertas que pueden derivar en incidencias |
|
||||
| MAI-015 (Portal Cliente) | Mapa de tracking, ETA y eventos para el cliente |
|
||||
| MAE-018 (Reportes y KPIs) | Datos de tracking para KPIs de puntualidad y eficiencia |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **PostGIS:** Se requiere la extension PostGIS habilitada. Los indices espaciales GIST se utilizan para consultas de proximidad (ST_DWithin) y contencion (ST_Contains) en la evaluacion de geocercas.
|
||||
- **Particionamiento:** La tabla `posiciones_gps` esta particionada por rango mensual en el campo `fecha_particion` para manejar el alto volumen de datos GPS sin degradar el rendimiento.
|
||||
- **WebSocket:** Las actualizaciones en tiempo real del mapa de flota y las notificaciones de alertas se transmiten via WebSocket (Socket.IO o ws nativo de NestJS) con canales por tenant.
|
||||
- **RLS (Row Level Security):** Todas las tablas del schema tracking tienen politicas RLS activas que filtran por `tenant_id = current_setting('app.tenant_id')::uuid`.
|
||||
- **SRID 4326:** Todas las coordenadas geograficas utilizan el sistema de referencia WGS 84 (SRID 4326), estandar para GPS.
|
||||
- **IMEI:** El campo `imei` en `posiciones_gps` permite asociar posiciones con dispositivos GPS fisicos independientemente de la unidad asignada.
|
||||
- **Datos JSONB:** Los campos `datos`, `evidencias` y `notificaciones_enviadas` utilizan JSONB para flexibilidad en el almacenamiento de metadatos variables por tipo de evento o alerta.
|
||||
|
||||
---
|
||||
|
||||
*MAI-006 Tracking en Tiempo Real - ERP Transportistas v1.0.0*
|
||||
166
docs/02-definicion-modulos/MAI-006-tracking/REQUERIMIENTOS.md
Normal file
166
docs/02-definicion-modulos/MAI-006-tracking/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,166 @@
|
||||
# REQUERIMIENTOS.md - MAI-006 Tracking en Tiempo Real
|
||||
|
||||
**Modulo:** MAI-006 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
**Referencia:** REQ-GIRO-TRANSPORTISTA.md (Secciones 4.5, 4.13)
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-MAI006-001: Ingestion de Posiciones GPS
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.1
|
||||
|
||||
El sistema debe recibir y almacenar posiciones GPS provenientes de dispositivos de telematica. Cada posicion debe incluir como minimo: latitud (DECIMAL 10,7), longitud (DECIMAL 10,7), velocidad en km/h, timestamp del GPS y la unidad asociada. Opcionalmente puede incluir: altitud, rumbo (0-360 grados), odometro, estado del motor (encendido/apagado), HDOP (precision horizontal), numero de satelites, IMEI del dispositivo y proveedor GPS. Las posiciones se almacenan en la tabla `tracking.posiciones_gps` particionada mensualmente por `fecha_particion`. Si la unidad esta asociada a un viaje activo, se debe registrar el `viaje_id`.
|
||||
|
||||
**Tabla DDL:** `tracking.posiciones_gps`
|
||||
**Indices:** `idx_posicion_unidad_fecha` (unidad_id, timestamp_gps), `idx_posicion_viaje` (viaje_id WHERE NOT NULL), `idx_posicion_geo` GIST (ST_SetSRID(ST_MakePoint(longitud, latitud), 4326))
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-002: Consulta de Posicion Actual
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.1, RF-4.13.1
|
||||
|
||||
El sistema debe permitir obtener la ultima posicion conocida de una unidad, incluyendo: latitud, longitud, velocidad, rumbo, timestamp GPS, estado del motor y viaje asociado. La consulta se resuelve obteniendo el registro mas reciente de `tracking.posiciones_gps` para la unidad indicada, ordenando por `timestamp_gps DESC LIMIT 1`. El endpoint debe soportar consulta individual por unidad y consulta masiva de toda la flota del tenant.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-003: Registro de Eventos de Tracking
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.2
|
||||
|
||||
El sistema debe registrar eventos de tracking durante la ejecucion de un viaje. Cada evento se almacena en `tracking.eventos` con: viaje_id (obligatorio), tipo_evento, fuente (OPERADOR, SISTEMA, USUARIO), ubicacion (latitud, longitud, direccion), timestamp del evento, datos especificos en JSONB, parada asociada (si aplica), generado_por_id y tipo, evidencias en JSONB, y observaciones. Los eventos pueden ser generados automaticamente por el sistema (geocercas, alertas) o manualmente por el operador a traves de la app movil.
|
||||
|
||||
**Tabla DDL:** `tracking.eventos`
|
||||
**Indices:** `idx_evento_viaje` (viaje_id), `idx_evento_tipo` (tenant_id, tipo_evento), `idx_evento_fecha` (timestamp_evento)
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-004: CRUD de Geocercas
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.4
|
||||
|
||||
El sistema debe permitir crear, consultar, actualizar y desactivar geocercas. Cada geocerca se almacena en `tracking.geocercas` con: codigo (unico por tenant), nombre, tipo (CLIENTE, PROVEEDOR, PATIO, ZONA_RIESGO, CASETA, GASOLINERA, PUNTO_CONTROL, OTRO). Las geocercas pueden ser circulares (centro_latitud, centro_longitud, radio_metros) o poligonales (poligono GEOMETRY POLYGON 4326). Cada geocerca configura: alerta_entrada (boolean), alerta_salida (boolean), tiempo_permanencia_minutos (alerta si excede), color de visualizacion, estado activa/inactiva, y opcionalmente un cliente asociado y direccion.
|
||||
|
||||
**Tabla DDL:** `tracking.geocercas`
|
||||
**Indices:** `idx_geocerca_tenant` (tenant_id), `idx_geocerca_tipo` (tenant_id, tipo), `idx_geocerca_geo` GIST (poligono), `idx_geocerca_codigo` UNIQUE (tenant_id, codigo)
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-005: Evaluacion Automatica de Geocercas
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.4
|
||||
|
||||
El sistema debe evaluar automaticamente cada posicion GPS recibida contra las geocercas activas del tenant. Para geocercas circulares, se utiliza `ST_DWithin` comparando la posicion con el punto centro y el radio en metros. Para geocercas poligonales, se utiliza `ST_Contains` verificando si la posicion esta dentro del poligono. Cuando una unidad ingresa o abandona una geocerca, el sistema debe generar automaticamente un evento en `tracking.eventos` y, si la geocerca tiene configurada la alerta correspondiente (alerta_entrada o alerta_salida), generar una alerta en `tracking.alertas`.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-006: Generacion de Alertas
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.5
|
||||
|
||||
El sistema debe generar alertas automaticas almacenadas en `tracking.alertas` con: tipo (tipo_alerta: 11 valores posibles), severidad (INFO, WARNING, CRITICAL), referencias (unidad_id, viaje_id, geocerca_id, operador_id), ubicacion, titulo, mensaje, datos especificos en JSONB, y timestamp. Las alertas se crean con estado leida=FALSE y atendida=FALSE. Al ser leida se registra leida_por y leida_fecha. Al ser atendida se registra atendida_por, atendida_fecha y resolucion (texto). El campo notificaciones_enviadas (JSONB) registra los canales por los que se notifico.
|
||||
|
||||
**Tabla DDL:** `tracking.alertas`
|
||||
**Indices:** `idx_alerta_tenant`, `idx_alerta_unidad`, `idx_alerta_viaje`, `idx_alerta_no_atendida` (WHERE atendida = FALSE), `idx_alerta_fecha`
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-007: Configuracion de Reglas de Alerta
|
||||
**Prioridad:** P1 | **Origen:** RF-4.5.5
|
||||
|
||||
El sistema debe permitir configurar reglas de alerta en `tracking.reglas_alerta`. Cada regla define: nombre, descripcion, tipo_alerta que genera, severidad por defecto, condiciones en JSONB (ejemplo: `{"velocidad_max": 100, "tiempo_parada_max_min": 30, "temp_min": -18, "temp_max": -15}`), aplicabilidad (todas las unidades o lista especifica de unidades_ids UUID[]), canales de notificacion (email, SMS, push), lista de destinatarios en JSONB, y estado activa/inactiva. El sistema evalua las reglas activas del tenant al procesar cada posicion GPS o evento relevante.
|
||||
|
||||
**Tabla DDL:** `tracking.reglas_alerta`
|
||||
**Indices:** `idx_regla_tenant` (tenant_id), `idx_regla_tipo` (tipo_alerta WHERE activa = TRUE)
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-008: Calculo de ETA Dinamico
|
||||
**Prioridad:** P0 | **Origen:** RF-4.5.3, RF-4.3.6
|
||||
|
||||
El sistema debe calcular y recalcular periodicamente el tiempo estimado de arribo (ETA) para cada viaje activo. Cada calculo se almacena en `tracking.eta_calculado` con: viaje_id, parada_id (opcional, para ETA por parada), eta_original (programado), eta_actual (recalculado), eta_anterior (para comparacion), distancia_restante_km, tiempo_restante_minutos, factor_trafico (multiplicador decimal), factor_clima (multiplicador decimal), estado (EN_TIEMPO, ADELANTADO, RETRASADO), y minutos_diferencia respecto al eta_original. El calculo considera la posicion actual de la unidad, la distancia restante y los factores de ajuste.
|
||||
|
||||
**Tabla DDL:** `tracking.eta_calculado`
|
||||
**Indices:** `idx_eta_viaje` (viaje_id), `idx_eta_fecha` (calculado_at)
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-009: Historial de Recorrido
|
||||
**Prioridad:** P1 | **Origen:** RF-4.5.1
|
||||
|
||||
El sistema debe permitir consultar el historial completo de posiciones GPS de una unidad o viaje en un rango de fechas. La consulta se ejecuta sobre `tracking.posiciones_gps` filtrando por unidad_id o viaje_id y rango de timestamp_gps. El resultado debe incluir las posiciones ordenadas cronologicamente y permitir la reconstruccion visual del recorrido en mapa. El sistema debe calcular metricas derivadas: distancia total recorrida, velocidad promedio, velocidad maxima, tiempo en movimiento, tiempo detenido, y numero de paradas.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-010: Deteccion de Desvio de Ruta
|
||||
**Prioridad:** P1 | **Origen:** RF-4.5.5
|
||||
|
||||
El sistema debe detectar cuando una unidad se desvia de la ruta planeada. Se compara la posicion GPS actual contra el corredor de la ruta esperada (buffer geometrico alrededor de la ruta planeada). Si la posicion cae fuera del corredor definido, se genera una alerta de tipo DESVIO_RUTA con severidad WARNING o CRITICAL segun la distancia de desvio. La deteccion utiliza funciones PostGIS como `ST_Distance` y `ST_Buffer` para calcular la distancia entre la posicion y la geometria de la ruta.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-011: Dashboard de Flota en Tiempo Real
|
||||
**Prioridad:** P1 | **Origen:** RF-4.5.1, RF-4.13.1
|
||||
|
||||
El sistema debe proporcionar un dashboard de flota con mapa interactivo mostrando la posicion actual de todas las unidades del tenant. El dashboard debe incluir: visualizacion en mapa con iconos por estado (en movimiento, detenida, con alerta), filtros por estado de viaje, tipo de unidad y operador, contadores de unidades en movimiento/detenidas/con alertas/fuera de cobertura, lista de alertas activas no atendidas, y panel de detalle al seleccionar una unidad. Las actualizaciones se transmiten via WebSocket para evitar polling constante.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-012: Reporte de Recorrido
|
||||
**Prioridad:** P2 | **Origen:** RF-4.5.1
|
||||
|
||||
El sistema debe generar reportes de recorrido por viaje con: ruta trazada en mapa, tabla de eventos con timestamps y ubicaciones, metricas de velocidad (promedio, maxima, distribucion), tiempos de parada por ubicacion, distancia planeada vs real, cumplimiento de geocercas (entradas/salidas con hora), alertas generadas durante el viaje, y ETA vs hora real de arribo. El reporte debe ser exportable en formato PDF.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-013: Integracion de Dispositivo GPS
|
||||
**Prioridad:** P1 | **Origen:** RF-4.5.1
|
||||
|
||||
El sistema debe soportar la ingestion de posiciones desde multiples proveedores de GPS/telematica. Cada posicion incluye el campo `proveedor_gps` (VARCHAR 50) y el `imei` (VARCHAR 50) del dispositivo. El sistema debe implementar una capa de abstraccion (adapter pattern) que normalice los datos de diferentes proveedores al esquema unificado de `tracking.posiciones_gps`. La asociacion entre IMEI y unidad se gestiona externamente (modulo flota MAI-011).
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-014: Notificaciones en Tiempo Real
|
||||
**Prioridad:** P1 | **Origen:** RF-4.5.6
|
||||
|
||||
El sistema debe transmitir actualizaciones en tiempo real a traves de WebSocket. Se implementan dos canales: (1) canal de posiciones de flota (`/ws/tracking/flota`) que emite la ultima posicion de cada unidad cuando se actualiza, y (2) canal de alertas (`/ws/tracking/alertas`) que emite alertas nuevas al momento de generarse. Los canales estan segregados por tenant_id. Las reglas de alerta definen adicionalmente si se envia notificacion por email, SMS y/o push a los destinatarios configurados.
|
||||
|
||||
---
|
||||
|
||||
### RF-MAI006-015: Aislamiento Multi-Tenant (RLS)
|
||||
**Prioridad:** P0 | **Origen:** Transversal
|
||||
|
||||
Todas las tablas del schema tracking deben tener Row Level Security habilitado con politica de aislamiento por tenant: `USING (tenant_id = current_setting('app.tenant_id')::uuid)`. Las tablas con RLS son: posiciones_gps, eventos, geocercas, alertas, reglas_alerta, eta_calculado. Ningun usuario debe poder acceder a datos de un tenant distinto al configurado en la sesion de base de datos.
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-MAI006-001: Rendimiento de Ingestion
|
||||
La ingestion de posiciones GPS debe procesar al menos 1,000 posiciones por segundo sin degradacion del rendimiento. El particionamiento mensual de `posiciones_gps` y los indices optimizados garantizan el rendimiento de escritura y lectura.
|
||||
|
||||
### RNF-MAI006-002: Latencia de Evaluacion
|
||||
La evaluacion de geocercas debe completarse en menos de 2 segundos por posicion procesada, incluyendo la verificacion contra todas las geocercas activas del tenant. Los indices GIST de PostGIS optimizan las consultas espaciales.
|
||||
|
||||
### RNF-MAI006-003: Escalabilidad de Almacenamiento
|
||||
El sistema debe soportar al menos 12 meses de historico de posiciones GPS sin degradacion significativa en consultas. La estrategia de particionamiento mensual permite la eliminacion selectiva de particiones antiguas y la creacion automatica de nuevas.
|
||||
|
||||
### RNF-MAI006-004: Disponibilidad WebSocket
|
||||
Los canales WebSocket de tracking y alertas deben mantener una disponibilidad del 99.5%. Se debe implementar reconexion automatica en el cliente frontend en caso de desconexion.
|
||||
|
||||
### RNF-MAI006-005: Seguridad de Datos GPS
|
||||
Los datos de posicion GPS son informacion sensible. Solo usuarios autorizados del tenant con los permisos adecuados (RBAC) pueden acceder a datos de tracking. Las politicas RLS proporcionan la primera capa de aislamiento a nivel de base de datos.
|
||||
|
||||
---
|
||||
|
||||
## Trazabilidad con Requerimientos del Giro
|
||||
|
||||
| RF del Giro | RF del Modulo | Cobertura |
|
||||
|-------------|---------------|-----------|
|
||||
| RF-4.5.1 Integracion GPS/Telematica | RF-MAI006-001, RF-MAI006-013 | Completa |
|
||||
| RF-4.5.3 ETA dinamico | RF-MAI006-008 | Completa |
|
||||
| RF-4.5.4 Geocercas (geofencing) | RF-MAI006-004, RF-MAI006-005 | Completa |
|
||||
| RF-4.5.5 Alertas | RF-MAI006-006, RF-MAI006-007, RF-MAI006-010 | Completa |
|
||||
| RF-4.5.6 Comunicacion omnicanal | RF-MAI006-014 | Parcial (configuracion de canales; implementacion de WhatsApp/SMS en modulo externo) |
|
||||
| RF-4.13.1 Tracking portal cliente | RF-MAI006-002, RF-MAI006-011 | Parcial (datos disponibles; portal en MAI-015) |
|
||||
| RF-4.3.6 Simulacion de ruta y ETA | RF-MAI006-008, RF-MAI006-010 | Parcial (ETA dinamico si; simulacion previa en MAI-004) |
|
||||
|
||||
---
|
||||
|
||||
*Requerimientos MAI-006 Tracking en Tiempo Real - ERP Transportistas v1.0.0*
|
||||
142
docs/02-definicion-modulos/MAI-006-tracking/RESUMEN-EPICA.md
Normal file
142
docs/02-definicion-modulos/MAI-006-tracking/RESUMEN-EPICA.md
Normal file
@ -0,0 +1,142 @@
|
||||
# RESUMEN-EPICA.md - MAI-006 Tracking en Tiempo Real
|
||||
|
||||
**Epica:** EPIC-MAI-006 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Epica
|
||||
|
||||
**ID:** EPIC-MAI-006
|
||||
**Titulo:** Tracking en Tiempo Real
|
||||
**Modulo:** MAI-006
|
||||
**Schema BD:** tracking
|
||||
**DDL:** `database/ddl/03-tracking-schema-ddl.sql`
|
||||
|
||||
---
|
||||
|
||||
## Descripcion de la Epica
|
||||
|
||||
Implementar el sistema completo de rastreo GPS en tiempo real para la flota de transporte de carga. El sistema debe permitir la ingestion masiva de posiciones GPS desde multiples proveedores de telematica, la configuracion y evaluacion automatica de geocercas utilizando PostGIS, el calculo dinamico de ETA considerando factores de trafico y clima, y la generacion de alertas operativas con flujo de atencion. Debe proporcionar visibilidad completa del estado y ubicacion de todas las unidades tanto para el equipo de operaciones (coordinador de trafico) como para el cliente final a traves del portal.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos de Negocio
|
||||
|
||||
1. **Visibilidad operativa total:** Conocer la ubicacion exacta de cada unidad en cualquier momento, eliminando la dependencia de llamadas telefonicas y mensajes manuales al operador.
|
||||
2. **Proactividad ante desvios:** Detectar automaticamente desvios de ruta, paradas prolongadas, excesos de velocidad y otros eventos criticos antes de que impacten el servicio al cliente.
|
||||
3. **ETA confiable:** Ofrecer a coordinadores y clientes un tiempo estimado de arribo dinamico y actualizado continuamente con base en la posicion real de la unidad.
|
||||
4. **Satisfaccion del cliente:** Brindar al cliente acceso directo a la posicion de su envio y eventos relevantes del viaje a traves del portal.
|
||||
5. **Trazabilidad completa:** Mantener un historial detallado de todas las posiciones y eventos de cada viaje para analisis posterior, reportes y resolucion de disputas.
|
||||
6. **Seguridad de la carga:** Alertar inmediatamente sobre situaciones de riesgo como ingreso a zonas peligrosas, boton de panico o apertura de puertas no autorizada.
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Ingestion y almacenamiento de posiciones GPS con particionamiento mensual
|
||||
- CRUD de geocercas circulares y poligonales con PostGIS
|
||||
- Evaluacion automatica de posiciones contra geocercas activas
|
||||
- Calculo y recalculo dinamico de ETA por viaje y por parada
|
||||
- Sistema de alertas configurable con 11 tipos y 3 niveles de severidad
|
||||
- Reglas de alerta configurables por tenant con condiciones JSONB
|
||||
- Flujo de atencion de alertas (leida, atendida, resolucion)
|
||||
- Dashboard de flota en tiempo real con mapa interactivo
|
||||
- Historial de recorrido por viaje con metricas
|
||||
- Generacion de reportes de recorrido
|
||||
- Integracion con dispositivos GPS via IMEI/proveedor
|
||||
- Actualizaciones en tiempo real via WebSocket
|
||||
- Row Level Security (RLS) por tenant en todas las tablas
|
||||
|
||||
### Excluido
|
||||
- Optimizacion automatica de rutas (MAA-019)
|
||||
- App movil del operador (componente transversal, no exclusivo de tracking)
|
||||
- Notificaciones omnicanal avanzadas (WhatsApp/SMS) - solo configuracion de destinatarios
|
||||
- Integracion EDI con clientes (MAA-020)
|
||||
- Procesamiento de datos de temperatura y cadena de frio (fase posterior)
|
||||
|
||||
---
|
||||
|
||||
## Metricas de Exito
|
||||
|
||||
| Metrica | Objetivo |
|
||||
|---------|----------|
|
||||
| Latencia de ingestion GPS | < 5 segundos desde recepcion hasta persistencia |
|
||||
| Evaluacion de geocercas | < 2 segundos por posicion procesada |
|
||||
| Recalculo de ETA | Cada 5 minutos para viajes activos |
|
||||
| Tiempo de deteccion de alertas | < 30 segundos desde evento desencadenante |
|
||||
| Disponibilidad del mapa de flota | 99.5% uptime |
|
||||
| Cobertura de tracking | 100% de viajes activos con posicion actualizada cada 2 minutos |
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Sprint |
|
||||
|----|--------|----|-----------|--------|
|
||||
| US-MAI006-001 | Ver posicion actual de unidad en mapa | 5 | P0 | Por asignar |
|
||||
| US-MAI006-002 | Configurar geocercas | 8 | P0 | Por asignar |
|
||||
| US-MAI006-003 | Recibir alerta de entrada/salida geocerca | 5 | P0 | Por asignar |
|
||||
| US-MAI006-004 | Consultar ETA dinamico del viaje | 8 | P0 | Por asignar |
|
||||
| US-MAI006-005 | Ver historial de ruta recorrida | 5 | P1 | Por asignar |
|
||||
| US-MAI006-006 | Configurar alertas por tipo de evento | 5 | P1 | Por asignar |
|
||||
| US-MAI006-007 | Detectar desvio de ruta | 8 | P1 | Por asignar |
|
||||
| US-MAI006-008 | Ver dashboard de flota en tiempo real | 5 | P1 | Por asignar |
|
||||
| US-MAI006-009 | Generar reporte de recorrido | 3 | P2 | Por asignar |
|
||||
| US-MAI006-010 | Integrar dispositivo GPS | 5 | P1 | Por asignar |
|
||||
| **Total** | | **57** | | |
|
||||
|
||||
---
|
||||
|
||||
## Distribucion por Prioridad
|
||||
|
||||
| Prioridad | Historias | Story Points | Descripcion |
|
||||
|-----------|-----------|-------------|-------------|
|
||||
| P0 | 4 | 26 | Funcionalidades criticas: posicion en mapa, geocercas, alertas geocerca, ETA |
|
||||
| P1 | 4 | 23 | Funcionalidades importantes: historial, configuracion alertas, desvio ruta, dashboard |
|
||||
| P2 | 1 | 3 | Funcionalidades deseables: reporte de recorrido |
|
||||
| P1 | 1 | 5 | Infraestructura: integracion dispositivo GPS |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Internas (otros modulos ERP Transportistas)
|
||||
| Modulo | Dependencia | Tipo |
|
||||
|--------|------------|------|
|
||||
| MAI-001 Fundamentos | Auth, RBAC, multi-tenancy | Bloqueante |
|
||||
| MAI-003 Ordenes de Transporte | Viaje (viaje_id), Paradas (parada_id) | Bloqueante |
|
||||
| MAI-011 Gestion de Flota | Unidad (unidad_id), Operador (operador_id) | Bloqueante |
|
||||
|
||||
### Externas (infraestructura/servicios)
|
||||
| Servicio | Dependencia | Tipo |
|
||||
|----------|------------|------|
|
||||
| PostgreSQL + PostGIS | Extension PostGIS habilitada, funciones ST_*, indices GIST | Bloqueante |
|
||||
| WebSocket Gateway | NestJS WebSocket (Socket.IO o ws) para actualizaciones en tiempo real | Bloqueante |
|
||||
| Proveedor GPS/Telematica | API o webhook de proveedor para ingestion de posiciones | Requerido para produccion |
|
||||
| Servicio de Mapas | Libreria de mapas frontend (Leaflet, Mapbox GL) para visualizacion | Requerido para frontend |
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Impacto | Probabilidad | Mitigacion |
|
||||
|--------|---------|-------------|------------|
|
||||
| Alto volumen de datos GPS | Alto | Alta | Particionamiento mensual de posiciones_gps, indices optimizados, politica de retencion |
|
||||
| Latencia en evaluacion de geocercas | Medio | Media | Indices GIST de PostGIS, cache de geocercas activas en Redis, evaluacion asincrona |
|
||||
| Conectividad intermitente del dispositivo GPS | Medio | Alta | Buffer local en dispositivo, reconciliacion por timestamp_gps vs timestamp_servidor |
|
||||
| Multiples proveedores GPS con formatos distintos | Medio | Alta | Capa de abstraccion (adapter pattern) por proveedor, normalizacion a schema unificado |
|
||||
| Sobrecarga de alertas (alert fatigue) | Medio | Media | Reglas configurables por tenant, agrupacion de alertas repetidas, cooldown configurable |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- **PostGIS:** El indice `idx_posicion_geo` utiliza `ST_SetSRID(ST_MakePoint(longitud, latitud), 4326)` para indexar posiciones espacialmente. Las geocercas poligonales se almacenan directamente como `GEOMETRY(POLYGON, 4326)` con indice GIST en `idx_geocerca_geo`.
|
||||
- **Particionamiento:** Se crean particiones mensuales de `posiciones_gps` (ejemplo: `posiciones_gps_2026_01`, `posiciones_gps_2026_02`, `posiciones_gps_2026_03`). Se requiere un proceso automatizado para crear particiones futuras.
|
||||
- **RLS:** Todas las tablas del schema tracking implementan Row Level Security con politica `tenant_id = current_setting('app.tenant_id')::uuid` para aislamiento multi-tenant.
|
||||
- **JSONB:** Los campos `condiciones` en reglas_alerta, `datos` y `evidencias` en eventos, y `notificaciones_enviadas` en alertas utilizan JSONB para flexibilidad y consultas indexables.
|
||||
|
||||
---
|
||||
|
||||
*EPIC-MAI-006 Tracking en Tiempo Real - ERP Transportistas v1.0.0*
|
||||
89
docs/02-definicion-modulos/MAI-008-incidencias/README.md
Normal file
89
docs/02-definicion-modulos/MAI-008-incidencias/README.md
Normal file
@ -0,0 +1,89 @@
|
||||
# MAI-008: Incidencias y Reclamaciones
|
||||
|
||||
**Modulo:** MAI-008
|
||||
**Nombre:** Incidencias y Reclamaciones (Claims)
|
||||
**Prioridad:** P1
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Modulo para gestionar eventos anomalos durante la operacion de transporte: retrasos, rechazos, danos, robos, faltantes, accidentes y multas. Proporciona trazabilidad completa, asignacion de responsabilidades e impacto economico.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Registrar y clasificar incidencias con evidencias
|
||||
2. Gestionar flujo de atencion (apertura -> resolucion -> cierre)
|
||||
3. Controlar tiempos de respuesta por SLA de severidad
|
||||
4. Calcular impacto economico y asociar a viaje/cliente
|
||||
5. Integrar con facturacion para cargos/abonos
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Operador | Reporta incidencias en campo |
|
||||
| Customer Success | Gestiona incidencias de cliente |
|
||||
| Supervisor Operaciones | Investiga y resuelve |
|
||||
| Jefe de Flota | Atiende incidencias de unidades |
|
||||
| Cliente | Reporta y da seguimiento |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Depende de | Para |
|
||||
|------------|------|
|
||||
| MAI-006 (Tracking) | Eventos que generan incidencias |
|
||||
| MAI-007 (POD) | Rechazos y faltantes en entrega |
|
||||
| MAI-003 (OT) | Viaje relacionado |
|
||||
| MAI-009 (Facturacion) | Cargos/abonos por incidencias |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
Evento anomalo → Apertura incidencia → Clasificacion →
|
||||
Asignacion responsable → Investigacion (evidencias) →
|
||||
Resolucion → Calculo impacto → Cierre → Facturacion (si aplica)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Incidencia
|
||||
|
||||
| Tipo | Descripcion | Impacto Tipico |
|
||||
|------|-------------|----------------|
|
||||
| RETRASO | Entrega fuera de ventana | Penalizacion SLA |
|
||||
| RECHAZO | Cliente no recibe | Reexpedicion |
|
||||
| DANO | Mercancia danada | Reclamo seguro |
|
||||
| ROBO | Robo parcial/total | Deducible, seguro |
|
||||
| FALTANTE | Diferencia en conteo | Cargo a responsable |
|
||||
| DEVOLUCION | Mercancia regresada | Flete retorno |
|
||||
| ACCIDENTE | Evento vial | Seguro, costos |
|
||||
| MULTA | Infraccion de transito | Deduccion operador |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAI-008-incidencias/
|
||||
├── README.md <- Este archivo
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAI008-001.md <- Registrar incidencia
|
||||
├── US-MAI008-002.md <- Gestionar flujo atencion
|
||||
└── US-MAI008-003.md <- Calcular impacto economico
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAI-008 Incidencias - ERP Transportistas v1.0.0*
|
||||
200
docs/02-definicion-modulos/MAI-008-incidencias/REQUERIMIENTOS.md
Normal file
200
docs/02-definicion-modulos/MAI-008-incidencias/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,200 @@
|
||||
# REQUERIMIENTOS - MAI-008: Incidencias y Reclamaciones
|
||||
|
||||
**Modulo:** MAI-008
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.6
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.6.1: Tipos de Incidencia
|
||||
|
||||
**Descripcion:** El sistema debe soportar un catalogo de tipos de incidencia del giro transporte.
|
||||
|
||||
**Tipos requeridos:**
|
||||
| Tipo | Codigo | Severidad Default |
|
||||
|------|--------|-------------------|
|
||||
| Retraso | RETRASO | Media |
|
||||
| Rechazo en entrega | RECHAZO | Alta |
|
||||
| Dano a mercancia | DANO | Critica |
|
||||
| Robo parcial/total | ROBO | Critica |
|
||||
| Faltante | FALTANTE | Media |
|
||||
| Devolucion | DEVOLUCION | Baja |
|
||||
| Accidente | ACCIDENTE | Critica |
|
||||
| Multa de transito | MULTA | Baja |
|
||||
|
||||
**Validaciones:**
|
||||
- Cada tipo tiene severidad default configurable
|
||||
- Tipos pueden tener campos adicionales obligatorios
|
||||
- Tipos se asocian a workflows especificos
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.tipos_incidencia`
|
||||
- `tracking.campos_tipo_incidencia`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.6.2: Flujo de Atencion
|
||||
|
||||
**Descripcion:** Las incidencias siguen un flujo de atencion estructurado.
|
||||
|
||||
**Estados del flujo:**
|
||||
```
|
||||
ABIERTA → ASIGNADA → EN_INVESTIGACION → PENDIENTE_EVIDENCIA →
|
||||
PENDIENTE_APROBACION → RESUELTA → CERRADA
|
||||
```
|
||||
|
||||
**Estados adicionales:**
|
||||
- `RECHAZADA` - Incidencia invalida
|
||||
- `CANCELADA` - Sin efecto
|
||||
- `ESCALADA` - Requiere nivel superior
|
||||
|
||||
**Reglas:**
|
||||
- No se puede cerrar sin resolucion documentada
|
||||
- Escalamiento automatico si excede SLA
|
||||
- Notificaciones a involucrados en cada cambio
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.incidencias` (estado)
|
||||
- `tracking.transiciones_incidencia`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.6.3: Evidencias y Bitacora
|
||||
|
||||
**Descripcion:** Toda incidencia debe tener soporte documental y trazabilidad completa.
|
||||
|
||||
**Tipos de evidencia:**
|
||||
- Fotos (dano, accidente, mercancia)
|
||||
- Documentos (actas, reportes, facturas)
|
||||
- Declaraciones escritas
|
||||
- Correos/mensajes
|
||||
- Reportes de policia/seguros
|
||||
|
||||
**Bitacora requerida:**
|
||||
- Todos los comentarios con usuario/fecha
|
||||
- Cambios de estado con motivo
|
||||
- Archivos adjuntos con metadatos
|
||||
- Asignaciones y reasignaciones
|
||||
|
||||
**Validaciones:**
|
||||
- Minimo 1 evidencia para tipos DANO, ROBO, ACCIDENTE
|
||||
- Fotos con geolocalizacion y timestamp
|
||||
- Limite de tamano configurable
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.evidencias_incidencia`
|
||||
- `tracking.bitacora_incidencia`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.6.4: Impacto Economico
|
||||
|
||||
**Descripcion:** Registrar y calcular costos derivados de incidencias.
|
||||
|
||||
**Conceptos de costo:**
|
||||
| Concepto | Descripcion | Quien paga |
|
||||
|----------|-------------|------------|
|
||||
| Deducible | Pago a seguro | Empresa |
|
||||
| Penalizacion SLA | Descuento al cliente | Empresa |
|
||||
| Reexpedicion | Costo de reentrega | Cliente/Empresa |
|
||||
| Multa transito | Infraccion | Operador |
|
||||
| Dano mercancia | Valor danado | Seguro/Empresa |
|
||||
| Faltante | Valor faltante | Operador/Empresa |
|
||||
|
||||
**Calculos:**
|
||||
- Total por incidencia = suma de conceptos
|
||||
- Asociacion a viaje para rentabilidad
|
||||
- Asociacion a cliente para analisis
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.costos_incidencia`
|
||||
- Relacion con `billing.lineas_factura`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.6.5: SLA de Incidencias
|
||||
|
||||
**Descripcion:** Tiempos maximos de respuesta por severidad.
|
||||
|
||||
**SLAs por severidad:**
|
||||
| Severidad | Primera respuesta | Resolucion |
|
||||
|-----------|-------------------|------------|
|
||||
| Critica | 1 hora | 24 horas |
|
||||
| Alta | 4 horas | 48 horas |
|
||||
| Media | 8 horas | 72 horas |
|
||||
| Baja | 24 horas | 5 dias |
|
||||
|
||||
**Reglas:**
|
||||
- Escalamiento automatico al 80% del SLA
|
||||
- Notificacion a supervisor al vencer
|
||||
- Metricas de cumplimiento por equipo
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.sla_incidencias` (configuracion)
|
||||
- `tracking.incidencias` (timestamps)
|
||||
|
||||
---
|
||||
|
||||
### RF-4.6.6: Integracion a Facturacion
|
||||
|
||||
**Descripcion:** Impactos economicos se reflejan en facturacion.
|
||||
|
||||
**Escenarios:**
|
||||
1. **Penalizacion al cliente** → Nota de credito
|
||||
2. **Cargo al cliente** → Cargo adicional en factura
|
||||
3. **Deduccion a operador** → Registro en liquidacion
|
||||
4. **Reclamo a seguro** → Expediente separado
|
||||
|
||||
**Flujo:**
|
||||
```
|
||||
Incidencia cerrada con impacto →
|
||||
Generar movimiento financiero →
|
||||
Asociar a factura/nota/liquidacion
|
||||
```
|
||||
|
||||
**Validaciones:**
|
||||
- Impacto debe estar aprobado antes de facturar
|
||||
- Trazabilidad incidencia ↔ movimiento financiero
|
||||
|
||||
**Tablas DDL:**
|
||||
- `billing.movimientos_incidencia`
|
||||
- Relacion con `settlements.deducciones`
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Tiempo de Respuesta
|
||||
- Apertura de incidencia < 2 segundos
|
||||
- Carga de evidencias < 5 segundos (fotos comprimidas)
|
||||
|
||||
### RNF-002: Disponibilidad
|
||||
- App movil debe permitir registro offline
|
||||
- Sincronizacion al recuperar conexion
|
||||
|
||||
### RNF-003: Auditoria
|
||||
- Todos los cambios auditados
|
||||
- Retencion minima 5 anos
|
||||
|
||||
### RNF-004: Notificaciones
|
||||
- Push, email, WhatsApp segun configuracion
|
||||
- Tiempo maximo de envio: 30 segundos
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tablas DDL | Endpoints | Historias |
|
||||
|----|------------|-----------|-----------|
|
||||
| RF-4.6.1 | tipos_incidencia | GET /tipos | US-MAI008-001 |
|
||||
| RF-4.6.2 | incidencias, transiciones | POST/PATCH | US-MAI008-002 |
|
||||
| RF-4.6.3 | evidencias, bitacora | POST /evidencias | US-MAI008-001 |
|
||||
| RF-4.6.4 | costos_incidencia | POST /costos | US-MAI008-003 |
|
||||
| RF-4.6.5 | sla_incidencias | Config | US-MAI008-002 |
|
||||
| RF-4.6.6 | movimientos_incidencia | POST /impacto | US-MAI008-003 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAI-008 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,79 @@
|
||||
# RESUMEN EPICA - MAI-008: Incidencias y Reclamaciones
|
||||
|
||||
**Modulo:** MAI-008
|
||||
**Prioridad:** P1
|
||||
**Story Points Total:** 18
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- Incidencias se manejan por WhatsApp/email sin trazabilidad
|
||||
- No hay control de tiempos de respuesta
|
||||
- Costos de incidencias no se asocian a viajes/clientes
|
||||
- Penalizaciones y reclamos se pierden o duplican
|
||||
|
||||
### Beneficios
|
||||
- **Trazabilidad completa** de cada incidencia
|
||||
- **SLAs controlados** con escalamiento automatico
|
||||
- **Impacto economico calculado** y asociado
|
||||
- **Integracion financiera** para cargos/abonos
|
||||
|
||||
### KPIs Impactados
|
||||
- Incidencias por 100 viajes
|
||||
- Tiempo promedio de resolucion
|
||||
- Costo total de reclamos
|
||||
- % cumplimiento SLA incidencias
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Catalogo de tipos de incidencia
|
||||
- Flujo de atencion completo
|
||||
- Gestion de evidencias
|
||||
- Calculo de impacto economico
|
||||
- SLAs y escalamiento
|
||||
- Integracion con facturacion
|
||||
|
||||
### Excluido
|
||||
- Gestion de seguros (solo registro basico)
|
||||
- Procesos legales
|
||||
- Arbitraje con clientes
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAI008-001 | Registrar incidencia con evidencias | 5 |
|
||||
| US-MAI008-002 | Gestionar flujo de atencion | 8 |
|
||||
| US-MAI008-003 | Calcular y aplicar impacto economico | 5 |
|
||||
| **Total** | | **18** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
MAI-006 (Tracking) ──┐
|
||||
MAI-007 (POD) ──────┼──> MAI-008 ──> MAI-009 (Facturacion)
|
||||
MAI-003 (OT) ───────┘ ──> MAI-010 (Liquidaciones)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Resistencia a documentar | Hacer obligatorio para cerrar |
|
||||
| Evidencias insuficientes | Validaciones minimas por tipo |
|
||||
| SLAs no realistas | Configurar con operaciones |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAI-008 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,124 @@
|
||||
# US-MAI008-001: Registrar incidencia con evidencias
|
||||
|
||||
**ID:** US-MAI008-001
|
||||
**Modulo:** MAI-008 (Incidencias)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** operador o supervisor
|
||||
**Quiero** registrar una incidencia con toda la informacion y evidencias necesarias
|
||||
**Para** documentar eventos anomalos de forma completa y trazable
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Seleccionar tipo de incidencia
|
||||
**Dado** que ocurrio un evento anomalo
|
||||
**Cuando** inicio el registro de incidencia
|
||||
**Entonces** selecciono el tipo (retraso, dano, robo, faltante, etc.)
|
||||
|
||||
### CA-002: Asociar a viaje
|
||||
**Dado** que la incidencia esta relacionada a un viaje
|
||||
**Cuando** la registro
|
||||
**Entonces** se vincula al viaje con sus datos (OT, operador, unidad, cliente)
|
||||
|
||||
### CA-003: Capturar evidencias
|
||||
**Dado** que necesito documentar la incidencia
|
||||
**Cuando** adjunto evidencias
|
||||
**Entonces** puedo agregar fotos, documentos y declaraciones
|
||||
|
||||
### CA-004: Campos obligatorios por tipo
|
||||
**Dado** que cada tipo tiene requisitos especificos
|
||||
**Cuando** registro una incidencia tipo DANO
|
||||
**Entonces** debo capturar fotos y descripcion del dano obligatoriamente
|
||||
|
||||
### CA-005: Registro offline
|
||||
**Dado** que el operador puede estar sin conexion
|
||||
**Cuando** registra una incidencia en campo
|
||||
**Entonces** se guarda localmente y sincroniza al tener red
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REGISTRAR INCIDENCIA X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Viaje: VJE-0125 | CDMX -> Monterrey |
|
||||
| Operador: Juan Perez Garcia |
|
||||
| Cliente: CEMEX S.A. |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TIPO DE INCIDENCIA |
|
||||
| |
|
||||
| [Dano a mercancia v] |
|
||||
| |
|
||||
| Severidad: [CRITICA] (segun tipo) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DESCRIPCION |
|
||||
| |
|
||||
| [Caja de producto X danada durante descarga. ]|
|
||||
| [Se cayo de la tarima al mover con montacargas. ]|
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EVIDENCIAS * |
|
||||
| |
|
||||
| [+ Agregar foto] [+ Agregar documento] |
|
||||
| |
|
||||
| [IMG] dano_caja_1.jpg (2.3 MB) [X] |
|
||||
| [IMG] dano_caja_2.jpg (1.8 MB) [X] |
|
||||
| [DOC] acta_recepcion.pdf (450 KB) [X] |
|
||||
| |
|
||||
| * Minimo 1 foto requerida para tipo DANO |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DATOS ADICIONALES |
|
||||
| |
|
||||
| Responsable aparente: |
|
||||
| ( ) Operador |
|
||||
| (o) Almacen destino |
|
||||
| ( ) Tercero |
|
||||
| ( ) No determinado |
|
||||
| |
|
||||
| Valor estimado del dano: [$4,500.00] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Cancelar] [Registrar Incidencia] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `tracking.incidencias`
|
||||
- Tabla: `tracking.evidencias_incidencia`
|
||||
- Fotos se comprimen antes de subir (max 2MB)
|
||||
- Evidencias a S3 con metadatos (geo, timestamp)
|
||||
- Validar campos obligatorios segun tipo
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Catalogo de tipos de incidencia
|
||||
- [ ] Formulario de registro con campos dinamicos
|
||||
- [ ] Carga de multiples evidencias
|
||||
- [ ] Validacion de campos obligatorios por tipo
|
||||
- [ ] Soporte offline con sincronizacion
|
||||
- [ ] Asociacion automatica a viaje activo
|
||||
- [ ] Tests de registro y evidencias
|
||||
@ -0,0 +1,169 @@
|
||||
# US-MAI008-002: Gestionar flujo de atencion
|
||||
|
||||
**ID:** US-MAI008-002
|
||||
**Modulo:** MAI-008 (Incidencias)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** supervisor de operaciones
|
||||
**Quiero** gestionar el flujo completo de atencion de incidencias
|
||||
**Para** asegurar resolucion oportuna con trazabilidad
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Asignar responsable
|
||||
**Dado** que hay una incidencia nueva
|
||||
**Cuando** la reviso
|
||||
**Entonces** puedo asignarla a un responsable de investigacion
|
||||
|
||||
### CA-002: Registrar avances
|
||||
**Dado** que estoy investigando una incidencia
|
||||
**Cuando** tengo avances
|
||||
**Entonces** los registro en la bitacora con fecha y hora
|
||||
|
||||
### CA-003: Solicitar informacion adicional
|
||||
**Dado** que necesito mas datos
|
||||
**Cuando** cambio estado a PENDIENTE_EVIDENCIA
|
||||
**Entonces** se notifica al reportador para que complete
|
||||
|
||||
### CA-004: Resolver incidencia
|
||||
**Dado** que complete la investigacion
|
||||
**Cuando** documento la resolucion
|
||||
**Entonces** puedo cerrar la incidencia con el resultado
|
||||
|
||||
### CA-005: Escalamiento automatico
|
||||
**Dado** que la incidencia esta cerca de vencer el SLA
|
||||
**Cuando** se alcanza el 80% del tiempo
|
||||
**Entonces** se escala automaticamente al supervisor
|
||||
|
||||
### CA-006: Metricas de SLA
|
||||
**Dado** que hay SLAs definidos por severidad
|
||||
**Cuando** consulto incidencias
|
||||
**Entonces** veo indicadores de tiempo restante/excedido
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Bandeja de Incidencias
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| INCIDENCIAS [+ Nueva] |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| [Mis asignadas v] [Todas] [Por vencer] [Vencidas] |
|
||||
| |
|
||||
| Filtros: [Tipo: Todos v] [Severidad: Todos v] |
|
||||
| [Cliente: ____] [Fecha: Ultimos 7 dias v] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| | # | Viaje | Tipo | Sev | Estado | SLA | Asignado | |
|
||||
| |---|-------|------|-----|--------|-----|----------| |
|
||||
| |023| VJE125| Dano |CRIT | Invest.| 4h | M.Garcia | |
|
||||
| |024| VJE118| Retr |MEDIA| Abierta| 48h | -- | |
|
||||
| |025| VJE130| Falt |MEDIA| P.Evid.| 24h | J.Lopez | |
|
||||
| |026| VJE115| Robo |CRIT | Escala.| -2h | Supervisor| |
|
||||
| |
|
||||
| [!] 1 incidencia vencida [!] 2 por vencer |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Detalle de Incidencia
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| INCIDENCIA #023 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Tipo: Dano a mercancia Severidad: CRITICA |
|
||||
| Viaje: VJE-0125 Cliente: CEMEX S.A. |
|
||||
| Reportada: 2026-01-27 10:30 Por: Juan Perez |
|
||||
| |
|
||||
| Estado: [EN INVESTIGACION v] |
|
||||
| |
|
||||
| SLA: [====------] 4h restantes (de 24h) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ASIGNACION |
|
||||
| |
|
||||
| Responsable: [Maria Garcia v] |
|
||||
| Fecha asignacion: 2026-01-27 10:45 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| BITACORA |
|
||||
| |
|
||||
| [+ Agregar comentario] |
|
||||
| |
|
||||
| 27-ene 14:30 | Maria Garcia |
|
||||
| Se contacto a almacen destino. Confirman que el |
|
||||
| dano ocurrio durante maniobra con montacargas. |
|
||||
| |
|
||||
| 27-ene 10:45 | Sistema |
|
||||
| Incidencia asignada a Maria Garcia |
|
||||
| |
|
||||
| 27-ene 10:30 | Juan Perez |
|
||||
| Incidencia registrada con 2 fotos adjuntas |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESOLUCION |
|
||||
| |
|
||||
| Resultado: [Responsabilidad de tercero (almacen) v] |
|
||||
| |
|
||||
| Descripcion resolucion: |
|
||||
| [Almacen reconoce responsabilidad. Se levanto acta ]|
|
||||
| [y se procedera a reclamo por $4,500.00 ]|
|
||||
| |
|
||||
| [Guardar] [Cerrar Incidencia] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados del Flujo
|
||||
|
||||
| Estado | Descripcion | Siguiente |
|
||||
|--------|-------------|-----------|
|
||||
| ABIERTA | Recien registrada | ASIGNADA |
|
||||
| ASIGNADA | Con responsable | EN_INVESTIGACION |
|
||||
| EN_INVESTIGACION | Investigando | PENDIENTE_*, RESUELTA |
|
||||
| PENDIENTE_EVIDENCIA | Faltan documentos | EN_INVESTIGACION |
|
||||
| PENDIENTE_APROBACION | Requiere autorizacion | RESUELTA |
|
||||
| ESCALADA | Fuera de SLA o compleja | RESUELTA |
|
||||
| RESUELTA | Con resultado | CERRADA |
|
||||
| CERRADA | Terminada | - |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `tracking.incidencias` (estado, asignado_a)
|
||||
- Tabla: `tracking.bitacora_incidencia`
|
||||
- Tabla: `tracking.transiciones_incidencia`
|
||||
- Job para verificar SLAs cada 5 minutos
|
||||
- Notificaciones por email/push en cambios
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Bandeja de incidencias con filtros
|
||||
- [ ] Asignacion de responsable
|
||||
- [ ] Bitacora de comentarios
|
||||
- [ ] Transiciones de estado validadas
|
||||
- [ ] Escalamiento automatico por SLA
|
||||
- [ ] Indicadores visuales de SLA
|
||||
- [ ] Notificaciones en cambios
|
||||
- [ ] Tests de flujo completo
|
||||
@ -0,0 +1,184 @@
|
||||
# US-MAI008-003: Calcular y aplicar impacto economico
|
||||
|
||||
**ID:** US-MAI008-003
|
||||
**Modulo:** MAI-008 (Incidencias)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** supervisor o facturador
|
||||
**Quiero** calcular el impacto economico de las incidencias
|
||||
**Para** reflejarlo en facturacion, liquidaciones o reclamos
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Registrar conceptos de costo
|
||||
**Dado** que la incidencia tiene impacto economico
|
||||
**Cuando** registro los costos
|
||||
**Entonces** especifico concepto, monto y responsable
|
||||
|
||||
### CA-002: Multiples conceptos
|
||||
**Dado** que una incidencia puede tener varios impactos
|
||||
**Cuando** la reviso
|
||||
**Entonces** puedo agregar multiples conceptos de costo
|
||||
|
||||
### CA-003: Aprobar impacto
|
||||
**Dado** que los costos afectan a terceros
|
||||
**Cuando** superen un umbral
|
||||
**Entonces** requieren aprobacion de supervisor
|
||||
|
||||
### CA-004: Generar movimiento financiero
|
||||
**Dado** que el impacto esta aprobado
|
||||
**Cuando** cierro la incidencia
|
||||
**Entonces** se genera el movimiento correspondiente (NC, cargo, deduccion)
|
||||
|
||||
### CA-005: Asociar a rentabilidad
|
||||
**Dado** que quiero medir rentabilidad real
|
||||
**Cuando** el costo se registra
|
||||
**Entonces** se asocia al viaje para calculos de margen
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| IMPACTO ECONOMICO - Incidencia #023 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Incidencia: Dano a mercancia |
|
||||
| Viaje: VJE-0125 | Cliente: CEMEX S.A. |
|
||||
| Responsabilidad determinada: Almacen destino |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CONCEPTOS DE COSTO [+ Agregar]|
|
||||
| |
|
||||
| | Concepto | Descripcion | Monto | Cargo a | Estado | |
|
||||
| |----------|-------------|-------|---------|--------| |
|
||||
| | Dano mer | 5 cajas prod| $4,500| Cliente | Aprob. | |
|
||||
| | Reexpedi.| Envio repos.| $1,200| Empresa | Pend. | |
|
||||
| |----------|-------------|-------|---------|--------| |
|
||||
| | TOTAL | $5,700| | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| AGREGAR CONCEPTO |
|
||||
| |
|
||||
| Tipo: [Dano a mercancia v] |
|
||||
| o Dano a mercancia |
|
||||
| o Penalizacion SLA |
|
||||
| o Reexpedicion |
|
||||
| o Deducible seguro |
|
||||
| o Multa transito |
|
||||
| o Faltante |
|
||||
| |
|
||||
| Descripcion: [________________________________] |
|
||||
| Monto: [$________] |
|
||||
| |
|
||||
| Cargo a: |
|
||||
| ( ) Cliente (genera nota de credito) |
|
||||
| (o) Empresa (costo operativo) |
|
||||
| ( ) Operador (deduccion en liquidacion) |
|
||||
| ( ) Tercero/Carrier (reclamo) |
|
||||
| ( ) Seguro (expediente de reclamo) |
|
||||
| |
|
||||
| [Agregar concepto] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| MOVIMIENTOS FINANCIEROS A GENERAR |
|
||||
| |
|
||||
| [x] Nota de credito a CEMEX por $4,500.00 |
|
||||
| Motivo: Dano a mercancia en viaje VJE-0125 |
|
||||
| |
|
||||
| [ ] Deduccion a operador (No aplica) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ! Monto > $1,000 requiere aprobacion de supervisor |
|
||||
| |
|
||||
| [Cancelar] [Solicitar Aprobacion] [Aplicar] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reporte de Incidencias por Costo
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REPORTE: COSTO DE INCIDENCIAS |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Periodo: Enero 2026 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESUMEN POR TIPO |
|
||||
| |
|
||||
| | Tipo | Cantidad | Costo Total | % del Total | |
|
||||
| |------------|----------|-------------|-------------| |
|
||||
| | Dano | 8 | $45,200.00 | 42% | |
|
||||
| | Faltante | 12 | $28,500.00 | 26% | |
|
||||
| | Retraso | 25 | $18,000.00 | 17% | |
|
||||
| | Robo | 2 | $12,000.00 | 11% | |
|
||||
| | Otros | 5 | $4,300.00 | 4% | |
|
||||
| |------------|----------|-------------|-------------| |
|
||||
| | TOTAL | 52 | $108,000.00 | 100% | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TOP 5 CLIENTES CON MAS INCIDENCIAS |
|
||||
| |
|
||||
| 1. CEMEX S.A. - 12 incidencias - $32,000 |
|
||||
| 2. Liverpool - 8 incidencias - $18,500 |
|
||||
| 3. Bimbo - 6 incidencias - $12,200 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| KPI: Costo incidencias / Ingresos = 2.1% |
|
||||
| (Meta: < 3%) |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Movimiento Financiero
|
||||
|
||||
| Responsable | Movimiento | Destino |
|
||||
|-------------|------------|---------|
|
||||
| Cliente | Nota de credito | MAI-009 Facturacion |
|
||||
| Empresa | Gasto operativo | Contabilidad |
|
||||
| Operador | Deduccion | MAI-010 Liquidaciones |
|
||||
| Tercero/Carrier | Reclamo | CxC Terceros |
|
||||
| Seguro | Expediente | Gestion separada |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `tracking.costos_incidencia`
|
||||
- Tabla: `billing.movimientos_incidencia`
|
||||
- Relacion con `settlements.deducciones`
|
||||
- Umbral de aprobacion configurable por tenant
|
||||
- Reportes en modulo MAE-018
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Registro de multiples conceptos de costo
|
||||
- [ ] Asignacion de responsable por concepto
|
||||
- [ ] Flujo de aprobacion para montos altos
|
||||
- [ ] Generacion de movimientos financieros
|
||||
- [ ] Asociacion a viaje para rentabilidad
|
||||
- [ ] Reporte de costos por periodo
|
||||
- [ ] Tests de calculo e integracion
|
||||
245
docs/02-definicion-modulos/MAI-011-gestion-flota/README.md
Normal file
245
docs/02-definicion-modulos/MAI-011-gestion-flota/README.md
Normal file
@ -0,0 +1,245 @@
|
||||
# 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*
|
||||
@ -0,0 +1,168 @@
|
||||
# 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*
|
||||
@ -0,0 +1,126 @@
|
||||
# RESUMEN-EPICA.md - MAI-011 Gestion de Flota
|
||||
|
||||
**Epica:** EPIC-MAI-011 | **Modulo:** MAI-011 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Epica: EPIC-MAI-011 - Gestion de Flota
|
||||
|
||||
### Descripcion de la Epica
|
||||
|
||||
Como empresa transportista de carga, necesitamos un sistema integral para gestionar toda nuestra flota vehicular (unidades motrices y remolques), operadores/conductores y su documentacion asociada. El sistema debe garantizar que solo recursos con documentacion vigente y en condiciones aptas puedan ser asignados a viajes, cumpliendo con la normatividad mexicana de autotransporte federal (permisos SCT, licencia federal tipo F, verificaciones, polizas de seguro, certificados fisicos medicos y pruebas antidoping).
|
||||
|
||||
### Objetivo de Negocio
|
||||
|
||||
Eliminar el control manual (Excel, WhatsApp, carpetas fisicas) de la flota vehicular y operadores, reduciendo riesgos operativos por documentacion vencida, mejorando la disponibilidad de recursos y asegurando cumplimiento regulatorio ante la Secretaria de Infraestructura, Comunicaciones y Transportes (SICT, antes SCT).
|
||||
|
||||
### Metricas de Exito
|
||||
|
||||
| Metrica | Objetivo | Medicion |
|
||||
|---------|----------|----------|
|
||||
| Tiempo de registro de unidad | < 5 minutos | Desde inicio de captura hasta guardado |
|
||||
| Documentos vencidos no detectados | 0% | Ningun recurso opera con documentos vencidos |
|
||||
| Disponibilidad de flota visible | 100% | Dashboard actualizado en tiempo real |
|
||||
| Tiempo de busqueda de operador disponible | < 30 segundos | Desde consulta hasta resultado |
|
||||
| Reduccion de incidencias por documentos | -80% | Comparado con proceso manual |
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Alta, baja y modificacion de unidades motrices (tractocamiones, tortones, rabones, camionetas)
|
||||
- Alta, baja y modificacion de remolques (caja seca, refrigerada, plataforma, tanque, portacontenedor)
|
||||
- Gestion completa de operadores/conductores (datos personales, licencias, certificaciones, datos bancarios)
|
||||
- Gestion de documentos con vigencia para las tres entidades (unidad, remolque, operador)
|
||||
- Alertas automaticas de vencimiento de documentos
|
||||
- Bloqueo automatico de recursos con documentacion vencida
|
||||
- Asignaciones operador-unidad-remolque con historial
|
||||
- Dashboard de disponibilidad de flota
|
||||
- Busqueda de operadores disponibles con filtros
|
||||
- Configuraciones vehiculares (tractora + remolque)
|
||||
- Exportacion de reportes de flota
|
||||
|
||||
### Excluido (cubierto por otros modulos)
|
||||
- Mantenimiento preventivo y correctivo (MAI-013)
|
||||
- Control de combustible y gastos de viaje (MAI-012)
|
||||
- Gestion de carriers/terceros (MAI-014)
|
||||
- Tracking GPS en tiempo real (MAI-006)
|
||||
- Liquidacion y pago a operadores (MAI-010)
|
||||
- Carta Porte y datos fiscales del viaje (MAE-016)
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Titulo | SP | Prioridad | Estado |
|
||||
|----|--------|----|-----------|--------|
|
||||
| US-MAI011-001 | Registrar unidad nueva en flota | 5 | P0 | Backlog |
|
||||
| US-MAI011-002 | Registrar operador con documentos | 8 | P0 | Backlog |
|
||||
| US-MAI011-003 | Consultar disponibilidad de recursos | 5 | P0 | Backlog |
|
||||
| US-MAI011-004 | Asignar operador a unidad | 3 | P1 | Backlog |
|
||||
| US-MAI011-005 | Recibir alerta de documento por vencer | 5 | P0 | Backlog |
|
||||
| US-MAI011-006 | Bloquear unidad por mantenimiento vencido | 5 | P1 | Backlog |
|
||||
| US-MAI011-007 | Ver historial de asignaciones | 3 | P2 | Backlog |
|
||||
| US-MAI011-008 | Registrar cambio de status de unidad | 3 | P1 | Backlog |
|
||||
| US-MAI011-009 | Dashboard de flota (disponibilidad) | 5 | P1 | Backlog |
|
||||
| US-MAI011-010 | Buscar operador disponible | 3 | P1 | Backlog |
|
||||
| US-MAI011-011 | Configurar combinacion vehicular | 5 | P1 | Backlog |
|
||||
| US-MAI011-012 | Exportar reporte de flota | 3 | P2 | Backlog |
|
||||
|
||||
### Resumen de Esfuerzo
|
||||
|
||||
| Prioridad | Historias | Story Points |
|
||||
|-----------|-----------|-------------|
|
||||
| P0 (Critico) | 4 | 23 |
|
||||
| P1 (Importante) | 6 | 24 |
|
||||
| P2 (Deseable) | 2 | 6 |
|
||||
| **Total** | **12** | **53** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias Criticas
|
||||
|
||||
### Prerequisitos (debe completarse antes)
|
||||
- MAI-001: Fundamentos (Auth, RBAC, multi-tenancy) debe estar operativo
|
||||
- Schema `fleet` creado en la base de datos con DDL `02-fleet-schema-ddl.sql`
|
||||
- ENUMs `fleet.tipo_unidad` y `fleet.estado_unidad` creados en `00-schemas-init.sql`
|
||||
|
||||
### Habilita (otros modulos dependen de este)
|
||||
- MAI-003: Ordenes de Transporte (necesita unidades/operadores para asignar)
|
||||
- MAI-004: Planeacion TMS (consulta disponibilidad de recursos)
|
||||
- MAI-005: Despacho (verifica aptitud de recursos)
|
||||
- MAI-013: Mantenimiento (opera sobre las unidades registradas aqui)
|
||||
- MAE-016: Carta Porte (usa datos de unidad/operador en complemento fiscal)
|
||||
|
||||
---
|
||||
|
||||
## Riesgos Identificados
|
||||
|
||||
| Riesgo | Impacto | Mitigacion |
|
||||
|--------|---------|------------|
|
||||
| Datos incompletos de unidades existentes | Alto | Proceso de migracion con validacion obligatoria |
|
||||
| Operadores sin licencia federal digitalizada | Medio | Periodo de gracia con alertas diarias |
|
||||
| Resistencia al cambio (de Excel a sistema) | Medio | Capacitacion y soporte en sitio |
|
||||
| Documentos fisicos sin digitalizar | Alto | Flujo de captura con smartphone (foto directa) |
|
||||
| Multiples unidades de un mismo carrier | Bajo | Campo `es_propia` y `propietario_id` en entidades |
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion de la Epica
|
||||
|
||||
1. Se pueden registrar unidades motrices de todos los tipos (tractora, torton, rabon, camioneta) con datos completos
|
||||
2. Se pueden registrar remolques de todos los tipos (caja seca, refrigerada, plataforma, tanque, portacontenedor)
|
||||
3. Se pueden registrar operadores con licencia federal y certificaciones
|
||||
4. Se pueden subir documentos con vigencia para unidades, remolques y operadores
|
||||
5. El sistema genera alertas automaticas cuando un documento esta por vencer (30 dias por defecto)
|
||||
6. El sistema bloquea automaticamente recursos con documentacion vencida
|
||||
7. Se pueden crear asignaciones operador-unidad-remolque con historial
|
||||
8. El dashboard muestra el estado de disponibilidad de toda la flota en tiempo real
|
||||
9. Se puede buscar y filtrar operadores disponibles por criterios
|
||||
10. Se puede exportar un reporte de la flota en formato Excel o PDF
|
||||
11. Todas las operaciones respetan multi-tenancy (RLS) y RBAC
|
||||
|
||||
---
|
||||
|
||||
*EPIC-MAI-011 Gestion de Flota - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,98 @@
|
||||
# MAI-012: Combustible y Gastos de Viaje
|
||||
|
||||
**Modulo:** MAI-012
|
||||
**Nombre:** Combustible y Gastos de Viaje
|
||||
**Prioridad:** P2
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Modulo para control de combustible, peajes y gastos variables de viaje. Incluye registro de cargas, control de rendimiento, deteccion de anomalias/fraude y liquidacion de viaticos.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Registrar cargas de combustible con evidencias
|
||||
2. Controlar rendimiento real vs esperado por unidad
|
||||
3. Detectar anomalias y posibles fugas/fraude
|
||||
4. Gestionar peajes y gastos varios
|
||||
5. Liquidar anticipos de viaticos
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Operador | Registra cargas y gastos |
|
||||
| Control Combustible | Aprueba y analiza rendimientos |
|
||||
| Despachador | Entrega anticipos |
|
||||
| Administracion | Aprueba gastos y detecta anomalias |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Depende de | Para |
|
||||
|------------|------|
|
||||
| MAI-011 (Flota) | Datos de unidades |
|
||||
| MAI-006 (Tracking) | Km recorridos reales |
|
||||
| MAI-003 (OT) | Viajes asociados |
|
||||
| MAI-010 (Liquidaciones) | Viaticos y deducciones |
|
||||
|
||||
---
|
||||
|
||||
## Entidades del Modulo
|
||||
|
||||
| Entidad | Tabla | Descripcion |
|
||||
|---------|-------|-------------|
|
||||
| CargaCombustible | fuel.cargas_combustible | Cargas de combustible |
|
||||
| CrucePeaje | fuel.cruces_peaje | Cruces de casetas |
|
||||
| GastoViaje | fuel.gastos_viaje | Gastos varios |
|
||||
| AnticipoViatico | fuel.anticipos_viaticos | Anticipos de viaticos |
|
||||
| ControlRendimiento | fuel.control_rendimiento | Control de rendimiento |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
Viaje asignado → Solicitud anticipo → Entrega efectivo →
|
||||
Cargas combustible → Peajes → Gastos varios →
|
||||
Cierre viaje → Comprobacion gastos → Liquidacion
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alertas Antifraude
|
||||
|
||||
| Alerta | Descripcion | Accion |
|
||||
|--------|-------------|--------|
|
||||
| Consumo excesivo | Rendimiento < 70% esperado | Investigar |
|
||||
| Carga fuera de ruta | GPS fuera de corredor | Rechazar |
|
||||
| Carga duplicada | Misma hora/estacion | Bloquear |
|
||||
| Ticket alterado | OCR detecta alteracion | Revisar |
|
||||
| Frecuencia anomala | Muchas cargas en poco tiempo | Alertar |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAI-012-combustible-gastos/
|
||||
├── README.md <- Este archivo
|
||||
├── ENTITIES.md <- Entidades (existente)
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAI012-001.md <- Registrar carga combustible
|
||||
├── US-MAI012-002.md <- Controlar rendimiento
|
||||
└── US-MAI012-003.md <- Liquidar anticipo viaticos
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAI-012 Combustible y Gastos - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,179 @@
|
||||
# REQUERIMIENTOS - MAI-012: Combustible y Gastos de Viaje
|
||||
|
||||
**Modulo:** MAI-012
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.10
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.10.1: Planeado vs Real
|
||||
|
||||
**Descripcion:** Comparar consumo esperado vs real por unidad y ruta.
|
||||
|
||||
**Datos de comparacion:**
|
||||
| Metrica | Fuente Esperado | Fuente Real |
|
||||
|---------|-----------------|-------------|
|
||||
| km | Ruta planeada | Tracking GPS |
|
||||
| Litros | Ficha tecnica × km | Cargas registradas |
|
||||
| Costo | Presupuesto viaje | Suma gastos |
|
||||
|
||||
**Calculos:**
|
||||
- Rendimiento esperado: km/litro segun tipo unidad
|
||||
- Rendimiento real: km recorridos / litros cargados
|
||||
- Desviacion: (real - esperado) / esperado × 100
|
||||
|
||||
**Umbrales de alerta (configurables):**
|
||||
| Nivel | Desviacion | Accion |
|
||||
|-------|------------|--------|
|
||||
| Normal | ±10% | Ninguna |
|
||||
| Atencion | ±10-20% | Notificacion |
|
||||
| Critico | >20% | Bloqueo/Investigacion |
|
||||
|
||||
**Tablas DDL:**
|
||||
- `fuel.control_rendimiento`
|
||||
- `fuel.cargas_combustible`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.10.2: Captura de Cargas de Combustible
|
||||
|
||||
**Descripcion:** Registrar cada carga con datos completos y evidencia.
|
||||
|
||||
**Datos obligatorios:**
|
||||
- Unidad (FK)
|
||||
- Operador (FK)
|
||||
- Tipo de carga (vale, tarjeta, efectivo, factura)
|
||||
- Tipo combustible (diesel, magna, premium)
|
||||
- Litros
|
||||
- Precio por litro
|
||||
- Total
|
||||
- Odometro
|
||||
- Estacion (nombre, direccion)
|
||||
- Ubicacion GPS
|
||||
- Fecha/hora
|
||||
- Foto del ticket
|
||||
|
||||
**Validaciones:**
|
||||
- GPS debe estar cerca de estacion de servicio
|
||||
- Odometro > ultimo odometro registrado
|
||||
- No permitir cargas duplicadas (misma hora/estacion)
|
||||
- Validar capacidad del tanque
|
||||
|
||||
**Tablas DDL:**
|
||||
- `fuel.cargas_combustible`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.10.3: Peajes
|
||||
|
||||
**Descripcion:** Registrar cruces de casetas con integracion a TAG o captura manual.
|
||||
|
||||
**Modalidades:**
|
||||
1. **Integracion TAG** (IAVE/Televia)
|
||||
- Importar cruces automaticamente
|
||||
- Conciliar vs reporte proveedor
|
||||
|
||||
2. **Captura manual**
|
||||
- Foto de ticket
|
||||
- Datos de caseta
|
||||
|
||||
**Prorrateo:**
|
||||
- Si viaje tiene multiples OTs: prorratear por peso/distancia
|
||||
- Asignar a centro de costo correcto
|
||||
|
||||
**Tablas DDL:**
|
||||
- `fuel.cruces_peaje`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.10.4: Gastos Varios
|
||||
|
||||
**Descripcion:** Registrar gastos adicionales de viaje.
|
||||
|
||||
**Tipos de gasto:**
|
||||
| Tipo | Requiere Factura | Requiere Aprobacion |
|
||||
|------|------------------|---------------------|
|
||||
| Hospedaje | Si | Si (>$500) |
|
||||
| Alimentos | No | No |
|
||||
| Estacionamiento | No | No |
|
||||
| Maniobras | Si | Si |
|
||||
| Reparacion menor | Si | Si |
|
||||
| Multa | Si | Si |
|
||||
| Otro | Configurable | Si |
|
||||
|
||||
**Gastos NO permitidos (bloqueo por politica):**
|
||||
- "Mordidas" / sobornos
|
||||
- Entretenimiento
|
||||
- Gastos personales
|
||||
|
||||
**Tablas DDL:**
|
||||
- `fuel.gastos_viaje`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.10.5: Alertas Antifraude
|
||||
|
||||
**Descripcion:** Detectar y alertar sobre anomalias en gastos de combustible.
|
||||
|
||||
**Tipos de alerta:**
|
||||
| Codigo | Descripcion | Severidad |
|
||||
|--------|-------------|-----------|
|
||||
| CONSUMO_EXCESIVO | Rendimiento < 70% esperado | Alta |
|
||||
| CARGA_FUERA_RUTA | GPS > 5km de ruta | Media |
|
||||
| CARGA_DUPLICADA | Misma estacion en <2h | Alta |
|
||||
| TICKET_ALTERADO | OCR detecta inconsistencia | Alta |
|
||||
| FRECUENCIA_ALTA | >3 cargas en 24h | Media |
|
||||
| TANQUE_EXCEDIDO | Litros > capacidad tanque | Critica |
|
||||
| HORARIO_INUSUAL | Carga en madrugada (2-5am) | Baja |
|
||||
|
||||
**Acciones por severidad:**
|
||||
| Severidad | Accion |
|
||||
|-----------|--------|
|
||||
| Critica | Bloqueo automatico + alerta jefe |
|
||||
| Alta | Alerta a supervisor + revision |
|
||||
| Media | Notificacion a control |
|
||||
| Baja | Log para analisis posterior |
|
||||
|
||||
**Tablas DDL:**
|
||||
- `fuel.alertas_fraude`
|
||||
- `fuel.control_rendimiento.tieneAnomalia`
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Captura Offline
|
||||
- App movil permite captura sin conexion
|
||||
- Sincroniza al recuperar red
|
||||
- Foto se comprime localmente
|
||||
|
||||
### RNF-002: Integracion GPS
|
||||
- Captura automatica de ubicacion
|
||||
- Validacion contra geocercas de estaciones
|
||||
|
||||
### RNF-003: OCR (Opcional)
|
||||
- Extraccion automatica de datos de ticket
|
||||
- Validacion cruzada con captura manual
|
||||
|
||||
### RNF-004: Reportes
|
||||
- Dashboard de rendimiento por unidad
|
||||
- Analisis de tendencias
|
||||
- Comparativo entre operadores
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tablas DDL | Endpoints | Historias |
|
||||
|----|------------|-----------|-----------|
|
||||
| RF-4.10.1 | control_rendimiento | GET /rendimiento | US-MAI012-002 |
|
||||
| RF-4.10.2 | cargas_combustible | POST /cargas | US-MAI012-001 |
|
||||
| RF-4.10.3 | cruces_peaje | POST /peajes | US-MAI012-001 |
|
||||
| RF-4.10.4 | gastos_viaje | POST /gastos | US-MAI012-003 |
|
||||
| RF-4.10.5 | alertas_fraude | GET /alertas | US-MAI012-002 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAI-012 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,79 @@
|
||||
# RESUMEN EPICA - MAI-012: Combustible y Gastos de Viaje
|
||||
|
||||
**Modulo:** MAI-012
|
||||
**Prioridad:** P2
|
||||
**Story Points Total:** 18
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- Fugas de combustible no detectadas (5-15% del costo)
|
||||
- Gastos sin comprobacion ni trazabilidad
|
||||
- Rendimiento por unidad desconocido
|
||||
- Fraude en vales y tickets
|
||||
|
||||
### Beneficios
|
||||
- **Control de costos** variables por viaje
|
||||
- **Deteccion de anomalias** automatica
|
||||
- **Rendimiento medido** por unidad/operador
|
||||
- **Liquidacion automatizada** de viaticos
|
||||
|
||||
### KPIs Impactados
|
||||
- Costo por km
|
||||
- Rendimiento km/litro por unidad
|
||||
- % anomalias detectadas
|
||||
- Tiempo de liquidacion viaticos
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Registro de cargas combustible
|
||||
- Control de rendimiento
|
||||
- Alertas antifraude
|
||||
- Peajes (manual + TAG)
|
||||
- Gastos varios
|
||||
- Liquidacion de anticipos
|
||||
|
||||
### Excluido
|
||||
- Integracion directa con bombas
|
||||
- OCR avanzado (fase posterior)
|
||||
- Prediccion de consumo con ML
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAI012-001 | Registrar carga de combustible | 5 |
|
||||
| US-MAI012-002 | Controlar rendimiento y detectar anomalias | 8 |
|
||||
| US-MAI012-003 | Liquidar anticipo de viaticos | 5 |
|
||||
| **Total** | | **18** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
MAI-011 (Flota) ───┐
|
||||
MAI-006 (Tracking)─┼──> MAI-012 ──> MAI-010 (Liquidaciones)
|
||||
MAI-003 (OT) ──────┘ ──> MAE-018 (Reportes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Resistencia de operadores | Capacitacion + incentivos |
|
||||
| GPS impreciso | Tolerancia configurable |
|
||||
| Falsos positivos fraude | Revision humana requerida |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAI-012 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,140 @@
|
||||
# US-MAI012-001: Registrar carga de combustible
|
||||
|
||||
**ID:** US-MAI012-001
|
||||
**Modulo:** MAI-012 (Combustible y Gastos)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** operador
|
||||
**Quiero** registrar cada carga de combustible con evidencia
|
||||
**Para** documentar el consumo y facilitar el control de rendimiento
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Capturar datos de carga
|
||||
**Dado** que cargo combustible durante el viaje
|
||||
**Cuando** registro la carga en la app
|
||||
**Entonces** capturo: litros, precio, estacion, odometro, tipo combustible
|
||||
|
||||
### CA-002: Tomar foto del ticket
|
||||
**Dado** que necesito comprobar la carga
|
||||
**Cuando** registro
|
||||
**Entonces** tomo foto del ticket que se sube como evidencia
|
||||
|
||||
### CA-003: Captura GPS automatica
|
||||
**Dado** que estoy en la estacion
|
||||
**Cuando** registro la carga
|
||||
**Entonces** el sistema captura mi ubicacion automaticamente
|
||||
|
||||
### CA-004: Validar odometro
|
||||
**Dado** que el odometro debe ser consistente
|
||||
**Cuando** ingreso el valor
|
||||
**Entonces** valida que sea > ultimo odometro registrado
|
||||
|
||||
### CA-005: Soporte offline
|
||||
**Dado** que puedo estar sin conexion
|
||||
**Cuando** registro una carga
|
||||
**Entonces** se guarda localmente y sincroniza despues
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REGISTRAR CARGA COMBUSTIBLE X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Unidad: T-1025 | Kenworth T680 |
|
||||
| Viaje: VJE-0125 | CDMX -> Monterrey |
|
||||
| Odometro anterior: 485,230 km |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DATOS DE LA CARGA |
|
||||
| |
|
||||
| Tipo combustible: [DIESEL v] |
|
||||
| |
|
||||
| Tipo de pago: |
|
||||
| (o) Vale de combustible |
|
||||
| ( ) Tarjeta empresa |
|
||||
| ( ) Efectivo (viatico) |
|
||||
| |
|
||||
| Numero de vale: [V-2026-01254 ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CANTIDADES |
|
||||
| |
|
||||
| Litros cargados: [450.500 ] L |
|
||||
| Precio por litro: [$24.35 ] |
|
||||
| Total: $10,969.68 |
|
||||
| |
|
||||
| Odometro actual: [485,890 ] km |
|
||||
| km desde ultima carga: 660 km |
|
||||
| Rendimiento: 1.47 km/L [!] Bajo (esperado: 2.8) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ESTACION |
|
||||
| |
|
||||
| [!] Ubicacion GPS: 25.6866, -100.3161 |
|
||||
| |
|
||||
| Estacion: [PEMEX Monterrey Norte ] |
|
||||
| Direccion: [Av. Lincoln 2500, MTY ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EVIDENCIA |
|
||||
| |
|
||||
| [Camara] Tomar foto del ticket |
|
||||
| |
|
||||
| [IMG] ticket_pemex_001.jpg OK |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Cancelar] [Guardar Carga] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validaciones
|
||||
|
||||
| Validacion | Regla | Mensaje Error |
|
||||
|------------|-------|---------------|
|
||||
| Odometro | > ultimo registrado | Odometro debe ser mayor a 485,230 |
|
||||
| Litros | <= capacidad tanque | Excede capacidad del tanque (800L) |
|
||||
| GPS | Cerca de estacion | Ubicacion no corresponde a estacion |
|
||||
| Foto | Obligatoria | Debe adjuntar foto del ticket |
|
||||
| Duplicado | No misma hora/estacion | Ya existe carga similar |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `fuel.cargas_combustible`
|
||||
- Foto a S3 con compresion (max 2MB)
|
||||
- GPS con tolerancia de 500m a estacion
|
||||
- Calculo rendimiento: km / litros
|
||||
- Alerta si rendimiento < 70% esperado
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Formulario de captura completo
|
||||
- [ ] Captura GPS automatica
|
||||
- [ ] Carga de foto de ticket
|
||||
- [ ] Validacion de odometro
|
||||
- [ ] Calculo de rendimiento
|
||||
- [ ] Alerta si rendimiento bajo
|
||||
- [ ] Soporte offline
|
||||
- [ ] Tests de captura y validaciones
|
||||
@ -0,0 +1,195 @@
|
||||
# US-MAI012-002: Controlar rendimiento y detectar anomalias
|
||||
|
||||
**ID:** US-MAI012-002
|
||||
**Modulo:** MAI-012 (Combustible y Gastos)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** administrador de control de combustible
|
||||
**Quiero** monitorear el rendimiento de las unidades y detectar anomalias
|
||||
**Para** prevenir fugas, fraude y optimizar costos
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Dashboard de rendimiento
|
||||
**Dado** que necesito vision general
|
||||
**Cuando** accedo al modulo de combustible
|
||||
**Entonces** veo dashboard con rendimiento de toda la flota
|
||||
|
||||
### CA-002: Comparativo esperado vs real
|
||||
**Dado** que cada unidad tiene rendimiento esperado
|
||||
**Cuando** consulto una unidad
|
||||
**Entonces** veo comparativo con desviacion porcentual
|
||||
|
||||
### CA-003: Alertas automaticas
|
||||
**Dado** que hay umbrales de anomalia definidos
|
||||
**Cuando** una carga excede el umbral
|
||||
**Entonces** se genera alerta automatica
|
||||
|
||||
### CA-004: Investigar anomalias
|
||||
**Dado** que hay una alerta de posible fraude
|
||||
**Cuando** la investigo
|
||||
**Entonces** veo detalle de cargas, ubicaciones, timeline
|
||||
|
||||
### CA-005: Reportes por periodo
|
||||
**Dado** que necesito analisis historico
|
||||
**Cuando** genero reporte
|
||||
**Entonces** veo tendencias de rendimiento por unidad/operador
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Dashboard de Rendimiento
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| CONTROL DE COMBUSTIBLE - Dashboard |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Periodo: [Enero 2026 v] [Actualizar] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESUMEN FLOTA |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | 35 Unidades | | 2.45 km/L | | $1.8M | |
|
||||
| | Activas | | Prom. Rend. | | Gasto Comb. | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | 5 Alertas | | 2 Criticas | | 98.2% | |
|
||||
| | Pendientes | | Por revisar | | Comprobado | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| UNIDADES CON ANOMALIA |
|
||||
| |
|
||||
| | Unidad | Rend.Real | Esperado | Desv. | Alerta ||
|
||||
| |---------|-----------|----------|-------|-----------|
|
||||
| | T-1025 | 1.47 | 2.80 | -47% | CRITICA ||
|
||||
| | T-1032 | 2.10 | 2.80 | -25% | ALTA ||
|
||||
| | R-0089 | 1.95 | 2.50 | -22% | MEDIA ||
|
||||
| |
|
||||
| [Ver todas las unidades] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RENDIMIENTO POR UNIDAD (Top 10 / Bottom 10) |
|
||||
| |
|
||||
| T-1015 ████████████████████████ 3.2 km/L |
|
||||
| T-1018 ███████████████████████ 3.1 km/L |
|
||||
| T-1022 ██████████████████████ 3.0 km/L |
|
||||
| ... |
|
||||
| T-1032 ████████████ 2.1 km/L [!] |
|
||||
| T-1025 ████████ 1.5 km/L [!] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Detalle de Anomalia
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| ALERTA: Bajo Rendimiento - T-1025 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Unidad: T-1025 | Kenworth T680 |
|
||||
| Operador: Juan Perez Garcia |
|
||||
| Periodo: 20-ene a 27-ene-2026 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| INDICADORES |
|
||||
| |
|
||||
| Rendimiento real: 1.47 km/L |
|
||||
| Rendimiento esperado: 2.80 km/L |
|
||||
| Desviacion: -47.5% [!!! CRITICO] |
|
||||
| |
|
||||
| km Recorridos: 2,310 km |
|
||||
| Litros consumidos: 1,571 L |
|
||||
| Costo total: $38,253.85 |
|
||||
| Costo esperado: $20,063.00 |
|
||||
| Sobrecosto: $18,190.85 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CARGAS EN EL PERIODO |
|
||||
| |
|
||||
| | Fecha | Estacion | Litros | GPS | Foto ||
|
||||
| |---------|---------------|--------|----------|------||
|
||||
| | 21-ene | PEMEX Qro | 450 L | [OK] | [Ver]||
|
||||
| | 22-ene | PEMEX SLP | 380 L | [OK] | [Ver]||
|
||||
| | 24-ene | PEMEX MTY | 420 L | [!] | [Ver]||
|
||||
| | 26-ene | PEMEX MTY | 321 L | [OK] | [Ver]||
|
||||
| |
|
||||
| [!] Carga del 24-ene: GPS a 8km de estacion |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| MAPA DE CARGAS |
|
||||
| |
|
||||
| [Mapa mostrando ruta vs ubicaciones de carga] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| POSIBLES CAUSAS |
|
||||
| |
|
||||
| [x] Fuga/robo de combustible |
|
||||
| [ ] Falla mecanica (inyectores, bomba) |
|
||||
| [ ] Ruta ineficiente |
|
||||
| [ ] Carga pesada / condiciones adversas |
|
||||
| [ ] Ticket alterado |
|
||||
| |
|
||||
| Accion: [Enviar a taller para revision v] |
|
||||
| |
|
||||
| Comentario: |
|
||||
| [Se sospecha de robo. Unidad a revision mecanic... ]|
|
||||
| |
|
||||
| [Cerrar sin accion] [Crear tarea] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Alerta
|
||||
|
||||
| Codigo | Descripcion | Umbral | Accion |
|
||||
|--------|-------------|--------|--------|
|
||||
| CONSUMO_EXCESIVO | Rendimiento muy bajo | < 70% esperado | Investigar |
|
||||
| CARGA_FUERA_RUTA | GPS lejos de ruta | > 5 km | Rechazar |
|
||||
| CARGA_DUPLICADA | Misma estacion/hora | < 2 horas | Bloquear |
|
||||
| TANQUE_EXCEDIDO | Mas de capacidad | > 100% | Bloquear |
|
||||
| HORARIO_INUSUAL | Carga en madrugada | 2am-5am | Revisar |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `fuel.control_rendimiento`
|
||||
- Tabla: `fuel.alertas_fraude`
|
||||
- Job diario calcula rendimiento
|
||||
- Notificaciones push/email por alerta
|
||||
- Dashboard con graficas Recharts
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Dashboard de rendimiento de flota
|
||||
- [ ] Comparativo esperado vs real
|
||||
- [ ] Sistema de alertas automaticas
|
||||
- [ ] Detalle de anomalia con evidencias
|
||||
- [ ] Mapa de cargas vs ruta
|
||||
- [ ] Reportes por periodo
|
||||
- [ ] Notificaciones por severidad
|
||||
- [ ] Tests de deteccion de anomalias
|
||||
@ -0,0 +1,159 @@
|
||||
# US-MAI012-003: Liquidar anticipo de viaticos
|
||||
|
||||
**ID:** US-MAI012-003
|
||||
**Modulo:** MAI-012 (Combustible y Gastos)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** administrador
|
||||
**Quiero** liquidar los anticipos de viaticos al cierre de viaje
|
||||
**Para** controlar el efectivo entregado y el saldo a favor/cargo
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Ver resumen de gastos
|
||||
**Dado** que el operador regreso del viaje
|
||||
**Cuando** inicio la liquidacion
|
||||
**Entonces** veo todos los gastos reportados vs anticipo
|
||||
|
||||
### CA-002: Validar comprobantes
|
||||
**Dado** que el operador presenta comprobantes
|
||||
**Cuando** los reviso
|
||||
**Entonces** puedo aprobar o rechazar cada gasto
|
||||
|
||||
### CA-003: Calcular saldo
|
||||
**Dado** que hay diferencia entre anticipo y gastos
|
||||
**Cuando** se calculan
|
||||
**Entonces** veo si hay reintegro (a favor empresa) o adicional (a favor operador)
|
||||
|
||||
### CA-004: Registrar reintegro
|
||||
**Dado** que el operador debe devolver dinero
|
||||
**Cuando** liquido
|
||||
**Entonces** registro el reintegro o genero deduccion en liquidacion
|
||||
|
||||
### CA-005: Cerrar liquidacion
|
||||
**Dado** que todo esta conciliado
|
||||
**Cuando** cierro la liquidacion
|
||||
**Entonces** el estado cambia a LIQUIDADO
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| LIQUIDAR ANTICIPO - VJE-0125 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Viaje: VJE-0125 | CDMX -> Monterrey |
|
||||
| Operador: Juan Perez Garcia |
|
||||
| Fecha viaje: 20-ene a 25-ene-2026 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ANTICIPO ENTREGADO |
|
||||
| |
|
||||
| Monto aprobado: $7,500.00 |
|
||||
| Fecha entrega: 20-ene-2026 |
|
||||
| Entregado por: Maria Gonzalez |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| GASTOS REPORTADOS |
|
||||
| |
|
||||
| | Fecha | Tipo | Descripcion | Monto | St ||
|
||||
| |-------|-------------|----------------|---------|----||
|
||||
| | 21-ene| Combustible | PEMEX Qro |$4,350.00| OK ||
|
||||
| | 22-ene| Combustible | PEMEX SLP |$1,890.00| OK ||
|
||||
| | 21-ene| Peaje | TAG IAVE | $980.00| OK ||
|
||||
| | 21-ene| Alimentos | Restaurante | $180.00| OK ||
|
||||
| | 22-ene| Alimentos | Restaurante | $150.00| OK ||
|
||||
| | 23-ene| Hospedaje | Hotel Express | $450.00| [?]||
|
||||
| |-------|-------------|----------------|---------|----||
|
||||
| | TOTAL REPORTADO |$8,000.00| ||
|
||||
| |
|
||||
| [?] Hospedaje: Verificar comprobante (foto borrosa) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| REVISAR GASTO |
|
||||
| |
|
||||
| Hospedaje - Hotel Express MTY |
|
||||
| Monto: $450.00 Fecha: 23-ene-2026 |
|
||||
| |
|
||||
| Comprobante: [Ver foto] |
|
||||
| |
|
||||
| Decision: |
|
||||
| (o) Aprobar |
|
||||
| ( ) Rechazar |
|
||||
| |
|
||||
| Motivo rechazo: [________________________] |
|
||||
| |
|
||||
| [Guardar decision] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CALCULO DE SALDO |
|
||||
| |
|
||||
| Anticipo entregado: $7,500.00 |
|
||||
| (-) Gastos aprobados: $8,000.00 |
|
||||
| ────────────────────────────────────── |
|
||||
| Saldo a favor operador: $500.00 |
|
||||
| |
|
||||
| Destino del saldo: |
|
||||
| (o) Pagar en efectivo |
|
||||
| ( ) Incluir en proxima liquidacion |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Cancelar] [Cerrar Liquidacion] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Escenarios de Saldo
|
||||
|
||||
| Escenario | Calculo | Accion |
|
||||
|-----------|---------|--------|
|
||||
| Gasto < Anticipo | Operador devuelve | Reintegro efectivo o deduccion |
|
||||
| Gasto = Anticipo | Sin saldo | Cerrar |
|
||||
| Gasto > Anticipo | Empresa debe | Pago adicional o en liquidacion |
|
||||
|
||||
---
|
||||
|
||||
## Estados del Anticipo
|
||||
|
||||
```
|
||||
SOLICITADO → APROBADO → ENTREGADO → COMPROBANDO → LIQUIDADO
|
||||
↓
|
||||
RECHAZADO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `fuel.anticipos_viaticos`
|
||||
- Relacion con `fuel.gastos_viaje`
|
||||
- Relacion con `settlements.deducciones` (si reintegro)
|
||||
- Fotos de comprobantes en S3
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Vista de anticipo vs gastos reportados
|
||||
- [ ] Revision y aprobacion de cada gasto
|
||||
- [ ] Calculo automatico de saldo
|
||||
- [ ] Opciones de destino del saldo
|
||||
- [ ] Generacion de deduccion si aplica
|
||||
- [ ] Cierre de liquidacion
|
||||
- [ ] Tests de calculo de saldos
|
||||
@ -0,0 +1,85 @@
|
||||
# MAI-013: Mantenimiento de Flota
|
||||
|
||||
**Modulo:** MAI-013
|
||||
**Nombre:** Mantenimiento de Flota
|
||||
**Prioridad:** P2
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Modulo para gestion de mantenimiento preventivo y correctivo de unidades (tractores, remolques, cajas). Controla planes de mantenimiento por km/horas/fecha, ordenes de trabajo, historial de fallas y disponibilidad de flota.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Programar mantenimiento preventivo automatico
|
||||
2. Gestionar ordenes de trabajo (correctivo)
|
||||
3. Controlar disponibilidad de unidades
|
||||
4. Analizar historial de fallas por unidad
|
||||
5. Bloquear unidades con mantenimiento vencido
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Jefe de Mantenimiento | Programa y supervisa |
|
||||
| Mecanico | Ejecuta ordenes de trabajo |
|
||||
| Jefe de Flota | Consulta disponibilidad |
|
||||
| Despachador | Verifica aptitud de unidades |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Depende de | Para |
|
||||
|------------|------|
|
||||
| MAI-011 (Flota) | Datos de unidades |
|
||||
| MAI-006 (Tracking) | Km/horas reales |
|
||||
| MAI-005 (Despacho) | Bloqueo de asignacion |
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Mantenimiento
|
||||
|
||||
| Tipo | Trigger | Ejemplo |
|
||||
|------|---------|---------|
|
||||
| Preventivo por km | Al alcanzar km | Cambio aceite cada 15,000 km |
|
||||
| Preventivo por horas | Al alcanzar horas | Revision motor cada 500 hrs |
|
||||
| Preventivo por fecha | Al vencer fecha | Verificacion anual |
|
||||
| Correctivo | Por falla reportada | Reparacion de frenos |
|
||||
|
||||
---
|
||||
|
||||
## Estados de Unidad
|
||||
|
||||
```
|
||||
DISPONIBLE ←→ EN_VIAJE
|
||||
↓ ↓
|
||||
EN_TALLER ←─── BLOQUEADA (doc vencida)
|
||||
↓
|
||||
BAJA_TEMPORAL / BAJA_DEFINITIVA
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAI-013-mantenimiento-flota/
|
||||
├── README.md <- Este archivo
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAI013-001.md <- Programar mantenimiento preventivo
|
||||
├── US-MAI013-002.md <- Gestionar orden de trabajo
|
||||
└── US-MAI013-003.md <- Controlar disponibilidad
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAI-013 Mantenimiento de Flota - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,185 @@
|
||||
# REQUERIMIENTOS - MAI-013: Mantenimiento de Flota
|
||||
|
||||
**Modulo:** MAI-013
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.11
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.11.1: Plan Preventivo
|
||||
|
||||
**Descripcion:** Programar mantenimiento preventivo automatico por km, horas o fecha.
|
||||
|
||||
**Tipos de trigger:**
|
||||
| Trigger | Parametro | Ejemplo |
|
||||
|---------|-----------|---------|
|
||||
| Por km | Intervalo km | Cada 15,000 km |
|
||||
| Por horas motor | Intervalo horas | Cada 500 hrs |
|
||||
| Por fecha | Periodicidad | Cada 6 meses |
|
||||
| Por evento | Condicion | Post-viaje largo |
|
||||
|
||||
**Planes tipicos por tipo de unidad:**
|
||||
| Unidad | Servicio | Intervalo |
|
||||
|--------|----------|-----------|
|
||||
| Tracto | Cambio aceite | 15,000 km |
|
||||
| Tracto | Revision frenos | 30,000 km |
|
||||
| Tracto | Service mayor | 100,000 km |
|
||||
| Remolque | Revision llantas | 10,000 km |
|
||||
| Remolque | Lubricacion | 5,000 km |
|
||||
|
||||
**Generacion automatica:**
|
||||
- Job diario verifica km/horas/fechas
|
||||
- Al alcanzar umbral → genera OT preventiva
|
||||
- Notifica a jefe de mantenimiento
|
||||
- Pre-agenda fecha tentativa
|
||||
|
||||
**Tablas DDL:**
|
||||
- `maintenance.planes_mantenimiento`
|
||||
- `maintenance.servicios_programados`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.11.2: Mantenimiento Correctivo
|
||||
|
||||
**Descripcion:** Gestionar fallas reportadas con tickets y ordenes de trabajo.
|
||||
|
||||
**Flujo correctivo:**
|
||||
```
|
||||
Falla detectada → Ticket → Diagnostico → OT →
|
||||
Ejecucion → Pruebas → Cierre → Liberacion
|
||||
```
|
||||
|
||||
**Prioridades:**
|
||||
| Nivel | Descripcion | SLA |
|
||||
|-------|-------------|-----|
|
||||
| CRITICA | Unidad parada en ruta | 4 horas |
|
||||
| ALTA | Afecta seguridad | 24 horas |
|
||||
| MEDIA | Afecta operacion | 48 horas |
|
||||
| BAJA | Estetico/menor | 1 semana |
|
||||
|
||||
**Campos de ticket:**
|
||||
- Unidad afectada
|
||||
- Tipo de falla
|
||||
- Descripcion
|
||||
- Fotos
|
||||
- Ubicacion (si en ruta)
|
||||
- Prioridad
|
||||
- Reportado por
|
||||
|
||||
**Tablas DDL:**
|
||||
- `maintenance.tickets_falla`
|
||||
- `maintenance.ordenes_trabajo`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.11.3: Inventario de Refacciones
|
||||
|
||||
**Descripcion:** Control minimo de refacciones para taller propio.
|
||||
|
||||
**Alcance (minimo para el giro):**
|
||||
- Catalogo de refacciones comunes
|
||||
- Stock actual por almacen
|
||||
- Consumo en ordenes de trabajo
|
||||
- Punto de reorden
|
||||
- Costo promedio
|
||||
|
||||
**Fuera de alcance:**
|
||||
- Multialmacen complejo
|
||||
- Lotes y caducidad
|
||||
- Produccion
|
||||
|
||||
**Tablas DDL:**
|
||||
- `maintenance.refacciones`
|
||||
- `maintenance.movimientos_refaccion`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.11.4: Historial por Activo
|
||||
|
||||
**Descripcion:** Mantener historial completo de mantenimientos por unidad.
|
||||
|
||||
**Metricas por unidad:**
|
||||
| Metrica | Descripcion |
|
||||
|---------|-------------|
|
||||
| MTBF | Mean Time Between Failures |
|
||||
| MTTR | Mean Time To Repair |
|
||||
| Costo total | Suma de OTs |
|
||||
| Fallas recurrentes | Misma falla >2 veces |
|
||||
|
||||
**Reportes:**
|
||||
- Historial cronologico de OTs
|
||||
- Costos acumulados
|
||||
- Fallas frecuentes
|
||||
- Comparativo entre unidades similares
|
||||
|
||||
**Tablas DDL:**
|
||||
- `maintenance.historial_unidad` (vista materializada)
|
||||
|
||||
---
|
||||
|
||||
### RF-4.11.5: Disponibilidad de Flota
|
||||
|
||||
**Descripcion:** Controlar estado de cada unidad y bloquear si corresponde.
|
||||
|
||||
**Estados de unidad:**
|
||||
| Estado | Puede asignarse | Motivo |
|
||||
|--------|-----------------|--------|
|
||||
| DISPONIBLE | Si | Lista para viaje |
|
||||
| EN_VIAJE | No | Ya asignada |
|
||||
| EN_TALLER | No | En mantenimiento |
|
||||
| BLOQUEADA | No | Doc vencida o falla critica |
|
||||
| BAJA_TEMPORAL | No | Fuera de servicio temporal |
|
||||
| BAJA_DEFINITIVA | No | Vendida/siniestrada |
|
||||
|
||||
**Bloqueos automaticos:**
|
||||
- Verificacion vehicular vencida
|
||||
- Poliza de seguro vencida
|
||||
- Mantenimiento preventivo vencido
|
||||
- Falla critica no resuelta
|
||||
|
||||
**Dashboard de disponibilidad:**
|
||||
- Total unidades
|
||||
- Disponibles
|
||||
- En viaje
|
||||
- En taller
|
||||
- Bloqueadas
|
||||
- % disponibilidad
|
||||
|
||||
**Tablas DDL:**
|
||||
- `fleet.unidades.estado`
|
||||
- `maintenance.bloqueos_unidad`
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Alertas Proactivas
|
||||
- Notificar 7 dias antes de vencimiento
|
||||
- Notificar 1,000 km antes de servicio
|
||||
- Notificar al 80% de horas de intervalo
|
||||
|
||||
### RNF-002: Integracion Telematica
|
||||
- Obtener km/horas de ECU automaticamente
|
||||
- Detectar codigos de falla OBD
|
||||
|
||||
### RNF-003: Movilidad
|
||||
- App para mecanicos en piso
|
||||
- Fotos de trabajos realizados
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tablas DDL | Endpoints | Historias |
|
||||
|----|------------|-----------|-----------|
|
||||
| RF-4.11.1 | planes_mto, servicios | GET/POST /planes | US-MAI013-001 |
|
||||
| RF-4.11.2 | tickets, ordenes | POST /tickets | US-MAI013-002 |
|
||||
| RF-4.11.3 | refacciones | GET /refacciones | US-MAI013-002 |
|
||||
| RF-4.11.4 | historial_unidad | GET /historial | US-MAI013-003 |
|
||||
| RF-4.11.5 | bloqueos_unidad | GET /disponibilidad | US-MAI013-003 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAI-013 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,79 @@
|
||||
# RESUMEN EPICA - MAI-013: Mantenimiento de Flota
|
||||
|
||||
**Modulo:** MAI-013
|
||||
**Prioridad:** P2
|
||||
**Story Points Total:** 18
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- Mantenimientos vencidos causan fallas en ruta
|
||||
- No hay visibilidad de disponibilidad real
|
||||
- Costos de mantenimiento no controlados
|
||||
- Unidades con documentos vencidos operando
|
||||
|
||||
### Beneficios
|
||||
- **Disponibilidad optimizada** de flota
|
||||
- **Prevencion** de fallas costosas
|
||||
- **Control de costos** por unidad
|
||||
- **Cumplimiento normativo** (NOM-068)
|
||||
|
||||
### KPIs Impactados
|
||||
- % Disponibilidad de flota
|
||||
- MTBF / MTTR
|
||||
- Costo de mantenimiento por km
|
||||
- Cumplimiento de plan preventivo
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Plan de mantenimiento preventivo
|
||||
- Ordenes de trabajo correctivo
|
||||
- Inventario basico de refacciones
|
||||
- Historial por unidad
|
||||
- Control de disponibilidad
|
||||
- Bloqueos automaticos
|
||||
|
||||
### Excluido
|
||||
- Gestion de taller tercero
|
||||
- Multialmacen complejo
|
||||
- Prediccion de fallas (ML)
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAI013-001 | Programar mantenimiento preventivo | 5 |
|
||||
| US-MAI013-002 | Gestionar orden de trabajo correctivo | 8 |
|
||||
| US-MAI013-003 | Controlar disponibilidad de flota | 5 |
|
||||
| **Total** | | **18** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
MAI-011 (Flota) ───┐
|
||||
MAI-006 (Tracking)─┼──> MAI-013 ──> MAI-005 (Despacho)
|
||||
│ ──> MAE-018 (Reportes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Resistencia a bloqueos | Alertas anticipadas |
|
||||
| Datos km inexactos | Integrar telematica |
|
||||
| Falta de mecanicos | Priorizar correctivo |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAI-013 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,177 @@
|
||||
# US-MAI013-001: Programar mantenimiento preventivo
|
||||
|
||||
**ID:** US-MAI013-001
|
||||
**Modulo:** MAI-013 (Mantenimiento)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** jefe de mantenimiento
|
||||
**Quiero** programar mantenimientos preventivos automaticos
|
||||
**Para** prevenir fallas y mantener la flota en optimas condiciones
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Definir plan por tipo de unidad
|
||||
**Dado** que cada tipo de unidad tiene necesidades diferentes
|
||||
**Cuando** configuro el plan de mantenimiento
|
||||
**Entonces** especifico servicios por tipo (tracto, remolque, caja)
|
||||
|
||||
### CA-002: Triggers por km/horas/fecha
|
||||
**Dado** que hay diferentes criterios de programacion
|
||||
**Cuando** defino un servicio
|
||||
**Entonces** puedo elegir trigger por km, horas motor o fecha
|
||||
|
||||
### CA-003: Generacion automatica de OT
|
||||
**Dado** que una unidad alcanzo el umbral
|
||||
**Cuando** el job diario verifica
|
||||
**Entonces** se genera OT preventiva automaticamente
|
||||
|
||||
### CA-004: Notificacion anticipada
|
||||
**Dado** que necesito planear recursos
|
||||
**Cuando** una unidad esta cerca del umbral
|
||||
**Entonces** recibo notificacion con anticipacion configurable
|
||||
|
||||
### CA-005: Calendario de mantenimientos
|
||||
**Dado** que necesito vision de proximos servicios
|
||||
**Cuando** consulto el calendario
|
||||
**Entonces** veo todos los mantenimientos programados
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Plan de Mantenimiento
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| PLANES DE MANTENIMIENTO [+ Nuevo] |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Tipo unidad: [Tracto v] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| SERVICIOS PROGRAMADOS |
|
||||
| |
|
||||
| | Servicio | Trigger | Intervalo | Alerta | |
|
||||
| |-----------------|---------|-----------|---------| |
|
||||
| | Cambio aceite | km | 15,000 km | 1,000km | |
|
||||
| | Revision frenos | km | 30,000 km | 3,000km | |
|
||||
| | Service mayor | km | 100,000km | 5,000km | |
|
||||
| | Verificacion | fecha | 12 meses | 30 dias | |
|
||||
| | Inspeccion NOM | fecha | 6 meses | 15 dias | |
|
||||
| |
|
||||
| [+ Agregar servicio] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Configurar Servicio
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| CONFIGURAR SERVICIO PREVENTIVO X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Nombre: [Cambio de aceite motor ] |
|
||||
| Codigo: [SRV-ACEITE-001 ] |
|
||||
| |
|
||||
| Aplica a: |
|
||||
| [x] Tracto |
|
||||
| [ ] Remolque |
|
||||
| [ ] Caja seca |
|
||||
| [ ] Caja refrigerada |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| PROGRAMACION |
|
||||
| |
|
||||
| Tipo de trigger: |
|
||||
| (o) Por kilometraje |
|
||||
| ( ) Por horas motor |
|
||||
| ( ) Por fecha |
|
||||
| |
|
||||
| Intervalo: [15,000 ] km |
|
||||
| |
|
||||
| Alerta anticipada: [1,000 ] km antes |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RECURSOS ESTIMADOS |
|
||||
| |
|
||||
| Tiempo estimado: [2.5 ] horas |
|
||||
| Costo estimado: [$2,500.00] |
|
||||
| |
|
||||
| Refacciones necesarias: |
|
||||
| + Filtro aceite motor (1 pz) |
|
||||
| + Aceite motor 15W40 (38 L) |
|
||||
| + Filtro aire (1 pz) |
|
||||
| [+ Agregar refaccion] |
|
||||
| |
|
||||
| [Cancelar] [Guardar] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Calendario de Mantenimientos
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| CALENDARIO DE MANTENIMIENTOS - Enero 2026 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| [<] Semana anterior [Esta semana] [>] Siguiente |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| Lun 27 Mar 28 Mie 29 Jue 30 Vie 31 |
|
||||
| -------- -------- -------- -------- -------- |
|
||||
| T-1025 T-1032 T-1018 |
|
||||
| Aceite Frenos Service |
|
||||
| |
|
||||
| T-1030 T-1022 |
|
||||
| Verif. Llantas |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| PROXIMOS 7 DIAS |
|
||||
| |
|
||||
| | Fecha | Unidad | Servicio | km actuales | |
|
||||
| |--------|---------|----------------|-------------| |
|
||||
| | 27-ene | T-1025 | Cambio aceite | 14,850 km | |
|
||||
| | 27-ene | T-1030 | Verificacion | Vence 28-ene| |
|
||||
| | 28-ene | T-1032 | Rev. frenos | 29,200 km | |
|
||||
| | 29-ene | T-1022 | Rotacion llant | 9,800 km | |
|
||||
| | 31-ene | T-1018 | Service mayor | 99,100 km | |
|
||||
| |
|
||||
| [Generar OTs para la semana] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `maintenance.planes_mantenimiento`
|
||||
- Tabla: `maintenance.servicios_programados`
|
||||
- Job: `generate-preventive-ots.job.ts` (corre diario 6am)
|
||||
- Notificaciones por email/push
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] CRUD de planes de mantenimiento
|
||||
- [ ] Configuracion por tipo de unidad
|
||||
- [ ] Triggers por km, horas, fecha
|
||||
- [ ] Generacion automatica de OT
|
||||
- [ ] Notificaciones anticipadas
|
||||
- [ ] Calendario visual
|
||||
- [ ] Tests de generacion automatica
|
||||
@ -0,0 +1,201 @@
|
||||
# US-MAI013-002: Gestionar orden de trabajo correctivo
|
||||
|
||||
**ID:** US-MAI013-002
|
||||
**Modulo:** MAI-013 (Mantenimiento)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** jefe de mantenimiento
|
||||
**Quiero** gestionar ordenes de trabajo para fallas correctivas
|
||||
**Para** reparar unidades de forma controlada y trazable
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Crear ticket de falla
|
||||
**Dado** que una unidad tiene una falla
|
||||
**Cuando** se reporta
|
||||
**Entonces** se crea ticket con descripcion, fotos y prioridad
|
||||
|
||||
### CA-002: Diagnosticar y crear OT
|
||||
**Dado** que hay un ticket de falla
|
||||
**Cuando** el mecanico diagnostica
|
||||
**Entonces** se crea OT con trabajos, refacciones y tiempo estimado
|
||||
|
||||
### CA-003: Ejecutar OT
|
||||
**Dado** que hay una OT aprobada
|
||||
**Cuando** el mecanico trabaja
|
||||
**Entonces** registra avances, refacciones usadas y tiempo real
|
||||
|
||||
### CA-004: Cerrar OT con pruebas
|
||||
**Dado** que se completo el trabajo
|
||||
**Cuando** se cierra la OT
|
||||
**Entonces** se documentan pruebas realizadas y fotos
|
||||
|
||||
### CA-005: Liberar unidad
|
||||
**Dado** que la OT esta cerrada
|
||||
**Cuando** se aprueba
|
||||
**Entonces** la unidad cambia a DISPONIBLE
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Ticket de Falla
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REPORTAR FALLA X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Unidad: [T-1025 - Kenworth T680 v] |
|
||||
| |
|
||||
| Ubicacion actual: |
|
||||
| (o) En patio |
|
||||
| ( ) En ruta - especificar ubicacion |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DESCRIPCION DE LA FALLA |
|
||||
| |
|
||||
| Tipo: [Frenos v] |
|
||||
| o Motor |
|
||||
| o Frenos |
|
||||
| o Suspension |
|
||||
| o Electrico |
|
||||
| o Llantas |
|
||||
| o Transmision |
|
||||
| o Aire acondicionado |
|
||||
| o Carroceria |
|
||||
| o Otro |
|
||||
| |
|
||||
| Descripcion: |
|
||||
| [Ruido metalico al frenar. Se siente vibracion ]|
|
||||
| [en el pedal. Posibles balatas gastadas. ]|
|
||||
| |
|
||||
| Prioridad: |
|
||||
| ( ) CRITICA - Unidad parada / Seguridad |
|
||||
| (o) ALTA - Afecta operacion |
|
||||
| ( ) MEDIA - Funciona con limitaciones |
|
||||
| ( ) BAJA - Estetico / menor |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EVIDENCIAS |
|
||||
| |
|
||||
| [+ Agregar foto] [+ Agregar video] |
|
||||
| |
|
||||
| [IMG] falla_freno_1.jpg |
|
||||
| |
|
||||
| [Cancelar] [Reportar Falla] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Orden de Trabajo
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| ORDEN DE TRABAJO - OT-2026-0125 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Unidad: T-1025 | Kenworth T680 |
|
||||
| Tipo: CORRECTIVO |
|
||||
| Prioridad: ALTA |
|
||||
| Estado: EN_EJECUCION |
|
||||
| |
|
||||
| Origen: Ticket #TKT-0089 - Falla en frenos |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DIAGNOSTICO |
|
||||
| |
|
||||
| Mecanico: Pedro Martinez |
|
||||
| Fecha: 27-ene-2026 08:30 |
|
||||
| |
|
||||
| Hallazgos: |
|
||||
| - Balatas delanteras desgastadas al 95% |
|
||||
| - Disco delantero derecho con ranuras |
|
||||
| - Liquido de frenos bajo nivel |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TRABAJOS A REALIZAR |
|
||||
| |
|
||||
| [x] Cambio de balatas delanteras (2 pz) |
|
||||
| [x] Rectificado de disco delantero |
|
||||
| [x] Cambio de liquido de frenos |
|
||||
| [ ] Purga de sistema |
|
||||
| |
|
||||
| Tiempo estimado: 4 horas |
|
||||
| Tiempo real: 3.5 horas |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| REFACCIONES |
|
||||
| |
|
||||
| | Refaccion | Cant | Stock | Costo | |
|
||||
| |---------------------|------|-------|---------| |
|
||||
| | Balatas del. KW | 2 | [8] | $1,200 | |
|
||||
| | Liquido frenos DOT4 | 2L | [15] | $350 | |
|
||||
| |---------------------|------|-------|---------| |
|
||||
| | TOTAL REFACCIONES | $1,550 | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| COSTOS |
|
||||
| |
|
||||
| Mano de obra (3.5h × $150): $525.00 |
|
||||
| Refacciones: $1,550.00 |
|
||||
| Servicio externo (rectificado): $400.00 |
|
||||
| ───────────────────────────────────────────── |
|
||||
| TOTAL OT: $2,475.00 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Agregar trabajo] [Agregar refaccion] |
|
||||
| |
|
||||
| [Cancelar OT] [Cerrar y Liberar Unidad] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Flujo de Estados OT
|
||||
|
||||
```
|
||||
CREADA → DIAGNOSTICO → APROBADA → EN_EJECUCION →
|
||||
↓
|
||||
PENDIENTE_REFACCION ←─────────────────────
|
||||
↓
|
||||
COMPLETADA → PRUEBAS → CERRADA → LIBERADA
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `maintenance.tickets_falla`
|
||||
- Tabla: `maintenance.ordenes_trabajo`
|
||||
- Tabla: `maintenance.lineas_ot`
|
||||
- Relacion con `maintenance.refacciones`
|
||||
- Actualiza `fleet.unidades.estado`
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Crear ticket de falla con fotos
|
||||
- [ ] Diagnostico por mecanico
|
||||
- [ ] Crear OT con trabajos y refacciones
|
||||
- [ ] Registro de ejecucion y avances
|
||||
- [ ] Consumo de refacciones del stock
|
||||
- [ ] Cierre con pruebas y fotos
|
||||
- [ ] Liberacion automatica de unidad
|
||||
- [ ] Tests de flujo completo
|
||||
@ -0,0 +1,181 @@
|
||||
# US-MAI013-003: Controlar disponibilidad de flota
|
||||
|
||||
**ID:** US-MAI013-003
|
||||
**Modulo:** MAI-013 (Mantenimiento)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** jefe de flota
|
||||
**Quiero** ver la disponibilidad real de las unidades
|
||||
**Para** planear operaciones y detectar problemas de capacidad
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Dashboard de disponibilidad
|
||||
**Dado** que necesito vision de la flota
|
||||
**Cuando** accedo al modulo
|
||||
**Entonces** veo resumen de disponibilidad por estado
|
||||
|
||||
### CA-002: Bloqueo automatico
|
||||
**Dado** que una unidad tiene documentos vencidos
|
||||
**Cuando** vence la fecha
|
||||
**Entonces** se bloquea automaticamente
|
||||
|
||||
### CA-003: Historial de estados
|
||||
**Dado** que quiero analizar una unidad
|
||||
**Cuando** consulto su historial
|
||||
**Entonces** veo timeline de cambios de estado
|
||||
|
||||
### CA-004: Alertas de baja disponibilidad
|
||||
**Dado** que la disponibilidad baja del umbral
|
||||
**Cuando** se detecta
|
||||
**Entonces** se envia alerta a operaciones
|
||||
|
||||
### CA-005: Reporte de disponibilidad
|
||||
**Dado** que necesito metricas
|
||||
**Cuando** genero reporte
|
||||
**Entonces** veo % disponibilidad por periodo
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Dashboard de Disponibilidad
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| DISPONIBILIDAD DE FLOTA |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | 35 | | 28 | | 80% | |
|
||||
| | Total Flota | | Disponibles | | Disponibil. | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DISTRIBUCION POR ESTADO |
|
||||
| |
|
||||
| Disponible ████████████████████████████ 28 (80%) |
|
||||
| En viaje ██████████████ 4 (11%) |
|
||||
| En taller ███ 2 (6%) |
|
||||
| Bloqueada █ 1 (3%) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| UNIDADES NO DISPONIBLES |
|
||||
| |
|
||||
| | Unidad | Estado | Motivo | Desde | |
|
||||
| |---------|-----------|------------------|----------| |
|
||||
| | T-1025 | En taller | OT-0125 Frenos | 27-ene | |
|
||||
| | T-1030 | En taller | OT-0124 Motor | 25-ene | |
|
||||
| | T-1018 | Bloqueada | Poliza vencida | 26-ene | |
|
||||
| | T-1022 | En viaje | VJE-0130 | 26-ene | |
|
||||
| | T-1032 | En viaje | VJE-0128 | 25-ene | |
|
||||
| | R-0045 | En viaje | VJE-0130 | 26-ene | |
|
||||
| | R-0048 | En viaje | VJE-0128 | 25-ene | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ALERTAS ACTIVAS |
|
||||
| |
|
||||
| [!] T-1018: Poliza vencida desde 26-ene-2026 |
|
||||
| [!] T-1015: Verificacion vence en 5 dias |
|
||||
| [!] R-0052: Mantenimiento vencido (pendiente 800 km) |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Detalle de Unidad
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| UNIDAD T-1025 - Kenworth T680 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Estado actual: EN_TALLER |
|
||||
| Desde: 27-ene-2026 07:00 |
|
||||
| Motivo: OT-0125 - Reparacion de frenos |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DOCUMENTACION |
|
||||
| |
|
||||
| | Documento | Vigencia | Estado | |
|
||||
| |------------------|------------|-----------| |
|
||||
| | Tarjeta circ. | 15-mar-27 | [OK] | |
|
||||
| | Poliza seguro | 30-jun-26 | [OK] | |
|
||||
| | Verificacion | 28-feb-26 | [30 dias] | |
|
||||
| | Permiso SCT | 01-dic-26 | [OK] | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| MANTENIMIENTO |
|
||||
| |
|
||||
| | Servicio | Ultimo | Proximo | |
|
||||
| |------------------|------------|-----------| |
|
||||
| | Cambio aceite | 485,230 km | 500,230km | |
|
||||
| | Rev. frenos | En curso | - | |
|
||||
| | Service mayor | 400,000 km | 500,000km | |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| HISTORIAL DE ESTADOS (ultimos 30 dias) |
|
||||
| |
|
||||
| 27-ene 07:00 EN_TALLER OT-0125 creada |
|
||||
| 26-ene 18:00 DISPONIBLE VJE-0125 cerrado |
|
||||
| 20-ene 06:00 EN_VIAJE VJE-0125 asignado |
|
||||
| 19-ene 14:00 DISPONIBLE Liberado de taller |
|
||||
| 15-ene 08:00 EN_TALLER OT-0118 preventivo |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| METRICAS |
|
||||
| |
|
||||
| % Disponibilidad (30 dias): 78% |
|
||||
| Dias en taller: 7 |
|
||||
| Dias en viaje: 18 |
|
||||
| Dias disponible: 5 |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Bloqueo Automatico
|
||||
|
||||
| Documento/Condicion | Anticipacion | Accion |
|
||||
|---------------------|--------------|--------|
|
||||
| Poliza seguro | 0 dias | Bloqueo inmediato |
|
||||
| Verificacion | 0 dias | Bloqueo inmediato |
|
||||
| Permiso SCT | 0 dias | Bloqueo inmediato |
|
||||
| Mto. preventivo | +10% km | Alerta, bloqueo a +20% |
|
||||
| Falla critica | Inmediato | Bloqueo inmediato |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `fleet.unidades.estado`
|
||||
- Tabla: `maintenance.bloqueos_unidad`
|
||||
- Vista: `maintenance.historial_estados_unidad`
|
||||
- Job: `check-document-expiry.job.ts` (diario)
|
||||
- Dashboard con Chart.js
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Dashboard de disponibilidad
|
||||
- [ ] Detalle por unidad con estados
|
||||
- [ ] Bloqueo automatico por vencimientos
|
||||
- [ ] Historial de cambios de estado
|
||||
- [ ] Alertas por baja disponibilidad
|
||||
- [ ] Reporte de % disponibilidad
|
||||
- [ ] Tests de bloqueo automatico
|
||||
86
docs/02-definicion-modulos/MAI-014-carriers/README.md
Normal file
86
docs/02-definicion-modulos/MAI-014-carriers/README.md
Normal file
@ -0,0 +1,86 @@
|
||||
# MAI-014: Gestion de Carriers (Terceros)
|
||||
|
||||
**Modulo:** MAI-014
|
||||
**Nombre:** Gestion de Carriers (Terceros)
|
||||
**Prioridad:** P2
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Modulo para gestion de transportistas subcontratados (carriers). Permite escalar capacidad sin perder control documental, calidad de servicio ni visibilidad operativa.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Registrar y validar carriers con documentacion
|
||||
2. Asignar viajes a carriers (rate shopping)
|
||||
3. Controlar documentos y vigencias
|
||||
4. Recibir POD y tracking de terceros
|
||||
5. Medir desempeno con scorecard
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Carrier Manager | Gestiona relacion con carriers |
|
||||
| Planeacion | Solicita cotizaciones |
|
||||
| Operaciones | Monitorea ejecucion |
|
||||
| Carrier (externo) | Ejecuta y reporta |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Depende de | Para |
|
||||
|------------|------|
|
||||
| MAI-004 (Planeacion) | Asignacion de viajes |
|
||||
| MAI-007 (POD) | Recepcion de evidencias |
|
||||
| MAI-009 (Facturacion) | Margen por subcontratacion |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
Viaje sin capacidad propia → Solicitar cotizaciones →
|
||||
Seleccionar carrier → Emitir OV al tercero →
|
||||
Carrier ejecuta → Recibir tracking/POD →
|
||||
Liquidar con carrier → Calcular margen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentos Requeridos del Carrier
|
||||
|
||||
| Documento | Obligatorio | Vigencia |
|
||||
|-----------|-------------|----------|
|
||||
| RFC / Constancia fiscal | Si | - |
|
||||
| Permiso SCT | Si | Verificar |
|
||||
| Poliza de seguro | Si | Verificar |
|
||||
| Carta responsiva | Si | Por viaje |
|
||||
| INE del operador | Si | Por viaje |
|
||||
| Licencia federal | Si | Verificar |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAI-014-carriers/
|
||||
├── README.md <- Este archivo
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAI014-001.md <- Registrar y validar carrier
|
||||
├── US-MAI014-002.md <- Asignar viaje a carrier
|
||||
└── US-MAI014-003.md <- Evaluar desempeno (scorecard)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAI-014 Gestion de Carriers - ERP Transportistas v1.0.0*
|
||||
215
docs/02-definicion-modulos/MAI-014-carriers/REQUERIMIENTOS.md
Normal file
215
docs/02-definicion-modulos/MAI-014-carriers/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,215 @@
|
||||
# REQUERIMIENTOS - MAI-014: Gestion de Carriers
|
||||
|
||||
**Modulo:** MAI-014
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.12
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.12.1: Registro de Carrier
|
||||
|
||||
**Descripcion:** Registrar carriers con datos fiscales, documentos y evaluacion inicial.
|
||||
|
||||
**Datos del carrier:**
|
||||
| Grupo | Campos |
|
||||
|-------|--------|
|
||||
| Fiscales | RFC, razon social, regimen, domicilio |
|
||||
| Contacto | Nombre, telefono, email, contacto operativo |
|
||||
| Bancarios | Banco, CLABE, beneficiario |
|
||||
| Operativos | Tipos de equipo, cobertura geografica |
|
||||
| Comerciales | Tarifas base, condiciones de pago |
|
||||
|
||||
**Documentos obligatorios:**
|
||||
- Constancia de situacion fiscal
|
||||
- Permiso SCT (autotransporte federal)
|
||||
- Poliza de seguro (responsabilidad civil)
|
||||
- Opinion de cumplimiento SAT (32-D)
|
||||
|
||||
**Evaluacion inicial:**
|
||||
- Verificar antecedentes
|
||||
- Validar referencias comerciales
|
||||
- Visita a instalaciones (opcional)
|
||||
|
||||
**Tablas DDL:**
|
||||
- `carriers.carriers`
|
||||
- `carriers.documentos_carrier`
|
||||
- `carriers.contactos_carrier`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.12.2: Asignacion a Carrier
|
||||
|
||||
**Descripcion:** Asignar viajes a carriers mediante licitacion interna.
|
||||
|
||||
**Proceso de asignacion:**
|
||||
```
|
||||
Viaje sin recurso propio → Solicitar cotizaciones (RFQ) →
|
||||
Recibir propuestas → Comparar vs margen requerido →
|
||||
Adjudicar → Emitir OV al carrier
|
||||
```
|
||||
|
||||
**Rate shopping:**
|
||||
- Enviar solicitud a N carriers
|
||||
- Tiempo limite de respuesta
|
||||
- Comparativo automatico
|
||||
- Margen minimo configurable
|
||||
|
||||
**Orden de Viaje a tercero:**
|
||||
- Datos del viaje (origen, destino, carga)
|
||||
- Instrucciones operativas
|
||||
- Datos de contacto cliente
|
||||
- Documentos requeridos
|
||||
|
||||
**Tablas DDL:**
|
||||
- `carriers.solicitudes_cotizacion`
|
||||
- `carriers.cotizaciones_carrier`
|
||||
- `carriers.ordenes_viaje_carrier`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.12.3: Control de Documentos del Tercero
|
||||
|
||||
**Descripcion:** Verificar vigencia de documentos antes de cada asignacion.
|
||||
|
||||
**Documentos por carrier:**
|
||||
| Documento | Frecuencia | Bloquea si vence |
|
||||
|-----------|------------|------------------|
|
||||
| Permiso SCT | Anual | Si |
|
||||
| Poliza seguro | Anual | Si |
|
||||
| Opinion 32-D | Mensual | Alerta |
|
||||
|
||||
**Documentos por viaje:**
|
||||
| Documento | Momento | Obligatorio |
|
||||
|-----------|---------|-------------|
|
||||
| Carta responsiva | Pre-carga | Si |
|
||||
| INE operador | Pre-carga | Si |
|
||||
| Licencia federal | Pre-carga | Si |
|
||||
| Tarjeta circulacion | Pre-carga | Si |
|
||||
|
||||
**Validaciones:**
|
||||
- Bloquear asignacion si documento vencido
|
||||
- Alerta 30 dias antes de vencimiento
|
||||
- Historial de documentos
|
||||
|
||||
**Tablas DDL:**
|
||||
- `carriers.documentos_carrier`
|
||||
- `carriers.documentos_viaje_carrier`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.12.4: Recepcion de POD del Tercero
|
||||
|
||||
**Descripcion:** Recibir evidencia de entrega del carrier.
|
||||
|
||||
**Canales de recepcion:**
|
||||
1. **Portal de carriers** - Upload directo
|
||||
2. **WhatsApp** - Fotos por mensaje
|
||||
3. **Email** - Adjuntos
|
||||
4. **App movil** (si carrier usa nuestra app)
|
||||
|
||||
**Validaciones del POD:**
|
||||
- Fotos legibles
|
||||
- Firma/sello presente
|
||||
- Datos del receptor
|
||||
- Fecha y hora
|
||||
|
||||
**Integracion:**
|
||||
- POD del carrier se integra a expediente del viaje
|
||||
- Mismo flujo de validacion que POD propio
|
||||
|
||||
**Tablas DDL:**
|
||||
- `carriers.pod_carrier`
|
||||
- Relacion con `tracking.evidencias_entrega`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.12.5: Costo vs Ingreso
|
||||
|
||||
**Descripcion:** Calcular margen por viaje subcontratado.
|
||||
|
||||
**Calculo:**
|
||||
```
|
||||
Ingreso = Tarifa cobrada al cliente
|
||||
Costo = Tarifa pagada al carrier
|
||||
Margen = Ingreso - Costo
|
||||
% Margen = Margen / Ingreso × 100
|
||||
```
|
||||
|
||||
**Reportes:**
|
||||
- Margen por viaje
|
||||
- Margen por carrier
|
||||
- Margen por ruta/lane
|
||||
- Margen por cliente
|
||||
|
||||
**Alertas:**
|
||||
- Margen < minimo configurado
|
||||
- Carrier mas caro que promedio
|
||||
- Tendencia de margen a la baja
|
||||
|
||||
**Tablas DDL:**
|
||||
- `carriers.liquidaciones_carrier`
|
||||
- Vista: `carriers.margen_por_viaje`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.12.6: Scorecard de Carriers
|
||||
|
||||
**Descripcion:** Evaluar desempeno de carriers con metricas objetivas.
|
||||
|
||||
**Metricas del scorecard:**
|
||||
| Metrica | Peso | Calculo |
|
||||
|---------|------|---------|
|
||||
| Puntualidad | 30% | % entregas a tiempo |
|
||||
| Incidencias | 25% | Incidencias / 100 viajes |
|
||||
| Calidad POD | 15% | % POD completos a tiempo |
|
||||
| Documentos | 15% | % documentos al dia |
|
||||
| Precio | 15% | Tarifa vs promedio mercado |
|
||||
|
||||
**Puntaje general:**
|
||||
| Rango | Categoria | Accion |
|
||||
|-------|-----------|--------|
|
||||
| 90-100 | A (Excelente) | Prioridad en asignacion |
|
||||
| 80-89 | B (Bueno) | Normal |
|
||||
| 70-79 | C (Regular) | Monitoreo |
|
||||
| <70 | D (Deficiente) | Revision/suspension |
|
||||
|
||||
**Tablas DDL:**
|
||||
- `carriers.evaluaciones_carrier`
|
||||
- `carriers.metricas_periodo`
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Portal de Carriers
|
||||
- Acceso web para carriers
|
||||
- Ver asignaciones y cargar documentos
|
||||
- Subir POD
|
||||
|
||||
### RNF-002: Notificaciones
|
||||
- Email/WhatsApp para RFQ
|
||||
- Alertas de documentos por vencer
|
||||
- Confirmacion de asignacion
|
||||
|
||||
### RNF-003: Seguridad
|
||||
- Carriers solo ven sus viajes
|
||||
- Documentos con acceso restringido
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tablas DDL | Endpoints | Historias |
|
||||
|----|------------|-----------|-----------|
|
||||
| RF-4.12.1 | carriers, documentos | POST /carriers | US-MAI014-001 |
|
||||
| RF-4.12.2 | solicitudes, ordenes | POST /asignacion | US-MAI014-002 |
|
||||
| RF-4.12.3 | documentos_carrier | GET /documentos | US-MAI014-001 |
|
||||
| RF-4.12.4 | pod_carrier | POST /pod | US-MAI014-002 |
|
||||
| RF-4.12.5 | liquidaciones | GET /margen | US-MAI014-003 |
|
||||
| RF-4.12.6 | evaluaciones | GET /scorecard | US-MAI014-003 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAI-014 - ERP Transportistas v1.0.0*
|
||||
79
docs/02-definicion-modulos/MAI-014-carriers/RESUMEN-EPICA.md
Normal file
79
docs/02-definicion-modulos/MAI-014-carriers/RESUMEN-EPICA.md
Normal file
@ -0,0 +1,79 @@
|
||||
# RESUMEN EPICA - MAI-014: Gestion de Carriers
|
||||
|
||||
**Modulo:** MAI-014
|
||||
**Prioridad:** P2
|
||||
**Story Points Total:** 18
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- No hay visibilidad de viajes subcontratados
|
||||
- Documentos de terceros no verificados
|
||||
- Margen por subcontratacion desconocido
|
||||
- Calidad de carriers no medida
|
||||
|
||||
### Beneficios
|
||||
- **Escalabilidad** sin perder control
|
||||
- **Compliance documental** de terceros
|
||||
- **Margen controlado** por viaje
|
||||
- **Calidad medida** con scorecard
|
||||
|
||||
### KPIs Impactados
|
||||
- % viajes subcontratados
|
||||
- Margen promedio subcontratacion
|
||||
- Scorecard promedio de carriers
|
||||
- Cumplimiento documental carriers
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Registro de carriers
|
||||
- Control de documentos
|
||||
- Asignacion (rate shopping)
|
||||
- Recepcion de POD
|
||||
- Calculo de margen
|
||||
- Scorecard
|
||||
|
||||
### Excluido
|
||||
- Portal completo para carriers (basico)
|
||||
- Integracion EDI con carriers
|
||||
- Facturacion electronica a carriers
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAI014-001 | Registrar y validar carrier | 5 |
|
||||
| US-MAI014-002 | Asignar viaje a carrier | 8 |
|
||||
| US-MAI014-003 | Evaluar desempeno (scorecard) | 5 |
|
||||
| **Total** | | **18** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
MAI-004 (Planeacion) ──┐
|
||||
MAI-007 (POD) ─────────┼──> MAI-014 ──> MAI-009 (Facturacion)
|
||||
│ ──> MAE-018 (Reportes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Carriers no usan portal | WhatsApp/email como alternativa |
|
||||
| Documentos falsos | Validacion cruzada SAT |
|
||||
| Margen negativo | Alerta y aprobacion manual |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAI-014 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,145 @@
|
||||
# US-MAI014-001: Registrar y validar carrier
|
||||
|
||||
**ID:** US-MAI014-001
|
||||
**Modulo:** MAI-014 (Carriers)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** carrier manager
|
||||
**Quiero** registrar carriers con su documentacion
|
||||
**Para** tener un pool de terceros validados para subcontratar
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Registrar datos del carrier
|
||||
**Dado** que tengo un nuevo carrier potencial
|
||||
**Cuando** lo registro
|
||||
**Entonces** capturo datos fiscales, contacto, bancarios y operativos
|
||||
|
||||
### CA-002: Cargar documentos obligatorios
|
||||
**Dado** que el carrier debe tener documentos vigentes
|
||||
**Cuando** completo el registro
|
||||
**Entonces** cargo permiso SCT, poliza y constancia fiscal
|
||||
|
||||
### CA-003: Validar vigencias
|
||||
**Dado** que los documentos tienen fecha de vencimiento
|
||||
**Cuando** el sistema verifica
|
||||
**Entonces** alerta si estan proximos a vencer o vencidos
|
||||
|
||||
### CA-004: Aprobar o rechazar carrier
|
||||
**Dado** que revise la documentacion
|
||||
**Cuando** decido
|
||||
**Entonces** puedo aprobar (activo) o rechazar con motivo
|
||||
|
||||
### CA-005: Bloquear si documento vence
|
||||
**Dado** que un documento expiro
|
||||
**Cuando** el job verifica
|
||||
**Entonces** el carrier pasa a estado BLOQUEADO
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| REGISTRAR CARRIER X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| DATOS FISCALES |
|
||||
| |
|
||||
| RFC: [TRA990101AB1 ] |
|
||||
| Razon social: [Transportes del Norte SA de CV ] |
|
||||
| Regimen fiscal: [General de ley personas morales v] |
|
||||
| |
|
||||
| Domicilio fiscal: |
|
||||
| [Av. Industrial 500, Parque Ind. Monterrey ] |
|
||||
| CP: [64000 ] Ciudad: [Monterrey, NL ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CONTACTO |
|
||||
| |
|
||||
| Contacto comercial: [Roberto Garza Martinez ] |
|
||||
| Telefono: [81 1234 5678 ] Email: [rgarza@... ] |
|
||||
| |
|
||||
| Contacto operativo: [Mario Lopez ] |
|
||||
| Telefono: [81 8765 4321 ] Email: [mlopez@... ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DATOS BANCARIOS |
|
||||
| |
|
||||
| Banco: [BBVA v] |
|
||||
| CLABE: [012580001234567890] |
|
||||
| Beneficiario: [Transportes del Norte SA de CV ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CAPACIDADES OPERATIVAS |
|
||||
| |
|
||||
| Tipos de equipo: |
|
||||
| [x] Caja seca 53' |
|
||||
| [x] Caja refrigerada |
|
||||
| [ ] Plataforma |
|
||||
| [ ] Tanque |
|
||||
| |
|
||||
| Cobertura: [Nacional v] |
|
||||
| Unidades disponibles: [15 ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DOCUMENTOS |
|
||||
| |
|
||||
| | Documento | Archivo | Vigencia | Est ||
|
||||
| |--------------------|------------|------------|-----||
|
||||
| | Constancia fiscal | [Cargar] | - | - ||
|
||||
| | Permiso SCT* | [Cargar] | [________] | - ||
|
||||
| | Poliza seguro* | [Cargar] | [________] | - ||
|
||||
| | Opinion 32-D | [Cargar] | [________] | - ||
|
||||
| |
|
||||
| * Documento obligatorio |
|
||||
| |
|
||||
| [Cancelar] [Guardar Carrier] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados del Carrier
|
||||
|
||||
| Estado | Puede asignarse | Descripcion |
|
||||
|--------|-----------------|-------------|
|
||||
| PENDIENTE | No | En revision |
|
||||
| ACTIVO | Si | Documentos OK |
|
||||
| BLOQUEADO | No | Documento vencido |
|
||||
| SUSPENDIDO | No | Por desempeno |
|
||||
| INACTIVO | No | Baja voluntaria |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `carriers.carriers`
|
||||
- Tabla: `carriers.documentos_carrier`
|
||||
- Tabla: `carriers.contactos_carrier`
|
||||
- Job: `check-carrier-documents.job.ts` (diario)
|
||||
- Validar RFC con SAT (opcional)
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Formulario de registro completo
|
||||
- [ ] Carga de documentos obligatorios
|
||||
- [ ] Validacion de vigencias
|
||||
- [ ] Estados del carrier
|
||||
- [ ] Bloqueo automatico por vencimiento
|
||||
- [ ] Alertas de documentos por vencer
|
||||
- [ ] Tests de registro y validacion
|
||||
@ -0,0 +1,204 @@
|
||||
# US-MAI014-002: Asignar viaje a carrier
|
||||
|
||||
**ID:** US-MAI014-002
|
||||
**Modulo:** MAI-014 (Carriers)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** planeador de trafico
|
||||
**Quiero** asignar viajes a carriers mediante cotizacion
|
||||
**Para** cubrir demanda cuando no hay capacidad propia
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Solicitar cotizaciones (RFQ)
|
||||
**Dado** que un viaje no tiene recurso propio
|
||||
**Cuando** envio solicitud de cotizacion
|
||||
**Entonces** se notifica a carriers seleccionados
|
||||
|
||||
### CA-002: Recibir propuestas
|
||||
**Dado** que carriers reciben el RFQ
|
||||
**Cuando** responden
|
||||
**Entonces** veo comparativo de propuestas
|
||||
|
||||
### CA-003: Validar margen
|
||||
**Dado** que hay un margen minimo requerido
|
||||
**Cuando** comparo propuestas
|
||||
**Entonces** el sistema indica si cumple el margen
|
||||
|
||||
### CA-004: Adjudicar a carrier
|
||||
**Dado** que selecciono una propuesta
|
||||
**Cuando** adjudico
|
||||
**Entonces** se genera OV al carrier
|
||||
|
||||
### CA-005: Recibir POD del carrier
|
||||
**Dado** que el carrier completo el viaje
|
||||
**Cuando** sube el POD
|
||||
**Entonces** se integra al expediente del viaje
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Solicitar Cotizacion (RFQ)
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| SOLICITAR COTIZACION A CARRIERS X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| VIAJE |
|
||||
| |
|
||||
| Viaje: VJE-0135 |
|
||||
| Ruta: CDMX -> Guadalajara |
|
||||
| Fecha carga: 28-ene-2026 08:00 |
|
||||
| Fecha entrega: 29-ene-2026 14:00 |
|
||||
| Tipo equipo: Caja seca 53' |
|
||||
| Peso: 18,500 kg |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CARRIERS A COTIZAR |
|
||||
| |
|
||||
| [x] Transportes del Norte Score: 92 [A] |
|
||||
| [x] Logistica Express Score: 85 [B] |
|
||||
| [x] Fletes Rapidos Score: 78 [C] |
|
||||
| [ ] Carga Segura (Bloqueado - doc vencido) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CONFIGURACION |
|
||||
| |
|
||||
| Tiempo limite respuesta: [4 ] horas |
|
||||
| Tarifa maxima aceptable: [$15,000.00] |
|
||||
| Margen minimo requerido: [15 ] % |
|
||||
| |
|
||||
| Tarifa al cliente: $18,000.00 |
|
||||
| Costo maximo carrier: $15,300.00 (para 15% margen) |
|
||||
| |
|
||||
| [Cancelar] [Enviar Solicitud] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Comparativo de Propuestas
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| PROPUESTAS - VJE-0135 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Tarifa cliente: $18,000.00 |
|
||||
| Margen minimo: 15% ($2,700) |
|
||||
| Vence en: 2h 15m |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| | Carrier | Tarifa | Margen | Score | |
|
||||
| |-------------------|-----------|--------|-------| |
|
||||
| | Trans. del Norte | $14,500 | 19.4% | 92 [A]| * |
|
||||
| | Logistica Express | $15,200 | 15.5% | 85 [B]| |
|
||||
| | Fletes Rapidos | $16,000 | 11.1% | 78 [C]| ! |
|
||||
| |
|
||||
| * Recomendado (mejor margen + score) |
|
||||
| ! Por debajo del margen minimo |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DETALLE PROPUESTA SELECCIONADA |
|
||||
| |
|
||||
| Carrier: Transportes del Norte |
|
||||
| Tarifa propuesta: $14,500.00 |
|
||||
| Tiempo transito: 10 horas |
|
||||
| Unidad ofrecida: Kenworth T680 + Caja 53' |
|
||||
| Operador: Juan Martinez Perez |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| MARGEN CALCULADO |
|
||||
| |
|
||||
| Ingreso (cliente): $18,000.00 |
|
||||
| (-) Costo (carrier): $14,500.00 |
|
||||
| ───────────────────────────────── |
|
||||
| Margen bruto: $3,500.00 (19.4%) |
|
||||
| |
|
||||
| [Rechazar todas] [Adjudicar a Carrier] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Orden de Viaje a Carrier
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| ORDEN DE VIAJE - OVC-2026-0089 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Para: Transportes del Norte SA de CV |
|
||||
| Contacto: Mario Lopez | 81 8765 4321 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DATOS DEL SERVICIO |
|
||||
| |
|
||||
| Referencia interna: VJE-0135 |
|
||||
| Cliente final: Liverpool SA de CV |
|
||||
| |
|
||||
| ORIGEN |
|
||||
| CEDIS CDMX |
|
||||
| Av. Tlahuac 500, Iztapalapa, CDMX |
|
||||
| Cita carga: 28-ene-2026 08:00 - 10:00 |
|
||||
| Contacto: Pedro Sanchez | 55 1234 5678 |
|
||||
| |
|
||||
| DESTINO |
|
||||
| CEDIS Guadalajara |
|
||||
| Av. Lazaro Cardenas 2000, Zapopan, JAL |
|
||||
| Cita entrega: 29-ene-2026 12:00 - 14:00 |
|
||||
| Contacto: Ana Martinez | 33 9876 5432 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| INSTRUCCIONES |
|
||||
| |
|
||||
| - Presentar OV impresa en origen |
|
||||
| - Verificar sellos antes de salir |
|
||||
| - Reportar eventos por WhatsApp |
|
||||
| - Subir POD al portal dentro de 24h |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TARIFA ACORDADA: $14,500.00 MXN |
|
||||
| Pago: 15 dias despues de POD |
|
||||
| |
|
||||
| [Descargar PDF] [Enviar por Email] [WhatsApp] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `carriers.solicitudes_cotizacion`
|
||||
- Tabla: `carriers.cotizaciones_carrier`
|
||||
- Tabla: `carriers.ordenes_viaje_carrier`
|
||||
- Notificaciones por email/WhatsApp
|
||||
- Portal para carriers (upload POD)
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Envio de RFQ a multiples carriers
|
||||
- [ ] Recepcion y comparativo de propuestas
|
||||
- [ ] Validacion de margen minimo
|
||||
- [ ] Adjudicacion y generacion de OV
|
||||
- [ ] Notificaciones a carrier
|
||||
- [ ] Recepcion de POD del carrier
|
||||
- [ ] Tests de flujo completo
|
||||
@ -0,0 +1,191 @@
|
||||
# US-MAI014-003: Evaluar desempeno (scorecard)
|
||||
|
||||
**ID:** US-MAI014-003
|
||||
**Modulo:** MAI-014 (Carriers)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** carrier manager
|
||||
**Quiero** evaluar el desempeno de los carriers con metricas objetivas
|
||||
**Para** tomar decisiones de asignacion basadas en datos
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Calcular metricas automaticas
|
||||
**Dado** que los carriers completan viajes
|
||||
**Cuando** se cierra el periodo
|
||||
**Entonces** se calculan metricas de puntualidad, incidencias, POD
|
||||
|
||||
### CA-002: Generar puntaje global
|
||||
**Dado** que hay metricas con pesos definidos
|
||||
**Cuando** se calcula el scorecard
|
||||
**Entonces** se obtiene puntaje de 0-100
|
||||
|
||||
### CA-003: Categorizar carriers
|
||||
**Dado** que hay rangos de puntaje
|
||||
**Cuando** se evalua
|
||||
**Entonces** se asigna categoria (A, B, C, D)
|
||||
|
||||
### CA-004: Comparar carriers
|
||||
**Dado** que tengo multiples carriers
|
||||
**Cuando** consulto el ranking
|
||||
**Entonces** veo comparativo ordenado por score
|
||||
|
||||
### CA-005: Tomar acciones por desempeno
|
||||
**Dado** que un carrier tiene mal desempeno
|
||||
**Cuando** cae a categoria D
|
||||
**Entonces** se notifica para revision o suspension
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Scorecard de Carrier
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| SCORECARD - Transportes del Norte |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Periodo: Enero 2026 |
|
||||
| Categoria: [A] EXCELENTE |
|
||||
| Puntaje global: 92 / 100 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DESGLOSE DE METRICAS |
|
||||
| |
|
||||
| Puntualidad (30%) ████████████████████ 95% |
|
||||
| Incidencias (25%) ██████████████████ 90% |
|
||||
| Calidad POD (15%) ███████████████████ 92% |
|
||||
| Documentos (15%) █████████████████████ 98% |
|
||||
| Precio (15%) ████████████████ 85% |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DETALLE POR METRICA |
|
||||
| |
|
||||
| PUNTUALIDAD (95%) |
|
||||
| Viajes a tiempo: 38 de 40 |
|
||||
| Retrasos: 2 (promedio 45 min) |
|
||||
| |
|
||||
| INCIDENCIAS (90%) |
|
||||
| Viajes sin incidencia: 36 de 40 |
|
||||
| Incidencias reportadas: 4 (2 menores, 2 medias) |
|
||||
| |
|
||||
| CALIDAD POD (92%) |
|
||||
| POD completos a tiempo: 37 de 40 |
|
||||
| POD tardios: 3 (promedio 8 horas despues) |
|
||||
| |
|
||||
| DOCUMENTOS (98%) |
|
||||
| Dias con documentos vigentes: 29 de 30 |
|
||||
| Alertas de vencimiento: 1 |
|
||||
| |
|
||||
| PRECIO (85%) |
|
||||
| Tarifa promedio: $14,200 |
|
||||
| vs Promedio mercado: +5% |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EVOLUCION ULTIMOS 6 MESES |
|
||||
| |
|
||||
| 100| * |
|
||||
| 90| * * * * |
|
||||
| 80| * |
|
||||
| 70| |
|
||||
| +-----+-----+-----+-----+-----+-----+ |
|
||||
| Ago Sep Oct Nov Dic Ene |
|
||||
| |
|
||||
| Tendencia: ESTABLE |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Ranking de Carriers
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| RANKING DE CARRIERS - Enero 2026 |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| [Filtrar por categoria: Todos v] [Exportar] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| | # | Carrier | Score | Cat | Viajes |Tend|
|
||||
| |---|---------------------|-------|-----|--------|----||
|
||||
| | 1 | Trans. del Norte | 92 | [A] | 40 | = ||
|
||||
| | 2 | Carga Segura | 89 | [B] | 28 | ^ ||
|
||||
| | 3 | Logistica Express | 85 | [B] | 35 | = ||
|
||||
| | 4 | Fletes Premium | 82 | [B] | 22 | v ||
|
||||
| | 5 | Envios Rapidos | 78 | [C] | 18 | v ||
|
||||
| | 6 | Trans. Economicos | 72 | [C] | 45 | = ||
|
||||
| | 7 | Fletes del Bajio | 68 | [D] | 12 | v ||
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ALERTAS |
|
||||
| |
|
||||
| [!] Fletes del Bajio: Categoria D por 2 meses |
|
||||
| consecutivos. Revisar para suspension. |
|
||||
| |
|
||||
| [!] Fletes Premium: Tendencia a la baja. Monitorear. |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RESUMEN |
|
||||
| |
|
||||
| Total carriers activos: 7 |
|
||||
| Score promedio: 81 |
|
||||
| Categoria A: 1 (14%) |
|
||||
| Categoria B: 3 (43%) |
|
||||
| Categoria C: 2 (29%) |
|
||||
| Categoria D: 1 (14%) |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Calculo del Scorecard
|
||||
|
||||
| Metrica | Peso | Formula |
|
||||
|---------|------|---------|
|
||||
| Puntualidad | 30% | (Entregas a tiempo / Total) × 100 |
|
||||
| Incidencias | 25% | 100 - (Incidencias × 2.5) |
|
||||
| Calidad POD | 15% | (POD completos < 24h / Total) × 100 |
|
||||
| Documentos | 15% | (Dias docs vigentes / Dias periodo) × 100 |
|
||||
| Precio | 15% | 100 - (% diferencia vs mercado × 2) |
|
||||
|
||||
**Puntaje global:**
|
||||
```
|
||||
Score = (Puntualidad × 0.30) + (Incidencias × 0.25) +
|
||||
(POD × 0.15) + (Documentos × 0.15) + (Precio × 0.15)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `carriers.evaluaciones_carrier`
|
||||
- Tabla: `carriers.metricas_periodo`
|
||||
- Job: `calculate-carrier-scorecard.job.ts` (mensual)
|
||||
- Dashboard con Chart.js
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Calculo automatico de metricas
|
||||
- [ ] Generacion de puntaje global
|
||||
- [ ] Categorizacion A/B/C/D
|
||||
- [ ] Ranking comparativo
|
||||
- [ ] Grafico de evolucion
|
||||
- [ ] Alertas por mal desempeno
|
||||
- [ ] Tests de calculo de scorecard
|
||||
74
docs/02-definicion-modulos/MAI-015-portal-cliente/README.md
Normal file
74
docs/02-definicion-modulos/MAI-015-portal-cliente/README.md
Normal file
@ -0,0 +1,74 @@
|
||||
# MAI-015: Portal de Cliente
|
||||
|
||||
**Modulo:** MAI-015
|
||||
**Nombre:** Portal de Cliente
|
||||
**Prioridad:** P3
|
||||
**Estado:** Especificado
|
||||
|
||||
---
|
||||
|
||||
## Descripcion General
|
||||
|
||||
Portal web de autoservicio para clientes (shippers). Permite tracking de envios, descarga de documentos, creacion de OTs y gestion de reclamaciones, reduciendo friccion operativa.
|
||||
|
||||
---
|
||||
|
||||
## Objetivos
|
||||
|
||||
1. Proporcionar tracking en tiempo real
|
||||
2. Acceso a documentos (POD, facturas, Carta Porte)
|
||||
3. Creacion de OTs desde portal
|
||||
4. Gestion de reclamaciones
|
||||
5. Reducir llamadas al call center
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el Modulo |
|
||||
|-------|------------------|
|
||||
| Usuario cliente | Consulta y crea OTs |
|
||||
| Admin cliente | Gestiona usuarios del cliente |
|
||||
| Customer Success | Configura accesos |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
| Depende de | Para |
|
||||
|------------|------|
|
||||
| MAI-006 (Tracking) | Datos de posicion y eventos |
|
||||
| MAI-007 (POD) | Documentos de entrega |
|
||||
| MAI-003 (OT) | Creacion de ordenes |
|
||||
| MAI-008 (Incidencias) | Reclamaciones |
|
||||
|
||||
---
|
||||
|
||||
## Funcionalidades Principales
|
||||
|
||||
| Funcionalidad | Descripcion |
|
||||
|---------------|-------------|
|
||||
| Tracking | Mapa, estado, ETA |
|
||||
| Documentos | POD, factura, Carta Porte |
|
||||
| Crear OT | Plantillas, recurrentes |
|
||||
| Reclamaciones | Abrir, seguimiento |
|
||||
| Reportes | Mis envios, KPIs |
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Archivos
|
||||
|
||||
```
|
||||
MAI-015-portal-cliente/
|
||||
├── README.md <- Este archivo
|
||||
├── REQUERIMIENTOS.md <- RF detallados
|
||||
├── RESUMEN-EPICA.md <- Vision de negocio
|
||||
└── historias-usuario/
|
||||
├── US-MAI015-001.md <- Consultar tracking
|
||||
├── US-MAI015-002.md <- Crear OT desde portal
|
||||
└── US-MAI015-003.md <- Gestionar reclamaciones
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*MAI-015 Portal de Cliente - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,194 @@
|
||||
# REQUERIMIENTOS - MAI-015: Portal de Cliente
|
||||
|
||||
**Modulo:** MAI-015
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.13
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.13.1: Tracking
|
||||
|
||||
**Descripcion:** Proporcionar visibilidad de envios al cliente.
|
||||
|
||||
**Funcionalidades:**
|
||||
| Funcion | Descripcion |
|
||||
|---------|-------------|
|
||||
| Mapa | Posicion actual en mapa |
|
||||
| Estado | Estado del viaje (etapa) |
|
||||
| Eventos | Timeline de eventos |
|
||||
| ETA | Hora estimada de llegada |
|
||||
| Historial | Viajes anteriores |
|
||||
|
||||
**Vista de mapa:**
|
||||
- Posicion actual del vehiculo
|
||||
- Ruta planeada
|
||||
- Origen y destino marcados
|
||||
- Actualizacion cada 5 minutos
|
||||
|
||||
**Filtros:**
|
||||
- Por fecha
|
||||
- Por estado (activos, entregados, todos)
|
||||
- Por referencia (PO, OT)
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.eventos_tracking`
|
||||
- `transport.viajes`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.13.2: Documentos
|
||||
|
||||
**Descripcion:** Acceso a documentos relacionados con envios.
|
||||
|
||||
**Documentos disponibles:**
|
||||
| Documento | Momento | Formato |
|
||||
|-----------|---------|---------|
|
||||
| POD | Post-entrega | PDF/Fotos |
|
||||
| Factura | Post-facturacion | PDF/XML |
|
||||
| Carta Porte | Con factura | PDF/XML |
|
||||
| Orden de viaje | Pre-carga | PDF |
|
||||
|
||||
**Funcionalidades:**
|
||||
- Vista previa
|
||||
- Descarga individual
|
||||
- Descarga masiva (ZIP)
|
||||
- Busqueda por referencia
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.evidencias_entrega`
|
||||
- `billing.facturas`
|
||||
- `compliance.cartas_porte`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.13.3: Creacion de OT
|
||||
|
||||
**Descripcion:** Permitir al cliente crear ordenes de transporte.
|
||||
|
||||
**Metodos de creacion:**
|
||||
1. **Formulario manual**
|
||||
- Origen/destino
|
||||
- Fechas/ventanas
|
||||
- Tipo de carga
|
||||
- Referencias
|
||||
|
||||
2. **Plantillas**
|
||||
- Rutas frecuentes guardadas
|
||||
- Un clic para crear
|
||||
|
||||
3. **Carga masiva**
|
||||
- Excel con multiples OTs
|
||||
- Validacion de datos
|
||||
|
||||
**Validaciones:**
|
||||
- Direcciones validas
|
||||
- Ventanas de tiempo logicas
|
||||
- Peso/volumen dentro de limites
|
||||
- Cliente con credito disponible
|
||||
|
||||
**Tablas DDL:**
|
||||
- `transport.ordenes_transporte`
|
||||
- `transport.plantillas_ot_cliente`
|
||||
|
||||
---
|
||||
|
||||
### RF-4.13.4: Reclamaciones
|
||||
|
||||
**Descripcion:** Apertura y seguimiento de incidencias.
|
||||
|
||||
**Flujo:**
|
||||
```
|
||||
Cliente abre reclamacion → Sube evidencias →
|
||||
Asignacion interna → Investigacion →
|
||||
Cliente ve avances → Resolucion → Cierre
|
||||
```
|
||||
|
||||
**Datos de apertura:**
|
||||
- Viaje relacionado
|
||||
- Tipo de reclamacion
|
||||
- Descripcion
|
||||
- Evidencias (fotos, docs)
|
||||
|
||||
**Seguimiento:**
|
||||
- Estado actual
|
||||
- Comentarios del equipo
|
||||
- Resolucion propuesta
|
||||
- Aceptar/rechazar
|
||||
|
||||
**Tablas DDL:**
|
||||
- `tracking.incidencias`
|
||||
- `tracking.bitacora_incidencia`
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Adicionales
|
||||
|
||||
### Gestion de Usuarios
|
||||
|
||||
**Roles del cliente:**
|
||||
| Rol | Permisos |
|
||||
|-----|----------|
|
||||
| Viewer | Solo consulta |
|
||||
| Creator | Consulta + crear OT |
|
||||
| Admin | Todo + gestionar usuarios |
|
||||
|
||||
**Funcionalidades:**
|
||||
- Invitar usuarios
|
||||
- Asignar roles
|
||||
- Desactivar usuarios
|
||||
|
||||
### Notificaciones
|
||||
|
||||
**Canales:**
|
||||
- Email (resumen diario, alertas)
|
||||
- Portal (en tiempo real)
|
||||
- WhatsApp (opcional)
|
||||
|
||||
**Eventos notificables:**
|
||||
- Carga completada
|
||||
- En transito
|
||||
- Entregado
|
||||
- Incidencia
|
||||
|
||||
### Reportes
|
||||
|
||||
**Reportes disponibles:**
|
||||
- Mis envios por periodo
|
||||
- KPIs (OTIF, tiempos)
|
||||
- Facturacion
|
||||
- Incidencias
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Seguridad
|
||||
- Login con email/password
|
||||
- MFA opcional
|
||||
- Sesion expira en 8 horas
|
||||
- Solo ve datos de su empresa
|
||||
|
||||
### RNF-002: Disponibilidad
|
||||
- 99.5% uptime
|
||||
- Responsive (movil/desktop)
|
||||
|
||||
### RNF-003: Performance
|
||||
- Carga inicial < 3 segundos
|
||||
- Tracking actualiza cada 5 min
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tablas DDL | Endpoints | Historias |
|
||||
|----|------------|-----------|-----------|
|
||||
| RF-4.13.1 | eventos_tracking | GET /tracking | US-MAI015-001 |
|
||||
| RF-4.13.2 | evidencias, facturas | GET /docs | US-MAI015-001 |
|
||||
| RF-4.13.3 | ordenes_transporte | POST /ot | US-MAI015-002 |
|
||||
| RF-4.13.4 | incidencias | POST /claims | US-MAI015-003 |
|
||||
|
||||
---
|
||||
|
||||
*REQUERIMIENTOS MAI-015 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,79 @@
|
||||
# RESUMEN EPICA - MAI-015: Portal de Cliente
|
||||
|
||||
**Modulo:** MAI-015
|
||||
**Prioridad:** P3
|
||||
**Story Points Total:** 18
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema que Resuelve
|
||||
- Clientes llaman constantemente para saber donde esta su carga
|
||||
- Solicitan documentos por email
|
||||
- No pueden crear OTs ellos mismos
|
||||
- Reclamaciones por telefono sin seguimiento
|
||||
|
||||
### Beneficios
|
||||
- **Autoservicio** reduce carga operativa
|
||||
- **Visibilidad 24/7** mejora satisfaccion
|
||||
- **Documentos accesibles** reduce solicitudes
|
||||
- **Diferenciador comercial** vs competencia
|
||||
|
||||
### KPIs Impactados
|
||||
- Llamadas al call center
|
||||
- Tiempo de respuesta a solicitudes
|
||||
- NPS de clientes
|
||||
- Tasa de retencion
|
||||
|
||||
---
|
||||
|
||||
## Alcance
|
||||
|
||||
### Incluido
|
||||
- Tracking en mapa
|
||||
- Descarga de documentos
|
||||
- Creacion de OT
|
||||
- Reclamaciones
|
||||
- Gestion de usuarios cliente
|
||||
|
||||
### Excluido
|
||||
- API para integracion (fase posterior)
|
||||
- App movil nativa
|
||||
- Chat en vivo
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
| ID | Historia | SP |
|
||||
|----|----------|---:|
|
||||
| US-MAI015-001 | Consultar tracking y documentos | 8 |
|
||||
| US-MAI015-002 | Crear OT desde portal | 5 |
|
||||
| US-MAI015-003 | Gestionar reclamaciones | 5 |
|
||||
| **Total** | | **18** |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
MAI-006 (Tracking) ──┐
|
||||
MAI-007 (POD) ──────┼──> MAI-015
|
||||
MAI-003 (OT) ───────┤
|
||||
MAI-008 (Incidencias)┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|--------|------------|
|
||||
| Baja adopcion | Capacitacion + incentivos |
|
||||
| Errores en OTs | Validaciones + plantillas |
|
||||
| Seguridad | MFA + auditoria |
|
||||
|
||||
---
|
||||
|
||||
*RESUMEN EPICA MAI-015 - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,204 @@
|
||||
# US-MAI015-001: Consultar tracking y documentos
|
||||
|
||||
**ID:** US-MAI015-001
|
||||
**Modulo:** MAI-015 (Portal Cliente)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** usuario cliente
|
||||
**Quiero** consultar el tracking de mis envios y descargar documentos
|
||||
**Para** tener visibilidad sin depender del call center
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Ver lista de envios
|
||||
**Dado** que tengo envios activos
|
||||
**Cuando** accedo al portal
|
||||
**Entonces** veo lista con estado, origen, destino, ETA
|
||||
|
||||
### CA-002: Ver tracking en mapa
|
||||
**Dado** que un envio esta en transito
|
||||
**Cuando** lo selecciono
|
||||
**Entonces** veo posicion en mapa con ruta
|
||||
|
||||
### CA-003: Ver timeline de eventos
|
||||
**Dado** que quiero saber que ha pasado
|
||||
**Cuando** consulto un envio
|
||||
**Entonces** veo timeline de eventos (carga, transito, etc.)
|
||||
|
||||
### CA-004: Descargar POD
|
||||
**Dado** que el envio fue entregado
|
||||
**Cuando** busco documentos
|
||||
**Entonces** puedo ver y descargar el POD
|
||||
|
||||
### CA-005: Descargar factura y Carta Porte
|
||||
**Dado** que el envio fue facturado
|
||||
**Cuando** consulto documentos
|
||||
**Entonces** descargo factura PDF/XML y Carta Porte
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Dashboard Principal
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| PORTAL CLIENTE - Liverpool SA de CV |
|
||||
+----------------------------------------------------------+
|
||||
| [Dashboard] [Mis Envios] [Crear OT] [Reclamaciones] |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Buenos dias, Maria Gonzalez |
|
||||
| |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | 3 | | 2 | | 12 | |
|
||||
| | En transito | | Entregados | | Este mes | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ENVIOS ACTIVOS |
|
||||
| |
|
||||
| | Ref. | Origen | Destino | Estado | ETA ||
|
||||
| |----------|-----------|-----------|-----------|------||
|
||||
| | PO-12345 | CDMX | Monterrey | En transi.| 14:30||
|
||||
| | PO-12346 | CDMX | Guadalaj. | Cargando | 18:00||
|
||||
| | PO-12347 | CDMX | Queretaro | Asignado | Manana|
|
||||
| |
|
||||
| [Ver todos mis envios] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ENTREGAS RECIENTES |
|
||||
| |
|
||||
| | Ref. | Destino | Entrega | POD | Factura ||
|
||||
| |----------|-----------|-----------|------|----------||
|
||||
| | PO-12340 | Leon | 26-ene | [Ver]| [Descar.]||
|
||||
| | PO-12338 | Tijuana | 25-ene | [Ver]| [Descar.]||
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Tracking en Mapa
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| TRACKING - PO-12345 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Origen: CEDIS CDMX |
|
||||
| Destino: CEDIS Monterrey |
|
||||
| Estado: EN TRANSITO |
|
||||
| ETA: Hoy 14:30 (en 2h 15m) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [MAPA] |
|
||||
| |
|
||||
| * CDMX (Origen - Salio 06:00) |
|
||||
| | |
|
||||
| | ---- Ruta 57D ---- |
|
||||
| | |
|
||||
| o Ubicacion actual: San Luis Potosi |
|
||||
| | Ultima actualizacion: hace 5 min |
|
||||
| | |
|
||||
| | ---- 280 km restantes ---- |
|
||||
| | |
|
||||
| * Monterrey (Destino - ETA 14:30) |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TIMELINE DE EVENTOS |
|
||||
| |
|
||||
| 12:15 En transito - San Luis Potosi |
|
||||
| 09:45 Salida de caseta Queretaro |
|
||||
| 08:30 Inicio de viaje |
|
||||
| 07:15 Carga completada |
|
||||
| 06:00 Arribo a origen |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DATOS DEL ENVIO |
|
||||
| |
|
||||
| Referencia: PO-12345 |
|
||||
| Unidad: T-1025 |
|
||||
| Operador: Juan Perez G. |
|
||||
| Peso: 18,500 kg |
|
||||
| Ventana entrega: 14:00 - 16:00 |
|
||||
| |
|
||||
| [Descargar tracking PDF] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Documentos
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| DOCUMENTOS - PO-12340 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Envio: PO-12340 | CDMX -> Leon |
|
||||
| Entregado: 26-ene-2026 10:45 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DOCUMENTOS DISPONIBLES |
|
||||
| |
|
||||
| | Documento | Fecha | Acciones | |
|
||||
| |-------------------|------------|------------------| |
|
||||
| | POD | 26-ene | [Ver] [Descargar]| |
|
||||
| | Factura (PDF) | 27-ene | [Ver] [Descargar]| |
|
||||
| | Factura (XML) | 27-ene | [Descargar] | |
|
||||
| | Carta Porte (PDF) | 27-ene | [Ver] [Descargar]| |
|
||||
| | Carta Porte (XML) | 27-ene | [Descargar] | |
|
||||
| |
|
||||
| [Descargar todo (ZIP)] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| VISTA PREVIA - POD |
|
||||
| |
|
||||
| +------------------------------------------------+ |
|
||||
| | | |
|
||||
| | [Foto de POD firmado] | |
|
||||
| | | |
|
||||
| | Receptor: Carlos Mendez | |
|
||||
| | Fecha/hora: 26-ene-2026 10:45 | |
|
||||
| | Firma: [imagen de firma] | |
|
||||
| | | |
|
||||
| +------------------------------------------------+ |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Frontend: React SPA separada
|
||||
- Auth: JWT con refresh tokens
|
||||
- API: Mismos endpoints, filtrado por tenant/cliente
|
||||
- Mapa: Google Maps o Mapbox
|
||||
- Documentos: S3 presigned URLs
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Login de usuarios cliente
|
||||
- [ ] Dashboard con envios activos
|
||||
- [ ] Lista filtrable de envios
|
||||
- [ ] Tracking en mapa con ruta
|
||||
- [ ] Timeline de eventos
|
||||
- [ ] Vista y descarga de POD
|
||||
- [ ] Descarga de facturas y Carta Porte
|
||||
- [ ] Responsive (movil)
|
||||
- [ ] Tests de consulta y descarga
|
||||
@ -0,0 +1,167 @@
|
||||
# US-MAI015-002: Crear OT desde portal
|
||||
|
||||
**ID:** US-MAI015-002
|
||||
**Modulo:** MAI-015 (Portal Cliente)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** usuario cliente
|
||||
**Quiero** crear ordenes de transporte desde el portal
|
||||
**Para** solicitar servicios sin llamar o enviar emails
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Crear OT manual
|
||||
**Dado** que necesito un envio
|
||||
**Cuando** lleno el formulario
|
||||
**Entonces** creo una OT con origen, destino, fechas, carga
|
||||
|
||||
### CA-002: Usar plantilla
|
||||
**Dado** que tengo rutas frecuentes
|
||||
**Cuando** selecciono una plantilla
|
||||
**Entonces** los datos se precargan y solo confirmo
|
||||
|
||||
### CA-003: Validar datos
|
||||
**Dado** que ingrese datos
|
||||
**Cuando** envio la OT
|
||||
**Entonces** el sistema valida direcciones, fechas y disponibilidad
|
||||
|
||||
### CA-004: Ver cotizacion
|
||||
**Dado** que la OT es valida
|
||||
**Cuando** reviso antes de confirmar
|
||||
**Entonces** veo precio estimado segun tarifa vigente
|
||||
|
||||
### CA-005: Confirmar y dar seguimiento
|
||||
**Dado** que confirmo la OT
|
||||
**Cuando** se procesa
|
||||
**Entonces** veo el numero asignado y puedo dar seguimiento
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Crear OT
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| CREAR ORDEN DE TRANSPORTE |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| [Crear desde cero] [Usar plantilla v] [Carga masiva] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| ORIGEN |
|
||||
| |
|
||||
| Direccion guardada: [CEDIS CDMX v] |
|
||||
| o Ingresar nueva direccion: |
|
||||
| [Av. Tlahuac 500, Iztapalapa, CDMX 09000 ] |
|
||||
| |
|
||||
| Fecha de carga: [29-ene-2026] |
|
||||
| Ventana: [08:00] a [10:00] |
|
||||
| Contacto: [Pedro Sanchez ] Tel: [55 1234 5678] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DESTINO |
|
||||
| |
|
||||
| Direccion guardada: [CEDIS Monterrey v] |
|
||||
| |
|
||||
| Fecha de entrega: [30-ene-2026] |
|
||||
| Ventana: [10:00] a [14:00] |
|
||||
| Contacto: [Ana Martinez ] Tel: [81 9876 5432] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| CARGA |
|
||||
| |
|
||||
| Descripcion: [Electrodomesticos - 25 tarimas ]|
|
||||
| Peso: [18,500 ] kg Volumen: [45 ] m3 |
|
||||
| Tipo equipo: [Caja seca 53' v] |
|
||||
| |
|
||||
| Instrucciones especiales: |
|
||||
| [Producto fragil. Estibar max 2 niveles. ]|
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| REFERENCIAS |
|
||||
| |
|
||||
| Numero de pedido (PO): [PO-12350 ] |
|
||||
| ASN: [ASN-2026-0089 ] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| COTIZACION ESTIMADA |
|
||||
| |
|
||||
| Tarifa base: $15,500.00 |
|
||||
| Fuel surcharge (5%): $775.00 |
|
||||
| ───────────────────────────────────── |
|
||||
| Total estimado: $16,275.00 MXN |
|
||||
| |
|
||||
| * Precio final puede variar segun recargos |
|
||||
| |
|
||||
| [Guardar como plantilla] |
|
||||
| |
|
||||
| [Cancelar] [Confirmar OT] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Plantillas Guardadas
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| MIS PLANTILLAS [+ Nueva] |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| | Nombre | Ruta | Uso/mes | |
|
||||
| |------------------|-------------------|---------| |
|
||||
| | Semanal MTY | CDMX -> Monterrey | 4 | [*] |
|
||||
| | Quincenal GDL | CDMX -> Guadalaj. | 2 | [*] |
|
||||
| | Mensual TIJ | CDMX -> Tijuana | 1 | [*] |
|
||||
| |
|
||||
| [*] = Usar plantilla |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validaciones
|
||||
|
||||
| Campo | Validacion | Mensaje |
|
||||
|-------|------------|---------|
|
||||
| Direccion | Geocodificable | Direccion no encontrada |
|
||||
| Fecha carga | > hoy | Fecha debe ser futura |
|
||||
| Fecha entrega | > fecha carga | Entrega debe ser despues de carga |
|
||||
| Peso | <= 25,000 kg | Excede peso maximo |
|
||||
| Credito | Disponible | Cliente sin credito |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `transport.ordenes_transporte`
|
||||
- Tabla: `transport.plantillas_ot_cliente`
|
||||
- Geocodificacion con Google Maps API
|
||||
- Cotizacion desde MAI-002 (Tarifas)
|
||||
- Notificacion a planeacion al crear
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Formulario de creacion de OT
|
||||
- [ ] Direcciones guardadas
|
||||
- [ ] Plantillas reutilizables
|
||||
- [ ] Validacion de datos
|
||||
- [ ] Cotizacion estimada
|
||||
- [ ] Confirmacion y numero de OT
|
||||
- [ ] Notificacion a operaciones
|
||||
- [ ] Tests de creacion
|
||||
@ -0,0 +1,219 @@
|
||||
# US-MAI015-003: Gestionar reclamaciones
|
||||
|
||||
**ID:** US-MAI015-003
|
||||
**Modulo:** MAI-015 (Portal Cliente)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** usuario cliente
|
||||
**Quiero** abrir y dar seguimiento a reclamaciones desde el portal
|
||||
**Para** reportar problemas y ver su resolucion
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptacion
|
||||
|
||||
### CA-001: Abrir reclamacion
|
||||
**Dado** que tuve un problema con un envio
|
||||
**Cuando** abro una reclamacion
|
||||
**Entonces** selecciono el envio, tipo de problema y subo evidencias
|
||||
|
||||
### CA-002: Ver mis reclamaciones
|
||||
**Dado** que tengo reclamaciones activas
|
||||
**Cuando** consulto el listado
|
||||
**Entonces** veo estado, fecha y ultima actualizacion
|
||||
|
||||
### CA-003: Agregar comentarios
|
||||
**Dado** que hay una reclamacion en curso
|
||||
**Cuando** tengo informacion adicional
|
||||
**Entonces** puedo agregar comentarios y archivos
|
||||
|
||||
### CA-004: Ver resolucion propuesta
|
||||
**Dado** que la investigacion concluyo
|
||||
**Cuando** hay una propuesta
|
||||
**Entonces** veo la resolucion y puedo aceptar o rechazar
|
||||
|
||||
### CA-005: Historial de reclamaciones
|
||||
**Dado** que quiero ver historial
|
||||
**Cuando** consulto reclamaciones cerradas
|
||||
**Entonces** veo todas con su resolucion final
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
### Abrir Reclamacion
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| ABRIR RECLAMACION X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| ENVIO RELACIONADO |
|
||||
| |
|
||||
| Buscar envio: [PO-12340 ] [Q] |
|
||||
| |
|
||||
| Envio seleccionado: |
|
||||
| PO-12340 | CDMX -> Leon | Entregado 26-ene-2026 |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TIPO DE RECLAMACION |
|
||||
| |
|
||||
| ( ) Retraso en entrega |
|
||||
| (o) Dano a mercancia |
|
||||
| ( ) Faltante |
|
||||
| ( ) Entrega incorrecta |
|
||||
| ( ) Cobro incorrecto |
|
||||
| ( ) Otro |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| DESCRIPCION DEL PROBLEMA |
|
||||
| |
|
||||
| [Se recibieron 3 cajas con dano visible. Producto ]|
|
||||
| [en interior golpeado. Fotos adjuntas. ]|
|
||||
| |
|
||||
| Valor estimado del dano: [$8,500.00] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| EVIDENCIAS |
|
||||
| |
|
||||
| [+ Agregar fotos] [+ Agregar documentos] |
|
||||
| |
|
||||
| [IMG] dano_caja1.jpg |
|
||||
| [IMG] dano_caja2.jpg |
|
||||
| [IMG] dano_caja3.jpg |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| [Cancelar] [Enviar Reclamacion]|
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Mis Reclamaciones
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| MIS RECLAMACIONES |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| [Activas] [Resueltas] [Todas] |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| RECLAMACIONES ACTIVAS |
|
||||
| |
|
||||
| +----------------------------------------------------+ |
|
||||
| | #REC-2026-0089 | |
|
||||
| | Envio: PO-12340 | Tipo: Dano a mercancia | |
|
||||
| | Abierta: 27-ene-2026 | |
|
||||
| | Estado: EN INVESTIGACION | |
|
||||
| | Ultima actualizacion: hace 2 horas | |
|
||||
| | [Ver >] | |
|
||||
| +----------------------------------------------------+ |
|
||||
| |
|
||||
| +----------------------------------------------------+ |
|
||||
| | #REC-2026-0085 | |
|
||||
| | Envio: PO-12335 | Tipo: Faltante | |
|
||||
| | Abierta: 22-ene-2026 | |
|
||||
| | Estado: PENDIENTE RESPUESTA | |
|
||||
| | Ultima actualizacion: hace 1 dia | |
|
||||
| | [Ver >] | |
|
||||
| +----------------------------------------------------+ |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Detalle de Reclamacion
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| RECLAMACION #REC-2026-0089 X |
|
||||
+----------------------------------------------------------+
|
||||
| |
|
||||
| Envio: PO-12340 | CDMX -> Leon |
|
||||
| Tipo: Dano a mercancia |
|
||||
| Abierta: 27-ene-2026 |
|
||||
| Estado: PENDIENTE RESPUESTA |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| PROPUESTA DE RESOLUCION |
|
||||
| |
|
||||
| +----------------------------------------------------+ |
|
||||
| | Despues de investigar, se determino que el dano | |
|
||||
| | ocurrio durante el transporte. Se propone: | |
|
||||
| | | |
|
||||
| | Nota de credito por: $8,500.00 | |
|
||||
| | | |
|
||||
| | Esta de acuerdo con esta resolucion? | |
|
||||
| | | |
|
||||
| | [Rechazar - Comentar] [Aceptar] | |
|
||||
| +----------------------------------------------------+ |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| TIMELINE |
|
||||
| |
|
||||
| 29-ene 10:00 | Propuesta de resolucion |
|
||||
| | Se determino responsabilidad del |
|
||||
| | transportista. NC por $8,500. |
|
||||
| |
|
||||
| 28-ene 14:00 | En investigacion |
|
||||
| | Se contacto al operador y destino. |
|
||||
| |
|
||||
| 27-ene 16:00 | Reclamacion recibida |
|
||||
| | Asignada a Maria Rodriguez. |
|
||||
| |
|
||||
| ------------------------------------------------------ |
|
||||
| |
|
||||
| AGREGAR COMENTARIO |
|
||||
| |
|
||||
| [Escribir comentario... ] |
|
||||
| [+ Adjuntar archivo] [Enviar] |
|
||||
| |
|
||||
+----------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados de Reclamacion (vista cliente)
|
||||
|
||||
| Estado | Descripcion |
|
||||
|--------|-------------|
|
||||
| RECIBIDA | Registrada, pendiente revision |
|
||||
| EN_INVESTIGACION | Equipo investigando |
|
||||
| PENDIENTE_INFO | Esperando datos del cliente |
|
||||
| PENDIENTE_RESPUESTA | Propuesta enviada |
|
||||
| RESUELTA | Cliente acepto resolucion |
|
||||
| CERRADA | Finalizada |
|
||||
|
||||
---
|
||||
|
||||
## Notas Tecnicas
|
||||
|
||||
- Tabla: `tracking.incidencias` (vista filtrada)
|
||||
- Tabla: `tracking.bitacora_incidencia`
|
||||
- Solo ve sus propias reclamaciones
|
||||
- Notificaciones por email en cambios
|
||||
- Integracion con MAI-008
|
||||
|
||||
---
|
||||
|
||||
## Definicion de Done
|
||||
|
||||
- [ ] Formulario de apertura de reclamacion
|
||||
- [ ] Carga de evidencias
|
||||
- [ ] Lista de mis reclamaciones
|
||||
- [ ] Timeline de actualizaciones
|
||||
- [ ] Agregar comentarios
|
||||
- [ ] Aceptar/rechazar propuesta
|
||||
- [ ] Notificaciones de cambios
|
||||
- [ ] Tests de flujo cliente
|
||||
Loading…
Reference in New Issue
Block a user