GET /api/materiales?tipo=LIBRO&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: 284

{"content":[{"isbn":"978-0000000001","titulo":"Java Efectivo","tipo":"LIBRO"}],
 "page":{"size":20,"number":0,"totalElements":3,"totalPages":1}}

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

// ServidorCatalogo, módulo 9: lo escribiste tú, entero
public void atender(Socket cliente) throws IOException {
    try (var entrada = new BufferedReader(new InputStreamReader(cliente.getInputStream(), UTF_8));
         var salida = new PrintWriter(cliente.getOutputStream(), true)) {

        String peticion = entrada.readLine();          // "BUSCAR 978-0000000001"
        String[] partes = peticion.split(" ", 2);      // parseo del protocolo

        switch (partes[0]) {                           // enrutado
            case "BUSCAR" -> {
                Optional<Material> m = catalogo.porIsbn(partes[1]);
                if (m.isPresent()) {
                    salida.println("OK " + serializar(m.get()));    // serialización
                } else {
                    salida.println("ERROR 404 No encontrado");      // código de error
                }
            }
            case "LISTAR" -> salida.println("OK " + serializar(catalogo.todos()));
            default -> salida.println("ERROR 400 Comando desconocido");
        }
    }
}

@RestController
@RequestMapping("/api/materiales")
public class CatalogoController {

    private final ConsultarCatalogo catalogo;

    @GetMapping("/{isbn}")
    public MaterialResponse porIsbn(@PathVariable Isbn isbn) {
        return catalogo.porIsbn(isbn)
                .map(MaterialResponse::desde)
                .orElseThrow(() -> new MaterialNoEncontradoException(isbn));
    }
}

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

{"isbn":"978-0000000001","idEmpleado":1,"dias":15}

# Opción A: subrecurso que representa el hecho. La preferida.
POST /api/prestamos/42/devolucion

# Opción B: PATCH sobre el estado
PATCH /api/prestamos/42
{"estado": "DEVUELTO"}

# Opción C: verbo en la ruta. Pragmática, y aceptable si se usa con moderación.
POST /api/prestamos/42/devolver

package com.nexussoftware.bibliotech.web.catalogo;

@RestController                              // = @Controller + @ResponseBody
@RequestMapping("/api/materiales")           // prefijo común de todos los métodos
public class CatalogoController {

    private final ConsultarCatalogo catalogo;
    private final GestionarCatalogo gestion;

    public CatalogoController(ConsultarCatalogo catalogo, GestionarCatalogo gestion) {
        this.catalogo = catalogo;
        this.gestion = gestion;
    }

    @GetMapping
    public PageResponse<MaterialResponse> listar(@Valid CriterioMaterialesRequest criterio,
                                                 Pageable paginacion) { … }

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

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

    @PutMapping("/{isbn}")
    public MaterialResponse reemplazar(@PathVariable Isbn isbn,
                                       @Valid @RequestBody ActualizarMaterialRequest peticion) { … }

    @PatchMapping("/{isbn}/unidades")
    public MaterialResponse ajustarUnidades(@PathVariable Isbn isbn,
                                            @Valid @RequestBody AjusteUnidadesRequest peticion) { … }

    @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")          // negociación de contenido
@GetMapping(params = "formato=resumen")                        // según parámetro
@GetMapping(headers = "X-Api-Version=2")                       // según cabecera

@GetMapping("/{isbn}/prestamos")
public List<PrestamoResponse> historial(

        // Parte de la ruta: identifica el recurso
        @PathVariable Isbn isbn,

        // Parámetro de consulta obligatorio
        @RequestParam EstadoPrestamo estado,

        // Opcional con valor por defecto
        @RequestParam(defaultValue = "10") int limite,

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

        // Nombre distinto al del parámetro Java
        @RequestParam(name = "ordenar_por", defaultValue = "FECHA") CriterioOrden orden,

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

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

@PostMapping
public ResponseEntity<PrestamoResponse> crear(@Valid @RequestBody CrearPrestamoRequest peticion) { … }

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

    @Override
    public Isbn convert(String texto) {
        try {
            return Isbn.de(texto);
        } catch (IsbnInvalidoException e) {
            // IllegalArgumentException → Spring lo traduce a 400, no a 500
            throw new IllegalArgumentException("ISBN inválido: " + texto, e);
        }
    }
}

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

@PostMapping
public ResponseEntity<PrestamoResponse> crear(@Valid @RequestBody CrearPrestamoRequest peticion) {
    Prestamo creado = gestor.prestar(peticion.isbn(), peticion.idEmpleado(), peticion.dias());

    URI ubicacion = ServletUriComponentsBuilder
            .fromCurrentRequest()          // http://host/api/prestamos
            .path("/{id}")
            .buildAndExpand(creado.getId())
            .toUri();                      // http://host/api/prestamos/42

    return ResponseEntity.created(ubicacion).body(PrestamoResponse.desde(creado));
}

@PutMapping("/{isbn}")
public ResponseEntity<MaterialResponse> reemplazar(@PathVariable Isbn isbn,
                                                   @Valid @RequestBody ActualizarMaterialRequest p) {
    ResultadoActualizacion resultado = gestion.crearOActualizar(isbn, p);

    return resultado.fueCreado()
            ? ResponseEntity.status(HttpStatus.CREATED).body(MaterialResponse.desde(resultado.material()))
            : ResponseEntity.ok(MaterialResponse.desde(resultado.material()));
}

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

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

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

package com.nexussoftware.bibliotech.web.prestamos;

@Schema(description = "Información de un préstamo")          // documentación OpenAPI
public record PrestamoResponse(

        @Schema(example = "42") Long id,
        @Schema(example = "978-0000000001") String isbn,
        @Schema(example = "Java Efectivo") String tituloMaterial,
        @Schema(example = "Marta Ruiz") String nombreEmpleado,
        LocalDate fechaPrestamo,
        LocalDate fechaVencimiento,

        @Schema(description = "Nula si el material sigue prestado")
        LocalDate fechaDevolucion,

        @Schema(example = "ACTIVO") String estado,

        @Schema(description = "Negativo si está vencido", example = "5")
        long diasRestantes,

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

    public static PrestamoResponse desde(Prestamo p, LocalDate hoy) {
        return new PrestamoResponse(
                p.getId(),
                p.getIsbn().valor(),
                p.tituloDelMaterial(),
                p.nombreDelEmpleado(),
                p.getFechaPrestamo(),
                p.getFechaVencimiento(),
                p.getFechaDevolucion().orElse(null),     // JSON no tiene Optional
                p.getEstado().name(),
                ChronoUnit.DAYS.between(hoy, p.getFechaVencimiento()),
                p.multaAcumulada(hoy).importe());
    }
}

public record CrearPrestamoRequest(

        @NotBlank(message = "El ISBN es obligatorio")
        @IsbnValido
        @Schema(example = "978-0000000001")
        String isbn,

        @NotNull(message = "El identificador del empleado es obligatorio")
        @Positive
        Long idEmpleado,

        @Positive @Max(value = 90, message = "La duración máxima es de 90 días")
        @Schema(description = "Días de préstamo. Si se omite, el estándar del tipo de material")
        Integer dias) {
}

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

@PostMapping
public ResponseEntity<PrestamoResponse> crear(@Valid @RequestBody CrearPrestamoRequest peticion) {
    // Si llega aquí, la petición es sintácticamente válida.
    // Si no, Spring ya lanzó MethodArgumentNotValidException.
}

@RestController
@Validated                                   // habilita la validación de parámetros sueltos
@RequestMapping("/api/materiales")
public class CatalogoController {

    @GetMapping
    public List<MaterialResponse> listar(
            @RequestParam @Size(min = 2, message = "Al menos 2 caracteres") String titulo,
            @RequestParam @Max(100) int limite) { … }
}

@RangoFechasValido       // validador propio: desde <= hasta
public record ConsultaMultasRequest(
        @NotNull @PastOrPresent LocalDate desde,
        @NotNull @PastOrPresent LocalDate hasta,
        Long idEmpleado) {
}

package com.nexussoftware.bibliotech.web.validacion;

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

    String message() default "ISBN-13 inválido: revisa el formato y el dígito de control";

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

    /** Si es true, acepta el ISBN con guiones y espacios. */
    boolean permitirSeparadores() default true;
}

public class ValidadorIsbn implements ConstraintValidator<IsbnValido, String> {

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

    private boolean permitirSeparadores;

    @Override
    public void initialize(IsbnValido anotacion) {
        this.permitirSeparadores = anotacion.permitirSeparadores();
    }

    @Override
    public boolean isValid(String valor, ConstraintValidatorContext contexto) {
        // Un valor nulo se considera válido: la obligatoriedad la impone @NotNull.
        // Separar responsabilidades entre validadores es lo correcto.
        if (valor == null) return true;

        String normalizado = permitirSeparadores ? valor.replaceAll("[- ]", "") : valor;

        if (!SIN_SEPARADORES.matcher(normalizado).matches()) {
            mensaje(contexto, "El ISBN debe empezar por 978 o 979 y tener 13 dígitos");
            return false;
        }
        if (!digitoDeControlCorrecto(normalizado)) {
            mensaje(contexto, "El dígito de control del ISBN no es correcto");
            return false;
        }
        return true;
    }

    /**
     * Algoritmo oficial del ISBN-13: se multiplican los 12 primeros dígitos
     * alternando 1 y 3, se suman, y el dígito de control es lo que falta
     * para el siguiente múltiplo de 10.
     */
    private boolean digitoDeControlCorrecto(String isbn) {
        int suma = 0;
        for (int i = 0; i < 12; i++) {
            int digito = isbn.charAt(i) - '0';
            suma += (i % 2 == 0) ? digito : digito * 3;
        }
        int control = (10 - (suma % 10)) % 10;
        return control == (isbn.charAt(12) - '0');
    }

    /** Sustituye el mensaje genérico por uno específico del fallo concreto. */
    private void mensaje(ConstraintValidatorContext contexto, String texto) {
        contexto.disableDefaultConstraintViolation();
        contexto.buildConstraintViolationWithTemplate(texto).addConstraintViolation();
    }
}

{
  "type": "https://bibliotech.nexussoftware.com/errores/limite-prestamos",
  "title": "Límite de préstamos excedido",
  "status": 409,
  "detail": "El empleado Diego Alonso ya tiene 3 préstamos activos (máximo: 3).",
  "instance": "/api/prestamos",
  "timestamp": "2026-08-05T10:23:45Z",
  "traceId": "a7f3e91c4b2d",
  "prestamosActivos": [12, 27, 38]
}

spring:
  mvc:
    problemdetails:
      enabled: true      # las excepciones estándar de Spring ya salen en formato RFC 7807

package com.nexussoftware.bibliotech.web.error;

@RestControllerAdvice
public class ManejadorGlobalErrores {

    private static final Logger log = LoggerFactory.getLogger(ManejadorGlobalErrores.class);
    private static final String BASE_TIPOS = "https://bibliotech.nexussoftware.com/errores/";

    // ---------- 404 ----------
    @ExceptionHandler({MaterialNoEncontradoException.class,
                       PrestamoNoEncontradoException.class,
                       EmpleadoNoEncontradoException.class})
    public ProblemDetail noEncontrado(RecursoNoEncontradoException e, HttpServletRequest peticion) {
        log.info("Recurso no encontrado: {}", e.getMessage());     // INFO: no es un fallo del sistema
        return problema(HttpStatus.NOT_FOUND, "recurso-no-encontrado",
                        "Recurso no encontrado", e.getMessage(), peticion);
    }

    // ---------- 409: reglas de negocio ----------
    @ExceptionHandler(LimiteDePrestamosExcedidoException.class)
    public ProblemDetail limiteExcedido(LimiteDePrestamosExcedidoException e, HttpServletRequest p) {
        ProblemDetail detalle = problema(HttpStatus.CONFLICT, "limite-prestamos",
                "Límite de préstamos excedido", e.getMessage(), p);
        detalle.setProperty("prestamosActivos", e.getIdsPrestamosActivos());
        detalle.setProperty("maximoPermitido", e.getMaximo());
        return detalle;
    }

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

    // ---------- 409: conflicto de concurrencia (el @Version de 11-03) ----------
    @ExceptionHandler(ObjectOptimisticLockingFailureException.class)
    public ProblemDetail conflictoDeVersion(ObjectOptimisticLockingFailureException e,
                                            HttpServletRequest p) {
        log.warn("Conflicto de bloqueo optimista en {}", p.getRequestURI());
        return problema(HttpStatus.CONFLICT, "conflicto-concurrencia",
                "Conflicto de concurrencia",
                "Otro usuario modificó este recurso mientras lo editabas. Recárgalo y reintenta.", p);
    }

    // ---------- 400: validación del cuerpo ----------
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail validacion(MethodArgumentNotValidException e, HttpServletRequest p) {
        List<ErrorCampo> errores = e.getBindingResult().getFieldErrors().stream()
                .map(f -> new ErrorCampo(f.getField(), f.getDefaultMessage(), f.getRejectedValue()))
                .toList();

        ProblemDetail detalle = problema(HttpStatus.BAD_REQUEST, "validacion",
                "Error de validación",
                "La petición contiene %d campo(s) inválido(s).".formatted(errores.size()), p);
        detalle.setProperty("errores", errores);     // ESTO es lo que hace útil un 400
        return detalle;
    }

    // ---------- 400: parámetros y tipos ----------
    @ExceptionHandler(ConstraintViolationException.class)
    public ProblemDetail parametrosInvalidos(ConstraintViolationException e, HttpServletRequest p) {
        List<ErrorCampo> errores = e.getConstraintViolations().stream()
                .map(v -> new ErrorCampo(v.getPropertyPath().toString(), v.getMessage(), v.getInvalidValue()))
                .toList();
        ProblemDetail detalle = problema(HttpStatus.BAD_REQUEST, "parametros-invalidos",
                "Parámetros inválidos", "Revisa los parámetros de la petición.", p);
        detalle.setProperty("errores", errores);
        return detalle;
    }

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ProblemDetail tipoIncorrecto(MethodArgumentTypeMismatchException e, HttpServletRequest p) {
        String esperado = e.getRequiredType() != null ? e.getRequiredType().getSimpleName() : "válido";
        return problema(HttpStatus.BAD_REQUEST, "tipo-incorrecto", "Tipo de dato incorrecto",
                "El parámetro '%s' con valor '%s' no es un %s."
                        .formatted(e.getName(), e.getValue(), esperado), p);
    }

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ProblemDetail cuerpoIlegible(HttpMessageNotReadableException e, HttpServletRequest p) {
        // NO exponemos e.getMessage(): revela la estructura interna de las clases
        return problema(HttpStatus.BAD_REQUEST, "cuerpo-invalido", "Cuerpo de la petición inválido",
                "El cuerpo no es un JSON válido o no encaja con el formato esperado.", p);
    }

    // ---------- 503: dependencia externa ----------
    @ExceptionHandler(ServicioExternoNoDisponibleException.class)
    public ResponseEntity<ProblemDetail> servicioCaido(ServicioExternoNoDisponibleException e,
                                                       HttpServletRequest p) {
        log.error("Servicio externo no disponible: {}", e.getServicio(), e);
        ProblemDetail detalle = problema(HttpStatus.SERVICE_UNAVAILABLE, "servicio-no-disponible",
                "Servicio temporalmente no disponible",
                "No se pudo completar la operación. Inténtalo de nuevo en unos minutos.", p);
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .header(HttpHeaders.RETRY_AFTER, "60")     // el cliente sabe cuándo reintentar
                .body(detalle);
    }

    // ---------- 500: la red de seguridad ----------
    @ExceptionHandler(Exception.class)
    public ProblemDetail errorNoPrevisto(Exception e, HttpServletRequest p) {
        String idIncidencia = UUID.randomUUID().toString().substring(0, 12);
        // La traza COMPLETA al log; al cliente, solo el identificador (06-07 y 12-07)
        log.error("Error no previsto [id={}] en {} {}", idIncidencia, p.getMethod(), p.getRequestURI(), e);

        ProblemDetail detalle = problema(HttpStatus.INTERNAL_SERVER_ERROR, "error-interno",
                "Error interno",
                "Se ha producido un error inesperado. Si el problema persiste, "
                + "contacta con soporte indicando el identificador de incidencia.", p);
        detalle.setProperty("idIncidencia", idIncidencia);
        return detalle;
    }

    // ---------- Constructor común ----------
    private ProblemDetail problema(HttpStatus estado, String tipo, String titulo,
                                   String detalleTexto, HttpServletRequest peticion) {
        ProblemDetail detalle = ProblemDetail.forStatusAndDetail(estado, detalleTexto);
        detalle.setType(URI.create(BASE_TIPOS + tipo));
        detalle.setTitle(titulo);
        detalle.setInstance(URI.create(peticion.getRequestURI()));
        detalle.setProperty("timestamp", Instant.now().toString());
        // El identificador de correlación que MDC puso en 11-07: une la respuesta con el log
        detalle.setProperty("traceId", MDC.get("traceId"));
        return detalle;
    }

    public record ErrorCampo(String campo, String mensaje, Object valorRechazado) { }
}

@GetMapping
public PageResponse<MaterialResponse> listar(
        @PageableDefault(size = 20, sort = "titulo", direction = Sort.Direction.ASC)
        Pageable paginacion) {

    Page<Material> pagina = catalogo.buscar(paginacion);
    return PageResponse.desde(pagina.map(MaterialResponse::desde));
}

GET /api/materiales?page=0&size=20&sort=titulo,asc
GET /api/materiales?page=2&size=50&sort=anioPublicacion,desc&sort=titulo,asc

spring:
  data:
    web:
      pageable:
        default-page-size: 20
        max-page-size: 100          # Spring recorta silenciosamente por encima
        one-indexed-parameters: false

public record PageResponse<T>(List<T> contenido, MetadatosPagina pagina) {

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

    public record MetadatosPagina(int numero, int tamano, long totalElementos,
                                  int totalPaginas, boolean primera, boolean ultima) { }
}

{
  "contenido": [ { "isbn": "978-0000000001", "titulo": "Java Efectivo", "…": "…" } ],
  "pagina": { "numero": 0, "tamano": 20, "totalElementos": 3,
              "totalPaginas": 1, "primera": true, "ultima": true }
}

public record CriterioMaterialesRequest(
        @Size(min = 2, max = 100) String titulo,
        @Size(min = 2, max = 100) String autor,
        TipoMaterial tipo,
        @Min(1450) Integer anioDesde,          // año de la imprenta: un límite razonable
        @Max(2100) Integer anioHasta,
        Boolean soloDisponibles) {

    public CriterioBusqueda aDominio() {
        return CriterioBusqueda.builder()      // el Builder de 12-02
                .titulo(titulo).autor(autor).tipo(tipo)
                .entre(anioDesde, anioHasta)
                .soloDisponibles(Boolean.TRUE.equals(soloDisponibles))
                .construir();
    }
}

@GetMapping
public PageResponse<MaterialResponse> listar(@Valid CriterioMaterialesRequest criterio,
                                             @PageableDefault(size = 20) Pageable paginacion) {
    Page<Material> resultados = catalogo.buscar(criterio.aDominio(), paginacion);
    return PageResponse.desde(resultados.map(MaterialResponse::desde));
}

GET /api/materiales?titulo=java&tipo=LIBRO&soloDisponibles=true&page=0&size=10

public Page<Material> buscar(CriterioBusqueda criterio, Pageable paginacion) {
    Specification<Material> spec = Specification.where(null);

    if (criterio.titulo() != null) {
        spec = spec.and((raiz, consulta, cb) ->
                cb.like(cb.lower(raiz.get("titulo")), "%" + criterio.titulo().toLowerCase() + "%"));
    }
    if (criterio.tipo() != null) {
        spec = spec.and((raiz, consulta, cb) -> cb.equal(raiz.get("tipo"), criterio.tipo()));
    }
    if (criterio.soloDisponibles()) {
        spec = spec.and((raiz, consulta, cb) -> cb.greaterThan(raiz.get("unidadesDisponibles"), 0));
    }
    return repositorio.findAll(spec, paginacion);
}

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

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

{
  "id": 42,
  "isbn": "978-0000000001",
  "tituloMaterial": "Java Efectivo",
  "nombreEmpleado": "Marta Ruiz",
  "fechaPrestamo": "2026-08-05",
  "fechaVencimiento": "2026-08-20",
  "fechaDevolucion": null,
  "estado": "ACTIVO",
  "diasRestantes": 15,
  "multaAcumulada": 0.00
}

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

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

{
  "type": "https://bibliotech.nexussoftware.com/errores/limite-prestamos",
  "title": "Límite de préstamos excedido",
  "status": 409,
  "detail": "El empleado Diego Alonso ya tiene 3 préstamos activos (máximo: 3).",
  "instance": "/api/prestamos",
  "timestamp": "2026-08-05T10:23:45Z",
  "traceId": "a7f3e91c4b2d",
  "prestamosActivos": [12, 27, 38],
  "maximoPermitido": 3
}

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

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

{
  "type": "https://bibliotech.nexussoftware.com/errores/validacion",
  "title": "Error de validación",
  "status": 400,
  "detail": "La petición contiene 3 campo(s) inválido(s).",
  "instance": "/api/prestamos",
  "errores": [
    {"campo": "isbn", "mensaje": "El ISBN debe empezar por 978 o 979 y tener 13 dígitos",
     "valorRechazado": "1234"},
    {"campo": "idEmpleado", "mensaje": "El identificador del empleado es obligatorio",
     "valorRechazado": null},
    {"campo": "dias", "mensaje": "La duración máxima es de 90 días", "valorRechazado": 365}
  ]
}

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

HTTP/1.1 200 OK

{
  "idPrestamo": 42,
  "fechaDevolucion": "2026-08-25",
  "diasDeRetraso": 5,
  "multa": 2.50,
  "estado": "DEVUELTO"
}

curl "http://localhost:8080/api/materiales?titulo=dise&tipo=LIBRO&page=0&size=5&sort=titulo,asc"

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

@RestController
@RequestMapping("/api/prestamos")
@Tag(name = "Préstamos", description = "Gestión de préstamos de materiales a empleados")
public class PrestamoController {

    @Operation(
        summary = "Crea un préstamo",
        description = """
                Presta un material a un empleado. Comprueba que haya unidades disponibles
                y que el empleado no supere el límite de préstamos activos.

                Si no se indica la duración, se usa la estándar del tipo de material:
                15 días para libros, 7 para revistas y 3 para DVD.""")
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "Préstamo creado",
            content = @Content(schema = @Schema(implementation = PrestamoResponse.class))),
        @ApiResponse(responseCode = "400", description = "Petición inválida",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
        @ApiResponse(responseCode = "404", description = "Material o empleado inexistente",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
        @ApiResponse(responseCode = "409", description = "Sin unidades libres o límite excedido",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
    })
    @PostMapping
    public ResponseEntity<PrestamoResponse> crear(@Valid @RequestBody CrearPrestamoRequest peticion) { … }
}

@Configuration
public class ConfiguracionOpenApi {

    @Bean
    OpenAPI apiBiblioTech(@Value("${bibliotech.version}") String version) {
        return new OpenAPI()
                .info(new Info()
                        .title("API de BiblioTech")
                        .version(version)
                        .description("Gestión de la biblioteca técnica interna de Nexus Software.")
                        .contact(new Contact().name("Equipo de plataforma")
                                              .email("[email protected]")))
                .servers(List.of(
                        new Server().url("http://localhost:8080").description("Desarrollo"),
                        new Server().url("https://bibliotech.nexussoftware.com").description("Producción")));
    }
}

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

OPTIONS /api/prestamos 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 ConfiguracionCors implements WebMvcConfigurer {

    private final List<String> origenesPermitidos;    // desde application.yml, por entorno

    @Override
    public void addCorsMappings(CorsRegistry registro) {
        registro.addMapping("/api/**")
                .allowedOrigins(origenesPermitidos.toArray(String[]::new))
                .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE")
                .allowedHeaders("Content-Type", "Authorization")
                .exposedHeaders("Location")            // para que el cliente pueda leerla tras un 201
                .allowCredentials(true)
                .maxAge(3600);                         // cachear la respuesta previa 1 hora
    }
}

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

// MAL: transacción en el controlador
@RestController
public class PrestamoController {
    @PostMapping
    @Transactional                          // ← no
    public PrestamoResponse crear(@RequestBody CrearPrestamoRequest p) { … }
}

// BIEN: la transacción, en el caso de uso
@Service
public class GestorPrestamos implements GestionarPrestamos {

    @Override
    @Transactional                                  // escritura
    public Prestamo prestar(Isbn isbn, Long idEmpleado, Integer dias) { … }

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

// Y el controlador solo traduce HTTP
@PostMapping
public ResponseEntity<PrestamoResponse> crear(@Valid @RequestBody CrearPrestamoRequest p) {
    Prestamo creado = gestor.prestar(p.isbn(), p.idEmpleado(), p.dias());
    return ResponseEntity.created(uriDe(creado)).body(PrestamoResponse.desde(creado, hoy()));
}

spring:
  jpa:
    open-in-view: false

@WebMvcTest(PrestamoController.class)
class PrestamoControllerTest {

    @Autowired MockMvc mvc;
    @Autowired ObjectMapper json;

    @MockitoBean GestionarPrestamos gestor;      // Spring Boot 3.4+; antes era @MockBean

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

        mvc.perform(post("/api/prestamos")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"978-0000000001","idEmpleado":1,"dias":15}"""))
                .andExpect(status().isCreated())
                .andExpect(header().string("Location", endsWith("/api/prestamos/42")))
                .andExpect(jsonPath("$.id").value(42))
                .andExpect(jsonPath("$.tituloMaterial").value("Java Efectivo"))
                .andExpect(jsonPath("$.estado").value("ACTIVO"));
    }

    @Test
    void devuelve400ConElDetalleDeCadaCampoInvalido() throws Exception {
        mvc.perform(post("/api/prestamos")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"1234","idEmpleado":null,"dias":365}"""))
                .andExpect(status().isBadRequest())
                .andExpect(content().contentTypeCompatibleWith("application/problem+json"))
                .andExpect(jsonPath("$.title").value("Error de validación"))
                .andExpect(jsonPath("$.errores", hasSize(3)))
                .andExpect(jsonPath("$.errores[*].campo",
                        containsInAnyOrder("isbn", "idEmpleado", "dias")));

        // Con datos inválidos, el caso de uso NO debe haberse invocado
        verifyNoInteractions(gestor);
    }

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

        mvc.perform(post("/api/prestamos")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"978-0000000003","idEmpleado":2,"dias":15}"""))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.type").value(endsWith("/errores/limite-prestamos")))
                .andExpect(jsonPath("$.detail").value(containsString("Diego Alonso")))
                .andExpect(jsonPath("$.prestamosActivos", hasSize(3)));
    }

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

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

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

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

    @Autowired TestRestTemplate cliente;
    @Autowired PrestamoRepository repositorio;

    @Test
    void cicloCompletoDePrestamoYDevolucion() {
        // 1. Crear
        var peticion = new CrearPrestamoRequest("978-0000000001", 1L, 15);
        ResponseEntity<PrestamoResponse> creacion =
                cliente.postForEntity("/api/prestamos", peticion, PrestamoResponse.class);

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

        // 2. Consultar por la URI que devolvió Location
        ResponseEntity<PrestamoResponse> consulta =
                cliente.getForEntity(creacion.getHeaders().getLocation(), PrestamoResponse.class);
        assertThat(consulta.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(consulta.getBody().estado()).isEqualTo("ACTIVO");

        // 3. Devolver
        ResponseEntity<DevolucionResponse> devolucion = cliente.postForEntity(
                "/api/prestamos/{id}/devolucion", new DevolucionRequest(null),
                DevolucionResponse.class, id);
        assertThat(devolucion.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(devolucion.getBody().multa()).isEqualByComparingTo("0.00");

        // 4. Verificar que la persistencia refleja el cambio
        assertThat(repositorio.findById(id))
                .get()
                .extracting(Prestamo::getEstado)
                .isEqualTo(EstadoPrestamo.DEVUELTO);
    }

    @Test
    void devolverDosVecesDevuelve409() {
        Long id = crearYDevolver();

        ResponseEntity<ProblemDetail> segunda = cliente.postForEntity(
                "/api/prestamos/{id}/devolucion", new DevolucionRequest(null),
                ProblemDetail.class, id);

        assertThat(segunda.getStatusCode()).isEqualTo(HttpStatus.CONFLICT);
        assertThat(segunda.getBody().getDetail()).contains("ya fue devuelto");
    }
}

@Controller                                   // ¡NO @RestController!
@RequestMapping("/catalogo")
public class CatalogoVistaController {

    @GetMapping
    public String listar(@RequestParam(required = false) String titulo, Model modelo) {
        modelo.addAttribute("materiales", catalogo.buscar(titulo));
        modelo.addAttribute("filtro", titulo);
        return "catalogo/lista";              // resuelve a templates/catalogo/lista.html
    }
}

<!-- src/main/resources/templates/catalogo/lista.html -->
<table>
  <tr th:each="m : ${materiales}">
    <td th:text="${m.isbn}">978-…</td>
    <td th:text="${m.titulo}">Título</td>
    <td th:text="${m.unidadesDisponibles}">0</td>
  </tr>
</table>

spring:
  threads:
    virtual:
      enabled: true

@GetMapping("/api/diagnostico/hilo")
public Map<String, Object> hiloActual() {
    Thread hilo = Thread.currentThread();
    return Map.of("nombre", hilo.getName(),
                  "virtual", hilo.isVirtual(),
                  "grupo", String.valueOf(hilo.threadId()));
}

{"nombre":"","virtual":true,"grupo":"142"}

public record RenovarPrestamoRequest(
        @Min(value = 1, message = "La renovación debe ser de al menos 1 día")
        @Max(value = 30, message = "La renovación no puede superar los 30 días")
        Integer dias) {
}

public record RenovacionResponse(
        Long idPrestamo,
        String tituloMaterial,
        LocalDate vencimientoAnterior,
        LocalDate vencimientoNuevo,
        int diasAnadidos,
        boolean puedeRenovarseDeNuevo) {

    public static RenovacionResponse desde(Prestamo p, LocalDate anterior) {
        return new RenovacionResponse(
                p.getId(), p.tituloDelMaterial(), anterior, p.getFechaVencimiento(),
                (int) ChronoUnit.DAYS.between(anterior, p.getFechaVencimiento()),
                p.getEstado().permiteRenovar());
    }
}

@PostMapping("/{id}/renovacion")
@Operation(summary = "Renueva un préstamo",
           description = "Amplía la fecha de vencimiento. Solo se permite una renovación por préstamo.")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "Renovado"),
    @ApiResponse(responseCode = "404", description = "El préstamo no existe"),
    @ApiResponse(responseCode = "409", description = "Ya renovado, vencido, o con reservas pendientes")
})
public RenovacionResponse renovar(
        @PathVariable Long id,
        @RequestBody(required = false) @Valid RenovarPrestamoRequest peticion) {

    Integer dias = (peticion != null) ? peticion.dias() : null;
    ResultadoRenovacion resultado = gestor.renovar(id, dias);
    return RenovacionResponse.desde(resultado.prestamo(), resultado.vencimientoAnterior());
}

@Override
@Transactional
public ResultadoRenovacion renovar(Long id, Integer dias) {
    Prestamo prestamo = repositorio.buscarPorId(id)
            .orElseThrow(() -> new PrestamoNoEncontradoException(id));

    LocalDate hoy = LocalDate.now(reloj);

    // Regla 1: el estado gobierna (patrón Estado, 12-02)
    if (!prestamo.getEstado().permiteRenovar()) {
        throw new RenovacionNoPermitidaException(id, prestamo.getEstado(),
                "Este préstamo ya fue renovado o no admite renovación.");
    }

    // Regla 2: vencido
    if (prestamo.estaVencidoA(hoy)) {
        throw new RenovacionNoPermitidaException(id, prestamo.getEstado(),
                "El préstamo venció el %s. Devuélvelo y vuelve a prestarlo."
                        .formatted(prestamo.getFechaVencimiento()));
    }

    // Regla 3: reservas de otros
    long pendientes = reservas.contarPendientesDe(prestamo.getIsbn());
    if (pendientes > 0) {
        throw new MaterialConReservasException(prestamo.getIsbn(), pendientes);
    }

    LocalDate anterior = prestamo.getFechaVencimiento();
    int diasEfectivos = (dias != null) ? dias : prestamo.diasEstandarDelMaterial();
    prestamo.renovar(diasEfectivos);          // valida y transita el estado

    return new ResultadoRenovacion(prestamo, anterior);
}

@ExceptionHandler(RenovacionNoPermitidaException.class)
public ProblemDetail renovacionNoPermitida(RenovacionNoPermitidaException e, HttpServletRequest p) {
    ProblemDetail d = problema(HttpStatus.CONFLICT, "renovacion-no-permitida",
            "Renovación no permitida", e.getMessage(), p);
    d.setProperty("idPrestamo", e.getIdPrestamo());
    d.setProperty("estadoActual", e.getEstado().name());
    return d;
}

@ExceptionHandler(MaterialConReservasException.class)
public ProblemDetail conReservas(MaterialConReservasException e, HttpServletRequest p) {
    ProblemDetail d = problema(HttpStatus.CONFLICT, "material-con-reservas",
            "Material con reservas pendientes",
            "No se puede renovar: hay %d empleado(s) esperando este material."
                    .formatted(e.getReservasPendientes()), p);
    d.setProperty("reservasPendientes", e.getReservasPendientes());
    return d;
}

@WebMvcTest(PrestamoController.class)
class RenovacionControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean GestionarPrestamos gestor;

    @Test
    void renuevaConLosDiasIndicados() throws Exception {
        var prestamo = unPrestamo(42L).conVencimiento(LocalDate.of(2026, 8, 20));
        when(gestor.renovar(42L, 10)).thenReturn(
                new ResultadoRenovacion(prestamo.renovadoHasta(LocalDate.of(2026, 8, 30)),
                                        LocalDate.of(2026, 8, 20)));

        mvc.perform(post("/api/prestamos/42/renovacion")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"dias":10}"""))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.vencimientoAnterior").value("2026-08-20"))
                .andExpect(jsonPath("$.vencimientoNuevo").value("2026-08-30"))
                .andExpect(jsonPath("$.diasAnadidos").value(10))
                .andExpect(jsonPath("$.puedeRenovarseDeNuevo").value(false));
    }

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

        mvc.perform(post("/api/prestamos/42/renovacion"))     // sin cuerpo
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.diasAnadidos").value(15));
    }

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

        mvc.perform(post("/api/prestamos/9999/renovacion"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.type").value(endsWith("/errores/recurso-no-encontrado")));
    }

    @Test
    void devuelve409SiYaFueRenovado() throws Exception {
        when(gestor.renovar(eq(42L), any())).thenThrow(
                new RenovacionNoPermitidaException(42L, EstadoPrestamo.RENOVADO,
                        "Este préstamo ya fue renovado o no admite renovación."));

        mvc.perform(post("/api/prestamos/42/renovacion"))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.estadoActual").value("RENOVADO"))
                .andExpect(jsonPath("$.detail").value(containsString("ya fue renovado")));
    }

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

        mvc.perform(post("/api/prestamos/42/renovacion"))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.reservasPendientes").value(2));
    }

    @ParameterizedTest
    @ValueSource(ints = {0, -5, 31, 100})
    void devuelve400SiLosDiasEstanFueraDeRango(int dias) throws Exception {
        mvc.perform(post("/api/prestamos/42/renovacion")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"dias\":%d}".formatted(dias)))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.errores[0].campo").value("dias"));

        verifyNoInteractions(gestor);      // ni siquiera se llamó al caso de uso
    }
}

@Documented
@Constraint(validatedBy = ValidadorRangoAnios.class)
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface RangoAniosValido {
    String message() default "anioDesde no puede ser posterior a anioHasta";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class ValidadorRangoAnios implements ConstraintValidator<RangoAniosValido, BusquedaRequest> {
    @Override
    public boolean isValid(BusquedaRequest r, ConstraintValidatorContext ctx) {
        if (r.anioDesde() == null || r.anioHasta() == null) return true;   // @NotNull no es cosa nuestra
        if (r.anioDesde() <= r.anioHasta()) return true;

        ctx.disableDefaultConstraintViolation();
        ctx.buildConstraintViolationWithTemplate(
                "anioDesde (%d) no puede ser posterior a anioHasta (%d)"
                        .formatted(r.anioDesde(), r.anioHasta()))
           .addPropertyNode("anioDesde")        // el error se asocia al campo correcto
           .addConstraintViolation();
        return false;
    }
}

@RangoAniosValido
public record BusquedaRequest(
        @NotBlank(message = "El texto de búsqueda es obligatorio")
        @Size(min = 2, max = 100, message = "Entre 2 y 100 caracteres")
        String q,

        List<TipoMaterial> tipo,          // repetible: ?tipo=LIBRO&tipo=DVD

        Boolean disponible,

        @Min(1450) @Max(2100) Integer anioDesde,
        @Min(1450) @Max(2100) Integer anioHasta) {

    /** Normalización: null → lista vacía, para no repetir comprobaciones aguas abajo. */
    public BusquedaRequest {
        tipo = (tipo == null) ? List.of() : List.copyOf(tipo);
    }

    public CriterioBusqueda aDominio() {
        return CriterioBusqueda.builder()
                .texto(q)
                .tipos(tipo)
                .soloDisponibles(Boolean.TRUE.equals(disponible))
                .entre(anioDesde, anioHasta)
                .construir();
    }
}

public record ResultadoBusquedaResponse(
        List<MaterialResponse> resultados,
        PageResponse.MetadatosPagina pagina,
        Map<String, Long> facetasPorTipo,
        long totalGlobal,
        String consulta) {

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

@GetMapping("/busqueda")
@Operation(summary = "Búsqueda avanzada con facetas por tipo de material")
public ResultadoBusquedaResponse buscar(
        @Valid BusquedaRequest criterio,
        @PageableDefault(size = 20, sort = "titulo") Pageable paginacion) {

    // Defensa en profundidad: aunque max-page-size esté configurado, no confíes
    if (paginacion.getPageSize() > 50) {
        paginacion = PageRequest.of(paginacion.getPageNumber(), 50, paginacion.getSort());
    }

    CriterioBusqueda dominio = criterio.aDominio();
    Page<Material> pagina = catalogo.buscar(dominio, paginacion);
    Map<TipoMaterial, Long> facetas = catalogo.contarPorTipo(dominio);   // consulta de agregación

    return ResultadoBusquedaResponse.desde(pagina, facetas, criterio.q());
}

@Query("""
       select m.tipo as tipo, count(m) as total
       from Material m
       where (lower(m.titulo) like lower(concat('%', :texto, '%'))
              or lower(m.autor) like lower(concat('%', :texto, '%')))
         and (:soloDisponibles = false or m.unidadesDisponibles > 0)
       group by m.tipo
       """)
List<FacetaTipo> contarPorTipo(@Param("texto") String texto,
                               @Param("soloDisponibles") boolean soloDisponibles);

@Test
void devuelveResultadosConFacetasPorTipo() throws Exception {
    when(catalogo.buscar(any(), any())).thenReturn(unaPaginaCon(2, "Java Efectivo", "Refactorización"));
    when(catalogo.contarPorTipo(any())).thenReturn(
            new LinkedHashMap<>(Map.of(TipoMaterial.LIBRO, 5L, TipoMaterial.DVD, 2L)));

    mvc.perform(get("/api/materiales/busqueda").param("q", "java").param("tipo", "LIBRO"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.resultados", hasSize(2)))
            .andExpect(jsonPath("$.facetasPorTipo.LIBRO").value(5))
            .andExpect(jsonPath("$.totalGlobal").value(7))
            .andExpect(jsonPath("$.consulta").value("java"));
}

@Test
void rechazaConsultasDemasiadoCortas() throws Exception {
    mvc.perform(get("/api/materiales/busqueda").param("q", "j"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errores[0].campo").value("q"));
}

@Test
void rechazaUnRangoDeAniosInvertido() throws Exception {
    mvc.perform(get("/api/materiales/busqueda")
                    .param("q", "java").param("anioDesde", "2020").param("anioHasta", "2010"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errores[0].campo").value("anioDesde"))
            .andExpect(jsonPath("$.errores[0].mensaje").value(containsString("no puede ser posterior")));
}

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

@Entity
@Table(name = "claves_idempotencia",
       indexes = @Index(name = "idx_caducidad", columnList = "caducaEn"))
public class ClaveIdempotencia {

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

    @Column(nullable = false, length = 64)
    private String huellaPeticion;     // hash del cuerpo: detecta reutilización con datos distintos

    @Enumerated(EnumType.STRING)
    private EstadoClave estado;        // EN_CURSO, COMPLETADA

    private Integer codigoRespuesta;

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

    private String ubicacion;
    private Instant creadaEn;
    private Instant caducaEn;

    public enum EstadoClave { EN_CURSO, COMPLETADA }
}

@Component
public class InterceptorIdempotencia implements HandlerInterceptor {

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

    private final RepositorioClavesIdempotencia repositorio;
    private final ObjectMapper json;
    private final Clock reloj;

    @Override
    public boolean preHandle(HttpServletRequest peticion, HttpServletResponse respuesta,
                             Object manejador) throws IOException {

        // Solo aplica a métodos no idempotentes por naturaleza
        if (!"POST".equals(peticion.getMethod())) return true;

        String clave = peticion.getHeader(CABECERA);
        if (clave == null || clave.isBlank()) return true;     // cabecera opcional

        String huella = huellaDe(peticion);

        // INSERT condicional: la restricción de clave primaria resuelve la carrera
        // entre dos peticiones simultáneas con la misma clave. NO uses "SELECT y luego INSERT".
        Optional<ClaveIdempotencia> existente = repositorio.reservarSiNoExiste(
                clave, huella, Instant.now(reloj), Instant.now(reloj).plus(VIGENCIA));

        if (existente.isEmpty()) {
            // La hemos reservado nosotros: seguimos con el procesamiento normal
            peticion.setAttribute("idempotencia.clave", clave);
            return true;
        }

        ClaveIdempotencia previa = existente.get();

        // Misma clave, cuerpo distinto: el cliente se ha equivocado
        if (!previa.getHuellaPeticion().equals(huella)) {
            escribirProblema(respuesta, HttpStatus.UNPROCESSABLE_ENTITY,
                    "La clave de idempotencia ya se usó con un cuerpo diferente.");
            return false;
        }

        if (previa.getEstado() == EstadoClave.EN_CURSO) {
            // Otra petición idéntica se está procesando ahora mismo
            respuesta.setHeader(HttpHeaders.RETRY_AFTER, "2");
            escribirProblema(respuesta, HttpStatus.CONFLICT,
                    "Ya hay una petición en curso con esta clave de idempotencia.");
            return false;
        }

        // COMPLETADA: reproducimos la respuesta original sin ejecutar nada
        log.info("Reproduciendo respuesta idempotente para la clave {}", clave);
        respuesta.setStatus(previa.getCodigoRespuesta());
        respuesta.setContentType(MediaType.APPLICATION_JSON_VALUE);
        respuesta.setHeader("Idempotent-Replay", "true");
        if (previa.getUbicacion() != null) {
            respuesta.setHeader(HttpHeaders.LOCATION, previa.getUbicacion());
        }
        respuesta.getWriter().write(previa.getCuerpoRespuesta());
        return false;                       // NO se llama al controlador
    }

    private String huellaDe(HttpServletRequest peticion) throws IOException {
        // Requiere ContentCachingRequestWrapper: el cuerpo solo se puede leer una vez
        byte[] cuerpo = ((ContentCachingRequestWrapper) peticion).getContentAsByteArray();
        return HexFormat.of().formatHex(
                MessageDigest.getInstance("SHA-256").digest(cuerpo));
    }
}

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

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

        var peticionCacheada = new ContentCachingRequestWrapper(peticion);
        var respuestaCacheada = new ContentCachingResponseWrapper(respuesta);

        try {
            cadena.doFilter(peticionCacheada, respuestaCacheada);

            String clave = (String) peticion.getAttribute("idempotencia.clave");
            if (clave != null) {
                int estado = respuestaCacheada.getStatus();
                if (estado >= 200 && estado < 300) {
                    // Solo se memoriza el éxito: un 500 debe poder reintentarse
                    repositorio.completar(clave, estado,
                            new String(respuestaCacheada.getContentAsByteArray(), UTF_8),
                            respuestaCacheada.getHeader(HttpHeaders.LOCATION));
                } else {
                    repositorio.liberar(clave);    // libera la clave para un reintento legítimo
                }
            }
        } finally {
            respuestaCacheada.copyBodyToResponse();   // IMPRESCINDIBLE: sin esto no llega nada al cliente
        }
    }
}

@Repository
public class RepositorioClavesIdempotencia {

    private final JdbcTemplate jdbc;

    /**
     * Devuelve Optional.empty() si la clave se ha reservado ahora (somos los primeros),
     * o la fila existente si ya estaba.
     *
     * ON CONFLICT DO NOTHING hace la operación ATÓMICA en la base de datos:
     * dos peticiones simultáneas con la misma clave no pueden reservarla ambas.
     * Un "SELECT y luego INSERT" en Java tendría una ventana de carrera.
     */
    public Optional<ClaveIdempotencia> reservarSiNoExiste(String clave, String huella,
                                                          Instant ahora, Instant caduca) {
        int filas = jdbc.update("""
                insert into claves_idempotencia
                       (clave, huella_peticion, estado, creada_en, caduca_en)
                values (?, ?, 'EN_CURSO', ?, ?)
                on conflict (clave) do nothing
                """, clave, huella, Timestamp.from(ahora), Timestamp.from(caduca));

        if (filas == 1) return Optional.empty();      // la hemos reservado nosotros

        return jdbc.query("select * from claves_idempotencia where clave = ?",
                          this::mapear, clave).stream().findFirst();
    }
}

@Scheduled(cron = "0 0 3 * * *")     // cada día a las 3:00
@Transactional
public void purgarClavesCaducadas() {
    int borradas = repositorio.borrarCaducadasAntesDe(Instant.now(reloj));
    log.info("Claves de idempotencia purgadas: {}", borradas);
}

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

# Reintento con la misma clave
curl -i -X POST … -H "Idempotency-Key: $CLAVE" -d '{…}'
# → 201 Created, Location: /api/prestamos/42, Idempotent-Replay: true
#   (y NO se ha creado un segundo préstamo)