Módulo de Asistencia - chip/lector de huellas dactilares

1. Descripción general del módulo

1.1 Propósito del módulo

El módulo Asistencia - chip/lector de huellas dactilares (WorkAttendanceChips) sirve para el registro automatizado de la asistencia laboral de los empleados mediante tarjetas físicas con chip (RFID/NFC), lectores biométricos de huellas dactilares o reconocimiento facial mediante inteligencia artificial.

El módulo elimina la necesidad de entrada manual de horarios de entrada y salida, aumenta la precisión del registro y proporciona mecanismos de control contra el abuso (p. ej., fotografía al registrar, duración mínima de pausa, cierre automático del tiempo de trabajo).

1.2 Funciones clave

• Configuración de tarjetas con chip - Registro del código de seguridad del chip RFID/NFC para cada empleado
• Lector de huellas dactilares - Identificación biométrica mediante huellas dactilares (opcional)
• Reconocimiento facial - Detección facial con IA mediante face-api.js (requiere terminal RasPi con cámara)
• Terminal de asistencia RasPi - Terminal físico para registrar asistencia en el lugar
• Restricción de IP - Lista blanca de direcciones IP permitidas para lectores (seguridad)
• Botones configurables - Tipos de asistencia disponibles en el terminal (médico, viaje de negocios, etc.)
• Cierre automático - Finalización automática del tiempo de trabajo (3 modos)
• Fotografía al registrar - Fotografía de seguridad desde el terminal para detectar uso indebido de tarjetas
• Prevención de ediciones manuales - Modo estricto de chip con posibilidad de excepciones (vacaciones, enfermedad)
• Pausa mínima - Aplicación de la duración mínima de descanso
• Botones en el panel de control - Entrada/salida virtual directamente en el sistema sin tarjeta física

1.3 Público objetivo

Esta documentación está dirigida a:

• Administradores del sistema - Configuración del módulo, gestión de lectores, configuración de seguridad
• Personal de recursos humanos - Gestión de permisos de usuario, configuración de códigos de chips, control de fotografías
• Administradores de TI - Instalación de terminales RasPi, configuración de red, actualización de firmware
• Gerentes - Control de asistencia, aprobación de excepciones

2. Configuración

2.1 Configuración del módulo

Ruta de configuración: Configuración → Asistencia - chip/lector de huellas dactilares

El módulo utiliza los siguientes parámetros de configuración almacenados en las tablas de base de datos Company y User:

Parámetros de la tabla Company

Parámetro	Tipo	Descripción	Valor predeterminado
wa_RasPi_Face	booleano	Activar reconocimiento facial (requiere RasPi con cámara)	0 (desactivado)
wa_RasPi_TakePhoto	booleano	Tomar fotografías al registrar desde el terminal	0 (desactivado)
wa_chip_allowed_ips_ser_arr	arreglo	Direcciones IP permitidas de lectores (arreglo serializado)	['all']
wa_chip_show_active	booleano	Mostrar estados (presencia) de otros en el lector	0 (desactivado)
wa_chip_use_WDT_14	booleano	Permitir registrar Almuerzos separados de Pausas	0 (desactivado)
wa_chip_buttons_on_dashboard	booleano	Mostrar botones de Entrada/Salida en el panel principal	0 (desactivado)
wa_chip_WritePause	booleano	Registrar pausa al regresar el mismo día	0 (desactivado)
wa_chip_AutoCloseInLastDay	booleano	Notificación y cierre de asistencia del día anterior	0 (desactivado)
wa_chip_ChiporFaceDetect	cadena	Modo principal de detección ('c' = chip, 'f' = rostro)	'c' (chip)

Parámetros de la tabla User

Parámetro	Tipo	Descripción	Valor predeterminado
wa_chip_code	cadena	Código hash de seguridad del chip del empleado	NULL
wa_chip_last_inout	enumeración	Estado actual del empleado ('in', 'out')	'out'
wa_chip_minimal_pause_min	entero	Duración mínima de pausa en minutos	NULL
wa_chip_last_poznamka	cadena	Última nota al registrar	NULL
wa_chip_AllowManualType_ser_arr	arreglo	Tipos de asistencia permitidos para registro manual (arreglo serializado)	[]
rights_workattendance	enumeración	Permisos de asistencia ('1' = solo chip, '2' = también registro manual)	'2'
FingerPrints_ser_arr	arreglo	Huellas dactilares guardadas (arreglo serializado)	[]

2.2 Permisos de usuario

Para acceder a la configuración del módulo, se debe cumplir una de las siguientes condiciones:

• Permisos de administrador: $Logged_User->admin == 1
• Administrador del módulo: in_array('dochazka_cipy', $Logged_User->AdminToModules_ser_arr)

3. Interfaz de usuario

3.1 Descripción general de pestañas

La interfaz de usuario del módulo está dividida en 5 pestañas principales:

1. Permisos de usuario - Configuración de códigos de chips, huellas dactilares, prevención de ediciones manuales
2. Direcciones IP permitidas - Lista blanca de direcciones IP de lectores
3. Botones adicionales permitidos - Configuración de botones en el terminal
4. Otras configuraciones - Configuraciones generales del módulo
5. Lectores registrados - Descripción general de terminales RasPi

3.2 Pestaña: Permisos de usuario

Pestaña principal para configurar el acceso de empleados al sistema de asistencia.

Detección de usuario

El sistema soporta 3 formas de identificación del empleado:

Método	Descripción	Requisitos	Estado
Por chip (RFID/NFC)	Tarjeta con chip estándar	Lector RFID/NFC	Siempre activado
Por rostro	Reconocimiento facial con IA mediante face-api.js	Terminal RasPi con cámara, wa_RasPi_Face=1	Opcional
Por huella dactilar	Lector biométrico de huellas	RasPi con lector de huellas, FingerPrintReader=1	Opcional

Tabla de empleados

La tabla contiene las siguientes columnas:

Columna	Descripción	Acción
ID	ID del empleado en el sistema	-
Apellido, nombre	Nombre completo con enlace al detalle del usuario	Haga clic para abrir el detalle del empleado
Código del chip	Código hash de seguridad del chip	Ingrese en el campo de texto El cambio se guarda automáticamente (onChange) El icono del portapapeles copia la URL de la API
Huella dactilar	Indicador de si el empleado tiene huellas guardadas	Muestra 0/1 según sizeofSafe($User->FingerPrints_ser_arr)
Prevenir ediciones	Casilla de verificación para prevenir ediciones manuales de asistencia	Al marcar se establece rights_workattendance='1' Se mostrará el botón para permitir excepciones
Duración mínima de pausa	Número de minutos de pausa mínima	Ingrese un número (p. ej., 30), el cambio se guarda automáticamente
Acción	Acciones especiales para el empleado	Si el estado es "in", se mostrará el botón Restablecer (para entrada) Restablece el estado a "out"

Botón: Puede registrar manualmente solo el tipo de asistencia...

Este botón se muestra solo para empleados que tienen marcado Prevenir ediciones del tiempo de trabajo.

Función: Abre una ventana modal para seleccionar tipos de asistencia que el empleado puede registrar manualmente a pesar de la prevención de ediciones manuales.

Uso típico:

• Vacaciones (el empleado puede registrar vacaciones manualmente)
• Enfermedad (el empleado puede registrar enfermedad manualmente)
• Teletrabajo (el empleado puede registrar teletrabajo manualmente)

3.3 Pestaña: Direcciones IP permitidas

Esta pestaña sirve para configurar la lista blanca de seguridad de direcciones IP desde las cuales los lectores pueden conectarse al sistema.

Casilla principal

Permitir acceso de lector solo desde las direcciones IP indicadas abajo

• Marcado: El sistema verifica la dirección IP de la solicitud contra la lista blanca
• No marcado: El acceso está permitido desde todas las direcciones IP (wa_chip_allowed_ips_ser_arr = ['all'])

Campo dinámico de direcciones IP

Después de marcar la casilla principal, se muestra el campo para ingresar direcciones IP:

• Cada dirección IP tiene su propio campo de texto
• Después de completar, se muestra automáticamente otro campo vacío
• Los cambios se guardan automáticamente (AJAX)
• Siempre son visibles al menos 2 campos vacíos para agregar más IPs

Ejemplo de configuración:

192.168.1.100
192.168.1.101
10.0.0.50

3.4 Pestaña: Botones adicionales permitidos

Configuración de botones adicionales en el terminal de asistencia para tipos especiales de asistencia (médico, viaje de negocios, etc.).

Botón: Agregar botón

Abre una ventana modal para agregar un nuevo botón:

1. Seleccione Tipo de asistencia de la lista desplegable (se cargan solo tipos con chip_buttons_available=1)
2. Haga clic en Guardar
3. El botón aparecerá en el terminal y en la tabla

Tabla de botones

Muestra todos los botones configurados con las siguientes columnas:

Columna	Descripción	Opciones
Botón	Nombre del tipo de asistencia	P. ej., "Médico", "Viaje de negocios"
Finalización automática según el número de horas de trabajo por día	El sistema calcula el final según la jornada diaria	Botón de opción Guarda autoclose_user_hour_day=1 Ejemplo: Jornada 8h, entrada 7:00 → fin automático 15:00
Finalización automática a hora especificada	Hora fija de finalización	Botón de opción + campo de hora (HH:MM) Guarda autoclose_user_hour_day=0 Guarda autoclose_at_time (p. ej., "15:30:00") Ejemplo: Siempre finalizar a las 16:00
Duración fija en min	Número específico de minutos	Botón de opción + campo numérico Guarda autoclose_user_hour_day=2 Guarda autoclose_at_length (minutos) Ejemplo: Médico = 60 min
Acción	Botón para eliminar	Botón Eliminar botón Establece delete=1 El botón desaparecerá del terminal

Modos de finalización automática - detalladamente

1. Según el número de horas de trabajo por día

Cómo funciona:

1. El sistema carga la jornada diaria del empleado (p. ej., 8 horas)
2. Al registrar la entrada, registra la hora (p. ej., 7:00)
3. Calcula automáticamente el final: 7:00 + 8h = 15:00
4. Si el empleado no registra la salida antes de la medianoche, el sistema finaliza automáticamente a las 15:00

Ejemplo de uso: Viaje de negocios - el empleado sale de viaje, el sistema finaliza el tiempo automáticamente según su jornada.

2. A hora especificada

Cómo funciona:

1. El administrador establece una hora fija de finalización (p. ej., 15:30)
2. Al registrar la entrada, registra la hora (p. ej., 7:00)
3. Si el empleado no registra la salida antes de la medianoche, el sistema finaliza automáticamente a las 15:30

Ejemplo de uso: Conferencia - todos los participantes tienen un final fijo a las 16:00.

3. Duración fija

Cómo funciona:

1. El administrador establece el número de minutos (p. ej., 60)
2. Al registrar la entrada, registra la hora (p. ej., 9:00)
3. El sistema finaliza automáticamente después de 60 minutos: 9:00 + 60 min = 10:00

Ejemplo de uso: Médico - el empleado va al médico, el sistema finaliza después de 60 minutos.

3.5 Pestaña: Otras configuraciones

Configuraciones generales del módulo que afectan el comportamiento de todo el sistema.

Configuración	Descripción	Valor predeterminado
Mostrar estados (presencia) de otros en el lector	En el terminal se muestra una lista de todos los empleados con su estado actual (presente/ausente). Columna de base de datos: wa_chip_show_active	Desactivado (0)
Permitir registrar Almuerzos separados de Pausas	El empleado puede distinguir en el terminal entre pausa general y almuerzo (tipo especial de pausa). Columna de base de datos: wa_chip_use_WDT_14 Tipo de asistencia: WDT_14 (Almuerzo)	Desactivado (0)
Mostrar botones de Entrada/Salida en el panel principal después del inicio de sesión	Cada empleado verá después de iniciar sesión en el panel de control botones para registrar entrada/salida sin necesidad de tarjeta física. Columna de base de datos: wa_chip_buttons_on_dashboard Uso: Adecuado para empleados que trabajan desde casa o sin acceso al terminal	Desactivado (0)
Registrar pausa al regresar el mismo día	Si el empleado registra salida y luego nuevamente entrada el mismo día, el sistema registra automáticamente el tiempo intermedio como pausa. Columna de base de datos: wa_chip_WritePause Ejemplo: Salida 12:00, Entrada 12:30 → Pausa 30 min	Desactivado (0)
Fotografía al registrar asistencia desde el terminal	En cada registro desde el terminal RasPi se toma una fotografía del empleado. Sirve para detectar uso indebido de tarjetas (verificar que la tarjeta es usada por su verdadero propietario). Columna de base de datos: wa_RasPi_TakePhoto Requisitos: Terminal RasPi con cámara	Desactivado (0)
Notificación y cierre de asistencia del día anterior	Si el empleado olvida registrar la salida ayer y hoy registra una nueva entrada, el sistema muestra una notificación y requiere completar la salida de ayer con el supervisor. Columna de base de datos: wa_chip_AutoCloseInLastDay Propósito: Prevención de registros "pendientes" en la asistencia	Desactivado (0)

3.6 Pestaña: Lectores registrados

Descripción general de todos los terminales RasPi registrados en el sistema.

Tabla de lectores

Columna	Descripción
ID	Identificador único del lector en la base de datos (idRasPi)
Fecha de adquisición	Fecha de instalación/registro del lector (BuyDate)
Versión de FW instalada	Versión de firmware instalada en RasPi (Version)
Última comprobación	Fecha y hora de la última comunicación con el lector (LastCheck)

Diagnóstico de lectores

Según la columna Última comprobación puede diagnosticar problemas:

• Verde: El lector se reportó en la última hora - todo correcto
• Amarillo: El lector no se ha reportado en más de una hora - posible problema de red
• Rojo: El lector no se ha reportado en más de un día - problema grave (apagado, red, hardware)

4. Operaciones básicas

4.1 Configuración del código del chip del empleado

Objetivo: Asignar al empleado un código de seguridad del chip para que pueda registrar asistencia.

1. Abra Configuración → Asistencia - chip/lector de huellas dactilares
2. Vaya a la pestaña Permisos de usuario
3. En la tabla de empleados, busque el empleado deseado (puede usar la búsqueda)
4. En la columna Código del chip ingrese el código hash de seguridad (se recomienda mínimo 16 caracteres, aleatorios)
5. El sistema guarda automáticamente el cambio al salir del campo (evento onChange)
6. Opcional: Haga clic en el icono del portapapeles (fa-clipboard) para copiar la URL de la API para pruebas

4.2 Prevención de ediciones manuales de asistencia

Objetivo: Configurar al empleado en modo estricto, donde solo puede registrar asistencia con chip.

1. En la pestaña Permisos de usuario busque al empleado
2. En la fila del empleado marque la casilla Prevenir ediciones del tiempo de trabajo en asistencia
3. El sistema establece rights_workattendance='1'
4. Aparecerá el botón verde Puede registrar manualmente solo el tipo de asistencia...
5. Haga clic en el botón
6. En la ventana modal marque los tipos permitidos (p. ej., Vacaciones, Enfermedad, Teletrabajo)
7. Haga clic en Guardar

Resultado: El empleado ahora no puede editar manualmente la asistencia, pero puede ingresar manualmente tipos seleccionados de ausencia.

4.3 Configuración de pausa mínima

Objetivo: Hacer cumplir una duración mínima de pausa (p. ej., almuerzo mínimo 30 minutos).

1. En la pestaña Permisos de usuario busque al empleado
2. En la columna Duración mínima de pausa (minutos) ingrese el número de minutos (p. ej., 30)
3. El sistema guarda automáticamente el cambio

Cómo funciona:

• El empleado registra pausa (p. ej., 12:00 - 12:10 = 10 minutos)
• El sistema verifica wa_chip_minimal_pause_min (p. ej., 30)
• Si la pausa es más corta, automáticamente la extiende al mínimo (10 min → 30 min)
• En el registro de asistencia aparece una pausa de 30 minutos

4.4 Restablecer estado entrada/salida

Objetivo: Restablecer el estado "pendiente" de un empleado que olvidó registrar la salida.

1. En la pestaña Permisos de usuario busque al empleado
2. Si el empleado está en estado "in" (presente), aparecerá el botón Restablecer (para entrada)
3. Haga clic en el botón
4. El sistema cambia el estado a "out" (ausente)
5. El empleado ahora puede registrar entrada nuevamente

Cuándo usar:

• El empleado olvidó registrar la salida ayer
• El sistema "está atascado" en estado "in" y no permite nueva entrada
• Necesita desbloquear rápidamente al empleado

5. Funciones avanzadas

5.1 Agregar botón al lector

Objetivo: Agregar un tipo especial de asistencia (p. ej., Médico, Viaje de negocios) como botón en el terminal RasPi.

1. Vaya a la pestaña Botones adicionales permitidos en el lector de chips
2. Haga clic en el botón verde Agregar botón
3. En la ventana modal seleccione Tipo de asistencia de la lista desplegable
4. Haga clic en Guardar
5. El botón aparecerá en la tabla
6. Configure el modo de finalización automática (ver abajo)

Configuración de finalización automática

Después de agregar el botón, seleccione uno de los 3 modos:

A) Según el número de horas de trabajo por día

• Marque el botón de opción en la columna Finalización automática según el número de horas de trabajo por día
• El sistema calcula el final según la jornada diaria del empleado
• Ejemplo: Viaje de negocios - el empleado tiene jornada de 8h, sale a las 9:00 → fin automático 17:00

B) A hora especificada

• Marque el botón de opción en la columna Finalización automática a hora especificada
• En el campo de hora debajo ingrese la hora (p. ej., 15:30)
• Ejemplo: Capacitación - todos tienen final fijo a las 16:00

C) Duración fija

• Marque el botón de opción en la columna Duración fija en min
• En el campo numérico debajo ingrese el número de minutos (p. ej., 60)
• Ejemplo: Médico - finalizar automáticamente después de 60 minutos

5.2 Eliminar botón

1. En la tabla de botones busque la fila con el botón que desea eliminar
2. Haga clic en el botón rojo Eliminar botón
3. El botón se elimina de la base de datos y desaparece del terminal

5.3 Restricción de direcciones IP

Objetivo: Permitir acceso a la API solo desde direcciones IP confiables (lectores).

1. Vaya a la pestaña Direcciones IP permitidas desde las cuales el lector puede reportarse
2. Marque Permitir acceso de lector solo desde las direcciones IP indicadas abajo
3. En el primer campo vacío ingrese la dirección IP del lector (p. ej., 192.168.1.100)
4. Después de escribir, automáticamente aparece otro campo vacío
5. Repita para todos los lectores
6. Los cambios se guardan automáticamente

Verificación de seguridad en el código:

// El sistema verifica USER_IP contra wa_chip_allowed_ips_ser_arr
if (!in_array(USER_IP, $Company->wa_chip_allowed_ips_ser_arr)
    && $Company->wa_chip_allowed_ips_ser_arr[0] != 'all') {
    DieUnauthorized();
}

5.4 Activación del reconocimiento facial

Objetivo: Permitir a los empleados registrar asistencia mediante rostro sin chip.

Requisitos:

• Terminal RasPi con cámara
• Fotografías de empleados en el sistema (mínimo 1 foto por empleado)
• Biblioteca JavaScript face-api.js (incluida en el sistema)

Procedimiento de activación:

1. Vaya a la pestaña Permisos de usuario
2. En el encabezado de la tabla marque Por rostro (requiere nuestro lector)
3. El sistema establece wa_RasPi_Face=1
4. En el terminal RasPi se activa la cámara y detección facial

Cómo funciona:

1. El empleado se acerca frente a la cámara RasPi
2. El sistema carga todas las fotografías guardadas de empleados
3. Face-api.js detecta el rostro en el video en vivo
4. Compara el rostro detectado con las fotografías guardadas (umbral 0.4)
5. Si coincide, automáticamente registra la asistencia

5.5 Mostrar estados de otros

Objetivo: Mostrar en el terminal quién está presente y quién no.

1. Vaya a la pestaña Otras configuraciones
2. Marque Mostrar estados (presencia) de otros en el lector
3. El sistema establece wa_chip_show_active=1

Resultado: En el terminal RasPi se muestra una lista de todos los empleados:

• Verde: Presente (wa_chip_last_inout='in')
• Rojo: Ausente (wa_chip_last_inout='out')

5.6 Botones en el panel de control

Objetivo: Permitir a los empleados registrar asistencia directamente desde la interfaz web sin tarjeta física.

1. Vaya a la pestaña Otras configuraciones
2. Marque Mostrar botones de Entrada/Salida en el panel principal después del inicio de sesión
3. El sistema establece wa_chip_buttons_on_dashboard=1

Resultado: Después de iniciar sesión, cada empleado verá en el panel de control:

• Botón verde "Entrada" (si el estado es 'out')
• Botón rojo "Salida" (si el estado es 'in')

Uso:

• Teletrabajo - el empleado no tiene acceso al lector
• Empleados móviles - registro desde móvil/tablet
• Administración - método de registro de respaldo

5.7 Fotografía al registrar

Objetivo: Tomar fotografía de seguridad en cada registro para detectar uso indebido de tarjetas.

1. Vaya a la pestaña Otras configuraciones
2. Marque Fotografía al registrar asistencia desde el terminal
3. El sistema establece wa_RasPi_TakePhoto=1

Cómo funciona:

1. El empleado coloca el chip en el lector
2. La cámara RasPi toma una fotografía
3. La fotografía se sube al servidor
4. Se guarda en la tabla Files con enlace al registro de asistencia
5. El administrador puede revisar las fotografías en el módulo de Asistencia

Detección de uso indebido:

• En la fotografía hay una persona diferente al propietario de la tarjeta → uso indebido
• La fotografía está borrosa/vacía → intento de eludir el sistema
• Fotografías repetidas de la misma persona con tarjeta ajena → uso indebido regular

6. Integración

6.1 Módulos conectados

Módulo	Relación	Descripción
Asistencia	Escritura de datos	Registro automático de horarios de entrada/salida en la tabla Workattendance. Si está activado wa_chip_WritePause=1, también se registra la duración de la pausa.
Usuarios	Enlace a empleados	Carga de datos de usuario (clase cUser): - Código del chip (wa_chip_code) - Huellas dactilares (FingerPrints_ser_arr) - Permisos de asistencia (rights_workattendance) - Pausa mínima (wa_chip_minimal_pause_min)
Terminales RasPi	Lector físico	Gestión de dispositivos RasPi (clase cRasPi): - Versión de firmware (Version) - Última comprobación (LastCheck) - Lector de huellas (FingerPrintReader) - Punto final de API (GetUrl())
Tipos de asistencia	Botones en el lector	Carga de tipos de asistencia (cWorkattendance_days_type): - Nombre del tipo (day_name_cs) - Disponibilidad en el lector (chip_buttons_available) - Enlace a través de la tabla Workattendance_chip_buttons
Archivos	Fotografías al registrar	Almacenamiento de fotografías del terminal: - Tabla Files - Enlace al registro de asistencia - Acceso a través del módulo de Asistencia

6.2 Flujos de datos

Flujo 1: Registro con chip desde terminal RasPi

1. El empleado coloca el chip en el lector RasPi
   ↓
2. RasPi lee el código del chip desde RFID/NFC
   ↓
3. RasPi llama al punto final de API:
   GET /?w=wa_chip_inout&idUser=123&hash=abc123xyz
   ↓
4. inc/wa_chip_inout.php procesa la solicitud:
   - Verifica el hash contra User.wa_chip_code
   - Verifica la dirección IP contra wa_chip_allowed_ips_ser_arr
   - Verifica el estado wa_chip_last_inout
   ↓
5. Escritura en la tabla Workattendance:
   - Entrada: Crea nuevo registro con time_start
   - Salida: Completa time_end en el registro existente
   ↓
6. Actualización de User.wa_chip_last_inout:
   - 'in' → 'out' o 'out' → 'in'
   ↓
7. Si wa_RasPi_TakePhoto=1:
   - RasPi toma fotografía
   - Sube al servidor
   - Guarda en la tabla Files
   ↓
8. Respuesta al terminal RasPi:
   - Página HTML con confirmación
   - Visualización de hora de registro
   - Lista de presentes (si wa_chip_show_active=1)

Flujo 2: Registro desde panel de control (interfaz web)

1. El empleado hace clic en el botón "Entrada" en el panel de control
   ↓
2. JavaScript llama a AJAX:
   $.get('/?w=wa_chip_inout&idUser='+idUser+'&hash='+hash)
   ↓
3. inc/wa_chip_inout.php procesa igual que RasPi
   ↓
4. Escritura en Workattendance
   ↓
5. Actualización de wa_chip_last_inout
   ↓
6. Respuesta AJAX:
   - El panel de control se actualiza
   - Muestra el nuevo estado ("Salida" en lugar de "Entrada")

Flujo 3: Reconocimiento facial (Face Recognition)

1. El empleado se acerca frente a la cámara RasPi
   ↓
2. RasPi transmite video al servidor
   ↓
3. JavaScript face-api.js:
   - Carga todas las fotografías de empleados
   - Crea FaceMatcher con rostros guardados
   - Detecta rostro en video en vivo
   - Compara con rostros guardados
   ↓
4. Si coincide (umbral > 0.4):
   window.location.replace('?w=wa_chip_inout&FaceDetection='+hash)
   ↓
5. El servidor procesa el parámetro FaceDetection:
   - Encuentra idUser según el hash
   - Carga wa_chip_code
   - Registra asistencia
   ↓
6. Mismo flujo que Flujo 1 (pasos 5-8)

6.3 Dependencias

Componente	Dependencia	Obligatorio
Terminal RasPi	Dispositivo físico con lector RFID/NFC	Sí
Módulo de asistencia	Debe estar activo para escritura de datos	Sí
Usuarios	Los empleados deben tener permisos de asistencia	Sí
RasPi con cámara	Para reconocimiento facial y fotografías	Opcional
Lector de huellas	Para identificación biométrica	Opcional
face-api.js	Biblioteca para reconocimiento facial	Opcional
Conexión de red	RasPi debe tener acceso al servidor	Sí

7. Punto final de API

7.1 Punto final principal

Formato de URL:

https://su-dominio.com/?w=wa_chip_inout&idUser={ID}&hash={HASH}

7.2 Parámetros

Parámetro	Tipo	Obligatorio	Descripción
w	cadena	Sí	Identificador del punto final Valor: wa_chip_inout
idUser	entero	Sí	ID del empleado en el sistema Ejemplo: 123
hash	cadena	Sí	Código hash de seguridad del chip Corresponde a: User.wa_chip_code Ejemplo: abc123xyz789def456
idWorkattendance_chip_buttons	entero	No	ID del botón en el lector (tipo especial de asistencia) Ejemplo: 5 (Médico)
FaceDetection	cadena	No	Hash del rostro reconocido Formato: {userHash}-{photoID} Ejemplo: abc123-1
FingerID	entero	No	ID de la huella dactilar reconocida Ejemplo: 7
wa_chip_action	cadena	No	Acción específica (p. ej., selección manual de nota) Valores: note, pause

7.3 Verificaciones de seguridad

El punto final de API realiza las siguientes verificaciones de seguridad:

1. Verificación del hash:

   if ($User->wa_chip_code != $_GET['hash']) {
       DieUnauthorized();
   }

2. Verificación de dirección IP:

   if (!in_array(USER_IP, $Company->wa_chip_allowed_ips_ser_arr)
       && $Company->wa_chip_allowed_ips_ser_arr[0] != 'all') {
       DieUnauthorized();
   }

3. Verificación de existencia del usuario:

   $User = new cUser();
   $User->load($_GET['idUser']);
   if ($User->idUser == 0) {
       DieUnauthorized();
   }

4. Verificación de cuenta activa:

   if ($User->active != 1 || $User->deleted != 0) {
       DieUnauthorized();
   }

7.4 Respuesta de la API

La API devuelve una página HTML con la siguiente información:

• Reloj y fecha: Hora y fecha actuales (reloj JavaScript)
• Confirmación de registro: "Entrada registrada" / "Salida registrada"
• Hora de registro: Hora exacta del registro
• Lista de presentes: Si wa_chip_show_active=1
• Fotografía: Si wa_RasPi_TakePhoto=1, se muestra vista previa de la fotografía

7.5 Ejemplos de llamadas

Ejemplo 1: Entrada regular

GET https://empresa.com/?w=wa_chip_inout&idUser=45&hash=x7k9mN2pQ5rT8vW1

Ejemplo 2: Salida al médico (botón ID=3)

GET https://empresa.com/?w=wa_chip_inout&idUser=45&hash=x7k9mN2pQ5rT8vW1&idWorkattendance_chip_buttons=3

Ejemplo 3: Reconocimiento facial

GET https://empresa.com/?w=wa_chip_inout&FaceDetection=abc123def456-1

Ejemplo 4: Huella dactilar

GET https://empresa.com/?w=wa_chip_inout&idUser=45&hash=x7k9mN2pQ5rT8vW1&FingerID=7

8. Terminal RasPi

8.1 Descripción del dispositivo

El terminal RasPi (Raspberry Pi) es un ordenador compacto del tamaño de una tarjeta de crédito que sirve como lector físico de asistencia.

Componentes de hardware

Componente	Descripción	Obligatorio
Raspberry Pi	Placa base (recomendado RPi 4 o más reciente)	Sí
Lector RFID/NFC	Módulo para leer tarjetas con chip (p. ej., RC522)	Sí
Pantalla	Pantalla táctil para mostrar botones y estados	Sí
Cámara	Pi Camera para fotografías y reconocimiento facial	Opcional
Lector de huellas	Lector biométrico de huellas dactilares (p. ej., R307)	Opcional
Conexión de red	Ethernet o WiFi para comunicación con el servidor	Sí

8.2 Funciones del terminal

Funciones básicas

• Lectura de chips: Detección automática de tarjetas RFID/NFC
• Visualización de hora: Hora y fecha actuales
• Botones de tipos de asistencia: Entrada, Salida, Pausa, Almuerzo + botones configurables
• Confirmación de registro: Señalización visual y sonora de registro exitoso
• Lista de presentes: Visualización de quién está en el trabajo (si está activado)

Funciones avanzadas (opcionales)

• Reconocimiento facial: Detección con IA mediante cámara y face-api.js
• Lectura de huellas: Identificación biométrica mediante huellas dactilares
• Fotografía: Captura de fotografía de seguridad en cada registro
• Transmisión de video: Video en vivo desde la cámara para reconocimiento facial

8.3 Gestión del terminal

Registro de nuevo terminal

1. Conecte físicamente el RasPi a la red (Ethernet o WiFi)
2. Ejecute el script de instalación en RasPi
3. RasPi se registra automáticamente en el servidor:

POST https://empresa.com/RestAPI/RasPi.php
{
    "action": "register",
    "hash": "E5tlu8Jg44ZwwlBQgSbCE3lU7RSRvMXa"
}

4. En la administración aparece el nuevo terminal en la pestaña Lectores registrados

Verificación del estado del terminal

El terminal se reporta regularmente al servidor (cada 5 minutos):

GET https://empresa.com/RestAPI/RasPiCheck.php?hash={hash}

El servidor actualiza la columna LastCheck en la tabla RasPi.

Actualización de firmware

1. Conéctese al RasPi vía SSH
2. Ejecute el comando: sudo /home/pi/UpdateFromeIntranetServer
3. El script descarga la versión más reciente de: https://empresa.com/Apps/RasPiUpdate/
4. Reinicia automáticamente los servicios
5. La versión se actualiza en la base de datos (columna Version)

8.4 URL de API del terminal

Cada terminal RasPi tiene una URL de API única:

https://empresa.com/RasPi/{HASH}/RFID/WorkAttenDance

Donde {HASH} es el identificador de seguridad del terminal (p. ej., E5tlu8Jg44ZwwlBQgSbCE3lU7RSRvMXa).

Uso:

• RasPi lee chip con código 12345
• RasPi llama: https://empresa.com/?w=wa_chip_inout&idUser=45&hash=12345
• El servidor verifica y registra asistencia
• RasPi muestra confirmación

8.5 Diagnóstico de problemas

Problema: El terminal no se reporta

Síntomas: En la pestaña "Lectores registrados" hay una hora antigua en la columna "Última comprobación"

Solución:

1. Verifique la conexión de red del RasPi (ping al servidor)
2. Compruebe que la dirección IP del RasPi está en la lista blanca
3. Revise los registros en RasPi: /var/log/eintranet/
4. Reinicie RasPi: sudo reboot

Problema: El lector no lee chips

Síntomas: Colocar el chip no produce ninguna reacción

Solución:

1. Verifique la conexión física del lector al RasPi
2. Compruebe que el servicio del lector está funcionando: sudo systemctl status rfid
3. Reinicie el servicio: sudo systemctl restart rfid
4. Verifique que el chip es compatible (RFID/NFC 13.56 MHz)

Problema: El reconocimiento facial no funciona

Síntomas: La cámara no muestra video o no reconoce rostros

Solución:

1. Compruebe que está activado en la configuración: wa_RasPi_Face=1
2. Verifique la conexión de la cámara al RasPi
3. Compruebe que los empleados tienen fotografías cargadas en el sistema
4. Revise la consola JavaScript del navegador para errores
5. Intente reducir el umbral: modifique minConfidence = 0.3 (en lugar de 0.4)

9. Consejos y trucos

9.1 Copiar URL de API

Consejo: En la pestaña "Permisos de usuario" haga clic en el icono del portapapeles (fa-clipboard) junto al código del chip. La URL se copiará al portapapeles.

Uso: Puede abrir la URL en el navegador para pruebas manuales de registro sin lector físico.

9.2 Pruebas sin terminal RasPi

Procedimiento:

1. Copie la URL de API del empleado
2. Abra la URL en el navegador
3. El sistema registra la asistencia como desde RasPi

9.3 Restablecer estados "pendientes" en masa

Situación: Varios empleados olvidaron registrar la salida y el sistema está en estado "in".

Solución con consulta SQL:

UPDATE User
SET wa_chip_last_inout='out'
WHERE Company_idCompany=123
AND wa_chip_last_inout='in';

Nota: Esto solo restablece los estados, no soluciona los registros faltantes en la asistencia.

9.4 Configurar pausa mínima para todos

Situación: Desea configurar pausa mínima de 30 minutos para todos los empleados.

Solución con consulta SQL:

UPDATE User
SET wa_chip_minimal_pause_min=30
WHERE Company_idCompany=123
AND active=1
AND deleted=0;

9.5 Exportar códigos de chips

Procedimiento:

1. En la pestaña "Permisos de usuario" use la exportación de DataTables
2. Haga clic en el botón "Excel" o "CSV"
3. Se descarga un archivo con todos los códigos de chips

9.6 Botón automático para teletrabajo

Recomendación: Agregue un botón "Teletrabajo" con finalización automática según el número de horas de trabajo.

Ventaja: El empleado registra teletrabajo, el sistema finaliza automáticamente según su jornada.

9.7 Combinación de chip y rostro

Opción: Active reconocimiento facial y chip simultáneamente.

Ventaja:

• El empleado puede usar el chip (rápido)
• O el rostro (si olvidó la tarjeta)
• El sistema soporta ambos

9.8 Fotografías como evidencia

Consejo: Si tiene disputas sobre asistencia, use las fotografías del terminal como evidencia.

Acceso:

1. Módulo de Asistencia
2. Detalle del registro
3. Se muestra la fotografía tomada al registrar

9.9 Aplicación móvil como alternativa

Información: El sistema también soporta aplicación móvil para registrar asistencia.

Ventaja:

• El empleado no necesita chip
• Registro desde teléfono desde cualquier lugar
• Ubicación GPS al registrar (opcional)

9.10 Limpieza regular de fotografías antiguas

Consejo: Las fotografías ocupan espacio en el servidor. Configure eliminación automática de las que tienen más de 3 meses.

Trabajo cron:

DELETE FROM Files
WHERE table_name='Workattendance'
AND created < DATE_SUB(NOW(), INTERVAL 3 MONTH);

10. Resolución de problemas

10.1 El chip no funciona

Síntomas: Colocar el chip en el lector no produce reacción o muestra error.

Posibles causas y soluciones:

Causa	Solución
Código del chip incorrecto o vacío	Verifique que en la pestaña "Permisos de usuario" está completado el Código del chip. Debe corresponder exactamente al código en el chip.
Dirección IP del lector no está en la lista blanca	Vaya a la pestaña "Direcciones IP permitidas". Agregue la dirección IP del terminal RasPi. O desactive la lista blanca de IP (sin marcar).
El lector no lee el chip	Verifique la conexión física del lector al RasPi. Reinicie el servicio RFID: sudo systemctl restart rfid
Chip incompatible	Compruebe que el chip es RFID/NFC 13.56 MHz (p. ej., Mifare). El sistema no soporta chips de 125 kHz.
Problema de red	Verifique la conexión del RasPi a la red. Ping al servidor: ping su-dominio.com

Prueba: Copie la URL de la API (icono del portapapeles) y ábrala en el navegador. Si funciona, el problema está en RasPi/lector. Si no funciona, el problema está en la configuración del sistema.

10.2 El empleado no puede registrar manualmente

Síntomas: Al intentar registro manual en el módulo de Asistencia se muestra el error "No tiene autorización".

Posibles causas y soluciones:

Causa	Solución
Marcado "Prevenir ediciones"	En la pestaña "Permisos de usuario" desmarque la casilla Prevenir ediciones del tiempo de trabajo. O haga clic en Puede registrar manualmente solo el tipo de asistencia... y permita tipos específicos.
Tipo de asistencia no permitido	Haga clic en Puede registrar manualmente solo el tipo de asistencia... Marque el tipo deseado (p. ej., Vacaciones, Enfermedad). Haga clic en Guardar.
No tiene permisos de asistencia	En la administración de usuarios verifique que el empleado tiene rights_workattendance configurado. Debe ser '1' o '2' (no NULL ni 0).

10.3 La pausa se extiende automáticamente

Síntomas: El empleado registra pausa de 15 minutos, pero en el sistema aparecen 30 minutos.

Causa: Está configurada la duración mínima de pausa.

Solución:

1. En la pestaña "Permisos de usuario" busque al empleado
2. En la columna Duración mínima de pausa (minutos) elimine el valor o redúzcalo (p. ej., de 30 a 15)
3. El sistema guarda automáticamente

Nota: La extensión de la pausa es una función intencional, no un error. Sirve para asegurar el almuerzo.

10.4 No se toman fotografías

Síntomas: En el módulo de Asistencia faltan fotografías en los registros, aunque la función está activada.

Posibles causas y soluciones:

Causa	Solución
No está activado en la configuración	En la pestaña "Otras configuraciones" marque Fotografía al registrar asistencia desde el terminal. Verifique que wa_RasPi_TakePhoto=1.
RasPi no tiene cámara	Compruebe que la Pi Camera está físicamente conectada al RasPi. Verifique la conexión del cable de la cámara. Ejecute prueba de cámara: raspistill -o test.jpg
El servicio de cámara no está funcionando	Verifique el estado: sudo systemctl status camera Reinicie: sudo systemctl restart camera
Error al subir al servidor	Revise los registros del RasPi: /var/log/eintranet/camera.log Verifique la conexión de red y permisos de escritura en el servidor.
Registro desde panel de control	Las fotografías solo se toman al registrar desde terminal RasPi. Los botones del panel de control no toman fotografías (no tienen cámara).

10.5 El terminal no se reporta

Síntomas: En la pestaña "Lectores registrados" en la columna "Última comprobación" hay fecha/hora antigua (más de una hora).

Posibles causas y soluciones:

Causa	Solución
RasPi está apagado	Verifique que el RasPi está conectado a la alimentación y el LED está encendido. Intente reiniciar físicamente (desconectar y conectar la alimentación).
Problema de red	Verifique el cable Ethernet o conexión WiFi. Ping al servidor desde RasPi: ping su-dominio.com Verifique firewall y router.
Dirección IP no está en la lista blanca	En la pestaña "Direcciones IP permitidas" agregue la dirección IP del RasPi. Verifique que la dirección IP del RasPi no ha cambiado (DHCP). Recomendamos configurar IP estática.
El servicio check no se inició	SSH al RasPi. Verifique el estado: sudo systemctl status eintranet-check Reinicie: sudo systemctl restart eintranet-check
Error en archivo de configuración	Revise la configuración: /etc/eintranet/config.json Compruebe la corrección de la URL del servidor y el hash.

10.6 El reconocimiento facial no funciona

Síntomas: La cámara muestra video, pero el sistema no reconoce a ningún empleado.

Posibles causas y soluciones:

Causa	Solución
No está activado en la configuración	En la pestaña "Permisos de usuario" marque Por rostro (requiere nuestro lector). Verifique que wa_RasPi_Face=1.
Faltan fotografías de empleados	En la administración de usuarios verifique que los empleados tienen fotografías cargadas. Mínimo 1 foto por empleado. Las fotografías deben ser frontales, bien iluminadas, sin gafas/gorra.
Malas condiciones de iluminación	Asegure iluminación suficiente frente al lector. Evite contraluz y lugares oscuros. Ideal es luz natural uniforme.
Umbral demasiado alto	En el archivo inc/wa_chip_inout.php reduzca minConfidence: let minConfidence = 0.3 (en lugar de 0.4) Cuidado: Umbral más bajo = más reconocimientos falsos.
Errores de JavaScript	Abra la consola JavaScript en el navegador (F12). Revise mensajes de error. Intente otro navegador (recomendado Chrome).
face-api.js no se cargó	Verifique que existe el archivo: /_components/face-api.js-0.22.2/dist/face-api.min.js Verifique la conexión de red (la API carga modelos desde CDN).

10.7 Los botones del panel de control no son visibles

Síntomas: Después de iniciar sesión en el panel de control faltan los botones Entrada/Salida.

Posibles causas y soluciones:

Causa	Solución
No está activado en la configuración	En la pestaña "Otras configuraciones" marque Mostrar botones de Entrada/Salida en el panel principal. Verifique que wa_chip_buttons_on_dashboard=1.
Caché del navegador	Actualice la página con borrado de caché: Ctrl + F5 (Windows) o Cmd + Shift + R (Mac). O borre cookies y caché en la configuración del navegador.
No tiene completado el código del chip	En la pestaña "Permisos de usuario" verifique que el empleado tiene completado el Código del chip. Los botones solo se muestran a usuarios con código de chip.
Error de JavaScript	Abra la consola JavaScript (F12). Revise mensajes de error. Intente otro navegador.

10.8 La finalización automática no funciona

Síntomas: El empleado registra tipo especial (p. ej., Médico), pero la asistencia no se finaliza automáticamente.

Posibles causas y soluciones:

Causa	Solución
No está configurado el modo	En la pestaña "Botones adicionales permitidos" verifique el botón. Debe estar marcado uno de los 3 botones de opción (a horas, hora o duración). Si no está, márquelo y configure el valor.
El empleado registró salida manualmente	La finalización automática solo se aplica si el empleado NO registró salida antes de la medianoche. Si registró manualmente, no se usa la automática.
El trabajo cron no está funcionando	La finalización automática la realiza un trabajo cron (p. ej., a las 00:01). Verifique que está funcionando: crontab -l Busque línea con wa_chip_autoclose.php (o similar).
Configuración incorrecta de hora	En el modo "A hora especificada" verifique el formato de hora: HH:MM Debe ser hora válida (p. ej., 15:30, no 25:00).

10.9 La pausa mínima no se aplica

Síntomas: El empleado tiene configurada pausa mínima de 30 min, pero el sistema acepta pausas más cortas.

Posibles causas y soluciones:

Causa	Solución
No está completado el valor	En la pestaña "Permisos de usuario" verifique la columna Duración mínima de pausa. Debe ser un valor numérico (p. ej., 30), no campo vacío.
Registro manual de asistencia	La pausa mínima solo se aplica al registrar desde el terminal. En registro manual en el módulo de Asistencia no se realiza la verificación.
La lógica no está implementada	Verifique que el código en inc/wa_chip_inout.php contiene la verificación de pausa mínima. Busque línea con wa_chip_minimal_pause_min.

10.10 La lista blanca de IP bloquea acceso legítimo

Síntomas: El lector no funciona, aunque está correctamente configurado. En el registro hay error "Unauthorized".

Posibles causas y soluciones:

Causa	Solución
Dirección IP no está en la lista	En la pestaña "Direcciones IP permitidas" agregue la dirección IP del lector. Determine la dirección IP real del RasPi: hostname -I
Dirección IP dinámica (DHCP)	La dirección IP del RasPi pudo haber cambiado después del reinicio. Recomendamos configurar dirección IP estática en la configuración del router o en RasPi.
Servidor NAT/Proxy	Si el RasPi está detrás de NAT/proxy, el servidor ve otra IP. Verifique qué IP ve el servidor: echo USER_IP en el registro. Agregue esta IP a la lista blanca.
Formato de dirección IP	Verifique el formato correcto: 192.168.1.100 No: 192.168.1.100:80 o http://192.168.1.100