> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unitedpetroleum.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporte por período

> Informe multi-día de rendimiento: distancias vendor/GPS, carga previa, bandas de marca, Excel y PDF

# Reporte de rendimiento por período

Cuando el rango de fechas tiene **más de un día**, la pantalla pasa al modo **Reporte de Rendimiento**: consolidado por vehículo para la semana, quincena o mes.

Complementa al [reporte diario de rutas](/combustible/reporte-diario). El diario es tanque-a-tanque + telemática del día; el período responde “¿cuántos km por galón compramos en este intervalo?”.

***

## Cómo generar el reporte

<Steps>
  <Step title="Abrir la pantalla">
    `/paso-rapido/dashboard/combustible/reporte-rendimiento`
  </Step>

  <Step title="Elegir un rango">
    Fecha inicio ≠ fecha fin. Presets útiles: **Últimos 7 días**, **Este mes**, **Mes pasado**.
  </Step>

  <Step title="Incluir última carga previa">
    Por defecto **activado**. Trae la última carga anterior al inicio (hasta 45 días) para no cortar el primer tanque a mitad.
  </Step>

  <Step title="Filtrar marca, flota y vehículos">
    Vacío en vehículos = todas las unidades con cargas en el rango (según marca/flota).
  </Step>

  <Step title="Generar reporte">
    Pulse **Generar reporte** y revise KPIs, gráficos y tabla.
  </Step>
</Steps>

***

## Qué calcula el motor

API `POST /api/fuel-performance`, lógica en el cálculo de rendimiento del producto:

1. Carga todas las entradas del período por vehículo.
2. Resuelve flota, marca y overlays del vehículo (bandas min/máx, ralentí).
3. **Distancia GPS del período:** primer y último odómetro de eventos GPS en el rango (no solo el GPS de las cargas).
4. **Distancia vendor:** primer → último `odometer_reading` de las cargas del período (ajustado si hay carry-in).
5. Detecta irregularidades (una sola carga, GPS faltante, reset de odómetro, outliers de distancia o economía).
6. Sugiere fuente de distancia:
   * Si el vendor está dañado (reset / unusable) → GPS si sirve; si no, vendor; si no, ninguna.
   * Si el vendor es usable → **prioriza vendor**.
   * Si no → GPS si sirve.
7. Economía = distancia efectiva / galones totales del período.

```mermaid theme={null}
flowchart TD
  A["Cargas en el rango"] --> B{"¿Incluir carga previa?"}
  B -->|Sí| C["Odómetro inicio = carga previa ≤45d"]
  B -->|No| D["Odómetro inicio = primera carga del rango"]
  C --> E["Distancias vendor + GPS"]
  D --> E
  E --> F["Detectar irregularidades"]
  F --> G["Sugerir fuente"]
  G --> H["km/gal = distancia / galones"]
  H --> I["Comparar vs banda marca min–máx"]
```

***

## KPIs

| KPI | Cómo leerlo |
| - | - |
| **Total combustible** | Suma de galones de todos los vehículos del resultado. |
| **Rendimiento prom.** | Distancia efectiva total / galones totales (solo donde hay distancia > 0). |
| **Distancia total** | Suma de km efectivos. |

Los gráficos ayudan a ver dispersión entre unidades; la tabla es la fuente de verdad para ajustes.

***

## Tabla por vehículo

| Columna | Significado |
| - | - |
| **Vehículo** | Ficha / placa. |
| **Modelo / Tipo / Flota / Marca** | Contexto de la unidad y su banda de eficiencia. |
| **Usar GPS** | Toggle: fuerza fuente GPS vs vendor. |
| **Distancia (km)** | Clic abre el editor (rango GPS o km manual). |
| **Galones** | Suma de cargas en el período. |
| **km/G** | Economía efectiva; color según banda de la marca y reglas de “smart buckets”. |
| **Benchmark** | Mini rango visual vs `fuel_efficiency_min`–`max`. |
| **Entradas** | Cantidad de cargas. |

Al expandir una fila verá el detalle de cargas (deltas vendor/GPS por entrada).

### Buckets de revisión (UI)

La interfaz clasifica filas para priorizar trabajo, por ejemplo:

* **ok** — datos coherentes.
* **gps\_out\_of\_range** / **needs\_review** — poca distancia GPS, pocas cargas, pocos galones, o economía fuera de banda (con holguras blandas/duras).

Umbrales internos de referencia (producto): distancia GPS mínima \~1 km para auto, mínimo ~~2 cargas y ~~5 galones para sugerencias automáticas; holgura blanda sobre el máximo de banda (~~+8 km/G) y dura (~~+100 km/G) para marcar anomalías extremas.

***

## Editor de distancia

Use el editor cuando:

* El odómetro vendor se reinició o saltó.
* El GPS del período está incompleto pero tiene un tramo confiable.
* Hay evidencia externa (bitácora) que justifica un km manual.

Al confirmar, la fuente efectiva puede quedar en **manual** o **gps** según lo elegido. Eso alimenta el km/G mostrado y las exportaciones.

***

## Exportar Excel y PDF

Disponible **solo en modo período** (no en el diario de rutas).

### Excel (hojas típicas)

| Hoja | Contenido |
| - | - |
| Resumen | KPIs del período. |
| Vehículos | Filas con distancias y economías. |
| Ajustes | Ediciones aplicadas. |
| Cargas | Detalle de entradas usadas. |

### PDF

Plantilla de informe de rendimiento para archivo / envío formal.

<Tip>
  Genere, corrija distancias dudosas, **guarde** la configuración y luego exporte. Así el Excel refleja los mismos ajustes que la pantalla.
</Tip>

***

## Guardar configuración

Igual que el diario: máximo **3** configs por organización. En modo período guarda:

* Filtros y flag de carga previa.
* Ediciones por vehículo (`vehicle_edits`).
* Opcionalmente un snapshot de estadísticas para reabrir rápido.

Deep link: `?configId=CONFIG_ID`.

***

## Irregularidades que debe reconocer

| Señal | Interpretación típica |
| - | - |
| `single_fill` | Solo una carga en el período: economía frágil. |
| `missing_gps` | Sin apoyo GPS. |
| `negative_delta` / `vendor_reset` | Odómetro vendor inconsistente; pruebe GPS o manual. |
| `vendor_unusable` | Vendor descartado por reglas de distancia máxima escalada al tamaño del período. |
| `distance_outlier` | Km improbables vs techo (\~15 000 km/mes prorrateado). |
| `economy_outlier` | km/G fuera de la banda de marca con buffer (\~35 %). |
| `carry_in_used` | Se usó carga previa (informativo). |

La distancia máxima de referencia escala con los días del período a partir de un techo mensual de **15 000 km**.

***

## Diferencias clave vs el reporte diario

| Tema | Diario (jornada) | Período |
| - | - | - |
| Unidad de análisis | Línea = carga del día vs carga previa | Fila = vehículo en el rango |
| Viajes / ralentí / ECO | Sí, en la tabla | No (use diario o reportes de flota) |
| Preferencia de distancia | GPS → vendor | Vendor usable → GPS |
| Carry-in 45 días | Cadena para hallar carga previa de cada línea | Flag explícito de carga previa al inicio |
| Export Excel/PDF | No | Sí |
| Meta | PARAM + umbrales % | Banda min–máx de marca |

Siguiente: [cómo interpretar y actuar](/combustible/interpretacion).