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