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

Tema: Brun-E — Sesiones de voz (Fases A + B)
Linear: NAC-76 · Idioma: ES · Versión: v1.5 · Fecha: 2026-07-02

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, junto con los parámetros de audio en tiempo real (detección de turnos / VAD, reducción de ruido, modelo de transcripción) y los datos del canal de apoyo para conectar; las claves internas nunca se muestran. La sesión captura el idioma del usuario (es/en/pt) al iniciar. Durante la conversación, Brun-E puede consultar la base de conocimiento de la metodología para dar respuestas más útiles y fundamentadas. Cuando la conversación termina — el cierre lo dispara la app al completar la sesión —, el sistema genera un reporte estructurado con el análisis de lo conversado (en el idioma de la sesión), lo guarda y con esa información genera el E-map del usuario automáticamente.

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, entrega los parámetros de audio y del canal de apoyo necesarios para conectar, y al terminar la sesión guarda el resultado y genera el E-map del usuario a partir del análisis de la conversación (en el idioma de la sesión).

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, un identificador de sesión, los parámetros de audio en tiempo real (detección de turnos / VAD con duración de silencio configurable, reducción de ruido, modelo de transcripción) y los datos del canal de apoyo (dirección y protocolo) para que la app abra la llamada de voz. La sesión captura además el idioma del usuario (es/en/pt). 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. Por ese canal Brun-E puede consultar la base de conocimiento de la metodología. Al terminar, el cierre lo dispara la app (acción de "completar sesión"); el sistema genera el reporte estructurado con el análisis de la conversación si no se lo pasan ya formado, guarda lo hablado y el reporte, y genera el E-map del usuario.
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 administración y configuración de la base de conocimiento de metodología (DRF separado).

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, el identificador de sesión, los parámetros de audio y los datos del canal de apoyo; captura el idioma de la sesión; en Fase B mantiene el canal de apoyo (consultas a metodología); al recibir la orden de completar la sesión genera el reporte si hace falta, lo guarda y genera el E-map.
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, genera un identificador de sesión y captura el idioma del usuario (es/en/pt); le devuelve a la app todo lo necesario para abrir la llamada de voz en el navegador: el permiso temporal, la fecha de caducidad, el identificador de sesión, los parámetros de audio en tiempo real (detección de turnos / VAD con duración de silencio configurable vía ajuste global, perfil de reducción de ruido y modelo de transcripción) y los datos del canal de apoyo (dirección y protocolo). 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 Brun-E puede consultar la base de conocimiento de la metodología para dar respuestas fundamentadas. Esta acción se ejecuta en el servidor de forma controlada y registrada. Otras herramientas del canal (obtener el perfil del usuario y el reporte de la última sesión) están previstas pero temporalmente inactivas pendientes de rediseño; hoy sólo opera la de metodología. El cierre de la sesión no lo dispara Brun-E por el canal: lo dispara la app con una acción de "completar sesión" (ver CU-3).

CU-3 Cerrar la sesión y generar el E-map (Fase B)

Cuando la conversación termina, el cierre lo dispara la app con una acción de "completar sesión" (o, si no se pulsó cerrar, por caducidad del permiso o por desconexión — ver R-2.2 y R-2.5). Junto con esa orden, la app puede enviar el transcript de lo conversado y, opcionalmente, un reporte ya formado. Si no llega un reporte formado pero sí hay transcript, el sistema genera el reporte a partir del transcript, en el idioma de la sesión. El sistema guarda el reporte junto con la sesión y, a partir de sus datos, genera el E-map del usuario: un perfil con scores en las dimensiones afectiva, efectiva y de perspectiva, junto con etiquetas, insights, alertas y recomendaciones. El E-map queda disponible de inmediato para el usuario en la plataforma.

Si no se puede formar un reporte, la sesión se cierra igual — sin reporte ni E-map —, registrando el motivo de la omisión (ver El reporte final).

CU-5 Reanudar una sesión activa (Fase B)

Si la conversación se interrumpe por una recarga de página o una caída de red mientras la sesión sigue activa, el usuario puede reconectar a esa misma sesión sin crear una nueva. El sistema busca la sesión activa del usuario, obtiene un nuevo permiso temporal y devuelve los mismos datos de conexión (permiso, parámetros de audio y canal de apoyo) para reanudar la llamada. No se consume una nueva sesión ni se altera el identificador. Si el usuario no tiene ninguna sesión activa, el sistema responde con un error claro (sesión no encontrada).

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, la pantalla muestra un mensaje claro acorde al motivo (sesión ya activa, en tiempo de espera / cooldown, máximo diario alcanzado, o motivo estructural — ver R-3.2) 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).

Herramientas del canal de apoyo

Durante la conversación, Brun-E dispone de herramientas que puede activar para obtener información. Estas herramientas se ejecutan en el servidor — el usuario no las ve ni las activa directamente. Hoy sólo está activa la de consultar metodología. Las demás están implementadas pero temporalmente inactivas pendientes de rediseño (ver más abajo). El cierre de la sesión ya no es una herramienta del canal: lo dispara la app (ver CU-3).

Herramienta 1 — Consultar metodología (lookup_methodology) — ACTIVA

Qué hace: Permite a Brun-E buscar en la base de conocimiento de la metodología para fundamentar sus respuestas durante la conversación.

Qué necesita para activarse: - El tipo de contenido que necesita (por ejemplo: contenido base de la metodología, o contenido específico para el e-mode del usuario) - Opcionalmente, un texto de búsqueda para filtrar por tema concreto - Opcionalmente, cuántos resultados quiere recibir (máximo 10)

Qué recibe como respuesta: - Una lista de entradas de la base de conocimiento con título, resumen y contenido relevante

Cuándo la usa Brun-E: Al inicio de cada sesión hace dos consultas automáticas: una para cargar el contenido base de la metodología, y otra para cargar el contenido específico del e-mode del usuario. Puede hacer consultas adicionales durante la conversación si necesita información puntual.

Herramientas previstas / temporalmente inactivas

Las siguientes herramientas están implementadas pero desactivadas pendientes de rediseño. Brun-E no puede usarlas hoy; se documentan aquí para dejar constancia de lo previsto.

Obtener datos del usuario (get_user_context) — INACTIVA. Permitiría a Brun-E conocer el perfil del usuario (nombre, nivel, e-mode y resultado de la entrevista existencial si existe) para personalizar la conversación.

Obtener el reporte de la última sesión (get_last_session_report) — INACTIVA. Permitiría a Brun-E recuperar el reporte de la sesión anterior del usuario para dar continuidad entre sesiones.

Mientras estas herramientas sigan inactivas, el canal de apoyo sólo responde a la consulta de metodología; cualquier otra herramienta no está disponible.

El reporte final

Al cerrar una sesión, el sistema guarda un reporte estructurado con el análisis de la conversación. Este reporte es la base para generar el E-map del usuario. El reporte puede llegar ya formado desde la app o generarlo el sistema a partir del transcript (en el idioma de la sesión) cuando no se lo pasan.

Campo	Descripción
Título	Un título corto que resume la sesión (máximo 200 caracteres)
Resumen	Un texto en lenguaje claro que resume lo conversado (máximo 1000 caracteres)
Proyección E-map	El análisis de Brun-E sobre las tres dimensiones existenciales del usuario. Para cada dimensión: un score de 0 a 10, una etiqueta descriptiva y un insight. Ver tabla abajo.
Análisis extendido	Un texto más largo con el análisis completo de Brun-E (máximo 4000 caracteres)
Insights	Lista de observaciones relevantes sobre el usuario
Recomendaciones	Lista de recomendaciones concretas para el usuario
Alertas	Lista de aspectos que requieren atención especial
Nivel de confianza	Qué tan seguro está Brun-E de su análisis (valor de 0 a 1, donde 1 es máxima confianza)

Proyección E-map — las tres dimensiones

Dimensión	Qué mide
Afectiva	El plano emocional del usuario: cómo procesa y expresa sus emociones
Efectiva	El plano de la acción: cómo el usuario actúa y logra sus objetivos
Perspectiva	El plano del pensamiento: cómo el usuario interpreta y da sentido a su experiencia

Cada dimensión recibe: - Score: número de 0 a 10 (internamente se maneja de 0 a 1, pero se muestra al usuario como 0 a 10) - Etiqueta: una palabra o frase corta que describe el estado en esa dimensión (la define Brun-E en base a la conversación) - Insight: una observación puntual sobre esa dimensión

Cuándo no hay reporte (motivos de omisión)

Si no se puede formar un reporte válido, la sesión se cierra igual, sin reporte ni E-map, y el sistema registra el motivo de la omisión:

Motivo	Cuándo ocurre
Sin transcript	La sesión se cierra sin nada conversado registrado; no hay base para generar reporte.
Falló la generación	Hay transcript, pero el intento de generar el reporte no produjo un resultado válido (p. ej. error del servicio de análisis).
Faltan valores dictados	El análisis se ejecutó pero no arrojó los valores mínimos necesarios para el reporte.

En todos estos casos la sesión queda cerrada correctamente; simplemente no genera E-map para esa sesión.

Flujo completo: sesión → reporte → E-map

El siguiente diagrama muestra el ciclo de vida completo de una sesión Brun-E, desde que el usuario inicia hasta que el E-map queda disponible.

sequenceDiagram
    actor Usuario
    participant App as Pantalla (App)
    participant Backend as Sistema (Backend)
    participant BrunE as Brun-E (IA de voz)

    Usuario->>App: Pulsa "Hablar con Brun-E"
    App->>Backend: Solicita iniciar sesión
    Backend->>Backend: Valida elegibilidad del usuario
    alt Usuario tiene derecho
        Backend-->>App: Permiso temporal + ID sesión + audio (VAD) + canal de apoyo
        App->>BrunE: Abre llamada de voz con el permiso temporal
        App-->>Usuario: Muestra "Conectado"

        note over BrunE,Backend: Al inicio y durante la conversación
        BrunE->>Backend: lookup_methodology (contenido base)
        Backend-->>BrunE: Entradas de metodología base
        BrunE->>Backend: lookup_methodology (contenido del e-mode del usuario)
        Backend-->>BrunE: Entradas de metodología para ese e-mode

        note over Usuario,BrunE: Conversación en curso
        Usuario->>BrunE: Habla con Brun-E
        BrunE-->>Usuario: Responde usando la metodología

        note over App,Backend: Al finalizar la conversación
        App->>Backend: Completar sesión (transcript, idioma; reporte opcional)
        Backend->>Backend: Si no llega reporte pero hay transcript, lo genera
        Backend->>Backend: Guarda sesión como completada
        Backend->>Backend: Genera E-map (o registra motivo si no hay reporte)
        Backend-->>App: Sesión cerrada + reporte final
        App-->>Usuario: Muestra resumen y E-map actualizado

    else Usuario sin derecho / error
        Backend-->>App: Motivo de rechazo (sesión activa, cooldown, máx. diario, estructural)
        App-->>Usuario: Mensaje claro acorde al motivo
    end

Descripción paso a paso

El usuario pulsa para iniciar — La app pide permiso al backend.
El sistema valida — Comprueba primero sesión activa y luego elegibilidad (cooldown, máximo diario, motivo estructural). Si no puede, responde con el motivo y un mensaje claro acorde.
Se abre la llamada — El usuario recibe el permiso temporal, los parámetros de audio (VAD) y los datos del canal de apoyo; la app abre la conversación de voz. El sistema captura el idioma de la sesión.
Brun-E se prepara — Al inicio, Brun-E hace automáticamente dos consultas a la base de conocimiento (contenido base + contenido del e-mode del usuario).
Conversación en curso — El usuario habla con Brun-E. Brun-E puede hacer consultas adicionales a la metodología en cualquier momento.
Cierre desde la app — Cuando la conversación termina, la app envía la orden de completar la sesión con el transcript (y opcionalmente un reporte ya formado).
Sistema guarda y genera E-map — Si no llega reporte pero hay transcript, el backend lo genera en el idioma de la sesión; guarda la sesión como completada y genera el E-map con los scores, etiquetas, insights, alertas y recomendaciones. Si no se puede formar reporte, cierra igual y registra el motivo (sin transcript / falló generación / faltan valores dictados).
E-map disponible — El usuario puede ver su E-map actualizado en la plataforma.

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, junto con los parámetros de audio en tiempo real (detección de turnos / VAD con duración de silencio, reducción de ruido, modelo de transcripción) y los datos del canal de apoyo (dirección y protocolo). 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-1.6 Parámetros de audio y canal de apoyo al iniciar

Al dar permiso para la sesión, el sistema entrega a la app los parámetros de audio en tiempo real que la llamada debe aplicar: la configuración de detección de turnos / VAD (con la duración de silencio tomada de un ajuste global configurable), el perfil de reducción de ruido y el modelo de transcripción. Entrega también los datos del canal de apoyo (dirección y protocolo) para que la app se conecte. Estos parámetros son la fuente de verdad que la app usa para configurar la sesión de voz.

R-1.7 Idioma de la sesión

Al iniciar, el sistema captura el idioma del usuario (es, en o pt). Ese idioma queda asociado a la sesión y es el que se usa para generar el reporte final. Si el idioma no puede resolverse, se usa español (es) por defecto.

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

Hoy el canal de apoyo ejecuta en el servidor, de forma controlada y registrada, una sola herramienta: consultar la base de conocimiento de la metodología. Otras herramientas (obtener el perfil del usuario, obtener el reporte de la última sesión) están implementadas pero temporalmente inactivas pendientes de rediseño. El cierre de la sesión no pasa por el canal: lo dispara la app (ver R-2.2).

R-2.2 Al cerrar la sesión: guardar reporte y generar E-map

El cierre lo dispara la app con una acción de "completar sesión", enviando el transcript de lo conversado y, opcionalmente, un reporte ya formado. Si no llega un reporte formado pero hay transcript, el sistema genera el reporte a partir del transcript, en el idioma de la sesión (R-1.7). Con el reporte, el sistema guarda la sesión y genera el E-map del usuario: scores en las tres dimensiones (afectiva, efectiva, perspectiva), etiquetas, insights, alertas y recomendaciones.

Si no se puede formar reporte, la sesión se cierra y guarda de todas formas, sin reporte ni E-map, registrando el motivo de la omisión (sin transcript, falló la generación o faltan valores dictados — ver El reporte final).

El cierre también puede ocurrir por caducidad del permiso temporal (expires_at) o por desconexión (R-2.5): en ambos casos el sistema considera la sesión cerrada y aplica la misma lógica de reporte/E-map. Si se recibe una petición de cierre para una sesión ya cerrada, el backend responde correctamente pero no vuelve a generar el E-map (evitar duplicados).

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 genera el E-map si hay reporte válido (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-2.6 Reanudar una sesión activa

Si una sesión sigue activa (no se cerró) y la app se recarga o pierde la conexión, el usuario puede reconectar a esa misma sesión sin crear una nueva. El sistema busca la sesión activa del usuario, emite un nuevo permiso temporal y devuelve los mismos datos de conexión (permiso, audio, canal de apoyo). No se consume una nueva sesión ni cambia el identificador. Si el usuario no tiene sesión activa, se responde con error claro (sesión no encontrada).

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, identificador de sesión, los parámetros de audio en tiempo real (VAD, reducción de ruido, transcripción) y los datos del canal de apoyo (dirección y protocolo). 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 según el motivo

Si no puede iniciar la sesión, el sistema distingue el motivo y la pantalla muestra un mensaje acorde (textos a definir en la implementación, en los idiomas de la plataforma):

Motivo	Qué indica
Sesión ya activa	El usuario ya tiene una sesión Brun-E abierta; debe cerrarla antes de iniciar otra.
Tiempo de espera (cooldown)	Aún no pasó el tiempo mínimo entre sesiones; se puede indicar cuánto falta.
Máximo diario alcanzado	El usuario llegó al límite de sesiones permitidas en el periodo.
Motivo estructural	El usuario no es elegible por configuración/reglas (no cumple las condiciones para usar Brun-E).

Si el servicio de voz no está disponible, se muestra un mensaje de servicio no disponible, sin detalles técnicos.

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.
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).
En tiempo de espera (cooldown): No se le da permiso todavía; mensaje claro indicando que debe esperar (puede señalar cuánto falta).
Máximo diario alcanzado: No se le da permiso; mensaje claro de que llegó al límite del periodo.
No elegible (motivo estructural): No se le da permiso; mensaje claro de que no cumple las condiciones para usar Brun-E.
Servicio de voz no disponible: Se muestra un mensaje de servicio no disponible, sin detalles técnicos internos.
Reanudar sin sesión activa: Si se pide reconectar y el usuario no tiene sesión activa, se responde con error claro (sesión no encontrada).
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 generado el E-map si había reporte válido (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 ejecuta la herramienta de metodología (Fase B)

El sistema responde correctamente a la consulta de metodología: devuelve entradas de la base de conocimiento (base o del e-mode del usuario) para que la conversación siga bien. Las herramientas inactivas (perfil del usuario, reporte de la última sesión) no están disponibles y no se ejecutan.

AC-4 Al cerrar: se guarda el reporte y se genera el E-map (Fase B)

Cuando la app completa la sesión con transcript, el sistema obtiene un reporte válido — el que llega ya formado o el que genera a partir del transcript en el idioma de la sesión —, guarda el reporte junto con la sesión y genera el E-map del usuario con scores en las tres dimensiones, etiquetas, insights, alertas y recomendaciones. El E-map queda disponible en la plataforma. Si no se puede formar reporte, la sesión se cierra igual sin E-map y se registra el motivo (sin transcript / falló generación / faltan valores dictados).

AC-5 Reanudar una sesión activa (Fase B)

Si el usuario tiene una sesión activa y la app pide reconectar, el sistema devuelve los datos de conexión de esa misma sesión (permiso temporal, audio, canal de apoyo) sin crear una nueva ni cambiar el identificador. Si no hay sesión activa, responde con error claro (sesión no encontrada).

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, se guarde el reporte y se genere el 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: consultar metodología (única herramienta activa)	Durante la conversación	AC-3
CU-3	Caso de uso	Cerrar sesión desde la app; generar reporte si falta y generar E-map	Cierre de sesión	AC-4
CU-5	Caso de uso	Reanudar una sesión activa tras recarga o caída de red	Durante la conversación	AC-5
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-1.6	Regla	Entregar parámetros de audio (VAD) y datos del canal de apoyo al iniciar	Inicio de sesión	Audio + canal en respuesta
R-1.7	Regla	Capturar idioma (es/en/pt); reporte en ese idioma	Inicio / cierre	Idioma del reporte
R-2.1	Regla	Canal de apoyo: sólo metodología activa; resto inactivas	Durante la conversación	AC-3
R-2.2	Regla	App cierra; generar reporte si falta y E-map; motivos de omisión	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 generar E-map; no sesiones huérfanas	Cierre / técnico	Sesión se cierra tras plazo
R-2.6	Regla	Reanudar sesión activa sin crear una nueva	Durante la conversación	AC-5
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 usa permiso temporal, audio y canal de apoyo; sin claves	Pantalla	Sin claves en front
R-3.2	Regla	Mensajes claros según motivo (sesión activa, cooldown, máx. diario, estructural)	Pantalla	Mensaje por motivo
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-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	Herramienta de metodología funciona; inactivas no disponibles	Canal de apoyo	Prueba metodología
AC-4	Aceptación	Generar reporte si falta + E-map al cerrar; motivos de omisión	Cierre	Comprobar E-map generado
AC-5	Aceptación	Reanudar sesión activa sin crear una nueva	Reanudar sesión	Misma sesión reconectada
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; cierre avisa al backend	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 genera el E-map si hay reporte válido. Confirmar con el cliente y fijar el valor 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.
2026-04-11	v1.4	Actualización para reflejar implementación real: herramientas del canal de apoyo (lookup_methodology, get_user_context, end_session) con entradas y salidas detalladas; reporte final con todos sus campos (schema v2); flujo completo sesión→reporte→E-map con diagrama Mermaid; E-map generado directamente desde el reporte (no solo aviso). Eliminada mención a record_answer.
2026-07-02	v1.5	Sincronización con el código actual: (1) la respuesta al iniciar entrega parámetros de audio en tiempo real (VAD con silencio configurable, reducción de ruido, transcripción) y datos del canal de apoyo — R-1.6. (2) La sesión captura el idioma (es/en/pt) y el reporte se genera en ese idioma — R-1.7. (3) El cierre lo dispara la app ("completar sesión"), no Brun-E; eliminada la herramienta end_session; el backend genera el reporte si hay transcript y no llega formado — CU-3, R-2.2. (4) Del canal de apoyo sólo está activa lookup_methodology; get_user_context y get_last_session_report quedan previstas/temporalmente inactivas — CU-2, R-2.1, AC-3. (5) Nuevo caso: reanudar una sesión activa tras recarga o caída de red — CU-5, R-2.6, AC-5. (6) Motivos de omisión del reporte (sin transcript / falló generación / faltan valores dictados). (7) Razones de denegación de elegibilidad diferenciadas (sesión activa, cooldown, máximo diario, estructural) con mensaje acorde — R-3.2.