Manual explicativo para clases · IBDP Computer Science SL

Cómo está construida la web EnrolUAE

Este repositorio interactivo documenta la aplicación web EnrolUAE de principio a fin: la identidad de marca, los cinco lenguajes utilizados (HTML, CSS, JavaScript, JSON y Python), la arquitectura, cada componente interactivo, los algoritmos y el código fuente completo explicado bloque a bloque, con demostraciones en vivo que ejecutan el código real.

HTML5CSS3JavaScript ES2022JSONPython 3.12 Sin frameworks12 idiomasResponsive

Abrir la aplicación Ir al código explicado

¿Qué problema resuelve la aplicación?

Las familias hispanohablantes que se trasladan a los Emiratos Árabes Unidos encuentran la información sobre matriculación escolar dispersa, en inglés y con un sistema educativo distinto al de origen. EnrolUAE centraliza esa información en una aplicación web interactiva, bilingüe (con traducción automática a otros diez idiomas) y con un asistente conversacional.

Cifras del proyecto (leídas en vivo de los datos)

Criterios de éxito (requisitos del cliente)

• Proceso de matriculación paso a paso (6 pasos, con progreso guardado).
• Lista personalizada e interactiva de documentos (15 documentos, marcables).
• Sección de currículos con IB, británico y americano: estructura por cursos, características y evaluación, más comparador y calculadora de curso.
• Preguntas frecuentes en un archivo JSON con 8 preguntas relevantes para familias hispanas.
• Búsqueda con ocho grupos de palabras clave predefinidas («documentos», «plan de estudios», «costos», «matrícula»…).
• Chatbot «Linda» basado en reglas con 86 temas + 28 colegios (el cliente exigía 15), tolerante a erratas, con contexto, avatar animado y respuesta alternativa que redirige a las FAQ.
• Diseño responsive sin desplazamiento horizontal, verificado automáticamente en tres tamaños de pantalla.
• Ampliaciones v2: identidad de marca premium, fotografías reales de Dubái, iconografía propia, traductor multiidioma y capa Python (API + validador + pruebas).
• Ampliaciones v3: mapa interactivo de 28 colegios (Leaflet/OpenStreetMap) con costos, religión y analíticas por colegio, sección monográfica de GEMS World Academy, logotipo vectorial, cursor lápiz, avatar animado de Linda y chat desplegable en móvil.
• Ampliaciones v4: capa de comprensión (NLU) de Linda —tipo de pregunta, entidades, búsqueda combinada de colegios con relajación de filtros y distancia geográfica, atributos con memoria de contexto, comparación de colegios, multipregunta, edad → curso, aclaración y búsqueda profunda—, idéntica en JavaScript y Python (paridad 39/39 preguntas); cuotas reales 2025-26 y fotos reales de los 28 colegios.

2Lenguajes y tecnologías

La aplicación está construida con las tres tecnologías estándar de la web, un formato de datos y un lenguaje de servidor. No usa frameworks (React, Vue, Flask…) y la única librería externa es Leaflet (mapa, código abierto) cargada desde CDN: todo el resto del código es propio, lo que facilita explicarlo, evaluarlo y ejecutarlo sin instalar dependencias.

¿Por qué el mismo algoritmo en JavaScript y en Python?

Paradigmas y técnicas

• Programación modular: cada función de la web es un módulo (Search, Process, Documents, Curricula, Estimator, FAQ, ChatUI, Translator).
• Orientación a objetos: la clase RuleBasedChatbot (JS y Python) encapsula estado (contexto) y comportamiento (reply()).
• Programación dirigida por eventos: clics, formularios, IntersectionObserver, evento personalizado languagechange.
• Programación asíncrona: Promise.all para cargar seis JSON en paralelo; fetch a la API con tiempo límite.
• Cliente–servidor: API REST en Python con JSON como formato de intercambio.
• Estructuras de datos: arrays, objetos/diccionarios, Set, listas ordenadas por clave compuesta, conjuntos de posiciones cubiertas.
• Algoritmos: normalización de texto, distancia de Levenshtein (programación dinámica), puntuación con desempate, filtrado por reglas.

3Estructura de archivos

Haz clic en cualquier archivo del árbol para ver qué hace, de qué se responsabiliza y cuántas líneas tiene (contadas en vivo). El botón «Ver código explicado» abre el archivo en el explorador de la sección 11.

4Arquitectura y flujo de datos

La aplicación separa datos (JSON), lógica (JavaScript en el navegador y Python en el servidor) y presentación (HTML + CSS). Puede funcionar en dos modos. Haz clic en cada bloque.

Los dos modos de ejecución

Secuencia de arranque del navegador

1. index.html enlaza styles.css y los scripts en orden: icons.js → i18n.js → translate.js → chatbot.js → app.js.
2. Al dispararse DOMContentLoaded: applyTranslations() traduce los textos estáticos y renderIcons() sustituye los <i data-icon> por SVG.
3. Nav.init() activa el menú, el resaltado de sección y el menú de idiomas (Translator.init()).
4. loadData() descarga los seis JSON en paralelo y los guarda en DATA.
5. Cada módulo ejecuta init() → registra eventos y llama a render().
6. ChatUI.detectPython() comprueba si existe la API y elige el motor.
7. Si cambia el idioma, setLanguage() emite languagechange y todos los módulos vuelven a renderizar.

5Identidad de marca y diseño visual

El logotipo

Un badge cuadrado redondeado en azul marino (#0B2A3A) contiene tres ideas en un solo trazo dorado: la aguja del Burj Khalifa (Dubái, aspiración), un libro abierto (educación) y tres figuras redondeadas (la familia: dos adultos y un niño). El degradado dorado (#A8861B → #E8C766) aporta el carácter premium; el marino transmite confianza institucional. Funciona a 44 px en la cabecera, como favicon y como icono de app.

Nombre: Enrol (matricular, en inglés británico, el más usado en Dubái) + UAE en dorado. En el código, la clase .brand-accent colorea la segunda parte.

Paleta de colores (haz clic para copiar el código)

Inspirada en Dubái: el marino de la noche sobre el Golfo, el teal de las aguas, el dorado del desierto y los neutros arena/marfil. Todos los colores son variables CSS en :root.

Tipografía

Tamaños fluidos con clamp(): h1 { font-size: clamp(2.2rem, 4.2vw + 0.6rem, 3.6rem); }.

Logotipo vectorial y cursor

El logotipo se dibujó a mano como SVG (assets/img/logo.svg, 3 KB): un círculo con degradado dorado, disco marino, anillo interior, la aguja del Burj Khalifa en tramos escalonados (con líneas de retranqueo), dos crecientes construidos con dos arcos de radios distintos y un libro abierto con páginas curvas. Al ser vectorial es nítido en la cabecera (44 px), el favicon y a tamaño póster. El cursor también es SVG (cursor-pencil.svg): un lápiz con la punta como hotspot en (6,26); en enlaces y botones cambia a la variante dorada. Se declara con cursor: url(…) 6 26, auto y los navegadores sin soporte usan la flecha normal.

Iconografía propia (SVG)

En lugar de emojis (que cambian de aspecto según el sistema operativo), la web usa un set de 60+ iconos SVG dibujados en una cuadrícula de 24×24 con trazo de 1,8 px y extremos redondeados (js/icons.js). Heredan el color del texto (currentColor) y escalan con la tipografía. Pasa el ratón para ver el nombre; haz clic para copiar el código HTML.

const ICONS = {
  search: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>',
  // …60 iconos más
};
function icon(name, cls = "") {
  return `<svg class="icon ${cls}" viewBox="0 0 24 24" fill="none" stroke="currentColor"
     stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">${ICONS[name]}</svg>`;
}
// En HTML: <i data-icon="search"></i>  →  renderIcons() lo sustituye por el SVG

Fotografía: real + fotorrealista

La v2 sustituye las ilustraciones planas por fotografía. Hay dos tipos, siempre etiquetados en la web:

• Fotografías reales de Dubái (etiqueta «Foto real»): obtenidas de Wikimedia Commons a través de su API pública, filtrando por licencias libres (CC0, CC BY, CC BY-SA). Incluyen el Burj Khalifa, Dubai Marina y un aula real de The Arbor School Dubai. La atribución a cada autor aparece en el pie de la web, como exige la licencia.
• Renders fotorrealistas (etiqueta «Render fotorrealista»): las escenas de familias hispanas frente al Burj Khalifa no existen en bancos libres de derechos, así que se generaron con un modelo de imágenes a partir de descripciones detalladas (óptica, hora del día, vestimenta, composición). Se marcan como tales por honestidad con el usuario.

Componentes de interfaz reutilizables

:root {
  --navy-900: #0b2a3a;   /* color principal de marca */
  --gold-600: #c9a227;   /* acento premium */
  --gold-gradient: linear-gradient(135deg, var(--gold-700), var(--gold-300));
  --radius: 18px; --shadow: 0 10px 30px rgba(11, 42, 58, 0.12);
}
.btn-gold { background: var(--gold-gradient); color: var(--navy-900); }
.hero-overlay { background: linear-gradient(90deg, rgba(11,42,58,.92), rgba(11,42,58,.15)); }

6Diseño responsive

Estrategia desktop-first con cuatro puntos de ruptura. Prueba a cambiar el dispositivo en la vista previa en vivo:

Móvil · 375 px

Técnicas utilizadas

7Idiomas y traductor multiidioma

La web tiene dos capas de idioma:

// i18n.js — texto estático y de datos
function t(key)   { return I18N[currentLang][key] || I18N.en[key] || key; }
function pick(obj){ return obj[currentLang] || obj.en || ""; }
function setLanguage(lang) {
  currentLang = lang; localStorage.setItem("enroluae-lang", lang);
  applyTranslations();                                   // recorre data-i18n, -placeholder, -aria, -alt
  document.dispatchEvent(new CustomEvent("languagechange"));
}
// translate.js — traducción automática
applyMachine(code) {
  document.cookie = `googtrans=/${currentLang}/${code}; path=/`;   // Google la lee al cargar
  this.loadWidget().then(() => { combo.value = code; combo.dispatchEvent(new Event("change")); });
}

8Componentes interactivos

Cada función de la web es un componente independiente. Para cada uno: qué hace, archivos implicados, cómo funciona y una demo en vivo con el código real.

const observer = new IntersectionObserver((entries) => {
  entries.forEach((e) => { if (e.isIntersecting)
    links.forEach((a) => a.classList.toggle("is-active", a.getAttribute("href") === "#" + e.target.id)); });
}, { rootMargin: "-40% 0px -55% 0px" });
sections.forEach((s) => observer.observe(s));

applies(doc, profile) {
  const rules = doc.rules || {};
  if (rules.always) return true;
  return Object.entries(rules).every(([key, allowed]) => allowed.includes(profile[key]));
}

filtered() {
  const f = this.filters, q = normalise(f.q);
  return this.schools.filter((s) =>
    (f.curriculum === "all" || s.curriculum.includes(f.curriculum)) &&
    (f.rating === "all" || s.khda.rating === f.rating) &&
    s.fees.min <= f.maxFee && (!f.spanish || s.spanish.offered) &&
    (!q || normalise(s.name + " " + s.area).includes(q)));
}
// marcador: color por currículo + iniciales, seleccionado en dorado
L.marker([s.lat, s.lng], { icon: this.markerIcon(s, s.id === this.selectedId) })
  .bindPopup(`<strong>${s.name}</strong>…`).on("click", () => this.select(s.id));

9Algoritmos clave (pseudocódigo)

9.1 Normalización de texto

FUNCTION normalise(text)
  text ← toLowerCase(text)
  text ← removeAccents(text)            // "matrícula" → "matricula"
  text ← replaceNonAlphanumeric(text, " ")
  RETURN collapseSpaces(trim(text))
END FUNCTION

9.2 Distancia de Levenshtein (tolerancia a erratas)

FUNCTION distance(a, b)                 // nº mínimo de inserciones, borrados o cambios
  IF a = b THEN RETURN 0
  IF |len(a) − len(b)| > 1 THEN RETURN 2  // corte rápido: nunca aceptamos más de 1
  prev ← [0, 1, 2, …, len(b)]
  FOR i ← 1 TO len(a)
    cur ← [i]
    FOR j ← 1 TO len(b)
      cost ← 0 IF a[i] = b[j] ELSE 1
      cur[j] ← MIN(prev[j] + 1, cur[j−1] + 1, prev[j−1] + cost)
    END FOR
    prev ← cur
  END FOR
  RETURN prev[len(b)]
END FUNCTION

9.3 Puntuación de una regla con consumo único de palabras

FUNCTION score(rule, tokens)
  covered ← ∅ ; score ← 0
  FOR EACH key IN rule.keys ORDERED BY wordCount DESC        // frases largas primero
    pos ← findKeyword(tokens, key)                            // −1 si no está
    IF pos ≥ 0 AND ninguna posición pos..pos+n−1 ∈ covered THEN
      covered ← covered ∪ {pos..pos+n−1}
      score ← score + n                                       // n = palabras de la clave
    END IF
  END FOR
  IF score > 0 THEN score ← score + MAX(0, rule.priority)     // bonificación de especificidad
  RETURN score
END FUNCTION

9.4 Respuesta por niveles con contexto

FUNCTION reply(userText)                       // v4
  pieces ← splitQuestions(userText)             // «… y …», «?»
  IF count(pieces) > 1 THEN RETURN merge(replyOne(p) FOR p IN pieces)
  RETURN replyOne(normalise(userText))
END FUNCTION

FUNCTION replyOne(text)
  a ← analyse(text)                             // tipo de pregunta + entidades + colegios nombrados
  IF a.compare THEN RETURN compareAnswer(a.schools[0], a.schools[1])
  IF (a.schools = 1 OR ctx.school recent) AND a.attribute THEN RETURN attributeAnswer(school, a.attribute)
  IF a.filters ≥ 1 AND (aboutSchools OR a.filters ≥ 2 OR a.area OR refining) THEN
    results ← searchSchools(merge(ctx.search, a))   // relaja filtros si está vacío
    RETURN searchAnswer(results)
  IF a.age THEN RETURN gradeAnswer(a.age)
  best ← bestOf(scoreAll(text, MAIN))
  IF best = NULL AND lastText ≠ "" AND wordCount(text) ≤ 6 THEN
    best ← bestOf(scoreAll(lastText + " " + text, MAIN) EXCEPT lastRule)   // contexto
  IF best = NULL THEN best ← bestOf(scoreAll(text, FAQ))
  IF best ≠ NULL THEN
    lastText ← text ; lastRule ← best
    RETURN { answer: best.answer, confidence: level(best.score), related: relatedFor(best) }
  IF isSmallTalk(text) THEN RETURN smallTalkAnswer
  deep ← deepSearch(text)                       // palabras significativas dentro de las respuestas
  IF deep ≠ NULL THEN RETURN deep.answer (confianza baja)
  RETURN fallbackAnswer   // enlaza a las FAQ + sugerencias
END FUNCTION

9.5 Complejidad

Con R ≈ 86 intenciones y K ≈ 12 palabras clave de media, una pregunta de T ≈ 8 palabras cuesta O(R·K·T) ≈ 8 000 comparaciones de cadenas, más las distancias de Levenshtein solo cuando las longitudes son compatibles. En la práctica: menos de 5 ms en el navegador y en Python. Las palabras clave se normalizan y ordenan una única vez en el constructor.

10Capa Python: servidor, API, validador y pruebas

La carpeta python/ y el archivo server.py añaden un backend escrito solo con la biblioteca estándar de Python (sin pip install). Cuatro piezas:

API REST

class EnrolHandler(SimpleHTTPRequestHandler):
    def do_POST(self):
        if urlparse(self.path).path != "/api/chat":
            return self.send_json({"error": "not found"}, HTTPStatus.NOT_FOUND)
        length = int(self.headers.get("Content-Length", "0"))
        payload = json.loads(self.rfile.read(length) or b"{}")
        result = session_bot(payload.get("session", "anon")).reply(payload.get("text", ""))
        result["engine"] = "python"
        self.send_json(result)

Ejecutar las herramientas Python

python server.py 8080                      # web + API (o doble clic en start-server.bat)
python python/data_validator.py            # informe de validación de los JSON
python -m unittest python/test_chatbot.py  # 15 pruebas unitarias
python python/chatbot_engine.py            # chat por consola con el motor Python

11Código completo explicado

Aquí está todo el código fuente del proyecto, cargado en vivo desde los archivos reales (siempre actualizado), con resaltado de sintaxis, números de línea y una explicación bloque a bloque a la derecha. Haz clic en una explicación para resaltar las líneas a las que se refiere; haz clic en una línea del código para saber a qué bloque pertenece.

12Persistencia con localStorage

Sin base de datos: el estado del usuario se guarda en el navegador como pares clave → texto (JSON.stringify / JSON.parse). El servidor Python solo guarda en memoria el contexto de la conversación por sesión.

13Accesibilidad

• Enlace «Saltar al contenido» y navegación completa con teclado (:focus-visible dorado).
• ARIA: role="progressbar" + aria-valuenow, aria-expanded (menús), aria-selected (pestañas), role="menu" / menuitemradio (idiomas), aria-live (chat, resultados, insignia de motor).
• Todas las imágenes decorativas llevan alt=""; las informativas tienen texto alternativo traducido (data-i18n-alt).
• Iconos SVG con aria-hidden="true": el texto adyacente es el que se lee.
• Contraste AA: texto marino sobre marfil; blanco sobre marino; dorado solo en tamaños grandes o con peso 700.
• Soporte RTL (dir="rtl") para árabe y urdu.
• Todo el HTML generado pasa por escapeHtml(); la API Python limita la longitud de entrada y usa lista blanca de archivos.

14Plan de pruebas

Tres niveles de prueba, todos automatizados:

15Cómo ejecutar y extender el proyecto

Ejecutar

• Con Python (recomendado): doble clic en start-server.bat o python server.py → http://localhost:8080. Activa la API y el motor Python.
• Sin Python: cualquier servidor estático (Live Server, npx serve, Netlify, GitHub Pages). Todo funciona con el motor JavaScript.

Añadir una regla al chatbot

{
  "id": "school-lunch", "category": "practical", "priority": 1,
  "question": { "en": "Is there a canteen?", "es": "¿Hay comedor?" },
  "keywords": ["comedor", "canteen", "lunch box"],
  "answer": { "en": "Most schools…", "es": "La mayoría de colegios…" },
  "link": "#costs", "related": ["hidden-costs"]
}

Después ejecuta python python/data_validator.py para comprobar enlaces y relacionados, y añade un caso a test_chatbot.py. Ambos motores la usarán automáticamente.

Añadir una FAQ, un documento o un paso

Basta con añadir el objeto al JSON correspondiente (con aliases en documentos y pasos): la web lo renderiza, el buscador lo indexa y el chatbot lo incorpora a su base de conocimiento.

Añadir un idioma nativo

Añade la clave (p. ej. "fr") al objeto I18N, marca el idioma como native: true en LANGUAGES (translate.js) y añade el campo "fr" a los objetos bilingües de los JSON.

16Autoevaluación para clase

Pulsa una opción para comprobar si es correcta.

17Glosario

API REST

Interfaz por HTTP en la que cada ruta (/api/chat) representa un recurso y se intercambia JSON.

Backdrop-filter

Propiedad CSS que desenfoca lo que hay detrás de un elemento (efecto cristal de la cabecera).

Chatbot basado en reglas

Programa que responde comparando el texto con palabras clave predefinidas; no aprende ni usa IA.

Cliente–servidor

Arquitectura en la que el navegador (cliente) pide datos a un programa remoto (servidor).

Consumo único de palabras

Regla del motor: una palabra del usuario solo puede puntuar una vez por regla.

Design token

Variable CSS con un valor de diseño reutilizable (color, radio, sombra, tipografía).

Distancia de Levenshtein

Número mínimo de ediciones (insertar, borrar, sustituir) para convertir una palabra en otra.

DOM

Representación en árbol del HTML que JavaScript puede leer y modificar.

Fallback

Respuesta alternativa cuando ninguna regla coincide; aquí redirige a las FAQ.

fetch / async-await

API para pedir recursos por HTTP y sintaxis para esperar el resultado sin bloquear.

http.server

Módulo de la biblioteca estándar de Python para crear servidores HTTP sencillos.

i18n

Internacionalización: separar los textos del código para soportar varios idiomas.

JSON

Formato de texto para datos estructurados; el mismo en JavaScript y Python (json.loads).

KHDA

Autoridad reguladora de los colegios privados de Dubái.

localStorage

Almacén clave-valor del navegador que persiste entre sesiones.

Media query

Regla CSS condicional, p. ej. @media (max-width: 720px).

Normalización

Transformar texto a una forma estándar (minúsculas, sin acentos) para comparar con fiabilidad.

Prioridad / bonificación de especificidad

Valor de una regla que se suma a su puntuación para que lo específico gane a lo genérico.

Responsive design

Diseño que se adapta al tamaño de pantalla.

Set

Colección de valores únicos (JS Set, Python set).

SVG

Gráficos vectoriales escalables; formato de los iconos de la web.

Template literal

Cadena JS con comillas invertidas que permite insertar variables: `Hola ${nombre}`. En Python: f-strings.

unittest

Módulo de pruebas unitarias de la biblioteca estándar de Python.