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>
206 lines
7.2 KiB
Markdown
206 lines
7.2 KiB
Markdown
# 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*
|