Finanzas Gratis - Gamificación Financiera con IA

El estropicio que había antes

---

Lo que resuelve el código

La traba real	Lo que hace el programa
Una vez al mes y ni una más	En el formato de calendario de Google, fijar a la vez el día del mes y el de la semana hace que baste con cumplir uno de los dos. Por eso solo se fija el día: el 1, a las tres de la mañana en hora de España.
Contar preguntas, no papeles	Lo que falta en cada tema sale de las preguntas distintas, no de los documentos guardados, y del tope del mes se descuentan las que ya se guardaron ese mes. El mes se cuenta en hora de Madrid: a las 00:30 del 1 de noviembre ya cuenta noviembre, aunque en hora universal todavía sea 31 de octubre.
La misma pregunta con otras palabras	Cada pregunta se queda en sus palabras clave: sin tildes, sin signos y sin palabras vacías como que, el o para. Comisión y comisiones cuentan como la misma palabra. Se compara con todo el banco, y dos preguntas cuentan como la misma si comparten el 60 % de sus palabras clave.
Palabras de fuera	Una lista de términos de Estados Unidos y Latinoamérica, buscados como palabra suelta, también con tildes, para que cajero automático no salte por llevar auto dentro. Deducible solo se rechaza en seguros, porque en impuestos es correcto decir que una aportación es deducible, y una pregunta que hable del dólar se queda. El encargo a la IA de los ocho temas tiene que pasar su propio filtro.
Que el largo no chive la respuesta	Entre la respuesta más larga y la más corta no puede haber más de 15 caracteres, cada una va de 15 a 100 y la correcta no puede pasar en más de un 20 % la media de las otras tres. Tampoco valen dos respuestas iguales ni una explicación de menos de 50 caracteres.

---

La madre del cordero

Capacidades de procesamiento

Capacidad	Operación lógica que realiza
Preguntas sin repetir	El servidor lee la lista de preguntas que ese jugador ya respondió y elige entre las que le faltan, filtrando por su dificultad preferida si tiene una. Solo cuando las ha respondido todas vuelve a darle alguna.
Papeleta de respuesta	Cada pregunta servida deja su papeleta en el servidor. Cada nueva petición anula las papeletas anteriores del mismo jugador, así que solo vale la de la pregunta que tiene delante, y caduca a los 30 minutos.
Puntos con racha	Un acierto vale 10, 20 o 30 según el nivel de la pregunta, multiplicado por x2 desde el tercer acierto seguido y por x3 desde el octavo. La racha vuelve a cero al fallar o al empezar partida, y el día que alguien llega a Soberano/a queda apuntada la fecha.
Rangos y avatares	El rango sale de los puntos totales: Escudero/a con 1.200, Caballero/a con 3.400, Erudito/a con 6.800, Noble con 9.700, Consejero/a Real con 13.100 y Soberano/a con 15.000. Dentro de cada partida hay además seis niveles por aciertos, de Aprendiz a Rey con 50.
Camino al Trono	Hay una parada por cada cifra de puntos que desbloquea avatares, dieciséis en total. El personaje se coloca entre la última parada que ha pasado y la siguiente, en proporción a los puntos que lleva, y el paseo de entrada solo se repite si hay algo nuevo desde la última visita, porque lo recuerda el navegador.
Tarjeta para presumir	Cada jugador tiene una página y una imagen de 1200 × 630 para redes, las dos fabricadas en el servidor con sus datos reales. El enlace solo cambia con los puntos, para que las redes refresquen la vista previa, y un añadido que cambia superarle por superarme cuando la comparte el propio jugador. Estas páginas no se dejan indexar en Google.
Prueba gratis	Quince preguntas fáciles sin cuenta, sacadas desde un punto al azar del banco y mezcladas, así que cada prueba sale distinta. Puntúan con la misma regla que las partidas con cuenta, no se guardan en ningún sitio y el navegador recuerda que ya se gastó.
Biblioteca para personas y para IAs	Cada artículo de la biblioteca lleva su tiempo de lectura, que se calcula contando palabras a 200 por minuto, y al final de cada artículo se proponen primero los del mismo tema. Además se genera un resumen en texto plano para asistentes de IA con todos los artículos, y un mapa del sitio con la fecha real de cada uno.
Privacidad de verdad	Google Analytics no se carga hasta que el usuario acepta, la elección dura 12 meses y, si la retira, se borran sus cookies. La publicidad va siempre denegada porque la web no tiene. Borrar la cuenta elimina el perfil, su rastro en el ranking y el acceso, y devuelve un justificante con el artículo 17 del RGPD.

---

Flujo lógico de la información

1. Fábrica. Cada tema que va corto pide tandas a la IA.
   • Cada tanda trae 15 candidatas, y todas pasan por la criba hasta completar lo que falta.
2. Guardado. Cada pregunta aceptada entra con su nivel, su tema, un número al azar para el reparto y la sesión, el modelo y la temperatura con que se hizo.
3. Petición. El jugador pide una pregunta con su pase de sesión, y el servidor comprueba el pase antes de mirar nada más.
4. Reparto. El servidor elige una pregunta que no haya respondido, baraja las respuestas y guarda la papeleta.
   • Al navegador solo llegan la pregunta, las respuestas en el orden nuevo, el nivel, el tema y el número de la papeleta.
5. Corrección. Con la respuesta y la papeleta, el servidor corrige, suma, sube de rango si toca y borra la papeleta, todo en un solo movimiento.
   • De vuelta van el acierto o el fallo, el hueco correcto, la explicación, los puntos ganados y la racha.
6. Escaparate. El ranking lee a los jugadores ordenados por puntos.

Organización del sistema

Componente o módulo	Tarea técnica	Tecnología principal
Web	Sirve el juego, el perfil, el ranking y la biblioteca. La biblioteca, la guía del juego y el resumen para IAs se fabrican una sola vez al desplegar; el ranking y la tarjeta de cada jugador se hacen en cada visita, para que el puesto sea el de ese momento.	Next.js 14 y React 18
Funciones del juego	Cuatro puertas en el servidor: pedir preguntas, pedir la prueba gratis, responder y leer el ranking. Las que tocan la partida comprueban el pase de sesión antes de hacer nada.	Cloud Functions de Firebase, Node.js 22
Fábrica mensual	Una tarea programada que solo reparte el trabajo y otra que genera un tema cada vez, con 30 minutos de margen, 512 MB de memoria y un segundo intento a los dos minutos si falla. La clave de OpenAI va guardada como secreto y solo la ve esta función.	Cloud Scheduler, Cloud Tasks y GPT-4o
Lógica de generación	Todas las reglas de la fábrica, del plan del mes a la criba, viven aparte y sin tocar la base de datos ni OpenAI.	TypeScript
Base de datos y reglas	Guarda preguntas, perfiles, papeletas y registros de la fábrica, en Europa.	Firestore
Identidad y cuenta	Registro con correo o con Google. El borrado de cuenta corre en el servidor de la web, porque el navegador no puede borrar su propio perfil.	Firebase Authentication

---

Comunicación entre capas

El jugador entra con Firebase Authentication y recibe un pase firmado. Con ese pase el navegador llama directamente a las funciones del juego, que lo validan, leen y escriben en Firestore con permisos de administrador y devuelven solo lo necesario: la pregunta sin solución al pedir, y el resultado ya corregido al responder. El perfil propio el navegador lo lee de Firestore, siempre bajo las reglas, que solo le dejan ver el suyo. El servidor de la web pide el ranking a la función del ranking, y la tarjeta de un jugador que está lejos de la cabeza cuenta su puesto preguntando a Firestore directamente. La fábrica va por su lado: el calendario despierta la tarea de reparto, esta encola un tema por cada hueco, la cola los entrega de uno en uno a la función que habla con OpenAI, y lo aceptado se guarda de una vez junto con su registro.

Decisiones de diseño técnico

---

Librerías clave y su función

Librería	Para qué se usa exactamente	Versión
next	Fabrica las páginas de la web y dibuja la imagen de la tarjeta para redes.	^14.2.35
firebase-admin	Lee y escribe Firestore con permisos de administrador, en las funciones y en el servidor de la web.	^13.0.0 funciones · ^12.1.1 web
firebase-functions	Define todas las funciones del servidor, tanto las del juego como las de la fábrica.	^7.0.0
openai	Pide las tandas de candidatas y la revisión, siempre con respuesta en formato JSON.	^5.0.0
sharp	Tiñe el logo de tinta marrón en la imagen de la tarjeta y prepara las copias ligeras de imágenes y personajes.	^0.33.5

Soluciones particulares de desarrollo

Reto de programación	Solución en el código
Andar sobre un dibujo	El camino del perfil está trazado como una lista de puntos sobre la imagen original: una de 2400 × 1800 para ordenador y otra de 1200 × 3600 para móvil, que entra cuando la pantalla mide menos de 600 píxeles. Según el ancho de la pantalla, todo se escala y se suma la distancia de cada tramo, así que cualquier fracción del camino se convierte en un punto exacto. Ningún personaje se sale por los lados, porque se cuenta su ancho como tres cuartos de su alto.
Un personaje que anda sin dibujar el paso	Cada personaje es una sola imagen fija partida en tres capas: de la cintura arriba y cada mitad de las piernas. El código levanta una pierna y luego la otra, sube y baja el cuerpo, lo aplasta un poco al pisar, lo inclina hacia delante al andar y lo hace respirar parado. Las uniones se funden en vez de cortarse, para que capas, colas y espadas no se partan, y al pisar suelta un poco de polvo.
El mes en hora de España sin librerías	El código formatea la fecha con el formato de Canadá, que escribe año, mes y día en ese orden, y se queda con los siete primeros caracteres. Una línea de la propia plataforma, sin paquetes extra de fechas.
Todas las piezas de una sola ilustración	La barra, el libro, el atril, las placas y el pergamino del juego se recortan con un script de una ilustración de 2400 × 2000 y se guardan al 75 %, y las medidas de la hoja de estilos salen de esas mismas cifras. En móvil, el pergamino va en nueve partes: crece con el texto de la pregunta sin deformar las esquinas.

Puntos de lógica destacados

• Una sola tabla de rangos. Los puntos de cada rango salen del avatar que desbloquea, así que rango y avatar no pueden desajustarse, y el servidor tiene los mismos números.
• Paradas a la misma distancia. Las paradas del Camino al Trono van espaciadas igual aunque los puntos entre ellas crezcan, y el personaje se queda siempre entre el 20 % y el 80 % del tramo, para no pisar ninguna.
• Antorchas con un solo motor. Todas las llamas comparten un único bucle de animación, y si el sistema pide reducir el movimiento se quedan encendidas pero quietas.

---

Ejemplo real de código de implementación

Este es el momento en que el servidor entrega las preguntas.

      const expiresAt = Timestamp.fromMillis(Date.now() + TICKET_TTL_MS);
      const servedQuestions = docs.map((doc) => {
        const q = doc.data();
        // order[i] = posición original de la respuesta que se muestra en el hueco i
        const order = shuffled([0, 1, 2, 3]);
        const ticketRef = adminDb.collection(ANSWER_TICKETS).doc();
        batch.set(ticketRef, {
          uid,
          questionId: doc.id,
          correctIndex: order.indexOf(q.correctAnswerIndex),
          difficulty: q.difficulty ?? null,
          explanation: q.explanation ?? null,
          createdAt: FieldValue.serverTimestamp(),
          expiresAt,
        });
        return {
          id: doc.id,
          ticketId: ticketRef.id,
          question: q.question,
          answers: order.map((i) => q.answers[i]),
          difficulty: q.difficulty,
          category: q.category,
        };
      });

Es el juego de los cubiletes, pero honrado. El servidor baraja el orden de los cuatro huecos y, con esa misma baraja, coloca las respuestas en su nuevo sitio y calcula en qué hueco ha quedado la buena. Ese hueco, la explicación y el nivel se guardan en la papeleta junto con el jugador y la hora de caducidad. Al navegador solo viajan los cubiletes, nunca la bolita.

Controles de código incorporados

Control o prueba	Fallo o riesgo que evita
Revisión antes de desplegar	Cada vez que se despliegan las funciones pasan antes el revisor de código y la compilación de TypeScript en modo estricto. Si algo falla, no se despliega nada.
Pruebas de la fábrica sin red	Comprueban el calendario, el plan del mes, las preguntas casi iguales, las palabras de fuera, la forma de las respuestas, un tema entero y que lo guardado tenga justo los campos que lee el juego. La del calendario lo simula día a día durante dos años y exige 24 ejecuciones, todas el día 1. Las de preguntas y palabras se hacen contra el banco real: las preguntas casi iguales tienen que caer y 22 preguntas buenas nuevas tienen que pasar, así que si alguien cambia una regla y deja pasar lo que antes cazaba, la prueba falla.
Pruebas del juego en emuladores	Juegan partidas de verdad contra el código real de las funciones: las 199 preguntas fáciles sin una sola repetida hasta agotarlas, 150 seguidas en dificultad mixta, veinte pruebas gratis con más de 30 preguntas distintas entre todas, y una generación mensual completa después de la cual el juego sigue sin repetir.
Reglas de la base de datos	El perfil nace con puntos, contadores y racha a cero, con el rango de Aspirante y con el correo del propio pase. Después solo se tocan apodo, de 1 a 30 caracteres; frase, hasta 100; avatar; dificultad, solo entre las cuatro que existen; y las partidas jugadas, de una en una. Puntos, rango y racha quedan fuera del alcance del navegador.
Acceso sin pistas	Correo inexistente, contraseña mala o cuenta bloqueada dan el mismo mensaje, para no chivar qué cuentas existen. Después de entrar solo se vuelve a una página de la propia web, nunca a otra dirección, y el apodo va de 2 a 15 caracteres con al menos una letra o un número.
Corrección vigilada	La respuesta solo se acepta con una papeleta de texto de hasta 128 caracteres y sin barras y con un hueco del 0 al 3. Una papeleta de otro jugador o ya usada da no encontrada, y una caducada, ya no disponible.
Cabeceras de seguridad	La web solo carga scripts de su propio dominio y de Google, no se deja meter dentro de otra página, apaga cámara, micrófono, ubicación y pagos, y quita la cabecera que anuncia con qué está hecha.

Cómo y cuándo se revisa el programa

La batería del juego arranca los emuladores con el proyecto demo-finanzas y apunta OpenAI a un servidor falso en la propia máquina. Para eso crea dos ficheros de configuración temporales, se niega a empezar si ya existen para no pisar nada y al terminar los borra, junto con los registros de los emuladores. En Windows además cierra los procesos de emulador que haya abierto esa ejecución y deja en paz los que ya estaban.

---

Ejemplo real de un verificador

La prueba crea un jugador nuevo en los emuladores, pide una pregunta fácil y la responde dos veces con la misma papeleta. La primera respuesta tiene que aceptarse y la segunda tiene que volver como no encontrada, y el perfil tiene que acabar con una sola respuesta contada.

  test("cada pase puntúa una sola vez: responder dos veces el mismo da 404 y no suma", async () => {
    const j = await nuevoJugador("pase", "Fácil");
    const r = await fetch(url("questions", { count: "1", difficulty: "Fácil" }), { headers: { Authorization: `Bearer ${j.token}` } });
    const [p] = (await r.json()).questions;
    const responder = () => fetch(url("answerQuestion"), {
      method: "POST",
      headers: { Authorization: `Bearer ${j.token}`, "Content-Type": "application/json" },
      body: JSON.stringify({ ticketId: p.ticketId, selectedAnswerIndex: 0 }),
    });
    assert.equal((await responder()).status, 200);
    assert.equal((await responder()).status, 404);
    const doc = (await db.collection("users").doc(j.uid).get()).data();
    assert.equal(doc.totalQuestionsAnswered, 1);
  });

Es el rasca y gana que no se puede cobrar dos veces. Si la papeleta no se borrara al corregir, bastaría con acertar una pregunta y reenviar la misma respuesta en bucle para subir el ranking sin jugar. La prueba lo cierra por los dos lados: la segunda respuesta se rechaza y el contador del jugador no se mueve.