2026-07-20 — Reportes de back-office

Para el panel de administración (back-office).

Summary

El panel gana tres familias de reportes de solo lectura calculados sobre el ledger: órdenes, clientes y cisterneros. Cada listado devuelve { items, meta, totals } (o filas por período), acepta filtros por query, respeta el alcance por ciudad del admin y tiene un endpoint gemelo de exportación. Cada .../export acepta ?format=csv|xlsx (CSV por defecto). Los montos se reportan en USD.

Algunas columnas dependen de datos que el esquema aún no captura (horas en línea del conductor y notificaciones por pedido); se devuelven como null y sus filtros se omiten hasta que se instrumente ese registro.

New

Reportes de órdenes (AGU-ADM-130/131/132)

Método	Endpoint	Rol	Para qué sirve
GET	`/admin/reports/orders`	admin	Reporte detallado de órdenes, una fila por pedido.
GET	`/admin/reports/orders/export`	admin	Exporta el detallado a CSV.
GET	`/admin/reports/orders/cancellations`	admin	Órdenes canceladas y expiradas, con quién canceló y recuperación.
GET	`/admin/reports/orders/cancellations/export`	admin	Exporta las cancelaciones a CSV.
GET	`/admin/reports/orders/operational`	admin	Consolidado operativo por día, con comparativo del período anterior.
GET	`/admin/reports/orders/operational/export`	admin	Exporta el operativo a CSV.

El rango de fechas admite hasta 30 días por consulta.

Reportes de clientes (AGU-ADM-140/141)

Método	Endpoint	Rol	Para qué sirve
GET	`/admin/reports/clients`	admin	Reporte detallado de clientes con sus métricas acumuladas.
GET	`/admin/reports/clients/export`	admin	Exporta el detallado a CSV.
GET	`/admin/reports/clients/retention`	admin	Actividad y retención por período (semana/mes).
GET	`/admin/reports/clients/retention/export`	admin	Exporta la retención a CSV.

La retención admite un rango de hasta 366 días.

Reportes de cisterneros (AGU-ADM-150/151/152)

Método	Endpoint	Rol	Para qué sirve
GET	`/admin/reports/drivers`	admin	Reporte detallado de cisterneros con métricas de actividad y finanzas.
GET	`/admin/reports/drivers/export`	admin	Exporta el detallado a CSV.
GET	`/admin/reports/drivers/documents`	admin	Documentación y KYC, una fila por conductor × documento, con semáforo.
GET	`/admin/reports/drivers/documents/export`	admin	Exporta la documentación a CSV.
GET	`/admin/reports/drivers/performance`	admin	Desempeño por conductor y período, con ranking configurable.
GET	`/admin/reports/drivers/performance/export`	admin	Exporta el desempeño a CSV.

El desempeño admite un rango de hasta 366 días.

Todos los reportes exigen token de admin (guards auth:admin + admin + scope.cities).
Errores: 422 ValidationError ante filtros inválidos o un rango de fechas mayor al permitido. El detalle de columnas y filtros de cada reporte está en la documentación de endpoints (/docs/endpoints/admin-reports-orders, /docs/endpoints/admin-reports-clients, /docs/endpoints/admin-reports-drivers).