Adrian Flores Cortes 569eaeb5a4 docs: Add MAI-009 (Facturación) and MAI-010 (Liquidaciones) specifications

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>

2026-01-27 02:05:03 -06:00

7.2 KiB

Raw Blame History

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

Esquemas de pago flexibles: Por km, por viaje, por porcentaje, por bono
Control de viáticos: Anticipos, comprobación, sobrantes
Deducciones documentadas: Multas, daños, faltantes con aprobación
Corte periódico: Semanal, quincenal con exportación a nómina
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

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/

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

7.2 KiB Raw Blame History