Skilled ERP

01 Qué es

API JSON en Flask, sin HTML, que sirve al SPA de Skilled ERP (React + Vite, hosteado en Vercel). Este repo expone /api/* y el canal de Socket.IO; el frontend vive en su propio repo. Cubre nóminas, empleados, proyectos, horas trabajadas, préstamos, inventario de materiales y herramientas, con notificaciones y bitácora en tiempo real.

• Empleados: alta, baja y edición; campos laborales, personales, médicos y financieros con whitelist por rol. Notas internas tipo «chatter» en la ficha.
• Nómina: prenómina semanal, descuentos, depósitos extra, préstamos con abonos y el ajuste Inbursa por periodo.
• Horas: reportes semanales, registros diarios, ausencias, saldo de vacaciones y checada por RFID o QR.
• Proyectos M:N: un trabajador puede estar en varios proyectos; expediente y credenciales se derivan solo de los proyectos activos.
• Inventario: productos, almacenes y estantes con QR; movimientos con bloqueo anti-concurrencia; solicitudes con flujo PENDIENTE → APROBADA / RECHAZADA / ENTREGADA y entrega parcial; tomas físicas con ajuste automático; etiquetas Avery y órdenes de compra.
• Herramientas: catálogo y unidades físicas rastreables por serie o QR; asignaciones a trabajadores, mantenimientos, incidencias y baja con autorización.
• Panel de sistemas: estado de la infraestructura, tráfico y percentiles, sesiones activas, bloqueos de cuenta, eventos de seguridad y archivos huérfanos en R2.
• Reportes: PDF (recibos, constancias, solicitudes, tomas, OC) y Excel (totales por proyecto, histórico), saneados contra inyección de fórmulas. Carga masiva de empleados y productos desde .xlsx.

02 Arquitectura

Todo entra por Cloudflare, baja por el túnel, pasa por Nginx y termina en Gunicorn. El servidor de origen no publica ningún puerto hacia afuera: el túnel es una conexión saliente y el firewall descarta cualquier intento de conexión entrante directa. En local ese mismo camino se levanta con docker compose up.

Los 4 workers de gevent son procesos distintos, así que todo lo que debe ser común (rate-limit, lockout, anti-replay de 2FA, eventos de Socket.IO) vive en Redis. Los archivos no se guardan tal cual: una imagen externa se valida contra SSRF, se comprueban sus magic bytes, se reescribe con Pillow a WebP y se sube a R2 con el SHA-256 de su contenido como llave. En inventario, dos movimientos sobre el mismo stock no se pisan porque la fila se toma con SELECT … FOR UPDATE antes de escribir.

03 Puesta en marcha

Requisitos: Python 3.12, PostgreSQL 14+, Redis y, por el camino recomendado, Docker con Docker Compose. Con Docker se levanta la API con su propio PostgreSQL, Redis y ClamAV usando el .env de la raíz. Es la única forma de probar en Windows el camino real de WebSockets con gevent y el antivirus, que en el venv nativo no arrancan.

> cp .env.example .env               # rellenar SECRET_KEY, DATABASE_URL, REDIS_URL…
> docker compose up --build          # api en http://localhost:5000
> docker compose logs -f api         # logs de la API
> docker compose exec api pytest     # tests dentro del contenedor

> python -m venv venv
> source venv/bin/activate           # Linux / Mac; en Windows: venv\Scripts\activate
> pip install -r requirements.txt
> flask db upgrade                   # crea la BD en Postgres antes
> python run.py                      # http://localhost:5000

04 Estructura del código

> run.py                  # entry point; monkey-patch de gevent si SOCKETIO_ASYNC_MODE=gevent
> Dockerfile              # imagen de la API (builder + runtime)
> docker-compose.yml      # stack de desarrollo: api, db, redis, clamav
> docker-compose.prod.yml # stack del VPS
> nginx.config            # config de Nginx
> gunicorn.serviceee      # unit de systemd; se instala como nominas.service
> app/__init__.py         # create_app(): CORS, Talisman, Limiter, blueprints, Socket.IO
> app/extensions.py       # db, limiter, mail; IP real tras Cloudflare; EncryptedString
> app/realtime.py         # Socket.IO: handshake, salas, hooks ORM, emit_to_*
> app/observabilidad.py   # after_request: contadores, histograma y detalle en Redis
> app/models/             # SQLAlchemy, 12 módulos por dominio
> app/routes/             # 18 blueprints, cada uno como sub-paquete con _core.py
> app/utils/              # seguridad, archivos, R2, antivirus, imágenes, horas, nómina
> templates/              # Jinja solo para PDFs (xhtml2pdf)
> migrations/             # Alembic
> tests/                  # 36 módulos de pytest

create_app() arranca en orden fijo: config → espera a Redis → extensiones → CORS solo en /api/* → Talisman y CSP → registra los 18 blueprints (exentos de CSRF, protegidos por JWT) → error handlers globales → headers de seguridad y Cache-Control: no-store → tablas auxiliares → ProxyFix → Socket.IO al final, para ver los headers ya corregidos.

• Cada blueprint es un sub-paquete: _core.py con el blueprint, los decoradores y los serializers, y un módulo por tema.
• _api_helpers.py compartido: current_user(), is_admin(), require_admin(), require_roles() y el decorador api_transactional (rollback y log automático ante excepción).
• Toda mutación relevante llama a log_action(...): escribe en audit_log con usuario, IP y acción, y el insert dispara el push bitacora:new.
• Paginación estándar page / per_page con respuesta {items, total, pages}; trabajadores, préstamos y proyectos aceptan además sort / dir con whitelist de columnas.
• Excel con _sanitize_rows (anti =fórmula) y estilos compartidos entre 5 paquetes. PDF: Jinja → xhtml2pdf.
• models/ es SQLAlchemy puro, sin lógica de negocio; se re-exporta plano desde app/models/__init__.py.

05 Referencia de la API

216 rutas agrupadas por blueprint. Todas requieren JWT (Authorization: Bearer …) salvo login, refresh y /health. Respuestas de error estándar: 401 (JWT ausente o expirado), 403 (rol), 404, 422 (validación), 429 (rate-limit) y 419 (CSRF en flujos con cookie).

06 Roles

La autorización va por decoradores (require_admin, require_roles, _require_inventario…) más whitelist de campos editables por rol en trabajadores: el coordinador no toca salarios ni PII fiscal, y lo prohibido se ignora y regresa en warnings. El coordinador tiene «ownership»: solo ve y edita lo de sus propios proyectos.

07 Tiempo real

El connect valida el JWT y cada conexión se une a las salas user:{id} y role:{rol}; join:reporte agrega reporte:{id} para el kiosko de captura. El worker que hace un cambio lo publica en Redis y el resto reenvía el evento a sus sockets. El evento solo lleva {id, action}: el navegador vuelve a pedir el dato por REST, donde el permiso se valida otra vez. Los hooks ORM emiten solo si el commit fue exitoso.

Notificaciones in-app: REPORTE_CERRADO al cerrar un reporte de horas y PRENOMINA_CERRADA al cerrar una prenómina; el push va por notif:new y el polling queda como respaldo. Las leídas se eliminan a los 30 días en cada GET /resumen, sin cron externo. La sesión del SPA se renueva sola 60 s antes de expirar y, si aun así llega un 401, varias peticiones en vuelo comparten un único refresh.

08 Seguridad

El sistema pasó por una auditoría ofensiva completa (pentest, revisión de código e infraestructura): score 5.8 → 8.4/10, con 4 críticas y 7 altas cerradas en código.

09 Producción

Cadena: Cloudflare Tunnel → Nginx (127.0.0.1:80) → Gunicorn (127.0.0.1:8000) → Flask. El unit instalado se llama nominas.service; el archivo del repo es gunicorn.serviceee.

> sudo cp gunicorn.serviceee /etc/systemd/system/nominas.service
> sudo systemctl daemon-reload && sudo systemctl enable --now nominas
> sudo cp nginx.config /etc/nginx/sites-available/skilled
> sudo ln -s /etc/nginx/sites-available/skilled /etc/nginx/sites-enabled/skilled
> sudo nginx -t && sudo systemctl reload nginx

• Gunicorn: 4 workers GeventWebSocketWorker × 1000 conexiones. gthread no implementa el upgrade a WebSocket y eventlet es incompatible con psycopg3.
• --max-requests 1000 con jitter recicla workers para evitar fugas de pandas, openpyxl y xhtml2pdf.
• Nginx: rate-limit por IP como segunda capa, IP real de Cloudflare, anti-Slowloris y anti request smuggling, bloque dedicado para /socket.io/ con proxy_read_timeout 3600s, whitelist de métodos y bloqueo de paths escaneados (.env, wp-login.php…).
• Los headers de seguridad y CORS los pone Flask; no se duplican en Nginx.
• Frontend en Vercel con VITE_API_URL=https://api.<dominio>/api; el backend lleva CORS_ORIGINS con el dominio de Vercel, RT_COOKIE_SAMESITE=None, FLASK_ENV=production y USE_X_ACCEL_REDIRECT=true.

> curl https://api.<dominio>/health                      # {"status":"ok"}
> sudo journalctl -u nominas -n 20 --no-pager           # IPs reales, no 127.0.0.1
> sudo tail -n 20 /var/log/nginx/skilled_api.access.log  # upstream=127.0.0.1:8000 request_time=…

10 Base de datos

PostgreSQL vía SQLAlchemy y Alembic (flask db …). Los modelos están partidos por dominio en app/models/. Convenciones: PK id autoincremental salvo en los mapeos M:N, timestamps en UTC, montos en Numeric(10,2) y estados como cadenas en mayúsculas.

> flask db migrate -m "descripción"    # nueva migración
> flask db upgrade                     # aplicar
> flask db current                     # revisión actual
> pytest tests/                        # correr tras cualquier cambio