#Page 1

#Modelo: Caja Real vs. Previsión

El módulo de cashflow prioriza el flujo de caja real frente al devengo. La visualización permite identificar desviaciones entre lo facturado y lo que realmente se ha cobrado o pagado.

#Principios de diseño

• Caja real primero: Total Cobrado/Pagado (consolidado) representa los movimientos reales.
• Previsión como objetivo: Total Facturado (previsión) representa el importe esperado; la brecha frente a lo real indica deuda o impago.
• Eje temporal: Siempre agrupado por fecha de vencimiento, no por fecha de factura.
• Conciencia de deuda: El orden por riesgo de caja (morosidad/impago) coloca primero las empresas de mayor riesgo.

#Gráfica

#Visión general

La gráfica muestra ingresos (entradas) y gastos (salidas) con dos métricas visuales:

• Altura de la barra (objetivo): Previsión / valor contractual total — según fecha de vencimiento
• Relleno de la barra (actual): Consolidado / flujo de caja real recibido — según fecha de pago

#Métricas

#Previsión (Forecast)

• Definición: Valor contractual total de la factura (Base + IVA)
• Alcance: TODAS las facturas del período seleccionado (sin filtrar por estado pagado/pendiente)
• Uso en la barra: Determina la altura completa de la barra en el mes en que vence la factura
• Eje temporal: Fecha efectiva (ExpirationDate ?? Date cuando config DueDate; si no, Date)

#Consolidado (Consolidation)

• Definición: Flujo de caja real recibido (suma de pagos)
• Uso en la barra: Cada pago aparece en el mes en que se recibió (PaymentDate)
• Eje temporal: PaymentDate (fecha real de ejecución) — ignora la config de fecha de factura

#Reglas visuales

• Altura_Barra = invoice.total (previsión) en el mes de vencimiento
• Relleno_Barra = pagos recibidos ese mes (consolidación por PaymentDate)
• Si una factura tiene pagos en febrero y marzo: febrero muestra una barra de 1100; marzo muestra altura 2200 con relleno 300 (brecha = pendiente)

#Reglas técnicas (SQL / Lógica)

• Previsión: Facturas con effective_date BETWEEN start AND end, importe = total
• Consolidación: Pagos con PaymentDate BETWEEN start AND end, importe = importe del pago (distribuido por proyecto)
• Fecha efectiva: ExpirationDate ?? Date cuando config DueDate; si no, Date (config InvoiceDate)

#Configuración

• InvoiceDateSource: InvoiceDate usa fecha de factura; DueDate usa ExpirationDate ?? Date
• InvoiceAmountSource: Payments usa el desglose (Previsión = total, Consolidación = cobrado); InvoiceAmount usa solo Consolidado con total, sin previsión

#Entradas vs Salidas

• Entradas (facturas de venta): Misma lógica — Previsión por fecha de vencimiento, Consolidación por PaymentDate.
• Salidas (facturas de gasto/empresa): Misma lógica — Previsión por fecha efectiva (total), Consolidación por PaymentDate (cada pago en el mes pagado).

#Tabla

#Estructura

• Jerarquía (sin filtros): Empresa (nivel 0) → Proyectos (nivel 1, expandible, oculto por defecto).
• Jerarquía con filtro de empresa: Igual que sin filtros (Empresa → Proyecto); solo cambia el conjunto de datos.
• Jerarquía con filtro de proyecto (o empresa + proyecto): Solo filas de empresa con importes agregados para ese alcance; no se listan proyectos como hijos.
• Celda dual: Cada mes muestra:
  • Arriba (negrita): Importe real (Cobrado/Pagado).
  • Abajo (gris): Total Facturado.
• Indicador de deuda: Punto rojo cuando Real < Facturado en un mes pasado (vencido).
• Valores cero: Se muestran como '-' en lugar de '0 €'.

#Resumen ejecutivo (cabecera)

• Flujo de caja neto: SUM(Cobros reales) − SUM(Pagos reales) por mes.
• Saldo de apertura: Saldo acumulado arrastrado del mes anterior dentro del rango seleccionado.

#Ordenación

• Empresas ordenadas por Riesgo de caja (mayor deuda vencida arriba): primero las de mayor deuda vencida.

#Filtros de alcance

Parámetros opcionales en GetCashFlowData y GetCashFlowMonthDetail:

Nóminas: excluidas si ProjectId o CompanyId tienen valor (excludesPayroll).

Detalle mensual: con ProjectId → BuildProjectScopedMonthDetailAsync; con CompanyId (sin proyecto) → BuildCompanyScopedMonthDetailAsync; si hay ambos, prevalece el alcance por proyecto.

Ver Filtros de alcance (guía de usuario).