hyper_api

API REST construida con FastAPI, SQLAlchemy 2, Alembic y PostgreSQL, con autenticación basada en PyJWT y bcrypt (hash de contraseñas), configuración mediante variables de entorno y logging estándar de Python.

Historial del scaffolding y decisiones: docs/plan-historial.md · Tablas auth/RBAC: docs/tables-auth-permissions.md · Primer usuario y token: docs/primer-acceso-api.md · CORS: docs/manual-cors.md

Stack

Componente	Tecnología
Framework web	FastAPI
Servidor ASGI (desarrollo)	Uvicorn
Servidor (producción)	Gunicorn + workers Uvicorn
ORM	SQLAlchemy 2.x
Migraciones	Alembic
Base de datos	PostgreSQL (driver psycopg 3)
Configuración	pydantic-settings (.env)
JWT	PyJWT
Hash de contraseñas	bcrypt
Logging	logging (stdlib), archivo rotativo + consola
Auth / permisos	Usuarios, roles y permisos (RBAC); JWT en rutas /api/v1/auth/*
Python	3.11+ recomendado

Requisitos previos

• Python 3.11 o superior
• PostgreSQL accesible (local o remoto)
• pip

Despliegue local

1. Clonar o situar el proyecto en tu máquina y entrar en la raíz del repositorio (hyper_api/).

2. Crear el entorno virtual localenv (desde la raíz del proyecto):

   python -m venv localenv
   

   Activar el entorno virtual (el prompt suele mostrar el prefijo (localenv)):

   Windows — PowerShell (recomendado): estando en la raíz del proyecto (hyper_api\), el entorno vive en localenv\ y los scripts en localenv\Scripts\.

   cd C:\ruta\completa\a\hyper_api
   .\localenv\Scripts\Activate.ps1
   

   Si prefieres la ruta absoluta al script (sustituye la carpeta del proyecto por la tuya):

   & "C:\ruta\completa\a\hyper_api\localenv\Scripts\Activate.ps1"
   

   Si aparece un error de política de ejecución, puedes permitir scripts locales para tu usuario con:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

   Windows — Símbolo del sistema (CMD): mis paths bajo localenv\Scripts\:

   cd C:\ruta\completa\a\hyper_api
   localenv\Scripts\activate.bat
   

   Con ruta absoluta:

   C:\ruta\completa\a\hyper_api\localenv\Scripts\activate.bat
   

   Ubuntu (Linux) y macOS — Bash o terminal estándar:

   source localenv/bin/activate
   

   Para desactivarlo en cualquier sistema: deactivate.

3. Instalar dependencias (puede tardar según red y disco):

   pip install -r requirements.txt
   

4. Variables de entorno: copia .env.example a .env y configura las variables DB_* (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, y opcionalmente DB_DRIVER). La URL de SQLAlchemy se arma en código (Settings.database_url). Ajusta también SECRET_KEY y, si aplica, CORS_ORIGINS. Si antes usabas DATABASE_URL en un solo valor, elimínala y reparte los datos en estas variables.

Autenticación (resumen)

• Guía paso a paso con requests listos para copiar: docs/primer-acceso-api.md.
• Esquema de tablas: docs/tables-auth-permissions.md.
• POST /api/v1/auth/register — JSON con email, username, password (registro; endurecer en producción).
• POST /api/v1/auth/token — formulario OAuth2 (username puede ser email o nombre de usuario, password).
• GET /api/v1/auth/me — cabecera Authorization: Bearer <token>.

Los roles y permisos se asignan en base de datos (o futuros endpoints admin); el token JWT solo incluye el sub (id de usuario).

Logs en local

• Variables: LOG_LEVEL (p. ej. INFO, DEBUG) y LOG_FILE_PATH (por defecto logs/app.log; puedes usar una ruta absoluta).
• Seguir el archivo en tiempo real:
  • Linux / macOS: tail -f logs/app.log (o tail -F si el archivo se rota y se recrea).
  • Windows (PowerShell): Get-Content -Path logs\app.log -Wait -Tail 50
• Con Uvicorn en primer plano también verás salida en consola.

Despliegue en producción

1. Definir variables de entorno en el sistema, systemd, panel del PaaS o orquestador (no commitear .env con secretos).

2. Instalar dependencias en el entorno de ejecución (pip install -r requirements.txt o imagen que lo haga en build).

3. Ejecutar migraciones contra la base de producción:

   alembic upgrade head
   

4. Servir la aplicación con Gunicorn y workers Uvicorn, por ejemplo:

   gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8000
   

   Ajusta -w (número de workers) según CPUs y carga.

5. Buenas prácticas: proxy inverso (nginx, Caddy, etc.) con HTTPS, SECRET_KEY fuerte y única, ENVIRONMENT=production, revisar CORS_ORIGINS para los orígenes reales del front. No uses --reload en producción.

Logs en producción

• Configura LOG_FILE_PATH en una ruta con permisos de escritura para el usuario del servicio (p. ej. bajo /var/log/...).
• Para inspección en el servidor: mismos comandos tail -f o Get-Content -Wait -Tail.

Comandos delegados (operaciones que pueden tardar)

La instalación con pip, las migraciones contra bases remotas y el servidor en primer plano pueden ser lentos o bloqueantes. En flujos automatizados conviene ejecutarlos tú mismo y confirmar el resultado antes de seguir. Detalle en docs/plan-historial.md.

Estructura principal

• app/ — aplicación FastAPI (main.py, api/, core/, db/, models/, schemas/)
• alembic/ — migraciones
• logs/ — directorio de logs (los .log no se versionan)
• docs/ — documentación de historial del proyecto