Base-QR-Spring-Boot/README.md

# 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

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

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

Respuesta exitosa:

```json
{
  "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

```http
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)

```http
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:

```bash
./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:

```bash
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:

```bash
SPRING_PROFILES_ACTIVE=postgres ./run-local.sh
```

Ejemplo con PostgreSQL remoto:

```bash
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.