Estado base antes de integración Cognito.

Incluye admin web Spring Boot, API JWT para escáner y app Flutter qrscanner con login y escaneo de pases.
2026-06-09 15:51:44 -06:00
commit f8468350d5
2162 changed files with 433376 additions and 0 deletions
@@ -0,0 +1,221 @@
+# 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.