# MAI-010: Liquidaciones a Operadores

**Version:** 1.0.0
**Fecha:** 2026-01-27
**Estado:** Diseño
**Prioridad:** P1 (Crítico - Pago a operadores)

---

## Descripción General

El módulo de Liquidaciones es responsable de calcular y gestionar los pagos a operadores (conductores) propios o terceros, incluyendo viáticos, bonos y deducciones.

**Problema que resuelve:**
- Cálculos manuales de pago propensos a errores
- Viáticos sin control ni comprobación
- Deducciones aplicadas inconsistentemente
- Falta de trazabilidad viaje → pago
- Retrasos en liquidación que afectan relación con operadores

---

## Objetivos del Módulo

1. **Esquemas de pago flexibles:** Por km, por viaje, por porcentaje, por bono
2. **Control de viáticos:** Anticipos, comprobación, sobrantes
3. **Deducciones documentadas:** Multas, daños, faltantes con aprobación
4. **Corte periódico:** Semanal, quincenal con exportación a nómina
5. **Trazabilidad completa:** Cada concepto ligado a viaje específico

---

## Alcance Funcional

### Incluido

- Configuración de esquemas de pago por operador
- Cálculo automático de monto por viaje
- Gestión de viáticos (anticipos y comprobación)
- Registro de deducciones con aprobación
- Bonos por cumplimiento de SLA
- Corte y autorización de liquidaciones
- Exportación a nómina/contabilidad

### Excluido

- Nómina completa (IMSS, ISR, prestaciones)
- Contratos laborales
- Reclutamiento de operadores

---

## Actores

| Actor | Rol en el módulo |
|-------|------------------|
| Operador | Consulta sus viajes y pagos |
| Liquidador | Calcula y procesa liquidaciones |
| Supervisor | Aprueba deducciones y bonos |
| Contador | Exporta a nómina, concilia |
| Sistema | Calcula montos automáticamente |

---

## Flujo Principal

```
VIAJES CERRADOS (con POD)
      │
      ▼
┌─────────────────────────────────────────┐
│ 1. CALCULAR PAGO POR VIAJE              │
│    - Según esquema del operador         │
│    - Por km, por viaje, % del flete     │
│    - Aplicar bonos si cumplió SLA       │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 2. REGISTRAR VIÁTICOS                   │
│    - Anticipos entregados               │
│    - Comprobación de gastos             │
│    - Sobrantes a descontar              │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 3. APLICAR DEDUCCIONES                  │
│    - Multas de tránsito                 │
│    - Daños a unidad/carga               │
│    - Faltantes de mercancía             │
│    - Con aprobación de supervisor       │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 4. GENERAR LIQUIDACIÓN                  │
│    - Acumular por periodo (semana)      │
│    - Desglose de conceptos              │
│    - Total a pagar                      │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 5. AUTORIZAR Y EXPORTAR                 │
│    - Revisión por supervisor            │
│    - Firma del operador                 │
│    - Exportar a nómina                  │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│         LIQUIDACIÓN PAGADA              │
│    → Registrada en contabilidad         │
└─────────────────────────────────────────┘
```

---

## Datos del Módulo

### Entidades Principales

| Entidad | Descripción | Estado |
|---------|-------------|--------|
| EsquemaPago | Configuración de pago por operador | NO IMPLEMENTADA |
| ConceptoLiquidacion | Líneas de la liquidación | NO IMPLEMENTADA |
| Liquidacion | Documento de pago | NO IMPLEMENTADA |
| Viatico | Anticipo y comprobación | NO IMPLEMENTADA |
| Deduccion | Descuentos aplicados | NO IMPLEMENTADA |

### Campos Clave Liquidación

| Campo | Tipo | Obligatorio | Descripción |
|-------|------|-------------|-------------|
| operador_id | UUID | Sí | Operador |
| periodo_inicio | DATE | Sí | Inicio del periodo |
| periodo_fin | DATE | Sí | Fin del periodo |
| total_viajes | DECIMAL | Sí | Suma de pagos por viaje |
| total_viaticos | DECIMAL | Sí | Viáticos netos |
| total_deducciones | DECIMAL | Sí | Deducciones aplicadas |
| total_bonos | DECIMAL | Sí | Bonos ganados |
| total_pagar | DECIMAL | Sí | Neto a pagar |
| estado | ENUM | Sí | BORRADOR, PENDIENTE, AUTORIZADA, PAGADA |

---

## Requerimientos Funcionales

Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)

---

## Esquemas de Pago

| Tipo | Descripción | Ejemplo |
|------|-------------|---------|
| Por km | Pago por kilómetro recorrido | $2.50/km |
| Por viaje | Monto fijo por viaje | $1,500/viaje |
| Porcentaje | % del flete cobrado | 25% del flete |
| Por bono | Adicional por cumplimiento | $500 si OTIF |
| Mixto | Combinación | Base + km + bono |

---

## Métricas del Módulo

| KPI | Fórmula | Meta |
|-----|---------|------|
| Tiempo de liquidación | Avg(fecha_pago - fecha_cierre) | <5 días |
| Precisión de cálculo | % liquidaciones sin ajuste | >98% |
| Viáticos comprobados | % viáticos con recibos | >90% |
| Deducciones aprobadas | % deducciones con autorización | 100% |

---

## Dependencias

### Este módulo depende de:
- MAI-007 (POD): Viajes cerrados
- MAI-006 (Tracking): Kilometraje real
- MAI-011 (Flota): Datos de operadores
- MAI-002 (Tarifas): Flete para % de pago

### Otros módulos dependen de este:
- erp-core/financial: Exportación a contabilidad
- erp-core/nomina: Integración con nómina

---

## Historias de Usuario

Ver carpeta: [historias-usuario/](./historias-usuario/)

| US | Título | Prioridad |
|----|--------|-----------|
| US-MAI010-001 | Configurar esquema de pago | Alta |
| US-MAI010-002 | Calcular pago por viaje | Alta |
| US-MAI010-003 | Gestionar viáticos | Alta |
| US-MAI010-004 | Aplicar deducciones | Media |
| US-MAI010-005 | Generar y autorizar liquidación | Alta |

---

*Módulo MAI-010 - ERP Transportistas - Sistema SIMCO v4.0.0*