rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-transportistas-v2/docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md
Adrian Flores Cortes 9caeae936a 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 <noreply@anthropic.com>
2026-01-27 01:51:58 -06:00

6.6 KiB
Raw Permalink Blame History

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