🏙️ UrbanExplorer: Guía Urbana Curada

UrbanExplorer es una plataforma web robusta, desarrollada como solución para entidades de promoción turística (DMOs). Su objetivo es ofrecer una guía de alta calidad sobre lugares de interés, garantizando la veracidad del contenido mediante moderación avanzada y enriqueciendo la experiencia del usuario con servicios externos en tiempo real.

---

🎯 Introducción

UrbanExplorer centraliza y automatiza la gestión de contenido urbano. Se enfoca en la confiabilidad, la seguridad de los datos y la eficiencia operativa, integrando tecnologías modernas para la detección de duplicados, autenticación de doble factor y monetización de contenido.

🎯 El Problema a Solucionar

Muchas DMOs enfrentan desafíos críticos:

• Recopilación Lenta: Procesos manuales ineficientes.
• Contenido Desactualizado: Información dispersa y difícil de mantener.
• Gestión de Sugerencias Caótica: Canales no estructurados (emails, redes sociales).
• Seguridad y Spam: Falta de control de acceso y validación de usuarios.
• Duplicidad: Registros redundantes que degradan la calidad.

UrbanExplorer resuelve esto con un ecosistema unificado, seguro y automatizado.

✨ Características Principales

🗺️ Exploración y Experiencia de Usuario

• Categorías Dinámicas: Filtrado por subcategorías, precio y valoración.
• Información en Tiempo Real: Integración con OpenWeatherMap API para mostrar el clima actual de cada distrito en la ficha del lugar.
• Interacciones Fluidas: Navegación asíncrona (AJAX) y animaciones de interfaz.

🔐 Seguridad Avanzada

• Roles y Permisos: Sistema robusto con roles ADMIN (acceso total) y USER.
• Autenticación de Doble Factor (2FA): Seguridad reforzada mediante el envío de tokens de 6 dígitos al correo electrónico (Gmail SMTP).
• Protección de Cuentas: Bloqueo temporal de usuarios tras 3 intentos fallidos de inicio de sesión.

💼 Monetización y API

• API RESTful: Exposición de endpoints (/api/lugares) para consumo por clientes externos (ej. portal "Lima Viajes").
• Pasarela de Pago Simulada: Flujo de "checkout" para que los dueños de negocios promocionen sus lugares, mejorando su posicionamiento en las búsquedas.

🛡️ Panel de Moderación Inteligente

• Detección de Duplicados: Algoritmos heurísticos (Levenshtein, Jaro-Winkler) para identificar similitudes entre sugerencias y lugares existentes.
• Gestión de Contenido: Flujos de aprobación, rechazo y vinculación de sugerencias.

📊 Panel de Estadísticas

• Dashboard Interactivo: Gráficos de barras, torta y líneas implementados con Chart.js.
• KPIs en Tiempo Real: Monitoreo de tasa de aprobación, lugares por distrito y actividad de la comunidad.

💻 Pila Tecnológica (Stack)

Capa	Tecnología	Descripción
Backend	Java 17 & Spring Boot 3	Núcleo de la aplicación.
	Spring Security	Gestión de autenticación, autorización y 2FA.
	Spring MVC & REST	Controladores web y API RESTful.
	JavaMailSender	Envío de correos electrónicos (SMTP).
	Dotenv (java-dotenv)	Gestión segura de variables de entorno.
Frontend	Thymeleaf	Motor de plantillas servidor.
	Bootstrap 5 & Icons	UI responsiva y componentes visuales.
	JavaScript (ES6+)	Lógica del cliente, AJAX y consumo de APIs.
	Chart.js	Visualización de datos estadísticos.
Datos	Spring Data JPA	Capa de persistencia y abstracción de BD.
	MySQL	Base de datos relacional.
Integración	OpenWeatherMap API	Datos meteorológicos en tiempo real.

🏗️ Arquitectura del Sistema

El siguiente diagrama ilustra el flujo de datos y la interacción entre los distintos actores, el núcleo de la aplicación y los servicios externos integrados.

graph TD
    subgraph "👥 Actores"
        User((Visitante))
        Admin((Administrador))
        ExtClient[Cliente API Externo]
    end

    subgraph "🏙️ UrbanExplorer (Spring Boot)"
        UI[Frontend Thymeleaf]
        Sec[Security & 2FA]
        Controllers[Controladores REST/Web]
        Services[Servicios de Negocio]
    end

    subgraph "☁️ Servicios & Datos"
        DB[(MySQL Database)]
        Gmail[Gmail SMTP]
        Weather[OpenWeatherMap API]
    end

    %% Relaciones
    User -->|Navega / Sugiere / Paga| UI
    Admin -->|Login / Modera| UI
    UI --> Sec
    ExtClient -->|Consume JSON| Controllers
    
    Sec -->|Verifica Credenciales| Services
    Controllers --> Services
    
    Services -->|Persiste Datos| DB
    Services -->|Envía Token 2FA| Gmail
    Services -->|Consulta Clima| Weather
    
    style UI fill:#e1f5fe,stroke:#01579b
    style Services fill:#fff9c4,stroke:#fbc02d
    style DB fill:#e8f5e9,stroke:#2e7d32

Loading

📁 Estructura del Proyecto

src/main/
  java/com/urbanexplorer/urbanexplorer/
    config/         # Configuración de Security, CORS, MVC y DataSeeder.
    controller/     # Controladores Web y REST (@RestController).
    dto/            # Objetos de Transferencia de Datos (API).
    model/          # Entidades JPA.
    repository/     # Interfaces de acceso a datos.
    service/        # Lógica de negocio (2FA, Duplicados, Email, Clima).
  resources/
    static/         # CSS, JS, Imágenes.
    templates/      # Vistas Thymeleaf.
    application.properties  # Configuración base (referencia a variables de entorno).
.env                # Variables secretas.

🧰 Requisitos Previos

• Java 17 (JDK 17)
• Maven 3.9+
• MySQL Server (corriendo en puerto 3306)
• Clave de API de OpenWeatherMap (Gratuita)
• Cuenta de Gmail con "Contraseña de Aplicación" habilitada (para SMTP)

📸 Galería de la Aplicación

🌏 Experiencia de Usuario (Frontend)

Página de Inicio (Hero)	Detalle de Lugar con Clima
Búsqueda y navegación visual	Integración con OpenWeatherMap y pagos

Formulario de Sugerencias	Listado por Categorías
Validación de datos y subida de contenido	Filtros dinámicos y valoración

🛡️ Panel de Administración (Backoffice)

Dashboard de Estadísticas	Moderación de Contenido
Gráficos con Chart.js y KPIs	Aprobación y detección de duplicados

⚙️ Configuración e Instalación

1. Clonar el repositorio

git clone https://github.com/Ferinjoque/urban-explorer.git
cd urban-explorer

---

2. Configurar Variables de Entorno (.env)

Crea un archivo llamado .env en la raíz del proyecto (al mismo nivel que pom.xml) y agrega tus credenciales. No debes compartir este archivo.

# Credenciales de Base de Datos
DB_USERNAME=root
DB_PASSWORD=tu_password_mysql

# Configuración de Correo (Gmail)
MAIL_USERNAME=tu_correo@gmail.com
MAIL_PASSWORD=tu_contraseña_de_aplicacion_gmail

# APIs Externas
OPENWEATHER_API_KEY=tu_api_key_de_openweathermap

---

3. Construir y Ejecutar

Para construir el proyecto:

mvn clean package

Para ejecutar la aplicación:

mvn spring-boot:run

O ejecutar el JAR generado:

java -jar target/urbanexplorer-0.0.1-SNAPSHOT.jar

Acceder a la aplicación:

http://localhost:8080/

---

🧭 Flujo de Uso

Visitante (Público)

• Explora lugares, filtra por categorías y consulta el clima en tiempo real.
• Puede usar la opción "Sugerir Lugar" (incluye validación de formulario).
• Accede al portal externo simulado: /cliente_externo.html.

Administrador

• Inicia sesión en /login.
• Completa el paso 2FA con el código recibido en su correo, ingresándolo en /verify-2fa.
• Accede al Dashboard en /admin/dashboard.
• Modera contenido: aprobar/rechazar sugerencias o gestionar duplicados.

Monetización

• En la ficha de un lugar, un usuario puede hacer clic en "Promocionar".
• Simula un pago.
• El lugar recibe un boost de visibilidad (aparece primero en los listados).

---

🔐 Seguridad Implementada

• Encriptación: Contraseñas hash con BCrypt.
• Protección CSRF & CORS: Configuración segura para la API.
• Variables de Entorno: Credenciales sensibles fuera del código fuente.
• Validación Robusta: En frontend (JS) y backend (Jakarta Validation).