Base Admin Web

Proyecto base de Spring Boot con Metronic, autenticacion local y estructura modular lista para reutilizar en nuevos paneles administrativos.

Stack

• Spring Boot 4.0.6
• Java 25
• Spring Security
• Thymeleaf
• JPA / Hibernate
• H2 en archivo para desarrollo rapido
• PostgreSQL listo por perfil
• JWT para autenticacion API de escaneo
• Assets Metronic reutilizados desde base-web

Estructura

• base-admin-web-domain: entidades y repositorios
• base-admin-web-application: servicios y carga inicial
• base-admin-web-configuration: seguridad, JWT y perfiles
• base-admin-web-web: controladores y vistas Thymeleaf
• base-admin-web-jar: punto de entrada ejecutable

Usuarios iniciales

Administrador (panel web)

• Usuario: admin
• Password: Admin123*
• Rol: ROLE_ADMIN
• Acceso: login web en /login, dashboard y modulo de codigos pase

Variables de entorno:

• APP_ADMIN_USERNAME
• APP_ADMIN_PASSWORD
• APP_ADMIN_DISPLAY_NAME

Escaneador (API)

• Usuario: scanner
• Password: Scanner123*
• Rol: ROLE_SCANNER
• Acceso: solo login por API y escaneo de codigos pase

Variables de entorno:

• APP_SCANNER_USERNAME
• APP_SCANNER_PASSWORD
• APP_SCANNER_DISPLAY_NAME

Modulo de codigos pase

Panel administrativo para dar de alta y consultar codigos pase.

• URL: http://localhost:8080/admin/pass-codes
• Tambien accesible desde el boton Codigos pase en el dashboard
• Alta por nombre; el sistema genera un codigo aleatorio de 10 caracteres
• Vista con tabla de estatus, escaneo y fecha de creacion
• Modal Metronic para ver el QR de cada codigo
• Al cerrar el modal, la lista se actualiza automaticamente por si el codigo fue utilizado

Campos del codigo pase:

• Nombre
• Codigo aleatorio
• Fecha de creacion
• Estatus (ACTIVO / UTILIZADO)
• Indicador de escaneado
• Fecha de escaneo

API

Login escaner

POST /api/auth/login
Content-Type: application/json

{
  "username": "scanner",
  "password": "Scanner123*"
}

Respuesta exitosa:

{
  "success": true,
  "accessToken": "eyJhbG...",
  "tokenType": "Bearer",
  "expiresIn": 28800,
  "username": "scanner",
  "roles": ["ROLE_SCANNER"]
}

Solo usuarios con rol SCANNER pueden iniciar sesion por API. El usuario admin no puede autenticarse por este endpoint.

Escanear codigo pase

POST /api/pass-codes/scan
Authorization: Bearer eyJhbG...
Content-Type: application/json

{
  "code": "K7P2M9XQ4R"
}

Marca el codigo como escaneado y cambia su estatus a UTILIZADO.

Listado para el panel (requiere sesion admin)

GET /admin/pass-codes/list

Devuelve JSON con los codigos registrados. Se usa internamente para refrescar la tabla del panel.

Arranque local

Desde la raiz del proyecto:

./run-local.sh

El script:

• Detecta automaticamente Temurin/Java 25
• Compila todos los modulos del proyecto
• Arranca el modulo ejecutable base-admin-web-jar
• Muestra el perfil activo y la base de datos en uso

Si SPRING_PROFILES_ACTIVE incluye postgres, el script intenta levantar automaticamente el contenedor definido en docker-compose-postgres.local.yml antes de iniciar la aplicacion.

Tambien puedes ejecutar:

mvn test
mvn -pl base-admin-web-jar -am -DskipTests install
mvn -pl base-admin-web-jar spring-boot:run

Aplicacion:

• Login: http://localhost:8080/login
• Dashboard: http://localhost:8080/dashboard
• Codigos pase: http://localhost:8080/admin/pass-codes
• H2 Console: http://localhost:8080/h2-console

Perfiles

• dev: H2 en archivo (./data/h2/), consola H2 habilitada, datos persistentes entre reinicios
• prod: cache Thymeleaf y H2 console deshabilitada
• postgres: datasource PostgreSQL, datos persistentes en el servidor o volumen Docker
• test: H2 en memoria con create-drop, usado solo por mvn test

Con postgres, run-local.sh intenta arrancar Docker Compose automaticamente.

Ejemplo con PostgreSQL local:

SPRING_PROFILES_ACTIVE=postgres ./run-local.sh

Ejemplo con PostgreSQL remoto:

SPRING_PROFILES_ACTIVE=postgres \
SPRING_DATASOURCE_URL=jdbc:postgresql://TU_SERVIDOR:5432/base_admin_web \
SPRING_DATASOURCE_USERNAME=tu_usuario \
SPRING_DATASOURCE_PASSWORD=tu_password \
./run-local.sh

Variables utiles

Aplicacion

• SERVER_PORT
• SPRING_PROFILES_ACTIVE
• APP_TITLE

Base de datos

• SPRING_DATASOURCE_URL
• SPRING_DATASOURCE_USERNAME
• SPRING_DATASOURCE_PASSWORD
• SPRING_JPA_HIBERNATE_DDL_AUTO

JWT API

• APP_JWT_SECRET (minimo 32 caracteres)
• APP_JWT_EXPIRATION_HOURS

Seguridad

• Panel web: autenticacion por formulario con usuarios en base de datos
• API de escaneo: autenticacion stateless con JWT
• /admin/** y /dashboard: requieren rol ADMIN
• /api/pass-codes/scan: requiere rol SCANNER y token Bearer
• /api/auth/login: publico, pero solo emite token a usuarios SCANNER

Objetivo de esta base

Esta base deja resuelto lo minimo para arrancar nuevos proyectos internos:

• autenticacion local funcional para administradores
• autenticacion API para escaneo movil o externo
• layout inicial con Metronic
• dashboard simple
• modulo de codigos pase con QR y API de escaneo
• estructura modular limpia
• soporte rapido para H2 y PostgreSQL

El dashboard actual se mantiene deliberadamente sencillo para servir como punto de partida para futuras integraciones.