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.

🚀 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
• Descuento automático de la cuota del préstamo respetando el tope sobre el neto del empleado
• Generación de recibos de pago y planilla de nómina en PDF
• Control de pagos pendientes y realizados

Control de Asistencia

• Registro de jornadas con cálculo de horas trabajadas y tardanzas
• Horarios por empleado y día de la semana (jornada diurna, nocturna o mixta)
• Horas extra clasificadas por recargo, incluidos feriados y días de descanso
• Ausencias justificadas automaticamente desde las incidencias aprobadas
• Reporte PDF de asistencia por período y exportación a Excel

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

Anticipos y Préstamos

• Solicitud, aprobación o rechazo y seguimiento del saldo por cuotas
• Tope de descuento configurable sobre el salario y sobre el neto de la nómina
• Plan de pagos cuota por cuota y descuento automático en el pago
• Reporte PDF de la cartera

Alertas del Sistema

• Alertas accionables con severidad y acceso directo al módulo donde se resuelven
• Cubren vencimientos, contratos, asistencia, pendientes, respaldos y credenciales

Panel Analítico

• Indicadores clave: nómina del mes, ausentismo, contratos por vencer y saldo por cobrar
• 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 y control de vencimientos de documentos
• Reportes de asistencia, contratos, préstamos y alertas
• 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, gráficos propios y panel de alertas
• 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

🔄 CI/CD Pipeline (GitHub Actions)

El workflow .github/workflows/build.yml automatiza todo el ciclo:

1. Pruebas: ejecuta la suite completa de pytest (aislada) en cada push.
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 Setup.exe, ZIP portable (Windows), tar.gz (Linux) y SDEP_CPP5_AutoUpdater.exe como artefactos del run.
7. Release continua: cada push a main publica automáticamente un Release de GitHub con el instalador y las versiones portables de Windows y Linux (sin necesidad de crear etiquetas). Un push con etiqueta vX.Y.Z genera una release versionada con ese nombre.

Cada cambio publicado genera su Release automáticamente:

git push origin main

Para una release versionada (opcional):

git tag v2.81
git push origin v2.81

🔧 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
• pagos: Registro de nóminas y pagos
• configuraciones: Configuración del sistema

📖 Uso

Atajos de Teclado

Atajo	Acción
Ctrl+1 … Ctrl+6	Ir al módulo 1 (Dashboard) … 6 (Configuración)
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

• Elimine el archivo personal_management.db
• Reinicie la aplicación para recrear la base de datos

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: 2.82
Última actualización: 2026