backend/README.md

Backend - PoC SaaS Iframe

Este documento explica cómo funciona el backend del proyecto, qué endpoints ofrece y cómo se integra con el frontend React.

Propósito

El backend sirve como:

• API para autenticación con token, configuración y gestión de sesiones.
• servidor de archivos estáticos para el build de React en producción (frontend/dist).
• punto de entrada de administración, preview y experiencia embebida.
• watcher opcional que reconstruye el frontend cuando cambian los archivos fuente.

Estructura principal

• main.py - servidor FastAPI principal.
• requirements.txt - dependencias Python.
• run_server.bat - helper para arrancar el backend con el virtual environment local.
• .venv/ - entorno virtual Python del backend.
• home.html, admin.html, preview.html - páginas de apoyo.

Cómo ejecutar

Activar entorno virtual

En Windows CMD:

cd /d C:\Users\alane\OneDrive\Escritorio\Prueba-PoC\backend
.venv\Scripts\activate

En PowerShell:

cd C:\Users\alane\OneDrive\Escritorio\Prueba-PoC\backend
.\.venv\Scripts\Activate.ps1

Instalar dependencias

pip install -r requirements.txt

Ejecutar servidor

python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

O usar el helper:

run_server.bat

Comportamiento de producción

En producción, el backend sirve el build de React desde frontend/dist en la ruta /app.

• El HTML principal se carga en /app
• Los assets de Vite se sirven en /app/assets/...
• Si frontend/dist/index.html no existe, se devuelve un mensaje de error claro.

Endpoints principales

Páginas y visualización

• GET / - home.html
• GET /preview - preview.html
• GET /admin - admin.html
• GET /app - React app estática servida desde frontend/dist
• GET /widget.js - script JS que inyecta un iframe con el visualizador
• GET /health - estado del backend y si el frontend build está listo

API de integración

• POST /api/token - genera un token temporal para client_id
• GET /config - devuelve datos del cliente según client_id o token
• POST /session/start - marca la sesión como activa
• GET /api/keys - lista clientes registrados
• POST /api/generate-key - genera una nueva API key de cliente
• GET /api/active-sessions - muestra sesiones activas actuales

Lógica de token y cliente

Validación de token

• Los tokens se guardan en memoria en TOKENS
• Cada token vence después de TOKEN_TTL segundos
• Si el token ha expirado, se devuelve 401

Configuración del cliente

• El diccionario CLIENTS contiene los clientes registrados por defecto
• Cada cliente tiene nombre, color_primario y created_at
• POST /api/generate-key agrega un nuevo cliente a CLIENTS

Seguridad y headers importantes

El backend habilita:

• CORS abierto (allow_origins=["*"]) para facilitar el desarrollo
• Eliminación de x-frame-options en todas las respuestas
• Agrega Content-Security-Policy: frame-ancestors * para permitir iframes

Watcher automático de frontend

El backend también incluye un watcher que observa cambios en el frontend y ejecuta npm run build automáticamente.

Qué archivos vigila

• frontend/src/**/*.{ts,tsx,js,jsx,css,json,html}
• frontend/vite.config.ts
• frontend/package.json
• frontend/tsconfig.json

Cómo funciona

• Si el backend está ejecutándose, el watcher corre en un hilo daemon.
• Cuando detecta cambios, ejecuta npm run build en frontend/.
• El resultado actualiza frontend/dist para que /app sirva la versión nueva.

Requisitos del watcher

• Necesitas tener npm instalado y accesible desde el PATH.
• El backend debe arrancarse desde el directorio raíz del proyecto.

Desarrollo y producción

Desarrollo

• Para trabajar en el frontend con hot reload, usa el dev server de Vite:

cd /d C:\Users\alane\OneDrive\Escritorio\Prueba-PoC\frontend
npm run dev

• Abre http://localhost:5173/app?token=...

Producción / backend

• Para servir el frontend estático desde el backend:

cd /d C:\Users\alane\OneDrive\Escritorio\Prueba-PoC\frontend
npm run build

• Luego carga http://localhost:8000/app?token=...

Integración con hyper-ferreteria

Este backend puede montar la lógica de hyper-ferreteria en un prefijo alterno para evitar conflictos de rutas.

• Se carga si la carpeta ../hyper-ferreteria existe junto al directorio Prueba-PoC.
• La integración queda disponible en http://localhost:8000/hf.
• Las rutas internas de hyper-ferreteria se exponen como:
  • http://localhost:8000/hf/upload_async
  • http://localhost:8000/hf/segment_guided
  • http://localhost:8000/hf/analyze_scene
  • http://localhost:8000/hf/apply_texture
  • http://localhost:8000/hf/textures
  • http://localhost:8000/hf/image/{filename}
  • http://localhost:8000/hf/masks/{filename}
  • http://localhost:8000/hf/ai/{filename}
  • y otras rutas de hyper-ferreteria con el prefijo /hf

Docker

Se añadió soporte Docker al backend con un Dockerfile y .dockerignore.

• El contenedor expone el puerto 8000.
• El servicio arranca con uvicorn main:app --host 0.0.0.0 --port 8000.
• El requirements.txt del backend fue ampliado para incluir las dependencias de hyper-ferreteria.

Para construir y correr:

cd /d C:\Users\alane\OneDrive\Escritorio\Trabajo\Prueba-PoC\backend
docker build -t prueba-poc-backend .
docker run -p 8000:8000 prueba-poc-backend

Notas para nuevos desarrolladores

• El backend es el origen de verdad para la lógica de seguridad y sesiones.
• El frontend puede correr en modo dev para desarrollo rápido.
• En producción, el backend usa el build estático de React.
• Si un cambio en frontend/src no se refleja, revisa si estás usando 5173 (dev) o 8000 (backend+build).