Deck of Cards

Proyecto completo con backend en FastAPI + MongoDB, frontend en React + Vite, contenedores Docker, autenticación por email y Google OAuth 2.0, y sistema de cálculo DoC-MF / DoC-IT2MF.

Incluye:

• Backend en FastAPI + MongoDB
• Frontend en Vite + React
• Contenedores Docker para todo el proyecto
• Sistema de historial por usuario
• Login normal + Login con Google

---

📸 Capturas de Pantalla

🛠️ Proceso de Modelado (3 Pasos)

El núcleo de la aplicación guía al experto a través de tres fases intuitivas para transformar cartas físicas en modelos matemáticos.

Paso 1: Definición de la Escala Base

Paso 2: Modelado Difuso Paso 2: Definición de Subescalas e Intervalos

Paso 3: Visualización de la Función Final

📂 Historial

Listado del Historial de Modelos Vista de Detalle de un Modelo Guardado

🔐 Acceso a la Plataforma

Login

Registro

---

⚡ 0. ¿En qué consiste?

Deck of Cards es una herramienta completa diseñada para construir, validar y evaluar funciones de pertenencia difusas mediante el método Deck of Cards (DoC), tanto en su versión T1MF (tipo-1) como IT2MF (tipo-2 intervalar).

El sistema combina un backend robusto en FastAPI + MongoDB, un frontend moderno en React + Vite, autenticación por email y Google OAuth 2.0, y un sistema de historial por usuario para guardar y recuperar trabajos anteriores.

---

◻️ Objetivos del proyecto

• Digitalizar el método Deck of Cards, permitiendo calcular funciones de valor y funciones de pertenencia de forma rápida, guiada y sin errores.
• Facilitar la creación de modelos difusos para toma de decisiones, análisis multicriterio y sistemas expertos.
• Ofrecer validación automática de núcleos, soportes y nodos para evitar inconsistencias matemáticas.
• Permitir trabajar tanto con funciones T1MF como IT2MF, incluyendo intervalos en cartas blancas.
• Proveer una API modular, clara y reutilizable para estudiantes, investigadores y desarrolladores.
• Guardar el trabajo del usuario mediante un sistema de historial asociado a su cuenta.

---

◻️ ¿En qué puede ayudar a la gente?

Este proyecto es especialmente útil para:

• Estudiantes que necesiten aprender o aplicar lógica difusa y métodos de decisión.
• Investigadores que requieran generar funciones de pertenencia de forma precisa y reproducible.
• Profesionales que trabajen en:
  • análisis multicriterio (MCDA)
  • sistemas expertos
  • inteligencia artificial explicable
  • sistemas de recomendación
• Desarrolladores que quieran integrar cálculos DoC-MF o IT2MF en sus propias aplicaciones.

Note

El sistema automatiza cálculos que normalmente se realizan a mano, reduce errores y permite visualizar resultados de forma inmediata.

---

◼️ ¿Cómo se usa?

1. El usuario puede (o no) iniciar sesión (email o Google OAuth).
2. Desde el frontend puede:
   • Crear niveles y cartas blancas
   • Calcular funciones de valor DoC
   • Validar funciones T1MF
   • Construir funciones T1MF e IT2MF completas
   • Evaluar puntos dentro de una función
3. Cada operación puede guardarse en el historial personal del usuario.
4. El backend expone endpoints claros y modulares, permitiendo integrar el sistema en otros proyectos o automatizar cálculos.

---

🚀 1. Requisitos previos

Antes de empezar, necesitas:

• Docker para correr el proyecto
• Cuenta de Google para crear credenciales OAuth
• Git para clonar el repositorio

---

📦 2. Instalación y ejecución del proyecto

Con una terminal clona el repositorio o descarga el contenido y guárdalo en una carpeta local:

git clone https://github.com/AlexisLopez-Dev/deck-of-cards.git
cd deck-of-cards

Situado en la carpeta adecuada levanta los contenedores del proyecto:

docker compose up --build

Important

Esto iniciará:

• Backend (python) → http://localhost:8000
• Frontend (react) → http://localhost:5173
• Base de Datos (mongodb) → puerto 27017

Note

Nota para desarrolladores: Gracias a Docker, no necesitas instalar nada localmente para que la app funcione. Sin embargo, para que tu editor de código reconozca las librerías, tenga autocompletado y no muestre errores de importación, te recomendamos entrar a las carpetas y descargar las dependencias en tu máquina local:

cd frontend && npm install
cd ../backend && pip install -r requirements.txt

---

🔌 3. Endpoints principales del proyecto

A continuación se resumen los endpoints más importantes del backend, organizados por funcionalidad.

Resumen de endpoints

Módulo	Método	Endpoint	¿Qué hace?
Auth	POST	/api/auth/register	Registra un nuevo usuario y devuelve token + user_id.
	POST	/api/auth/login	Inicia sesión con email y contraseña.
	POST	/api/auth/logout/{user_id}	Cierra sesión y elimina el token del usuario.
	GET	/api/auth/me	Devuelve los datos del usuario autenticado.
Google OAuth	GET	/api/auth/google/login	Redirige a Google para iniciar sesión.
	GET	/api/auth/google/callback	Recibe el código de Google y genera el token de sesión.
DoC – Función de valor	POST	/api/criteria/doc/value-function	Calcula la función de valor DoC a partir de niveles y cartas blancas.
	POST	/api/criteria/doc/value-function/points	Devuelve los puntos (x,y) de la función de valor.
T1MF – Validación	POST	/api/criteria/doc-mf/validate-simple	Valida núcleo y soporte (sin nodos).
	POST	/api/criteria/doc-mf/validate	Valida niveles completos: núcleo, soporte y nodos.
T1MF – Construcción y evaluación	POST	/api/criteria/doc-mf/build	Construye la función de pertenencia DoC-MF.
	POST	/api/criteria/doc-mf/evaluate	Evalúa un punto x dentro de una función DoC-MF.
IT2MF – Construcción	POST	/api/criteria/doc-it2mf/build	Construye funciones IT2MF (lower y upper).
Historial	POST	/api/history/add	Guarda un elemento en el historial del usuario.
	DELETE	/api/history/delete/{history_item_id}	Elimina un elemento del historial.

---

📚 4. Estructura del proyecto

deck-of-cards/
│
├── backend/        → API FastAPI + OAuth + MongoDB
│   ├── routers/
│   ├── models/
│   ├── utils/
│   ├── .env            → !!!
│   └── main.py
│
├── frontend/       → Vite + React
│   ├── src/
│   ├── .env            → !!!
│   └── ...
│
├── docker-compose.yaml
└── README.md

---

🔐 5. Configuración de los archivos .env

El frontend necesita un archivo .env para especificar el puerto del backend

📍 Este archivo debe estar dentro de la carpeta frontend/, así:

deck-of-cards/
│
├── frontend/ 
│   ├── src/
│   ├── .env   ← AQUÍ
│   └── ...

Contenido obligatorio del .env:

VITE_API_URL=http://localhost:8000/api

Por otro lado,

El backend necesita un archivo .env para funcionar correctamente, especialmente para el login con Google.

📍 Este archivo debe estar dentro de la carpeta backend/, así:

deck-of-cards/
│
├── backend/
│   ├── .env   ← AQUÍ
│   ├── main.py
│   ├── routers/
│   └── ...

Contenido obligatorio del .env:

GOOGLE_CLIENT_ID=tu_client_id_de_google      //id del cliente, debe ser el mismo del proyecto de google cloud.
GOOGLE_CLIENT_SECRET=tu_client_secret_de_google    //secreto del cliente, debe de copiarse del proyecto de google cloud cuando se crea.
GOOGLE_REDIRECT_URI=http://localhost:8000/api/auth/google/callback    //url de redirección, debe ser la misma que en el proyecto de google cloud.
SECRET_KEY=superclaveultrasecreta123      //para codificación de los tokens (puedes poner cualquier texto o dejar el ejemplo que te doy).

Warning

No compartas la clave secreta del cliente.

Un ejemplo de página de donde sacar las tres primeras claves:

---

🔑 6. Cómo crear el proyecto con su GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET

Para activar el login con Google, debes crear credenciales OAuth 2.0. Para ello sigue estos pasos:

🟦 Paso 1 — Entra en Google Cloud Console

https://console.cloud.google.com

🟩 Paso 2 — Crea un proyecto

Menú superior → “Seleccionar proyecto” → “Nuevo proyecto”.

🟧 Paso 3 — Configura la pantalla de consentimiento OAuth

En el buscador escribe: OAuth consent screen ó ve a la página que se muestra en la captura superior.

Selecciona Información de la página:

→ Rellena los datos necesarios (no hace falta poner un dominio si lo tienes en local) → Guardar

🟨 Paso 4 — Crea las credenciales OAuth

Menú lateral:
APIs & Services → Credentials → Create Credentials → OAuth Client ID

Tipo de aplicación:
✔ Web application

Añade en Orígenes autorizados de javascript: http://localhost:8000

Añade este Redirect URI obligatorio: http://localhost:8000/api/auth/google/callback

🟥 Paso 5 — Copia tus claves

Google te mostrará:

• Client ID
• Client Secret

Pégalos en tu .env dentro de backend/. Asegúrate de que las copias correctamente.

---

🎉 7. Listo para usar

Con esto, ya puedes:

• Clonar el proyecto
• Crear sus credenciales de Google
• Configurar el .env
• Levantar el sistema con Docker
• Usar login normal y login con Google

Y... ¡Proyecto listo para ejecutarse en local!

👥 Autores y Equipo

Este proyecto es fruto de la colaboración académica con la Universidad de Jaén.

Rol	Desarrollador	GitHub
Frontend	Alexis López Moral	@AlexisLopez-Dev
Backend	Mireya Cueto Garrido	@MireyaCueto

🎓 Dirección y Tutorización

• Director del proyecto: Luis Martínez López

---

Realizado con ❤️ en la Universidad de Jaén