yovi_es4a

La app dispone de una interfaz web para jugar al juego Y.

Se ofrecen dos modos de juego:

El tablero tiene tamaño variable, configurable por el usuario dentro de unos límites establecidos.

El usuario puede elegir quién empieza la partida, según el modo de juego.

El usuario podrá registrarse en la aplicación, o inciar sesión si ya tiene cuenta asociada.

Se proporcionará un API externo (documentado) para que los bots puedan usar el sistema.

El “motor” del juego estará en un módulo/servicio aparte (implementado en Rust), y la web lo llamará por HTTP mediante JSON (usando YEN).

Adecuación funcional: El motor debe garantizar el cumplimiento de reglas y la validación del estado de la partida, evitando acciones inválidas y guiando al usuario durante el juego.

Eficiencia de desempeño: Se busca respuesta ágil y sin “lag” en las operaciones principales, con un uso eficiente de recursos y soporte de concurrencia, apoyado en el motor en Rust y el despliegue en contenedores.

Compatibilidad / interoperabilidad: La comunicación entre subsistemas y con bots externos debe ser estable, clara y validada, basada en JSON con notación YEN y un API bien documentado.

Usabilidad: La web debe ser intuitiva y fácil de aprender, con una interfaz que indique turnos, opciones y restricciones, reduciendo errores del usuario.

Fiabilidad / disponibilidad: El sistema debe mantener estabilidad ante fallos habituales y ser observable/monitorizable para detectar caídas o degradaciones.

Seguridad: Se controlarán accesos (registro/login y API pública), validación de entradas y medidas de protección de credenciales (por ejemplo, cifrado/hasheado de contraseñas).

Mantenibilidad: El diseño modular por microservicios y la separación de responsabilidades deben permitir incorporar nuevas estrategias/reglas o cambios en el API minimizando el impacto en el resto del sistema.

Portabilidad: Al basarse en Docker, el sistema debe ser desplegable en distintos entornos con una instalación reproducible.

Jugador: Usa el sistema para registrarse o iniciar sesión, configurar partidas, jugar al juego Y desde la interfaz web y consultar resultados/estadísticas.

Bot: Sistema externo que interactúa con YOVI mediante una API, permitiendo automatizar partidas o realizar jugadas.

Administrador: Responsable de desplegar, supervisar y mantener el sistema.

YOVI: Sistema principal que ofrece la funcionalidad de juego y expone las capacidades necesarias tanto para usuarios finales como para integraciones externas.

Web Browser (Jugador): Cliente desde el que el usuario accede a la aplicación web.

Bot Externo: Cliente software que consume la API del sistema para interactuar con las partidas.

Servidor (Docker): Aloja los servicios backend y el motor del juego. Contiene:

webapp (React + Vite + TypeScript): Interfaz web donde los usuarios juegan

users (Node.js + Express): Gestiona usuarios, autenticación y partidas

gamey (Rust): Motor del juego con las reglas y lógica del Juego Y

GitHub Issues para tareas y bugs

Kanban para seguimiento visual

Pull Requests con revisión obligatoria

Rama master protegida

Arc42 para la documentación del proyecto

Draw.io para realizar los diagramas

Wiki para las actas de las reuniones

Tablero (Board): Estructura triangular de tamaño variable (N×N casillas). Las posiciones se representan mediante coordenadas baricéntricas (x, y, z) donde x + y + z = N - 1, lo que facilita el cálculo de distancias a los lados.

Partida (Game): Sesión de juego entre dos participantes (usuarios o bots). Contiene el estado del tablero, el turno actual, los jugadores y el historial de movimientos.

Movimiento (Move): Acción de colocar una pieza en una casilla libre. Se serializa en notación YEN para el intercambio entre servicios.

Notación YEN (Y Exchange Notation): Formato de serialización JSON inspirado en FEN (del ajedrez). Representa el estado completo de una partida (tablero, turno, jugadores) para su almacenamiento o transmisión entre webapp, users y gamey.

Notación YGN (Y Game Notation): Formato de registro de la secuencia de movimientos de una partida completa, análogo al PGN del ajedrez.

Usuario: Persona registrada en el sistema con credenciales, historial de partidas y estadísticas.

Bot: Agente automático que juega partidas consumiendo el API público. Puede usar distintas estrategias de decisión.

Registro y autenticación: Los usuarios se registran y autentican mediante correo electrónico y contraseña. El sistema implementa una verificación en dos pasos (2FA por email) para confirmar la identidad del usuario antes de dar acceso a su cuenta.

Almacenamiento seguro de contraseñas: Las contraseñas nunca se almacenan en texto plano. Se guardan en MongoDB como hashes criptográficos (usando algoritmos como bcrypt), de forma que incluso un acceso no autorizado a la base de datos no exponga las credenciales reales.

Validación de entradas: El servicio users valida todas las entradas recibidas (tanto de la webapp como de bots externos) para prevenir inyecciones y datos malformados.

Control de acceso a la API: El API público para bots expone únicamente las operaciones necesarias (consultar estado, enviar movimiento), con comprobaciones de permisos para impedir acceso a datos de otros usuarios.

Red interna de Docker: MongoDB no expone puertos públicos; solo es accesible desde la red interna de contenedores (docker network), reduciendo la superficie de ataque.

Protocolo: HTTP/REST en todos los intercambios.

Formato de datos: JSON en todos los mensajes, incluyendo la representación del estado del juego en notación YEN.

Sincronía: Las llamadas son síncronas (petición-respuesta). La webapp llama al servicio users, que a su vez llama a gamey cuando necesita delegar lógica de juego.

Documentación del API: El servicio users expone su API documentada con Swagger/OpenAPI, permitiendo que los desarrolladores de bots conozcan los endpoints disponibles, sus parámetros y los formatos de respuesta esperados.

Bot aleatorio: Elige una casilla válida aleatoria. Nivel de dificultad mínimo.

Bot MCTS (Monte Carlo Tree Search): Algoritmo probabilístico que simula miles de partidas aleatorias desde el estado actual para estimar estadísticamente la probabilidad de victoria de cada movimiento posible. Es el nivel de dificultad más alto. Se implementa con un límite de tiempo de respuesta para evitar bloqueos del contenedor.

Recolección de métricas: Prometheus actúa como el recolector central, haciendo scraping periódico del endpoint /metrics de los diferentes servicios instrumentados. Registra métricas de rendimiento como tiempos de respuesta, número de peticiones, errores HTTP y uso de recursos.

Visualización: Grafana proporciona tableros de control (dashboards) para monitorizar en tiempo real el estado de los servicios, facilitando la detección temprana de fallos o degradaciones de rendimiento. Los dashboards se aprovisionan automáticamente como código (como volúmenes de configuración).

Trazabilidad de logs: Los servicios generan logs estructurados que permiten correlacionar eventos entre webapp, users y gamey para diagnosticar problemas en flujos completos.

Tests unitarios: Cada servicio tiene su suite de tests unitarios independiente (npm test para webapp y users, cargo test para gamey). Se verifica la lógica de negocio de forma aislada con mocks de dependencias.

Tests de integración: Se prueba la comunicación entre servicios para verificar que los contratos del API se cumplen correctamente.

Tests end-to-end: La webapp incluye tests E2E (npm run test:e2e) que simulan la interacción completa de un usuario con el sistema a través del navegador.

Análisis estático (SonarCloud): Integrado en el pipeline de CI/CD, analiza cada pull request en busca de code smells, duplicidades, vulnerabilidades de seguridad y cobertura de tests. Se publica un Quality Gate público con el estado del proyecto.

Gestión de Tareas (Kanban): Se utiliza GitHub Projects con una metodología Kanban para visualizar el flujo de trabajo (To Do, In Progress, Done…​). Esto permite el seguimiento en tiempo real del estado de cada funcionalidad.

Seguimiento de Tareas (Issues): Cada nueva funcionalidad, error o mejora se documenta mediante Issues, que sirven como unidad básica de trabajo y permiten la trazabilidad de los requisitos hasta el código.

Flujo de Trabajo (Pull Requests): El código no se integra directamente en la rama principal (master, que está protegida). Se utilizan Pull Requests (PRs) para la revisión por parte de otros miembros del equipo, asegurando que el código cumpla con los estándares antes de ser fusionado.

Actas de reuniones (Wiki): Las reuniones semanales de equipo y las reuniones extraordinarias quedan registradas en la Wiki del repositorio de GitHub, garantizando trazabilidad de las decisiones tomadas.

Motor de Juego de Alto Rendimiento (Rust): El servicio gamey está desarrollado en Rust para garantizar la seguridad de memoria (sin garbage collector, sin carreras de datos) y un alto rendimiento en la evaluación del árbol de juego. Rust también ofrece versatilidad al poder ejecutarse tanto en modo servidor HTTP como en modo CLI para pruebas. La documentación del motor se genera automáticamente con cargo doc.

Backend de Gestión (Node.js/Express): El servicio users utiliza un entorno basado en eventos y JavaScript/TypeScript para gestionar la lógica de usuario de forma ágil y escalable. Node.js es especialmente apropiado para APIs REST con operaciones de I/O intensivas (acceso a MongoDB, llamadas a gamey).

Frontend Moderno (React + Vite + TypeScript): La interfaz de usuario (webapp) utiliza React para una gestión eficiente del estado de la UI, TypeScript para la seguridad de tipos en tiempo de compilación, y Vite como herramienta de construcción ultrarrápida en desarrollo.

Base de Datos Documental (MongoDB): La flexibilidad del esquema JSON/BSON facilita la evolución del modelo de datos sin migraciones complejas, y su integración nativa con el ecosistema JavaScript/TypeScript simplifica el desarrollo del servicio users.

Contenedorización (Docker + Docker Compose): Todos los servicios se empaquetan en imágenes Docker, garantizando la portabilidad y reproducibilidad del entorno en desarrollo, pruebas y producción.

Estado: Aceptada.

Contexto: Se requiere un sistema de persistencia para almacenar los datos de los usuarios, partidas y estadísticas del juego que sea flexible y compatible con el ecosistema tecnológico actual.

Alternativas consideradas:

Justificación:

Consecuencias: Se espera mayor velocidad de desarrollo al no depender de esquemas rígidos. Como contrapartida, se renuncia a la consistencia transaccional fuerte entre colecciones, lo que es aceptable dado el dominio del problema.

Estado: Reemplazada (por ADR 3).

Contexto: Necesidad de una herramienta para crear los diagramas técnicos de la documentación arc42.

Alternativas consideradas:

Justificación:

Consecuencias: Permite la generación automática de diagramas visuales a partir de relaciones definidas por código, aunque carece de flexibilidad en la disposición visual manual, lo que provocó dificultades al representar arquitecturas complejas.

Estado: Aceptada.

Contexto: Tras evaluar el uso de PlantUML en los primeros diagramas, se identificó la necesidad de una representación más libre, esquemática y visual de los componentes, especialmente para los diagramas de despliegue y contexto.

Alternativas consideradas:

Justificación:

Consecuencias: Aunque requiere algo más de tiempo manual para la creación y no permite generación automática, resulta más cómoda, comunicativa y accesible para todo el equipo. Se usa conjuntamente con PlantUML para los diagramas de secuencia (vista de ejecución), donde la generación desde código sigue siendo ventajosa.

Estado: Aceptada (impuesta por los requisitos del proyecto).

Contexto: La lógica del juego Y, incluyendo la validación de movimientos, la detección de victoria y la implementación de bots, requiere un alto rendimiento, especialmente para el algoritmo MCTS que simula miles de partidas.

Alternativas consideradas:

Justificación:

Consecuencias: La curva de aprendizaje de Rust es significativa (gestión de lifetimes, ownership), lo que supuso un riesgo de retraso inicial. Se mitigó empezando con implementaciones simples y evolucionando gradualmente hacia algoritmos más complejos.

Estado: Aceptada.

Contexto: El sistema necesita integrar tecnologías heterogéneas (React, Node.js, Rust) y permitir el desarrollo en paralelo por parte de los distintos miembros del equipo.

Alternativas consideradas:

Justificación:

Consecuencias: Aumenta la complejidad operacional (hay que gestionar múltiples servicios, redes Docker, configuraciones de entorno). Se mitiga mediante docker-compose.yml que define toda la topología en un solo fichero y un pipeline de CI/CD completamente automatizado.

Estado: Aceptada.

Contexto: El bot del juego debe ofrecer al menos dos niveles de dificultad. Se necesita una estrategia de alto nivel que proporcione un oponente desafiante para usuarios avanzados.

Alternativas consideradas:

Justificación:

Consecuencias: El algoritmo MCTS es computacionalmente intensivo y puede causar tiempos de respuesta elevados si no se limita. Se implementa un límite de tiempo (timeout) para garantizar que el servicio gamey siempre responde dentro de un umbral aceptable, devolviendo el mejor movimiento encontrado hasta ese momento.

Completitud funcional: Se cubren los requisitos de jugabilidad implementando las acciones propias del juego Y, competición contra un bot y contra otro usuario en local. SC8

Corrección funcional: Se contemplan las reglas de juego desde el motor, garantizando una validación precisa del estado de la partida en cada momento. Se guía al usuario a seguir correctamente el desarrollo de partida. SC1

Comportamiento en el tiempo: Se garantiza un tiempo de respuesta óptimo al utilizarse Rust en el motor del juego. Además de la implementación de una estrategia cuidada del algoritmo de respuesta.

Utilización de recursos: El despliegue mediante contenedores Docker permite una gestión eficiente de la memoria y la CPU para los tres subsistemas (webapp, users, gamey). SC4

Capacidad: Se limitan los tamaños de tablero dentro de un rango para que siga siendo jugable dentro de la configuración que el usuario escoja.

Facilidad para interoperar: El intercambio de información entre subsistemas se realiza estrictamente mediante mensajes JSON siguiendo la notación YEN, asegurando que el API sea compatible tanto con la WebApp como con bots externos.

Coexistencia: Los microservicios están clasificados en sus contenedores correspondientes y facilmente se levantan y conectan entre sí en el docker-compose.yml.

Inteligibilidad: Dispone de una interfaz clara e intuitiva diseñada con React para facilitar su uso a todo tipo de usuario. Se busca tener un aspecto actualizado.

Capacidad de aprendizaje: El juego sigue reglas sencillas con facilidad de aprendizaje. La dificultad está presente en aprender qué estrategia seguir.

Operabilidad: La propia interfaz te guía durante el juego mostrándote de quién es el turno, las casillas disponibles y opciones disponibles. SC2

Protección contra errores de usuario: Aquellas acciones que desencadenarían algún fallo, como por ejemplo jugar fuera de tu propio turno, están deshabilitadas, previendo una mala práctica del juego.

Participación del usuario: Se dispone de una interfaz interactiva con distintas funciones para que el usuario además de jugar al juego pueda registrar usuario y disponer de sus estadísticas.

Accesibilidad: Cualquier persona de habla hispana puede acceder al juego. No tiene soporte de idiomas. SC3 El uso de un DNS permite que los usuarios accedan a la aplicación mediante un nombre legible (yovies4a.duckdns.org) en lugar de una dirección IP técnica y difícil de recordar. SC7

Asistencia al usuario: Dispone de una ayuda para entender qué hace cada componente en cada caso, además de tooltips y mensajes descriptivos.

Autodescripción: Se busca dejar lo más claro posible el uso de cada herramienta ya sea con un texto descriptivo en botones o dibujos que indiquen claramente su finalidad.

Madurez: A lo largo de todo el proyecto se utiliza SonarCloud para mantener cierta calidad de código. Se han realizado pruebas unitarias y de integración para garantizar la estabilidad del sistema.

Disponibilidad: Se utilizan las herramientas Prometheus y Grafana para monitorizar el estado de los microservicios y detectar posibles caídas o problemas de rendimiento.

Confidencialidad: Se implementa un sistema de registro apoyado por una base de datos para almacenar a los usuarios, los cuales se autenticarán para acceder a sus cuentas.

Integridad: Se implementa un grado más de seguiridad cifrando las contraseñas de los usuarios, así nosotros tampoco contamos explicitamente con estas. SC5

No repudio: Se guarda en la base de datos la interacción del usuario con la aplicación junto con una serie de datos estadísticos, por lo que el correo asociado con la cuenta guarda un registro de actividad.

Modularidad: El proyecto está dividido en tres microservicios (gamey, users y webapp). A su vez, en cada uno se sigue una estructura con las resposabilidades bien definidas y una clara separación de capas. Así se garantiza que un mínimo cambio no provoca un efecto de cascada. SC6

Adaptabilidad: Al estar basado en Docker, el proyecto es independiente del sistema operativo, lo que facilita su despliegue en diferentes entornos.

Instalabilidad: Mediante scripts de npm y comandos de Cargo, se levanta el entorno al completo rápidamente, con todos los componentes ya configurados.