Package com.gestorrh.api.service

Class FichajeService

java.lang.Object
com.gestorrh.api.service.FichajeService
@Service public class FichajeService extends Object
Servicio central para la gestión de fichajes y registros de jornada de los empleados.

Gestiona el ciclo completo de la jornada laboral: desde el registro de entrada con validación de geolocalización (geovallado) y detección de retrasos, hasta el registro de salida con cálculo automático de incidencias horarias.

Proporciona además funcionalidades críticas de auditoría para la modificación manual de fichajes por parte de gestores, garantizando la trazabilidad de cualquier alteración en el registro de tiempos.

  • Field Details

  • Constructor Details

    • FichajeService

      public FichajeService()

  • Method Details

    • ficharEntrada

      @Transactional public RespuestaFichajeDTO ficharEntrada(PeticionFichajeEntradaDTO peticion)
      Registra un nuevo inicio de jornada (fichaje de entrada) para el empleado autenticado.

      El flujo de ejecución realiza las siguientes validaciones críticas:

      1. Configuración de Sede: Verifica que la empresa haya configurado sus coordenadas GPS y radio de validez.
      2. Fichaje Duplicado: Impide abrir una nueva jornada si ya existe un registro abierto (sin hora de salida) para hoy.
      3. Geovallado: Si el turno asignado es de modalidad presencial, valida que la ubicación GPS recibida esté dentro del radio permitido respecto a la sede.
      4. Control de Puntualidad: Compara la hora actual con el inicio del turno asignado (incluyendo un margen de cortesía de 15 minutos) para detectar posibles retrasos.
      Parameters:
      peticion - Objeto PeticionFichajeEntradaDTO con las coordenadas GPS (latitud y longitud) del empleado.
      Returns:
      RespuestaFichajeDTO con los detalles del registro creado satisfactoriamente.
      Throws:
      RuntimeException - Si se detecta una violación de geolocalización o si el estado del empleado/empresa es inválido para operar.

    • ficharSalida

      @Transactional public RespuestaFichajeDTO ficharSalida(PeticionFichajeSalidaDTO peticion)
      Finaliza la jornada laboral actual registrando el fichaje de salida.

      Calcula posibles incidencias por salida anticipada si el empleado cierra el turno antes de la hora prevista.

      Parameters:
      peticion - DTO con las coordenadas GPS del momento de salida.
      Returns:
      RespuestaFichajeDTO con la información actualizada incluyendo la hora de salida.
      Throws:
      RuntimeException - Si no hay ninguna entrada abierta para el día de hoy.

    • consultarFichajes

      @Transactional(readOnly=true) public List<RespuestaFichajeDTO> consultarFichajes(LocalDate fechaInicio, LocalDate fechaFin, Long empleadoIdFiltro)
      Consulta el historial de fichajes bajo un rango de fechas y filtros opcionales.

      La visibilidad de los datos depende del rol: - EMPRESA: Ve todos los fichajes de su plantilla. - SUPERVISOR: Ve fichajes de su departamento. - EMPLEADO: Ve únicamente sus propios registros.

      Parameters:
      fechaInicio - Fecha de inicio de la búsqueda.
      fechaFin - Fecha de fin de la búsqueda.
      empleadoIdFiltro - Identificador opcional para filtrar por un empleado concreto.
      Returns:
      List de RespuestaFichajeDTO con los registros localizados.

    • modificarFichajeManual

      @Transactional public RespuestaFichajeDTO modificarFichajeManual(Long idFichaje, PeticionModificacionFichajeDTO peticion)
      Permite a una empresa o supervisor modificar manualmente las horas de un fichaje ya registrado.

      Esta operación está estrictamente auditada y requiere un motivo justificado. Los supervisores no pueden modificar sus propios fichajes.

      Parameters:
      idFichaje - Identificador del registro a modificar.
      peticion - DTO con las nuevas horas y el motivo de la modificación.
      Returns:
      RespuestaFichajeDTO con el registro actualizado y la marca de auditoría en incidencias.
      Throws:
      RuntimeException - Si la modificación viola reglas de seguridad o jurisdicción de roles.

    • obtenerEmpleadoAutenticado

      private Empleado obtenerEmpleadoAutenticado()

    • validarSedeConfigurada

      private void validarSedeConfigurada(Empresa empresa)

    • validarGeovalladoSiEsPresencial

      private void validarGeovalladoSiEsPresencial(Empleado empleado, AsignacionTurno asignacionActual, PeticionFichajeEntradaDTO peticion)

    • evaluarRetrasoEntrada

      private String evaluarRetrasoEntrada(AsignacionTurno asignacion, LocalDateTime ahora, Empleado empleado)

    • evaluarSalidaAnticipada

      private String evaluarSalidaAnticipada(AsignacionTurno asignacion, LocalDateTime ahora, Empleado empleado, String incidenciasPrevias)

    • consultarFichajesComoEmpresa

      private List<Fichaje> consultarFichajesComoEmpresa(String emailAuth, LocalDate fechaInicio, LocalDate fechaFin, Long empleadoIdFiltro)

    • consultarFichajesComoSupervisor

      private List<Fichaje> consultarFichajesComoSupervisor(String emailAuth, LocalDate fechaInicio, LocalDate fechaFin, Long empleadoIdFiltro)

    • consultarFichajesComoEmpleado

      private List<Fichaje> consultarFichajesComoEmpleado(String emailAuth, LocalDate fechaInicio, LocalDate fechaFin)

    • validarPermisosModificacion

      private void validarPermisosModificacion(Fichaje fichaje, String emailAuth, boolean esEmpresa)

    • mapearARespuesta

      private RespuestaFichajeDTO mapearARespuesta(Fichaje f)