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 y haz login

https://console.cloud.google.com

🟩 Paso 2 — Crea un proyecto

Menú superior → “Seleccionar proyecto” → “Nuevo proyecto” → Elige un nombre para tu proyecto.

🟨 Paso 3 — Crea las credenciales OAuth

En el menú lateral:
APIs y Servicios → Credenciales → Crear Credenciales → ID de Cliente OAuth

Tipo de aplicación:
✔ Aplicación Web

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

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

Después te saldrá una ventana para descargarte las claves en formato json (hazlo para que no se pierdan)

Finalmente podrás ver la pantalla final (desde aquí no se puede acceder al secreto del cliente, solo puedes generar uno nuevo):

🟧 Paso 4 — 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 cada una en su lugar.

🟥 Paso 5 — Configura la pantalla de consentimiento OAuth

En el buscador escribe: OAuth consent screen o busca en el menu lateral la siguiente opción:

Configura los datos de tu proyecto seleccionando Información de la página:

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

🟪 Paso 6 — Publicar la app

Publica tu app accediendo a: (Este paso es muy importante para permitir acceder a cualquier correo)

---

🎉 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