Secure User Management API 🛡️

API REST segura de nivel empresarial diseñada para la gestión avanzada de usuarios, autenticación y control de acceso basado en roles (RBAC), protegiendo endpoints de misión crítica mediante JSON Web Tokens (JWT).

---

🚀 Características Principales

• Gestión Avanzada de Usuarios (RBAC): Autenticación robusta y control de acceso con roles jerárquicos (ADMIN, USER, SUPPORT), asegurando que cada usuario acceda solo a los recursos permitidos.
• Seguridad y Protección Stateless: Filtros personalizados con Spring Security para validar y decodificar JWT en cada petición HTTP, garantizando comunicaciones seguras sin estado.
• Operaciones CRUD Completas: Registro, inicio de sesión, activación, desactivación (soft delete) y administración integral del ciclo de vida de los usuarios en la plataforma.
• Manejo Global de Excepciones: Respuestas estandarizadas y amigables ante errores, validaciones fallidas o problemas de seguridad a través de un @ControllerAdvice.
• Documentación Interactiva: Integración nativa con OpenAPI (Swagger UI) para la visualización, exploración y prueba de todos los endpoints directamente desde el navegador.

---

🛠️ Stack Tecnológico

Capa	Tecnología
Backend REST Core	Java 21, Spring Boot 3, Spring Web
Capa de Seguridad	Spring Security, JJWT (JSON Web Token)
Persistencia de Datos	Spring Data JPA, Hibernate, PostgreSQL 15
Pruebas y Utilidades	JUnit 5, Mockito, Lombok, Validation
Documentación API	Springdoc OpenAPI (Swagger UI)
Orquestación DevOps	Docker, Docker Compose, Maven

---

⚙️ Cómo ejecutar el proyecto (Modo Local)

La infraestructura de base de datos está contenerizada para garantizar un despliegue rápido y sin conflictos de configuración.

Prerrequisitos

1. Tener instalado Docker Desktop.
2. Tener instalado Java 21 en tu máquina anfitriona.

Paso 1: Levantar la Infraestructura Core

Abre una terminal en la raíz del proyecto y levanta el servicio de PostgreSQL utilizando el orquestador:

docker-compose up -d

Esto descargará la imagen de PostgreSQL 15 y levantará la base de datos secure_users_db en el puerto 5432.

Paso 2: Ejecutar la Aplicación Spring Boot

Inicia el servidor backend ejecutando el wrapper de Maven (no requiere instalación global de Maven):

En Windows (PowerShell):

.\mvnw spring-boot:run

En Linux / macOS:

./mvnw spring-boot:run

Paso 3: Explorar el Centro de Mando API

1. Abre tu navegador web y dirígete a: http://localhost:8080/swagger-ui/index.html
2. Puedes interactuar con la interfaz Swagger para registrar nuevos usuarios, obtener tokens JWT y probar endpoints protegidos.

---

🔐 Flujo de Autenticación Rápido

1. Registrar un nuevo usuario:

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Administrador",
    "lastName": "Principal",
    "email": "admin@example.com",
    "password": "Password123"
  }'

2. Iniciar Sesión (Generar Token):

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "Password123"
  }'

La API responderá con un token JWT firmado. Guárdalo para el siguiente paso.

3. Consumir Endpoint Protegido: Incluye el token obtenido en el encabezado Authorization para cualquier petición segura:

Authorization: Bearer <TU_TOKEN_JWT>

---

📐 Arquitectura del Sistema

graph TD
    A[Cliente REST / Swagger UI] -->|Petición HTTP + Token JWT| B(Filtro Spring Security)
    B -->|Token Válido| C{Controladores REST}
    B -->|Inválido / Sin Token| F[Error 401 / 403]
    C -->|DTOs| D[Capa de Servicios]
    D -->|Entidades JPA| E[(PostgreSQL 15)]
    E -->|Datos| D
    D -->|Respuestas| C
    C -->|JSON| A

Loading

---

📂 Estructura del Proyecto

• 📁 config/ - Configuraciones globales (Seguridad, CORS, Swagger OpenAPI).
• 📁 controller/ - Exposición de endpoints REST y manejo de peticiones HTTP.
• 📁 dto/ - Objetos de Transferencia de Datos (Request/Response).
• 📁 entity/ - Modelos de dominio mapeados a la base de datos relacional.
• 📁 exception/ - Control centralizado y manejo de excepciones globales (@ControllerAdvice).
• 📁 repository/ - Interfaces de persistencia utilizando Spring Data JPA.
• 📁 security/ - Lógica core de autenticación, filtros JWT y UserDetails.
• 📁 service/ - Lógica de negocio, validaciones y orquestación.

---

🚀 Roadmap y Futuras Mejoras

• Implementación de Refresh Tokens para mantener sesiones activas de forma segura.
• Flujo de Recuperación de Contraseña mediante envío asíncrono de correos electrónicos.
• Auditoría de Acciones (Logs) para trazabilidad en endpoints de administración.
• Dockerización del Backend para construir una red completa en Docker Compose.
• Pipelines de CI/CD para testing y despliegue automatizado.

---

👨‍💻 Autor

Brayan Jair Chavez Oscor Ingeniería de Software / Arquitectura Backend

Desarrollado como demostración técnica de buenas prácticas en arquitectura de software seguro y APIs empresariales.