Sistema de Gestión de Personal y Nómina

Sistema completo para la gestión de personal y nómina de instituciones educativas, desarrollado en Python con interfaz gráfica CustomTkinter.

🎯 Objetivo del Proyecto

Este sistema proporciona una solución integral para la administración de recursos humanos en instituciones educativas, permitiendo gestionar empleados, documentos, incidencias, permisos y nóminas de manera eficiente y organizada.

📚 Documentación

Punto de entrada	Contenido
Portal web	Lector de la tesis y la documentación técnica, catálogo y buscador
Informes académicos	Contabilidad, socio crítico, proyecto y redes de computadoras
Documentación técnica	Arquitectura, instalación, operación y mantenimiento
Guía de usuario	Manual operativo del sistema
Tesis	Índice del compendio académico y sus anexos
Guía del servidor local	Sincronización, cuentas, firewall y diagnóstico
Checklist de producción	Instalación y validación en equipos reales
Notas de desarrollo	Bitácora técnica y decisiones de diseño
Guía de contribución	Convenciones, pruebas y flujo de trabajo

El portal también se abre sin conexión: start docs/index.html (Windows), open docs/index.html (macOS) o xdg-open docs/index.html (Linux).

🚀 Características

Gestión de Personal

• Registro completo de empleados (Docentes, Administrativos, Mantenimiento)
• Ficha de datos personales, físicos y de contacto
• Gestión de fotos de perfil
• Clasificación por tipo, cargo y departamento
• Búsqueda y filtrado avanzado

Gestión Documental

• Carga y almacenamiento de documentos digitalizados
• Soporte para PDFs e imágenes
• Clasificación por tipo de documento
• Control de vencimientos (reporte PDF con vencidos y por vencer)
• Gestión de documentos por empleado
• Exportación del listado a Excel/CSV

Incidencias y Permisos

• Registro de reposos médicos, ausencias y permisos
• Sistema de aprobación/rechazo
• Gestión de documentos de soporte
• Cálculo automático de días
• Control de incidencias vigentes
• Reporte PDF y exportación a Excel/CSV (por empleado o general)

Nómina y Pagos

• Generación automática de nóminas por periodo
• Motor de cálculo con dos modalidades: porcentual (histórica) y por tramos progresivos de ISR con techos de cotización y aportes patronales
• Horas extra con recargo por jornada (diurna, nocturna y feriada)
• Prestaciones: aguinaldo, bono vacacional, prestaciones por antigüedad, indemnización y preaviso proportional al tiempo servido
• Generación de recibos de pago y planilla de nómina en PDF
• Control de pagos pendientes y realizados

Contratos Laborales

• Alta de contratos (indefinido, temporal, por obra o pasantía)
• Renovación encadenada al contrato anterior y terminación con finiquito
• Unicidad del contrato vigente y numeración automática
• Control de contratos por vencer y vencidos
• Reporte PDF de contratos

Módulo Académico

• Estudiantes: legajo completo con cédula única, nivel educativo, representante y datos de contacto, búsqueda por nombre o cédula y exportación a Excel
• Grados y matrículas: grados y secciones por año escolar, asignación del docente responsable y una sola matrícula activa por estudiante y periodo
• Calificaciones: registro, corrección y eliminación de notas finales por materia, carga por lotes en una única transacción, consolidado del periodo, boletín por estudiante y acta final del grado
• Periodos académicos: alta y edición del año escolar, cierre que bloquea las notas (servicio y base de datos) y reapertura restringida al administrador
• Autorización por token: solo la administración o el docente asignado al grado escriben notas, con token de sesión de una jornada y sin guardarlo en claro

Panel Analítico

• Indicadores clave: nómina del mes, contratos por vencer y dotación activa
• Gráficos de barras, dona y línea dibujados sobre Canvas (sin dependencias nuevas)

Generación de Documentos y Exportación

• Constancias de trabajo y de estudios
• Ficha completa del empleado (datos personales, laborales, bancarios, salud y familia)
• Recibos de pago
• Reportes de empleados
• Planilla de nómina por periodo con totales (ISSS, AFP, ISR, neto)
• Reporte de incidencias, control de vencimientos de documentos y reporte de contratos
• Exportación de listados a Excel (.xlsx) y CSV (UTF-8 compatible con Excel), incluida la exportación multihoja

Seguridad y Auditoría

• Autenticación de usuarios con contraseñas cifradas (PBKDF2)
• Roles y permisos por módulo (Administrador, Gestor, Usuario, Solo lectura)
• Cambio de contraseña del usuario logueado
• Visor de auditoría (solo administradores) con filtro por tipo y exportación
• Bloqueo de cuenta por intentos fallidos con desbloqueo administrativo
• Caducidad de contraseñas, historial de claves y cambio obligatorio
• Respaldos automáticos programados con verificación de integridad

Interfaz y Experiencia de Usuario

• Tema oscuro/claro configurable y persistente (botón ☀️/🌙 en la cabecera)
• Atajos de teclado para navegar y operar más rápido
• Panel de control (Dashboard) con tarjetas estadísticas navegables, indicadores analíticos y gráficos propios
• Ventanas integradas de Ayuda (guía rápida) y Acerca de
• Barra de estado con reloj y mensajes de la aplicación
• Soporte de alta resolución (DPI) en Windows

Actualización Automática (Windows)

• Actualizador incluido en el instalador y programado automáticamente cada 2 días (Programador de tareas de Windows, 09:00)
• Ventana de estado que muestra todo el proceso: comprobando, descargando (con porcentaje y tamaño), instalando y resultado final
• Ícono en la bandeja del sistema (barra inferior derecha) con menú: buscar ahora, mostrar ventana o salir
• Descarga e instala en silencio la última versión publicada en GitHub

📋 Requisitos del Sistema

• Python 3.15 o superior
• Windows 10/11
• 4GB RAM mínimo
• 500MB espacio en disco

🏗️ Arquitectura del Sistema

El sistema sigue una arquitectura en capas separando la lógica de negocio, acceso a datos e interfaz de usuario:

• Capa de Modelos: Define la estructura de datos usando SQLAlchemy ORM
• Capa de Repositorios: Maneja el acceso a la base de datos
• Capa de Servicios: Contiene la lógica de negocio
• Capa de GUI: Interfaz gráfica con CustomTkinter
• Capa de Utilidades: Funciones auxiliares y helpers

📱 Aplicación móvil Android

El repositorio incluye SDEP Móvil, una aplicación nativa en Kotlin (Jetpack Compose, Room, Hilt) que se conecta al nodo central de sincronización como un puesto más de la intranet. Permite levantar registros de campo desde el teléfono, editarlos y consultarlos sin conexión; al recuperar la red, las operaciones viajan al servidor con el mismo protocolo que usan los puestos de escritorio y aterrizan en la tabla registros_moviles, visible desde la base institucional.

• Ingreso con contraseña (PBKDF2) y desbloqueo con huella o rostro.
• Roles de administrador, editor y consulta.
• CRUD completo con búsqueda, categorías y valor numérico.
• Cola de salida transaccional, cursor de sincronización y bandeja de conflictos.
• Sin dependencia de servicios en la nube: habla solo con el nodo del colegio.

Instrucciones de compilación, emparejamiento y contrato del protocolo en android/README.md.

🔄 Servidor de Sincronización

El sistema incluye un servidor de sincronización que permite que múltiples instalaciones del sistema (en diferentes computadoras) se mantengan sincronizadas automáticamente. El servidor puede ejecutarse en cualquier computadora sin necesidad de un servidor dedicado y está configurado para comunicarse con:

• ✅ Otras computadoras con el mismo programa en la red local
• ✅ Aplicación Android (SDEP Móvil) en la misma red WiFi
• ✅ Cualquier dispositivo conectado a la misma red

Inicio Rápido del Servidor Local

# Opción 1: Script de inicialización automática (recomendado)
python iniciar_servidor.py

# El servidor mostrará automáticamente las URLs de conexión:
# - Desde esta PC: http://127.0.0.1:8765
# - Desde Android/otros PCs: http://192.168.1.XXX:8765

Esto:

• Crea la base de datos central (sync_central.db)
• Inicializa el esquema necesario
• Crea usuarios por defecto (admin, manager, user, viewer)
• Crea un dispositivo para conexión
• Inicia el servidor HTTP en el puerto 8765
• Muestra la IP local para conectar desde Android y otros equipos

Inicio automático desde la aplicación

En la instalación de escritorio no hace falta ejecutar ningún script ni responder preguntas. Desde la primera ejecución el nodo central arranca solo con la aplicación, incluso antes de iniciar sesión, y queda visible en el área de notificación de Windows, que muestra su estado y avisa cuando ya está disponible para el teléfono.

La auto-configuración copia al nodo central las cuentas de este equipo que aún no existan allí, con su misma contraseña (solo el hash), y crea las cuentas iniciales que falten, de modo que el teléfono entra con el mismo usuario y contraseña que la computadora. También deja este equipo como puesto cliente del nodo local. Desde el icono se puede copiar la URL de red para el teléfono, ver los datos de conexión, iniciar o detener el servidor y salir. Si el servicio se cayera, la aplicación lo vuelve a levantar sola; al salir, se cierra de forma ordenada.

Usuarios Por Defecto

Usuario	Contraseña	Rol
admin	Admin1234	Administrador total
manager	Gestor1234	Gestor con permisos de edición
user	Usuario1234	Usuario estándar
viewer	Lector1234	Solo lectura

IMPORTANTE: Cambie estas contraseñas después del primer inicio.

En el arranque automático, las cuentas que ya existen en el equipo se copian al nodo central con su contraseña actual; la tabla anterior solo se aplica a las cuentas que falten o al script manual.

Conectar Clientes al Servidor

Desde la Aplicación de Escritorio (Otro PC en la Red)

1. Vaya a Configuración → Sincronización
2. Configure la URL del servidor (use la IP local que muestra el servidor)
   • Ejemplo: http://192.168.1.100:8765
3. Ingrese el token del dispositivo
4. Active la sincronización

Desde la Aplicación Móvil Android

1. Instale y abra SDEP Móvil en el teléfono, en la misma Wi-Fi.
2. Escriba solo su usuario y contraseña de la institución. No hay dirección, equipo ni token que configurar: el teléfono descubre el escritorio por difusión UDP y, si la red la bloquea, por sondeo de la subred.
3. Si el escritorio aún no aparece, pulse «Volver a buscar». La app sigue intentando en segundo plano mientras el equipo se enciende.

Configuración de Firewall (Importante)

Para que Android y otros PCs puedan conectarse, el firewall debe permitir el puerto 8765/TCP y el 8766/UDP (descubrimiento automático):

Windows:

New-NetFirewallRule -DisplayName "SDEP Servidor" -Direction Inbound -LocalPort 8765 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "SDEP Descubrimiento" -Direction Inbound -LocalPort 8766 -Protocol UDP -Action Allow

El instalador crea esta regla automáticamente para las redes privada y de dominio; al ejecutar desde el código fuente hay que crearla a mano.

Linux (UFW):

sudo ufw allow 8765/tcp

Gestión del Servidor

# Ver dispositivos registrados
py -3 -m sync_agent dispositivos --db sqlite:///sync_central.db --listar

# Crear un nuevo dispositivo
py -3 -m sync_agent servidor --db sqlite:///sync_central.db --crear-dispositivo "Puesto 2"

# Ver sesiones activas
py -3 -m sync_agent sesiones --db sqlite:///sync_central.db --listar

Documentación Completa

Para instrucciones detalladas sobre configuración, seguridad, firewall y solución de problemas, consulte GUIA_SERVIDOR_LOCAL.md.

🔄 CI/CD Pipeline (GitHub Actions)

La integración continua se reparte entre dos workflows complementarios.

.github/workflows/build.yml (integración y empaquetado):

1. Pruebas: ejecuta la suite completa de pytest sobre los 33 archivos de (32 test_*.py + conftest.py) tests/ en cada push a main o develop.
2. Compilación Windows: en windows-latest, empaqueta la app con PyInstaller (directorio onedir + icono + metadatos de versión).
3. Actualizador automático: compila SDEP_CPP5_AutoUpdater.exe (PyInstaller onefile, sin consola) con la ventana de estado y el ícono de bandeja del sistema.
4. Instalador: genera SistemaGestionPersonal-Setup-<versión>.exe con Inno Setup (asistente en español/inglés, accesos directos, desinstalador); incluye el actualizador dentro del instalador y lo programa en el Programador de tareas cada 2 días.
5. Compilación Linux: compila el mismo spec/app.spec dentro de un contenedor Debian 13 (glibc 2.41) y empaqueta la versión portable de Linux en un tar.gz. El binario funciona en Debian 13 y Ubuntu 24.04 LTS o superior; se autoverifica con --selftest bajo xvfb-run dentro de contenedores debian:13-slim y se comprueba que la glibc máxima requerida no supere 2.41.
6. Artefactos: sube a la ejecución el instalador Setup.exe, el ZIP portable de Windows, el tar.gz portable de Linux y el reporte de cobertura. El actualizador SDEP_CPP5_AutoUpdater.exe se compila y queda incluido dentro del instalador. Este workflow no publica releases: solo compila y verifica.

.github/workflows/release.yml (release firmada) se activa con cada push a main, con etiquetas v* y de forma manual. Aplica firma masiva profunda en dos pasadas —todo el contenido de dist/ antes de Inno Setup y el instalador final después—, audita que ningún archivo firmable quede sin firma y publica la Release con un único adjunto: el instalador SistemaGestionPersonal-Setup-<versión>.exe. En los push a main la etiqueta de la release continua es continuous-v<versión>.<número de ejecución>; una etiqueta vX.Y.Z produce una release versionada con ese nombre. La firma requiere los secretos PFX_BASE64 y PFX_PASSWORD.

Cada cambio publicado genera su Release firmada automáticamente:

git push origin main

Para una release versionada (opcional):

git tag v3.0.1
git push origin v3.0.1

🔧 Instalación

Instalador para usuarios finales (Windows 10/11)

Descargue SistemaGestionPersonal-Setup-<versión>.exe desde el Release o los artefactos del workflow y ejecútelo. Los datos de la aplicación (base de datos, documentos, respaldos) se guardan en %LOCALAPPDATA%\SistemaGestionPersonal, independientes de la instalación.

El instalador incluye el actualizador automático (SDEP_CPP5_AutoUpdater.exe): al terminar la instalación queda programado para comprobar novedades cada 2 días y se ejecuta con ventana de estado e ícono en la bandeja del sistema.

Versión portable para Linux

Descargue SistemaGestionPersonal-Linux-<versión>.tar.gz desde el Release, descomprímalo y ejecute el binario:

tar -xzf SistemaGestionPersonal-Linux-<versión>.tar.gz
cd SistemaGestionPersonal
./SistemaGestionPersonal

Los datos de la aplicación se guardan junto al ejecutable.

Entorno de Desarrollo

1. Clonar el repositorio:

git clone <repository-url>
cd SDEP_CPP5

2. Crear entorno virtual:

python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

3. Instalar dependencias:

pip install -r requirements.txt

4. Ejecutar la aplicación:

python src/main.py

Construcción de Ejecutable e Instalador (local)

1. Instalar dependencias de construcción:

pip install pyinstaller
# Instale además Inno Setup 6: https://jrsoftware.org/isdl.php
# o con Chocolatey: choco install innosetup -y

2. Ejecutar el script de construcción:

python build.py        # ejecutable + actualizador + instalador
python build.py --exe  # solo el ejecutable
python build.py --updater  # solo el actualizador automático

3. Resultados:
   • Ejecutable: dist/SistemaGestionPersonal/
   • Actualizador: dist_updater/SDEP_CPP5_AutoUpdater.exe
   • Instalador: dist_installer/SistemaGestionPersonal-Setup-<versión>.exe

La versión se lee del archivo VERSION (fuente única).

📁 Estructura del Proyecto

SDEP_CPP5/
├── src/                        # Código fuente principal
│   ├── gui/                    # Interfaz gráfica de usuario
│   │   ├── main_window.py      # Ventana principal
│   │   └── frames.py           # Frames de cada módulo
│   ├── models/                 # Modelos de datos (ORM)
│   │   ├── base.py             # Modelo base
│   │   ├── enums.py            # Enumeraciones
│   │   ├── empleado.py        # Modelo de empleado
│   │   ├── documento.py       # Modelo de documento
│   │   ├── incidencia.py       # Modelo de incidencia
│   │   ├── pago.py            # Modelo de pago
│   │   └── configuracion.py    # Modelo de configuración
│   ├── repositories/           # Acceso a datos
│   │   ├── base_repository.py  # Repositorio base
│   │   ├── empleado_repository.py
│   │   ├── documento_repository.py
│   │   ├── incidencia_repository.py
│   │   ├── pago_repository.py
│   │   └── configuracion_repository.py
│   ├── services/               # Lógica de negocio
│   │   ├── empleado_service.py
│   │   ├── documento_service.py
│   │   ├── incidencia_service.py
│   │   ├── pago_service.py
│   │   └── configuracion_service.py
│   ├── utils/                  # Utilidades y helpers
│   │   ├── helpers.py          # Funciones auxiliares
│   │   ├── validators.py      # Validadores
│   │   ├── document_manager.py # Gestión de documentos
│   │   └── pdf_generator.py    # Generación de PDFs
│   ├── config/                 # Configuración
│   │   ├── settings.py         # Configuración general
│   │   └── database.py         # Configuración de base de datos
│   └── main.py                 # Punto de entrada
├── tests/                      # Pruebas unitarias
├── requirements.txt            # Dependencias del proyecto
├── requirements-dev.txt        # Dependencias de desarrollo
├── pyproject.toml             # Configuración del proyecto
├── build.py                   # Script de construcción
├── updater/                   # Actualizador automático
│   ├── auto_updater.py        # Lógica principal (GitHub, descarga, tareas)
│   ├── updater_gui.py         # Ventana de estado (tkinter)
│   ├── tray_icon.py           # Ícono de bandeja del sistema (ctypes)
│   └── updater.spec           # Spec de PyInstaller
└── .env.example               # Ejemplo de variables de entorno

🗄️ Base de Datos

El sistema utiliza SQLite como base de datos local. La base de datos se crea automáticamente al iniciar la aplicación y se encuentra en el archivo personal_management.db.

Tablas Principales:

• empleados: Información completa de empleados
• documentos: Documentos digitalizados de empleados
• incidencias: Permisos, reposos y ausencias
• contratos: Contratos laborales y su ciclo de vida
• pagos: Registro de nóminas y pagos
• estudiantes, grados, matriculas, notas_finales y periodos_academicos: subdominio académico (legajo, estructura escolar y calificaciones)
• tokens_sesion: tokens de sesión con alcance académico (solo su hash; no se sincronizan entre equipos)
• configuraciones: Configuración del sistema

📖 Uso

Atajos de Teclado

Atajo	Acción
Ctrl+1 … Ctrl+9	Ir al módulo 1 (Dashboard) … 7 (Configuración), 8 (Estudiantes) y 9 (Calificaciones)
Ctrl+N	Nuevo registro en el módulo activo
Ctrl+F	Buscar / enfocar el filtro del módulo activo
Ctrl+S	Guardar cambios (Configuración)
F5	Actualizar la lista del módulo activo
Esc	Cerrar diálogos o limpiar la selección de la tabla

Primeros Pasos

1. Configuración Inicial:

   • Configure los datos de la institución en la sección "Configuración"
   • Establezca los porcentajes de deducciones para nómina

2. Registro de Empleados:

   • Vaya a la sección "Empleados"
   • Haga clic en "Nuevo Empleado"
   • Complete los datos personales, laborales y de contacto

3. Gestión Documental:

   • Seleccione un empleado
   • Vaya a "Documentos"
   • Cargue documentos digitalizados (cedulas, títulos, etc.)

4. Incidencias:

   • Seleccione un empleado
   • Vaya a "Incidencias"
   • Registre permisos, reposos o ausencias
   • Apruebe o rechace solicitudes

5. Nómina:

   • Vaya a "Nómina"
   • Seleccione el periodo
   • Genere la nómina automáticamente
   • Genere recibos de pago en PDF

🔐 Seguridad

• Los datos se almacenan localmente en SQLite
• La aplicación funciona sin conexión a internet (solo el actualizador automático la consulta, de forma opcional)
• Los documentos se almacenan en el sistema de archivos local
• Se recomienda realizar copias de seguridad periódicas

🛠️ Desarrollo

Ejecutar Tests

pytest tests/

Formateo de Código

black src/
isort src/

Linting

flake8 src/
pylint src/

🔄 Flujo de Trabajo

1. Configuración Inicial: Al iniciar el sistema por primera vez, configure los datos de la institución
2. Registro de Empleados: Agregue los empleados con sus datos personales y laborales
3. Gestión Documental: Cargue los documentos requeridos para cada empleado
4. Control de Incidencias: Registre permisos, reposos y ausencias
5. Procesamiento de Nómina: Genere nóminas periódicas y emita recibos de pago

⚙️ Configuración

Variables de Entorno

Copie .env.example a .env y configure las variables:

DATABASE_URL=sqlite:///personal_management.db
APP_NAME=Sistema de Gestión de Personal
DEBUG=False

Configuración de la Aplicación

La configuración se puede modificar desde la sección "Configuración" de la aplicación:

• General: Nombre de la institución, dirección, contacto
• Nómina: Porcentajes de deducciones, salario mínimo
• Recursos Humanos: Días de vacaciones, horas laborales

🐛 Troubleshooting

Error al iniciar la aplicación

• Verifique que Python 3.15+ esté instalado
• Instale las dependencias: pip install -r requirements.txt
• Verifique que los directorios documents, photos, exports existan

Error de base de datos

• No elimine el archivo personal_management.db. Conserve el archivo dañado para diagnóstico.
• En su lugar, use la función de respaldo automático o recupere desde %LOCALAPPDATA%\SistemaGestionPersonal

Problemas con PyInstaller

• Asegúrese de tener PyInstaller instalado: pip install pyinstaller
• Verifique que el archivo spec/app.spec exista
• Ejecute el script build.py

📄 Licencia

Este proyecto está bajo licencia MIT.

👥 Autores

Desarrollado para gestión de personal en instituciones educativas.

📞 Soporte

Para soporte o consultas, contacte al equipo de desarrollo.

---

• Versión: 3.0.1
• Última actualización: 2026