From 9caeae936a9da3823ccc2758a1d470641d79a891 Mon Sep 17 00:00:00 2001 From: Adrian Flores Cortes Date: Tue, 27 Jan 2026 01:51:58 -0600 Subject: [PATCH] docs: Add MAI-002, MAI-004, MAI-005 module specifications MAI-002 (Tarifas y SLA): - README, REQUERIMIENTOS, RESUMEN-EPICA - 5 User Stories (31 SP total) - Covers: tarifario por lane, recargos, SLA, cotizaciones, aprobaciones MAI-004 (Planeacion TMS): - README, REQUERIMIENTOS, RESUMEN-EPICA - 5 User Stories (39 SP total) - Covers: tablero planeacion, consolidacion, asignacion, validaciones, ETA MAI-005 (Despacho): - README, REQUERIMIENTOS, RESUMEN-EPICA - 5 User Stories (28 SP total) - Covers: checklist NOM-068, sellos, evidencias, kit documental, gate out Co-Authored-By: Claude Opus 4.5 --- .../MAI-002-tarifas-sla/README.md | 223 +++++++++++++++ .../MAI-002-tarifas-sla/REQUERIMIENTOS.md | 197 +++++++++++++ .../MAI-002-tarifas-sla/RESUMEN-EPICA.md | 233 +++++++++++++++ .../historias-usuario/US-MAI002-001.md | 185 ++++++++++++ .../historias-usuario/US-MAI002-002.md | 227 +++++++++++++++ .../historias-usuario/US-MAI002-003.md | 218 ++++++++++++++ .../historias-usuario/US-MAI002-004.md | 265 +++++++++++++++++ .../historias-usuario/US-MAI002-005.md | 268 ++++++++++++++++++ .../MAI-004-planeacion/README.md | 210 ++++++++++++++ .../MAI-004-planeacion/REQUERIMIENTOS.md | 223 +++++++++++++++ .../MAI-004-planeacion/RESUMEN-EPICA.md | 191 +++++++++++++ .../historias-usuario/US-MAI004-001.md | 96 +++++++ .../historias-usuario/US-MAI004-002.md | 110 +++++++ .../historias-usuario/US-MAI004-003.md | 118 ++++++++ .../historias-usuario/US-MAI004-004.md | 113 ++++++++ .../historias-usuario/US-MAI004-005.md | 125 ++++++++ .../MAI-005-despacho/README.md | 216 ++++++++++++++ .../MAI-005-despacho/REQUERIMIENTOS.md | 214 ++++++++++++++ .../MAI-005-despacho/RESUMEN-EPICA.md | 215 ++++++++++++++ .../historias-usuario/US-MAI005-001.md | 142 ++++++++++ .../historias-usuario/US-MAI005-002.md | 172 +++++++++++ .../historias-usuario/US-MAI005-003.md | 171 +++++++++++ .../historias-usuario/US-MAI005-004.md | 158 +++++++++++ .../historias-usuario/US-MAI005-005.md | 208 ++++++++++++++ 24 files changed, 4498 insertions(+) create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/README.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/RESUMEN-EPICA.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-001.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-002.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-003.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-004.md create mode 100644 docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-005.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/README.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/RESUMEN-EPICA.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-001.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-002.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-003.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-004.md create mode 100644 docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-005.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/README.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/REQUERIMIENTOS.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/RESUMEN-EPICA.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-001.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-002.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-003.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-004.md create mode 100644 docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-005.md diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/README.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/README.md new file mode 100644 index 0000000..ac850b1 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/README.md @@ -0,0 +1,223 @@ +# MAI-002: Tarifas, Contratos y SLA + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Estado:** Diseño +**Prioridad:** P0 (Crítico - Base Comercial) + +--- + +## Descripción General + +El módulo de Tarifas, Contratos y SLA es responsable de la gestión comercial del transporte: definición de precios por ruta/servicio, cálculo de recargos, contratos con clientes y acuerdos de nivel de servicio. + +**Problema que resuelve:** +- Cotizaciones manuales inconsistentes +- Tarifas dispersas en hojas de cálculo +- Recargos olvidados o mal calculados +- Incumplimiento de SLA sin penalización +- Descuentos sin control ni aprobación + +--- + +## Objetivos del Módulo + +1. **Tarifario estructurado:** Tarifas por lane, tipo de unidad, modalidad (FTL/LTL) +2. **Recargos automatizados:** Fuel surcharge, detention, reentrega, maniobras +3. **SLA documentados:** Tiempos comprometidos, penalizaciones, tolerancias +4. **Cotización rápida:** Cálculo automático con desglose de costos +5. **Control de descuentos:** Flujos de aprobación por monto/porcentaje + +--- + +## Alcance Funcional + +### Incluido + +- Gestión de tarifario por lane (origen-destino-zona) +- Matriz de recargos (surcharges) configurables +- Contratos con clientes y vigencias +- Definición de SLA por cliente/servicio +- Motor de cotización con cálculo automático +- Flujos de aprobación para descuentos/excepciones +- Snapshot de tarifa aplicada a cada OT + +### Excluido + +- Facturación (MAI-009) +- Captura de OT (MAI-003) +- CRM avanzado (módulo heredado de erp-core) + +--- + +## Actores + +| Actor | Rol en el módulo | +|-------|------------------| +| Ejecutivo de Ventas | Cotiza, negocia tarifas, gestiona contratos | +| Gerente Comercial | Aprueba descuentos, define políticas | +| Planner | Consulta tarifas para planeación | +| Sistema | Calcula precios, valida vigencias, aplica recargos | + +--- + +## Flujo Principal + +``` +CLIENTE SOLICITA COTIZACIÓN + │ + ▼ +┌─────────────────────────────────────────┐ +│ 1. IDENTIFICAR LANE │ +│ - Origen → Destino │ +│ - Zona tarifaria │ +│ - Tipo de equipo requerido │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 2. BUSCAR TARIFA VIGENTE │ +│ - Por contrato del cliente │ +│ - Por tarifa general del lane │ +│ - Por tarifa por defecto │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 3. CALCULAR RECARGOS │ +│ - Fuel surcharge (% o fijo) │ +│ - Maniobras │ +│ - Escolta/seguridad │ +│ - Seguro adicional │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 4. APLICAR DESCUENTO (si aplica) │ +│ - Dentro de límite → Automático │ +│ - Excede límite → Requiere aprobación│ +└────────────────────┬────────────────────┘ + │ + ┌──────┴──────┐ + │ │ + ▼ ▼ + [APROBADO] [PENDIENTE] + │ │ + ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ +│ 5. GENERAR │ │ Flujo de │ +│ COTIZACIÓN │ │ aprobación │ +│ - Desglose │ │ │ +│ - Vigencia │ │ │ +│ - PDF │ │ │ +└────────┬────────┘ └────────┬────────┘ + │ │ + ▼ ▼ +┌─────────────────────────────────────────┐ +│ COTIZACIÓN LISTA │ +│ → Convertir a OT si acepta │ +└─────────────────────────────────────────┘ +``` + +--- + +## Datos del Módulo + +### Entidades Principales + +| Entidad | Descripción | Estado | +|---------|-------------|--------| +| Tarifa | Precio base por lane/servicio | NO IMPLEMENTADA | +| Lane | Combinación origen-destino-zona | NO IMPLEMENTADA | +| Recargo | Tipo de surcharge aplicable | NO IMPLEMENTADA | +| Contrato | Acuerdo comercial con cliente | NO IMPLEMENTADA | +| SLA | Niveles de servicio comprometidos | NO IMPLEMENTADA | +| Cotizacion | Propuesta de precio al cliente | NO IMPLEMENTADA | + +### Campos Clave Tarifa + +| Campo | Tipo | Obligatorio | Descripción | +|-------|------|-------------|-------------| +| lane_id | UUID | Sí | Lane (origen-destino) | +| tipo_unidad | ENUM | Sí | TRACTOCAMION, TORTON, RABON, etc. | +| modalidad | ENUM | Sí | FTL, LTL | +| precio_base | DECIMAL | Sí | Monto base | +| moneda | ENUM | Sí | MXN, USD | +| vigencia_inicio | DATE | Sí | Desde cuándo aplica | +| vigencia_fin | DATE | No | Hasta cuándo aplica | +| cliente_id | UUID | No | Si es tarifa específica de cliente | + +--- + +## Requerimientos Funcionales + +Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md) + +--- + +## Tipos de Tarifa + +| Tipo | Descripción | Ejemplo | +|------|-------------|---------| +| Por viaje | Monto fijo por trayecto | $15,000 MXN CDMX→GDL | +| Por km | Precio por kilómetro | $18 MXN/km | +| Por tonelada | Precio por peso | $450 MXN/ton | +| Por pallet | Precio por posición | $800 MXN/pallet | +| Combinada | Base + variable | $8,000 + $12/km | + +--- + +## Tipos de Recargo + +| Código | Nombre | Cálculo | +|--------|--------|---------| +| FUEL | Fuel Surcharge | % sobre base | +| DETENTION_CARGA | Demora en carga | $/hora después de tolerancia | +| DETENTION_DESCARGA | Demora en descarga | $/hora después de tolerancia | +| MANIOBRA | Maniobra especial | Monto fijo | +| REENTREGA | Reentrega/reexpedición | % o monto fijo | +| ESCOLTA | Escolta de seguridad | Monto fijo | +| SEGURO_ADICIONAL | Seguro extra | % sobre valor declarado | +| ALMACENAJE | Almacenaje temporal | $/día | + +--- + +## Métricas del Módulo + +| KPI | Fórmula | Meta | +|-----|---------|------| +| Cotizaciones convertidas | % cotizaciones → OT | >30% | +| Tiempo de cotización | Avg(tiempo de respuesta) | <2 hrs | +| Descuentos fuera de política | % descuentos con override | <10% | +| Tarifas actualizadas | % tarifas vigentes | 100% | + +--- + +## Dependencias + +### Este módulo depende de: +- MAE-001 (Clientes/Partners): Datos de cliente +- erp-core/catalogs: Zonas, tipos de equipo + +### Otros módulos dependen de este: +- MAI-003 (OT): Usa tarifa para precio de OT +- MAI-009 (Facturación): Usa tarifa para facturar +- MAI-004 (Planeación): Consulta tarifas para optimización + +--- + +## Historias de Usuario + +Ver carpeta: [historias-usuario/](./historias-usuario/) + +| US | Título | Prioridad | +|----|--------|-----------| +| US-MAI002-001 | Definir tarifa por lane | Alta | +| US-MAI002-002 | Configurar recargos | Alta | +| US-MAI002-003 | Definir SLA por cliente | Alta | +| US-MAI002-004 | Generar cotización rápida | Alta | +| US-MAI002-005 | Aprobar descuento excepcional | Media | + +--- + +*Módulo MAI-002 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md new file mode 100644 index 0000000..1428233 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md @@ -0,0 +1,197 @@ +# REQUERIMIENTOS.md - MAI-002: Tarifas, Contratos y SLA + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.1 + +--- + +## Requerimientos Funcionales + +### RF-4.1.1: Tarifario por Lane y Servicio + +**Descripción:** +El sistema debe permitir definir tarifas por ruta (origen/destino/zona), tipo de unidad, modalidad (FTL/LTL), prioridad y vigencia. + +**Criterios de Aceptación:** +1. Crear tarifas con lane (origen-destino o zona) +2. Especificar tipo de unidad (tractocamión, torton, rabón, etc.) +3. Definir modalidad: FTL (carga completa) o LTL (carga parcial) +4. Configurar prioridad/servicio (estándar, express, mismo día) +5. Establecer vigencia (fecha inicio, fecha fin opcional) +6. Soportar múltiples monedas (MXN, USD) +7. Definir tarifa específica por cliente o general + +**Mapeo a DDL:** +- Tabla: `tarifas` +- Tabla: `lanes` +- Tabla: `zonas_tarifarias` + +**Endpoints Requeridos:** +- `GET /api/v1/tarifas` - Listar tarifas +- `POST /api/v1/tarifas` - Crear tarifa +- `PUT /api/v1/tarifas/:id` - Actualizar tarifa +- `GET /api/v1/tarifas/buscar` - Buscar tarifa por lane/cliente + +**Prioridad:** Alta + +--- + +### RF-4.1.2: Matriz de Recargos (Surcharges) + +**Descripción:** +El sistema debe gestionar una matriz de recargos aplicables: fuel surcharge, demoras, almacenaje, reexpedición, maniobras, escoltas, seguro adicional. + +**Criterios de Aceptación:** +1. Catálogo de tipos de recargo configurable +2. Cada recargo define: nombre, código, tipo de cálculo (% o fijo) +3. Fuel surcharge con índice actualizable periódicamente +4. Demoras (detention) con tolerancia en horas y costo por hora extra +5. Recargos por cliente/servicio o generales +6. Vigencia por recargo +7. Reglas de aplicación automática o manual + +**Mapeo a DDL:** +- Tabla: `tipos_recargo` +- Tabla: `recargos_cliente` +- Tabla: `indice_combustible` + +**Endpoints Requeridos:** +- `GET /api/v1/recargos/tipos` - Catálogo de tipos +- `POST /api/v1/recargos` - Crear recargo +- `PUT /api/v1/recargos/fuel-surcharge` - Actualizar índice combustible +- `GET /api/v1/recargos/calcular` - Calcular recargos aplicables + +**Prioridad:** Alta + +--- + +### RF-4.1.3: SLA por Cliente + +**Descripción:** +El sistema debe permitir definir acuerdos de nivel de servicio (SLA) con tiempos comprometidos, ventanas, penalizaciones, tolerancias y reglas de notificación. + +**Criterios de Aceptación:** +1. Definir SLA por cliente o por tipo de servicio +2. Especificar tiempo de pickup comprometido (horas desde solicitud) +3. Especificar tiempo de entrega (horas o días según distancia) +4. Definir tolerancias (minutos/horas de gracia) +5. Configurar penalizaciones por incumplimiento (% o monto) +6. Reglas de notificación (alertas antes de vencer SLA) +7. Dashboard de cumplimiento de SLA + +**Mapeo a DDL:** +- Tabla: `sla_clientes` +- Tabla: `sla_servicios` +- Vista: `v_cumplimiento_sla` + +**Endpoints Requeridos:** +- `GET /api/v1/clientes/:id/sla` - Obtener SLA del cliente +- `POST /api/v1/sla` - Crear SLA +- `GET /api/v1/sla/cumplimiento` - Reporte de cumplimiento + +**Prioridad:** Alta + +--- + +### RF-4.1.4: Cotización Rápida + +**Descripción:** +El sistema debe permitir generar cotizaciones desde CRM/ventas con cálculo automático de tarifa base + recargos, considerando distancia/kms si se integra con mapas. + +**Criterios de Aceptación:** +1. Buscar tarifa vigente por lane y tipo de servicio +2. Calcular distancia si se integra con API de mapas +3. Aplicar recargos automáticamente según reglas +4. Mostrar desglose de precio (base + recargos) +5. Permitir agregar descuento (dentro de política) +6. Generar PDF de cotización con vigencia +7. Guardar snapshot de tarifa aplicada +8. Convertir cotización a OT si cliente acepta + +**Mapeo a DDL:** +- Tabla: `cotizaciones` +- Tabla: `cotizacion_detalle` +- Tabla: `snapshot_tarifa` + +**Endpoints Requeridos:** +- `POST /api/v1/cotizaciones` - Crear cotización +- `GET /api/v1/cotizaciones/:id` - Obtener cotización +- `GET /api/v1/cotizaciones/:id/pdf` - Generar PDF +- `POST /api/v1/cotizaciones/:id/convertir-ot` - Convertir a OT + +**Prioridad:** Alta + +--- + +### RF-4.1.5: Control de Aprobaciones + +**Descripción:** +El sistema debe implementar flujos de aprobación para descuentos, tarifas especiales y recargos excepcionales según políticas definidas. + +**Criterios de Aceptación:** +1. Definir umbrales de descuento por rol (ej: vendedor hasta 5%, gerente hasta 15%) +2. Descuento dentro de umbral se aplica automáticamente +3. Descuento fuera de umbral requiere aprobación +4. Flujo de aprobación con niveles (supervisor → gerente) +5. Notificación al aprobador cuando hay solicitud pendiente +6. Registro de aprobaciones/rechazos con motivo +7. Tarifas especiales (fuera de catálogo) requieren aprobación +8. Auditoría de todas las excepciones + +**Mapeo a DDL:** +- Tabla: `politicas_descuento` +- Tabla: `solicitudes_aprobacion` +- Tabla: `aprobaciones` + +**Endpoints Requeridos:** +- `POST /api/v1/descuentos/solicitar` - Solicitar aprobación +- `GET /api/v1/aprobaciones/pendientes` - Listar pendientes +- `POST /api/v1/aprobaciones/:id/aprobar` - Aprobar solicitud +- `POST /api/v1/aprobaciones/:id/rechazar` - Rechazar solicitud + +**Prioridad:** Media + +--- + +## Requerimientos No Funcionales + +### RNF-001: Performance de Búsqueda +La búsqueda de tarifa por lane debe responder en menos de 500ms. + +### RNF-002: Consistencia de Precios +El sistema debe garantizar que la tarifa aplicada a una OT es la vigente al momento de creación (snapshot inmutable). + +### RNF-003: Auditoría +Todos los cambios de tarifa, recargos y aprobaciones deben registrarse con usuario, fecha y valores anteriores/nuevos. + +### RNF-004: Multi-moneda +Soportar al menos MXN y USD con conversión configurable. + +--- + +## Validaciones de Negocio + +| Validación | Descripción | Acción si falla | +|------------|-------------|-----------------| +| TAR_001 | Tarifa vigente para el lane | Alertar, usar tarifa por defecto | +| TAR_002 | Descuento dentro de política | Requiere aprobación | +| TAR_003 | Contrato del cliente vigente | Usar tarifa general | +| TAR_004 | Fuel surcharge actualizado | Alertar si índice >30 días | +| TAR_005 | SLA definido para el cliente | Usar SLA por defecto | + +--- + +## Matriz de Trazabilidad + +| RF | Tabla DDL | Entity | Endpoint | US | +|----|-----------|--------|----------|---| +| RF-4.1.1 | tarifas, lanes | Tarifa, Lane | /tarifas | US-MAI002-001 | +| RF-4.1.2 | tipos_recargo | TipoRecargo | /recargos | US-MAI002-002 | +| RF-4.1.3 | sla_clientes | SLACliente | /sla | US-MAI002-003 | +| RF-4.1.4 | cotizaciones | Cotizacion | /cotizaciones | US-MAI002-004 | +| RF-4.1.5 | solicitudes_aprobacion | SolicitudAprobacion | /aprobaciones | US-MAI002-005 | + +--- + +*MAI-002 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/RESUMEN-EPICA.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/RESUMEN-EPICA.md new file mode 100644 index 0000000..b99dc7b --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/RESUMEN-EPICA.md @@ -0,0 +1,233 @@ +# RESUMEN-EPICA.md - MAI-002: Tarifas, Contratos y SLA + +**Código:** MAI-002 +**Nombre:** Tarifas, Contratos y SLA +**Version:** 1.0.0 +**Fecha:** 2026-01-27 + +--- + +## Valor de Negocio + +### Problema + +Las empresas transportistas enfrentan pérdidas por: +- Cotizaciones inconsistentes entre vendedores +- Recargos olvidados (fuel, demoras) no facturados +- Tarifas desactualizadas que generan márgenes negativos +- Descuentos sin control que erosionan rentabilidad +- Incumplimiento de SLA sin consecuencias + +### Solución + +Un módulo de gestión comercial que: +- Centraliza tarifario por lane/servicio +- Automatiza cálculo de recargos +- Documenta SLA con penalizaciones +- Genera cotizaciones con desglose +- Controla descuentos con flujos de aprobación + +### Beneficios Esperados + +| Beneficio | Métrica | Impacto | +|-----------|---------|---------| +| Recuperación de recargos | +15% ingresos por recargos | Rentabilidad | +| Tiempo de cotización | -70% tiempo de respuesta | Productividad | +| Control de descuentos | -50% descuentos excesivos | Margen | +| Cumplimiento SLA | +20% OTIF | Satisfacción cliente | + +--- + +## Actores y Stakeholders + +### Usuarios Primarios + +| Actor | Responsabilidad | Frecuencia | +|-------|-----------------|------------| +| Ejecutivo de Ventas | Crea cotizaciones, gestiona tarifas | Diaria | +| Gerente Comercial | Aprueba descuentos, define políticas | Semanal | +| Administrador | Configura recargos, actualiza índices | Mensual | + +### Usuarios Secundarios + +| Actor | Interés | +|-------|---------| +| Planner | Consulta tarifas para costeo de rutas | +| Facturación | Usa tarifas para generar facturas | +| Finanzas | Reportes de margen por cliente/lane | + +--- + +## Flujo Principal + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SOLICITUD DE COTIZACIÓN │ +│ (Cliente pide precio de servicio) │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 1. IDENTIFICAR SERVICIO (Ejecutivo de Ventas) │ +│ │ +│ Cliente: [Distribuidora ABC ▼] │ +│ │ +│ Origen: [CDMX - Bodega Norte ] │ +│ Destino: [Guadalajara - Centro ] │ +│ │ +│ Tipo de equipo: (●) Caja seca 53' ( ) Refrigerado ( ) Plat │ +│ Modalidad: (●) FTL ( ) LTL │ +│ Servicio: (●) Estándar ( ) Express │ +│ │ +│ [Buscar Tarifa] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 2. TARIFA ENCONTRADA │ +│ │ +│ Lane: CDMX → GDL (Zona Centro) │ +│ Distancia: 540 km │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Tarifa base: $12,500.00 MXN │ │ +│ │ Vigencia: 01-ene-2026 al 31-dic-2026 │ │ +│ │ Tipo: Por viaje (FTL) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ [Continuar con Recargos] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 3. CALCULAR RECARGOS │ +│ │ +│ Recargos aplicables: │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ☑ Fuel Surcharge (8%) $1,000.00 │ │ +│ │ ☐ Maniobra de carga $800.00 │ │ +│ │ ☐ Maniobra de descarga $800.00 │ │ +│ │ ☑ Seguro adicional (0.5%) $250.00 │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Subtotal recargos: $1,250.00 │ +│ │ +│ [Continuar] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 4. APLICAR DESCUENTO (Opcional) │ +│ │ +│ Subtotal: $13,750.00 MXN │ +│ │ +│ ¿Aplicar descuento? │ +│ Descuento: [5] % = $687.50 │ +│ │ +│ ✓ Dentro de tu límite (hasta 5%) │ +│ │ +│ Total cotización: $13,062.50 MXN │ +│ │ +│ [Generar Cotización] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 5. COTIZACIÓN GENERADA │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ COTIZACIÓN COT-2026-00456 │ │ +│ │ │ │ +│ │ Cliente: Distribuidora ABC │ │ +│ │ Servicio: CDMX → GDL | Caja seca 53' | FTL │ │ +│ │ │ │ +│ │ DESGLOSE: │ │ +│ │ Tarifa base (FTL CDMX→GDL) $12,500.00 │ │ +│ │ Fuel Surcharge (8%) $1,000.00 │ │ +│ │ Seguro adicional (0.5%) $250.00 │ │ +│ │ Subtotal $13,750.00 │ │ +│ │ Descuento (5%) -$687.50 │ │ +│ │ ───────────────────────────────────────────── │ │ +│ │ TOTAL $13,062.50 MXN │ │ +│ │ │ │ +│ │ Vigencia cotización: 7 días │ │ +│ │ Tiempo de entrega: 24-48 hrs │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ [Descargar PDF] [Enviar por email] [Convertir a OT] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ COTIZACIÓN ENVIADA │ +│ → Si acepta: Convertir a OT (MAI-003) │ +│ → Snapshot de tarifa guardado │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Criterios de Éxito + +### Funcionales + +- [ ] CRUD de tarifas por lane +- [ ] Matriz de recargos configurable +- [ ] SLA por cliente documentado +- [ ] Motor de cotización automático +- [ ] Flujo de aprobación de descuentos +- [ ] Snapshot de tarifa al crear OT + +### Técnicos + +- [ ] Búsqueda de tarifa <500ms +- [ ] Histórico de cambios auditado +- [ ] Soporte multi-moneda +- [ ] Integración con API de mapas (opcional) + +### Negocio + +- [ ] 100% cotizaciones con desglose +- [ ] 100% recargos aplicados según reglas +- [ ] <10% descuentos fuera de política +- [ ] Tiempo de cotización <5 minutos + +--- + +## Riesgos y Mitigaciones + +| Riesgo | Probabilidad | Impacto | Mitigación | +|--------|--------------|---------|------------| +| Tarifas no actualizadas | Alta | Alto | Alertas de vencimiento | +| Índice fuel desactualizado | Media | Medio | Recordatorio mensual | +| Descuentos excesivos | Media | Alto | Umbrales por rol | +| Complejidad de lanes | Media | Medio | Zonas tarifarias | + +--- + +## Dependencias + +### Prerequisitos +- erp-core/partners: Catálogo de clientes +- erp-core/catalogs: Zonas, tipos de equipo + +### Habilita +- MAI-003 (OT): Precio de orden de transporte +- MAI-009 (Facturación): Base para facturar + +--- + +## Story Points Estimados + +| Historia | Complejidad | SP | +|----------|-------------|---| +| US-MAI002-001 | Alta | 8 | +| US-MAI002-002 | Media | 5 | +| US-MAI002-003 | Media | 5 | +| US-MAI002-004 | Alta | 8 | +| US-MAI002-005 | Media | 5 | +| **Total** | | **31** | + +--- + +*Épica MAI-002 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-001.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-001.md new file mode 100644 index 0000000..aa3e6ea --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-001.md @@ -0,0 +1,185 @@ +# US-MAI002-001: Definir tarifa por lane + +**ID:** US-MAI002-001 +**Módulo:** MAI-002 (Tarifas y SLA) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** ejecutivo de ventas +**Quiero** definir tarifas por lane (origen-destino) con diferentes tipos de servicio y vigencias +**Para** tener un tarifario estructurado que permita cotizar rápidamente + +--- + +## Criterios de Aceptación + +### CA-001: Crear tarifa básica +**Dado** que necesito definir un precio para una ruta +**Cuando** creo una nueva tarifa +**Entonces** puedo especificar: lane (origen-destino), tipo de unidad, modalidad (FTL/LTL), precio base y vigencia + +### CA-002: Definir lane por zona o ubicación específica +**Dado** que algunos precios aplican a zonas completas +**Cuando** defino el lane +**Entonces** puedo elegir entre zona tarifaria (ej: "Zona Centro") o ubicación específica (ej: "CDMX Tepito") + +### CA-003: Tipos de tarifa +**Dado** que existen diferentes esquemas de cobro +**Cuando** defino el tipo de tarifa +**Entonces** puedo elegir: por viaje, por km, por tonelada, por pallet, o combinada + +### CA-004: Tarifa específica por cliente +**Dado** que algunos clientes tienen precios negociados +**Cuando** creo una tarifa +**Entonces** puedo asociarla a un cliente específico (aplica solo a ese cliente) + +### CA-005: Control de vigencias +**Dado** que las tarifas cambian con el tiempo +**Cuando** defino vigencia +**Entonces** el sistema solo aplica tarifas vigentes y alerta cuando están por vencer + +### CA-006: Búsqueda de tarifa vigente +**Dado** que necesito encontrar el precio para una ruta +**Cuando** busco por origen, destino, tipo de unidad y cliente +**Entonces** el sistema retorna la tarifa más específica vigente (cliente > general) + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ NUEVA TARIFA ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ INFORMACIÓN DEL LANE │ +│ │ +│ Origen │ +│ Tipo: (●) Zona tarifaria ( ) Ubicación específica │ +│ Zona: [Zona Metropolitana CDMX ▼] │ +│ │ +│ Destino │ +│ Tipo: (●) Zona tarifaria ( ) Ubicación específica │ +│ Zona: [Zona Centro (GDL, AGS, QRO)▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ CONFIGURACIÓN DE TARIFA │ +│ │ +│ Tipo de unidad: [Tractocamión - Caja seca 53' ▼] │ +│ │ +│ Modalidad: (●) FTL (Carga completa) ( ) LTL (Consolidado) │ +│ │ +│ Servicio: (●) Estándar ( ) Express ( ) Mismo día │ +│ │ +│ Tipo de tarifa: [Por viaje (monto fijo) ▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ PRECIO │ +│ │ +│ Precio base: [$12,500.00] Moneda: [MXN ▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ VIGENCIA │ +│ │ +│ Fecha inicio: [2026-01-01] │ +│ Fecha fin: [2026-12-31] ☐ Sin fecha de fin │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ALCANCE │ +│ │ +│ (●) Tarifa general (todos los clientes) │ +│ ( ) Tarifa específica: [Seleccionar cliente...] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ [Cancelar] [Guardar Tarifa] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Lista de Tarifas + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ TARIFARIO [+ Nueva]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Filtros: [Zona origen ▼] [Zona destino ▼] [Tipo unidad ▼] │ +│ [Modalidad ▼] [Estado: Vigente ▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ CDMX → Zona Centro │ │ +│ │ Caja seca 53' | FTL | Estándar │ │ +│ │ $12,500.00 MXN por viaje │ │ +│ │ Vigente: 01-ene-2026 al 31-dic-2026 │ │ +│ │ Alcance: General [Editar]│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ CDMX → Zona Centro │ │ +│ │ Caja seca 53' | FTL | Estándar │ │ +│ │ $11,800.00 MXN por viaje │ │ +│ │ Vigente: 01-ene-2026 al 31-dic-2026 │ │ +│ │ Alcance: Distribuidora ABC (contrato) [Editar]│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Zona Norte → Zona Sur │ │ +│ │ Torton | FTL | Estándar │ │ +│ │ $18.00 MXN por km │ │ +│ │ Vigente: 15-feb-2026 al -- │ │ +│ │ Alcance: General [Editar]│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Mostrando 3 de 45 tarifas [< 1 2 3 4 5 >] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Tipos de Tarifa + +| Tipo | Campos requeridos | Ejemplo | +|------|-------------------|---------| +| Por viaje | precio_base | $12,500 por viaje | +| Por km | precio_por_km | $18/km | +| Por tonelada | precio_por_ton | $450/ton | +| Por pallet | precio_por_pallet | $800/pallet | +| Combinada | precio_base + precio_por_km | $8,000 + $12/km | + +--- + +## Notas Técnicas + +- Tabla: `tarifas` con `lane_id`, `tipo_unidad`, `modalidad`, `servicio` +- Tabla: `lanes` con `origen_zona_id`, `destino_zona_id` +- Tabla: `zonas_tarifarias` con polígono o lista de ubicaciones +- Índice por (cliente_id, lane_id, tipo_unidad, modalidad, vigencia) +- Soft delete para mantener histórico + +--- + +## Definición de Done + +- [ ] CRUD completo de tarifas +- [ ] Gestión de lanes por zona o ubicación +- [ ] Soporte para todos los tipos de tarifa +- [ ] Tarifa específica por cliente +- [ ] Control de vigencias con alertas +- [ ] Búsqueda de tarifa vigente más específica +- [ ] Tests unitarios de búsqueda +- [ ] Tests de integración + diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-002.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-002.md new file mode 100644 index 0000000..085bdff --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-002.md @@ -0,0 +1,227 @@ +# US-MAI002-002: Configurar recargos (surcharges) + +**ID:** US-MAI002-002 +**Módulo:** MAI-002 (Tarifas y SLA) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** administrador comercial +**Quiero** configurar una matriz de recargos aplicables a los servicios de transporte +**Para** asegurar que todos los costos adicionales se capturen y facturen correctamente + +--- + +## Criterios de Aceptación + +### CA-001: Catálogo de tipos de recargo +**Dado** que existen diferentes tipos de cargos adicionales +**Cuando** configuro el catálogo +**Entonces** puedo definir: nombre, código, descripción y tipo de cálculo (% o fijo) + +### CA-002: Fuel surcharge con índice +**Dado** que el fuel surcharge varía según el precio del combustible +**Cuando** configuro este recargo +**Entonces** puedo definir un índice actualizable (%) que se aplica sobre la tarifa base + +### CA-003: Demoras (detention) con tolerancia +**Dado** que las demoras en carga/descarga tienen un tiempo de gracia +**Cuando** configuro detention +**Entonces** puedo definir: tolerancia (horas), costo por hora adicional + +### CA-004: Recargos por cliente +**Dado** que algunos clientes tienen recargos específicos +**Cuando** configuro recargos +**Entonces** puedo asignarlos a clientes específicos o dejarlos como generales + +### CA-005: Reglas de aplicación +**Dado** que algunos recargos se aplican automáticamente y otros manualmente +**Cuando** configuro un recargo +**Entonces** puedo definir si es: automático (siempre aplica), condicional (según regla), o manual + +### CA-006: Actualizar índice de combustible +**Dado** que el precio del combustible cambia periódicamente +**Cuando** actualizo el índice +**Entonces** se registra con fecha y el sistema usa el índice vigente para nuevas cotizaciones + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CONFIGURACIÓN DE RECARGOS [+ Nuevo]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ÍNDICE DE COMBUSTIBLE (FUEL SURCHARGE) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Índice actual: 8% │ │ +│ │ Última actualización: 2026-01-15 │ │ +│ │ Próxima revisión: 2026-02-15 │ │ +│ │ [Actualizar]│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ TIPOS DE RECARGO │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ FUEL - Fuel Surcharge │ │ +│ │ Tipo: Porcentaje sobre base │ │ +│ │ Aplicación: Automática │ │ +│ │ Valor actual: 8% [Editar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ DETENTION_CARGA - Demora en carga │ │ +│ │ Tipo: Monto por hora │ │ +│ │ Tolerancia: 2 horas | Costo: $350/hora adicional │ │ +│ │ Aplicación: Condicional (si excede tolerancia) [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ DETENTION_DESCARGA - Demora en descarga │ │ +│ │ Tipo: Monto por hora │ │ +│ │ Tolerancia: 1.5 horas | Costo: $350/hora adicional │ │ +│ │ Aplicación: Condicional (si excede tolerancia) [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ MANIOBRA - Maniobra especial │ │ +│ │ Tipo: Monto fijo │ │ +│ │ Valor: $800.00 │ │ +│ │ Aplicación: Manual [Editar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ REENTREGA - Reentrega/Reexpedición │ │ +│ │ Tipo: Porcentaje sobre base │ │ +│ │ Valor: 30% │ │ +│ │ Aplicación: Manual [Editar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ESCOLTA - Escolta de seguridad │ │ +│ │ Tipo: Monto fijo │ │ +│ │ Valor: $5,000.00 │ │ +│ │ Aplicación: Manual [Editar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ SEGURO_ADICIONAL - Seguro extra │ │ +│ │ Tipo: Porcentaje sobre valor declarado │ │ +│ │ Valor: 0.5% │ │ +│ │ Aplicación: Condicional (si valor > $500K) [Editar] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Editar Recargo + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ EDITAR RECARGO: DETENTION_CARGA ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ INFORMACIÓN BÁSICA │ +│ │ +│ Código: [DETENTION_CARGA] (no editable) │ +│ Nombre: [Demora en carga] │ +│ Descripción: [Cargo por tiempo excedido en punto de carga] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ TIPO DE CÁLCULO │ +│ │ +│ ( ) Porcentaje sobre tarifa base │ +│ ( ) Monto fijo │ +│ (●) Monto por hora/unidad │ +│ ( ) Porcentaje sobre valor declarado │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ CONFIGURACIÓN ESPECÍFICA │ +│ │ +│ Tolerancia: [2] horas (tiempo de gracia) │ +│ Costo por hora adicional: [$350.00] MXN │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ APLICACIÓN │ +│ │ +│ ( ) Automática (siempre se incluye) │ +│ (●) Condicional (se aplica si se cumple regla) │ +│ ( ) Manual (el usuario decide) │ +│ │ +│ Regla: [Tiempo en punto > tolerancia definida] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ALCANCE │ +│ │ +│ (●) General (todos los clientes) │ +│ ( ) Específico: [Seleccionar clientes...] │ +│ │ +│ [Cancelar] [Guardar] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Historial de Índice Fuel + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ HISTORIAL ÍNDICE FUEL SURCHARGE ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Índice actual: 8% │ +│ │ +│ Nuevo índice: [ ] % [Aplicar] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ HISTORIAL │ +│ │ +│ | Fecha | Índice | Usuario | │ +│ |------------|--------|------------------| │ +│ | 2026-01-15 | 8.0% | admin@empresa.mx | │ +│ | 2025-12-15 | 7.5% | admin@empresa.mx | │ +│ | 2025-11-15 | 7.0% | admin@empresa.mx | │ +│ | 2025-10-15 | 7.5% | admin@empresa.mx | │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Catálogo de Recargos + +| Código | Nombre | Cálculo | Aplicación | +|--------|--------|---------|------------| +| FUEL | Fuel Surcharge | % sobre base | Automática | +| DETENTION_CARGA | Demora en carga | $/hora | Condicional | +| DETENTION_DESCARGA | Demora en descarga | $/hora | Condicional | +| MANIOBRA | Maniobra especial | Monto fijo | Manual | +| REENTREGA | Reentrega | % sobre base | Manual | +| ESCOLTA | Escolta seguridad | Monto fijo | Manual | +| SEGURO_ADICIONAL | Seguro extra | % sobre valor | Condicional | +| ALMACENAJE | Almacenaje temporal | $/día | Manual | + +--- + +## Notas Técnicas + +- Tabla: `tipos_recargo` para el catálogo +- Tabla: `indice_combustible` para histórico de fuel surcharge +- Tabla: `recargos_cliente` para configuraciones específicas por cliente +- Los recargos condicionales se evalúan según reglas configurables +- El índice fuel tiene trigger de actualización mensual + +--- + +## Definición de Done + +- [ ] CRUD de tipos de recargo +- [ ] Configuración de fuel surcharge con índice +- [ ] Configuración de detention con tolerancia +- [ ] Recargos por cliente +- [ ] Reglas de aplicación (auto/condicional/manual) +- [ ] Historial de cambios de índice fuel +- [ ] Tests de cálculo de recargos + diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-003.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-003.md new file mode 100644 index 0000000..1e9fecd --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-003.md @@ -0,0 +1,218 @@ +# US-MAI002-003: Definir SLA por cliente + +**ID:** US-MAI002-003 +**Módulo:** MAI-002 (Tarifas y SLA) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** gerente comercial +**Quiero** definir acuerdos de nivel de servicio (SLA) por cliente +**Para** documentar los compromisos de tiempo y las consecuencias por incumplimiento + +--- + +## Criterios de Aceptación + +### CA-001: Crear SLA por cliente +**Dado** que tengo un cliente con contrato +**Cuando** defino su SLA +**Entonces** puedo especificar tiempos comprometidos de pickup y entrega + +### CA-002: Definir tolerancias +**Dado** que los tiempos tienen cierta flexibilidad +**Cuando** configuro el SLA +**Entonces** puedo definir tolerancia (minutos/horas de gracia) antes de considerar incumplimiento + +### CA-003: Configurar penalizaciones +**Dado** que el incumplimiento tiene consecuencias +**Cuando** defino penalizaciones +**Entonces** puedo especificar descuento o cargo (% o monto) por incumplimiento + +### CA-004: Reglas de notificación +**Dado** que queremos prevenir incumplimientos +**Cuando** configuro alertas +**Entonces** puedo definir cuándo notificar (ej: 2 hrs antes de vencer el SLA) + +### CA-005: SLA por servicio/zona +**Dado** que los tiempos varían según la ruta +**Cuando** defino SLA +**Entonces** puedo especificar diferentes tiempos por zona o tipo de servicio + +### CA-006: Dashboard de cumplimiento +**Dado** que necesito monitorear el desempeño +**Cuando** consulto el dashboard +**Entonces** veo el % de cumplimiento de SLA por cliente, periodo y causa de incumplimiento + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ DEFINIR SLA ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ CLIENTE Y ALCANCE │ +│ │ +│ Cliente: [Distribuidora ABC ▼] │ +│ │ +│ Alcance: │ +│ (●) General (todas las rutas) │ +│ ( ) Por zona destino: [Seleccionar zonas...] │ +│ ( ) Por servicio: [Seleccionar servicios...] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ TIEMPOS COMPROMETIDOS │ +│ │ +│ Pickup (tiempo desde solicitud hasta recolección): │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Servicio estándar: [24] horas │ │ +│ │ Servicio express: [6] horas │ │ +│ │ Mismo día: [4] horas │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Entrega (tiempo desde pickup hasta entrega): │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Zona local (<200km): [24] horas │ │ +│ │ Zona regional (200-500km): [48] horas │ │ +│ │ Zona nacional (>500km): [72] horas │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ TOLERANCIAS │ +│ │ +│ Tolerancia pickup: [30] minutos (gracia antes de incumplir) │ +│ Tolerancia entrega: [60] minutos │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ PENALIZACIONES │ +│ │ +│ Por incumplimiento de pickup: │ +│ Tipo: (●) Descuento ( ) Cargo │ +│ Valor: [3] % sobre el servicio │ +│ │ +│ Por incumplimiento de entrega: │ +│ Tipo: (●) Descuento ( ) Cargo │ +│ Valor: [5] % sobre el servicio │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ALERTAS Y NOTIFICACIONES │ +│ │ +│ ☑ Notificar al equipo [2] horas antes de vencer SLA │ +│ ☑ Notificar al cliente cuando SLA está en riesgo │ +│ ☑ Escalar a supervisor si falta [1] hora │ +│ │ +│ [Cancelar] [Guardar SLA] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Dashboard de Cumplimiento + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CUMPLIMIENTO DE SLA │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Periodo: [Enero 2026 ▼] Cliente: [Todos ▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ RESUMEN GENERAL │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 94.2% │ │ 97.1% │ │ 91.3% │ │ +│ │ On-Time │ │ On-Time │ │ OTIF │ │ +│ │ Pickup │ │ Delivery │ │ (Completo) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ POR CLIENTE │ +│ │ +│ | Cliente | Viajes | Pickup | Entrega | OTIF | │ +│ |----------------------|--------|--------|---------|------| │ +│ | Distribuidora ABC | 145 | 96.5% | 98.2% | 94.5%| │ +│ | Comercial XYZ | 89 | 91.0% | 95.5% | 88.7%| │ +│ | Mayorista 123 | 67 | 94.0% | 97.0% | 91.0%| │ +│ | Retail Partners | 52 | 95.2% | 96.1% | 92.3%| │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ CAUSAS DE INCUMPLIMIENTO │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ Demora en carga (cliente) ████████████░░░░░░ 35% │ │ +│ │ Tráfico/accidente ███████░░░░░░░░░░░ 22% │ │ +│ │ Falta de unidad ██████░░░░░░░░░░░░ 18% │ │ +│ │ Rechazo en destino █████░░░░░░░░░░░░░ 15% │ │ +│ │ Problema mecánico ███░░░░░░░░░░░░░░░ 10% │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ [Exportar reporte] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Lista de SLAs + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ACUERDOS DE NIVEL DE SERVICIO (SLA) [+ Nuevo]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Distribuidora ABC │ │ +│ │ Pickup: 24h (estándar) | Entrega: 48h (regional) │ │ +│ │ Penalización: 5% por incumplimiento │ │ +│ │ Cumplimiento actual: 94.5% [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ Comercial XYZ │ │ +│ │ Pickup: 12h (express) | Entrega: 24h (local) │ │ +│ │ Penalización: 3% + $500 fijo │ │ +│ │ Cumplimiento actual: 88.7% [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ SLA POR DEFECTO (clientes sin SLA específico) │ │ +│ │ Pickup: 48h | Entrega: 72h │ │ +│ │ Sin penalización automática │ │ +│ │ [Editar]│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Notas Técnicas + +- Tabla: `sla_clientes` con tiempos y tolerancias +- Tabla: `sla_servicios` para SLA por tipo de servicio +- Vista: `v_cumplimiento_sla` para dashboard +- Trigger de alerta cuando SLA está por vencer +- Las penalizaciones se registran en facturación (MAI-009) + +--- + +## Definición de Done + +- [ ] CRUD de SLA por cliente +- [ ] Configuración de tiempos por zona/servicio +- [ ] Definición de tolerancias +- [ ] Configuración de penalizaciones +- [ ] Sistema de alertas previas +- [ ] Dashboard de cumplimiento de SLA +- [ ] Reporte de causas de incumplimiento +- [ ] Tests de cálculo de cumplimiento + diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-004.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-004.md new file mode 100644 index 0000000..2b70757 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-004.md @@ -0,0 +1,265 @@ +# US-MAI002-004: Generar cotización rápida + +**ID:** US-MAI002-004 +**Módulo:** MAI-002 (Tarifas y SLA) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** ejecutivo de ventas +**Quiero** generar cotizaciones rápidamente con cálculo automático de precios +**Para** responder ágilmente a solicitudes de clientes y cerrar más negocios + +--- + +## Criterios de Aceptación + +### CA-001: Buscar tarifa automáticamente +**Dado** que ingreso origen, destino, tipo de unidad y cliente +**Cuando** solicito cotizar +**Entonces** el sistema encuentra la tarifa vigente más específica (cliente > general) + +### CA-002: Calcular recargos automáticos +**Dado** que hay recargos configurados como automáticos +**Cuando** se genera la cotización +**Entonces** el sistema aplica: fuel surcharge, y otros recargos automáticos + +### CA-003: Agregar recargos manuales +**Dado** que el servicio requiere cargos adicionales +**Cuando** configuro la cotización +**Entonces** puedo agregar manualmente: maniobras, escolta, seguro adicional, etc. + +### CA-004: Mostrar desglose de precio +**Dado** que el cliente necesita ver el detalle +**Cuando** genero la cotización +**Entonces** muestra: tarifa base, cada recargo con su monto, subtotal, descuento (si aplica), total + +### CA-005: Aplicar descuento +**Dado** que puedo ofrecer un descuento +**Cuando** aplico un porcentaje +**Entonces** si está dentro de mi límite se aplica; si excede, se envía a aprobación + +### CA-006: Generar PDF profesional +**Dado** que necesito enviar la cotización al cliente +**Cuando** solicito el PDF +**Entonces** genera un documento con logo, desglose, vigencia y condiciones + +### CA-007: Convertir a OT +**Dado** que el cliente acepta la cotización +**Cuando** selecciono "Convertir a OT" +**Entonces** se crea la OT con el snapshot de tarifa aplicada + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ NUEVA COTIZACIÓN ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ PASO 1: INFORMACIÓN DEL SERVICIO │ +│ │ +│ Cliente: [Distribuidora ABC ▼] [+ Nuevo] │ +│ Contacto: [Juan Pérez - Logística ▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ Origen: [Ciudad de México - Bodega Norte ] 📍 │ +│ Destino: [Guadalajara - Centro Distribución ] 📍 │ +│ │ +│ Distancia estimada: 540 km (automático) │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ Tipo de unidad: [Tractocamión - Caja seca 53' ▼] │ +│ Modalidad: (●) FTL ( ) LTL │ +│ Servicio: (●) Estándar ( ) Express ( ) Mismo día │ +│ │ +│ [Buscar Tarifa] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Resultado de Tarifa + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ COTIZACIÓN - PASO 2: PRECIO ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ TARIFA ENCONTRADA │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ✓ Tarifa específica para Distribuidora ABC │ │ +│ │ Lane: CDMX → GDL (Zona Centro) │ │ +│ │ Vigencia: 01-ene-2026 al 31-dic-2026 │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ DESGLOSE DE PRECIO │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Tarifa base (FTL Caja seca CDMX→GDL) $11,800.00 │ │ +│ │ │ │ +│ │ RECARGOS AUTOMÁTICOS: │ │ +│ │ + Fuel Surcharge (8%) $944.00 │ │ +│ │ │ │ +│ │ RECARGOS OPCIONALES: │ │ +│ │ ☐ Maniobra de carga $800.00 │ │ +│ │ ☐ Maniobra de descarga $800.00 │ │ +│ │ ☑ Seguro adicional (0.5% sobre $500K) $250.00 │ │ +│ │ ☐ Escolta de seguridad $5,000.00 │ │ +│ │ │ │ +│ │ ───────────────────────────────────────────────────── │ │ +│ │ Subtotal $12,994.00 │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ DESCUENTO │ +│ │ +│ Aplicar descuento: ☑ │ +│ Porcentaje: [5] % = $649.70 │ +│ ✓ Dentro de tu límite autorizado (hasta 5%) │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ TOTAL COTIZACIÓN: $12,344.30 MXN │ +│ │ +│ [← Volver] [Generar Cotización] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Cotización Generada + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ COTIZACIÓN COT-2026-00456 ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ [LOGO EMPRESA] │ │ +│ │ │ │ +│ │ COTIZACIÓN DE SERVICIO DE TRANSPORTE │ │ +│ │ No. COT-2026-00456 │ │ +│ │ Fecha: 27 de enero de 2026 │ │ +│ │ Vigencia: 7 días (hasta 03-feb-2026) │ │ +│ │ │ │ +│ │ CLIENTE │ │ +│ │ Distribuidora ABC S.A. de C.V. │ │ +│ │ Atención: Juan Pérez - Logística │ │ +│ │ │ │ +│ │ SERVICIO │ │ +│ │ Origen: CDMX - Bodega Norte │ │ +│ │ Destino: Guadalajara - Centro Distribución │ │ +│ │ Distancia: 540 km │ │ +│ │ Equipo: Tractocamión Caja seca 53' │ │ +│ │ Modalidad: FTL (Carga completa) │ │ +│ │ Servicio: Estándar (24-48 hrs) │ │ +│ │ │ │ +│ │ DESGLOSE │ │ +│ │ Tarifa base $11,800.00 │ │ +│ │ Fuel Surcharge (8%) $944.00 │ │ +│ │ Seguro adicional $250.00 │ │ +│ │ Subtotal $12,994.00 │ │ +│ │ Descuento (5%) -$649.70 │ │ +│ │ ───────────────────────────────────────────── │ │ +│ │ TOTAL $12,344.30 MXN │ │ +│ │ (Doce mil trescientos cuarenta y cuatro pesos 30/100) │ │ +│ │ │ │ +│ │ CONDICIONES │ │ +│ │ • Tiempo de entrega: 24-48 horas hábiles │ │ +│ │ • No incluye maniobras de carga/descarga │ │ +│ │ • Seguro incluido hasta $500,000 MXN │ │ +│ │ • Precio + IVA (16%) │ │ +│ │ │ │ +│ │ Cotización válida por 7 días. │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ [Descargar PDF] [Enviar por Email] [Convertir a OT] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Lista de Cotizaciones + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ COTIZACIONES [+ Nueva]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Filtros: [Este mes ▼] [Todos los estados ▼] [Mi equipo ▼] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ COT-2026-00456 | Distribuidora ABC │ │ +│ │ CDMX → GDL | $12,344.30 MXN │ │ +│ │ Creada: 27-ene-2026 | Vigencia: 03-feb-2026 │ │ +│ │ Estado: ⏳ PENDIENTE [Ver] [Convertir a OT] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ COT-2026-00455 | Comercial XYZ │ │ +│ │ MTY → CDMX | $18,500.00 MXN │ │ +│ │ Creada: 26-ene-2026 | Vigencia: 02-feb-2026 │ │ +│ │ Estado: ✅ ACEPTADA → OT-2026-00234 [Ver] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ COT-2026-00454 | Mayorista 123 │ │ +│ │ GDL → TIJ | $45,000.00 MXN │ │ +│ │ Creada: 25-ene-2026 | Vigencia: 01-feb-2026 │ │ +│ │ Estado: ❌ RECHAZADA (precio alto) [Ver] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Resumen: 15 pendientes | 8 aceptadas | 3 rechazadas | 2 vencidas│ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Estados de Cotización + +| Estado | Descripción | +|--------|-------------| +| BORRADOR | En proceso de creación | +| PENDIENTE | Enviada al cliente, esperando respuesta | +| ACEPTADA | Cliente aceptó, convertida a OT | +| RECHAZADA | Cliente rechazó | +| VENCIDA | Pasó la fecha de vigencia sin respuesta | +| CANCELADA | Anulada por el vendedor | + +--- + +## Notas Técnicas + +- Tabla: `cotizaciones` con snapshot de tarifa aplicada +- Tabla: `cotizacion_detalle` para el desglose +- Tabla: `snapshot_tarifa` para guardar la tarifa al momento de cotizar +- Generación de PDF con template HTML + puppeteer +- Conversión a OT crea la orden con los mismos datos + +--- + +## Definición de Done + +- [ ] Búsqueda de tarifa por lane/cliente +- [ ] Cálculo automático de recargos +- [ ] Agregar recargos manuales +- [ ] Desglose completo de precio +- [ ] Aplicación de descuento con validación +- [ ] Generación de PDF profesional +- [ ] Envío por email +- [ ] Conversión a OT +- [ ] Gestión de estados (pendiente, aceptada, etc.) +- [ ] Tests de cálculo de precios + diff --git a/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-005.md b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-005.md new file mode 100644 index 0000000..5a79bb0 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-002-tarifas-sla/historias-usuario/US-MAI002-005.md @@ -0,0 +1,268 @@ +# US-MAI002-005: Aprobar descuento excepcional + +**ID:** US-MAI002-005 +**Módulo:** MAI-002 (Tarifas y SLA) +**Prioridad:** Media +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** gerente comercial +**Quiero** aprobar o rechazar solicitudes de descuentos que excedan los límites autorizados +**Para** mantener control sobre los márgenes y evitar erosión de rentabilidad + +--- + +## Criterios de Aceptación + +### CA-001: Definir políticas de descuento +**Dado** que necesito establecer límites por rol +**Cuando** configuro las políticas +**Entonces** puedo definir: rol, % máximo permitido, monto máximo, y si requiere aprobación + +### CA-002: Solicitud automática de aprobación +**Dado** que un vendedor aplica un descuento que excede su límite +**Cuando** intenta guardar la cotización +**Entonces** el sistema genera automáticamente una solicitud de aprobación + +### CA-003: Notificación al aprobador +**Dado** que hay una solicitud pendiente +**Cuando** se crea +**Entonces** el aprobador recibe notificación (email, app, dashboard) + +### CA-004: Aprobar con justificación +**Dado** que soy aprobador y reviso una solicitud +**Cuando** decido aprobar +**Entonces** debo registrar una justificación y la solicitud queda aprobada + +### CA-005: Rechazar con motivo +**Dado** que soy aprobador y la solicitud no procede +**Cuando** decido rechazar +**Entonces** registro el motivo y el vendedor es notificado + +### CA-006: Escalamiento automático +**Dado** que el descuento excede el límite de mi nivel de aprobación +**Cuando** apruebo parcialmente o escalo +**Entonces** la solicitud sube al siguiente nivel (supervisor → gerente → director) + +### CA-007: Auditoría de aprobaciones +**Dado** que necesito revisar el histórico +**Cuando** consulto el reporte +**Entonces** veo todas las aprobaciones/rechazos con fecha, usuario, justificación y monto + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ POLÍTICAS DE DESCUENTO [+ Nueva]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ LÍMITES POR ROL │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Vendedor Junior │ │ +│ │ Límite: hasta 3% o $500 MXN (lo que sea menor) │ │ +│ │ Aprobador: Vendedor Senior [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ Vendedor Senior │ │ +│ │ Límite: hasta 5% o $2,000 MXN │ │ +│ │ Aprobador: Gerente Comercial [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ Gerente Comercial │ │ +│ │ Límite: hasta 10% o $10,000 MXN │ │ +│ │ Aprobador: Director Comercial [Editar]│ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ Director Comercial │ │ +│ │ Límite: hasta 15% o $50,000 MXN │ │ +│ │ Aprobador: CEO (nivel final) [Editar]│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ REGLAS ADICIONALES │ +│ │ +│ ☑ Descuento > 10% siempre requiere justificación escrita │ +│ ☑ Descuento > $5,000 requiere aprobación de Finanzas │ +│ ☑ Cliente nuevo: límite reducido 50% (primeros 3 meses) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Solicitud de Aprobación (Vendedor) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SOLICITAR APROBACIÓN DE DESCUENTO ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ⚠ El descuento solicitado excede tu límite autorizado │ +│ │ +│ Tu límite: 5% ($2,000 MXN) │ +│ Descuento solicitado: 8% ($1,039.52) │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ DETALLE DE LA COTIZACIÓN │ +│ │ +│ Cotización: COT-2026-00457 │ +│ Cliente: Distribuidora ABC │ +│ Servicio: CDMX → GDL | $12,994.00 │ +│ Descuento solicitado: 8% = $1,039.52 │ +│ Total con descuento: $11,954.48 │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ JUSTIFICACIÓN (Obligatoria) │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Cliente estratégico con 3 años de relación. Están │ │ +│ │ evaluando cotización de competidor con precio similar. │ │ +│ │ Potencial de 15 viajes mensuales si ganamos la cuenta. │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Aprobador: María González (Gerente Comercial) │ +│ │ +│ [Cancelar] [Enviar Solicitud] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Bandeja de Aprobaciones (Gerente) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ APROBACIONES PENDIENTES (3) │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 🔴 URGENTE | Hace 15 min │ │ +│ │ │ │ +│ │ Solicitante: Pedro Ramírez (Vendedor Senior) │ │ +│ │ Cotización: COT-2026-00457 │ │ +│ │ Cliente: Distribuidora ABC │ │ +│ │ Descuento: 8% ($1,039.52) │ │ +│ │ │ │ +│ │ Justificación: │ │ +│ │ "Cliente estratégico con 3 años de relación. Están │ │ +│ │ evaluando cotización de competidor..." │ │ +│ │ │ │ +│ │ [Ver cotización completa] │ │ +│ │ │ │ +│ │ [❌ Rechazar] [⬆ Escalar] [✓ Aprobar] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 🟡 NORMAL | Hace 2 horas │ │ +│ │ │ │ +│ │ Solicitante: Ana López (Vendedor Junior) │ │ +│ │ Cotización: COT-2026-00455 │ │ +│ │ Cliente: Comercial XYZ │ │ +│ │ Descuento: 5% ($925.00) │ │ +│ │ │ │ +│ │ [Ver detalle] [❌ Rechazar] [✓ Aprobar] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Diálogo de Aprobación + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ APROBAR DESCUENTO ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Cotización: COT-2026-00457 │ +│ Descuento solicitado: 8% ($1,039.52) │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ DECISIÓN │ +│ │ +│ (●) Aprobar el descuento solicitado (8%) │ +│ ( ) Aprobar parcialmente: [____] % │ +│ ( ) Rechazar │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ COMENTARIO (Obligatorio) │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Aprobado. Cliente estratégico, el volumen proyectado │ │ +│ │ justifica el descuento. Revisar margen al cierre del │ │ +│ │ trimestre. │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ [Cancelar] [Confirmar] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Reporte de Auditoría + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ AUDITORÍA DE DESCUENTOS │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Periodo: [Enero 2026 ▼] │ +│ │ +│ RESUMEN │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ 23 │ │ 18 │ │ 3 │ │ 2 │ │ +│ │ Solicitudes│ │ Aprobadas │ │ Rechazadas │ │ Pendientes │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ Monto total aprobado: $45,230.00 │ +│ Descuento promedio: 6.2% │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ DETALLE │ +│ │ +│ | Fecha | Cotización | Solicitante | % | Monto | Estado |│ +│ |--------|------------|-------------|-----|---------|--------|│ +│ | 27-ene | COT-00457 | P. Ramírez | 8% | $1,039 | ✓ Apr. |│ +│ | 26-ene | COT-00455 | A. López | 5% | $925 | ✓ Apr. |│ +│ | 25-ene | COT-00452 | J. García | 12% | $3,500 | ❌ Rech.|│ +│ | 24-ene | COT-00448 | P. Ramírez | 6% | $780 | ✓ Apr. |│ +│ │ +│ [Exportar a Excel] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Notas Técnicas + +- Tabla: `politicas_descuento` con límites por rol +- Tabla: `solicitudes_aprobacion` con estado (pendiente, aprobada, rechazada) +- Tabla: `aprobaciones` con detalle de cada decisión +- Notificaciones vía módulo de notificaciones (erp-core) +- Auditoría completa con usuario, fecha y justificación + +--- + +## Definición de Done + +- [ ] CRUD de políticas de descuento +- [ ] Generación automática de solicitud si excede límite +- [ ] Notificación a aprobadores +- [ ] Flujo de aprobación/rechazo con justificación +- [ ] Escalamiento a siguiente nivel +- [ ] Reporte de auditoría de descuentos +- [ ] Tests de flujo de aprobación +- [ ] Tests de escalamiento + diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/README.md b/docs/02-definicion-modulos/MAI-004-planeacion/README.md new file mode 100644 index 0000000..7daba31 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/README.md @@ -0,0 +1,210 @@ +# MAI-004: Planeación TMS + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Estado:** Diseño +**Prioridad:** P0 (Crítico - Workflow principal) + +--- + +## Descripción General + +El módulo de Planeación TMS (Transportation Management System) es responsable de convertir las Órdenes de Transporte en embarques y viajes factibles, optimizando la asignación de recursos (unidades, operadores, remolques) según capacidad, ventanas de tiempo y restricciones. + +**Problema que resuelve:** +- Asignación manual ineficiente de recursos +- Subutilización de capacidad de unidades +- Incumplimiento de ventanas de entrega +- Falta de visibilidad de disponibilidad de flota + +--- + +## Objetivos del Módulo + +1. **Consolidación:** Agrupar OTs compatibles en embarques para optimizar capacidad +2. **Asignación:** Seleccionar la mejor combinación unidad-operador-remolque +3. **Validación:** Verificar que los recursos cumplen requisitos del servicio +4. **Visibilidad:** Tablero de planeación con vista de recursos y OTs pendientes + +--- + +## Alcance Funcional + +### Incluido + +- Tablero de planeación (vista Gantt/Kanban) +- Consolidación de OTs en embarques +- Cálculo de capacidad por unidad +- Pre-asignación de recursos +- Validación de compatibilidad operador-unidad-cliente +- Estimación de ETA inicial +- Generación de viajes planificados + +### Excluido + +- Optimización automática de rutas (MAA-019) +- Despacho y liberación de viaje (MAI-005) +- Tracking en tiempo real (MAI-006) + +--- + +## Actores + +| Actor | Rol en el módulo | +|-------|------------------| +| Planner/Tráfico | Usuario principal, planifica y asigna | +| Jefe de Flota | Consulta disponibilidad, bloquea recursos | +| Ventas | Consulta capacidad para compromisos | +| Sistema | Sugiere consolidaciones automáticas | + +--- + +## Flujo Principal + +``` +OTs CONFIRMADAS + │ + ▼ +┌─────────────────────────────────────────┐ +│ 1. TABLERO DE PLANEACIÓN │ +│ - Vista por fecha/región/cliente │ +│ - OTs pendientes de asignar │ +│ - Recursos disponibles │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 2. CONSOLIDACIÓN │ +│ - Sistema sugiere agrupaciones │ +│ - Por zona, ventana, tipo equipo │ +│ - Planner acepta/modifica │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 3. VALIDACIÓN DE CAPACIDAD │ +│ - Peso vs capacidad unidad │ +│ - Volumen vs metros cúbicos │ +│ - Pallets vs posiciones │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 4. ASIGNACIÓN DE RECURSOS │ +│ - Seleccionar unidad disponible │ +│ - Seleccionar operador calificado │ +│ - Seleccionar remolque compatible │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 5. VALIDACIONES │ +│ ✓ Operador con licencia vigente │ +│ ✓ Unidad con documentos OK │ +│ ✓ Cumple requisitos del cliente │ +│ ✓ No hay conflicto de horarios │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 6. VIAJE PLANIFICADO │ +│ - Estado: PLANIFICADO │ +│ - Listo para despacho (MAI-005) │ +└─────────────────────────────────────────┘ +``` + +--- + +## Datos del Módulo + +### Entidades Principales + +| Entidad | Descripción | Estado | +|---------|-------------|--------| +| Embarque | Agrupación de OTs | NO IMPLEMENTADA | +| Viaje | Ejecución planificada | NO IMPLEMENTADA | +| AsignacionRecurso | Reserva de unidad/operador | NO IMPLEMENTADA | +| CapacidadUnidad | Configuración de capacidad | NO IMPLEMENTADA | +| ReglaAsignacion | Criterios de compatibilidad | NO IMPLEMENTADA | + +### Campos Clave Viaje + +| Campo | Tipo | Obligatorio | Descripción | +|-------|------|-------------|-------------| +| embarque_id | UUID | Sí | Embarque asociado | +| unidad_id | UUID | Sí | Unidad asignada | +| operador_id | UUID | Sí | Operador asignado | +| remolque_id | UUID | No | Remolque si aplica | +| fecha_salida_planificada | TIMESTAMP | Sí | Salida estimada | +| fecha_llegada_planificada | TIMESTAMP | Sí | Llegada estimada | +| status | ENUM | Sí | PLANIFICADO, DESPACHADO, etc. | + +--- + +## Requerimientos Funcionales + +Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md) + +--- + +## Métricas del Módulo + +| KPI | Fórmula | Meta | +|-----|---------|------| +| Utilización flota | % unidades en viaje | >75% | +| Fill rate | Capacidad usada vs disponible | >85% | +| Planificación exitosa | % OTs asignadas vs recibidas | >95% | +| Tiempo de planeación | Promedio minutos por viaje | <15 min | + +--- + +## Dependencias + +### Este módulo depende de: +- MAI-003 (OT): Recibe órdenes confirmadas +- MAI-011 (Flota): Consulta disponibilidad de recursos +- MAI-002 (Tarifas): Restricciones del cliente + +### Otros módulos dependen de este: +- MAI-005 (Despacho): Recibe viajes planificados +- MAI-006 (Tracking): Inicia seguimiento del viaje + +--- + +## Consideraciones Técnicas + +### Performance +- Consulta de disponibilidad debe responder en <2 segundos +- Tablero debe manejar 500+ OTs sin degradación +- Cálculo de consolidación en background + +### Integraciones +- Consulta de distancias/tiempos vía API de mapas +- Sincronización con calendario de operadores +- Webhook a notificaciones cuando se asigna recurso + +--- + +## Historias de Usuario + +Ver carpeta: [historias-usuario/](./historias-usuario/) + +| US | Título | Prioridad | +|----|--------|-----------| +| US-MAI004-001 | Ver tablero de planeación | Alta | +| US-MAI004-002 | Consolidar OTs en embarque | Alta | +| US-MAI004-003 | Asignar unidad a viaje | Alta | +| US-MAI004-004 | Validar compatibilidad de recursos | Alta | +| US-MAI004-005 | Calcular ETA inicial | Media | + +--- + +## Referencias + +- REQ-GIRO-TRANSPORTISTA.md - Sección 4.3 +- MATRIZ-COHERENCIA-DDL-BACKEND.yml +- MAPEO-RF-GIRO-A-MODULOS.yml + +--- + +*Módulo MAI-004 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md b/docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md new file mode 100644 index 0000000..c84404f --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md @@ -0,0 +1,223 @@ +# REQUERIMIENTOS.md - MAI-004: Planeación TMS + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.3 + +--- + +## Requerimientos Funcionales + +### RF-4.3.1: Tablero de Planeación + +**Descripción:** +El sistema debe proveer un tablero visual (Gantt/Kanban) para ver OTs por fecha, ventana, estado, prioridad y región. + +**Criterios de Aceptación:** +1. Vista Gantt muestra línea de tiempo con OTs y viajes +2. Vista Kanban muestra OTs por estado (Pendiente, Asignada, Planificada) +3. Filtros por: fecha, cliente, región, tipo de servicio, prioridad +4. Drag & drop para mover OTs entre fechas/recursos +5. Indicadores visuales de urgencia (SLA próximo a vencer) +6. Panel lateral con detalle de OT seleccionada +7. Vista de recursos disponibles por fecha + +**Mapeo a DDL:** +- Tabla: `ordenes_transporte`, `viajes`, `embarques` +- Vista: `v_tablero_planeacion` + +**Endpoints Requeridos:** +- `GET /api/v1/planeacion/tablero` - Datos del tablero +- `GET /api/v1/planeacion/recursos-disponibles` - Recursos por fecha +- `PUT /api/v1/ot/:id/fecha-planificada` - Mover OT de fecha + +**Prioridad:** Alta + +--- + +### RF-4.3.2: Consolidación Automática Sugerida + +**Descripción:** +El sistema debe sugerir agrupaciones de OTs compatibles por zona, ventana de tiempo, capacidad y tipo de equipo. + +**Criterios de Aceptación:** +1. Al seleccionar múltiples OTs, el sistema sugiere si son consolidables +2. Criterios de consolidación configurables: + - Misma zona de origen + - Zona de destino cercana (radio configurable) + - Ventanas de tiempo compatibles (overlap) + - Mismo tipo de equipo requerido +3. El sistema calcula capacidad total vs disponible +4. El planner puede aceptar, modificar o rechazar sugerencia +5. Se crea embarque al aceptar consolidación + +**Mapeo a DDL:** +- Tabla: `embarques` +- Campos: ot_ids[], capacidad_total, tipo_equipo + +**Endpoints Requeridos:** +- `POST /api/v1/planeacion/sugerir-consolidacion` - Analizar OTs +- `POST /api/v1/embarques` - Crear embarque +- `PUT /api/v1/embarques/:id/agregar-ot` - Añadir OT a embarque + +**Prioridad:** Alta + +--- + +### RF-4.3.3: Cálculo de Capacidad + +**Descripción:** +El sistema debe validar que la carga no exceda capacidad de la unidad por peso, volumen, pallets y altura. + +**Criterios de Aceptación:** +1. Cada unidad tiene configurada su capacidad: + - Peso máximo (toneladas) + - Volumen máximo (m³) + - Posiciones de pallet + - Altura máxima de carga +2. Al asignar OT/embarque, el sistema valida: + - Suma de pesos ≤ capacidad peso + - Suma de volúmenes ≤ capacidad volumen + - Suma de pallets ≤ posiciones +3. Alerta si se excede 90% de capacidad +4. Bloquea si se excede 100% +5. Considera restricciones especiales (temperatura, peligrosidad) + +**Mapeo a DDL:** +- Tabla: `unidades` campos capacidad_* +- Tabla: `ordenes_transporte` campos peso, volumen, pallets + +**Endpoints Requeridos:** +- `GET /api/v1/unidades/:id/capacidad` - Consultar capacidad +- `POST /api/v1/planeacion/validar-capacidad` - Validar asignación + +**Prioridad:** Alta + +--- + +### RF-4.3.4: Reservas de Recursos + +**Descripción:** +El sistema debe permitir pre-asignar unidad, operador y remolque con bloqueo de disponibilidad. + +**Criterios de Aceptación:** +1. Al asignar recurso, se crea reserva con: + - Fecha/hora inicio y fin estimados + - Estado: RESERVADO +2. El recurso no aparece disponible para otras asignaciones +3. La reserva puede cancelarse liberando el recurso +4. Conflictos de horario se detectan y alertan +5. Vista de calendario por recurso muestra reservas + +**Mapeo a DDL:** +- Tabla: `asignaciones` +- Campos: recurso_tipo, recurso_id, viaje_id, fecha_inicio, fecha_fin, status + +**Endpoints Requeridos:** +- `POST /api/v1/asignaciones` - Crear reserva +- `DELETE /api/v1/asignaciones/:id` - Cancelar reserva +- `GET /api/v1/recursos/:tipo/:id/calendario` - Ver calendario + +**Prioridad:** Alta + +--- + +### RF-4.3.5: Reglas de Compatibilidad + +**Descripción:** +El sistema debe validar que el recurso asignado cumple requisitos del servicio y del cliente. + +**Criterios de Aceptación:** +1. Validaciones de operador: + - Licencia tipo requerido vigente + - Certificaciones especiales (hazmat, doble articulado) + - No está en lista negra del cliente + - Horas de servicio disponibles +2. Validaciones de unidad: + - Tipo de equipo correcto (caja seca, refrigerada, plataforma) + - Documentos vigentes (verificación, seguro, permiso SCT) + - Cumple requisitos de cliente (GPS, antigüedad máxima) +3. El sistema bloquea asignación si no cumple +4. Opción de override con justificación (supervisor) + +**Mapeo a DDL:** +- Tabla: `reglas_asignacion` +- Tabla: `requisitos_cliente` + +**Endpoints Requeridos:** +- `POST /api/v1/planeacion/validar-compatibilidad` - Validar reglas +- `GET /api/v1/clientes/:id/requisitos` - Requisitos del cliente + +**Prioridad:** Alta + +--- + +### RF-4.3.6: Simulación de Ruta y ETA + +**Descripción:** +El sistema debe calcular estimación de tiempos y ETAs basado en distancias y velocidades promedio. + +**Criterios de Aceptación:** +1. Cálculo de distancia entre origen y destinos +2. Estimación de tiempo de tránsito: + - Velocidad promedio por tipo de vía + - Paradas programadas (descansos, combustible) + - Ventanas de carga/descarga +3. ETA por cada parada del itinerario +4. Comparación ETA vs ventana comprometida (SLA) +5. Alerta si ETA > ventana permitida + +**Mapeo a DDL:** +- Tabla: `eta_calculado` +- Campos: viaje_id, parada_id, eta_llegada, eta_salida + +**Endpoints Requeridos:** +- `POST /api/v1/planeacion/calcular-eta` - Calcular ETAs +- `GET /api/v1/viajes/:id/itinerario` - Ver itinerario con ETAs + +**Prioridad:** Media + +--- + +## Requerimientos No Funcionales + +### RNF-001: Performance Tablero +El tablero debe cargar en menos de 3 segundos con 500 OTs visibles. + +### RNF-002: Concurrencia +Múltiples planners pueden trabajar simultáneamente sin conflictos de asignación. + +### RNF-003: Tiempo Real +Los cambios de disponibilidad deben reflejarse en menos de 5 segundos. + +### RNF-004: Usabilidad +El flujo de asignación completo debe completarse en menos de 5 clics. + +--- + +## Validaciones de Negocio + +| Validación | Descripción | Acción si falla | +|------------|-------------|-----------------| +| PLN_001 | Capacidad no excedida | Bloquear asignación | +| PLN_002 | Operador con licencia vigente | Bloquear asignación | +| PLN_003 | Unidad con documentos OK | Bloquear asignación | +| PLN_004 | Sin conflicto de horarios | Alertar, permitir override | +| PLN_005 | ETA dentro de SLA | Alertar, permitir continuar | + +--- + +## Matriz de Trazabilidad + +| RF | Tabla DDL | Entity | Endpoint | US | +|----|-----------|--------|----------|---| +| RF-4.3.1 | v_tablero_planeacion | - | GET /planeacion/tablero | US-MAI004-001 | +| RF-4.3.2 | embarques | Embarque | POST /embarques | US-MAI004-002 | +| RF-4.3.3 | unidades | Unidad | POST /validar-capacidad | US-MAI004-003 | +| RF-4.3.4 | asignaciones | AsignacionRecurso | POST /asignaciones | US-MAI004-003 | +| RF-4.3.5 | reglas_asignacion | ReglaAsignacion | POST /validar-compatibilidad | US-MAI004-004 | +| RF-4.3.6 | eta_calculado | ETACalculado | POST /calcular-eta | US-MAI004-005 | + +--- + +*MAI-004 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/RESUMEN-EPICA.md b/docs/02-definicion-modulos/MAI-004-planeacion/RESUMEN-EPICA.md new file mode 100644 index 0000000..dfd457e --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/RESUMEN-EPICA.md @@ -0,0 +1,191 @@ +# RESUMEN-EPICA.md - MAI-004: Planeación TMS + +**Código:** MAI-004 +**Nombre:** Planeación TMS +**Version:** 1.0.0 +**Fecha:** 2026-01-27 + +--- + +## Valor de Negocio + +### Problema + +Las empresas transportistas enfrentan: +- Asignación manual que consume horas de trabajo +- Unidades viajando con capacidad subutilizada +- Incumplimiento de ventanas por mala planeación +- Falta de visibilidad de recursos disponibles +- Operadores asignados sin validar requisitos + +### Solución + +Un módulo TMS que: +- Centraliza la planeación en un tablero visual +- Sugiere consolidaciones para maximizar capacidad +- Valida automáticamente compatibilidad de recursos +- Calcula ETAs para anticipar problemas + +### Beneficios Esperados + +| Beneficio | Métrica | Impacto | +|-----------|---------|---------| +| Mejor utilización | +20% fill rate | Más ingresos por viaje | +| Menos incumplimientos | -50% SLA missed | Retención clientes | +| Productividad planner | -40% tiempo planeación | Costos operativos | +| Menos errores | -80% asignaciones inválidas | Evita sanciones | + +--- + +## Actores y Stakeholders + +### Usuarios Primarios + +| Actor | Responsabilidad | Frecuencia | +|-------|-----------------|------------| +| Planner/Tráfico | Planifica y asigna recursos | Continuo | +| Jefe de Flota | Gestiona disponibilidad | Diario | +| Supervisor | Aprueba excepciones | Bajo demanda | + +### Usuarios Secundarios + +| Actor | Interés | +|-------|---------| +| Ventas | Consulta capacidad para compromisos | +| Despacho | Recibe viajes planificados | +| Gerencia | Métricas de utilización | + +--- + +## Flujo Principal + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ OTs CONFIRMADAS PARA PLANIFICAR │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 1. TABLERO DE PLANEACIÓN │ +│ │ +│ ┌──────────────────┐ ┌──────────────────────────────────┐ │ +│ │ OTs Pendientes │ │ GANTT / CALENDARIO │ │ +│ │ │ │ │ │ +│ │ □ OT-001 CDMX │ │ Lun Mar Mie Jue Vie │ │ +│ │ □ OT-002 GDL │ │ ════ ════ ════ ════ ════ │ │ +│ │ □ OT-003 MTY │ │ U-01 ▓▓▓▓ ░░░░ ▓▓▓▓ │ │ +│ │ □ OT-004 CDMX │ │ U-02 ▓▓▓▓▓▓▓▓▓ │ │ +│ │ │ │ U-03 ░░░░░░░░░░░░ │ │ +│ └──────────────────┘ └──────────────────────────────────┘ │ +│ │ +│ [Seleccionar OTs] [Sugerir Consolidación] [Asignar] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 2. CONSOLIDACIÓN │ +│ │ +│ Sistema detecta OTs consolidables: │ +│ • OT-001 y OT-004: Mismo origen (CDMX), destinos cercanos │ +│ • Ventanas compatibles: 8:00-12:00 y 10:00-14:00 │ +│ • Capacidad combinada: 12 ton (Unidad: 18 ton) ✓ │ +│ │ +│ [Crear Embarque EMB-001] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 3. ASIGNACIÓN DE RECURSOS │ +│ │ +│ Embarque: EMB-001 (OT-001 + OT-004) │ +│ │ +│ Unidad: [U-05 Kenworth T680 ▼] ✓ Disponible │ +│ Operador: [Juan Pérez García ▼] ✓ Licencia OK │ +│ Remolque: [R-12 Caja Seca 53' ▼] ✓ Documentos OK │ +│ │ +│ Validaciones: │ +│ ✓ Capacidad: 12/18 ton (67%) │ +│ ✓ Operador autorizado para cliente │ +│ ✓ Unidad cumple requisitos GPS │ +│ ✓ Sin conflicto de horarios │ +│ │ +│ [Cancelar] [Crear Viaje Planificado] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ VIAJE VJE-001 PLANIFICADO │ +│ │ +│ Fecha salida: 2026-01-28 06:00 │ +│ ETA Destino 1: 2026-01-28 10:30 │ +│ ETA Destino 2: 2026-01-28 14:00 │ +│ │ +│ → Listo para Despacho (MAI-005) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Criterios de Éxito + +### Funcionales + +- [ ] Tablero carga en <3 segundos +- [ ] Sugerencia de consolidación funciona correctamente +- [ ] Validaciones bloquean asignaciones inválidas +- [ ] ETA calculado con precisión ±30 minutos + +### Técnicos + +- [ ] Soporte para 500+ OTs en tablero +- [ ] Concurrencia sin conflictos +- [ ] Integración con API de mapas +- [ ] Cache de disponibilidad + +### Negocio + +- [ ] >75% utilización de flota +- [ ] >85% fill rate promedio +- [ ] <15 minutos por asignación +- [ ] <5% asignaciones con override + +--- + +## Riesgos y Mitigaciones + +| Riesgo | Probabilidad | Impacto | Mitigación | +|--------|--------------|---------|------------| +| Performance tablero | Media | Alto | Paginación, lazy loading | +| Conflictos concurrencia | Media | Alto | Bloqueo optimista | +| Datos de capacidad incorrectos | Baja | Alto | Validación en carga | +| API mapas no disponible | Baja | Medio | Cache de distancias | + +--- + +## Dependencias + +### Prerequisitos +- MAI-003 (OT): OTs confirmadas disponibles +- MAI-011 (Flota): Datos de unidades y operadores +- MAI-002 (Tarifas): Requisitos del cliente + +### Habilita +- MAI-005 (Despacho): Viajes planificados para despachar +- MAI-006 (Tracking): Inicio de seguimiento + +--- + +## Story Points Estimados + +| Historia | Complejidad | SP | +|----------|-------------|---| +| US-MAI004-001 | Alta | 13 | +| US-MAI004-002 | Alta | 8 | +| US-MAI004-003 | Alta | 8 | +| US-MAI004-004 | Media | 5 | +| US-MAI004-005 | Media | 5 | +| **Total** | | **39** | + +--- + +*Épica MAI-004 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-001.md b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-001.md new file mode 100644 index 0000000..4946dcf --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-001.md @@ -0,0 +1,96 @@ +# US-MAI004-001: Ver tablero de planeación + +**ID:** US-MAI004-001 +**Módulo:** MAI-004 (Planeación TMS) +**Prioridad:** Alta +**Story Points:** 13 + +--- + +## Historia de Usuario + +**Como** planner de tráfico +**Quiero** ver un tablero visual con todas las OTs pendientes y recursos disponibles +**Para** planificar eficientemente las asignaciones del día + +--- + +## Criterios de Aceptación + +### CA-001: Vista Gantt +**Dado** que accedo al módulo de planeación +**Cuando** selecciono vista Gantt +**Entonces** veo una línea de tiempo con unidades en filas y días en columnas, mostrando viajes programados + +### CA-002: Vista Kanban +**Dado** que prefiero organizar por estado +**Cuando** selecciono vista Kanban +**Entonces** veo columnas: Pendiente, En Planeación, Planificado, Despachado + +### CA-003: Panel de OTs pendientes +**Dado** que hay OTs sin asignar +**Cuando** veo el tablero +**Entonces** aparece un panel lateral con lista de OTs pendientes de planificar + +### CA-004: Filtros +**Dado** que tengo muchas OTs +**Cuando** aplico filtros (fecha, cliente, región, prioridad) +**Entonces** el tablero muestra solo OTs que cumplen los criterios + +### CA-005: Detalle de OT +**Dado** que quiero ver información de una OT +**Cuando** hago clic en ella +**Entonces** se abre panel con detalles: cliente, origen, destino, carga, restricciones + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ PLANEACIÓN TMS [Gantt] [Kanban] │ +├─────────────────────────────────────────────────────────────────────────┤ +│ Filtros: [Fecha ▼] [Cliente ▼] [Región ▼] [Prioridad ▼] [Buscar...] │ +├─────────────────────┬───────────────────────────────────────────────────┤ +│ OTs PENDIENTES (12) │ CALENDARIO SEMANAL │ +│ │ Recurso │ Lun 27 │ Mar 28 │ Mie 29 │ Jue 30 │ +│ ┌─────────────────┐ │ ─────────┼────────┼────────┼────────┼──────── │ +│ │ 🔴 OT-1234 │ │ U-001 │ ▓▓▓▓▓▓ │ │ ▓▓▓▓ │ │ +│ │ CDMX → GDL │ │ U-002 │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ +│ │ 8 ton, 28 ene │ │ U-003 │ ░░░░ │ │ │ ▓▓▓▓▓▓ │ +│ └─────────────────┘ │ U-004 │ │ ▓▓▓ │ │ │ +│ ┌─────────────────┐ │ U-005 │ DISP. │ DISP. │ DISP. │ DISP. │ +│ │ 🟡 OT-1235 │ │ │ │ │ │ │ +│ │ MTY → CDMX │ │ ▓▓▓ = Asignado ░░░ = Mantenimiento │ +│ │ 5 ton, 29 ene │ │ │ +│ └─────────────────┘ │ │ +│ ┌─────────────────┐ │───────────────────────────────────────────────────│ +│ │ 🟢 OT-1236 │ │ RECURSOS DISPONIBLES (28 ene) │ +│ │ GDL → TIJ │ │ Unidades: 5/12 Operadores: 8/15 Remolques: 10 │ +│ │ 12 ton, 30 ene │ │ │ +│ └─────────────────┘ │ │ +└─────────────────────┴───────────────────────────────────────────────────┘ + +🔴 Urgente (SLA <24h) 🟡 Normal 🟢 Flexible +``` + +--- + +## Notas Técnicas + +- Usar biblioteca de Gantt (DHTMLX, Bryntum, o similar) +- Carga lazy de semanas para performance +- WebSocket para actualizaciones en tiempo real +- Cache de disponibilidad con TTL de 30 segundos + +--- + +## Definición de Done + +- [ ] Vista Gantt funcional +- [ ] Vista Kanban funcional +- [ ] Panel de OTs pendientes +- [ ] Filtros implementados +- [ ] Detalle de OT en panel lateral +- [ ] Performance <3s con 500 OTs +- [ ] Tests E2E diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-002.md b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-002.md new file mode 100644 index 0000000..c748e9d --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-002.md @@ -0,0 +1,110 @@ +# US-MAI004-002: Consolidar OTs en embarque + +**ID:** US-MAI004-002 +**Módulo:** MAI-004 (Planeación TMS) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** planner de tráfico +**Quiero** que el sistema sugiera qué OTs puedo consolidar en un mismo viaje +**Para** maximizar la utilización de capacidad de las unidades + +--- + +## Criterios de Aceptación + +### CA-001: Selección múltiple +**Dado** que hay OTs con características similares +**Cuando** selecciono 2 o más OTs en el tablero +**Entonces** se habilita el botón "Sugerir Consolidación" + +### CA-002: Análisis de compatibilidad +**Dado** que solicito sugerencia de consolidación +**Cuando** el sistema analiza las OTs +**Entonces** verifica: zona origen similar, destinos cercanos, ventanas compatibles, mismo tipo equipo + +### CA-003: Resultado positivo +**Dado** que las OTs son consolidables +**Cuando** veo el resultado +**Entonces** muestra: capacidad combinada, ahorro estimado, y botón "Crear Embarque" + +### CA-004: Resultado negativo +**Dado** que las OTs no son consolidables +**Cuando** veo el resultado +**Entonces** muestra el motivo: "Ventanas incompatibles", "Destinos muy lejanos", etc. + +### CA-005: Creación de embarque +**Dado** que acepto la sugerencia +**Cuando** confirmo crear embarque +**Entonces** se crea EMB con las OTs agrupadas y aparece en el tablero + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ANÁLISIS DE CONSOLIDACIÓN [X]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ OTs Seleccionadas: │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ OT-1234 │ CDMX → GDL │ 8 ton │ Ventana 8:00-12:00 │ │ +│ │ OT-1237 │ CDMX → GDL Sur │ 4 ton │ Ventana 9:00-14:00 │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ✅ CONSOLIDACIÓN RECOMENDADA │ +│ │ +│ Criterios cumplidos: │ +│ ✓ Mismo origen: CDMX │ +│ ✓ Destinos cercanos: 15 km entre GDL y GDL Sur │ +│ ✓ Ventanas compatibles: Overlap 9:00-12:00 │ +│ ✓ Mismo tipo equipo: Caja seca │ +│ │ +│ Capacidad combinada: 12 toneladas │ +│ Unidad sugerida: Caja seca 18 ton (67% utilización) │ +│ │ +│ 💰 Ahorro estimado: $2,500 vs 2 viajes separados │ +│ │ +│ [Cancelar] [Crear Embarque EMB-0089] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Reglas de Consolidación + +| Criterio | Condición | Peso | +|----------|-----------|------| +| Mismo origen | Distancia < 20km | Obligatorio | +| Destinos cercanos | Distancia < 50km | Obligatorio | +| Ventanas compatibles | Overlap > 2 horas | Obligatorio | +| Mismo tipo equipo | Match exacto | Obligatorio | +| Mismo cliente | Preferido | Opcional | +| Capacidad disponible | Sum < 100% unidad | Obligatorio | + +--- + +## Notas Técnicas + +- Algoritmo de clustering por zona geográfica +- Cálculo de distancias vía API de mapas (cache) +- El ahorro se calcula: 2*tarifa_individual - tarifa_consolidada + +--- + +## Definición de Done + +- [ ] Selección múltiple de OTs +- [ ] Algoritmo de análisis implementado +- [ ] UI de resultado con detalles +- [ ] Creación de embarque funcional +- [ ] Cálculo de ahorro estimado +- [ ] Tests unitarios del algoritmo diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-003.md b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-003.md new file mode 100644 index 0000000..08b6b58 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-003.md @@ -0,0 +1,118 @@ +# US-MAI004-003: Asignar unidad a viaje + +**ID:** US-MAI004-003 +**Módulo:** MAI-004 (Planeación TMS) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** planner de tráfico +**Quiero** asignar unidad, operador y remolque a un embarque/viaje +**Para** crear el viaje planificado listo para despacho + +--- + +## Criterios de Aceptación + +### CA-001: Selector de unidad +**Dado** que tengo un embarque para asignar +**Cuando** abro el selector de unidad +**Entonces** veo solo unidades disponibles en las fechas requeridas con capacidad suficiente + +### CA-002: Selector de operador +**Dado** que seleccioné una unidad +**Cuando** abro el selector de operador +**Entonces** veo solo operadores disponibles con licencia vigente y calificados + +### CA-003: Selector de remolque +**Dado** que el viaje requiere remolque +**Cuando** abro el selector +**Entonces** veo remolques disponibles del tipo correcto + +### CA-004: Validación de capacidad +**Dado** que asigno recursos +**Cuando** la capacidad de la unidad es menor al peso total +**Entonces** el sistema bloquea y muestra "Capacidad insuficiente" + +### CA-005: Creación de viaje +**Dado** que todos los recursos están asignados y validados +**Cuando** confirmo la asignación +**Entonces** se crea viaje en estado PLANIFICADO con reservas de recursos + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ASIGNAR RECURSOS - EMB-0089 [X]│ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Embarque: 2 OTs | 12 ton | CDMX → GDL/GDL Sur │ +│ Fecha requerida: 28 Ene 2026 | Tipo equipo: Caja Seca │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ UNIDAD * │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ U-005 Kenworth T680 | Caja Seca 18 ton | ✓ Disponible ▼│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ Capacidad: 12/18 ton (67%) ✓ │ +│ │ +│ OPERADOR * │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Juan Pérez García | Lic. Federal A | ✓ Vigente ▼│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ HOS disponibles: 11 hrs ✓ │ +│ │ +│ REMOLQUE (Opcional) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Seleccionar remolque... ▼│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ RESUMEN DE VALIDACIONES │ +│ ✓ Capacidad OK │ +│ ✓ Operador calificado │ +│ ✓ Unidad con documentos vigentes │ +│ ✓ Sin conflicto de horarios │ +│ │ +│ [Cancelar] [Crear Viaje Planificado] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Filtros de Disponibilidad + +| Recurso | Criterios de filtrado | +|---------|----------------------| +| Unidad | Disponible en fecha, tipo equipo, capacidad suficiente, documentos OK | +| Operador | Disponible en fecha, licencia vigente, HOS suficiente, no en lista negra | +| Remolque | Disponible en fecha, tipo compatible, documentos OK | + +--- + +## Notas Técnicas + +- Los selectores usan búsqueda con autocomplete +- La disponibilidad se consulta en tiempo real +- Al crear viaje se crean registros en `asignaciones` +- Notificación push al operador asignado + +--- + +## Definición de Done + +- [ ] Selector de unidad con filtros +- [ ] Selector de operador con filtros +- [ ] Selector de remolque con filtros +- [ ] Validación de capacidad +- [ ] Creación de viaje y reservas +- [ ] Notificación al operador +- [ ] Tests de integración diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-004.md b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-004.md new file mode 100644 index 0000000..e402fe3 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-004.md @@ -0,0 +1,113 @@ +# US-MAI004-004: Validar compatibilidad de recursos + +**ID:** US-MAI004-004 +**Módulo:** MAI-004 (Planeación TMS) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** planner de tráfico +**Quiero** que el sistema valide automáticamente que los recursos cumplen todos los requisitos +**Para** evitar asignar operadores o unidades que no están calificados para el servicio + +--- + +## Criterios de Aceptación + +### CA-001: Validación de operador +**Dado** que asigno un operador +**Cuando** el sistema valida +**Entonces** verifica: licencia vigente, certificaciones requeridas, HOS disponibles, no en lista negra del cliente + +### CA-002: Validación de unidad +**Dado** que asigno una unidad +**Cuando** el sistema valida +**Entonces** verifica: documentos vigentes, cumple requisitos del cliente (GPS, antigüedad), tipo equipo correcto + +### CA-003: Bloqueo por incumplimiento +**Dado** que un recurso no cumple validación obligatoria +**Cuando** intento confirmar asignación +**Entonces** el sistema bloquea y muestra el motivo específico + +### CA-004: Advertencia +**Dado** que un recurso cumple pero con observaciones +**Cuando** intento confirmar +**Entonces** el sistema muestra advertencia pero permite continuar + +### CA-005: Override con autorización +**Dado** que necesito asignar un recurso que no cumple +**Cuando** un supervisor autoriza el override +**Entonces** se permite la asignación con registro de justificación + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ VALIDACIÓN DE RECURSOS │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ OPERADOR: Juan Pérez García │ +│ ├─ ✓ Licencia Federal A vigente hasta 2027-05-15 │ +│ ├─ ✓ Certificación materiales peligrosos │ +│ ├─ ✓ HOS disponibles: 11 hrs (requerido: 8 hrs) │ +│ └─ ✓ No está en lista negra del cliente │ +│ │ +│ UNIDAD: U-005 Kenworth T680 │ +│ ├─ ✓ Verificación vigente hasta 2026-06-30 │ +│ ├─ ✓ Seguro vigente hasta 2026-12-31 │ +│ ├─ ✓ Permiso SCT vigente │ +│ ├─ ✓ GPS instalado y activo │ +│ └─ ⚠ Antigüedad: 6 años (cliente pide <5 años) │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ⚠ 1 ADVERTENCIA ENCONTRADA │ +│ │ +│ La unidad excede la antigüedad requerida por el cliente. │ +│ Puede continuar pero se registrará como excepción. │ +│ │ +│ [Cancelar] [Solicitar Override] [Continuar con Advertencia] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Catálogo de Validaciones + +| Código | Validación | Tipo | Aplica a | +|--------|------------|------|----------| +| VAL-001 | Licencia vigente | Bloqueante | Operador | +| VAL-002 | Certificación requerida | Bloqueante | Operador | +| VAL-003 | HOS suficientes | Bloqueante | Operador | +| VAL-004 | Lista negra cliente | Bloqueante | Operador | +| VAL-005 | Documentos unidad | Bloqueante | Unidad | +| VAL-006 | GPS activo | Bloqueante | Unidad | +| VAL-007 | Antigüedad máxima | Advertencia | Unidad | +| VAL-008 | Tipo equipo correcto | Bloqueante | Unidad | + +--- + +## Notas Técnicas + +- Las reglas se almacenan en `requisitos_cliente` y `reglas_asignacion` +- El override requiere rol de supervisor +- Todos los overrides se registran en auditoría +- Las validaciones se ejecutan en tiempo real + +--- + +## Definición de Done + +- [ ] Validaciones de operador implementadas +- [ ] Validaciones de unidad implementadas +- [ ] UI de resultado de validaciones +- [ ] Bloqueo por incumplimiento +- [ ] Flujo de override con supervisor +- [ ] Registro en auditoría +- [ ] Tests de cada validación diff --git a/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-005.md b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-005.md new file mode 100644 index 0000000..91738ae --- /dev/null +++ b/docs/02-definicion-modulos/MAI-004-planeacion/historias-usuario/US-MAI004-005.md @@ -0,0 +1,125 @@ +# US-MAI004-005: Calcular ETA inicial + +**ID:** US-MAI004-005 +**Módulo:** MAI-004 (Planeación TMS) +**Prioridad:** Media +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** planner de tráfico +**Quiero** que el sistema calcule los ETAs estimados para cada parada del viaje +**Para** validar que puedo cumplir las ventanas comprometidas con el cliente + +--- + +## Criterios de Aceptación + +### CA-001: Cálculo de distancia +**Dado** que tengo un viaje con origen y destinos +**Cuando** solicito calcular ETA +**Entonces** el sistema obtiene distancias vía API de mapas + +### CA-002: Estimación de tiempo +**Dado** que tengo las distancias +**Cuando** el sistema calcula tiempos +**Entonces** considera: velocidad promedio por tipo de vía, paradas de descanso, tiempo en cada parada + +### CA-003: Itinerario con ETAs +**Dado** que el cálculo está completo +**Cuando** veo el resultado +**Entonces** muestra itinerario con ETA de llegada y salida de cada punto + +### CA-004: Comparación con SLA +**Dado** que tengo ETAs calculados +**Cuando** comparo con ventanas del cliente +**Entonces** el sistema marca en verde si cumple, rojo si no cumple + +### CA-005: Ajuste de hora salida +**Dado** que el ETA no cumple la ventana +**Cuando** ajusto la hora de salida planificada +**Entonces** el sistema recalcula todos los ETAs + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ITINERARIO Y ETAs - VJE-0123 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Hora salida planificada: [06:00] ▲▼ [Recalcular] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ITINERARIO │ +│ │ +│ 📍 ORIGEN: Bodega CDMX Norte │ +│ Salida planificada: 06:00 │ +│ Tiempo carga: 1 hora │ +│ Salida real estimada: 07:00 │ +│ │ +│ ↓ 280 km | ~4.5 hrs | Autopista México-Querétaro │ +│ │ +│ 📍 PARADA 1: Almacén GDL Centro │ +│ ETA llegada: 11:30 │ +│ Ventana cliente: 10:00 - 14:00 │ +│ Estado: ✅ DENTRO DE VENTANA │ +│ Tiempo descarga: 1 hora │ +│ Salida estimada: 12:30 │ +│ │ +│ ↓ 45 km | ~1 hr | Periférico GDL │ +│ │ +│ 📍 PARADA 2: Bodega GDL Sur │ +│ ETA llegada: 13:30 │ +│ Ventana cliente: 12:00 - 16:00 │ +│ Estado: ✅ DENTRO DE VENTANA │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ RESUMEN │ +│ Distancia total: 325 km │ +│ Tiempo total estimado: 7.5 horas │ +│ Todas las ventanas: ✅ OK │ +│ │ +│ [Guardar ETAs] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Parámetros de Cálculo + +| Parámetro | Valor por defecto | Configurable | +|-----------|-------------------|--------------| +| Velocidad autopista | 80 km/h | Sí | +| Velocidad carretera | 60 km/h | Sí | +| Velocidad urbana | 30 km/h | Sí | +| Tiempo carga promedio | 60 min | Por cliente | +| Tiempo descarga promedio | 45 min | Por cliente | +| Parada descanso | 30 min cada 4 hrs | Por política | + +--- + +## Notas Técnicas + +- Usar Google Maps Distance Matrix API o similar +- Cache de distancias frecuentes (TTL 7 días) +- Los ETAs se almacenan en `eta_calculado` +- Recálculo automático si cambian paradas + +--- + +## Definición de Done + +- [ ] Integración con API de mapas +- [ ] Cálculo de tiempos con parámetros +- [ ] UI de itinerario con ETAs +- [ ] Comparación con ventanas SLA +- [ ] Ajuste de hora de salida +- [ ] Cache de distancias +- [ ] Tests de cálculo diff --git a/docs/02-definicion-modulos/MAI-005-despacho/README.md b/docs/02-definicion-modulos/MAI-005-despacho/README.md new file mode 100644 index 0000000..e4db55c --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/README.md @@ -0,0 +1,216 @@ +# MAI-005: Despacho + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Estado:** Diseño +**Prioridad:** P0 (Crítico - Workflow + NOM-068 Compliance) + +--- + +## Descripción General + +El módulo de Despacho es responsable de la liberación operativa del viaje, asegurando que todos los checklists, documentos, sellos y evidencias estén completos antes de que la unidad salga a ruta. + +**Problema que resuelve:** +- Viajes que salen sin inspección pre-viaje (riesgo de accidentes) +- Falta de control de sellos de seguridad +- Documentación incompleta que genera problemas en ruta +- Incumplimiento de NOM-068 (condiciones físico-mecánicas) + +--- + +## Objetivos del Módulo + +1. **Checklist Pre-Viaje:** Inspección documentada según NOM-068 +2. **Control de Sellos:** Registro y evidencia de sellos de seguridad +3. **Evidencias de Carga:** Fotos del estado de la carga antes de salir +4. **Kit Documental:** Compilar todos los documentos necesarios +5. **Liberación Oficial:** Evento de "gate out" con timestamp y responsable + +--- + +## Alcance Funcional + +### Incluido + +- Checklist de inspección pre-viaje parametrizable +- Control de sellos (asignación, fotos, verificación) +- Captura de evidencias de carga +- Compilación de kit documental digital +- Registro de salida (gate out) +- Validaciones de despacho +- Notificación de salida + +### Excluido + +- Planeación y asignación (MAI-004) +- Tracking en ruta (MAI-006) +- Generación de Carta Porte (MAE-016) + +--- + +## Actores + +| Actor | Rol en el módulo | +|-------|------------------| +| Operador | Ejecuta checklist, registra sellos, toma evidencias | +| Despachador | Valida checklist, autoriza salida | +| Vigilancia | Confirma salida física (gate out) | +| Sistema | Valida documentación, genera alertas | + +--- + +## Flujo Principal + +``` +VIAJE PLANIFICADO + │ + ▼ +┌─────────────────────────────────────────┐ +│ 1. CHECKLIST PRE-VIAJE │ +│ - Operador inspecciona unidad │ +│ - Registra estado de cada punto │ +│ - Adjunta fotos si hay observaciones │ +│ - Firma digital del checklist │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 2. CONTROL DE SELLOS │ +│ - Asignar números de sello │ +│ - Tomar foto de cada sello colocado │ +│ - Registrar ubicación del sello │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 3. EVIDENCIAS DE CARGA │ +│ - Fotos de la carga │ +│ - Peso en báscula (si aplica) │ +│ - Firma de almacén │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 4. KIT DOCUMENTAL │ +│ - Orden de viaje │ +│ - Carta porte (si ya generada) │ +│ - Remisión/factura del cliente │ +│ - Permisos especiales │ +│ - Instrucciones de entrega │ +└────────────────────┬────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ 5. VALIDACIÓN DE DESPACHO │ +│ ✓ Checklist completo │ +│ ✓ Sellos registrados │ +│ ✓ Documentos completos │ +│ ✓ Sin bloqueos de unidad/operador │ +└────────────────────┬────────────────────┘ + │ + ┌──────┴──────┐ + │ │ + ▼ ▼ + [APROBADO] [BLOQUEADO] + │ │ + ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ +│ 6. GATE OUT │ │ Resolver y │ +│ - Timestamp │ │ reintentar │ +│ - GPS │ │ │ +│ - Responsable│ │ │ +└────────┬────────┘ └─────────────────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ VIAJE DESPACHADO │ +│ → Inicia Tracking (MAI-006) │ +└─────────────────────────────────────────┘ +``` + +--- + +## Datos del Módulo + +### Entidades Principales + +| Entidad | Descripción | Estado | +|---------|-------------|--------| +| ChecklistPreViaje | Inspección de unidad | NO IMPLEMENTADA | +| ItemChecklist | Puntos de inspección | NO IMPLEMENTADA | +| SelloViaje | Registro de sellos | NO IMPLEMENTADA | +| EvidenciaCarga | Fotos de la carga | NO IMPLEMENTADA | +| DespachoViaje | Registro de liberación | NO IMPLEMENTADA | + +### Campos Clave Checklist + +| Campo | Tipo | Obligatorio | Descripción | +|-------|------|-------------|-------------| +| viaje_id | UUID | Sí | Viaje asociado | +| tipo_checklist | ENUM | Sí | PRE_VIAJE, POST_VIAJE | +| operador_id | UUID | Sí | Quien ejecuta | +| fecha_ejecucion | TIMESTAMP | Sí | Cuándo se ejecutó | +| firma_operador | TEXT | Sí | Firma digital | +| status | ENUM | Sí | EN_PROCESO, APROBADO, RECHAZADO | +| items | JSONB | Sí | Detalle de puntos inspeccionados | + +--- + +## Requerimientos Funcionales + +Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md) + +--- + +## Compliance NOM-068 + +El módulo debe cumplir con NOM-068-SCT-2-2014: + +- **Checklist parametrizable** según tipo de vehículo +- **Puntos de inspección** según norma (llantas, frenos, luces, etc.) +- **Evidencia fotográfica** de condiciones +- **Bloqueo de salida** si hay fallas críticas +- **Registro auditable** de inspecciones + +--- + +## Métricas del Módulo + +| KPI | Fórmula | Meta | +|-----|---------|------| +| Checklists completados | % viajes con checklist | 100% | +| Tiempo de despacho | Avg(gate_out - inicio_checklist) | <45 min | +| Viajes bloqueados | % viajes con bloqueo | <5% | +| Sellos documentados | % viajes con sellos OK | 100% | + +--- + +## Dependencias + +### Este módulo depende de: +- MAI-004 (Planeación): Viajes planificados +- MAI-011 (Flota): Datos de unidad y operador +- MAE-016 (Carta Porte): Documento para kit + +### Otros módulos dependen de este: +- MAI-006 (Tracking): Inicia al despachar +- MAI-007 (POD): Viaje debe estar despachado + +--- + +## Historias de Usuario + +Ver carpeta: [historias-usuario/](./historias-usuario/) + +| US | Título | Prioridad | +|----|--------|-----------| +| US-MAI005-001 | Ejecutar checklist pre-viaje | Alta | +| US-MAI005-002 | Registrar sellos de seguridad | Alta | +| US-MAI005-003 | Capturar evidencias de carga | Alta | +| US-MAI005-004 | Compilar kit documental | Media | +| US-MAI005-005 | Registrar salida (gate out) | Alta | + +--- + +*Módulo MAI-005 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-005-despacho/REQUERIMIENTOS.md b/docs/02-definicion-modulos/MAI-005-despacho/REQUERIMIENTOS.md new file mode 100644 index 0000000..e6878e7 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/REQUERIMIENTOS.md @@ -0,0 +1,214 @@ +# REQUERIMIENTOS.md - MAI-005: Despacho + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.4 + +--- + +## Requerimientos Funcionales + +### RF-4.4.1: Orden de Viaje (OV) + +**Descripción:** +El sistema debe generar la Orden de Viaje desde el embarque con toda la información operativa necesaria. + +**Criterios de Aceptación:** +1. La OV incluye: unidad, remolques, operador, ruta completa, paradas con secuencia +2. La OV incluye instrucciones especiales del cliente +3. La OV es visible en app móvil del operador +4. La OV puede imprimirse en formato compacto +5. La OV tiene código QR para identificación rápida + +**Mapeo a DDL:** +- Tabla: `viajes` +- Vista: `v_orden_viaje` + +**Endpoints Requeridos:** +- `GET /api/v1/viajes/:id/orden-viaje` - Obtener OV +- `GET /api/v1/viajes/:id/orden-viaje/pdf` - Descargar PDF + +**Prioridad:** Alta + +--- + +### RF-4.4.2: Checklists Pre-Viaje + +**Descripción:** +El sistema debe permitir ejecutar una inspección de la unidad con checklist parametrizable por tipo de vehículo, cumpliendo NOM-068. + +**Criterios de Aceptación:** +1. Checklist configurable por tipo de unidad (tractora, remolque, caja) +2. Puntos de inspección incluyen: + - Llantas (presión, estado, profundidad) + - Frenos (servicio, estacionamiento) + - Luces (delanteras, traseras, direccionales) + - Espejos y cristales + - Niveles (aceite, anticongelante, combustible) + - Sistema de acoplamiento (quinta rueda, conexiones) + - Documentación abordo +3. Cada punto tiene opciones: OK, Observación, Falla +4. Fallas críticas bloquean el despacho +5. Operador firma digitalmente al completar +6. Se pueden adjuntar fotos por punto + +**Mapeo a DDL:** +- Tabla: `inspecciones_pre_viaje` +- Tabla: `checklist_items` (catálogo) + +**Endpoints Requeridos:** +- `GET /api/v1/checklists/plantilla/:tipo-unidad` - Obtener plantilla +- `POST /api/v1/viajes/:id/checklist` - Registrar checklist +- `POST /api/v1/viajes/:id/checklist/items/:item/foto` - Adjuntar foto + +**Prioridad:** Alta + +--- + +### RF-4.4.3: Control de Sellos + +**Descripción:** +El sistema debe registrar la asignación y evidencia de sellos de seguridad. + +**Criterios de Aceptación:** +1. Asignar uno o más sellos al viaje +2. Registrar número de sello (manual o escáner) +3. Registrar ubicación del sello (puerta trasera, lateral) +4. Capturar foto del sello colocado +5. Registrar ruptura de sello con motivo +6. Reemplazo de sello con nuevo número y evidencia + +**Mapeo a DDL:** +- Tabla: `sellos_viaje` +- Campos: numero, ubicacion, foto_url, fecha_colocacion, status + +**Endpoints Requeridos:** +- `POST /api/v1/viajes/:id/sellos` - Registrar sello +- `PUT /api/v1/sellos/:id/ruptura` - Registrar ruptura +- `POST /api/v1/sellos/:id/reemplazo` - Registrar reemplazo + +**Prioridad:** Alta + +--- + +### RF-4.4.4: Evidencias de Carga + +**Descripción:** +El sistema debe capturar evidencias fotográficas del estado de la carga antes de cerrar. + +**Criterios de Aceptación:** +1. Capturar fotos de la carga estibada +2. Registrar peso en báscula (opcional, manual o integrado) +3. Capturar firma del responsable de almacén +4. Asociar evidencias al viaje +5. Las fotos funcionan en modo offline + +**Mapeo a DDL:** +- Tabla: `evidencias_carga` +- Campos: viaje_id, tipo, url, peso_bascula, firma_almacen + +**Endpoints Requeridos:** +- `POST /api/v1/viajes/:id/evidencias-carga` - Subir evidencia +- `POST /api/v1/viajes/:id/evidencias-carga/firma` - Registrar firma + +**Prioridad:** Alta + +--- + +### RF-4.4.5: Kit Documental + +**Descripción:** +El sistema debe compilar todos los documentos necesarios para el viaje en formato digital. + +**Criterios de Aceptación:** +1. Compilar automáticamente: + - Orden de Viaje + - Carta Porte (si ya generada) + - Remisión/factura del cliente + - Permisos especiales (hazmat, sobredimensión) + - Instrucciones de entrega por parada +2. Disponible en app móvil para consulta offline +3. Opción de imprimir paquete completo +4. Alertar si falta documento obligatorio + +**Mapeo a DDL:** +- Tabla: `documentos_viaje` +- Campos: viaje_id, tipo_documento, url, obligatorio + +**Endpoints Requeridos:** +- `GET /api/v1/viajes/:id/kit-documental` - Obtener lista +- `GET /api/v1/viajes/:id/kit-documental/zip` - Descargar todos +- `POST /api/v1/viajes/:id/documentos` - Agregar documento + +**Prioridad:** Media + +--- + +### RF-4.4.6: Gate Out / Salida Oficial + +**Descripción:** +El sistema debe registrar el evento de salida con timestamp, usuario responsable y geolocalización. + +**Criterios de Aceptación:** +1. Validar que todas las condiciones de despacho estén cumplidas +2. Registrar timestamp exacto de salida +3. Registrar coordenadas GPS de la salida +4. Registrar usuario que autoriza (despachador o vigilancia) +5. Cambiar estado del viaje a DESPACHADO +6. Notificar al cliente que el viaje inició +7. Activar tracking (MAI-006) + +**Mapeo a DDL:** +- Tabla: `despachos` +- Campos: viaje_id, fecha_salida, coordenadas, usuario_id, notas + +**Endpoints Requeridos:** +- `POST /api/v1/viajes/:id/gate-out` - Registrar salida +- `GET /api/v1/viajes/:id/validar-despacho` - Verificar condiciones + +**Prioridad:** Alta + +--- + +## Requerimientos No Funcionales + +### RNF-001: Modo Offline +El checklist y captura de evidencias deben funcionar sin conexión. + +### RNF-002: Performance +El checklist debe cargar en menos de 2 segundos. + +### RNF-003: Compliance +Todos los registros deben ser inmutables para auditoría NOM-068. + +### RNF-004: Disponibilidad +El módulo debe estar disponible 24/7 para operaciones nocturnas. + +--- + +## Validaciones de Negocio + +| Validación | Descripción | Acción si falla | +|------------|-------------|-----------------| +| DSP_001 | Checklist completado | Bloquear gate out | +| DSP_002 | Sin fallas críticas en checklist | Bloquear gate out | +| DSP_003 | Sellos registrados (si aplica) | Bloquear gate out | +| DSP_004 | Documentos obligatorios presentes | Alertar, permitir override | +| DSP_005 | Operador con HOS suficiente | Bloquear gate out | + +--- + +## Matriz de Trazabilidad + +| RF | Tabla DDL | Entity | Endpoint | US | +|----|-----------|--------|----------|---| +| RF-4.4.1 | viajes | Viaje | GET /orden-viaje | US-MAI005-004 | +| RF-4.4.2 | inspecciones_pre_viaje | ChecklistPreViaje | POST /checklist | US-MAI005-001 | +| RF-4.4.3 | sellos_viaje | SelloViaje | POST /sellos | US-MAI005-002 | +| RF-4.4.4 | evidencias_carga | EvidenciaCarga | POST /evidencias-carga | US-MAI005-003 | +| RF-4.4.5 | documentos_viaje | DocumentoViaje | GET /kit-documental | US-MAI005-004 | +| RF-4.4.6 | despachos | DespachoViaje | POST /gate-out | US-MAI005-005 | + +--- + +*MAI-005 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-005-despacho/RESUMEN-EPICA.md b/docs/02-definicion-modulos/MAI-005-despacho/RESUMEN-EPICA.md new file mode 100644 index 0000000..fcc7208 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/RESUMEN-EPICA.md @@ -0,0 +1,215 @@ +# RESUMEN-EPICA.md - MAI-005: Despacho + +**Código:** MAI-005 +**Nombre:** Despacho +**Version:** 1.0.0 +**Fecha:** 2026-01-27 + +--- + +## Valor de Negocio + +### Problema + +Las empresas transportistas enfrentan riesgos por: +- Unidades que salen sin inspección (accidentes, multas) +- Sellos no documentados (reclamos por robo/faltante) +- Documentación incompleta (retenciones en ruta) +- Incumplimiento de NOM-068 (sanciones SCT) +- Sin registro de hora de salida real + +### Solución + +Un módulo de despacho que: +- Obliga a completar checklist antes de salir +- Documenta sellos con evidencia fotográfica +- Compila kit documental digital +- Registra gate out con timestamp y GPS + +### Beneficios Esperados + +| Beneficio | Métrica | Impacto | +|-----------|---------|---------| +| Reducción accidentes | -40% incidentes mecánicos | Seguridad, costos | +| Compliance NOM-068 | 100% inspecciones | Evita multas | +| Menos reclamos | -60% disputas por sellos | Ahorro legal | +| Trazabilidad | 100% viajes con gate out | Auditoría | + +--- + +## Actores y Stakeholders + +### Usuarios Primarios + +| Actor | Responsabilidad | Frecuencia | +|-------|-----------------|------------| +| Operador | Ejecuta checklist, registra sellos | Cada viaje | +| Despachador | Valida y autoriza salida | Cada viaje | +| Vigilancia | Confirma gate out físico | Cada viaje | + +### Usuarios Secundarios + +| Actor | Interés | +|-------|---------| +| Jefe de Flota | Monitorea condiciones de unidades | +| Cliente | Recibe notificación de salida | +| Auditor | Revisa compliance NOM-068 | + +--- + +## Flujo Principal + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ VIAJE PLANIFICADO │ +│ (Unidad y operador asignados) │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 1. CHECKLIST PRE-VIAJE (Operador) │ +│ │ +│ Unidad: U-005 Kenworth T680 │ +│ │ +│ □ Llantas │ +│ ├─ Presión eje delantero: [110 psi] ✓ │ +│ ├─ Presión eje trasero: [105 psi] ✓ │ +│ └─ Estado visual: [OK ▼] ✓ │ +│ │ +│ □ Frenos │ +│ ├─ Freno de servicio: [OK ▼] ✓ │ +│ └─ Freno de mano: [OK ▼] ✓ │ +│ │ +│ □ Luces │ +│ ├─ Delanteras: [OK ▼] ✓ │ +│ ├─ Traseras: [Observación ▼] ⚠ [📷 Foto] │ +│ └─ Direccionales: [OK ▼] ✓ │ +│ │ +│ ... (más puntos según NOM-068) │ +│ │ +│ [Firmar y Enviar] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 2. CONTROL DE SELLOS (Operador) │ +│ │ +│ Sellos del viaje: │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ #001: ABC-123456 │ Puerta trasera │ [📷] ✓ │ │ +│ │ #002: ABC-123457 │ Puerta lateral │ [📷] ✓ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ [+ Agregar Sello] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 3. EVIDENCIAS DE CARGA (Operador) │ +│ │ +│ Fotos de carga: [📷] [📷] [📷] 3/5 │ +│ Peso báscula: [12,500 kg] │ +│ Firma almacén: [✓ Capturada] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 4. VALIDACIÓN (Despachador) │ +│ │ +│ Estado del despacho: │ +│ ✓ Checklist completado (15 puntos OK, 1 observación) │ +│ ✓ Sellos registrados (2) │ +│ ✓ Evidencias de carga (3 fotos + firma) │ +│ ✓ Kit documental completo │ +│ ✓ Operador con HOS disponible (11 hrs) │ +│ │ +│ [Autorizar Salida] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 5. GATE OUT (Vigilancia) │ +│ │ +│ ✓ Confirmar salida física │ +│ │ +│ Fecha/Hora: 2026-01-28 06:15:32 │ +│ GPS: 19.4326, -99.1332 │ +│ Autoriza: Carlos Méndez (Vigilancia) │ +│ │ +│ [Registrar Gate Out] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ VIAJE DESPACHADO │ +│ → Tracking activado (MAI-006) │ +│ → Cliente notificado │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Criterios de Éxito + +### Funcionales + +- [ ] Checklist parametrizable por tipo de unidad +- [ ] Bloqueo de salida por fallas críticas +- [ ] Registro de sellos con fotos +- [ ] Kit documental compilado +- [ ] Gate out con GPS y timestamp + +### Técnicos + +- [ ] Funciona offline (checklist, fotos) +- [ ] Sincronización en <30 segundos +- [ ] Registros inmutables +- [ ] Integración con tracking + +### Negocio + +- [ ] 100% viajes con checklist +- [ ] 100% sellos documentados +- [ ] <45 min tiempo de despacho +- [ ] 0 multas por NOM-068 + +--- + +## Riesgos y Mitigaciones + +| Riesgo | Probabilidad | Impacto | Mitigación | +|--------|--------------|---------|------------| +| Operador omite checklist | Media | Alto | Bloqueo obligatorio | +| Fotos no se sincronizan | Media | Medio | Cola de reintentos | +| Resistencia al cambio | Alta | Medio | Capacitación, UX simple | +| Falta de conectividad | Alta | Medio | Modo offline robusto | + +--- + +## Dependencias + +### Prerequisitos +- MAI-004 (Planeación): Viaje planificado +- MAI-011 (Flota): Datos de unidad +- MAE-016 (Carta Porte): Documento para kit (opcional) + +### Habilita +- MAI-006 (Tracking): Se activa al despachar +- MAI-007 (POD): Viaje debe estar despachado + +--- + +## Story Points Estimados + +| Historia | Complejidad | SP | +|----------|-------------|---| +| US-MAI005-001 | Alta | 8 | +| US-MAI005-002 | Media | 5 | +| US-MAI005-003 | Media | 5 | +| US-MAI005-004 | Media | 5 | +| US-MAI005-005 | Media | 5 | +| **Total** | | **28** | + +--- + +*Épica MAI-005 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-001.md b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-001.md new file mode 100644 index 0000000..7d20f0f --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-001.md @@ -0,0 +1,142 @@ +# US-MAI005-001: Ejecutar checklist pre-viaje + +**ID:** US-MAI005-001 +**Módulo:** MAI-005 (Despacho) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** operador de transporte +**Quiero** ejecutar un checklist de inspección pre-viaje en mi dispositivo móvil +**Para** documentar el estado de la unidad y cumplir con NOM-068 antes de salir a ruta + +--- + +## Criterios de Aceptación + +### CA-001: Cargar checklist por tipo de unidad +**Dado** que tengo un viaje asignado +**Cuando** inicio el checklist pre-viaje +**Entonces** el sistema carga la plantilla correspondiente al tipo de unidad (tractora, remolque, caja seca) + +### CA-002: Registrar estado de cada punto +**Dado** que estoy ejecutando el checklist +**Cuando** inspecciono cada punto +**Entonces** puedo marcar: OK, Observación, o Falla con comentario opcional + +### CA-003: Adjuntar fotos por punto +**Dado** que un punto tiene observación o falla +**Cuando** selecciono la opción de foto +**Entonces** puedo capturar y adjuntar una imagen como evidencia + +### CA-004: Bloqueo por fallas críticas +**Dado** que marco una falla en punto crítico (frenos, llantas, luces) +**Cuando** intento finalizar el checklist +**Entonces** el sistema indica que el viaje no puede despacharse sin resolver + +### CA-005: Firma digital del operador +**Dado** que completé todos los puntos del checklist +**Cuando** finalizo la inspección +**Entonces** debo firmar digitalmente para confirmar que realicé la inspección + +### CA-006: Funcionamiento offline +**Dado** que estoy sin conexión a internet +**Cuando** ejecuto el checklist +**Entonces** puedo completarlo y las fotos se sincronizan al recuperar conexión + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CHECKLIST PRE-VIAJE ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Viaje: VJE-0123 | Unidad: U-005 Kenworth T680 │ +│ Tipo: Tractocamión con semirremolque │ +│ │ +│ Progreso: ████████░░░░░░░░ 8/15 puntos │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ 🔧 LLANTAS │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Presión eje delantero │ │ +│ │ Valor: [110 psi] │ │ +│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │ +│ │ │ │ +│ │ Presión eje trasero │ │ +│ │ Valor: [105 psi] │ │ +│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │ +│ │ │ │ +│ │ Profundidad de dibujo │ │ +│ │ Estado: ( ) OK (●) Observación ( ) Falla │ │ +│ │ Nota: [Desgaste visible en eje 3] │ │ +│ │ [📷 Agregar Foto] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ 🔧 FRENOS (CRÍTICO) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Freno de servicio │ │ +│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │ +│ │ │ │ +│ │ Freno de estacionamiento │ │ +│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ 🔧 LUCES [Expandir] │ +│ 🔧 ESPEJOS Y CRISTALES [Expandir] │ +│ 🔧 NIVELES [Expandir] │ +│ 🔧 ACOPLAMIENTO [Expandir] │ +│ 🔧 DOCUMENTACIÓN [Expandir] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ⚠ 1 observación registrada │ +│ │ +│ [Cancelar] [Firmar y Finalizar] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Puntos de Inspección NOM-068 + +| Categoría | Puntos | Crítico | +|-----------|--------|---------| +| Llantas | Presión, profundidad, estado | Sí | +| Frenos | Servicio, estacionamiento | Sí | +| Luces | Delanteras, traseras, direccionales | Sí | +| Espejos | Retrovisores, laterales | No | +| Niveles | Aceite, anticongelante, combustible | No | +| Acoplamiento | Quinta rueda, conexiones, pernos | Sí | +| Documentación | Licencia, tarjeta, permisos | Sí | + +--- + +## Notas Técnicas + +- Plantillas en tabla `checklist_items` filtradas por `tipo_unidad` +- Checklist se guarda en `inspecciones_pre_viaje` +- Fotos se suben a S3 con referencia en `item.foto_url` +- Sincronización via cola de reintentos (máx 3 intentos) +- Firma se almacena como base64 en `firma_operador` + +--- + +## Definición de Done + +- [ ] Carga de plantilla por tipo de unidad +- [ ] UI de checklist con todos los puntos NOM-068 +- [ ] Captura de fotos por punto +- [ ] Validación de puntos críticos +- [ ] Firma digital del operador +- [ ] Funcionamiento offline con sincronización +- [ ] Tests unitarios de validaciones +- [ ] Tests de integración de sincronización + diff --git a/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-002.md b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-002.md new file mode 100644 index 0000000..34091ff --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-002.md @@ -0,0 +1,172 @@ +# US-MAI005-002: Registrar sellos de seguridad + +**ID:** US-MAI005-002 +**Módulo:** MAI-005 (Despacho) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** operador de transporte +**Quiero** registrar los sellos de seguridad colocados en la unidad con evidencia fotográfica +**Para** tener respaldo ante reclamos por robo o faltante de mercancía + +--- + +## Criterios de Aceptación + +### CA-001: Agregar sello con número +**Dado** que estoy en el proceso de despacho +**Cuando** agrego un sello +**Entonces** puedo ingresar el número (manual o escáner) y la ubicación donde se colocó + +### CA-002: Foto obligatoria del sello +**Dado** que registro un sello +**Cuando** completo el registro +**Entonces** debo adjuntar foto del sello colocado mostrando el número visible + +### CA-003: Múltiples sellos por viaje +**Dado** que un viaje puede tener varios sellos +**Cuando** necesito agregar más sellos +**Entonces** puedo registrar tantos como sean necesarios (puerta trasera, lateral, etc.) + +### CA-004: Escaneo de código de barras +**Dado** que el sello tiene código de barras +**Cuando** uso la cámara para escanear +**Entonces** el sistema captura automáticamente el número del sello + +### CA-005: Registro de ruptura +**Dado** que un sello fue roto (inspección, emergencia) +**Cuando** registro la ruptura +**Entonces** debo indicar el motivo y subir foto del sello roto + +### CA-006: Reemplazo de sello +**Dado** que un sello fue roto +**Cuando** coloco un sello nuevo +**Entonces** se registra como reemplazo vinculado al sello original + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CONTROL DE SELLOS ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Viaje: VJE-0123 | Cliente: Distribuidora ABC │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ SELLOS REGISTRADOS │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ #1 Sello: ABC-123456 │ │ +│ │ Ubicación: Puerta trasera │ │ +│ │ Colocado: 2026-01-28 06:05:12 │ │ +│ │ Estado: ✅ ACTIVO │ │ +│ │ [📷 Ver foto] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ #2 Sello: ABC-123457 │ │ +│ │ Ubicación: Puerta lateral izquierda │ │ +│ │ Colocado: 2026-01-28 06:08:45 │ │ +│ │ Estado: ✅ ACTIVO │ │ +│ │ [📷 Ver foto] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ AGREGAR NUEVO SELLO │ +│ │ +│ Número: [________________] [📷 Escanear] │ +│ │ +│ Ubicación: [Seleccionar ubicación ▼] │ +│ ○ Puerta trasera │ +│ ○ Puerta lateral izquierda │ +│ ○ Puerta lateral derecha │ +│ ○ Otra: [________________] │ +│ │ +│ Foto del sello colocado: [📷 Tomar foto] (Obligatorio) │ +│ │ +│ [+ Agregar Sello] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ 2 sellos registrados [Continuar →] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Pantalla de Ruptura de Sello + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ REGISTRAR RUPTURA DE SELLO ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Sello: ABC-123456 │ +│ Ubicación original: Puerta trasera │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ⚠ REGISTRAR RUPTURA │ +│ │ +│ Motivo de ruptura: │ +│ ( ) Inspección en aduana/retén │ +│ ( ) Inspección por cliente │ +│ ( ) Emergencia (accidente, falla mecánica) │ +│ (●) Otro: [Verificación por almacén destino] │ +│ │ +│ Foto del sello roto: [📷 Foto capturada ✓] │ +│ │ +│ Coordenadas GPS: 20.6597, -103.3496 (Auto) │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ¿Colocar sello de reemplazo? │ +│ [Sí, agregar reemplazo] [No, continuar sin sello] │ +│ │ +│ [Cancelar] [Registrar Ruptura] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Estados de Sello + +| Estado | Descripción | +|--------|-------------| +| ACTIVO | Sello colocado y vigente | +| ROTO | Sello roto con motivo registrado | +| REEMPLAZADO | Sello que fue sustituido por otro | +| VERIFICADO | Sello verificado en destino (POD) | + +--- + +## Notas Técnicas + +- Tabla: `sellos_viaje` +- Escaneo de código de barras via cámara (ML Kit o ZXing) +- Fotos se suben a S3 con metadata de geolocalización +- Historial completo inmutable para auditoría +- La ruptura registra coordenadas GPS automáticamente + +--- + +## Definición de Done + +- [ ] CRUD de sellos por viaje +- [ ] Escaneo de código de barras +- [ ] Captura de foto obligatoria +- [ ] Registro de ruptura con motivo +- [ ] Registro de reemplazo vinculado +- [ ] Funcionamiento offline +- [ ] Tests de escenarios de ruptura/reemplazo + diff --git a/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-003.md b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-003.md new file mode 100644 index 0000000..d489b3d --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-003.md @@ -0,0 +1,171 @@ +# US-MAI005-003: Capturar evidencias de carga + +**ID:** US-MAI005-003 +**Módulo:** MAI-005 (Despacho) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** operador de transporte +**Quiero** capturar evidencias fotográficas del estado de la carga antes de salir +**Para** tener respaldo del estado inicial y evitar disputas por daños + +--- + +## Criterios de Aceptación + +### CA-001: Capturar fotos de la carga +**Dado** que la carga está lista en la unidad +**Cuando** tomo fotos de evidencia +**Entonces** puedo capturar múltiples fotos mostrando el estado de la mercancía + +### CA-002: Mínimo de fotos requerido +**Dado** que el cliente o tipo de carga requiere evidencias +**Cuando** intento continuar sin fotos suficientes +**Entonces** el sistema indica cuántas fotos mínimas se requieren (configurable) + +### CA-003: Registrar peso en báscula +**Dado** que la carga pasa por báscula +**Cuando** registro el peso +**Entonces** puedo ingresar el peso total (kg) manual o desde ticket de báscula + +### CA-004: Capturar firma de almacén +**Dado** que el almacén entrega la carga +**Cuando** solicito la firma +**Entonces** el responsable de almacén firma en pantalla confirmando la entrega + +### CA-005: Funcionamiento offline +**Dado** que estoy en área sin señal +**Cuando** capturo fotos y firma +**Entonces** se almacenan localmente y sincronizan al recuperar conexión + +### CA-006: Metadata de fotos +**Dado** que capturo una foto +**Cuando** se guarda +**Entonces** incluye timestamp, coordenadas GPS y dispositivo origen + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ EVIDENCIAS DE CARGA ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Viaje: VJE-0123 | Carga: Electrodomésticos │ +│ Requisito mínimo: 3 fotos │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ 📷 FOTOS DE CARGA (3/3 mínimo) │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ 📷 1 │ │ 📷 2 │ │ 📷 3 │ │ + │ │ +│ │ [Vista] │ │ [Vista] │ │ [Vista] │ │ Agregar │ │ +│ │ 06:10am │ │ 06:11am │ │ 06:12am │ │ foto │ │ +│ │ ✓ │ │ ✓ │ │ ✓ │ │ │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ⚖ PESO EN BÁSCULA (Opcional) │ +│ │ +│ Peso bruto: [12,500] kg │ +│ Peso neto: [10,200] kg │ +│ Referencia ticket: [BSC-2026-0145] │ +│ │ +│ [📷 Foto de ticket báscula] ✓ Capturada │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ✍ FIRMA DE ALMACÉN │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ [Área de firma - táctil] │ │ +│ │ │ │ +│ │ ~~~~~~~~~~~~~~~~~~~~~~ │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ Nombre: [Carlos López Hernández] │ +│ Puesto: [Jefe de Almacén] │ +│ │ +│ [Limpiar firma] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ✓ Fotos: 3/3 ✓ Peso: Registrado ✓ Firma: Capturada │ +│ │ +│ [Cancelar] [Continuar →] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Vista de Foto Individual + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ DETALLE DE EVIDENCIA ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ │ [Imagen de la carga] │ │ +│ │ │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ 📅 Fecha/Hora: 2026-01-28 06:10:32 │ +│ 📍 Ubicación: 19.4326, -99.1332 (Bodega CDMX) │ +│ 📱 Dispositivo: iPhone 14 Pro │ +│ │ +│ Nota: [Vista frontal de la estiba completa] │ +│ │ +│ [🗑 Eliminar] [✓ Confirmar] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Configuración por Cliente + +| Cliente | Fotos mínimas | Peso requerido | Firma requerida | +|---------|---------------|----------------|-----------------| +| Default | 3 | No | Sí | +| Cliente A | 5 | Sí | Sí | +| Cliente B | 3 | Sí (neto y bruto) | Sí | +| Cliente C | 2 | No | No | + +--- + +## Notas Técnicas + +- Tabla: `evidencias_carga` +- Fotos se comprimen a max 1MB antes de subir +- Firma se guarda como SVG o PNG base64 +- Metadata EXIF se extrae automáticamente +- Cola de sincronización con reintentos exponenciales +- Configuración de requisitos en `requisitos_cliente` + +--- + +## Definición de Done + +- [ ] Captura de múltiples fotos con cámara +- [ ] Validación de fotos mínimas por configuración +- [ ] Registro de peso con campos bruto/neto +- [ ] Captura de firma táctil +- [ ] Almacenamiento con metadata (GPS, timestamp) +- [ ] Funcionamiento offline completo +- [ ] Sincronización con cola de reintentos +- [ ] Tests de sincronización y validación + diff --git a/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-004.md b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-004.md new file mode 100644 index 0000000..5ef36e3 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-004.md @@ -0,0 +1,158 @@ +# US-MAI005-004: Compilar kit documental + +**ID:** US-MAI005-004 +**Módulo:** MAI-005 (Despacho) +**Prioridad:** Media +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** despachador +**Quiero** que el sistema compile automáticamente todos los documentos necesarios para el viaje +**Para** asegurar que el operador lleva toda la documentación requerida y evitar retenciones en ruta + +--- + +## Criterios de Aceptación + +### CA-001: Compilar documentos automáticamente +**Dado** que un viaje está listo para despachar +**Cuando** accedo al kit documental +**Entonces** el sistema lista todos los documentos requeridos con su estado (disponible/pendiente) + +### CA-002: Incluir orden de viaje +**Dado** que el viaje está planificado +**Cuando** compilo el kit +**Entonces** incluye la Orden de Viaje con código QR para identificación rápida + +### CA-003: Incluir Carta Porte (si existe) +**Dado** que la Carta Porte fue generada en MAE-016 +**Cuando** compilo el kit +**Entonces** incluye el CFDI Carta Porte con su UUID + +### CA-004: Alertar documentos faltantes +**Dado** que faltan documentos obligatorios +**Cuando** reviso el kit +**Entonces** el sistema muestra alertas con los documentos pendientes + +### CA-005: Disponible offline en app +**Dado** que el kit está completo +**Cuando** el operador lo descarga en su app +**Entonces** todos los documentos están disponibles sin conexión + +### CA-006: Descargar paquete completo +**Dado** que necesito imprimir los documentos +**Cuando** solicito descarga +**Entonces** se genera un ZIP con todos los PDFs del kit + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ KIT DOCUMENTAL ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Viaje: VJE-0123 | Ruta: CDMX → GDL → AGS │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ DOCUMENTOS DEL VIAJE │ +│ │ +│ 📄 OBLIGATORIOS │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ✅ Orden de Viaje │ │ +│ │ OV-VJE-0123.pdf | 2 páginas | [Ver] [Descargar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ Carta Porte CFDI │ │ +│ │ UUID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 │ │ +│ │ CP-VJE-0123.pdf | 4 páginas | [Ver] [Descargar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ Remisión del cliente │ │ +│ │ REM-CLI-2026-0891.pdf | [Ver] [Descargar] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ⚠️ Factura del cliente │ │ +│ │ PENDIENTE - El cliente no ha subido la factura │ │ +│ │ [Subir manualmente] [Omitir con nota] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ 📄 CONDICIONALES (según carga) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ✅ Permiso de materiales peligrosos │ │ +│ │ PERM-HAZMAT-2026.pdf | [Ver] [Descargar] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ 📄 INSTRUCCIONES POR PARADA │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Parada 1: Almacén GDL Centro │ │ +│ │ • Entregar en andén 5 │ │ +│ │ • Contacto: Juan Pérez (33) 1234-5678 │ │ +│ │ • Horario: 08:00 - 18:00 │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ Parada 2: Bodega AGS │ │ +│ │ • Requiere cita previa (ya agendada) │ │ +│ │ • Contacto: María López (449) 876-5432 │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ⚠ 1 documento pendiente │ +│ │ +│ [Descargar ZIP] [Enviar a app] [Imprimir todo] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Tipos de Documentos + +| Tipo | Obligatorio | Fuente | Generación | +|------|-------------|--------|------------| +| Orden de Viaje | Siempre | Sistema | Automática | +| Carta Porte | Siempre | MAE-016 | Automática | +| Remisión | Por cliente | Cliente/Sistema | Manual/Auto | +| Factura | Por cliente | Cliente | Manual | +| Permiso Hazmat | Si aplica | Sistema | Referencia | +| Permiso Sobredimensión | Si aplica | SCT | Manual | +| Instrucciones | Siempre | Embarque | Automática | + +--- + +## Validaciones de Documentos + +| Código | Validación | Acción si falla | +|--------|------------|-----------------| +| DOC_001 | Orden de Viaje presente | Bloquear despacho | +| DOC_002 | Carta Porte si viaje federal | Bloquear despacho | +| DOC_003 | Permisos especiales si carga lo requiere | Bloquear despacho | +| DOC_004 | Factura del cliente | Advertencia | +| DOC_005 | Instrucciones de entrega | Advertencia | + +--- + +## Notas Técnicas + +- Tabla: `documentos_viaje` +- Generación de OV desde vista `v_orden_viaje` +- Integración con MAE-016 para obtener Carta Porte +- ZIP generado con JSZip o similar +- Sincronización a app móvil via API dedicada +- Cache de documentos para acceso offline + +--- + +## Definición de Done + +- [ ] Compilación automática de documentos +- [ ] Generación de Orden de Viaje con QR +- [ ] Integración con Carta Porte (MAE-016) +- [ ] Alertas de documentos faltantes +- [ ] Descarga de ZIP con todos los PDFs +- [ ] Sincronización a app móvil +- [ ] Validaciones bloqueantes vs advertencias +- [ ] Tests de compilación y generación + diff --git a/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-005.md b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-005.md new file mode 100644 index 0000000..3dec8d0 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-005-despacho/historias-usuario/US-MAI005-005.md @@ -0,0 +1,208 @@ +# US-MAI005-005: Registrar salida (gate out) + +**ID:** US-MAI005-005 +**Módulo:** MAI-005 (Despacho) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** personal de vigilancia o despachador +**Quiero** registrar el evento de salida oficial de la unidad +**Para** tener un timestamp exacto de cuándo el viaje inició y activar el tracking + +--- + +## Criterios de Aceptación + +### CA-001: Validar condiciones de despacho +**Dado** que intento registrar gate out +**Cuando** el sistema valida +**Entonces** verifica: checklist completo, sellos registrados, documentos OK, HOS del operador + +### CA-002: Bloquear si no cumple +**Dado** que hay condiciones no cumplidas +**Cuando** intento confirmar salida +**Entonces** el sistema bloquea y muestra qué falta resolver + +### CA-003: Registrar timestamp y GPS +**Dado** que confirmo la salida +**Cuando** se registra el gate out +**Entonces** guarda: fecha/hora exacta, coordenadas GPS del punto de salida + +### CA-004: Registrar usuario responsable +**Dado** que confirmo la salida +**Cuando** se registra +**Entonces** queda registrado quién autorizó (despachador o vigilancia) + +### CA-005: Cambiar estado del viaje +**Dado** que el gate out se registró +**Cuando** se completa +**Entonces** el viaje cambia a estado DESPACHADO + +### CA-006: Notificar y activar tracking +**Dado** que el viaje fue despachado +**Cuando** se confirma gate out +**Entonces** se notifica al cliente y se activa tracking (MAI-006) + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ GATE OUT - SALIDA OFICIAL ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Viaje: VJE-0123 │ +│ Unidad: U-005 Kenworth T680 │ +│ Operador: Juan Pérez García │ +│ Destino: Guadalajara, JAL │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ✓ VALIDACIÓN DE CONDICIONES │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ✅ Checklist pre-viaje │ │ +│ │ Completado: 2026-01-28 06:00 │ │ +│ │ Resultado: 14 OK, 1 observación, 0 fallas │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ Sellos de seguridad │ │ +│ │ 2 sellos registrados con foto │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ Evidencias de carga │ │ +│ │ 3 fotos + firma de almacén │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ Kit documental │ │ +│ │ 4/4 documentos obligatorios │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ HOS del operador │ │ +│ │ Disponible: 11 hrs | Requerido: 8 hrs │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ ✅ Unidad sin bloqueos │ │ +│ │ Sin alertas de mantenimiento │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ 📍 INFORMACIÓN DE SALIDA │ +│ │ +│ Fecha/Hora: 2026-01-28 06:15:32 (automático) │ +│ GPS: 19.4326, -99.1332 │ +│ Ubicación: Bodega CDMX Norte │ +│ │ +│ Autoriza: [Carlos Méndez - Vigilancia ▼] │ +│ │ +│ Notas (opcional): │ +│ [________________________________________] │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ Al confirmar: │ +│ • El viaje cambiará a estado DESPACHADO │ +│ • Se activará el tracking GPS │ +│ • Se notificará al cliente │ +│ │ +│ [Cancelar] [✓ Confirmar Gate Out] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Pantalla de Bloqueo + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ⛔ DESPACHO BLOQUEADO ✕ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Viaje: VJE-0123 │ +│ │ +│ No se puede autorizar la salida. Resolver lo siguiente: │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ ❌ BLOQUEOS CRÍTICOS (deben resolverse) │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 1. Checklist incompleto │ │ +│ │ Faltan 3 puntos por inspeccionar │ │ +│ │ [Ir a Checklist] │ │ +│ ├─────────────────────────────────────────────────────────┤ │ +│ │ 2. Falla crítica en frenos │ │ +│ │ Registrada en checklist - requiere mantenimiento │ │ +│ │ [Ver detalle] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ⚠ ADVERTENCIAS (pueden omitirse con autorización) │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 1. Factura del cliente pendiente │ │ +│ │ [Subir documento] [Omitir - Justificar] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ 2 bloqueos críticos | 1 advertencia │ +│ │ +│ [Volver] │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Validaciones de Despacho + +| Código | Validación | Tipo | Override | +|--------|------------|------|----------| +| DSP_001 | Checklist completado | Bloqueante | No | +| DSP_002 | Sin fallas críticas | Bloqueante | No | +| DSP_003 | Sellos registrados (si aplica) | Bloqueante | No | +| DSP_004 | Documentos obligatorios | Bloqueante | No | +| DSP_005 | HOS suficiente del operador | Bloqueante | Supervisor | +| DSP_006 | Unidad sin bloqueos | Bloqueante | Supervisor | +| DSP_007 | Factura del cliente | Advertencia | Sí | +| DSP_008 | Evidencias de carga | Advertencia | Sí | + +--- + +## Acciones Post Gate Out + +| Acción | Destino | Trigger | +|--------|---------|---------| +| Cambiar estado viaje | viajes.estado = DESPACHADO | Inmediato | +| Activar tracking | MAI-006 | Inmediato | +| Notificar cliente | Email/SMS/WhatsApp | <1 min | +| Actualizar dashboard | Métricas de despacho | Inmediato | +| Log de auditoría | Sistema | Inmediato | + +--- + +## Notas Técnicas + +- Tabla: `despachos` +- Endpoint: `POST /api/v1/viajes/:id/gate-out` +- Validaciones en endpoint `GET /api/v1/viajes/:id/validar-despacho` +- GPS se captura del dispositivo o se infiere de ubicación base +- Notificaciones via servicio de mensajería (MAI-015) +- Activación de tracking via evento interno + +--- + +## Definición de Done + +- [ ] Validación completa de condiciones +- [ ] Bloqueo con detalle de pendientes +- [ ] Registro de timestamp y GPS +- [ ] Registro de usuario responsable +- [ ] Cambio de estado del viaje +- [ ] Integración con notificaciones +- [ ] Integración con tracking (MAI-006) +- [ ] Override con supervisor para advertencias +- [ ] Tests de validaciones y flujo completo +