Cómo ver horas trabajadas por empleado
Consulta las horas efectivamente trabajadas por empleado en una ubicación y un periodo concretos, con resumen agregado, tabla por empleado y comparación de rangos.
En este artículo
El reporte de horas trabajadas ayuda a responsables de operaciones y encargados a revisar la actividad real del equipo sin salir de Reportes. La pantalla agrupa turnos, horas y empleados con actividad para los periodos seleccionados.
El cálculo se basa en eventos de calendario `staff_shift` que solapan el rango elegido. La acción es solo de consulta: no crea, corrige ni elimina turnos desde la tabla.
Antes de empezar
- Sesión iniciada en la app administrativa.
- Organización y ubicación activas; en el demo ES, Grupo Marea Demo y Marea Gran Via.
- Tener al menos uno de estos permisos de ubicación: `reports:view`, `tpv:view`, `tpv:use`, `catalog:view`, `reservation:view` o `staff:view`.
- Para ver resultados con datos, la ubicación debe tener empleados y `calendar_events` con `kind = "staff_shift"` que solapen el periodo seleccionado.
Instrucciones
- 1.
Abre el reporte
Desde la ubicación, entra en Reportes > Empleados > Horas trabajadas o abre directamente `/:orgId/:locationId/reporting/employees/worked-hours`.
- 2.
Selecciona el periodo
Usa el selector de periodos para definir el rango. Si la URL no trae un periodo válido, la pantalla crea uno por defecto y actualiza `periods` con el formato `YYYY-MM-DD_YYYY-MM-DD`.
- 3.
Lee el resumen
Revisa las métricas Horas trabajadas, Turnos registrados y Empleados con actividad, calculadas con la zona horaria de la ubicación.
- 4.
Revisa la tabla por empleado
Consulta el bloque Por empleado para ver Nombre empleado, Horas trabajadas y Turnos. Si no se puede resolver el empleado, la fila aparece como `SIN ASIGNAR`.
- 5.
Compara periodos
Añade un segundo rango cuando quieras comparar semanas o ciclos operativos. Varios periodos viajan en `periods` separados por `~`.
- 6.
Exporta resultados en web
En web, abre el menú de exportación del resumen o la tabla y elige CSV, Excel o PNG. En plataformas nativas, la app muestra `Exportación no disponible`.
- 7.
Interpreta estados vacíos o errores
Si no hay horas para el filtro, la tabla muestra `No hay horas trabajadas para los filtros seleccionados.`; si la API falla, se muestra `No pudimos cargar los datos del reporte.`
Validaciones y límites
- La ruta `LocationReportsEmployeeWorkedHours` acepta `periods` como parámetro opcional de tipo string.
- El formato de `periods` es `YYYY-MM-DD_YYYY-MM-DD`; varios periodos se separan con `~`.
- Si la fecha final llega antes que la inicial, frontend y backend normalizan el rango al día inicial.
- La pantalla consume `GET /api/app/{orgId}/{locationId}/reports` y selecciona la página `employee-worked-hours`; no existe un endpoint dedicado solo para este reporte.
- El backend filtra `calendar_events` por ubicación, rango temporal y `kind = "staff_shift"`.
- Los turnos sin `starts_at` válido no aportan horas; si falta `ends_at`, el cálculo usa `time.Now().UTC()` como respaldo.
- Las filas se ordenan por horas del periodo más reciente en orden descendente y, si empatan, por clave.
- La tabla no ofrece búsqueda interna y la exportación solo está disponible en web.
Resultado esperado
El responsable obtiene una lectura clara de horas trabajadas, turnos registrados y actividad por empleado para el periodo revisado, sin modificar los turnos ni los datos de personal.