Brun-E — Sesiones de voz (Fases A + B)

Tema: Brun-E — Sesiones de voz (Fases A + B)
Linear: NAC-76 · Idioma: ES

Resumen en pocas palabras

Brun-E es el asistente de voz dentro de la plataforma. El usuario puede iniciar una conversación por voz con Brun-E desde el navegador. Antes de permitir esa conversación, el sistema comprueba si el usuario tiene derecho (por ejemplo: créditos, límite de uso o tiempo de espera entre sesiones). Si todo está bien, el usuario recibe un permiso temporal para abrir la llamada; las claves internas nunca se muestran. Cuando la conversación termina, el sistema guarda lo que pasó y avisa a E-map para que haga su proceso. En una fase posterior (B), durante la conversación Brun-E podrá consultar la metodología, ver datos del usuario (curso, progreso, respuestas anteriores) y guardar las respuestas que el usuario vaya dando.

Objetivo de negocio

Que los usuarios de la plataforma puedan mantener conversaciones de voz con el asistente Brun-E de forma segura y controlada: el sistema valida si el usuario puede usar Brun-E antes de darle permiso, no expone claves internas, y al terminar la sesión guarda el resultado y avisa a E-map para que ejecute su lógica (fuera de este alcance).

Contexto y alcance

Qué sí está incluido (Fases A y B)

Fase A — Empezar una sesión: El usuario (ya logueado) pide iniciar una conversación con Brun-E. El sistema valida si tiene derecho (créditos, tokens, tiempo de espera u otro criterio a definir). Si es así, le da un permiso temporal y un identificador de sesión para que la app abra la llamada de voz. Las claves secretas del servicio de voz no salen del servidor.
Fase B — Durante la conversación: El sistema mantiene un canal de apoyo ligado a esa sesión. Ese canal permite: guardar respuestas del usuario, buscar en la metodología cuando Brun-E lo pida, dar a Brun-E datos del usuario (curso actual, progreso, respuestas anteriores) y registrar el cierre de sesión. Al terminar, se guarda lo hablado y se envía un aviso interno para E-map.
A definir con el cliente: Quién puede tener una sesión Brun-E (por rol, curso, organización, etc.) y el modelo de consumo (créditos, tokens, tiempo de espera, límite por periodo).
Pantalla y conexión de voz en el navegador: Qué ve y hace el usuario en la pantalla de Brun-E, qué pide la app al backend, qué recibe para abrir la llamada de voz y qué mensajes se muestran si algo falla. Detalle en la sección Pantalla y conexión de voz en el navegador.

Qué no está incluido en este documento

Historial de sesiones, detalle de una sesión pasada, recordatorios programados y ajustes técnicos de voz (otra fase).
La lógica interna de E-map (solo el aviso que la dispara).

Actores

Actor	Qué hace
Usuario	Ya está logueado en la plataforma. Pide iniciar una conversación con Brun-E y habla por voz durante la sesión. Quién exactamente puede tener sesión Brun-E se define con el cliente.
Sistema (backend)	Comprueba si el usuario puede usar Brun-E; genera el permiso temporal y el identificador de sesión; en Fase B mantiene el canal de apoyo (consultas a metodología, datos del usuario, guardado de respuestas), guarda la sesión y avisa a E-map al terminar.
Servicio de voz (externo)	Proporciona la conversación de voz; no es un actor de negocio (lo usa el sistema).

Casos de uso

CU-1 Iniciar una sesión con Brun-E

El usuario, ya logueado, pide empezar una conversación con Brun-E. El sistema comprueba primero si tiene derecho (créditos, tokens, tiempo de espera u otro modelo a acordar). Si sí tiene derecho, el sistema obtiene un permiso temporal del servicio de voz y genera un identificador de sesión; le devuelve a la app lo necesario para abrir la llamada de voz en el navegador. Las claves secretas del servicio de voz nunca se envían al usuario ni a la app.

CU-2 Canal de apoyo durante la conversación (Fase B)

El sistema mantiene un canal de apoyo asociado a esa sesión. Por ese canal: guarda las respuestas que el usuario va dando, busca en la metodología cuando Brun-E lo necesita, entrega a Brun-E datos del usuario (curso, progreso, respuestas anteriores) y registra cuando se pide cerrar la sesión. Todo eso permite que la conversación sea útil y quede registrada.

CU-3 Cerrar la sesión y avisar a E-map (Fase B)

Cuando la conversación termina (por cierre desde la app o por fin de sesión), el sistema guarda el resultado de la sesión y envía un aviso interno para que otro módulo ejecute la lógica de E-map. Qué hace E-map con ese aviso queda fuera de este alcance.

CU-4 Pantalla y conexión de voz en el navegador

El usuario entra a la pantalla de Brun-E (ya logueado). Ve una forma clara de empezar una conversación (por ejemplo un botón "Hablar con Brun-E"). Al pulsar:

La app pide al backend permiso para esa sesión (con la identificación del usuario que ya tiene).
Si el backend responde que sí, la app recibe un permiso temporal y un identificador de sesión. Con eso abre la llamada de voz en el navegador: el usuario puede hablar y escuchar a Brun-E. La pantalla debe mostrar que la llamada está activa (por ejemplo: "Conectado", "En conversación") y dar opción de cerrar cuando quiera.
Si el backend responde que no (sin derecho, sin créditos, en espera, etc.), la pantalla muestra un mensaje claro y no abre la llamada. El usuario no ve claves ni detalles técnicos.
Si el backend no está disponible o hay error, la pantalla muestra un mensaje de servicio no disponible (o similar), sin detalles internos.

La pantalla no muestra ni guarda claves secretas; solo usa el permiso temporal para conectar la llamada. Cuando el usuario pulsa "Cerrar", la pantalla debe avisar al backend (p. ej. POST complete en Fase B) para que la sesión se cierre de inmediato y no dependa solo del timeout por desconexión (R-2.5).

Reglas de negocio

R-1.1 Seguridad: claves internas no visibles

Las claves secretas del servicio de voz solo existen en el servidor. Al usuario y a la app solo se les da un permiso temporal con fecha de caducidad para conectar la llamada. Nadie fuera del servidor puede ver ni usar las claves internas.

R-1.2 Identificador de sesión

Cada sesión tiene un identificador único generado por el sistema. Sirve para relacionar la llamada de voz, el canal de apoyo y lo que se guarda en base de datos. No es el mismo identificador que usa el servicio de voz por dentro.

R-1.3 Comprobar derecho antes de dar permiso

Antes de dar permiso para una sesión Brun-E, el sistema debe comprobar que el usuario cumple las condiciones de negocio: tiene créditos o tokens, ha pasado el tiempo de espera entre sesiones, o el criterio que se acuerde con el cliente. El modelo concreto (créditos, tokens, tiempo de espera, límite por periodo) se define con el cliente.

R-1.4 Una sola sesión activa por usuario

Un usuario no puede iniciar una nueva sesión Brun-E si ya tiene una sesión activa. Debe cerrar la sesión actual antes de poder iniciar otra. El sistema rechaza el nuevo inicio y devuelve un mensaje claro (p. ej. "Ya tienes una sesión activa").

R-1.5 Orden de comprobaciones al iniciar

Al recibir una petición de iniciar sesión Brun-E, el sistema comprueba primero si el usuario ya tiene una sesión activa (R-1.4). Si la tiene, rechaza sin evaluar créditos ni tiempo de espera. Solo si no tiene sesión activa se comprueba el derecho a usar Brun-E (R-1.3: créditos, cooldown, elegibilidad). Así no se consume elegibilidad cuando el rechazo es solo por sesión ya activa.

R-2.1 Qué hace el canal de apoyo (Fase B)

Las acciones del canal de apoyo se ejecutan en el servidor: buscar en la metodología (usando el agente/formación ya preparada), devolver datos del usuario (curso actual, progreso, respuestas anteriores) y guardar las respuestas y el cierre de sesión. Todo de forma controlada y registrada.

R-2.2 Al cerrar la sesión: guardar y avisar a E-map

Al cerrar la sesión se guardan los resultados y se envía un aviso interno. Un módulo del sistema escucha ese aviso y ejecuta la lógica de E-map (qué hace E-map no forma parte de este alcance). El cierre puede ser iniciado por el usuario desde la pantalla (p. ej. POST complete), por el sistema/canal de apoyo (p. ej. end_session) o por caducidad del permiso temporal (expires_at): cuando el permiso caduca, la llamada se corta y el sistema considera la sesión cerrada, guarda y avisa a E-map igual que en los otros casos. Si se recibe POST complete (o equivalente) para una sesión ya cerrada, el backend responde correctamente pero no vuelve a enviar el aviso a E-map (evitar doble aviso).

R-2.3 Límite de duración (propuesta para el cliente)

Para controlar costes, se propone que cada sesión no supere un máximo de unos 5–10 minutos. El permiso temporal (expires_at) se configurará en consecuencia; al caducar, la sesión se cierra (R-2.2). Esta duración máxima es propuesta para validar con el cliente; superar el límite podría conllevar costes altos y por tanto la sesión debe cerrarse al expirar.

R-2.4 Quién puede tener una sesión Brun-E

Quién puede tener una sesión Brun-E (por rol, curso, organización, plan, etc.) se define con el cliente y se reflejará en las reglas y permisos del sistema.

R-2.5 Cierre por desconexión (sin “Cerrar” explícito)

Si el usuario cierra la pestaña o el navegador sin pulsar “Cerrar”, el sistema puede no recibir el aviso de cierre. Para no dejar sesiones “huérfanas” (activas pero sin llamada real), el sistema detecta la desconexión (p. ej. por caída del canal de apoyo, heartbeat o timeout) y, tras un plazo definido, considera la sesión cerrada: guarda lo que haya y avisa a E-map (R-2.2). Así el usuario no queda bloqueado por “ya tienes una sesión activa” cuando en la práctica la sesión ya no existe. El detalle técnico (timeout, heartbeat) se define en implementación.

R-3.1 La pantalla solo usa lo que el backend entrega

La pantalla pide al backend "iniciar sesión Brun-E" (con el usuario ya identificado). El backend entrega solo: permiso temporal para la llamada, fecha de caducidad de ese permiso e identificador de sesión. La pantalla usa eso para abrir la llamada de voz y, si aplica, para avisar el cierre. No recibe ni debe mostrar claves secretas.

R-3.2 Mensajes claros en pantalla

Si no puede iniciar la sesión (sin derecho, sin créditos, en espera, error del servicio), la pantalla muestra un mensaje entendible para el usuario (textos a definir en la implementación, en los idiomas de la plataforma).

R-3.3 Sin tiempo restante en pantalla

Durante la conversación la pantalla muestra solo el estado de conexión (p. ej. "Conectado", "En conversación") y la opción de cerrar. No se muestra tiempo restante ni countdown hasta expires_at.

R-3.4 Avisar al backend al pulsar "Cerrar"

Cuando el usuario pulsa "Cerrar" en la pantalla, la aplicación debe avisar al backend (POST complete en Fase B) para cerrar la sesión de inmediato. No se depende solo de la detección de desconexión (R-2.5).

Validaciones y mensajes al usuario

No está logueado: No se procesa la petición; debe iniciar sesión.
No tiene derecho a usar Brun-E ahora: No se le da permiso para la llamada; se le muestra un mensaje claro (por ejemplo: sin créditos, en tiempo de espera, o no elegible).
Ya tiene una sesión activa: No se le da permiso para iniciar otra; se le muestra un mensaje claro (p. ej. "Ya tienes una sesión activa"; debe cerrar la actual antes de iniciar otra).
Servicio de voz no disponible: Se muestra un mensaje de servicio no disponible, sin detalles técnicos internos.
Sesión inexistente o ya cerrada (al intentar cerrar o usar datos de esa sesión): Mensaje claro de error (no encontrada o ya finalizada).
Sesión terminada por caducidad del permiso (p. ej. límite de tiempo): Si la pantalla puede detectarlo, mostrar mensaje claro (p. ej. "La sesión ha terminado por tiempo"); el backend habrá cerrado la sesión y avisado a E-map (R-2.2).

Los textos exactos de los mensajes y su traducción (es, en, pt) se definen en la implementación.

Criterios de aceptación (cómo comprobar que está bien)

AC-1 Inicio con comprobación de derecho

Si el usuario sí tiene derecho a usar Brun-E, al pedir iniciar sesión recibe permiso para la llamada y puede conectar la conversación de voz. Si no tiene derecho, recibe un mensaje claro y no se le da permiso (no puede conectar).

AC-2 La app nunca ve claves secretas

La aplicación solo recibe el permiso temporal y lo necesario para abrir la llamada. En ningún momento recibe ni muestra las claves secretas del servicio de voz.

AC-3 El canal de apoyo hace las cuatro acciones (Fase B)

El sistema ejecuta correctamente: guardar respuestas, buscar en metodología, dar datos del usuario a Brun-E y registrar el cierre de sesión. Cada una devuelve lo esperado para que la conversación siga bien.

AC-4 Al cerrar: se guarda y se avisa a E-map (Fase B)

Cuando la sesión termina, se guardan los resultados y se envía el aviso interno que dispara E-map. No hace falta implementar la lógica de E-map en este alcance; solo el aviso.

AC-5 Datos del usuario que recibe Brun-E (Fase B)

Cuando Brun-E pide datos del usuario, el sistema devuelve: identificación del usuario y organización, curso actual, progreso en la metodología y respuestas anteriores relevantes (si existen).

AC-6 Pantalla: pedir permiso y abrir la llamada

Desde la pantalla de Brun-E, el usuario puede pulsar para iniciar. La app pide al backend; si recibe permiso, abre la llamada de voz y el usuario puede hablar y escuchar. Si no recibe permiso, no abre la llamada.

AC-7 Pantalla: mensajes cuando algo falla

Si el backend indica que no puede dar permiso (sin derecho, sin créditos, en espera), la pantalla muestra un mensaje claro y no abre la llamada. Si hay error de servicio, muestra un mensaje de servicio no disponible (o equivalente). En ningún caso se muestran claves ni detalles técnicos internos.

AC-8 Pantalla: estado de la conversación y cierre

Durante la conversación, el usuario ve que está conectado (o en conversación) y tiene forma de cerrar la sesión cuando quiera. Al pulsar "Cerrar", la pantalla avisa al backend (POST complete en Fase B) para que la sesión se cierre de inmediato y se guarde y dispare E-map.

Trazabilidad

(Para el equipo: relación entre casos de uso, reglas y criterios de aceptación.)

ID	Tipo	Descripción breve	Dónde / Referencia	Criterio de prueba
CU-1	Caso de uso	Iniciar sesión Brun-E con validación de derecho	Inicio de sesión	AC-1, AC-2
CU-2	Caso de uso	Canal de apoyo: guardar respuestas, metodología, datos usuario, cierre	Durante la conversación	AC-3, AC-5
CU-3	Caso de uso	Cerrar sesión; guardar y avisar E-map	Cierre de sesión	AC-4
R-1.1	Regla	Claves internas no visibles; solo permiso temporal	Sistema	Solo permiso temporal al cliente
R-1.2	Regla	Identificador único de sesión interno	Sistema	Relación sesión / datos guardados
R-1.3	Regla	Comprobar derecho antes de dar permiso	Inicio de sesión	Rechazo si no cumple
R-1.4	Regla	Una sola sesión activa por usuario; rechazar nuevo inicio si ya tiene activa	Inicio de sesión	Mensaje "sesión activa"
R-1.5	Regla	Orden: primero sesión activa, luego derecho; no consumir elegibilidad si ya tiene sesión	Inicio de sesión	Rechazo sin gastar crédito/cooldown
R-2.1	Regla	Canal de apoyo: metodología, datos usuario, guardar	Durante la conversación	AC-3, AC-5
R-2.2	Regla	Guardar y avisar E-map al cerrar (incl. caducidad permiso)	Cierre de sesión	AC-4
R-2.3	Regla	Límite duración 5–10 min (propuesta cliente); caducidad cierra sesión	Negocio / técnico	Validar con cliente
R-2.4	Regla	Quién puede tener sesión: a definir con cliente	Negocio	Definición con cliente
R-2.5	Regla	Cierre por desconexión (timeout/heartbeat); guardar y avisar E-map; no sesiones huérfanas	Cierre / técnico	Sesión se cierra tras plazo
AC-1	Aceptación	Inicio con validación; mensaje claro si no puede	Inicio de sesión	Prueba flujo OK y rechazo
AC-2	Aceptación	App sin claves secretas	Respuesta al iniciar	Sin claves en cliente
AC-3	Aceptación	Cuatro acciones del canal de apoyo	Canal de apoyo	Pruebas por acción
AC-4	Aceptación	Guardar + aviso E-map al cerrar	Cierre	Comprobar aviso emitido
AC-5	Aceptación	Datos usuario completos para Brun-E	Datos usuario	Comprobar contenido
CU-4	Caso de uso	Pantalla: pedir permiso, abrir llamada, mensajes de error, cierre	Pantalla Brun-E	AC-6, AC-7, AC-8
R-3.1	Regla	Pantalla solo usa permiso temporal e identificador; sin claves	Pantalla	Sin claves en front
R-3.2	Regla	Mensajes claros en pantalla si falla	Pantalla	Textos definidos
R-3.3	Regla	Sin tiempo restante ni countdown; solo estado y Cerrar	Pantalla	Sin countdown
R-3.4	Regla	Al pulsar Cerrar, pantalla debe avisar al backend (POST complete)	Pantalla	Cierre inmediato
AC-6	Aceptación	Pantalla pide permiso y abre llamada si OK	Pantalla	Flujo inicio OK
AC-7	Aceptación	Pantalla muestra mensajes claros si no puede / error	Pantalla	Mensajes sin detalles técnicos
AC-8	Aceptación	Pantalla muestra conectado y opción de cerrar	Pantalla	Estado y cierre

Supuestos y riesgos

Supuesto: La plataforma ya tiene registro, login e identificación de usuario (con datos de usuario y organización). Brun-E es una funcionalidad dentro de esa plataforma.
Supuesto: El modelo de consumo (créditos, tokens, tiempo de espera) y quién puede tener sesión Brun-E se cerrarán con el cliente antes o durante la implementación.
Riesgo: Cambios o indisponibilidad del servicio de voz externo. Mitigación: el equipo técnico aísla esa dependencia para poder adaptarse o cambiar de proveedor si hiciera falta.

Preguntas abiertas (para cerrar con el cliente)

Modelo de consumo: ¿Créditos, tokens, tiempo de espera entre sesiones, límite por periodo, o combinación? ¿Dónde se guarda (por usuario, por organización, por plan)?
Quién puede tener una sesión Brun-E: Criterios exactos (rol, curso, organización, plan, etc.).
Duración máxima de cada sesión: Propuesta: 5–10 minutos máximo por sesión para controlar costes; al caducar el permiso la sesión se cierra y se avisa a E-map. Confirmar con el cliente y fijar el valor (expires_at) en consecuencia.
(Para el equipo técnico:) Cómo se aloja el canal de apoyo (detalle de infraestructura).

Correcciones / historial de validación

Fecha	Versión	Cambio
(pendiente)	v1	Borrador inicial Fases A+B.
(pendiente)	v1.1	Reescrito en lenguaje no técnico para que persona no técnica pueda entender el DRF.
(pendiente)	v1.2	Añadida pantalla y conexión de voz en el navegador: CU-4, R-3.1, R-3.2, AC-6, AC-7, AC-8.
(pendiente)	v1.3	Movido a docs/drf/ como 12-brun-e-sesiones-voz.md; referenciado en 00-overview y README.