Time clock

Para qué sirve y para quién

Es el registro de jornada del negocio. Cada persona del equipo ficha la entrada al llegar y la salida al irse, con sus pausas en medio, con un toque y sin elegir nada: quien ficha es la persona de la sesión, por la ficha de Personal vinculada a su cuenta. El responsable ve las jornadas de todo el equipo, corrige las que están mal (siempre con un motivo, que queda en el historial) y saca el mes en CSV para la gestoría o la Inspección de Trabajo.

En España todo negocio con empleados tiene que registrar el inicio y el fin de cada jornada, guardarlo cuatro años y tenerlo a disposición del trabajador, de sus representantes y de la Inspección (art. 34.9 del Estatuto de los Trabajadores, Real Decreto-ley 8/2019). Por eso:

• Ninguna jornada se borra, y una jornada solo cambia con una corrección con motivo, que deja una fila nueva en su historial que tampoco se borra ni se edita.
• El trabajador ve sus propias jornadas y quién las corrigió, cuándo y por qué.

Quién la usa:

• El empleado ficha la entrada, la salida y sus pausas, ve sus jornadas, su historial de correcciones y los ajustes (sin poder cambiarlos), y exporta sus jornadas en CSV.
• El responsable, el administrador y el propietario además ven las jornadas de todo el equipo y quién está dentro ahora, corrigen jornadas con motivo, fichan la entrada o la salida de otra persona (por el asistente o la API: «ficha la salida de Ana») y cambian los ajustes.

Referencia adoptada

• Odoo Asistencias, Square Team, Toast y Lightspeed: una jornada es una entrada y una salida de una persona, con pausas dentro; una sola jornada abierta por persona.
• Toast y Square: el encargado edita una jornada con rastro (antes, después, quién y por qué).
• Square, Factorial y Homebase: el radio del lugar de trabajo se exige solo a los dispositivos personales; el TPV del mostrador nunca pide la ubicación, y la salida nunca se bloquea.
• Homebase y Deputy: el encargado puede fichar la entrada o la salida de alguien de su equipo, y queda quién lo hizo.
• El fichaje no calcula nóminas ni horas extra: eso, en el mercado, es otro producto.

Antes de empezar

1. La app Personal encendida: el fichaje es de una ficha de Personal (Control horario la necesita y la enciende con ella).
2. Cada persona que vaya a fichar tiene su ficha en Personal vinculada a su cuenta («Usuario del Hub», STAFF-F03). Una cuenta sin ficha vinculada ve «Tu usuario no está vinculado a ninguna ficha de Personal» y no puede fichar.
3. Si se quiere exigir que el móvil esté en el local, un responsable lo activa en Ajustes y fija la ubicación del local (ATTENDANCE-F04). Por defecto no se pide ninguna ubicación.

Pantallas

Fichar

Se llega desde el menú de la app, «Fichar». Arriba, «Hola, » y «Son las »; en el centro, el estado («No has fichado la entrada», «Dentro desde las 09:00», «En pausa desde las 13:00»), el tiempo que lleva desde la entrada, que corre solo, y el botón grande del momento: «Fichar entrada», o «Empezar pausa» / «Terminar pausa» y «Fichar salida». A la derecha (debajo en el móvil), «Hoy» (Trabajado y Pausas, que corren solos) y «Últimas jornadas» (las diez últimas, con su estado: «En curso», «Cerrada», «Por revisar»). La puede abrir cualquier persona del equipo.

Registros

Se llega desde el menú de la app, «Registros». Una tabla de las jornadas del mes elegido: Fecha, Persona, Entrada, Salida, Pausas (min), Trabajado, Estado y Ubicación, con las acciones «Corregir» e «Historial» en cada fila; en el móvil, tarjetas. Un empleado ve solo las suyas (sin columna Persona, con «Historial»); el responsable ve las de todo el equipo con los filtros «Persona» (con buscador), «Mes» y «Estado», y encima de la tabla «Fichados ahora»: cuántas personas tienen la jornada abierta y quiénes, desde qué hora y si están en pausa. Arriba, «Exportar CSV».

Ajustes

La pestaña «Ajustes» de la app. «Pedir la ubicación al fichar desde un dispositivo personal», «Radio permitido», «Ubicación del lugar de trabajo» (Latitud, Longitud y «Usar mi ubicación actual») y «Marcar a revisar tras (horas)». Solo un responsable o un administrador puede guardar; los demás la ven en solo lectura con «Solo un responsable o un administrador puede cambiar estos ajustes.».

Estados de cada pantalla

En las tres páginas: «Reconectando…» mientras el directo se recupera (lo pintado se queda), «Esta app no está activa en este negocio» si se apaga y «No tienes permiso» si el papel no llega.

Flujos

ATTENDANCE-F01 Fichar la entrada al llegar y la salida al irse

Actor: propietario, administrador, responsable, empleado Pantalla: Fichar Pasos: 1. Abre Control horario → «Fichar». Ve «No has fichado la entrada» y el botón «Fichar entrada». 2. Pulsa «Fichar entrada». Ve «Entrada fichada a las 09:00.», «Dentro desde las 09:00» y el tiempo que lleva desde la entrada, que corre solo. 3. Al acabar, pulsa «Fichar salida». Ve «Salida fichada a las 17:00.» y vuelve el botón «Fichar entrada». 4. En «Hoy» sale el tiempo trabajado y en «Últimas jornadas» la jornada, «Cerrada». 5. Una jornada que cruza la medianoche (de 22:00 a 06:00) es una sola y cuenta entera en el día en que empezó (el día del negocio, no el del dispositivo). Entra: la persona de la sesión y su ficha de Personal. Sale: la jornada guardada con la hora del servidor, abierta al entrar y cerrada al salir; los avisos de entrada y de salida; «Fichados ahora» sube y baja. Si falla: fichar la entrada con una jornada ya abierta se rechaza con «Ya tienes una jornada abierta: ficha la salida antes de volver a entrar.» y la pantalla enseña la jornada abierta (dos toques a la vez dejan una sola jornada); sin ficha vinculada, «Tu usuario no está vinculado a ninguna ficha de Personal: pide a un responsable que la vincule en Personal.»; con la ficha inactiva o de baja temporal, «Esa ficha de Personal no está activa (inactiva o de baja temporal): no puede fichar la entrada.» (la salida sí se ficha); sin conexión, el error y «Reintentar».

ATTENDANCE-F02 Hacer una pausa sin salir de la jornada

Actor: propietario, administrador, responsable, empleado Pantalla: Fichar Pasos: 1. Con la jornada abierta, pulsa «Empezar pausa». Ve «Pausa iniciada a las 13:00.» y «En pausa desde las 13:00»; el botón pasa a «Terminar pausa». 2. A la vuelta, pulsa «Terminar pausa». Ve «Pausa terminada a las 13:30.». 3. Puede hacer tantas pausas como quiera, una detrás de otra. 4. Si pulsa «Fichar salida» en plena pausa, la pausa se termina en ese mismo momento. 5. En «Hoy», «Pausas» suma el tiempo de pausa y «Trabajado» ya lo descuenta. Entra: la jornada abierta de la persona (ATTENDANCE-F01). Sale: cada pausa guardada dentro de su jornada; los avisos de pausa empezada y terminada. Si falla: sin jornada abierta, «No hay ninguna jornada abierta: ficha la entrada primero.»; con una pausa ya en curso, «Ya hay una pausa en curso.»; terminar una pausa que no existe, «No hay ninguna pausa en curso que terminar.»; en una jornada olvidada (ATTENDANCE-F05), «Esta jornada lleva abierta más de 12 horas y está por revisar…».

ATTENDANCE-F03 Fichar desde el móvil cuando el negocio pide la ubicación

Estado: parcial — saber si un dispositivo es el TPV compartido o el móvil de alguien es de la plataforma, que lo traerá con el PIN y el dispositivo de confianza (fase 2), y nunca lo dice la petición (ni la pantalla, ni el asistente, ni la API). Hasta entonces todo dispositivo ficha como el compartido, no se pide ninguna ubicación y Ajustes deja «Pedir la ubicación…» desactivado diciendo por qué. Lo que sigue está hecho y probado en el servidor y en la pantalla, a la espera de ese dato. Actor: propietario, administrador, responsable, empleado Pantalla: Fichar Pasos: 1. El negocio tiene activado «Pedir la ubicación al fichar desde un dispositivo personal» (ATTENDANCE-F04) y la persona usa su propio móvil o portátil. 2. Pulsa «Fichar entrada». Ve «Obteniendo tu ubicación…»; la primera vez el móvil pide permiso. 3. Dentro del radio, ficha como siempre y la jornada guarda la posición, la precisión y la distancia al local, que calcula el Hub (no se fía de la que diga el dispositivo). 4. Fuera del radio no ficha y lo dice: «Estás a 850 m del lugar de trabajo, fuera de los 100 m permitidos. Acércate para fichar o ficha en el mostrador.». 5. La salida nunca se bloquea: se guarda la posición si se puede y, si no, se ficha igual. 6. En el TPV del mostrador nunca se pide la ubicación, aunque el ajuste esté activado. Entra: los ajustes de ubicación (ATTENDANCE-F04) y el modo del dispositivo. Sale: la jornada con la distancia, la precisión y si estaba dentro del radio, solo en el momento de fichar; las coordenadas exactas, solo cuando el negocio pide la ubicación y el dispositivo es personal (nunca se guardan si nadie las pidió). Se conservan lo que la jornada: cuatro años. En Registros, la columna «Ubicación» enseña dentro o fuera. Si falla: con el permiso denegado, «El acceso a la ubicación está denegado…»; sin la ubicación del local fijada, «Aún no se ha fijado la ubicación del lugar de trabajo…»; sin posición, «Hace falta tu ubicación para fichar desde este dispositivo…»; si el GPS tarda más de 15 segundos, «Obtener tu posición ha tardado demasiado. Vuelve a intentarlo.». En todos los casos no se ficha y se puede fichar en el mostrador.

ATTENDANCE-F04 Ajustar la ubicación del local y cuándo se revisa una jornada olvidada

Actor: propietario, administrador, responsable Pantalla: Ajustes Pasos: 1. Abre Control horario → «Ajustes». 2. Activa «Pedir la ubicación al fichar desde un dispositivo personal» (desactivado, con su motivo, mientras el Hub no distinga los dispositivos: ATTENDANCE-F03) y elige el «Radio permitido»: 50, 100, 250, 500 o 1000 m. 3. Desde el propio local, pulsa «Usar mi ubicación actual»: se rellenan la latitud y la longitud y ve la precisión leída. También puede escribirlas a mano. 4. En «Marcar a revisar tras (horas)» pone de 1 a 24 horas (12 si no lo toca). 5. Pulsa «Guardar» y ve «Ajustes guardados.». Solo se envía lo que cambió. Entra: nada de otras apps; sin ajustes guardados se ven los valores por defecto. Sale: los ajustes que leen Fichar (ATTENDANCE-F03) y la revisión de jornadas (ATTENDANCE-F05); el aviso de ajustes cambiados. Si falla: una latitud o longitud fuera de rango, solo una de las dos o unas horas que no son un entero de 1 a 24 se señalan en su campo; con la ubicación pedida y el local sin fijar, avisa «Fija la ubicación del lugar de trabajo o nadie podrá fichar desde un dispositivo personal.»; quien no es responsable ve los ajustes en solo lectura.

ATTENDANCE-F05 Marcar para revisar una jornada que nadie cerró

Actor: sistema Pantalla: ninguna (la insignia «Por revisar» sale en Fichar y en Registros) Pasos: 1. Una jornada abierta más horas de las fijadas en Ajustes (12 por defecto) es una jornada olvidada: la persona olvidó fichar la salida. Desde ese momento se ve «Por revisar» en todas partes (Fichar, Registros, el CSV), sin tiempo trabajado, y no cuenta como «Fichados ahora». La tarea programada (cada 15 minutos, en el worker) la marca en la base de datos; el Hub la marca también cuando esa persona vuelve a fichar la entrada. 2. No se inventa ninguna hora de salida: ni «Fichar salida» ni las pausas la cierran (responde «Esta jornada lleva abierta más de 12 horas y está por revisar: la corrige un responsable. Ficha la entrada para empezar una jornada nueva.»); la pone un responsable con una corrección (ATTENDANCE-F08). 3. La persona puede volver a fichar la entrada sin esperar a esa corrección: Fichar le ofrece «Fichar entrada». Entra: las horas de ATTENDANCE-F04. Sale: la jornada en estado «Por revisar»; el aviso de jornada marcada (solo de las que se marcan). Si falla: si la tarea no corre, la jornada se ve igual «Por revisar» y se marca cuando la persona vuelve a fichar.

ATTENDANCE-F06 Ver mis jornadas del mes y quién las corrigió

Actor: empleado (y cualquiera, para las suyas) Pantalla: Registros Pasos: 1. Abre Control horario → «Registros»: ve sus jornadas del mes en curso, sin elegir persona. 2. En «Mes» puede elegir cualquiera de los últimos cuatro años. 3. La jornada abierta sale con «En curso» y el tiempo trabajado hasta ahora; la que falta por cerrar, «Por revisar». 4. Una jornada corregida sale con las horas nuevas; «Historial» enseña quién la corrigió, cuándo, el antes y el después y el motivo. Entra: sus jornadas y sus pausas. Sale: nada; solo lee. Si falla: «No se han podido cargar las jornadas.» y «Reintentar».

ATTENDANCE-F07 Ver las jornadas de todo el equipo

Actor: propietario, administrador, responsable Pantalla: Registros Pasos: 1. Abre Control horario → «Registros»: ve las jornadas del mes de todo el equipo, con el nombre de cada persona (también de quien ya se dio de baja: sus jornadas se guardan cuatro años). 2. Filtra por «Persona» (busca por nombre), «Mes» y «Estado» («Abierta», «Cerrada», «Por revisar»), y ordena por fecha, entrada, salida, persona o estado. 3. En «Ubicación» ve si la entrada y la salida se ficharon dentro del radio del local, o «Sin ubicación registrada». Entra: las jornadas y pausas de todos; los nombres, de las fichas de Personal. Sale: nada; solo lee. Si falla: «No se han podido cargar las jornadas.» y «Reintentar».

ATTENDANCE-F08 Corregir una jornada mal fichada, con su motivo

Actor: propietario, administrador, responsable Pantalla: Registros Pasos: 1. En «Registros», en la jornada mal fichada, pulsa «Corregir». 2. En «Corregir jornada» ve la entrada y la salida en la hora del negocio. Cambia la que está mal; dejar «Salida (vacía = sigue abierta)» vacía reabre la jornada. 3. Escribe el «Motivo» (obligatorio, al menos 3 caracteres) y pulsa «Guardar corrección». 4. Ve «Jornada corregida.»; la fila enseña las horas nuevas y el tiempo trabajado recalculado. 5. Una jornada «Por revisar» se cierra así: se le pone la salida y queda «Cerrada». Una pausa que seguía en curso se termina en la nueva salida. Entra: la jornada (ATTENDANCE-F07). Sale: la jornada con las horas nuevas y una entrada nueva en su historial (ATTENDANCE-F09), que nunca se borra; el aviso de jornada corregida; «Fichados ahora» se actualiza. Si falla: «La salida tiene que ser posterior a la entrada.» bajo la salida; «Estas horas se solapan con otra jornada de esta persona.» (tocarse no es solaparse: una jornada puede empezar en el instante en que acabó la anterior); «Esa persona ya tiene otra jornada abierta: no se puede reabrir esta.»; una hora futura, «La hora no puede ser futura.»; sin motivo, «Escribe un motivo de al menos 3 caracteres.». Una corrección rechazada no cambia nada ni deja rastro. «Corregir» solo aparece a quien puede corregir.

ATTENDANCE-F09 Ver quién cambió una jornada, cuándo y por qué

Actor: propietario, administrador, responsable; el empleado, de las suyas Pantalla: Registros Pasos: 1. En «Registros», en una jornada, pulsa «Historial». 2. En «Historial de correcciones» ve cada cambio, del más reciente al más antiguo: quién (o «Sistema»), cuándo, «Antes» → «Después» y el «Motivo». 3. Si nadie la ha corregido, ve «Esta jornada no se ha corregido nunca.». Entra: las correcciones de ATTENDANCE-F08 y ATTENDANCE-F13. Sale: nada; el historial no se puede editar ni borrar. Si falla: «No se ha podido cargar el historial.».

ATTENDANCE-F10 Sacar el mes en CSV para la gestoría o la Inspección

Actor: todos (el empleado, solo sus jornadas) Pantalla: Registros Pasos: 1. En «Registros», elige el mes (y, si es responsable, la persona y el estado). 2. Pulsa «Exportar CSV»; mientras tanto ve «Exportando…». 3. Se descarga attendance-2026-10.csv con una línea por jornada del filtro, todas, no solo las que caben en la pantalla: fecha, persona, entrada, salida, minutos de pausa, minutos trabajados, estado y si la entrada y la salida fueron dentro del radio. 4. El fichero se abre con los acentos bien en una hoja de cálculo. Entra: las jornadas del filtro (ATTENDANCE-F06, ATTENDANCE-F07). Sale: el fichero descargado en el dispositivo; nada se guarda en el Hub. Si falla: un mes sin jornadas descarga solo la cabecera y avisa «No hay jornadas con este filtro: el fichero solo lleva la cabecera.»; si la descarga falla, «No se ha podido exportar el CSV. Inténtalo de nuevo.».

ATTENDANCE-F11 Ver quién está fichado ahora

Actor: propietario, administrador, responsable Pantalla: Registros («Fichados ahora») Pasos: 1. Abre «Registros». Encima de la tabla, «Fichados ahora» dice cuántas personas tienen la jornada abierta y quiénes, desde qué hora y si están en pausa. 2. Cambia solo en cuanto alguien ficha la entrada o la salida, empieza o termina una pausa, o se corrige una jornada. 3. Una jornada «Por revisar» (o ya olvidada) no cuenta: nadie sabe si esa persona sigue dentro. Una ficha dada de baja tampoco. Entra: las jornadas abiertas (ATTENDANCE-F01, ATTENDANCE-F08). Sale: nada; solo lee. Si falla: el aviso de error en su lugar, sin tapar la tabla.

ATTENDANCE-F12 Fichar la entrada o la salida de otra persona

Actor: propietario, administrador, responsable Pantalla: ninguna (asistente y API) Pasos: 1. El responsable le dice al asistente «ficha la entrada de Ana» o «ficha la salida de Ana» (o llama a la API con la persona por su id o su nombre). 2. El Hub ficha a Ana con la hora del servidor, como si lo hiciera ella, y guarda quién lo hizo. Entra: la ficha de Personal de esa persona. Sale: lo mismo que ATTENDANCE-F01 y ATTENDANCE-F02. Si falla: un empleado no puede fichar a otra persona («Solo puedes fichar tu propia entrada y salida.»); si el nombre vale para varias, se dice cuáles y se pide que elija; si no existe, «Esa persona no existe en Personal.».

ATTENDANCE-F13 Cerrar la jornada abierta de quien se da de baja

Actor: sistema Pantalla: ninguna Pasos: 1. Un responsable da de baja a una persona en Personal (STAFF-F06) mientras tiene la jornada abierta. 2. Control horario cierra esa jornada en ese momento (y su pausa en curso) con una corrección del «Sistema» cuyo motivo es «Jornada cerrada al dar de baja a la persona en Personal.». Entra: el aviso de Personal staff.member.terminated. Sale: la jornada cerrada, con su entrada en el historial; el aviso de jornada corregida. Si falla: si la persona no tenía jornada abierta, no se hace nada (y una segunda entrega del aviso tampoco). Nota: la reacción está hecha y probada contra Personal real (tests/test_integration_staff.py); la entrega automática del aviso es el relay del outbox, que llega con el worker de la fase 2, como las reacciones de inventory, customer o sale.

Servicios: lo que entra y lo que sale

Todo se puede pedir por las pantallas, el asistente (por voz o por texto, con la sesión de quien habla) y la API, con las mismas reglas y los mismos permisos. Una persona se nombra por su id o por su nombre («ficha la salida de Ana»); «mi jornada de hoy» es attendance.record.current. Las horas viajan en ISO 8601 con zona; las duraciones, en segundos.

Lo que ofrece: consultas (leen, no cambian nada; todas menos la exportación se siguen en vivo)

Lo que ofrece: acciones (cambian datos)

No hay acción de borrar una jornada, a propósito: la ley pide conservarlas cuatro años.

Lo que avisa

Los avisos nunca llevan la posición ni el motivo de una corrección (datos personales).

A qué reacciona y lo que necesita de otras apps

• Personal (requires = ["staff"]): la jornada es de una ficha de Personal (staff.Member), y la persona de la sesión se encuentra por la ficha vinculada a su cuenta. Lee los nombres de las fichas (también las dadas de baja) para la tabla, el CSV y el filtro.
• staff.member.terminated → attendance.record.close_for_terminated (ATTENDANCE-F13).
• staff.member.updated y staff.member.terminated vuelven a pintar las listas (el nombre o el estado de una persona).
• De la plataforma: la sesión y la zona horaria del negocio (fase 1: Europe/Madrid).

Quién puede qué