# 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

1. **Factura automatizada:** Generar facturas desde viajes cerrados con POD
2. **Recargos automáticos:** Aplicar fuel surcharge, detention, maniobras
3. **Trazabilidad completa:** Vincular factura con viajes, POD y evidencias
4. **CFDI timbrado:** Integración con PAC para factura electrónica
5. **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](./ENTITIES.md)

---

## Requerimientos Funcionales

Ver archivo: [REQUERIMIENTOS.md](./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/](./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*