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

8.0 KiB

Raw Blame History

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

Tarifario estructurado: Tarifas por lane, tipo de unidad, modalidad (FTL/LTL)
Recargos automatizados: Fuel surcharge, detention, reentrega, maniobras
SLA documentados: Tiempos comprometidos, penalizaciones, tolerancias
Cotización rápida: Cálculo automático con desglose de costos
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

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/

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

8.0 KiB Raw Blame History