Add materials, exam images, storage quota, and API guide

Upload documents for AI context, exam images for Moodle questions, per-template storage limits, embedded images in XML export, and GUIA_API_Y_FLUJO.md with full endpoint documentation.

README.md

@@ -2,6 +2,8 @@
 
 Backend para generar exámenes con IA, procesar la salida de un LLM y exportar preguntas a Moodle XML.
 
+**Guía detallada de flujo, endpoints, ejemplos y errores:** [GUIA_API_Y_FLUJO.md](GUIA_API_Y_FLUJO.md)
+
 El proyecto está centrado en backend. La carpeta `frontend` se mantiene vacía a nivel de aplicación, aunque existe un servicio en Docker Compose para reservar el despliegue futuro.
 
 ## Stack
@@ -46,6 +48,7 @@ Variables principales:
 - `LLM_BASE_URL`: endpoint compatible con OpenAI.
 - `LLM_MODEL`: modelo usado para generar preguntas.
 - `ALLOWED_ORIGINS`: orígenes permitidos por CORS.
+- `MAX_STORAGE_BYTES_PER_TEMPLATE`: cupo total de almacenamiento por examen (materiales + imágenes).
 
 Todas las rutas bajo `/exam` requieren autenticación de usuario con:
 
@@ -64,11 +67,12 @@ docker compose up --build
 
 1. Registrarse o iniciar sesión.
 2. Crear una plantilla de examen (queda asociada al usuario).
-3. Generar un prompt guiado para el LLM.
-4. Generar preguntas automáticamente con el LLM o parsear una salida externa en JSON/TXT.
-5. Guardar las preguntas validadas en PostgreSQL.
-6. Consultar el historial de exámenes creados.
-7. Exportar el examen a Moodle XML, TXT o JSON.
+3. Subir materiales de referencia (PDF, DOCX, TXT, PNG, JPG…) a la plantilla.
+4. Generar un prompt guiado para el LLM (incluye el texto extraído de los ficheros).
+5. Generar preguntas automáticamente con el LLM o parsear una salida externa en JSON/TXT.
+6. Guardar las preguntas validadas en PostgreSQL.
+7. Consultar el historial de exámenes creados.
+8. Exportar el examen a Moodle XML, TXT o JSON.
 
 ## Endpoints
 
@@ -96,6 +100,38 @@ Devuelve los datos del usuario autenticado.
 
 Lista el historial de exámenes del usuario (plantillas, preguntas y exportaciones).
 
+`POST /exam/templates/{template_id}/materials`
+
+Sube un fichero (`multipart/form-data`, campo `file`). Formatos: PDF, DOCX, TXT, MD, PNG, JPG, WEBP. Extrae texto y lo guarda como contexto.
+
+`GET /exam/templates/{template_id}/materials`
+
+Lista los materiales subidos a una plantilla.
+
+`DELETE /exam/templates/{template_id}/materials/{material_id}`
+
+Elimina un material.
+
+`POST /exam/templates/{template_id}/images`
+
+Sube una imagen para preguntas visuales (`file`, opcional `caption`). No se usa OCR: la imagen se muestra en el examen y se embebe en el XML de Moodle.
+
+`GET /exam/templates/{template_id}/images`
+
+Lista las imágenes de la plantilla.
+
+`GET /exam/images/{image_id}/content`
+
+Devuelve la imagen (requiere JWT). Para previsualizar en el frontend o en Moodle tras importar.
+
+`DELETE /exam/templates/{template_id}/images/{image_id}`
+
+Elimina una imagen.
+
+`PATCH /exam/questions/{question_id}/image`
+
+Vincula o desvincula una imagen a una pregunta existente (`{"image_id": "uuid"}` o `null`).
+
 `POST /exam/templates`
 
 Crea una plantilla con materia, nivel educativo, tipos de pregunta, puntuación, penalización y dificultad.
@@ -108,6 +144,10 @@ Lista las plantillas del usuario autenticado.
 
 Obtiene una plantilla concreta.
 
+`GET /exam/templates/{template_id}/storage`
+
+Muestra cuánto espacio usa el examen (materiales + imágenes) y el límite configurado.
+
 `POST /exam/prompts/{template_id}`
 
 Genera un prompt estructurado para IA.