569eaeb5a4
MAI-009 Facturación Transporte (31 SP): - README, REQUERIMIENTOS (7 RF), RESUMEN-EPICA - 5 User Stories: generación factura, recargos, CFDI/Carta Porte, conciliación/pagos, estados de cuenta MAI-010 Liquidaciones (31 SP): - README, REQUERIMIENTOS (6 RF), RESUMEN-EPICA - 5 User Stories: esquemas pago, cálculo por viaje, viáticos, deducciones, generar/autorizar liquidación Part of Phase 2 - P0 Critical Modules specification Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
11 KiB
11 KiB
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_surchargevigente - 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