Manual Editor – Especificación completa

1) Resumen ejecutivo

Este documento define todo lo necesario para que un desarrollador implemente el módulo Manual Editor sin consultas adicionales, respetando el flujo de trabajo y estándares del equipo.

• Lectura y edición en vivo del campo manual (LONGTEXT) de la tabla cursos_sence, identificado por $curso_id = cursos_sence.id.
• Interfaz en dos columnas: galería de imágenes arrastrables (izquierda) + editor TinyMCE (derecha).
• Inserción por drag & drop de imágenes en el contenido; actualización persistente del HTML.
• Subida de imágenes con validaciones, límite y optimización automática (Imagick → GD).
• Registro de historial en tabla manual_historial previo a cada actualización.
• Monitoreo por consola (cliente) y en error_log (servidor).

2) Decisiones confirmadas

• Editor: TinyMCE Community (se dispone de carpeta local: /manual_editor/tinymce/js/tinymce/ tal como la imagen proporcionada; también se admite CDN si se prefiere).
• Raíz del módulo: /manual_editor/
• Carpeta de imágenes (configurable en duro): /manual_editor/img/
• Formatos permitidos: jpg, jpeg, png, gif.
• Límites: 4 MB por archivo, 2560 px lado mayor (reeescala/optimiza si los excede).
• Rutas de imágenes en contenido: relativas bajo el propio módulo.
• Acceso: “cualquiera puede editar” (no hay control de roles en esta fase).
• Historial: tabla manual_historial, sin interfaz de administración por ahora.
• CSRF: activado desde el inicio.

3) Objetivos funcionales

1. Cargar manual por $curso_id y mostrarlo en el editor.
2. Listar imágenes desde $carpeta_img como miniaturas arrastrables.
3. Permitir subir imágenes (validar, optimizar, guardar, exponer URL relativa).
4. Insertar imágenes por drag&drop en el contenido.
5. Actualizar el campo manual con el HTML resultante (texto + <img>).
6. Crear registro en manual_historial previo a la actualización.
7. Mostrar notificaciones y logs claros de cada acción.

4) Arquitectura de archivos

Todos los archivos residen bajo /manual_editor/:

5) Configuración (en duro, reutilizable)

Las siguientes variables se definirán al inicio de manual_editor.php y se reutilizarán (vía include) en los endpoints:

Todos los endpoints deben include el mismo archivo de configuración para mantener consistencia.

6) UI / UX

7) Arrastrar y soltar (comportamiento)

1. La miniatura establece en dataTransfer una carga con la ruta relativa (p. ej. /manual_editor/img/curso_123_1717400000.jpg).
2. El área del editor acepta el drop y usa la API de TinyMCE para insertar un nodo <img> en la posición del cursor.
3. Antes de insertar, se valida que la ruta:
   • No contenga ../ (path traversal).
   • Empiece por $carpeta_img.
   • Termine en una extensión permitida.

8) API – Contratos

8.1. GET /manual_editor/api_get_manual.php?curso_id={ID}

{
  "ok": true,
  "curso_id": 123,
  "html": "<p>...</p>"
}

{
  "ok": false,
  "error_code": "NOT_FOUND" | "INVALID_ID" | "DB_ERROR",
  "message": "..."
}

8.2. GET /manual_editor/api_listar_imagenes.php

{
  "ok": true,
  "base": "/manual_editor/img/",
  "page": 1,
  "total": 42,
  "imagenes": [
    {"nombre":"curso_123_1717400000.jpg","ruta_rel":"/manual_editor/img/curso_123_1717400000.jpg","ancho":1200,"alto":800,"peso":340212},
    ...
  ]
}

8.3. POST /manual_editor/api_subir_imagen.php

{
  "ok": true,
  "ruta_rel": "/manual_editor/img/curso_123_1717400000.jpg",
  "width": 1200, "height": 800, "size": 240132
}

{
  "ok": false,
  "error_code": "NO_FILE" | "EXT_NOT_ALLOWED" | "MIME_NOT_ALLOWED" | "TOO_LARGE" | "OPTIMIZE_FAIL" | "SAVE_FAIL" | "CSRF_FAIL",
  "message": "..."
}

8.4. POST /manual_editor/api_update_manual.php

{
  "curso_id": 123,
  "html": "<p>...<img src="/manual_editor/img/....jpg" alt="">...</p>",
  "csrf_token": "..."
}

{
  "ok": true,
  "updated": true,
  "historial_id": 9876
}

{
  "ok": false,
  "error_code": "INVALID_ID" | "EMPTY_HTML" | "SANITIZE_FAIL" | "DB_ERROR" | "CSRF_FAIL",
  "message": "..."
}

9) Base de datos

9.1. Tabla existente

• cursos_sence
  • id (PK, entero) — se usa como $curso_id.
  • manual (LONGTEXT) — contenido HTML.

9.2. Tabla de historial (nueva)

Definición funcional (sin entregar DDL):

10) TinyMCE

Se utilizará la distribución local provista (ver captura): /manual_editor/tinymce/js/tinymce/tinymce.min.js. Alternativamente puede emplearse CDN oficial si se desea.

• Plugins: link, lists, image, code, paste.
• Política de pegado: limpiar estilos/formatos agresivos; helpers_html.php hará el saneado final del lado servidor.
• Imágenes: se insertan por drop con src relativo, nunca data:.

11) Seguridad y saneado

11.1. Saneado HTML (servidor)

• Etiquetas permitidas: p, br, h1, h2, h3, h4, h5, h6, ul, ol, li, a, strong, em, u, blockquote, code, pre, hr, img, figure, figcaption, div, span.
• Atributos permitidos:
  • a: href, title, target (si _blank → añadir rel="noopener")
  • img: src (relativo bajo $carpeta_img), alt, title, width, height
  • class opcional para estilos Bootstrap
• Bloqueado: style inline, eventos on*, script, iframe, URLs externas en img, protocolo data:.

11.2. Subida de imágenes

• Validación de extensión y MIME real con finfo.
• Rechazo si excede límites → intentar optimización (reescalar/recomprimir) → guardar.
• Nomenclatura: curso_{ID}_{timestamp}_{rand}.{ext}
• Prevención de path traversal: limpiar nombres, prohibir ../.

11.3. CSRF

• Token generado en manual_editor.php, almacenado en $_SESSION.
• Incluido en POST de subida y actualización.
• Validado server-side; error CSRF_FAIL si no coincide.

12) Monitoreo y logging

12.1. Cliente (consola)

Todos los eventos relevantes deben registrarse con prefijo MANUAL_EDITOR:

12.2. Servidor

• Usar error_log con contexto: [curso_id] [endpoint] [ip] [ua] [detalle].
• Loggear fallos de validación, sanitización, optimización y SQL.

13) Catálogo de errores (códigos estándar)

14) Rendimiento

• Lazy loading/paginación en api_listar_imagenes.php (p. ej. 60 miniaturas por página).
• Miniaturas: mostrar versión reducida en cliente (usar loading="lazy" en <img>).
• Optimización en servidor con calidad adecuada (JPEG 75–82).

15) Cabeceras y endurecimiento

• X-Content-Type-Options: nosniff
• Referrer-Policy: same-origin
• Content-Security-Policy restrictiva (sin unsafe-inline si es posible; permitir la ruta local de TinyMCE).

16) Recursos obligatorios (front)

• jQuery 3.7.1 (CDN): https://code.jquery.com/jquery-3.7.1.js
• Bootstrap 5.3.3 JS (CDN): https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js
• Bootstrap 5.3 CSS (si no está global): CDN oficial.
• TinyMCE local: /manual_editor/tinymce/js/tinymce/tinymce.min.js

17) Plan de pruebas

1. Carga inicial: con curso_id válido/ inválido; manual vacío / con contenido pesado.
2. Listado imágenes: sin archivos / con 1000+ archivos (paginación); filtro por nombre.
3. Subida:
   • Archivos válidos en cada formato permitido.
   • Archivo > 4 MB y > 2560 px (verificar optimización).
   • MIME falso / extensión cambiada.
4. Drag&Drop: insertar 1, 10 y 100 imágenes; verificar rutas relativas y saneado.
5. Actualización: guardar cambios, confirmar inserción en manual_historial y UPDATE en cursos_sence.
6. CSRF: token ausente/incorrecto → rechazar.
7. Accesibilidad: foco, teclas de navegación, textos alternativos en <img>.

18) Criterios de aceptación

• El editor muestra exactamente el contenido del campo manual y los cambios se ven al instante.
• Se puede arrastrar cualquier miniatura válida y se inserta en el caret sin errores.
• Subidas fuera de límites son optimizadas y aceptadas; si fallan, se reporta con código y mensaje.
• Las rutas de <img> guardadas son relativas bajo $carpeta_img.
• Previo a cada UPDATE, se genera un registro en manual_historial.
• La consola muestra MANUAL_EDITOR logs consistentes para todas las acciones.

19) Plan de implementación por etapas (sin escribir código aún)

1. Esqueleto: crear estructura de archivos y bloque de configuración único.
2. UI base: layout Bootstrap 2 columnas, carga de TinyMCE y botones.
3. GET manual: endpoint + render en editor + logs LOAD_OK/FAIL.
4. Galería: endpoint listar + grid + dragstart.
5. Drop en TinyMCE: insertar <img> seguro (validaciones ruta).
6. Subida: endpoint multipart + validaciones + optimización + refresco galería.
7. Update: saneado server, historial, UPDATE BD + toasts + logs.
8. CSRF: integrar en subir y update.
9. Pulido: paginación, filtro, lazy images, mensajes UX.
10. QA: ejecutar plan de pruebas y checklist de aceptación.

20) Estándares y encabezados obligatorios de código

Cuando autorices la codificación, todos los archivos PHP del módulo iniciarán con el bloque de depuración y el include a la conexión que definiste:

• Config de errores activada (desactivable en producción).
• include("include/conecta_mysql_otec.php");
• Código organizado en secciones numeradas con comentarios claros.

21) Anexos

A) Glosario rápido

• Rutas relativas: comienzan en /manual_editor/ y no contienen ../.
• TinyMCE local: /manual_editor/tinymce/js/tinymce/tinymce.min.js
• Carpeta imágenes: /manual_editor/img/

B) Compatibilidad del botón “Buscar…”

Para seleccionar carpetas completas, usar el atributo webkitdirectory (Chrome/Edge/Opera/Brave). En Firefox no está soportado: usar selección múltiple de archivos. En todos los casos, la lectura del disco solo ocurre después de que el usuario selecciona explícitamente la carpeta/archivos.