Empezar aquí¶
Esta carpeta resume cómo está armado eseasa_sys y cómo operar el stack day-to-day. Los demás archivos amplían cada área:
- Guía de usuario: flujo paso a paso para el panel web sin asumir conocimientos técnicos.
- Arquitectura: visión detallada de backend, frontend y servicios auxiliares (sesión, permisos, DSL, tareas, logs, backups, etc.).
- Despliegue: cómo levantar el entorno con Docker, ejecutar migraciones Alembic y poner a correr los workers Huey.
- API y Frontend: referencias para integraciones y para quienes extiendan la UI basada en
DynamicTable. - Referencia automática: notas rápidas por módulo (ej.
app.routes.users).
Descripción¶
eseasa_sys es la plataforma interna del corporativo ESESASA para gestionar funciones y requerimientos de los diferentes departamentos. Provee tanto una API REST (FastAPI) como paneles web y funcionalidades administrativas para:
- Coordinar solicitudes y requerimientos internos.
- Administración de usuarios y permisos por departamento.
- Paneles y reportes específicos por área (definidos por cada departamento).
- Integración con servicios de correo y llamadas a APIs externas.
Usuarios previstos: administradores globales, administradores de departamento, empleados internos y usuarios externos como proveedores o clientes.
Mapa rápido del proyecto¶
| Capa | Ubicación | Descripción |
|---|---|---|
| Frontend | frontend/ |
Next.js 13 (app router) con componentes compartidos (components/) y páginas por dominio (app/admin, app/ingenieria, etc.). |
| Backend | app/ |
FastAPI modular. Rutas agrupadas por dominio (admin, ingeniería, construcción, LDA), utilitarios (app/utils), tareas Huey (app/tasks) y modelos SQLAlchemy (app/models). |
| Infra | docker-compose.yml, nginx/ |
Servicios auxiliares: PostgreSQL, Redis, worker Huey y Nginx como reverse proxy. |
| Datos compartidos | app/models/base.py + Alembic |
SQLAlchemy declarative Base compartido entre modelos y migraciones. |
Base de datos: PostgreSQL en producción (instancia fuera de Docker). Para desarrollo y pruebas locales se ofrece una copia de PostgreSQL via Docker Compose.
Despliegue: pensado para Docker Compose; puede adaptarse a otras plataformas si se requiere.
Estado funcional: muchas funcionalidades y módulos se definen por departamento — el repositorio proporciona la estructura base (autenticación, modelos, rutas, plantillas y migraciones) y se extiende por cada área.
Estructura principal del repositorio¶
-
app/– Código principal de la aplicación FastAPI.alembic/,alembic.ini– Migraciones de base de datos.auth/– Autenticación y autorización.core/– Configuración, conexión a la base de datos y lifecycle.models/– Modelos ORM.routes/– Rutas y controladores (submódulos:panel,www,admin).static/,templates/– Activos y plantillas para la UI.utils/– Utilidades y helpers.
-
Dockerfile,docker-compose.yml– Contenedores y orquestación. requirements.txt– Dependencias de Python.
Integraciones conocidas¶
- Servicios de correo (envío de notificaciones, recuperación de contraseña, etc.).
- Consultas a APIs externas (dependiendo del módulo/servicio requerido por cada departamento).
Instrucciones rápidas¶
Recomendado: usar Docker Compose para levantar una copia local que incluye la aplicación y, opcionalmente, una base de datos PostgreSQL para pruebas.
1) Levantar con Docker Compose (recomendado):
Por defecto la configuración de docker-compose.yml debería exponer los puertos y montar volúmenes para datos y código; revisa las variables de entorno en el archivo o en un .env si existe.
2) Desarrollo local (sin Docker) - PowerShell:
# Crear y activar un entorno virtual
python -m venv .venv
. .\.venv\Scripts\Activate.ps1
# Instalar dependencias
pip install -r requirements.txt
# Configurar la variable de conexión a la base de datos (ejemplo)
$env:DATABASE_URL = "postgresql://user:password@localhost:5432/system"
# Ejecutar migraciones (Alembic)
alembic upgrade head
# Ejecutar la aplicación
uvicorn app.main:app --reload
Descripción del Entorno¶
El servidor Ubuntu se gestiona a través de una consola conectada por SSH, lo que permite acceder a su terminal para administración y supervisión. Para la edición y configuración remota, se utiliza Visual Studio Code con extensiones compatibles con SSH.
Uso de NGINX¶
Se utiliza NGINX como proxy inverso para redireccionar puertos y exponer servicios de manera segura. También se encarga de servir certificados HTTPS para los dominios configurados, garantizando comunicaciones cifradas.
Cuando una solicitud HTTPS llega al servidor, NGINX la desencripta, la procesa internamente y luego vuelve a encriptarla antes de enviarla al cliente.
Ejemplo de Flujo de Peticiones con NGINX¶
Dominio actual en uso: grupoeseasa
NGINX actúa como intermediario entre el cliente y los servicios del servidor. A continuación, se muestra un ejemplo simplificado del flujo de una petición:
| grupoeseasa.com | localhost:8000 |
|---|---|
| Quién hace la petición | A dónde se redirige la petición |
Cuando una solicitud HTTPS llega al servidor, NGINX desencripta la petición para que pueda ser procesada internamente. Una vez que el servicio correspondiente genera una respuesta, NGINX vuelve a encriptarla antes de enviarla de regreso al cliente.
Este proceso garantiza una comunicación cifrada de extremo a extremo y permite una gestión centralizada del tráfico y la seguridad.
Configuración del archivo hosts en Windows¶
Para el correcto funcionamiento del sistema, es necesario agregar al archivo hosts de Windows el dominio que se asigne en el archivo .env. Esto se debe a que, al usar subdominios para compartir cookies, el navegador valida el dominio. Además, todos los subdominios deben estar registrados en el archivo hosts.
Se ha establecido la terminación .test para los dominios, con el fin de evitar referencias a HTTPS. Asegúrate de incluir todas las entradas necesarias en el archivo hosts para que el sistema funcione correctamente (add-grupoeseasa-domain.ps1).