266 lines
6.5 KiB
Markdown
266 lines
6.5 KiB
Markdown
# 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
|
|
|
|
```typescript
|
|
// 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](../../services/cms-service/src/handlers_question_bank.rs)
|
|
- [Test Templates UI](./TestTemplates/)
|