@Service
public class GestorPrestamos {

    public void prestar(String isbn, Long idEmpleado, int dias) {
        // 1. Validación de entrada
        if (isbn == null || !isbn.matches("97[89]-\\d{10}")) {
            throw new IllegalArgumentException("ISBN inválido");
        }
        // 2. Acceso a datos
        Material m = em.createQuery("select m from Material m where m.isbn = :i", Material.class)
                       .setParameter("i", isbn).getSingleResult();
        // 3. Reglas de negocio
        long activos = em.createQuery("select count(p) from Prestamo p where …").getSingleResult();
        if (activos >= 3) throw new LimiteExcedidoException();
        // 4. Persistencia
        Prestamo p = new Prestamo(m, empleado, LocalDate.now(), LocalDate.now().plusDays(dias));
        em.persist(p);
        // 5. Notificación
        smtp.enviar(empleado.getCorreo(), "Préstamo confirmado", "Has cogido " + m.getTitulo());
        // 6. Formato de salida
        System.out.printf("%-40s %s%n", m.getTitulo(), p.getFechaVencimiento());
        // 7. Auditoría
        Files.writeString(Path.of("auditoria.log"), LocalDateTime.now() + " PRESTAMO " + isbn + "\n",
                          StandardOpenOption.APPEND);
    }
}

// DOMINIO: la regla, y solo la regla
public class PoliticaPrestamos {
    private final int maximoActivos;

    public void verificarPuedePrestar(Empleado empleado, List<Prestamo> activos) {
        if (activos.size() >= maximoActivos) {
            throw new LimiteDePrestamosExcedidoException(empleado.getNombre(), maximoActivos);
        }
        if (empleado.tieneMultasPendientes()) {
            throw new MultasPendientesException(empleado.getNombre());
        }
    }
}

// APLICACIÓN: orquestación, y solo orquestación
public class GestorPrestamos implements GestionarPrestamos {

    private final RepositorioMateriales materiales;
    private final RepositorioPrestamos prestamos;
    private final RepositorioEmpleados empleados;
    private final PoliticaPrestamos politica;
    private final NotificadorAvisos notificador;
    private final Clock reloj;

    @Override
    public Prestamo prestar(Isbn isbn, Long idEmpleado, int dias) {
        Material material = materiales.buscarPorIsbn(isbn)
                .orElseThrow(() -> new MaterialNoEncontradoException(isbn));
        Empleado empleado = empleados.buscarPorId(idEmpleado)
                .orElseThrow(() -> new EmpleadoNoEncontradoException(idEmpleado));

        politica.verificarPuedePrestar(empleado, prestamos.activosDe(empleado));

        Prestamo prestamo = Prestamo.nuevo(material, empleado, LocalDate.now(reloj), dias);
        prestamos.guardar(prestamo);
        notificador.notificar(Aviso.porPrestamo(prestamo));
        return prestamo;
    }
}

public int diasDePrestamo(Material material) {
    switch (material.getTipo()) {
        case LIBRO:   return 15;
        case REVISTA: return 7;
        case DVD:     return 3;
        default: throw new IllegalStateException("Tipo desconocido: " + material.getTipo());
    }
}

public abstract class Material {
    // Cada subtipo responde por sí mismo; el resto del sistema no cambia.
    public abstract int diasDePrestamoPorDefecto();
    public abstract Dinero multaPorDia();
}

public class Libro extends Material {
    @Override public int diasDePrestamoPorDefecto() { return 15; }
    @Override public Dinero multaPorDia() { return Dinero.euros("0.50"); }
}

public class Revista extends Material {
    @Override public int diasDePrestamoPorDefecto() { return 7; }
    @Override public Dinero multaPorDia() { return Dinero.euros("0.25"); }
}

public class Dvd extends Material {
    @Override public int diasDePrestamoPorDefecto() { return 3; }
    @Override public Dinero multaPorDia() { return Dinero.euros("1.00"); }
}

public class MaterialDeReferencia extends Libro {

    @Override
    public Prestamo prestarA(Empleado empleado, int dias) {
        throw new UnsupportedOperationException("Los materiales de referencia no se prestan");
    }
}

// Este método era correcto. Ahora explota en producción cuando Diego Alonso
// añade un material de referencia al carrito de préstamo.
public void prestarTodos(List<Material> materiales, Empleado empleado) {
    for (Material m : materiales) {
        m.prestarA(empleado, m.diasDePrestamoPorDefecto());   // UnsupportedOperationException
    }
}

/** No todo material es prestable. La capacidad se modela aparte del tipo. */
public interface Prestable {
    Prestamo prestarA(Empleado empleado, int dias);
    int diasDePrestamoPorDefecto();
}

public abstract class Material {                 // todos: título, ISBN, ubicación
    public abstract String getTitulo();
    public abstract Isbn getIsbn();
}

public class Libro extends Material implements Prestable { … }
public class MaterialDeReferencia extends Material { }   // simplemente NO es Prestable

public void prestarTodos(List<Prestable> materiales, Empleado empleado) { … }
// Ya es IMPOSIBLE pasarle un MaterialDeReferencia.

public interface GestionBiblioteca {
    Prestamo prestar(Isbn isbn, Long idEmpleado, int dias);
    void devolver(Long idPrestamo);
    void reservar(Isbn isbn, Long idEmpleado);
    void enviarAviso(Aviso aviso);
    InformeMensual generarInforme(YearMonth periodo);
    void importarCatalogo(Path fichero);
    void exportarCatalogo(Path destino);
}

public interface Prestable {
    Prestamo prestarA(Empleado empleado, int dias);
}

public interface Notificable {
    String destinoDeNotificacion();
}

public interface GestionarPrestamos {           // puerto de entrada del caso de uso
    Prestamo prestar(Isbn isbn, Long idEmpleado, int dias);
    void devolver(Long idPrestamo);
}

public interface ConsultarCatalogo {
    List<Material> buscar(CriterioBusqueda criterio);
    Optional<Material> porIsbn(Isbn isbn);
}

public class GestorPrestamos {
    // La política de alto nivel depende de un detalle de bajo nivel.
    private final PrestamoRepositoryJpa repositorio = new PrestamoRepositoryJpa();
    private final ClienteMetadatosHttp metadatos = new ClienteMetadatosHttp();
}

public class GestorPrestamos {
    private final RepositorioPrestamos repositorio;   // abstracción definida en el dominio
    private final PasarelaMetadatos metadatos;

    public GestorPrestamos(RepositorioPrestamos repositorio, PasarelaMetadatos metadatos) {
        this.repositorio = repositorio;
        this.metadatos = metadatos;
    }
}

// VIOLACIÓN: cuatro niveles de profundidad. Conoces toda la estructura interna.
String ciudad = prestamo.getEmpleado().getDepartamento().getSede().getDireccion().getCiudad();

// CORRECTO: cada objeto expone lo que le preguntan, y oculta cómo lo sabe.
String ciudad = prestamo.ciudadDelEmpleado();

// en Prestamo
public String ciudadDelEmpleado() { return empleado.ciudad(); }
// en Empleado
public String ciudad() { return departamento.ciudad(); }

public class ConfiguracionBiblioTech {

    private static final ConfiguracionBiblioTech INSTANCIA = new ConfiguracionBiblioTech();

    private ConfiguracionBiblioTech() { }          // nadie más puede construirla

    public static ConfiguracionBiblioTech getInstancia() { return INSTANCIA; }
}

public enum ConfiguracionBiblioTech {
    INSTANCIA;

    private final int diasPorDefecto = 15;
    public int diasPorDefecto() { return diasPorDefecto; }
}

public final class FabricaMateriales {

    private FabricaMateriales() { }

    public static Material desde(RegistroImportacion registro) {
        return switch (registro.tipo()) {
            case LIBRO   -> new Libro(registro.titulo(), new Isbn(registro.isbn()),
                                      registro.autor(), registro.paginas());
            case REVISTA -> new Revista(registro.titulo(), new Isbn(registro.isbn()),
                                        registro.numero(), registro.periodicidad());
            case DVD     -> new Dvd(registro.titulo(), new Isbn(registro.isbn()),
                                    registro.duracionMinutos());
        };
    }
}

public class Prestamo {

    private Prestamo(...) { }   // constructor privado: la creación pasa por las fábricas

    /** Préstamo estándar, con los días por defecto del material. */
    public static Prestamo nuevo(Material material, Empleado empleado, LocalDate hoy) {
        return new Prestamo(material, empleado, hoy,
                            hoy.plusDays(material.diasDePrestamoPorDefecto()),
                            EstadoPrestamo.ACTIVO);
    }

    /** Préstamo prorrogado por dirección: hasta 90 días. */
    public static Prestamo especial(Material material, Empleado empleado, LocalDate hoy, int dias) {
        if (dias > 90) throw new IllegalArgumentException("Máximo 90 días");
        return new Prestamo(material, empleado, hoy, hoy.plusDays(dias), EstadoPrestamo.ACTIVO);
    }
}

public interface FabricaExportacion {
    GeneradorInforme generador();
    FormateadorTabla formateadorTabla();
    String extension();

    static FabricaExportacion para(Formato formato) {
        return switch (formato) {
            case PDF  -> new FabricaPdf();
            case CSV  -> new FabricaCsv();
            case JSON -> new FabricaJson();
        };
    }
}

// ¿Qué significa el 15? ¿Y el true? ¿Y el segundo null?
Prestamo p = new Prestamo(material, empleado, LocalDate.now(), 15, true, null, false, null, "Marta Ruiz");

public class Prestamo {

    private final Material material;
    private final Empleado empleado;
    private final LocalDate fechaPrestamo;
    private final LocalDate fechaVencimiento;
    private final boolean renovable;
    private final String observaciones;
    private final Empleado autorizadoPor;
    private final EstadoPrestamo estado;

    private Prestamo(Builder b) {
        this.material = b.material;
        this.empleado = b.empleado;
        this.fechaPrestamo = b.fechaPrestamo;
        this.fechaVencimiento = b.fechaVencimiento;
        this.renovable = b.renovable;
        this.observaciones = b.observaciones;
        this.autorizadoPor = b.autorizadoPor;
        this.estado = EstadoPrestamo.ACTIVO;
    }

    public static Builder de(Material material, Empleado empleado) {
        return new Builder(material, empleado);      // obligatorios en la fábrica del builder
    }

    public static class Builder {
        // Obligatorios: final, exigidos en el constructor del builder
        private final Material material;
        private final Empleado empleado;
        // Opcionales: con valor por defecto sensato
        private LocalDate fechaPrestamo = LocalDate.now();
        private LocalDate fechaVencimiento;
        private boolean renovable = true;
        private String observaciones = "";
        private Empleado autorizadoPor;

        private Builder(Material material, Empleado empleado) {
            this.material = Objects.requireNonNull(material, "material");
            this.empleado = Objects.requireNonNull(empleado, "empleado");
        }

        public Builder desde(LocalDate fecha)      { this.fechaPrestamo = fecha; return this; }
        public Builder durante(int dias)           { this.fechaVencimiento = fechaPrestamo.plusDays(dias); return this; }
        public Builder hasta(LocalDate fecha)      { this.fechaVencimiento = fecha; return this; }
        public Builder noRenovable()               { this.renovable = false; return this; }
        public Builder conObservaciones(String o)  { this.observaciones = o; return this; }
        public Builder autorizadoPor(Empleado e)   { this.autorizadoPor = e; return this; }

        public Prestamo construir() {
            // La validación de coherencia se hace UNA VEZ, aquí:
            // así el objeto construido es siempre válido.
            if (fechaVencimiento == null) {
                fechaVencimiento = fechaPrestamo.plusDays(material.diasDePrestamoPorDefecto());
            }
            if (fechaVencimiento.isBefore(fechaPrestamo)) {
                throw new IllegalStateException("El vencimiento no puede ser anterior al préstamo");
            }
            if (!material.esPrestable() && autorizadoPor == null) {
                throw new IllegalStateException("Un material restringido requiere autorización");
            }
            return new Prestamo(this);
        }
    }
}

Prestamo p = Prestamo.de(javaEfectivo, martaRuiz)
        .desde(LocalDate.of(2026, 3, 1))
        .durante(30)
        .noRenovable()
        .conObservaciones("Para el curso interno de Java")
        .autorizadoPor(nuriaVidal)
        .construir();

public record CriterioBusqueda(String titulo, String autor, TipoMaterial tipo,
                               Integer anioDesde, Integer anioHasta, Boolean soloDisponibles) {

    public static Builder builder() { return new Builder(); }

    public static class Builder {
        private String titulo; private String autor; private TipoMaterial tipo;
        private Integer anioDesde; private Integer anioHasta;
        private Boolean soloDisponibles = Boolean.FALSE;

        public Builder titulo(String t) { this.titulo = t; return this; }
        public Builder autor(String a)  { this.autor = a; return this; }
        public Builder tipo(TipoMaterial t) { this.tipo = t; return this; }
        public Builder entre(int desde, int hasta) { this.anioDesde = desde; this.anioHasta = hasta; return this; }
        public Builder soloDisponibles() { this.soloDisponibles = true; return this; }

        public CriterioBusqueda construir() {
            return new CriterioBusqueda(titulo, autor, tipo, anioDesde, anioHasta, soloDisponibles);
        }
    }
}

public record CriterioBusqueda(String titulo, String autor, TipoMaterial tipo, …) {

    public CriterioBusqueda conTipo(TipoMaterial nuevo) {
        return new CriterioBusqueda(titulo, autor, nuevo, anioDesde, anioHasta, soloDisponibles);
    }
}

package com.nexussoftware.bibliotech.dominio.catalogo.puerto;

public interface PasarelaMetadatos {
    /** Vacío si no hay metadatos o si el servicio no está disponible. */
    Optional<MetadatosMaterial> buscar(Isbn isbn);
}

package com.nexussoftware.bibliotech.infraestructura.metadatos;

@Component
class AdaptadorMetadatosHttp implements PasarelaMetadatos {

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

    private final ClienteMetadatos cliente;   // el "adaptee": la clase con interfaz incompatible

    AdaptadorMetadatosHttp(ClienteMetadatos cliente) { this.cliente = cliente; }

    @Override
    public Optional<MetadatosMaterial> buscar(Isbn isbn) {
        try {
            RespuestaApiDto dto = cliente.consultarPorIsbn(isbn.valor());   // formato externo

            // 1. Traduce el modelo externo al del dominio
            // 2. Traduce las excepciones (frontera de errores, 06-07)
            // 3. Aísla el dominio de que existan HTTP, JSON y esta API concreta
            return Optional.of(new MetadatosMaterial(
                    dto.title(),
                    dto.authors() == null ? List.of() : dto.authors(),
                    dto.publishedDate() == null ? null : Year.parse(dto.publishedDate().substring(0, 4)),
                    dto.pageCount()));

        } catch (RecursoNoEncontradoException e) {
            return Optional.empty();                     // "no hay datos" no es un error
        } catch (IOException | InterruptedException e) {
            if (e instanceof InterruptedException) Thread.currentThread().interrupt();
            log.warn("Metadatos no disponibles para {}: {}", isbn, e.getMessage());
            return Optional.empty();                     // degradación elegante
        }
    }
}

// Cada envoltorio AÑADE una capacidad al anterior, y todos son InputStream.
InputStream base       = Files.newInputStream(Path.of("catalogo.csv"));  // bytes crudos
InputStream buferizado = new BufferedInputStream(base);                  // + búfer
InputStream descomp    = new GZIPInputStream(buferizado);                // + descompresión
Reader      lector     = new InputStreamReader(descomp, UTF_8);          // + codificación
BufferedReader lineas  = new BufferedReader(lector);                     // + readLine()

/**
 * Decorador: ES un RepositorioMateriales y TIENE un RepositorioMateriales.
 * Esa doble relación es la firma del patrón.
 */
public class CatalogoConCache implements RepositorioMateriales {

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

    private final RepositorioMateriales delegado;
    private final Map<Isbn, Material> cache = new ConcurrentHashMap<>();   // módulo 8

    public CatalogoConCache(RepositorioMateriales delegado) {
        this.delegado = delegado;
    }

    @Override
    public Optional<Material> buscarPorIsbn(Isbn isbn) {
        Material enCache = cache.get(isbn);
        if (enCache != null) {
            log.debug("Acierto de caché para {}", isbn);
            return Optional.of(enCache);
        }
        Optional<Material> resultado = delegado.buscarPorIsbn(isbn);
        resultado.ifPresent(m -> cache.put(isbn, m));
        return resultado;
    }

    @Override
    public List<Material> buscar(CriterioBusqueda criterio) {
        return delegado.buscar(criterio);      // las búsquedas no se cachean: son variables
    }

    @Override
    public Material guardar(Material material) {
        cache.remove(material.getIsbn());      // invalidación: lo más difícil de una caché
        return delegado.guardar(material);
    }
}

@Bean
RepositorioMateriales repositorioMateriales(RepositorioMaterialesJpa jpa, MeterRegistry registro) {
    return new CatalogoConMetricas(          // 3.º: mide
             new CatalogoConCache(           // 2.º: cachea
               new CatalogoConReintentos(jpa, 3)));   // 1.º: reintenta
}

// Proxy dinámico del módulo 10-03: registra el tiempo de cada llamada
@SuppressWarnings("unchecked")
public static <T> T conCronometro(T objetivo, Class<T> interfaz) {
    return (T) Proxy.newProxyInstance(
        interfaz.getClassLoader(),
        new Class<?>[]{interfaz},
        (proxy, metodo, args) -> {
            long inicio = System.nanoTime();
            try {
                return metodo.invoke(objetivo, args);
            } finally {
                long ms = (System.nanoTime() - inicio) / 1_000_000;
                LoggerFactory.getLogger(interfaz).debug("{} tardó {} ms", metodo.getName(), ms);
            }
        });
}

@Service
public class GestorPrestamos {
    @Transactional
    public Prestamo prestar(Isbn isbn, Long idEmpleado, int dias) { … }
}

public interface ElementoCatalogo {
    String titulo();
    int unidadesDisponibles();
}

public class Libro implements ElementoCatalogo { … }              // hoja

public class ColeccionTematica implements ElementoCatalogo {      // compuesto
    private final String titulo;
    private final List<ElementoCatalogo> elementos;

    @Override
    public int unidadesDisponibles() {
        // Disponible si TODOS sus elementos lo están: el mínimo manda
        return elementos.stream().mapToInt(ElementoCatalogo::unidadesDisponibles).min().orElse(0);
    }
}

public Dinero calcularMulta(Prestamo p, LocalDate hoy) {
    int retraso = (int) ChronoUnit.DAYS.between(p.getFechaVencimiento(), hoy);
    if (retraso <= 0) return Dinero.CERO;

    if (p.getEmpleado().antiguedadEnMeses() < 6) {
        return Dinero.euros("0.25").por(retraso);
    } else if (p.getMaterial().esCritico()) {
        return Dinero.euros("2.00").por(retraso);
    } else if (p.getEmpleado().esDireccion()) {
        return Dinero.CERO;
    } else {
        return Dinero.euros("0.50").por(retraso);
    }
}

@FunctionalInterface
public interface ReglaTarifa {
    Dinero calcular(int diasDeRetraso, Prestamo prestamo);

    default boolean aplicaA(Prestamo prestamo) { return true; }
}

public class TarifaEstandar implements ReglaTarifa {
    @Override public Dinero calcular(int dias, Prestamo p) {
        return p.getMaterial().multaPorDia().por(dias).limitadaA(Dinero.euros("20.00"));
    }
}

public class TarifaReducidaEmpleadoNuevo implements ReglaTarifa {
    @Override public boolean aplicaA(Prestamo p) { return p.getEmpleado().antiguedadEnMeses() < 6; }
    @Override public Dinero calcular(int dias, Prestamo p) { return Dinero.euros("0.25").por(dias); }
}

public class TarifaExentaDireccion implements ReglaTarifa {
    @Override public boolean aplicaA(Prestamo p) { return p.getEmpleado().esDireccion(); }
    @Override public Dinero calcular(int dias, Prestamo p) { return Dinero.CERO; }
}

public class CalculadoraMultas {
    private final List<ReglaTarifa> reglas;      // ordenadas: la primera que aplica, gana
    private final ReglaTarifa porDefecto = new TarifaEstandar();

    public CalculadoraMultas(List<ReglaTarifa> reglas) { this.reglas = List.copyOf(reglas); }

    public Dinero calcular(Prestamo p, LocalDate hoy) {
        int retraso = (int) ChronoUnit.DAYS.between(p.getFechaVencimiento(), hoy);
        if (retraso <= 0) return Dinero.CERO;

        return reglas.stream()
                .filter(r -> r.aplicaA(p))
                .findFirst()
                .orElse(porDefecto)
                .calcular(retraso, p);
    }
}

@Component @Order(10) class TarifaExentaDireccion implements ReglaTarifa { … }
@Component @Order(20) class TarifaReducidaEmpleadoNuevo implements ReglaTarifa { … }

@Service
class CalculadoraMultas {
    private final List<ReglaTarifa> reglas;
    CalculadoraMultas(List<ReglaTarifa> reglas) { this.reglas = reglas; }   // Spring inyecta todas
}

public abstract class ImportadorCatalogo {

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

    private final RepositorioMateriales repositorio;

    protected ImportadorCatalogo(RepositorioMateriales repositorio) {
        this.repositorio = repositorio;
    }

    /**
     * MÉTODO PLANTILLA: define el algoritmo y es final para que nadie
     * pueda alterar la secuencia. Solo los pasos son sustituibles.
     */
    public final ResultadoImportacion importar(Path origen) {
        log.info("Iniciando importación desde {}", origen);
        long inicio = System.nanoTime();

        int correctos = 0;
        List<ErrorImportacion> errores = new ArrayList<>();

        try (Origen o = abrir(origen)) {                       // PASO ABSTRACTO
            for (RegistroImportacion registro : leerRegistros(o)) {   // PASO ABSTRACTO
                try {
                    if (!validar(registro)) {                  // GANCHO con implementación por defecto
                        errores.add(ErrorImportacion.invalido(registro));
                        continue;
                    }
                    repositorio.guardar(FabricaMateriales.desde(registro));
                    correctos++;
                } catch (Exception e) {
                    errores.add(ErrorImportacion.de(registro, e));
                }
            }
        } catch (IOException e) {
            throw new ImportacionFallidaException(origen, e);
        }

        long ms = (System.nanoTime() - inicio) / 1_000_000;
        alTerminar(correctos, errores);                        // GANCHO opcional
        log.info("Importación terminada: {} correctos, {} errores, {} ms",
                 correctos, errores.size(), ms);
        return new ResultadoImportacion(correctos, errores, Duration.ofMillis(ms));
    }

    // --- Pasos que cada subclase DEBE aportar ---
    protected abstract Origen abrir(Path ruta) throws IOException;
    protected abstract List<RegistroImportacion> leerRegistros(Origen origen) throws IOException;

    // --- Ganchos: comportamiento por defecto, sustituible ---
    protected boolean validar(RegistroImportacion r) {
        return r.isbn() != null && r.titulo() != null && !r.titulo().isBlank();
    }

    protected void alTerminar(int correctos, List<ErrorImportacion> errores) { }
}

public class ImportadorCsv extends ImportadorCatalogo {

    private final char separador;

    @Override
    protected Origen abrir(Path ruta) throws IOException {
        return new OrigenLector(Files.newBufferedReader(ruta, StandardCharsets.UTF_8));
    }

    @Override
    protected List<RegistroImportacion> leerRegistros(Origen origen) throws IOException {
        try (CSVReader csv = new CSVReaderBuilder(origen.lector())
                .withSkipLines(1)
                .withCSVParser(new CSVParserBuilder().withSeparator(separador).build())
                .build()) {
            return csv.readAll().stream().map(this::aRegistro).toList();
        }
    }
}

public interface OyenteDevolucion {
    void alDevolver(EventoDevolucion evento);
}

public class GestorPrestamos {
    private final List<OyenteDevolucion> oyentes = new CopyOnWriteArrayList<>();  // módulo 8

    public void registrar(OyenteDevolucion oyente) { oyentes.add(oyente); }

    public void devolver(Long id) {
        Prestamo p = …;
        p.registrarDevolucion(LocalDate.now(reloj));
        prestamos.guardar(p);

        EventoDevolucion evento = new EventoDevolucion(p.getId(), p.getIsbn(), …);
        for (OyenteDevolucion oyente : oyentes) {
            try {
                oyente.alDevolver(evento);
            } catch (Exception e) {
                // Un oyente que falla NO puede impedir que se ejecuten los demás
                log.error("Oyente {} falló", oyente.getClass().getSimpleName(), e);
            }
        }
    }
}

// El evento: un record inmutable
public record MaterialDevuelto(Long idPrestamo, Isbn isbn, Long idEmpleado,
                               LocalDate fecha, Dinero multa) { }

// El emisor: no conoce a ningún oyente
@Service
public class GestorPrestamos {

    private final ApplicationEventPublisher eventos;

    @Transactional
    public void devolver(Long id) {
        Prestamo p = prestamos.buscarPorId(id).orElseThrow(…);
        Dinero multa = p.registrarDevolucion(LocalDate.now(reloj));
        prestamos.guardar(p);

        eventos.publishEvent(new MaterialDevuelto(p.getId(), p.getIsbn(),
                                                  p.getIdEmpleado(), LocalDate.now(reloj), multa));
    }
}

// Los oyentes: independientes, añadir uno no toca el emisor
@Component
class ActivadorReservas {
    @EventListener
    void alDevolver(MaterialDevuelto evento) {
        procesadorReservas.activarSiguienteReserva(evento.isbn());
    }
}

@Component
class ActualizadorEstadisticas {
    // Solo si la transacción hace COMMIT: no queremos contar devoluciones que se deshicieron
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void alDevolver(MaterialDevuelto evento) {
        estadisticas.registrarDevolucion(evento);
    }
}

@Component
class NotificadorMultas {
    @Async                                     // en otro hilo: no bloquea la respuesta
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void alDevolver(MaterialDevuelto evento) {
        if (evento.multa().esPositiva()) {
            notificador.notificar(Aviso.porMulta(evento));
        }
    }
}

public enum EstadoPrestamo {

    ACTIVO {
        @Override public boolean permiteRenovar()  { return true; }
        @Override public boolean permiteDevolver() { return true; }
        @Override public EstadoPrestamo alRenovar() { return RENOVADO; }
    },
    RENOVADO {
        @Override public boolean permiteRenovar()  { return false; }   // solo una renovación
        @Override public boolean permiteDevolver() { return true; }
    },
    VENCIDO {
        @Override public boolean permiteRenovar()  { return false; }
        @Override public boolean permiteDevolver() { return true; }
        @Override public boolean generaMulta()     { return true; }
    },
    DEVUELTO {
        @Override public boolean esFinal() { return true; }
    },
    PERDIDO {
        @Override public boolean esFinal() { return true; }
        @Override public boolean generaMulta() { return true; }
    };

    public boolean permiteRenovar()  { return false; }
    public boolean permiteDevolver() { return false; }
    public boolean generaMulta()     { return false; }
    public boolean esFinal()         { return false; }

    public EstadoPrestamo alRenovar() {
        throw new TransicionInvalidaException(this, "renovar");
    }
}

public void renovar(int dias) {
    if (!estado.permiteRenovar()) {
        throw new TransicionInvalidaException(estado, "renovar");
    }
    this.fechaVencimiento = fechaVencimiento.plusDays(dias);
    this.estado = estado.alRenovar();
}

public interface Comando {
    void ejecutar();
    void deshacer();
    String descripcion();
}

public class ComandoPrestar implements Comando {

    private final GestionarPrestamos gestor;
    private final Isbn isbn;
    private final Long idEmpleado;
    private Long idPrestamoCreado;      // estado necesario para deshacer

    @Override
    public void ejecutar() {
        this.idPrestamoCreado = gestor.prestar(isbn, idEmpleado, 15).getId();
    }

    @Override
    public void deshacer() {
        if (idPrestamoCreado == null) throw new IllegalStateException("No ejecutado");
        gestor.anular(idPrestamoCreado);
    }

    @Override
    public String descripcion() { return "Prestar " + isbn + " a empleado " + idEmpleado; }
}

public class HistorialOperaciones {
    private final Deque<Comando> pila = new ArrayDeque<>();      // 05-07/05-08

    public void ejecutar(Comando c) {
        c.ejecutar();
        pila.push(c);
    }

    public void deshacerUltima() {
        if (pila.isEmpty()) throw new NadaQueDeshacerException();
        pila.pop().deshacer();
    }
}

public interface ValidadorImportacion {
    Optional<ErrorImportacion> validar(RegistroImportacion r);
}

@Service
class CadenaValidacion {
    private final List<ValidadorImportacion> validadores;   // Spring inyecta todos, ordenados

    public Optional<ErrorImportacion> validar(RegistroImportacion r) {
        return validadores.stream()
                .map(v -> v.validar(r))
                .flatMap(Optional::stream)
                .findFirst();               // el primer error corta la cadena
    }
}

public class CatalogoPaginado implements Iterable<Material> {

    private final RepositorioMateriales repositorio;
    private final int tamanoPagina;

    @Override
    public Iterator<Material> iterator() {
        return new Iterator<>() {
            private int pagina = 0;
            private Iterator<Material> actual = Collections.emptyIterator();

            @Override public boolean hasNext() {
                if (actual.hasNext()) return true;
                List<Material> siguiente = repositorio.pagina(pagina++, tamanoPagina);
                actual = siguiente.iterator();
                return actual.hasNext();
            }

            @Override public Material next() {
                if (!hasNext()) throw new NoSuchElementException();
                return actual.next();
            }
        };
    }
}

// El cliente recorre 50.000 materiales sin cargarlos todos en memoria
for (Material m : new CatalogoPaginado(repositorio, 500)) { … }

@Transactional
public void renovar(Long id, int dias) {
    Prestamo p = prestamos.buscarPorId(id).orElseThrow(…);
    p.renovar(dias);
    // NO hace falta prestamos.guardar(p):
    // el contexto de persistencia (la unidad de trabajo) rastrea la entidad
    // y hace el UPDATE al hacer flush, antes del commit.
}

public final class ConfigGlobal {
    public static int diasPrestamo = 15;    // cualquiera lo cambia, desde cualquier hilo
}

// MAL: un gestor de préstamos NO ES una lista de préstamos.
public class GestorPrestamos extends ArrayList<Prestamo> { … }

// ANÉMICO: Prestamo es una bolsa de datos
public class Prestamo {
    private LocalDate fechaVencimiento;
    private EstadoPrestamo estado;
    // 15 getters y 15 setters, cero comportamiento
}

@Service
public class GestorPrestamos {
    public void devolver(Prestamo p, LocalDate hoy) {
        // La regla de negocio vive FUERA del objeto que la protege
        if (p.getEstado() == EstadoPrestamo.DEVUELTO) throw new …;
        p.setFechaDevolucion(hoy);
        p.setEstado(EstadoPrestamo.DEVUELTO);
    }
}

// RICO: el objeto protege sus propias reglas
public class Prestamo {
    public Dinero registrarDevolucion(LocalDate fecha) {
        if (estado.esFinal()) throw new PrestamoYaCerradoException(id);
        if (fecha.isBefore(fechaPrestamo)) throw new FechaInvalidaException(fecha);
        this.fechaDevolucion = fecha;
        this.estado = EstadoPrestamo.DEVUELTO;
        return multaHasta(fecha);
    }
    // sin setters públicos: es IMPOSIBLE dejar el objeto a medias
}

@Service
public class ServicioExportacion {

    @Autowired private EntityManager em;
    @Autowired private JavaMailSender correo;

    public void exportar(String formato, String destino, String correoDestino) throws Exception {
        List<Material> materiales = em.createQuery("select m from Material m", Material.class)
                                      .getResultList();
        String contenido;

        if (formato.equals("csv")) {
            StringBuilder sb = new StringBuilder("isbn;titulo;tipo\n");
            for (Material m : materiales) {
                sb.append(m.getIsbn()).append(';')
                  .append(m.getTitulo()).append(';');
                if (m instanceof Libro)        sb.append("LIBRO");
                else if (m instanceof Revista) sb.append("REVISTA");
                else if (m instanceof Dvd)     sb.append("DVD");
                sb.append('\n');
            }
            contenido = sb.toString();
        } else if (formato.equals("json")) {
            contenido = new ObjectMapper().writeValueAsString(materiales);
        } else {
            throw new IllegalArgumentException("Formato no soportado: " + formato);
        }

        Files.writeString(Path.of(destino), contenido);

        if (correoDestino != null) {
            SimpleMailMessage m = new SimpleMailMessage();
            m.setTo(correoDestino);
            m.setSubject("Catálogo BiblioTech");
            m.setText("Adjunto el catálogo en formato " + formato);
            correo.send(m);
        }
        System.out.println("Exportados " + materiales.size() + " materiales");
    }
}

public abstract class Material {
    public abstract TipoMaterial tipo();     // adiós al instanceof
}
public class Libro extends Material {
    @Override public TipoMaterial tipo() { return TipoMaterial.LIBRO; }
}

public interface FormateadorCatalogo {
    String formatear(List<Material> materiales);
    Formato formato();
    String extension();
}

@Component
class FormateadorCsv implements FormateadorCatalogo {
    @Override public Formato formato()   { return Formato.CSV; }
    @Override public String extension()  { return "csv"; }

    @Override
    public String formatear(List<Material> materiales) {
        return materiales.stream()
                .map(m -> String.join(";", m.getIsbn().valor(), m.getTitulo(), m.tipo().name()))
                .collect(Collectors.joining("\n", "isbn;titulo;tipo\n", "\n"));
    }
}

@Component
class FormateadorJson implements FormateadorCatalogo {
    private final ObjectMapper mapper;               // inyectado: uno solo, reutilizado

    FormateadorJson(ObjectMapper mapper) { this.mapper = mapper; }

    @Override public Formato formato()  { return Formato.JSON; }
    @Override public String extension() { return "json"; }

    @Override
    public String formatear(List<Material> materiales) {
        try {
            // DTOs, no entidades (12-01)
            List<MaterialDto> dtos = materiales.stream().map(MaterialDto::desde).toList();
            return mapper.writeValueAsString(dtos);
        } catch (JsonProcessingException e) {
            throw new ExportacionFallidaException("No se pudo serializar el catálogo", e);
        }
    }
}

public interface AlmacenExportaciones {
    URI guardar(String nombre, String contenido);
}

public interface NotificadorAvisos {
    void notificar(Aviso aviso);
}

@Service
public class ServicioExportacion {

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

    private final RepositorioMateriales materiales;
    private final Map<Formato, FormateadorCatalogo> formateadores;
    private final AlmacenExportaciones almacen;
    private final NotificadorAvisos notificador;

    /** Spring inyecta TODOS los formateadores; los indexamos por formato. */
    public ServicioExportacion(RepositorioMateriales materiales,
                               List<FormateadorCatalogo> formateadores,
                               AlmacenExportaciones almacen,
                               NotificadorAvisos notificador) {
        this.materiales = materiales;
        this.formateadores = formateadores.stream()
                .collect(Collectors.toUnmodifiableMap(FormateadorCatalogo::formato, f -> f));
        this.almacen = almacen;
        this.notificador = notificador;
    }

    public ResultadoExportacion exportar(Formato formato, String nombre, String correoDestino) {
        FormateadorCatalogo formateador = formateadores.get(formato);
        if (formateador == null) {
            throw new FormatoNoSoportadoException(formato, formateadores.keySet());
        }

        List<Material> catalogo = materiales.todos();
        String contenido = formateador.formatear(catalogo);
        URI ubicacion = almacen.guardar(nombre + "." + formateador.extension(), contenido);

        if (correoDestino != null) {
            notificador.notificar(Aviso.exportacionLista(correoDestino, formato, ubicacion));
        }

        log.info("Exportados {} materiales en formato {} a {}", catalogo.size(), formato, ubicacion);
        return new ResultadoExportacion(catalogo.size(), ubicacion, formato);
    }
}

/**
 * Decorador que limita la tasa de peticiones a la pasarela de metadatos.
 *
 * Implementa una ventana deslizante: guarda la marca de tiempo de las
 * últimas N peticiones; si la más antigua está dentro de la ventana,
 * espera hasta que salga.
 *
 * ES una PasarelaMetadatos y TIENE una PasarelaMetadatos: decorador.
 */
public class PasarelaConLimiteDeTasa implements PasarelaMetadatos {

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

    private final PasarelaMetadatos delegado;
    private final int maximoPeticiones;
    private final Duration ventana;
    private final Clock reloj;                     // 10-05: inyectable, para poder probarlo

    /** Marcas de tiempo de las últimas peticiones. Acceso siempre bajo el lock. */
    private final Deque<Instant> marcas = new ArrayDeque<>();
    private final ReentrantLock lock = new ReentrantLock(true);   // justo: orden FIFO

    public PasarelaConLimiteDeTasa(PasarelaMetadatos delegado, int maximoPeticiones,
                                   Duration ventana, Clock reloj) {
        this.delegado = Objects.requireNonNull(delegado);
        if (maximoPeticiones < 1) throw new IllegalArgumentException("maximoPeticiones >= 1");
        this.maximoPeticiones = maximoPeticiones;
        this.ventana = Objects.requireNonNull(ventana);
        this.reloj = Objects.requireNonNull(reloj);
    }

    @Override
    public Optional<MetadatosMaterial> buscar(Isbn isbn) {
        adquirirPermiso();                 // puede bloquear
        return delegado.buscar(isbn);      // la llamada real, ya fuera del lock
    }

    private void adquirirPermiso() {
        lock.lock();
        try {
            while (true) {
                Instant ahora = Instant.now(reloj);
                purgarAntiguas(ahora);

                if (marcas.size() < maximoPeticiones) {
                    marcas.addLast(ahora);
                    return;
                }

                // La ventana está llena: hay que esperar a que caduque la más antigua
                Instant masAntigua = marcas.peekFirst();
                Duration espera = Duration.between(ahora, masAntigua.plus(ventana));
                if (espera.isNegative() || espera.isZero()) continue;

                log.debug("Límite de tasa alcanzado; esperando {} ms", espera.toMillis());
                lock.unlock();                       // liberar mientras dormimos
                try {
                    Thread.sleep(espera.toMillis());
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();     // regla del módulo 8: restaurar la marca
                    throw new ConsultaInterrumpidaException("Espera de límite de tasa interrumpida", e);
                } finally {
                    lock.lock();                     // recuperar antes de volver al bucle
                }
            }
        } finally {
            lock.unlock();
        }
    }

    private void purgarAntiguas(Instant ahora) {
        Instant limite = ahora.minus(ventana);
        while (!marcas.isEmpty() && marcas.peekFirst().isBefore(limite)) {
            marcas.pollFirst();
        }
    }
}

@Bean
PasarelaMetadatos pasarelaMetadatos(AdaptadorMetadatosHttp http, Clock reloj, MeterRegistry registro) {
    return new PasarelaConMetricas(                      // 3.º: mide el tiempo total (incluida la espera)
             new PasarelaConLimiteDeTasa(                // 2.º: no supera 10 por minuto
               new PasarelaConCache(http, Duration.ofHours(24)),   // 1.º: la caché evita peticiones
               10, Duration.ofMinutes(1), reloj));
}

@Test
void esperaCuandoSeSuperaElLimite() {
    var delegado = new PasarelaFalsa();
    var reloj = Clock.fixed(Instant.parse("2026-03-20T10:00:00Z"), ZoneOffset.UTC);
    var pasarela = new PasarelaConLimiteDeTasa(delegado, 2, Duration.ofSeconds(1), reloj);

    long inicio = System.nanoTime();
    pasarela.buscar(Isbn.de("978-0000000001"));
    pasarela.buscar(Isbn.de("978-0000000002"));
    pasarela.buscar(Isbn.de("978-0000000003"));   // la tercera debe esperar ~1 s
    long ms = (System.nanoTime() - inicio) / 1_000_000;

    assertThat(ms).isGreaterThanOrEqualTo(900);
    assertThat(delegado.llamadas()).isEqualTo(3);
}

public enum EstadoReserva {

    /** En cola, esperando a que haya un ejemplar libre. */
    PENDIENTE {
        @Override public boolean puedeCancelarse()    { return true; }
        @Override public boolean ocupaPuestoEnCola()  { return true; }
        @Override public EstadoReserva alHaberEjemplar() { return DISPONIBLE; }
    },

    /** Hay ejemplar apartado; el empleado dispone de 48 horas. */
    DISPONIBLE {
        @Override public boolean puedeCancelarse()   { return true; }
        @Override public boolean puedeRecogerse()    { return true; }
        @Override public boolean puedeCaducar()      { return true; }
        @Override public boolean ocupaPuestoEnCola() { return true; }
        @Override public boolean tieneFechaLimite()  { return true; }
        @Override public EstadoReserva alRecoger()   { return RECOGIDA; }
        @Override public EstadoReserva alCaducar()   { return CADUCADA; }
    },

    RECOGIDA  { @Override public boolean esFinal() { return true; } },
    CADUCADA  { @Override public boolean esFinal() { return true; } },
    CANCELADA { @Override public boolean esFinal() { return true; } };

    // --- Consultas: por defecto, nada está permitido ---
    public boolean puedeCancelarse()   { return false; }
    public boolean puedeRecogerse()    { return false; }
    public boolean puedeCaducar()      { return false; }
    public boolean ocupaPuestoEnCola() { return false; }
    public boolean tieneFechaLimite()  { return false; }
    public boolean esFinal()           { return false; }

    // --- Transiciones: por defecto, inválidas ---
    public EstadoReserva alHaberEjemplar() { throw new TransicionInvalidaException(this, "haber ejemplar"); }
    public EstadoReserva alRecoger()       { throw new TransicionInvalidaException(this, "recoger"); }
    public EstadoReserva alCaducar()       { throw new TransicionInvalidaException(this, "caducar"); }

    /** Cancelar es la única transición común a varios estados. */
    public EstadoReserva alCancelar() {
        if (!puedeCancelarse()) throw new TransicionInvalidaException(this, "cancelar");
        return CANCELADA;
    }
}

@Entity
public class Reserva {

    private static final int HORAS_PARA_RECOGER = 48;

    @Id @GeneratedValue private Long id;
    @ManyToOne(fetch = FetchType.LAZY) private Material material;
    @ManyToOne(fetch = FetchType.LAZY) private Empleado empleado;
    @Enumerated(EnumType.STRING) private EstadoReserva estado;
    private Instant fechaSolicitud;
    private Instant fechaLimiteRecogida;      // solo tiene sentido en DISPONIBLE
    @Version private long version;            // bloqueo optimista (11-03)

    protected Reserva() { }                   // exigido por JPA

    public static Reserva nueva(Material material, Empleado empleado, Clock reloj) {
        Reserva r = new Reserva();
        r.material = material;
        r.empleado = empleado;
        r.estado = EstadoReserva.PENDIENTE;
        r.fechaSolicitud = Instant.now(reloj);
        return r;
    }

    public void asignarEjemplar(Clock reloj) {
        this.estado = estado.alHaberEjemplar();       // valida y transita en una línea
        this.fechaLimiteRecogida = Instant.now(reloj).plus(HORAS_PARA_RECOGER, ChronoUnit.HOURS);
    }

    public void recoger() {
        this.estado = estado.alRecoger();
        this.fechaLimiteRecogida = null;
    }

    public void cancelar() {
        this.estado = estado.alCancelar();
        this.fechaLimiteRecogida = null;
    }

    /** Devuelve true si efectivamente caducó. Idempotente: si no procede, no hace nada. */
    public boolean caducarSiProcede(Clock reloj) {
        if (!estado.puedeCaducar()) return false;
        if (Instant.now(reloj).isBefore(fechaLimiteRecogida)) return false;
        this.estado = estado.alCaducar();
        this.fechaLimiteRecogida = null;
        return true;
    }

    public boolean ocupaPuestoEnCola() { return estado.ocupaPuestoEnCola(); }
}

@Scheduled(cron = "0 */15 * * * *")     // cada 15 minutos
@Transactional
public void caducarReservasVencidas() {
    int caducadas = 0;
    for (Reserva r : repositorio.enEstado(EstadoReserva.DISPONIBLE)) {
        if (r.caducarSiProcede(reloj)) {
            caducadas++;
            eventos.publishEvent(new ReservaCaducada(r.getId()));   // Observador
        }
    }
    log.info("Reservas caducadas: {}", caducadas);
}