Instalar y operar el servicio de Windows¶

El servicio de sincronización corre en la PC de oficina que tiene acceso a la red del reloj. Se instala como servicio de Windows con NSSM para que arranque solo y sobreviva a reinicios.

Requisitos previos¶

Windows con PowerShell como Administrador.
Python 3.10+.
Acceso a la red local donde está el ZKTeco F22 (puerto 4370).
config.ini ya configurado — ver Configuración y entornos.
Idealmente, una IP fija reservada por DHCP para el reloj. Sin ella, cada reinicio del F22 puede cambiarle la IP y tumbar la sincronización (reserva pendiente).

1. Preparar el entorno¶

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Copia la plantilla y completa los valores:

Copy-Item config.example.ini config.ini

Verifica antes de instalar el servicio:

python sync.py --dry-run     # imprime el payload sin enviarlo a Odoo

2. Instalar el servicio¶

En PowerShell como Administrador:

powershell -ExecutionPolicy Bypass -File scripts\install_service.ps1

El script descarga NSSM si no está presente (lo deja en tools\nssm.exe), crea el servicio y lo inicia con arranque automático. Redirige stdout y stderr a logs\service.log.

Ajuste del servicio	Valor
Nombre	`ZKSyncService`
Display name	`ZKTeco Sync - Asistencias a Odoo`
Arranque	`SERVICE_AUTO_START`
Ejecutable	`.venv\Scripts\python.exe`
Logs	`logs\service.log`

El nombre del servicio no coincide entre scripts

install_service.ps1 crea ZKSyncService, pero uninstall_service.ps1 y el README.md del repo usan ZKTecoSync. Si la desinstalación falla con "servicio no encontrado", es por esto: confirma el nombre real con Get-Service *ZK* antes de operar.

3. Gestionar el servicio¶

Get-Service *ZK*                 # confirmar el nombre real
Get-Service ZKSyncService        # ver estado
Start-Service ZKSyncService      # iniciar
Stop-Service ZKSyncService       # detener
Restart-Service ZKSyncService    # reiniciar (necesario tras editar config.ini)

Ver el log en tiempo real:

Get-Content logs\sync.log -Tail 30 -Wait

Snapshot del estado:

.\.venv\Scripts\python.exe utils\status.py

Reiniciar tras cambiar la configuración

config.ini se lee al arrancar. Editarlo sin reiniciar el servicio no tiene efecto.

Probar contra staging¶

sync.py no acepta --config, así que se alterna el archivo activo:

# 1. Detener produccion
Stop-Service ZKSyncService

# 2. Activar staging
Copy-Item config.staging.ini config.ini

# 3. Probar manualmente (no como servicio)
python sync.py --dry-run     # ver que se enviaria
python sync.py               # una corrida real contra staging

# 4. Volver a produccion
Copy-Item config.production.ini config.ini
Start-Service ZKSyncService

Para correr staging sin detener producción hace falta otra máquina (o una segunda instancia del servicio apuntando a otro directorio con su propio config.ini).

Desinstalar¶

powershell -ExecutionPolicy Bypass -File scripts\uninstall_service.ps1

Si el script no encuentra el servicio, revisa el aviso sobre el nombre y elimínalo con el nombre real:

nssm remove ZKSyncService confirm