# US-MAI009-002: Aplicar recargos automáticos **ID:** US-MAI009-002 **Módulo:** MAI-009 (Facturación Transporte) **Prioridad:** Alta **Story Points:** 5 --- ## Historia de Usuario **Como** facturador **Quiero** que el sistema calcule y aplique automáticamente los recargos correspondientes **Para** no olvidar cobrar fuel surcharge, demoras y otros cargos adicionales --- ## Criterios de Aceptación ### CA-001: Calcular fuel surcharge **Dado** que existe un índice de fuel surcharge vigente **Cuando** calculo recargos en la factura **Entonces** se aplica el % correspondiente sobre el subtotal de tarifas ### CA-002: Calcular detention en carga **Dado** que un viaje tuvo tiempo excedido en carga **Cuando** calculo recargos **Entonces** se aplica cargo por horas extra según tolerancia configurada ### CA-003: Calcular detention en descarga **Dado** que un viaje tuvo tiempo excedido en descarga **Cuando** calculo recargos **Entonces** se aplica cargo por horas extra según tolerancia configurada ### CA-004: Mostrar desglose de recargos **Dado** que se aplicaron recargos **Cuando** veo la factura **Entonces** cada recargo aparece como línea separada con descripción clara ### CA-005: Permitir ajustar recargos **Dado** que hay recargos calculados **Cuando** necesito ajustar uno **Entonces** puedo modificar el monto o eliminar la línea con justificación ### CA-006: Recargos manuales **Dado** que hay cargos adicionales no automáticos **Cuando** necesito agregarlos **Entonces** puedo seleccionar del catálogo y especificar monto --- ## Mockup / UI ``` ┌─────────────────────────────────────────────────────────────────┐ │ CALCULAR RECARGOS ✕ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Factura: BORRADOR | Subtotal servicios: $43,200.00 │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ RECARGOS AUTOMÁTICOS │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ✓ FUEL SURCHARGE │ │ │ │ Índice vigente: 8% (desde 15-ene-2026) │ │ │ │ Base de cálculo: $43,200.00 │ │ │ │ Monto: $3,456.00 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ✓ DETENTION DESCARGA (VJE-0125) │ │ │ │ Tiempo real: 4.5 horas | Tolerancia: 1.5 horas │ │ │ │ Horas extra: 3 @ $350/hr │ │ │ │ Monto: $1,050.00 │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ RECARGOS MANUALES [+ Agregar]│ │ │ │ (No hay recargos manuales) │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ RESUMEN │ │ Subtotal servicios: $43,200.00 │ │ Total recargos: $4,506.00 │ │ ───────────────────────────────────────── │ │ Nuevo subtotal: $47,706.00 │ │ IVA (16%): $7,632.96 │ │ ───────────────────────────────────────── │ │ TOTAL: $55,338.96 MXN │ │ │ │ [Cancelar] [Aplicar Recargos] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Agregar Recargo Manual ``` ┌─────────────────────────────────────────────────────────────────┐ │ AGREGAR RECARGO MANUAL ✕ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Tipo de recargo: [Seleccionar tipo ▼] │ │ ○ MANIOBRAS - Maniobra especial │ │ ○ ESCOLTA - Escolta de seguridad │ │ ○ PERNOCTA - Pernocta de unidad │ │ ○ ESTADIAS - Días extra │ │ ○ FALSO_FLETE - Viaje cancelado │ │ ○ SEGURO_ADICIONAL - Seguro extra │ │ ○ OTRO - Otros │ │ │ │ Viaje relacionado: [VJE-0125 (opcional) ▼] │ │ │ │ Descripción: │ │ [Maniobra de descarga con montacargas especial ] │ │ │ │ Cálculo: │ │ (●) Monto fijo: [$800.00] │ │ ( ) Porcentaje sobre base: [____] % │ │ │ │ [Cancelar] [Agregar Recargo] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Ajustar Recargo ``` ┌─────────────────────────────────────────────────────────────────┐ │ AJUSTAR RECARGO ✕ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Recargo: DETENTION DESCARGA (VJE-0125) │ │ Monto calculado: $1,050.00 │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ Acción: │ │ ( ) Mantener monto calculado │ │ (●) Ajustar monto: [$700.00] │ │ ( ) Eliminar recargo │ │ │ │ Justificación (obligatoria si ajusta): │ │ [Acuerdo con cliente: se cobra parcial por ser primera vez ]│ │ │ │ [Cancelar] [Guardar Ajuste] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Tipos de Recargo | Código | Nombre | Cálculo | Automático | |--------|--------|---------|------------| | FUEL | Fuel Surcharge | % sobre subtotal | Sí | | DETENTION_CARGA | Demora en carga | $/hora extra | Sí | | DETENTION_DESCARGA | Demora en descarga | $/hora extra | Sí | | MANIOBRAS | Maniobra especial | Monto fijo | No | | ESCOLTA | Escolta | Monto fijo | No | | PERNOCTA | Pernocta | $/noche | No | | ESTADIAS | Días extra | $/día | No | | FALSO_FLETE | Viaje cancelado | % de tarifa | No | | SEGURO_ADICIONAL | Seguro extra | % sobre valor | Condición | --- ## Notas Técnicas - Endpoint: `POST /api/v1/facturas/:id/calcular-recargos` - Fuel surcharge se obtiene de `billing.fuel_surcharge` vigente - Detention se calcula desde datos de `tracking.eventos` (tiempo real) - Los ajustes se registran en auditoría con justificación --- ## Definición de Done - [ ] Cálculo automático de fuel surcharge - [ ] Cálculo de detention desde tiempos reales - [ ] Agregar recargos manuales del catálogo - [ ] Ajustar/eliminar recargos con justificación - [ ] Desglose de recargos en factura - [ ] Registro de ajustes en auditoría - [ ] Tests de cálculo de recargos