# 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