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>
198 lines
6.6 KiB
Markdown
198 lines
6.6 KiB
Markdown
# 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*
|