9caeae936a
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>
224 lines
8.0 KiB
Markdown
224 lines
8.0 KiB
Markdown
# 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*
|