GET /api/materials?tipus=LLIBRE&page=0&size=20 HTTP/1.1
Host: bibliotech.nexussoftware.com
Accept: application/json
User-Agent: curl/8.5.0

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 283

{"content":[{"isbn":"978-0000000001","titol":"Java Eficac","tipus":"LLIBRE"}],
 "page":{"size":20,"number":0,"totalElements":3,"totalPages":1}}

@SpringBootApplication
public class BiblioTechApplication {
    public static void main(String[] args) {
        SpringApplication.run(BiblioTechApplication.class, args);
    }
}

// ServidorCataleg, modul 9: el vas escriure tu, sencer
public void atendre(Socket client) throws IOException {
    try (var entrada = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var sortida = new PrintWriter(client.getOutputStream(), true)) {

        String peticio = entrada.readLine();           // "CERCAR 978-0000000001"
        String[] parts = peticio.split(" ", 2);        // analisi del protocol

        switch (parts[0]) {                            // encaminament
            case "CERCAR" -> {
                Optional<Material> m = cataleg.perIsbn(parts[1]);
                if (m.isPresent()) {
                    sortida.println("OK " + serialitzar(m.get()));  // serialitzacio
                } else {
                    sortida.println("ERROR 404 No trobat");         // codi d'error
                }
            }
            case "LLISTAR" -> sortida.println("OK " + serialitzar(cataleg.tots()));
            default -> sortida.println("ERROR 400 Ordre desconeguda");
        }
    }
}

@RestController
@RequestMapping("/api/materials")
public class CatalegController {

    private final ConsultarCataleg cataleg;

    @GetMapping("/{isbn}")
    public MaterialResponse perIsbn(@PathVariable Isbn isbn) {
        return cataleg.perIsbn(isbn)
                .map(MaterialResponse::desDe)
                .orElseThrow(() -> new MaterialNoTrobatException(isbn));
    }
}

POST /api/prestecs HTTP/1.1
Idempotency-Key: 3f2504e0-4f89-11d3-9a0c-0305e82c3301
Content-Type: application/json

{"isbn":"978-0000000001","idEmpleat":1,"dies":15}

# Opcio A: subrecurs que representa el fet. La preferida.
POST /api/prestecs/42/devolucio

# Opcio B: PATCH sobre l'estat
PATCH /api/prestecs/42
{"estat": "RETORNAT"}

# Opcio C: verb al cami. Pragmatica, i acceptable si es fa servir amb moderacio.
POST /api/prestecs/42/retornar

package com.nexussoftware.bibliotech.web.cataleg;

@RestController                              // = @Controller + @ResponseBody
@RequestMapping("/api/materials")            // prefix comu de tots els metodes
public class CatalegController {

    private final ConsultarCataleg cataleg;
    private final GestionarCataleg gestio;

    public CatalegController(ConsultarCataleg cataleg, GestionarCataleg gestio) {
        this.cataleg = cataleg;
        this.gestio = gestio;
    }

    @GetMapping
    public PageResponse<MaterialResponse> llistar(@Valid CriteriMaterialsRequest criteri,
                                                  Pageable paginacio) { … }

    @GetMapping("/{isbn}")
    public MaterialResponse perIsbn(@PathVariable Isbn isbn) { … }

    @PostMapping
    public ResponseEntity<MaterialResponse> crear(@Valid @RequestBody CrearMaterialRequest peticio) { … }

    @PutMapping("/{isbn}")
    public MaterialResponse reemplacar(@PathVariable Isbn isbn,
                                       @Valid @RequestBody ActualitzarMaterialRequest peticio) { … }

    @PatchMapping("/{isbn}/unitats")
    public MaterialResponse ajustarUnitats(@PathVariable Isbn isbn,
                                           @Valid @RequestBody AjustUnitatsRequest peticio) { … }

    @DeleteMapping("/{isbn}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void eliminar(@PathVariable Isbn isbn) { … }
}

@GetMapping(value = "/{isbn}", produces = MediaType.APPLICATION_JSON_VALUE)
@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
@GetMapping(value = "/{isbn}", produces = "text/csv")          // negociacio de contingut
@GetMapping(params = "format=resum")                           // segons parametre
@GetMapping(headers = "X-Api-Version=2")                       // segons capcalera

@GetMapping("/{isbn}/prestecs")
public List<PrestecResponse> historial(

        // Part del cami: identifica el recurs
        @PathVariable Isbn isbn,

        // Parametre de consulta obligatori
        @RequestParam EstatPrestec estat,

        // Opcional amb valor per defecte
        @RequestParam(defaultValue = "10") int limit,

        // Opcional de debo: Optional (10-04)
        @RequestParam Optional<LocalDate> desDe,

        // Nom diferent del del parametre Java
        @RequestParam(name = "ordenar_per", defaultValue = "DATA") CriteriOrdre ordre,

        // Repetible: ?etiqueta=java&etiqueta=disseny
        @RequestParam(required = false) List<String> etiqueta,

        // Capcalera
        @RequestHeader(value = "Accept-Language", defaultValue = "ca") Locale idioma) { … }

@PostMapping
public ResponseEntity<PrestecResponse> crear(@Valid @RequestBody CrearPrestecRequest peticio) { … }

@Component
public class ConvertidorIsbn implements Converter<String, Isbn> {

    @Override
    public Isbn convert(String text) {
        try {
            return Isbn.de(text);
        } catch (IsbnInvalidException e) {
            // IllegalArgumentException → Spring ho tradueix a 400, no a 500
            throw new IllegalArgumentException("ISBN invalid: " + text, e);
        }
    }
}

@GetMapping("/{isbn}")
public MaterialResponse perIsbn(@PathVariable Isbn isbn) { … }    // 200 + JSON

@PostMapping
public ResponseEntity<PrestecResponse> crear(@Valid @RequestBody CrearPrestecRequest peticio) {
    Prestec creat = gestor.prestar(peticio.isbn(), peticio.idEmpleat(), peticio.dies());

    URI ubicacio = ServletUriComponentsBuilder
            .fromCurrentRequest()          // http://host/api/prestecs
            .path("/{id}")
            .buildAndExpand(creat.getId())
            .toUri();                      // http://host/api/prestecs/42

    return ResponseEntity.created(ubicacio).body(PrestecResponse.desDe(creat));
}

@PutMapping("/{isbn}")
public ResponseEntity<MaterialResponse> reemplacar(@PathVariable Isbn isbn,
                                                   @Valid @RequestBody ActualitzarMaterialRequest p) {
    ResultatActualitzacio resultat = gestio.crearOActualitzar(isbn, p);

    return resultat.haEstatCreat()
            ? ResponseEntity.status(HttpStatus.CREATED).body(MaterialResponse.desDe(resultat.material()))
            : ResponseEntity.ok(MaterialResponse.desDe(resultat.material()));
}

@GetMapping("/{isbn}")
public ResponseEntity<MaterialResponse> perIsbn(@PathVariable Isbn isbn) {
    Material material = cataleg.perIsbn(isbn).orElseThrow(() -> new MaterialNoTrobatException(isbn));

    return ResponseEntity.ok()
            .eTag("\"" + material.getVersion() + "\"")     // el @Version de JPA com a ETag
            .cacheControl(CacheControl.maxAge(5, TimeUnit.MINUTES).cachePublic())
            .body(MaterialResponse.desDe(material));
}

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)      // 204
public void cancellar(@PathVariable Long id) { reserves.cancellar(id); }

package com.nexussoftware.bibliotech.web.prestecs;

@Schema(description = "Informacio d'un prestec")             // documentacio OpenAPI
public record PrestecResponse(

        @Schema(example = "42") Long id,
        @Schema(example = "978-0000000001") String isbn,
        @Schema(example = "Java Eficac") String titolMaterial,
        @Schema(example = "Marta Ruiz") String nomEmpleat,
        LocalDate dataPrestec,
        LocalDate dataVenciment,

        @Schema(description = "Nulla si el material continua prestat")
        LocalDate dataDevolucio,

        @Schema(example = "ACTIU") String estat,

        @Schema(description = "Negatiu si esta vencut", example = "5")
        long diesRestants,

        @Schema(example = "2.50") BigDecimal multaAcumulada) {

    public static PrestecResponse desDe(Prestec p, LocalDate avui) {
        return new PrestecResponse(
                p.getId(),
                p.getIsbn().valor(),
                p.titolDelMaterial(),
                p.nomDeLempleat(),
                p.getDataPrestec(),
                p.getDataVenciment(),
                p.getDataDevolucio().orElse(null),       // JSON no te Optional
                p.getEstat().name(),
                ChronoUnit.DAYS.between(avui, p.getDataVenciment()),
                p.multaAcumulada(avui).quantitat());
    }
}

public record CrearPrestecRequest(

        @NotBlank(message = "L'ISBN es obligatori")
        @IsbnValid
        @Schema(example = "978-0000000001")
        String isbn,

        @NotNull(message = "L'identificador de l'empleat es obligatori")
        @Positive
        Long idEmpleat,

        @Positive @Max(value = 90, message = "La durada maxima es de 90 dies")
        @Schema(description = "Dies de prestec. Si s'omet, l'estandard del tipus de material")
        Integer dies) {
}

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

@PostMapping
public ResponseEntity<PrestecResponse> crear(@Valid @RequestBody CrearPrestecRequest peticio) {
    // Si arriba aqui, la peticio es sintacticament valida.
    // Si no, Spring ja ha llancat MethodArgumentNotValidException.
}

@RestController
@Validated                                   // habilita la validacio de parametres solts
@RequestMapping("/api/materials")
public class CatalegController {

    @GetMapping
    public List<MaterialResponse> llistar(
            @RequestParam @Size(min = 2, message = "Almenys 2 caracters") String titol,
            @RequestParam @Max(100) int limit) { … }
}

@RangDatesValid          // validador propi: desDe <= finsA
public record ConsultaMultesRequest(
        @NotNull @PastOrPresent LocalDate desDe,
        @NotNull @PastOrPresent LocalDate finsA,
        Long idEmpleat) {
}

package com.nexussoftware.bibliotech.web.validacio;

@Documented
@Constraint(validatedBy = ValidadorIsbn.class)
@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.RECORD_COMPONENT})
@Retention(RetentionPolicy.RUNTIME)
public @interface IsbnValid {

    String message() default "ISBN-13 invalid: revisa el format i el digit de control";

    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};

    /** Si es true, accepta l'ISBN amb guions i espais. */
    boolean permetreSeparadors() default true;
}

public class ValidadorIsbn implements ConstraintValidator<IsbnValid, String> {

    private static final Pattern AMB_SEPARADORS = Pattern.compile("^97[89][- ]?\\d{1,5}[- ]?\\d+[- ]?\\d+[- ]?\\d$");
    private static final Pattern SENSE_SEPARADORS = Pattern.compile("^97[89]\\d{10}$");

    private boolean permetreSeparadors;

    @Override
    public void initialize(IsbnValid anotacio) {
        this.permetreSeparadors = anotacio.permetreSeparadors();
    }

    @Override
    public boolean isValid(String valor, ConstraintValidatorContext context) {
        // Un valor nul es considera valid: l'obligatorietat la imposa @NotNull.
        // Separar responsabilitats entre validadors es el correcte.
        if (valor == null) return true;

        String normalitzat = permetreSeparadors ? valor.replaceAll("[- ]", "") : valor;

        if (!SENSE_SEPARADORS.matcher(normalitzat).matches()) {
            missatge(context, "L'ISBN ha de comencar per 978 o 979 i tenir 13 digits");
            return false;
        }
        if (!digitDeControlCorrecte(normalitzat)) {
            missatge(context, "El digit de control de l'ISBN no es correcte");
            return false;
        }
        return true;
    }

    /**
     * Algoritme oficial de l'ISBN-13: es multipliquen els 12 primers digits
     * alternant 1 i 3, se sumen, i el digit de control es el que falta
     * per al seguent multiple de 10.
     */
    private boolean digitDeControlCorrecte(String isbn) {
        int suma = 0;
        for (int i = 0; i < 12; i++) {
            int digit = isbn.charAt(i) - '0';
            suma += (i % 2 == 0) ? digit : digit * 3;
        }
        int control = (10 - (suma % 10)) % 10;
        return control == (isbn.charAt(12) - '0');
    }

    /** Substitueix el missatge generic per un d'especific de la fallada concreta. */
    private void missatge(ConstraintValidatorContext context, String text) {
        context.disableDefaultConstraintViolation();
        context.buildConstraintViolationWithTemplate(text).addConstraintViolation();
    }
}

{
  "type": "https://bibliotech.nexussoftware.com/errors/limit-prestecs",
  "title": "Limit de prestecs excedit",
  "status": 409,
  "detail": "L'empleat Diego Alonso ja te 3 prestecs actius (maxim: 3).",
  "instance": "/api/prestecs",
  "timestamp": "2026-08-05T10:23:45Z",
  "traceId": "a7f3e91c4b2d",
  "prestecsActius": [12, 27, 38]
}

spring:
  mvc:
    problemdetails:
      enabled: true      # les excepcions estandard de Spring ja surten en format RFC 7807

package com.nexussoftware.bibliotech.web.error;

@RestControllerAdvice
public class GestorGlobalErrors {

    private static final Logger log = LoggerFactory.getLogger(GestorGlobalErrors.class);
    private static final String BASE_TIPUS = "https://bibliotech.nexussoftware.com/errors/";

    // ---------- 404 ----------
    @ExceptionHandler({MaterialNoTrobatException.class,
                       PrestecNoTrobatException.class,
                       EmpleatNoTrobatException.class})
    public ProblemDetail noTrobat(RecursNoTrobatException e, HttpServletRequest peticio) {
        log.info("Recurs no trobat: {}", e.getMessage());          // INFO: no es una fallada del sistema
        return problema(HttpStatus.NOT_FOUND, "recurs-no-trobat",
                        "Recurs no trobat", e.getMessage(), peticio);
    }

    // ---------- 409: regles de negoci ----------
    @ExceptionHandler(LimitPrestecsExceditException.class)
    public ProblemDetail limitExcedit(LimitPrestecsExceditException e, HttpServletRequest p) {
        ProblemDetail detall = problema(HttpStatus.CONFLICT, "limit-prestecs",
                "Limit de prestecs excedit", e.getMessage(), p);
        detall.setProperty("prestecsActius", e.getIdsPrestecsActius());
        detall.setProperty("maximPermes", e.getMaxim());
        return detall;
    }

    @ExceptionHandler(MaterialNoDisponibleException.class)
    public ProblemDetail noDisponible(MaterialNoDisponibleException e, HttpServletRequest p) {
        ProblemDetail detall = problema(HttpStatus.CONFLICT, "material-no-disponible",
                "Material no disponible", e.getMessage(), p);
        e.getDataPrevistaDisponibilitat()
         .ifPresent(f -> detall.setProperty("disponiblePrevisiblementEl", f.toString()));
        return detall;
    }

    // ---------- 409: conflicte de concurrencia (el @Version d'11-03) ----------
    @ExceptionHandler(ObjectOptimisticLockingFailureException.class)
    public ProblemDetail conflicteDeVersio(ObjectOptimisticLockingFailureException e,
                                           HttpServletRequest p) {
        log.warn("Conflicte de bloqueig optimista a {}", p.getRequestURI());
        return problema(HttpStatus.CONFLICT, "conflicte-concurrencia",
                "Conflicte de concurrencia",
                "Un altre usuari ha modificat aquest recurs mentre l'editaves. Recarrega'l i reintenta.", p);
    }

    // ---------- 400: validacio del cos ----------
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail validacio(MethodArgumentNotValidException e, HttpServletRequest p) {
        List<ErrorCamp> errors = e.getBindingResult().getFieldErrors().stream()
                .map(f -> new ErrorCamp(f.getField(), f.getDefaultMessage(), f.getRejectedValue()))
                .toList();

        ProblemDetail detall = problema(HttpStatus.BAD_REQUEST, "validacio",
                "Error de validacio",
                "La peticio conte %d camp(s) invalid(s).".formatted(errors.size()), p);
        detall.setProperty("errors", errors);        // AIXO es el que fa util un 400
        return detall;
    }

    // ---------- 400: parametres i tipus ----------
    @ExceptionHandler(ConstraintViolationException.class)
    public ProblemDetail parametresInvalids(ConstraintViolationException e, HttpServletRequest p) {
        List<ErrorCamp> errors = e.getConstraintViolations().stream()
                .map(v -> new ErrorCamp(v.getPropertyPath().toString(), v.getMessage(), v.getInvalidValue()))
                .toList();
        ProblemDetail detall = problema(HttpStatus.BAD_REQUEST, "parametres-invalids",
                "Parametres invalids", "Revisa els parametres de la peticio.", p);
        detall.setProperty("errors", errors);
        return detall;
    }

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ProblemDetail tipusIncorrecte(MethodArgumentTypeMismatchException e, HttpServletRequest p) {
        String esperat = e.getRequiredType() != null ? e.getRequiredType().getSimpleName() : "valid";
        return problema(HttpStatus.BAD_REQUEST, "tipus-incorrecte", "Tipus de dada incorrecte",
                "El parametre '%s' amb valor '%s' no es un %s."
                        .formatted(e.getName(), e.getValue(), esperat), p);
    }

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ProblemDetail cosIllegible(HttpMessageNotReadableException e, HttpServletRequest p) {
        // NO exposem e.getMessage(): revela l'estructura interna de les classes
        return problema(HttpStatus.BAD_REQUEST, "cos-invalid", "Cos de la peticio invalid",
                "El cos no es un JSON valid o no encaixa amb el format esperat.", p);
    }

    // ---------- 503: dependencia externa ----------
    @ExceptionHandler(ServeiExternNoDisponibleException.class)
    public ResponseEntity<ProblemDetail> serveiCaigut(ServeiExternNoDisponibleException e,
                                                      HttpServletRequest p) {
        log.error("Servei extern no disponible: {}", e.getServei(), e);
        ProblemDetail detall = problema(HttpStatus.SERVICE_UNAVAILABLE, "servei-no-disponible",
                "Servei temporalment no disponible",
                "No s'ha pogut completar l'operacio. Torna-ho a provar d'aqui a uns minuts.", p);
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .header(HttpHeaders.RETRY_AFTER, "60")     // el client sap quan reintentar
                .body(detall);
    }

    // ---------- 500: la xarxa de seguretat ----------
    @ExceptionHandler(Exception.class)
    public ProblemDetail errorNoPrevist(Exception e, HttpServletRequest p) {
        String idIncidencia = UUID.randomUUID().toString().substring(0, 12);
        // La traca COMPLETA al log; al client, nomes l'identificador (06-07 i 12-07)
        log.error("Error no previst [id={}] a {} {}", idIncidencia, p.getMethod(), p.getRequestURI(), e);

        ProblemDetail detall = problema(HttpStatus.INTERNAL_SERVER_ERROR, "error-intern",
                "Error intern",
                "S'ha produit un error inesperat. Si el problema persisteix, "
                + "contacta amb suport indicant l'identificador d'incidencia.", p);
        detall.setProperty("idIncidencia", idIncidencia);
        return detall;
    }

    // ---------- Constructor comu ----------
    private ProblemDetail problema(HttpStatus estat, String tipus, String titol,
                                   String detallText, HttpServletRequest peticio) {
        ProblemDetail detall = ProblemDetail.forStatusAndDetail(estat, detallText);
        detall.setType(URI.create(BASE_TIPUS + tipus));
        detall.setTitle(titol);
        detall.setInstance(URI.create(peticio.getRequestURI()));
        detall.setProperty("timestamp", Instant.now().toString());
        // L'identificador de correlacio que MDC va posar a 11-07: uneix la resposta amb el log
        detall.setProperty("traceId", MDC.get("traceId"));
        return detall;
    }

    public record ErrorCamp(String camp, String missatge, Object valorRebutjat) { }
}

@GetMapping
public PageResponse<MaterialResponse> llistar(
        @PageableDefault(size = 20, sort = "titol", direction = Sort.Direction.ASC)
        Pageable paginacio) {

    Page<Material> pagina = cataleg.cercar(paginacio);
    return PageResponse.desDe(pagina.map(MaterialResponse::desDe));
}

GET /api/materials?page=0&size=20&sort=titol,asc
GET /api/materials?page=2&size=50&sort=anyPublicacio,desc&sort=titol,asc

spring:
  data:
    web:
      pageable:
        default-page-size: 20
        max-page-size: 100          # Spring retalla silenciosament per damunt
        one-indexed-parameters: false

public record PageResponse<T>(List<T> contingut, MetadadesPagina pagina) {

    public static <T> PageResponse<T> desDe(Page<T> page) {
        return new PageResponse<>(page.getContent(), new MetadadesPagina(
                page.getNumber(), page.getSize(), page.getTotalElements(),
                page.getTotalPages(), page.isFirst(), page.isLast()));
    }

    public record MetadadesPagina(int numero, int mida, long totalElements,
                                  int totalPagines, boolean primera, boolean ultima) { }
}

{
  "contingut": [ { "isbn": "978-0000000001", "titol": "Java Eficac", "…": "…" } ],
  "pagina": { "numero": 0, "mida": 20, "totalElements": 3,
              "totalPagines": 1, "primera": true, "ultima": true }
}

public record CriteriMaterialsRequest(
        @Size(min = 2, max = 100) String titol,
        @Size(min = 2, max = 100) String autor,
        TipusMaterial tipus,
        @Min(1450) Integer anyDesDe,           // any de la impremta: un limit raonable
        @Max(2100) Integer anyFinsA,
        Boolean nomesDisponibles) {

    public CriteriCerca aDomini() {
        return CriteriCerca.builder()          // el Builder de 12-02
                .titol(titol).autor(autor).tipus(tipus)
                .entre(anyDesDe, anyFinsA)
                .nomesDisponibles(Boolean.TRUE.equals(nomesDisponibles))
                .construir();
    }
}

@GetMapping
public PageResponse<MaterialResponse> llistar(@Valid CriteriMaterialsRequest criteri,
                                              @PageableDefault(size = 20) Pageable paginacio) {
    Page<Material> resultats = cataleg.cercar(criteri.aDomini(), paginacio);
    return PageResponse.desDe(resultats.map(MaterialResponse::desDe));
}

GET /api/materials?titol=java&tipus=LLIBRE&nomesDisponibles=true&page=0&size=10

public Page<Material> cercar(CriteriCerca criteri, Pageable paginacio) {
    Specification<Material> spec = Specification.where(null);

    if (criteri.titol() != null) {
        spec = spec.and((arrel, consulta, cb) ->
                cb.like(cb.lower(arrel.get("titol")), "%" + criteri.titol().toLowerCase() + "%"));
    }
    if (criteri.tipus() != null) {
        spec = spec.and((arrel, consulta, cb) -> cb.equal(arrel.get("tipus"), criteri.tipus()));
    }
    if (criteri.nomesDisponibles()) {
        spec = spec.and((arrel, consulta, cb) -> cb.greaterThan(arrel.get("unitatsDisponibles"), 0));
    }
    return repositori.findAll(spec, paginacio);
}

curl -i -X POST http://localhost:8080/api/prestecs \
  -H "Content-Type: application/json" \
  -d '{"isbn":"978-0000000001","idEmpleat":1,"dies":15}'

HTTP/1.1 201 Created
Location: http://localhost:8080/api/prestecs/42
Content-Type: application/json

{
  "id": 42,
  "isbn": "978-0000000001",
  "titolMaterial": "Java Eficac",
  "nomEmpleat": "Marta Ruiz",
  "dataPrestec": "2026-08-05",
  "dataVenciment": "2026-08-20",
  "dataDevolucio": null,
  "estat": "ACTIU",
  "diesRestants": 15,
  "multaAcumulada": 0.00
}

curl -i -X POST http://localhost:8080/api/prestecs \
  -H "Content-Type: application/json" \
  -d '{"isbn":"978-0000000003","idEmpleat":2,"dies":15}'

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://bibliotech.nexussoftware.com/errors/limit-prestecs",
  "title": "Limit de prestecs excedit",
  "status": 409,
  "detail": "L'empleat Diego Alonso ja te 3 prestecs actius (maxim: 3).",
  "instance": "/api/prestecs",
  "timestamp": "2026-08-05T10:23:45Z",
  "traceId": "a7f3e91c4b2d",
  "prestecsActius": [12, 27, 38],
  "maximPermes": 3
}

curl -i -X POST http://localhost:8080/api/prestecs \
  -H "Content-Type: application/json" \
  -d '{"isbn":"1234","idEmpleat":null,"dies":365}'

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://bibliotech.nexussoftware.com/errors/validacio",
  "title": "Error de validacio",
  "status": 400,
  "detail": "La peticio conte 3 camp(s) invalid(s).",
  "instance": "/api/prestecs",
  "errors": [
    {"camp": "isbn", "missatge": "L'ISBN ha de comencar per 978 o 979 i tenir 13 digits",
     "valorRebutjat": "1234"},
    {"camp": "idEmpleat", "missatge": "L'identificador de l'empleat es obligatori",
     "valorRebutjat": null},
    {"camp": "dies", "missatge": "La durada maxima es de 90 dies", "valorRebutjat": 365}
  ]
}

curl -i -X POST http://localhost:8080/api/prestecs/42/devolucio \
  -H "Content-Type: application/json" -d '{"data":"2026-08-25"}'

HTTP/1.1 200 OK

{
  "idPrestec": 42,
  "dataDevolucio": "2026-08-25",
  "diesDeRetard": 5,
  "multa": 2.50,
  "estat": "RETORNAT"
}

curl "http://localhost:8080/api/materials?titol=diss&tipus=LLIBRE&page=0&size=5&sort=titol,asc"

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

@RestController
@RequestMapping("/api/prestecs")
@Tag(name = "Prestecs", description = "Gestio de prestecs de materials a empleats")
public class PrestecController {

    @Operation(
        summary = "Crea un prestec",
        description = """
                Presta un material a un empleat. Comprova que hi hagi unitats disponibles
                i que l'empleat no superi el limit de prestecs actius.

                Si no s'indica la durada, es fa servir l'estandard del tipus de material:
                15 dies per a llibres, 7 per a revistes i 3 per a DVD.""")
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "Prestec creat",
            content = @Content(schema = @Schema(implementation = PrestecResponse.class))),
        @ApiResponse(responseCode = "400", description = "Peticio invalida",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
        @ApiResponse(responseCode = "404", description = "Material o empleat inexistent",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
        @ApiResponse(responseCode = "409", description = "Sense unitats lliures o limit excedit",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
    })
    @PostMapping
    public ResponseEntity<PrestecResponse> crear(@Valid @RequestBody CrearPrestecRequest peticio) { … }
}

@Configuration
public class ConfiguracioOpenApi {

    @Bean
    OpenAPI apiBiblioTech(@Value("${bibliotech.version}") String versio) {
        return new OpenAPI()
                .info(new Info()
                        .title("API de BiblioTech")
                        .version(versio)
                        .description("Gestio de la biblioteca tecnica interna de Nexus Software.")
                        .contact(new Contact().name("Equip de plataforma")
                                              .email("[email protected]")))
                .servers(List.of(
                        new Server().url("http://localhost:8080").description("Desenvolupament"),
                        new Server().url("https://bibliotech.nexussoftware.com").description("Produccio")));
    }
}

springdoc:
  swagger-ui:
    enabled: false        # en prod
  api-docs:
    path: /v3/api-docs

OPTIONS /api/prestecs HTTP/1.1
Origin: https://intranet.nexussoftware.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://intranet.nexussoftware.com
Access-Control-Allow-Methods: GET,POST,PUT,DELETE
Access-Control-Allow-Headers: content-type
Access-Control-Max-Age: 3600

@Configuration
public class ConfiguracioCors implements WebMvcConfigurer {

    private final List<String> origensPermesos;       // des d'application.yml, per entorn

    @Override
    public void addCorsMappings(CorsRegistry registre) {
        registre.addMapping("/api/**")
                .allowedOrigins(origensPermesos.toArray(String[]::new))
                .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE")
                .allowedHeaders("Content-Type", "Authorization")
                .exposedHeaders("Location")            // perque el client la pugui llegir despres d'un 201
                .allowCredentials(true)
                .maxAge(3600);                         // desar la resposta previa 1 hora
    }
}

# dev
bibliotech:
  cors:
    origens: ["http://localhost:5173", "http://localhost:3000"]
# prod
bibliotech:
  cors:
    origens: ["https://intranet.nexussoftware.com"]

// MALAMENT: transaccio al controlador
@RestController
public class PrestecController {
    @PostMapping
    @Transactional                          // ← no
    public PrestecResponse crear(@RequestBody CrearPrestecRequest p) { … }
}

// BE: la transaccio, al cas d'us
@Service
public class GestorPrestecs implements GestionarPrestecs {

    @Override
    @Transactional                                  // escriptura
    public Prestec prestar(Isbn isbn, Long idEmpleat, Integer dies) { … }

    @Override
    @Transactional(readOnly = true)                 // lectura: Hibernate omet el dirty checking
    public Optional<Prestec> cercar(Long id) { … }
}

// I el controlador nomes tradueix HTTP
@PostMapping
public ResponseEntity<PrestecResponse> crear(@Valid @RequestBody CrearPrestecRequest p) {
    Prestec creat = gestor.prestar(p.isbn(), p.idEmpleat(), p.dies());
    return ResponseEntity.created(uriDe(creat)).body(PrestecResponse.desDe(creat, avui()));
}

spring:
  jpa:
    open-in-view: false

@WebMvcTest(PrestecController.class)
class PrestecControllerTest {

    @Autowired MockMvc mvc;
    @Autowired ObjectMapper json;

    @MockitoBean GestionarPrestecs gestor;       // Spring Boot 3.4+; abans era @MockBean

    @Test
    void retorna201ILocationEnCrearUnPrestec() throws Exception {
        var creat = unPrestec(42L, "978-0000000001", "Marta Ruiz");
        when(gestor.prestar(any(), eq(1L), eq(15))).thenReturn(creat);

        mvc.perform(post("/api/prestecs")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"978-0000000001","idEmpleat":1,"dies":15}"""))
                .andExpect(status().isCreated())
                .andExpect(header().string("Location", endsWith("/api/prestecs/42")))
                .andExpect(jsonPath("$.id").value(42))
                .andExpect(jsonPath("$.titolMaterial").value("Java Eficac"))
                .andExpect(jsonPath("$.estat").value("ACTIU"));
    }

    @Test
    void retorna400AmbElDetallDeCadaCampInvalid() throws Exception {
        mvc.perform(post("/api/prestecs")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"1234","idEmpleat":null,"dies":365}"""))
                .andExpect(status().isBadRequest())
                .andExpect(content().contentTypeCompatibleWith("application/problem+json"))
                .andExpect(jsonPath("$.title").value("Error de validacio"))
                .andExpect(jsonPath("$.errors", hasSize(3)))
                .andExpect(jsonPath("$.errors[*].camp",
                        containsInAnyOrder("isbn", "idEmpleat", "dies")));

        // Amb dades invalides, el cas d'us NO ha d'haver-se invocat
        verifyNoInteractions(gestor);
    }

    @Test
    void retorna409AmbDetallQuanSeSuperaElLimit() throws Exception {
        when(gestor.prestar(any(), eq(2L), any()))
                .thenThrow(new LimitPrestecsExceditException(2L, "Diego Alonso", 3,
                                                             List.of(12L, 27L, 38L)));

        mvc.perform(post("/api/prestecs")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"978-0000000003","idEmpleat":2,"dies":15}"""))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.type").value(endsWith("/errors/limit-prestecs")))
                .andExpect(jsonPath("$.detail").value(containsString("Diego Alonso")))
                .andExpect(jsonPath("$.prestecsActius", hasSize(3)));
    }

    @Test
    void retorna404QuanElPrestecNoExisteix() throws Exception {
        when(gestor.cercar(9999L)).thenReturn(Optional.empty());

        mvc.perform(get("/api/prestecs/9999"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.status").value(404));
    }

    @Test
    void retorna400QuanLIsbnDelCamiEsInvalid() throws Exception {
        mvc.perform(get("/api/materials/no-es-un-isbn"))
                .andExpect(status().isBadRequest());
    }
}

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class PrestecApiIT {

    @Autowired TestRestTemplate client;
    @Autowired PrestecRepository repositori;

    @Test
    void cicleCompletDePrestecIDevolucio() {
        // 1. Crear
        var peticio = new CrearPrestecRequest("978-0000000001", 1L, 15);
        ResponseEntity<PrestecResponse> creacio =
                client.postForEntity("/api/prestecs", peticio, PrestecResponse.class);

        assertThat(creacio.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(creacio.getHeaders().getLocation()).isNotNull();
        Long id = creacio.getBody().id();

        // 2. Consultar per l'URI que va retornar Location
        ResponseEntity<PrestecResponse> consulta =
                client.getForEntity(creacio.getHeaders().getLocation(), PrestecResponse.class);
        assertThat(consulta.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(consulta.getBody().estat()).isEqualTo("ACTIU");

        // 3. Retornar
        ResponseEntity<DevolucioResponse> devolucio = client.postForEntity(
                "/api/prestecs/{id}/devolucio", new DevolucioRequest(null),
                DevolucioResponse.class, id);
        assertThat(devolucio.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(devolucio.getBody().multa()).isEqualByComparingTo("0.00");

        // 4. Verificar que la persistencia reflecteix el canvi
        assertThat(repositori.findById(id))
                .get()
                .extracting(Prestec::getEstat)
                .isEqualTo(EstatPrestec.RETORNAT);
    }

    @Test
    void retornarDuesVegadesRetorna409() {
        Long id = crearIRetornar();

        ResponseEntity<ProblemDetail> segona = client.postForEntity(
                "/api/prestecs/{id}/devolucio", new DevolucioRequest(null),
                ProblemDetail.class, id);

        assertThat(segona.getStatusCode()).isEqualTo(HttpStatus.CONFLICT);
        assertThat(segona.getBody().getDetail()).contains("ja ha estat retornat");
    }
}

@Controller                                   // NO @RestController!
@RequestMapping("/cataleg")
public class CatalegVistaController {

    @GetMapping
    public String llistar(@RequestParam(required = false) String titol, Model model) {
        model.addAttribute("materials", cataleg.cercar(titol));
        model.addAttribute("filtre", titol);
        return "cataleg/llista";              // resol a templates/cataleg/llista.html
    }
}

<!-- src/main/resources/templates/cataleg/llista.html -->
<table>
  <tr th:each="m : ${materials}">
    <td th:text="${m.isbn}">978-…</td>
    <td th:text="${m.titol}">Titol</td>
    <td th:text="${m.unitatsDisponibles}">0</td>
  </tr>
</table>

spring:
  threads:
    virtual:
      enabled: true

@GetMapping("/api/diagnostic/fil")
public Map<String, Object> filActual() {
    Thread fil = Thread.currentThread();
    return Map.of("nom", fil.getName(),
                  "virtual", fil.isVirtual(),
                  "grup", String.valueOf(fil.threadId()));
}

{"nom":"","virtual":true,"grup":"142"}

public record RenovarPrestecRequest(
        @Min(value = 1, message = "La renovacio ha de ser d'almenys 1 dia")
        @Max(value = 30, message = "La renovacio no pot superar els 30 dies")
        Integer dies) {
}

public record RenovacioResponse(
        Long idPrestec,
        String titolMaterial,
        LocalDate vencimentAnterior,
        LocalDate vencimentNou,
        int diesAfegits,
        boolean potRenovarseDeNou) {

    public static RenovacioResponse desDe(Prestec p, LocalDate anterior) {
        return new RenovacioResponse(
                p.getId(), p.titolDelMaterial(), anterior, p.getDataVenciment(),
                (int) ChronoUnit.DAYS.between(anterior, p.getDataVenciment()),
                p.getEstat().permetRenovar());
    }
}

@PostMapping("/{id}/renovacio")
@Operation(summary = "Renova un prestec",
           description = "Amplia la data de venciment. Nomes es permet una renovacio per prestec.")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "Renovat"),
    @ApiResponse(responseCode = "404", description = "El prestec no existeix"),
    @ApiResponse(responseCode = "409", description = "Ja renovat, vencut, o amb reserves pendents")
})
public RenovacioResponse renovar(
        @PathVariable Long id,
        @RequestBody(required = false) @Valid RenovarPrestecRequest peticio) {

    Integer dies = (peticio != null) ? peticio.dies() : null;
    ResultatRenovacio resultat = gestor.renovar(id, dies);
    return RenovacioResponse.desDe(resultat.prestec(), resultat.vencimentAnterior());
}

@Override
@Transactional
public ResultatRenovacio renovar(Long id, Integer dies) {
    Prestec prestec = repositori.cercarPerId(id)
            .orElseThrow(() -> new PrestecNoTrobatException(id));

    LocalDate avui = LocalDate.now(rellotge);

    // Regla 1: l'estat governa (patro Estat, 12-02)
    if (!prestec.getEstat().permetRenovar()) {
        throw new RenovacioNoPermesaException(id, prestec.getEstat(),
                "Aquest prestec ja ha estat renovat o no admet renovacio.");
    }

    // Regla 2: vencut
    if (prestec.estaVencutA(avui)) {
        throw new RenovacioNoPermesaException(id, prestec.getEstat(),
                "El prestec va vencer el %s. Retorna'l i torna a prestar-lo."
                        .formatted(prestec.getDataVenciment()));
    }

    // Regla 3: reserves d'altri
    long pendents = reserves.comptarPendentsDe(prestec.getIsbn());
    if (pendents > 0) {
        throw new MaterialAmbReservesException(prestec.getIsbn(), pendents);
    }

    LocalDate anterior = prestec.getDataVenciment();
    int diesEfectius = (dies != null) ? dies : prestec.diesEstandardDelMaterial();
    prestec.renovar(diesEfectius);            // valida i transita l'estat

    return new ResultatRenovacio(prestec, anterior);
}

@ExceptionHandler(RenovacioNoPermesaException.class)
public ProblemDetail renovacioNoPermesa(RenovacioNoPermesaException e, HttpServletRequest p) {
    ProblemDetail d = problema(HttpStatus.CONFLICT, "renovacio-no-permesa",
            "Renovacio no permesa", e.getMessage(), p);
    d.setProperty("idPrestec", e.getIdPrestec());
    d.setProperty("estatActual", e.getEstat().name());
    return d;
}

@ExceptionHandler(MaterialAmbReservesException.class)
public ProblemDetail ambReserves(MaterialAmbReservesException e, HttpServletRequest p) {
    ProblemDetail d = problema(HttpStatus.CONFLICT, "material-amb-reserves",
            "Material amb reserves pendents",
            "No es pot renovar: hi ha %d empleat(s) esperant aquest material."
                    .formatted(e.getReservesPendents()), p);
    d.setProperty("reservesPendents", e.getReservesPendents());
    return d;
}

@WebMvcTest(PrestecController.class)
class RenovacioControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean GestionarPrestecs gestor;

    @Test
    void renovaAmbElsDiesIndicats() throws Exception {
        var prestec = unPrestec(42L).ambVenciment(LocalDate.of(2026, 8, 20));
        when(gestor.renovar(42L, 10)).thenReturn(
                new ResultatRenovacio(prestec.renovatFinsA(LocalDate.of(2026, 8, 30)),
                                      LocalDate.of(2026, 8, 20)));

        mvc.perform(post("/api/prestecs/42/renovacio")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"dies":10}"""))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.vencimentAnterior").value("2026-08-20"))
                .andExpect(jsonPath("$.vencimentNou").value("2026-08-30"))
                .andExpect(jsonPath("$.diesAfegits").value(10))
                .andExpect(jsonPath("$.potRenovarseDeNou").value(false));
    }

    @Test
    void renovaSenseCosAmbLaDuradaEstandard() throws Exception {
        when(gestor.renovar(42L, null)).thenReturn(unaRenovacioDe(15));

        mvc.perform(post("/api/prestecs/42/renovacio"))     // sense cos
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.diesAfegits").value(15));
    }

    @Test
    void retorna404SiElPrestecNoExisteix() throws Exception {
        when(gestor.renovar(eq(9999L), any())).thenThrow(new PrestecNoTrobatException(9999L));

        mvc.perform(post("/api/prestecs/9999/renovacio"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.type").value(endsWith("/errors/recurs-no-trobat")));
    }

    @Test
    void retorna409SiJaVaSerRenovat() throws Exception {
        when(gestor.renovar(eq(42L), any())).thenThrow(
                new RenovacioNoPermesaException(42L, EstatPrestec.RENOVAT,
                        "Aquest prestec ja ha estat renovat o no admet renovacio."));

        mvc.perform(post("/api/prestecs/42/renovacio"))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.estatActual").value("RENOVAT"))
                .andExpect(jsonPath("$.detail").value(containsString("ja ha estat renovat")));
    }

    @Test
    void retorna409SiHiHaReservesPendents() throws Exception {
        when(gestor.renovar(eq(42L), any()))
                .thenThrow(new MaterialAmbReservesException(Isbn.de("978-0000000001"), 2));

        mvc.perform(post("/api/prestecs/42/renovacio"))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.reservesPendents").value(2));
    }

    @ParameterizedTest
    @ValueSource(ints = {0, -5, 31, 100})
    void retorna400SiElsDiesEstanForaDeRang(int dies) throws Exception {
        mvc.perform(post("/api/prestecs/42/renovacio")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"dies\":%d}".formatted(dies)))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.errors[0].camp").value("dies"));

        verifyNoInteractions(gestor);      // ni tan sols s'ha cridat el cas d'us
    }
}

@Documented
@Constraint(validatedBy = ValidadorRangAnys.class)
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface RangAnysValid {
    String message() default "anyDesDe no pot ser posterior a anyFinsA";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class ValidadorRangAnys implements ConstraintValidator<RangAnysValid, CercaRequest> {
    @Override
    public boolean isValid(CercaRequest r, ConstraintValidatorContext ctx) {
        if (r.anyDesDe() == null || r.anyFinsA() == null) return true;   // @NotNull no es cosa nostra
        if (r.anyDesDe() <= r.anyFinsA()) return true;

        ctx.disableDefaultConstraintViolation();
        ctx.buildConstraintViolationWithTemplate(
                "anyDesDe (%d) no pot ser posterior a anyFinsA (%d)"
                        .formatted(r.anyDesDe(), r.anyFinsA()))
           .addPropertyNode("anyDesDe")         // l'error s'associa al camp correcte
           .addConstraintViolation();
        return false;
    }
}

@RangAnysValid
public record CercaRequest(
        @NotBlank(message = "El text de cerca es obligatori")
        @Size(min = 2, max = 100, message = "Entre 2 i 100 caracters")
        String q,

        List<TipusMaterial> tipus,        // repetible: ?tipus=LLIBRE&tipus=DVD

        Boolean disponible,

        @Min(1450) @Max(2100) Integer anyDesDe,
        @Min(1450) @Max(2100) Integer anyFinsA) {

    /** Normalitzacio: null → llista buida, per no repetir comprovacions aigues avall. */
    public CercaRequest {
        tipus = (tipus == null) ? List.of() : List.copyOf(tipus);
    }

    public CriteriCerca aDomini() {
        return CriteriCerca.builder()
                .text(q)
                .tipus(tipus)
                .nomesDisponibles(Boolean.TRUE.equals(disponible))
                .entre(anyDesDe, anyFinsA)
                .construir();
    }
}

public record ResultatCercaResponse(
        List<MaterialResponse> resultats,
        PageResponse.MetadadesPagina pagina,
        Map<String, Long> facetesPerTipus,
        long totalGlobal,
        String consulta) {

    public static ResultatCercaResponse desDe(Page<Material> pagina,
                                              Map<TipusMaterial, Long> facetes,
                                              String consulta) {
        return new ResultatCercaResponse(
                pagina.getContent().stream().map(MaterialResponse::desDe).toList(),
                new PageResponse.MetadadesPagina(pagina.getNumber(), pagina.getSize(),
                        pagina.getTotalElements(), pagina.getTotalPages(),
                        pagina.isFirst(), pagina.isLast()),
                facetes.entrySet().stream()
                        .collect(Collectors.toMap(e -> e.getKey().name(), Map.Entry::getValue,
                                                  (a, b) -> a, LinkedHashMap::new)),
                facetes.values().stream().mapToLong(Long::longValue).sum(),
                consulta);
    }
}

@GetMapping("/cerca")
@Operation(summary = "Cerca avancada amb facetes per tipus de material")
public ResultatCercaResponse cercar(
        @Valid CercaRequest criteri,
        @PageableDefault(size = 20, sort = "titol") Pageable paginacio) {

    // Defensa en profunditat: encara que max-page-size estigui configurat, no te'n fiis
    if (paginacio.getPageSize() > 50) {
        paginacio = PageRequest.of(paginacio.getPageNumber(), 50, paginacio.getSort());
    }

    CriteriCerca domini = criteri.aDomini();
    Page<Material> pagina = cataleg.cercar(domini, paginacio);
    Map<TipusMaterial, Long> facetes = cataleg.comptarPerTipus(domini);   // consulta d'agregacio

    return ResultatCercaResponse.desDe(pagina, facetes, criteri.q());
}

@Query("""
       select m.tipus as tipus, count(m) as total
       from Material m
       where (lower(m.titol) like lower(concat('%', :text, '%'))
              or lower(m.autor) like lower(concat('%', :text, '%')))
         and (:nomesDisponibles = false or m.unitatsDisponibles > 0)
       group by m.tipus
       """)
List<FacetaTipus> comptarPerTipus(@Param("text") String text,
                                  @Param("nomesDisponibles") boolean nomesDisponibles);

@Test
void retornaResultatsAmbFacetesPerTipus() throws Exception {
    when(cataleg.cercar(any(), any())).thenReturn(unaPaginaAmb(2, "Java Eficac", "Refactoritzacio"));
    when(cataleg.comptarPerTipus(any())).thenReturn(
            new LinkedHashMap<>(Map.of(TipusMaterial.LLIBRE, 5L, TipusMaterial.DVD, 2L)));

    mvc.perform(get("/api/materials/cerca").param("q", "java").param("tipus", "LLIBRE"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.resultats", hasSize(2)))
            .andExpect(jsonPath("$.facetesPerTipus.LLIBRE").value(5))
            .andExpect(jsonPath("$.totalGlobal").value(7))
            .andExpect(jsonPath("$.consulta").value("java"));
}

@Test
void rebutjaConsultesMassaCurtes() throws Exception {
    mvc.perform(get("/api/materials/cerca").param("q", "j"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errors[0].camp").value("q"));
}

@Test
void rebutjaUnRangDAnysInvertit() throws Exception {
    mvc.perform(get("/api/materials/cerca")
                    .param("q", "java").param("anyDesDe", "2020").param("anyFinsA", "2010"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errors[0].camp").value("anyDesDe"))
            .andExpect(jsonPath("$.errors[0].missatge").value(containsString("no pot ser posterior")));
}

@Test
void retallaLaMidaDePaginaAlMaxim() throws Exception {
    mvc.perform(get("/api/materials/cerca").param("q", "java").param("size", "500"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.pagina.mida").value(lessThanOrEqualTo(50)));
}

@Entity
@Table(name = "claus_idempotencia",
       indexes = @Index(name = "idx_caducitat", columnList = "caducaEl"))
public class ClauIdempotencia {

    @Id
    @Column(length = 100)
    private String clau;

    @Column(nullable = false, length = 64)
    private String empremtaPeticio;    // hash del cos: detecta reutilitzacio amb dades diferents

    @Enumerated(EnumType.STRING)
    private EstatClau estat;           // EN_CURS, COMPLETADA

    private Integer codiResposta;

    @Column(columnDefinition = "text")
    private String cosResposta;

    private String ubicacio;
    private Instant creadaEl;
    private Instant caducaEl;

    public enum EstatClau { EN_CURS, COMPLETADA }
}

@Component
public class InterceptorIdempotencia implements HandlerInterceptor {

    private static final Logger log = LoggerFactory.getLogger(InterceptorIdempotencia.class);
    private static final String CAPCALERA = "Idempotency-Key";
    private static final Duration VIGENCIA = Duration.ofHours(24);

    private final RepositoriClausIdempotencia repositori;
    private final ObjectMapper json;
    private final Clock rellotge;

    @Override
    public boolean preHandle(HttpServletRequest peticio, HttpServletResponse resposta,
                             Object gestor) throws IOException {

        // Nomes aplica a metodes no idempotents per naturalesa
        if (!"POST".equals(peticio.getMethod())) return true;

        String clau = peticio.getHeader(CAPCALERA);
        if (clau == null || clau.isBlank()) return true;       // capcalera opcional

        String empremta = empremtaDe(peticio);

        // INSERT condicional: la restriccio de clau primaria resol la cursa
        // entre dues peticions simultanies amb la mateixa clau. NO facis "SELECT i despres INSERT".
        Optional<ClauIdempotencia> existent = repositori.reservarSiNoExisteix(
                clau, empremta, Instant.now(rellotge), Instant.now(rellotge).plus(VIGENCIA));

        if (existent.isEmpty()) {
            // L'hem reservada nosaltres: continuem amb el processament normal
            peticio.setAttribute("idempotencia.clau", clau);
            return true;
        }

        ClauIdempotencia previa = existent.get();

        // Mateixa clau, cos diferent: el client s'ha equivocat
        if (!previa.getEmpremtaPeticio().equals(empremta)) {
            escriureProblema(resposta, HttpStatus.UNPROCESSABLE_ENTITY,
                    "La clau d'idempotencia ja s'ha fet servir amb un cos diferent.");
            return false;
        }

        if (previa.getEstat() == EstatClau.EN_CURS) {
            // Una altra peticio identica s'esta processant ara mateix
            resposta.setHeader(HttpHeaders.RETRY_AFTER, "2");
            escriureProblema(resposta, HttpStatus.CONFLICT,
                    "Ja hi ha una peticio en curs amb aquesta clau d'idempotencia.");
            return false;
        }

        // COMPLETADA: reproduim la resposta original sense executar res
        log.info("Reproduint resposta idempotent per a la clau {}", clau);
        resposta.setStatus(previa.getCodiResposta());
        resposta.setContentType(MediaType.APPLICATION_JSON_VALUE);
        resposta.setHeader("Idempotent-Replay", "true");
        if (previa.getUbicacio() != null) {
            resposta.setHeader(HttpHeaders.LOCATION, previa.getUbicacio());
        }
        resposta.getWriter().write(previa.getCosResposta());
        return false;                       // NO es crida el controlador
    }

    private String empremtaDe(HttpServletRequest peticio) throws IOException {
        // Requereix ContentCachingRequestWrapper: el cos nomes es pot llegir una vegada
        byte[] cos = ((ContentCachingRequestWrapper) peticio).getContentAsByteArray();
        return HexFormat.of().formatHex(
                MessageDigest.getInstance("SHA-256").digest(cos));
    }
}

@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
public class FiltreIdempotencia extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest peticio, HttpServletResponse resposta,
                                    FilterChain cadena) throws ServletException, IOException {

        var peticioCacheada = new ContentCachingRequestWrapper(peticio);
        var respostaCacheada = new ContentCachingResponseWrapper(resposta);

        try {
            cadena.doFilter(peticioCacheada, respostaCacheada);

            String clau = (String) peticio.getAttribute("idempotencia.clau");
            if (clau != null) {
                int estat = respostaCacheada.getStatus();
                if (estat >= 200 && estat < 300) {
                    // Nomes es memoritza l'exit: un 500 ha de poder reintentar-se
                    repositori.completar(clau, estat,
                            new String(respostaCacheada.getContentAsByteArray(), UTF_8),
                            respostaCacheada.getHeader(HttpHeaders.LOCATION));
                } else {
                    repositori.alliberar(clau);   // allibera la clau per a un reintent legitim
                }
            }
        } finally {
            respostaCacheada.copyBodyToResponse();   // IMPRESCINDIBLE: sense aixo no arriba res al client
        }
    }
}

@Repository
public class RepositoriClausIdempotencia {

    private final JdbcTemplate jdbc;

    /**
     * Retorna Optional.empty() si la clau s'ha reservat ara (som els primers),
     * o la fila existent si ja hi era.
     *
     * ON CONFLICT DO NOTHING fa l'operacio ATOMICA a la base de dades:
     * dues peticions simultanies amb la mateixa clau no poden reservar-la totes dues.
     * Un "SELECT i despres INSERT" en Java tindria una finestra de cursa.
     */
    public Optional<ClauIdempotencia> reservarSiNoExisteix(String clau, String empremta,
                                                           Instant ara, Instant caduca) {
        int files = jdbc.update("""
                insert into claus_idempotencia
                       (clau, empremta_peticio, estat, creada_el, caduca_el)
                values (?, ?, 'EN_CURS', ?, ?)
                on conflict (clau) do nothing
                """, clau, empremta, Timestamp.from(ara), Timestamp.from(caduca));

        if (files == 1) return Optional.empty();     // l'hem reservada nosaltres

        return jdbc.query("select * from claus_idempotencia where clau = ?",
                          this::mapejar, clau).stream().findFirst();
    }
}

@Scheduled(cron = "0 0 3 * * *")     // cada dia a les 3:00
@Transactional
public void purgarClausCaducades() {
    int esborrades = repositori.esborrarCaducadesAbansDe(Instant.now(rellotge));
    log.info("Claus d'idempotencia purgades: {}", esborrades);
}

CLAU=$(uuidgen)
curl -i -X POST http://localhost:8080/api/prestecs \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAU" \
  -d '{"isbn":"978-0000000001","idEmpleat":1,"dies":15}'
# → 201 Created, Location: /api/prestecs/42

# Reintent amb la mateixa clau
curl -i -X POST … -H "Idempotency-Key: $CLAU" -d '{…}'
# → 201 Created, Location: /api/prestecs/42, Idempotent-Replay: true
#   (i NO s'ha creat un segon prestec)