# 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*