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>
194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
# US-MAI010-002: Calcular pago por viaje
|
||
|
||
**ID:** US-MAI010-002
|
||
**Módulo:** MAI-010 (Liquidaciones)
|
||
**Prioridad:** Alta
|
||
**Story Points:** 8
|
||
|
||
---
|
||
|
||
## Historia de Usuario
|
||
|
||
**Como** sistema de liquidaciones
|
||
**Quiero** calcular automáticamente el monto a pagar por cada viaje cerrado
|
||
**Para** que el liquidador tenga los montos listos sin cálculos manuales
|
||
|
||
---
|
||
|
||
## Criterios de Aceptación
|
||
|
||
### CA-001: Calcular al cerrar viaje
|
||
**Dado** que un viaje se cierra con POD
|
||
**Cuando** se confirma el cierre
|
||
**Entonces** el sistema calcula automáticamente el pago del operador
|
||
|
||
### CA-002: Aplicar esquema del operador
|
||
**Dado** que el operador tiene un esquema asignado
|
||
**Cuando** se calcula el pago
|
||
**Entonces** se aplica la fórmula correspondiente (km, %, fijo)
|
||
|
||
### CA-003: Usar km reales
|
||
**Dado** que el esquema es por km
|
||
**Cuando** se calcula
|
||
**Entonces** se usan los km reales del tracking, no los estimados
|
||
|
||
### CA-004: Calcular bonos automáticamente
|
||
**Dado** que el viaje cumplió condiciones de bono
|
||
**Cuando** se calcula el pago
|
||
**Entonces** se agrega el bono correspondiente (OTIF, sin incidencias)
|
||
|
||
### CA-005: Mostrar desglose
|
||
**Dado** que se calculó el pago
|
||
**Cuando** consulto el detalle
|
||
**Entonces** veo el desglose: base, variable, bonos, total
|
||
|
||
### CA-006: Ajuste manual
|
||
**Dado** que hay situaciones excepcionales
|
||
**Cuando** necesito ajustar el monto
|
||
**Entonces** puedo hacerlo con justificación obligatoria
|
||
|
||
---
|
||
|
||
## Mockup / UI
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ PAGO CALCULADO - VJE-0125 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Viaje: VJE-0125 | CDMX → Monterrey │
|
||
│ Operador: Juan Pérez García │
|
||
│ Esquema: ESQ-002 (25% del flete + bonos) │
|
||
│ │
|
||
│ ───────────────────────────────────────────────────────────── │
|
||
│ │
|
||
│ DATOS DEL VIAJE │
|
||
│ │
|
||
│ Fecha cierre: 2026-01-25 16:45 │
|
||
│ Flete facturado: $18,200.00 MXN │
|
||
│ Km recorridos (tracking): 892 km │
|
||
│ Tiempo en ruta: 11 hrs 32 min │
|
||
│ Entrega: ✓ A tiempo (dentro de ventana SLA) │
|
||
│ Incidencias: ✓ Sin incidencias │
|
||
│ │
|
||
│ ───────────────────────────────────────────────────────────── │
|
||
│ │
|
||
│ CÁLCULO DEL PAGO │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ PERCEPCIONES │ │
|
||
│ │ │ │
|
||
│ │ Pago por flete (25% de $18,200): $4,550.00 │ │
|
||
│ │ Bono OTIF (entrega a tiempo): $800.00 │ │
|
||
│ │ Bono sin incidencias: $300.00 │ │
|
||
│ │ ───────────────────────────────────────────────── │ │
|
||
│ │ TOTAL A PAGAR: $5,650.00 MXN │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Estado: ✓ CALCULADO | Pendiente de liquidación │
|
||
│ │
|
||
│ [Ajustar monto] [Ver detalles] │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Lista de Viajes por Liquidar
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ VIAJES PENDIENTES DE LIQUIDAR │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Operador: [Juan Pérez García ▼] │
|
||
│ Periodo: [20-ene-2026] al [26-ene-2026] │
|
||
│ │
|
||
│ ───────────────────────────────────────────────────────────── │
|
||
│ │
|
||
│ VIAJES CERRADOS ESTA SEMANA │
|
||
│ │
|
||
│ | Viaje | Ruta | Cierre | Pago | Estado |│
|
||
│ |---------|----------------|----------|-----------|----------|│
|
||
│ | VJE-0120| CDMX → GDL | 21-ene | $1,750.00 | Calculado|│
|
||
│ | VJE-0125| CDMX → MTY | 23-ene | $5,650.00 | Calculado|│
|
||
│ | VJE-0128| CDMX → GDL | 25-ene | $1,750.00 | Calculado|│
|
||
│ │
|
||
│ ───────────────────────────────────────────────────────────── │
|
||
│ │
|
||
│ RESUMEN │
|
||
│ Total viajes: 3 │
|
||
│ Total pagos: $9,150.00 │
|
||
│ │
|
||
│ [Generar liquidación semanal] │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Ajuste Manual
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ AJUSTAR PAGO ✕ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Viaje: VJE-0125 │
|
||
│ Pago calculado: $5,650.00 │
|
||
│ │
|
||
│ ───────────────────────────────────────────────────────────── │
|
||
│ │
|
||
│ AJUSTE │
|
||
│ │
|
||
│ Nuevo monto: [$5,000.00] │
|
||
│ Diferencia: -$650.00 │
|
||
│ │
|
||
│ Motivo del ajuste (obligatorio): │
|
||
│ [Viaje solicitó apoyo de otro operador para última ]│
|
||
│ [hora de entrega. Se comparte pago con OP-0032 ]│
|
||
│ │
|
||
│ Autoriza: [Supervisor requerido ▼] │
|
||
│ │
|
||
│ ⚠ Los ajustes quedan registrados en auditoría │
|
||
│ │
|
||
│ [Cancelar] [Guardar Ajuste] │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Cálculo por Tipo de Esquema
|
||
|
||
| Tipo | Fórmula | Ejemplo |
|
||
|------|---------|---------|
|
||
| Por km | km_reales × tarifa_km | 892 × $2.50 = $2,230 |
|
||
| Por viaje | tarifa_fija | $1,500 |
|
||
| Porcentaje | flete × % | $18,200 × 25% = $4,550 |
|
||
| Mixto | base + (km × tarifa) | $500 + (892 × $1.50) = $1,838 |
|
||
|
||
---
|
||
|
||
## Notas Técnicas
|
||
|
||
- El cálculo se dispara al evento `viaje.cerrado` (MAI-007)
|
||
- Km reales desde `tracking.eventos` (suma de tramos)
|
||
- Flete desde `billing.lineas_factura` vinculada al viaje
|
||
- Bonos se evalúan según condiciones del esquema
|
||
- Ajustes requieren aprobación si >10% del calculado
|
||
|
||
---
|
||
|
||
## Definición de Done
|
||
|
||
- [ ] Cálculo automático al cerrar viaje
|
||
- [ ] Soporte para los 4 tipos de esquema
|
||
- [ ] Uso de km reales desde tracking
|
||
- [ ] Cálculo automático de bonos
|
||
- [ ] Desglose detallado del pago
|
||
- [ ] Ajuste manual con justificación
|
||
- [ ] Auditoría de ajustes
|
||
- [ ] Tests de cálculo por tipo
|
||
|