Biblioteca Maxipet

01 Qué es

API en Spring Boot 3 sobre Java 17 para la plataforma corporativa de Maxipet. Es la migración de la aplicación original en Flask: mismo PostgreSQL, mismos usuarios, backend nuevo. Sirve a un SPA en React + Vite hosteado en Vercel y cubre gestión documental, KPIs y objetivos, quejas, acciones correctivas, alertas de seguridad, cuestionarios, bitácora y directorio.

• Contenido por categoría (documentos, manuales, cursos, lecciones, boletín, almacenes): subida, listado, borrado y comentarios en boletín y lecciones.
• KPIs y objetivos con alta y baja; quejas con evidencia, edición, solución adjunta y estadísticas.
• Acciones correctivas con actividades por folio, pendientes globales y cambio de estatus.
• Seguridad: alertas, material general, podcast, video y cuestionarios con una sola respuesta por usuario.
• Bitácora de auditoría de toda mutación, dashboard con contador de días y directorio de usuarios.
• Cuenta: 2FA por TOTP o por correo, avisos de inicio de sesión, sesiones activas y actividad propia.

02 La migración

La plataforma ya estaba en producción y había que modernizarla sin detener la operación ni tocar los datos. Flyway toma el control del esquema con migraciones versionadas y Hibernate solo valida: nunca modifica.

1. Flyway detecta que el esquema no está vacío y que no existe flyway_schema_history (baseline-on-migrate=true, baseline-version=1).
2. Crea la tabla con un registro de baseline marcado como V1 y no re-ejecuta V1: el esquema actual ya es V1.
3. Aplica V2 en adelante sobre el esquema existente; todas son idempotentes (IF NOT EXISTS, WHERE NOT EXISTS).
4. Hibernate hace validate. Si todo coincide, la app arranca.

03 Arquitectura

Cadena: Cloudflare Tunnel → Nginx (127.0.0.1:80) → JVM (127.0.0.1:8080). La app no necesita puerto público; cloudflared apunta su ingress a Nginx local y el túnel pone el transporte cifrado. Spring procesa los X-Forwarded-* con forward-headers-strategy=framework, así la IP real llega al rate-limit y la cookie Secure sabe que la petición fue HTTPS.

Dos perfiles: default para desarrollo (rate-limit apagado, secretos con fallback, errores detallados) y prod (rate-limit encendido, secretos obligatorios por entorno, errores mínimos, logs JSON). En prod, ProdSecretsValidator se niega a arrancar si JWT_SECRET o APP_ENCRYPTION_KEY siguen siendo los valores de desarrollo.

04 Puesta en marcha

Requisitos: Java 17, PostgreSQL 12+ (probado en 18) y, opcionalmente, Docker. Con Docker el contenedor corre como usuario no root y monta el volumen uploads.

> ./mvnw spring-boot:run              # dev; lee DATABASE_URL, DB_USERNAME y DB_PASSWORD del .env
> ./mvnw -DskipTests package && java -jar target/biblioteca-api-1.0.0.jar --spring.profiles.active=prod
> docker compose up -d --build        # api + db; usuario no root y volumen uploads
> docker compose logs -f api
> curl http://localhost:8080/actuator/health   # {"status":"UP"}

La aplicación no da de alta ningún usuario por su cuenta: contra una base vacía nadie puede entrar hasta insertar el primero a mano, una sola vez por instalación. A partir de ahí, el resto se crea desde Usuarios → Nuevo usuario.

> python3 -c "import bcrypt,getpass; print(bcrypt.hashpw(getpass.getpass().encode(), bcrypt.gensalt(12)).decode())"
> psql -U bibliotecario -d biblioteca_maxipet -c "INSERT INTO users (username, password_hash, role, full_name) VALUES (…, …, 'super_admin', …);"

05 Referencia de la API

Todo bajo /api/* exige JWT (Authorization: Bearer …) salvo login, verify-2fa, refresh, logout y /actuator/health. Los errores llegan como JSON: 400 con fields en validación o JSON malformado, 401, 403 por rol, 404 en rutas inexistentes y 429 por rate-limit.

06 Seguridad

Cada control existe por un escenario concreto: un token robado, una contraseña filtrada, un archivo malicioso o una lectura de la base de datos. La idea es que ninguno de ellos, por sí solo, alcance.

07 Producción

Nginx es la pieza crítica: sin X-Forwarded-Proto https la cookie de refresh sale sin Secure, y sin real_ip_header CF-Connecting-IP (aceptado solo desde los rangos de Cloudflare) el rate-limit vería la IP del túnel.

> upstream biblioteca_api { server 127.0.0.1:8080; }
> real_ip_header CF-Connecting-IP;                 # con set_real_ip_from para cada rango de Cloudflare
> client_max_body_size 50M;                        # subidas grandes
> proxy_set_header X-Forwarded-Proto https;        # la cookie Secure depende de esto
> location /_protected/ { internal; alias /srv/biblioteca-uploads/; }   # X-Accel-Redirect

• Archivos por X-Accel-Redirect: Spring valida sesión y rol y responde con el header y cuerpo vacío; Nginx sirve desde disco. El volumen uploads es un bind-mount (/srv/biblioteca-uploads, UID 1000) legible por ambos.
• Logs JSON en stdout con requestId; se respeta el X-Request-Id que mande el balanceador o se genera un UUID, y se devuelve en la respuesta para correlacionar tickets.
• En el borde de Cloudflare: rate-limit en /api/auth/login y /api/auth/refresh, WAF managed rules y Bot Fight Mode.
• Para 2+ instancias: RATE_LIMIT_BACKEND=redis; sin eso los buckets son por proceso.

> curl https://app.<dominio>/actuator/health                       # {"status":"UP"}
> curl -i -X POST https://app.<dominio>/api/auth/login -H "Content-Type: application/json" -d '{"username":"…","password":"…"}'
> # → Set-Cookie: refreshToken=…; HttpOnly; Secure; SameSite=None; Path=/api/auth
> journalctl -u biblioteca-api -f --output=cat | jq .            # logs JSON con requestId
> ./mvnw test                                                    # 18 tests de cifrado y rotación, < 3 s

08 Base de datos

La bitácora se escribe en su propia transacción (REQUIRES_NEW): si falla el insert no rompe la operación, pero se registra como ERROR para que un hueco en la auditoría sí dispare una alerta.

> SELECT version, description, installed_on, success FROM flyway_schema_history ORDER BY installed_rank;