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:

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

En PowerShell:

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

### Instalar dependencias

```cmd
pip install -r requirements.txt
```

### Ejecutar servidor

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

O usar el helper:

```cmd
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:

```cmd
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:

```cmd
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:

```cmd
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).