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-009: Facturación de Transporte

Version: 1.0.0 Fecha: 2026-01-27 Estado: Diseño Prioridad: P1 (Crítico - Monetización)

Descripción General

El módulo de Facturación de Transporte es responsable de generar facturas CFDI por los servicios de transporte, aplicando tarifas, recargos y conectando con evidencias de entrega (POD).

Problema que resuelve:

Facturación manual lenta y propensa a errores
Recargos (demoras, fuel surcharge) no capturados
Falta de trazabilidad factura → viaje → POD
Conciliación difícil entre cotizado vs facturado vs cobrado
Aging de cartera sin visibilidad

Objetivos del Módulo

Factura automatizada: Generar facturas desde viajes cerrados con POD
Recargos automáticos: Aplicar fuel surcharge, detention, maniobras
Trazabilidad completa: Vincular factura con viajes, POD y evidencias
CFDI timbrado: Integración con PAC para factura electrónica
Gestión de cobranza: Estados de cuenta, aging, pagos

Alcance Funcional

Incluido

Facturación por viaje, por embarque o por OT
Cálculo automático de recargos (fuel, detention, etc.)
Integración con POD para adjuntar evidencias
Timbrado CFDI via PAC
Complemento Carta Porte (MAE-016)
Estados de cuenta por cliente
Registro de pagos y aging de cartera

Excluido

Cobranza judicial (CRM/Legal)
Contabilidad detallada (módulo financiero erp-core)
Carta Porte como documento independiente (MAE-016)

Actores

Actor	Rol en el módulo
Facturador	Crea y emite facturas
Contador	Revisa, aprueba, concilia
Cobranza	Seguimiento de pagos, aging
Cliente	Recibe factura, realiza pagos
Sistema PAC	Timbra CFDI

Flujo Principal

VIAJES CERRADOS (con POD)
      │
      ▼
┌─────────────────────────────────────────┐
│ 1. SELECCIONAR VIAJES A FACTURAR        │
│    - Filtrar por cliente/periodo        │
│    - Viajes con POD pendientes facturar │
│    - Selección individual o masiva      │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 2. GENERAR BORRADOR DE FACTURA          │
│    - Líneas automáticas desde viajes    │
│    - Aplicar tarifa de cada viaje       │
│    - Calcular subtotales                │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 3. APLICAR RECARGOS                     │
│    - Fuel surcharge automático          │
│    - Detention si aplica                │
│    - Maniobras, escoltas, etc.          │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 4. REVISAR Y AJUSTAR                    │
│    - Verificar montos                   │
│    - Aplicar descuento (si autorizado)  │
│    - Agregar notas/observaciones        │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 5. TIMBRAR CFDI                         │
│    - Generar XML con datos fiscales     │
│    - Incluir complemento Carta Porte    │
│    - Enviar a PAC                       │
│    - Recibir UUID y sellos              │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 6. ENVIAR AL CLIENTE                    │
│    - Email con PDF + XML                │
│    - Publicar en portal cliente         │
│    - Adjuntar POD si requiere           │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 7. SEGUIMIENTO DE COBRANZA              │
│    - Registrar pagos                    │
│    - Alertas de vencimiento             │
│    - Estados de cuenta                  │
└─────────────────────────────────────────┘

Datos del Módulo

Entidades Principales

Entidad	Descripción	Estado
Lane	Ruta origen-destino	IMPLEMENTADA
Tarifa	Precio por lane/servicio	IMPLEMENTADA
RecargoCatalogo	Tipos de recargos	IMPLEMENTADA
FacturaTransporte	Factura CFDI	IMPLEMENTADA
LineaFactura	Conceptos facturados	IMPLEMENTADA
FuelSurcharge	Índice de combustible	IMPLEMENTADA

Ver archivo: ENTITIES.md

Requerimientos Funcionales

Ver archivo: REQUERIMIENTOS.md

Integración con PAC

PAC	Tipo	Uso
Finkok	Primario	Timbrado, cancelación
SW Sapien	Respaldo	Failover

Servicios requeridos:

Timbrado de CFDI 4.0
Complemento Carta Porte 3.1
Cancelación de CFDI
Consulta de estatus

Métricas del Módulo

KPI	Fórmula	Meta
Días a facturar	Avg(fecha_factura - fecha_pod)	<3 días
Recargos capturados	% viajes con recargos aplicados	>95%
Facturas rechazadas	% facturas con error PAC	<2%
DSO	Días promedio de cobranza	<45 días

Dependencias

Este módulo depende de:

MAI-007 (POD): Viajes cerrados con evidencia
MAI-002 (Tarifas): Precios y recargos
MAE-016 (Carta Porte): Complemento CFDI
erp-core/partners: Datos fiscales del cliente

Otros módulos dependen de este:

erp-core/financial: Conciliación contable
MAI-015 (Portal Cliente): Consulta de facturas

Historias de Usuario

Ver carpeta: historias-usuario/

US	Título	Prioridad
US-MAI009-001	Generar factura desde viajes	Alta
US-MAI009-002	Aplicar recargos automáticos	Alta
US-MAI009-003	Timbrar CFDI con Carta Porte	Alta
US-MAI009-004	Gestionar conciliación y pagos	Media
US-MAI009-005	Generar estados de cuenta	Media

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

7.2 KiB Raw Blame History