openccb/docs/QUESTION_BANK_UI.md

Question Bank UI - Documentación

Vista General

El Banco de Preguntas es una interfaz completa en Studio para gestionar preguntas reutilizables con soporte para audio generado por IA.

Acceso

http://localhost:3000/question-bank

Componentes

1. Página Principal (/question-bank/page.tsx)

Características:

• Lista todas las preguntas del banco
• Filtros por tipo, dificultad, origen, audio
• Búsqueda por texto
• Estadísticas rápidas (total, importadas, con audio, IA)
• Accesos rápidos para crear e importar

Estadísticas mostradas:

┌──────────────┬──────────────┬──────────────┬──────────────┐
│ Total        │ MySQL        │ Con Audio    │ IA           │
│    150       │     45       │     32       │     18       │
└──────────────┴──────────────┴──────────────┴──────────────┘

2. QuestionBankCard (QuestionBankCard.tsx)

Tarjeta individual de pregunta que muestra:

• Tipo de pregunta (badge)
• Dificultad (color-coded)
• Texto de la pregunta (truncado)
• Opciones preview (primeras 3)
• Estado del audio
• Origen (MySQL, IA, Manual)
• Uso (veces utilizada)
• Acciones: Editar, Eliminar, Audio

Badges de tipo:

• 🟦 Opción Múltiple
• 🟩 Verdadero/Falso
• 🟨 Respuesta Corta
• 🟪 Ensayo
• 🟧 Emparejamiento
• 🔵 Ordenar
• 🟫 Completar
• 🟣 Respuesta Audio
• 🔴 Hotspot
• ⬛ Código

Badges de dificultad:

• 🟢 Fácil (easy)
• 🟡 Media (medium)
• 🔴 Difícil (hard)

Badges de origen:

• 🌐 MySQL - Importado desde sistema legacy
• ✨ IA - Generado por Inteligencia Artificial
• Manual - Creado manualmente

3. QuestionBankEditor (QuestionBankEditor.tsx)

Modal para crear/editar preguntas con:

Campos:

• Tipo de pregunta (10 tipos soportados)
• Dificultad (easy/medium/hard)
• Texto de la pregunta (required)
• Opciones (para multiple-choice/true-false)
• Respuesta correcta (selector radial)
• Explicación/feedback
• Puntos
• Etiquetas (tags)
• Checkbox "Generar audio automáticamente"

Características especiales:

• Botón "Generar con IA" para opciones y explicación
• Agregar/remover opciones dinámicamente
• Tags con auto-complete
• Validación en tiempo real

4. MySQLImportModal (MySQLImportModal.tsx)

Modal para importar preguntas desde MySQL:

Flujo:

1. Selecciona curso de MySQL (carga dinámica)
2. Click en "Importar Preguntas"
3. Importa todas las preguntas activas del curso
4. Muestra cantidad importada
5. Redirige a la lista actualizada

Información mostrada:

• Lista de cursos disponibles (NombreCurso + NombrePlan)
• Explicación de qué se importará
• Progreso de importación
• Resultado (éxito/error)

Flujos de Usuario

Crear Pregunta Manualmente

1. Click "Nueva Pregunta"
2. Seleccionar tipo de pregunta
3. Completar texto de pregunta
4. Agregar opciones (si aplica)
5. Marcar respuesta correcta
6. Agregar explicación (opcional)
7. Configurar puntos y dificultad
8. Agregar etiquetas
9. ☑️ Marcar "Generar audio automáticamente"
10. Click "Guardar Pregunta"

Importar desde MySQL

1. Click "Importar desde MySQL"
2. Seleccionar curso del dropdown
3. Click "Importar Preguntas"
4. Esperar confirmación (ej: "Se importaron 45 preguntas")
5. Las preguntas aparecen en la lista con badge 🌐 MySQL

Generar Audio para Pregunta

1. Click ícono 🔊 en pregunta (si no tiene audio)
2. (Opcional) Personalizar texto para audio
3. Seleccionar voz
4. Ajustar velocidad
5. Click "Generar Audio"
6. Esperar generación (5-30 segundos)
7. Click "Reproducir" para preview
8. Click "Cerrar" cuando esté listo

Filtrar Preguntas

1. Click "Filtros"
2. Seleccionar tipo de pregunta
3. Seleccionar dificultad
4. Seleccionar origen
5. Filtrar por audio (con/sin)
6. Results se actualizan automáticamente

Buscar Preguntas

1. Escribir en barra de búsqueda
2. Presionar Enter
3. Results filtran por texto en question_text

Integración con Test Templates

Las preguntas del banco se pueden usar en:

• Plantillas de pruebas (Test Templates)
• Lecciones tipo quiz directamente
• Ejercicios de práctica

Próximamente:

• Selector de preguntas desde banco al crear plantilla
• Bulk selection para agregar múltiples preguntas
• Vista previa de pregunta con audio

API Endpoints Utilizados

// Listar preguntas
GET /question-bank?question_type=multiple-choice&difficulty=medium&has_audio=true

// Crear pregunta
POST /question-bank
{
  "question_text": "What is...?",
  "question_type": "multiple-choice",
  "options": ["A", "B", "C", "D"],
  "correct_answer": 0,
  "explanation": "Because...",
  "points": 1,
  "difficulty": "medium",
  "tags": ["grammar", "past-tense"],
  "generate_audio": true
}

// Actualizar pregunta
PUT /question-bank/{id}

// Eliminar pregunta
DELETE /question-bank/{id}

// Importar desde MySQL
POST /question-bank/import-mysql
{
  "mysql_course_id": 30,
  "import_all": true
}

// Generar audio
POST /question-bank/{id}/generate-audio
{
  "text": "What color is the sky?",
  "voice": "v2/en_speaker_1",
  "speed": 1.0
}

// Listar cursos MySQL
GET /question-bank/mysql-courses

Estilos y UX

Tema:

• Soporte completo dark mode
• Colores consistentes con el resto de Studio
• Animaciones suaves (hover, transitions)

Responsive:

• Grid adaptable (1/2/3 columnas)
• Modal con scroll interno
• Touch-friendly en móviles

Accesibilidad:

• Labels en todos los inputs
• Focus visible
• ARIA attributes
• Keyboard navigation

Próximas Mejoras

• Bulk audio generation (múltiples preguntas)
• Exportar preguntas a CSV/JSON
• Importar desde CSV
• Vista previa de pregunta completa en card
• Historial de ediciones
• Comentarios/notas en preguntas
• Compartir preguntas entre organizaciones
• Analytics de uso por pregunta
• AI-powered tagging automático
• Detección de preguntas duplicadas

Troubleshooting

Error: "No se pudo cargar los cursos de MySQL"

• Verificar que MYSQL_DATABASE_URL esté configurado en .env
• Verificar conectividad al servidor MySQL

Audio no se reproduce

• Verificar formato de audio (WAV soportado)
• Verificar permisos del navegador
• Probar en otro navegador

Referencias

• Question Bank Backend
• Test Templates UI