# Guía E2E — Flujo de generación de tokens entre broadcast-panel y backend-api

Objetivo
---------
Esta guía explica paso a paso cómo preparar el entorno y probar la generación/validación de tokens que el `backend-api` crea para que `broadcast-panel` (y su `studioportal`) inicien sesiones de LiveKit.

Resumen rápido
--------------
- Preparar la base de datos (Postgres) y Prisma.
- Levantar `backend-api` (con `prisma generate` aplicado). 
- Levantar `broadcast-panel` (Vite). 
- Opcional: levantar Playwright server local o usar browserless remoto para E2E.
- Ejecutar pruebas manuales (curl + UI) y automatizadas (plugin Playwright ya incluido: `packages/broadcast-panel/e2e/dify-plugin-playwright.mjs`).

Checklist mínimo
-----------------
- [ ] Postgres accesible (connection string correcta)
- [ ] `prisma generate` ejecutado y migraciones aplicadas
- [ ] `backend-api` corriendo
- [ ] `broadcast-panel` corriendo en `http://localhost:5176` (o puerto elegido)
- [ ] Playwright server corriendo (opcional: `npx playwright run-server --port 3003`)
- [ ] `npx playwright install chromium` ejecutado si se usa fallback local
- [ ] Plugin E2E probado: `node packages/broadcast-panel/e2e/dify-plugin-playwright.mjs` 

Entorno y variables clave
-------------------------
- DATABASE_URL (Postgres):
  - Ejemplo: `postgres://postgres:72ff3d8d80c352f89d99@192.168.1.20:5433/avanzacast?sslmode=disable`
- LIVEKIT_API_KEY / LIVEKIT_API_SECRET (para generación de tokens en backend)
- X-BACKEND-SECRET (si el backend requiere un header secreto entre servicios)

1) Preparar la base de datos y Prisma
-----------------------------------
1. Asegúrate que la DB está accesible desde la máquina donde ejecutas las pruebas.
2. En `packages/backend-api` ejecuta:

```bash
cd packages/backend-api
# Generar prisma client
npx prisma generate
# Aplicar migraciones dev o deploy según tu flujo
npx prisma migrate deploy
# o en desarrollo
npx prisma db push
```

3. Verifica tablas (ejemplo con psql):

```bash
PGPASSWORD='72ff3d8d80c352f89d99' psql -h 192.168.1.20 -p 5433 -U postgres -d avanzacast -c '\dt'
```

2) Configurar y arrancar backend-api
------------------------------------
1. Añade las variables de entorno necesarias (LIVEKIT_API_KEY / LIVEKIT_API_SECRET y DATABASE_URL). Puedes usar `.env` o exportarlas:

```bash
export DATABASE_URL='postgres://postgres:...'
export LIVEKIT_API_KEY='devkey'
export LIVEKIT_API_SECRET='secret'
export X_BACKEND_SECRET='secreto-interno'
```

2. Lanza el backend:

```bash
cd packages/backend-api
npm install
npm run dev        # o la forma que uses para arrancar en dev
# Si dockerizas: docker-compose up --build
```

3. Comprueba salud:

```bash
curl -sS http://localhost:4000/health
# o
curl -sS http://localhost:4000 | jq .'  # según endpoint
```

3) Arrancar broadcast-panel (frontend)
--------------------------------------
1. En otra terminal:

```bash
cd packages/broadcast-panel
npm install
# Forzar puerto 5176 (ejemplo)
PORT=5176 npm run dev -- --port 5176
# o: npx vite --port 5176 --host 127.0.0.1
```

2. Abre `http://localhost:5176` y prueba el flujo manual (crear transmisión → omitir modal → Empezar ahora → Entrar al Estudio).

4) Probar flujo manual con curl (backend)
----------------------------------------
- Crear sesión (ejemplo):

```bash
curl -X POST 'http://localhost:4000/api/session' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Transmision e2e","ownerId":"user-casa"}' | jq
```

Respuesta esperada: JSON con `{ id, studioUrl, redirectUrl, ttlSeconds }`.

- Generar token (si el backend ofrece endpoint explícito):

```bash
curl -X POST 'http://localhost:4000/api/session/<id>/token' -H 'Content-Type: application/json' -d '{}' | jq
```

Respuesta esperada: `{ token: "ey...", ttlSeconds: 300 }`.

5) Probar la conexión token → LiveKit (manual)
----------------------------------------------
- En `studioportal` (la página que abre broadcast-panel), inspecciona consola de JS y network para ver que se obtiene el token y que `livekit-client` intenta conectar.
- Si la consola muestra errores relacionados con token inválido, revisa las credenciales LIVEKIT_API_* en el backend.

6) E2E automatizado con Playwright (plugin incluido)
----------------------------------------------------
He añadido un plugin CLI en `packages/broadcast-panel/e2e/dify-plugin-playwright.mjs` que realiza el flujo básico (con fallback local cuando falla la conexión al Playwright server remoto).

Pasos para usarlo (recomendado):

1. Instalar navegadores Playwright (si no lo hiciste):

```bash
# helper que creé
./scripts/install-playwright-deps.sh
# o manualmente
cd packages/broadcast-panel
npm install
npx playwright install chromium
```

2. Levantar Playwright server (opcional) — útil para ejecutar E2E desde controlador externo:

```bash
npx playwright run-server --port 3003 --host 0.0.0.0
```

3. Ejecutar el plugin CLI (desde la raíz del repo):

```bash
node packages/broadcast-panel/e2e/dify-plugin-playwright.mjs --ws ws://localhost:3003 --url http://localhost:5176 --out /tmp/dify-shot.png
```

- Si `--ws` falla o no es compatible por versión, el plugin hace fallback e intenta lanzar Chromium local.
- Salida: JSON impreso en stdout con estructura { success, used: 'remote'|'local-launch', steps, out, error }.
- Captura: `/tmp/dify-shot.png`.

Ejemplo de uso con npm script (ya añadido):

```bash
cd packages/broadcast-panel
npm run e2e:dify
# esto ejecuta el plugin con las opciones por defecto definidas en package.json
```

7) E2E con Puppeteer + Browserless (alternativa)
------------------------------------------------
- Si usas browserless remote, en `packages/broadcast-panel/e2e` hay scripts: `browserless_connect.mjs`, `puppeteer_browserless_e2e.js`.
- Para probar ws directo y debug, existe `e2e/ws_connect.mjs`.

Ejemplo flujo rápido con browserless:

```bash
# comprobar WSS
node packages/broadcast-panel/e2e/ws_connect.mjs
# ejecutar script que usa browserless
BROWSERLESS_WS='ws://browserless.bfzqqk.easypanel.host?token=TOKEN' node packages/broadcast-panel/e2e/browserless_connect.mjs
```

8) Comprobaciones y logs a recopilar en fallos
---------------------------------------------
Cuando algo falle, pega estos outputs (útiles para diagnóstico):

- Output del plugin Playwright (/tmp/dify-plugin-output.log o stdout)
- `ls -la /tmp/dify-shot.png` (si existe)
- Vite dev log (ej. `/tmp/broadcast_dev_5176.log` o `packages/broadcast-panel/vite-dev.log`)
- Backend logs (stdout / docker logs)
- Resultado de `npx prisma generate` o errores de Prisma
- Postgres connectivity test:

```bash
PGPASSWORD='72ff3d8d80c352f89d99' psql -h 192.168.1.20 -p 5433 -U postgres -d avanzacast -c "select id, token, createdat from \"Session\" order by createdat desc limit 10;"
```

- Playwright server log (cuando ejecutas `npx playwright run-server` aparece en la terminal)

9) Errores comunes y soluciones rápidas
--------------------------------------
- Playwright version mismatch: sincroniza versión del cliente (en `packages/broadcast-panel`) con la del server que usas, o usa fallback local. Ej:

```bash
cd packages/broadcast-panel
npm install playwright@1.51.0
npx playwright install chromium
```

- "BEWARE: your OS is not officially supported... fallback ubuntu20.04-x64": es un aviso normal en distros no listadas; ejecutar `npx playwright install chromium` y/o `./scripts/install-playwright-deps.sh` para instalar dependencias de sistema.

- `@prisma/client did not initialize yet`: ejecutar `npx prisma generate` antes de arrancar backend.

- `ERR_CONNECTION_REFUSED` navegando a `http://localhost:5176/`: arranca el dev server (Vite) en ese puerto.

10) Pruebas adicionales automáticas (sugerencia)
------------------------------------------------
- Crear un script orquestador `scripts/e2e-run.sh` que:
  - levante Postgres (container) si no existe,
  - aplique migraciones,
  - arranque backend-api en background,
  - arranque broadcast-panel en background,
  - arranque Playwright run-server,
  - ejecute `node e2e/dify-plugin-playwright.mjs`, y
  - recopile artefactos (`/tmp/*.png`, logs) como outputs.

Puedo crear este script si quieres que lo automatice.

11) Próximos pasos recomendados
-------------------------------
- Implementar `GET /api/session/:id/token` en `backend-api` si quieres flujo REST claro (session created -> separate token retrieval).
- Implementar tests unitarios para el generador del token (mock LiveKit) y un E2E que valide token TTL y reconexión.
- Añadir un `e2e:all` que levante servicios y ejecute el plugin y guarde artefactos (ideal para CI).

Soporte inmediato
------------------
Si pegas aquí la salida JSON del plugin (`node packages/broadcast-panel/e2e/dify-plugin-playwright.mjs ...`) o el log `/tmp/dify-plugin-output.log`, lo analizo y aplico correcciones inmediatas (selectores, timeouts, version mismatch, dependencia faltante) y vuelvo a ejecutar el flujo contigo.

---

Si quieres, creo ahora mismo el script `scripts/e2e-run.sh` que orquesta todo (opción recomendada). ¿Lo genero?