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

15 KiB

Raw Blame History

US-MAI002-002: Configurar recargos (surcharges)

ID: US-MAI002-002 Módulo: MAI-002 (Tarifas y SLA) Prioridad: Alta Story Points: 5

Historia de Usuario

Como administrador comercial Quiero configurar una matriz de recargos aplicables a los servicios de transporte Para asegurar que todos los costos adicionales se capturen y facturen correctamente

Criterios de Aceptación

CA-001: Catálogo de tipos de recargo

Dado que existen diferentes tipos de cargos adicionales Cuando configuro el catálogo Entonces puedo definir: nombre, código, descripción y tipo de cálculo (% o fijo)

CA-002: Fuel surcharge con índice

Dado que el fuel surcharge varía según el precio del combustible Cuando configuro este recargo Entonces puedo definir un índice actualizable (%) que se aplica sobre la tarifa base

CA-003: Demoras (detention) con tolerancia

Dado que las demoras en carga/descarga tienen un tiempo de gracia Cuando configuro detention Entonces puedo definir: tolerancia (horas), costo por hora adicional

CA-004: Recargos por cliente

Dado que algunos clientes tienen recargos específicos Cuando configuro recargos Entonces puedo asignarlos a clientes específicos o dejarlos como generales

CA-005: Reglas de aplicación

Dado que algunos recargos se aplican automáticamente y otros manualmente Cuando configuro un recargo Entonces puedo definir si es: automático (siempre aplica), condicional (según regla), o manual

CA-006: Actualizar índice de combustible

Dado que el precio del combustible cambia periódicamente Cuando actualizo el índice Entonces se registra con fecha y el sistema usa el índice vigente para nuevas cotizaciones

Mockup / UI

┌─────────────────────────────────────────────────────────────────┐
│ CONFIGURACIÓN DE RECARGOS                              [+ Nuevo]│
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ÍNDICE DE COMBUSTIBLE (FUEL SURCHARGE)                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Índice actual: 8%                                       │   │
│  │ Última actualización: 2026-01-15                        │   │
│  │ Próxima revisión: 2026-02-15                           │   │
│  │                                              [Actualizar]│   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  TIPOS DE RECARGO                                               │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ FUEL - Fuel Surcharge                                   │   │
│  │ Tipo: Porcentaje sobre base                            │   │
│  │ Aplicación: Automática                                 │   │
│  │ Valor actual: 8%                              [Editar] │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ DETENTION_CARGA - Demora en carga                       │   │
│  │ Tipo: Monto por hora                                   │   │
│  │ Tolerancia: 2 horas | Costo: $350/hora adicional      │   │
│  │ Aplicación: Condicional (si excede tolerancia) [Editar]│   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ DETENTION_DESCARGA - Demora en descarga                 │   │
│  │ Tipo: Monto por hora                                   │   │
│  │ Tolerancia: 1.5 horas | Costo: $350/hora adicional    │   │
│  │ Aplicación: Condicional (si excede tolerancia) [Editar]│   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ MANIOBRA - Maniobra especial                            │   │
│  │ Tipo: Monto fijo                                       │   │
│  │ Valor: $800.00                                         │   │
│  │ Aplicación: Manual                            [Editar] │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ REENTREGA - Reentrega/Reexpedición                      │   │
│  │ Tipo: Porcentaje sobre base                            │   │
│  │ Valor: 30%                                             │   │
│  │ Aplicación: Manual                            [Editar] │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ ESCOLTA - Escolta de seguridad                          │   │
│  │ Tipo: Monto fijo                                       │   │
│  │ Valor: $5,000.00                                       │   │
│  │ Aplicación: Manual                            [Editar] │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ SEGURO_ADICIONAL - Seguro extra                         │   │
│  │ Tipo: Porcentaje sobre valor declarado                 │   │
│  │ Valor: 0.5%                                            │   │
│  │ Aplicación: Condicional (si valor > $500K)    [Editar] │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Editar Recargo

┌─────────────────────────────────────────────────────────────────┐
│ EDITAR RECARGO: DETENTION_CARGA                        ✕        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  INFORMACIÓN BÁSICA                                             │
│                                                                 │
│  Código: [DETENTION_CARGA] (no editable)                       │
│  Nombre: [Demora en carga]                                      │
│  Descripción: [Cargo por tiempo excedido en punto de carga]    │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  TIPO DE CÁLCULO                                                │
│                                                                 │
│  ( ) Porcentaje sobre tarifa base                              │
│  ( ) Monto fijo                                                 │
│  (●) Monto por hora/unidad                                     │
│  ( ) Porcentaje sobre valor declarado                          │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  CONFIGURACIÓN ESPECÍFICA                                       │
│                                                                 │
│  Tolerancia: [2] horas (tiempo de gracia)                      │
│  Costo por hora adicional: [$350.00] MXN                       │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  APLICACIÓN                                                     │
│                                                                 │
│  ( ) Automática (siempre se incluye)                           │
│  (●) Condicional (se aplica si se cumple regla)                │
│  ( ) Manual (el usuario decide)                                 │
│                                                                 │
│  Regla: [Tiempo en punto > tolerancia definida]                │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  ALCANCE                                                        │
│                                                                 │
│  (●) General (todos los clientes)                              │
│  ( ) Específico: [Seleccionar clientes...]                     │
│                                                                 │
│  [Cancelar]                                     [Guardar]      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Historial de Índice Fuel

┌─────────────────────────────────────────────────────────────────┐
│ HISTORIAL ÍNDICE FUEL SURCHARGE                        ✕        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Índice actual: 8%                                              │
│                                                                 │
│  Nuevo índice: [    ] %   [Aplicar]                            │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  HISTORIAL                                                      │
│                                                                 │
│  | Fecha      | Índice | Usuario          |                    │
│  |------------|--------|------------------|                    │
│  | 2026-01-15 | 8.0%   | admin@empresa.mx |                    │
│  | 2025-12-15 | 7.5%   | admin@empresa.mx |                    │
│  | 2025-11-15 | 7.0%   | admin@empresa.mx |                    │
│  | 2025-10-15 | 7.5%   | admin@empresa.mx |                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Catálogo de Recargos

Código	Nombre	Cálculo	Aplicación
FUEL	Fuel Surcharge	% sobre base	Automática
DETENTION_CARGA	Demora en carga	$/hora	Condicional
DETENTION_DESCARGA	Demora en descarga	$/hora	Condicional
MANIOBRA	Maniobra especial	Monto fijo	Manual
REENTREGA	Reentrega	% sobre base	Manual
ESCOLTA	Escolta seguridad	Monto fijo	Manual
SEGURO_ADICIONAL	Seguro extra	% sobre valor	Condicional
ALMACENAJE	Almacenaje temporal	$/día	Manual

Notas Técnicas

Tabla: tipos_recargo para el catálogo
Tabla: indice_combustible para histórico de fuel surcharge
Tabla: recargos_cliente para configuraciones específicas por cliente
Los recargos condicionales se evalúan según reglas configurables
El índice fuel tiene trigger de actualización mensual

Definición de Done

CRUD de tipos de recargo
Configuración de fuel surcharge con índice
Configuración de detention con tolerancia
Recargos por cliente
Reglas de aplicación (auto/condicional/manual)
Historial de cambios de índice fuel
Tests de cálculo de recargos

15 KiB Raw Blame History