> For the complete documentation index, see [llms.txt](https://academy.trowelapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.trowelapp.com/informes/cashflow/page-1.md).

# 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`:

| Parámetro   | Efecto                                                                                                                                                |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CompanyId` | Filtra registros por empresa (cliente en ventas, proveedor en gastos; también presupuesto–planificación por `ClientCompanyId` / `SupplierCompanyId`). |
| `ProjectId` | Filtra por proyecto. Activa `companyLevelOnly` en `BuildMergedInvoiceCashflowDataHierarchical`.                                                       |

**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](/informes/cashflow/filtros-de-alcance.md) (guía de usuario).