tipo,referencia,titulo,autor,anio,disponible
LIBRO,978-0000000001,Java Efectivo,Joshua Bloch,2018,true
LIBRO,978-0000000002,Patrones de Diseno,Erich Gamma,1994,false
LIBRO,978-0000000003,Refactorizacion,Martin Fowler,1999,true

titulo,autor,notas
Java Efectivo,Bloch,Sin notas
"Java: el lenguaje, la maquina y el ecosistema",Bloch,"Contiene una coma"
"El libro llamado ""Refactorizacion""",Fowler,"Contiene comillas duplicadas"
"Titulo con
salto de linea",Autor,"Un campo puede ocupar varias lineas fisicas"
Sin comillas,,"Campo vacio en medio"

// INGENUO: funciona con datos simples y falla con datos reales
String[] campos = linea.split(",");

String linea = "\"Java: el lenguaje, la maquina y el ecosistema\",Bloch,2018";
String[] campos = linea.split(",");

// campos.length == 4, no 3
// campos[0] == "\"Java: el lenguaje"
// campos[1] == " la maquina y el ecosistema\""
// campos[2] == "Bloch"
// campos[3] == "2018"

"Java Efectivo,Bloch,".split(",");        // 2 elementos: descarta los vacios finales
"Java Efectivo,Bloch,".split(",", -1);    // 3 elementos: correcto

String primera = campos[0];               // "\uFEFFtipo", no "tipo"
primera.equals("tipo");                   // false
primera.length();                         // 5, no 4

/**
 * Escapa un campo segun el RFC 4180.
 *
 * Un campo necesita comillas si contiene el separador, una comilla, un
 * salto de linea, o espacios al principio o al final (que muchas
 * herramientas recortan sin avisar).
 *
 * Las comillas interiores se DUPLICAN, no se preceden de barra invertida:
 * CSV no usa barras invertidas.
 */
public static String escapar(String campo, char separador) {
    if (campo == null) {
        return "";                     // null y vacio se escriben igual (apartado 5)
    }

    boolean necesitaComillas =
            campo.indexOf(separador) >= 0
            || campo.indexOf('"') >= 0
            || campo.indexOf('\n') >= 0
            || campo.indexOf('\r') >= 0
            || campo.startsWith(" ")
            || campo.endsWith(" ");

    if (!necesitaComillas) {
        return campo;
    }
    // Duplicar las comillas interiores y envolver en comillas
    return '"' + campo.replace("\"", "\"\"") + '"';
}

/** Deshace el escapado de un campo ya extraido. */
public static String desescapar(String campo) {
    if (campo == null || campo.isEmpty()) {
        return "";
    }
    String limpio = campo.trim();

    if (limpio.length() >= 2 && limpio.startsWith("\"") && limpio.endsWith("\"")) {
        limpio = limpio.substring(1, limpio.length() - 1);
        limpio = limpio.replace("\"\"", "\"");
    }
    return limpio;
}

package com.nexussoftware.bibliotech.infraestructura;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.Reader;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

/**
 * Lector CSV conforme al RFC 4180.
 *
 * Maneja correctamente:
 *   - separadores dentro de campos entrecomillados
 *   - comillas escapadas por duplicacion
 *   - saltos de linea dentro de un campo (un registro ocupa varias lineas)
 *   - campos vacios, incluido el ultimo
 *   - la marca BOM al principio del fichero
 *
 * NO maneja (y lo dice honestamente):
 *   - la distincion entre null y cadena vacia: CSV no la tiene
 *   - codificaciones distintas de la que se le pase
 *
 * Es Closeable: cierra el Reader que envuelve (06-06).
 */
public class LectorCsv implements AutoCloseable {

    /** Marca de orden de bytes que Excel escribe al principio de los UTF-8. */
    private static final char BOM = '\uFEFF';

    private static final char COMILLA = '"';

    private final BufferedReader lector;
    private final char separador;

    private boolean primeraLectura = true;
    private int numeroRegistro = 0;
    private int numeroLineaFisica = 0;

    public LectorCsv(Reader origen, char separador) {
        Objects.requireNonNull(origen, "El origen no puede ser nulo");
        this.lector = (origen instanceof BufferedReader br)
                ? br
                : new BufferedReader(origen);       // no envolver dos veces (07-04)
        this.separador = separador;
    }

    public LectorCsv(Reader origen) {
        this(origen, ',');
    }

    /**
     * Lee el siguiente registro.
     *
     * Un registro puede ocupar VARIAS lineas fisicas si algun campo tiene un
     * salto de linea dentro. Por eso no basta con un readLine() por registro.
     *
     * @return los campos ya desescapados, o null si no hay mas registros
     * @throws CsvFormatoException si el registro esta mal formado
     */
    public List<String> siguiente() throws IOException {
        String linea = lector.readLine();
        if (linea == null) {
            return null;                             // fin (07-04)
        }
        numeroLineaFisica++;

        // Quitar el BOM SOLO de la primera linea
        if (primeraLectura) {
            primeraLectura = false;
            if (!linea.isEmpty() && linea.charAt(0) == BOM) {
                linea = linea.substring(1);
            }
        }

        List<String> campos = new ArrayList<>();
        StringBuilder campo = new StringBuilder();
        boolean dentroDeComillas = false;
        int indice = 0;

        while (true) {
            if (indice >= linea.length()) {
                if (!dentroDeComillas) {
                    break;                           // fin del registro
                }
                // Estamos DENTRO de comillas: el campo continua en la
                // siguiente linea fisica. Se repone el salto de linea.
                String continuacion = lector.readLine();
                if (continuacion == null) {
                    throw new CsvFormatoException(numeroLineaFisica,
                            "El fichero termina con unas comillas sin cerrar");
                }
                numeroLineaFisica++;
                campo.append('\n');
                linea = continuacion;
                indice = 0;
                continue;
            }

            char c = linea.charAt(indice);

            if (dentroDeComillas) {
                if (c == COMILLA) {
                    // Una comilla dentro de comillas: o cierra, o esta duplicada
                    if (indice + 1 < linea.length() && linea.charAt(indice + 1) == COMILLA) {
                        campo.append(COMILLA);       // duplicada: una comilla literal
                        indice += 2;
                    } else {
                        dentroDeComillas = false;    // cierra el campo
                        indice++;
                    }
                } else {
                    campo.append(c);
                    indice++;
                }

            } else {
                if (c == COMILLA && campo.isEmpty()) {
                    // Comillas al PRINCIPIO del campo: abren
                    dentroDeComillas = true;
                    indice++;
                } else if (c == separador) {
                    campos.add(campo.toString());
                    campo.setLength(0);
                    indice++;
                } else {
                    campo.append(c);
                    indice++;
                }
            }
        }

        campos.add(campo.toString());                // el ultimo campo, siempre
        numeroRegistro++;
        return campos;
    }

    /**
     * Lee todos los registros restantes.
     *
     * AVISO: carga el fichero entero en memoria (07-01). Para ficheros
     * grandes, usa siguiente() en un bucle.
     */
    public List<List<String>> leerTodo() throws IOException {
        List<List<String>> registros = new ArrayList<>();
        List<String> registro;
        while ((registro = siguiente()) != null) {
            registros.add(registro);
        }
        return registros;
    }

    public int getNumeroRegistro()    { return numeroRegistro; }
    public int getNumeroLineaFisica() { return numeroLineaFisica; }

    @Override
    public void close() throws IOException {
        lector.close();
    }

    /** Fallo de formato con la linea fisica exacta (06-04). */
    public static class CsvFormatoException extends IOException {

        private static final long serialVersionUID = 1L;

        private final int linea;

        public CsvFormatoException(int linea, String mensaje) {
            super("Linea " + linea + ": " + mensaje);
            this.linea = linea;
        }

        public int getLinea() { return linea; }
    }
}

public class PruebaLectorCsv {

    public static void main(String[] args) throws IOException {
        String contenido = String.join("\n",
                "titulo,autor,anio",
                "Java Efectivo,Joshua Bloch,2018",
                "\"Java: el lenguaje, la maquina\",Bloch,2018",
                "\"El libro \"\"Refactorizacion\"\"\",Fowler,1999",
                "\"Titulo con",
                "salto de linea\",Autor,2020",
                "Sin comillas,,2021",
                "Ultimo campo vacio,Autor,");

        try (LectorCsv csv = new LectorCsv(new java.io.StringReader(contenido))) {
            List<String> registro;
            while ((registro = csv.siguiente()) != null) {
                System.out.printf("[%d] %d campos: %s%n",
                        csv.getNumeroRegistro(), registro.size(), registro);
            }
        }
    }
}

[1] 3 campos: [titulo, autor, anio]
[2] 3 campos: [Java Efectivo, Joshua Bloch, 2018]
[3] 3 campos: [Java: el lenguaje, la maquina, Bloch, 2018]
[4] 3 campos: [El libro "Refactorizacion", Fowler, 1999]
[5] 3 campos: [Titulo con
salto de linea, Autor, 2020]
[6] 3 campos: [Sin comillas, , 2021]
[7] 3 campos: [Ultimo campo vacio, Autor, ]

package com.nexussoftware.bibliotech.infraestructura;

import java.io.IOException;
import java.io.Writer;
import java.util.List;
import java.util.Objects;

/**
 * Escritor CSV conforme al RFC 4180.
 *
 * Entrecomilla y escapa lo que haga falta, de modo que lo escrito se puede
 * volver a leer con LectorCsv sin perder nada.
 */
public class EscritorCsv implements AutoCloseable {

    private static final char COMILLA = '"';

    private final Writer salida;
    private final char separador;
    private final String finDeLinea;

    private int registrosEscritos = 0;

    /**
     * @param salida     destino, normalmente un BufferedWriter (07-04)
     * @param separador  ',' o ';'
     * @param finDeLinea "\n" para ficheros que se versionan; CRLF si lo exige
     *                   el consumidor. El RFC 4180 pide CRLF.
     */
    public EscritorCsv(Writer salida, char separador, String finDeLinea) {
        this.salida = Objects.requireNonNull(salida, "La salida no puede ser nula");
        this.separador = separador;
        this.finDeLinea = Objects.requireNonNull(finDeLinea);
    }

    public EscritorCsv(Writer salida) {
        this(salida, ',', "\n");
    }

    /** Escribe un registro completo. */
    public void escribirRegistro(List<String> campos) throws IOException {
        Objects.requireNonNull(campos, "Los campos no pueden ser nulos");

        for (int i = 0; i < campos.size(); i++) {
            if (i > 0) {
                salida.write(separador);
            }
            salida.write(escapar(campos.get(i)));
        }
        salida.write(finDeLinea);
        registrosEscritos++;
    }

    /** Variante con argumentos variables, cómoda para llamadas cortas. */
    public void escribirRegistro(String... campos) throws IOException {
        escribirRegistro(List.of(campos));
    }

    /** Escribe la cabecera. Es un registro normal; el nombre es documentacion. */
    public void escribirCabecera(String... nombres) throws IOException {
        escribirRegistro(nombres);
    }

    /**
     * Escapa un campo segun el RFC 4180.
     *
     * Se entrecomilla si contiene el separador, una comilla, un salto de
     * linea, o espacios en los extremos (que muchas herramientas recortan).
     */
    private String escapar(String campo) {
        if (campo == null || campo.isEmpty()) {
            return "";
        }
        boolean necesita = campo.indexOf(separador) >= 0
                || campo.indexOf(COMILLA) >= 0
                || campo.indexOf('\n') >= 0
                || campo.indexOf('\r') >= 0
                || campo.charAt(0) == ' '
                || campo.charAt(campo.length() - 1) == ' ';

        if (!necesita) {
            return campo;
        }
        return COMILLA + campo.replace("\"", "\"\"") + COMILLA;
    }

    public int getRegistrosEscritos() { return registrosEscritos; }

    /** flush explicito: util si el consumidor lee mientras escribimos (07-02). */
    public void flush() throws IOException {
        salida.flush();
    }

    @Override
    public void close() throws IOException {
        salida.close();          // el close del Writer hace flush (07-02)
    }
}

public class PruebaIdaYVuelta {

    public static void main(String[] args) throws IOException {
        List<List<String>> originales = List.of(
                List.of("titulo", "autor", "notas"),
                List.of("Java Efectivo", "Bloch", ""),
                List.of("Java: el lenguaje, la maquina", "Bloch", "con coma"),
                List.of("El libro \"Refactorizacion\"", "Fowler", "con comillas"),
                List.of("Titulo con\nsalto", "Autor", "con salto"),
                List.of("  espacios  ", "Autor", "con espacios"));

        // Escribir a memoria (07-03)
        java.io.StringWriter memoria = new java.io.StringWriter();
        try (EscritorCsv escritor = new EscritorCsv(memoria)) {
            for (List<String> r : originales) {
                escritor.escribirRegistro(r);
            }
        }

        System.out.println("=== CSV GENERADO ===");
        System.out.println(memoria);

        // Leer de vuelta
        System.out.println("=== COMPROBACION DE IDA Y VUELTA ===");
        try (LectorCsv lector = new LectorCsv(new java.io.StringReader(memoria.toString()))) {
            int i = 0;
            List<String> leido;
            boolean todoBien = true;

            while ((leido = lector.siguiente()) != null) {
                boolean igual = leido.equals(originales.get(i));
                todoBien &= igual;
                System.out.printf("  [%d] %s  %s%n", i, igual ? "OK  " : "FALLO", leido);
                i++;
            }
            System.out.println(todoBien
                    ? "  Todos los registros vuelven IDENTICOS."
                    : "  HAY PERDIDA DE DATOS.");
        }
    }
}

=== CSV GENERADO ===
titulo,autor,notas
Java Efectivo,Bloch,
"Java: el lenguaje, la maquina",Bloch,con coma
"El libro ""Refactorizacion""",Fowler,con comillas
"Titulo con
salto",Autor,con salto
"  espacios  ",Autor,con espacios

=== COMPROBACION DE IDA Y VUELTA ===
  [0] OK   [titulo, autor, notas]
  [1] OK   [Java Efectivo, Bloch, ]
  [2] OK   [Java: el lenguaje, la maquina, Bloch, con coma]
  [3] OK   [El libro "Refactorizacion", Fowler, con comillas]
  [4] OK   [Titulo con
salto, Autor, con salto]
  [5] OK   [  espacios  , Autor, con espacios]
  Todos los registros vuelven IDENTICOS.

titulo,tarifa
Java Efectivo,0,25

import java.util.Locale;

// ESCRIBIR: fijar el Locale para que el decimal sea SIEMPRE el punto
String tarifa = String.format(Locale.ROOT, "%.2f", 0.25);      // "0.25"

// Sin Locale, en una maquina espanola:
String malo = String.format("%.2f", 0.25);                     // "0,25"  <-- ambiguo

// LEER: parsear siempre con punto
double valor = Double.parseDouble("0.25");     // Double.parseDouble usa SIEMPRE punto

// Si el fichero tiene coma decimal, hay que normalizarlo antes
double valorEs = Double.parseDouble("0,25".replace(',', '.'));

/** Parsea un decimal aceptando punto o coma. Tolerante al leer, estricto al escribir. */
private static double parsearDecimal(String texto, String campo, int linea) {
    if (texto == null || texto.isBlank()) {
        return 0.0;
    }
    try {
        return Double.parseDouble(texto.trim().replace(',', '.'));
    } catch (NumberFormatException e) {
        throw new IllegalArgumentException(String.format(
                "Linea %d: el campo '%s' no es un numero valido: '%s'",
                linea, campo, texto), e);          // encadenar la causa (06-03)
    }
}

package com.nexussoftware.bibliotech.servicio;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.dominio.Libro;
import com.nexussoftware.bibliotech.dominio.Material;
import com.nexussoftware.bibliotech.dominio.ReferenciaDuplicadaException;
import com.nexussoftware.bibliotech.infraestructura.EscritorCsv;
import com.nexussoftware.bibliotech.infraestructura.LectorCsv;

/**
 * Exporta e importa el catalogo de BiblioTech en CSV conforme al RFC 4180.
 *
 * Sustituye a la version de 07-02, que "saneaba" los titulos sustituyendo
 * los separadores por comas y PERDIA EL DATO. Ahora un titulo como
 * "Java: el lenguaje, la maquina y el ecosistema" se exporta y se vuelve a
 * importar identico.
 *
 * Persistencia sobre NIO.2 (07-06), con escritura atomica.
 */
public class ExportadorCatalogoCsv {

    private static final Logger LOG =
            Logger.getLogger(ExportadorCatalogoCsv.class.getName());

    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    /** Coma y punto decimal: el estandar. Para Excel espanol, ';' (apartado 7). */
    private static final char SEPARADOR = ',';

    private static final String[] CABECERA_CATALOGO =
            { "tipo", "referencia", "titulo", "autor", "anio", "disponible" };

    private static final String[] CABECERA_PRESTAMOS =
            { "referencia", "material", "empleado", "dia_inicio",
              "dia_devolucion", "multa" };

    private final Path directorio;

    public ExportadorCatalogoCsv(Path directorio) throws IOException {
        this.directorio = Objects.requireNonNull(directorio).toAbsolutePath().normalize();
        Files.createDirectories(this.directorio);
    }

    // ---------------------- EXPORTAR ----------------------

    /**
     * Exporta el catalogo a CSV, de forma atomica (07-06).
     *
     * @return numero de materiales exportados
     */
    public int exportarCatalogo(Catalogo catalogo) throws IOException {
        Objects.requireNonNull(catalogo, "El catalogo no puede ser nulo");

        List<Material> materiales = catalogo.listar();
        Path destino = directorio.resolve("catalogo.csv");
        Path temporal = destino.resolveSibling(destino.getFileName() + ".tmp");

        boolean completado = false;
        try {
            try (BufferedWriter salida = Files.newBufferedWriter(temporal, CHARSET,
                         StandardOpenOption.CREATE,
                         StandardOpenOption.TRUNCATE_EXISTING,
                         StandardOpenOption.WRITE);
                 EscritorCsv csv = new EscritorCsv(salida, SEPARADOR, "\n")) {

                csv.escribirCabecera(CABECERA_CATALOGO);

                for (Material m : materiales) {
                    csv.escribirRegistro(aRegistro(m));
                }
            }

            Files.move(temporal, destino,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completado = true;

            LOG.info(() -> String.format("Catalogo exportado: %d materiales en %s",
                    materiales.size(), destino));

        } catch (AtomicMoveNotSupportedException e) {
            LOG.warning(() -> "Sin ATOMIC_MOVE; sustitucion no atomica");
            Files.move(temporal, destino, StandardCopyOption.REPLACE_EXISTING);
            completado = true;

        } finally {
            if (!completado) {
                Files.deleteIfExists(temporal);           // compensacion (06-05)
            }
        }
        return materiales.size();
    }

    /**
     * Convierte un material a registro CSV.
     *
     * SIN saneado: el escritor entrecomilla lo que haga falta. El titulo
     * viaja INTACTO, con sus comas, sus comillas y sus dos puntos.
     */
    private List<String> aRegistro(Material m) {
        List<String> campos = new ArrayList<>(6);

        if (m instanceof Libro libro) {                    // 03-06
            campos.add("LIBRO");
            campos.add(libro.getIsbn());
            campos.add(libro.getTitulo());
            campos.add(libro.getAutor());
            campos.add(String.valueOf(libro.getAnioPublicacion()));
        } else {
            campos.add(m.getTipo().toUpperCase(Locale.ROOT));
            campos.add(m.getReferencia());
            campos.add(m.getTitulo());
            campos.add("");
            campos.add("");
        }
        campos.add(String.valueOf(m.estaDisponible()));
        return campos;
    }

    // ---------------------- IMPORTAR ----------------------

    /** Resultado de una importacion (06-07, 07-04). */
    public record ResultadoImportacion(int leidos, int importados, int descartados,
                                       List<String> errores) {

        public String resumen() {
            StringBuilder sb = new StringBuilder();
            sb.append(String.format(
                    "Importacion CSV: %d registros leidos, %d importados, %d descartados%n",
                    leidos, importados, descartados));
            int n = Math.min(10, errores.size());
            for (int i = 0; i < n; i++) {
                sb.append("    ").append(errores.get(i)).append('\n');
            }
            if (errores.size() > n) {
                sb.append(String.format("    ... y %d mas%n", errores.size() - n));
            }
            return sb.toString();
        }
    }

    /**
     * Importa el catalogo desde CSV.
     *
     * Politica de 06-07 y 07-04: una linea mala se descarta y se cuenta;
     * el fichero ausente degrada a resultado vacio sin excepcion.
     */
    public ResultadoImportacion importarCatalogo(Catalogo catalogo) throws IOException {
        Objects.requireNonNull(catalogo, "El catalogo no puede ser nulo");

        Path origen = directorio.resolve("catalogo.csv");
        List<String> errores = new ArrayList<>();
        int leidos = 0, importados = 0;

        if (Files.notExists(origen)) {
            LOG.warning(() -> "No hay catalogo CSV en " + origen
                    + "; se arranca con catalogo vacio");
            return new ResultadoImportacion(0, 0, 0, errores);
        }

        try (BufferedReader lector = Files.newBufferedReader(origen, CHARSET);
             LectorCsv csv = new LectorCsv(lector, SEPARADOR)) {

            List<String> cabecera = csv.siguiente();
            if (cabecera == null) {
                LOG.warning(() -> "El fichero " + origen + " esta vacio");
                return new ResultadoImportacion(0, 0, 0, errores);
            }
            comprobarCabecera(cabecera, errores);

            List<String> registro;
            while ((registro = csv.siguiente()) != null) {
                leidos++;
                int numero = csv.getNumeroRegistro();

                try {
                    Material material = aMaterial(registro, numero);
                    if (material != null) {
                        catalogo.registrar(material);
                        importados++;
                    }
                } catch (IllegalArgumentException e) {
                    errores.add(e.getMessage());
                } catch (ReferenciaDuplicadaException e) {
                    errores.add("Registro " + numero + ": " + e.getMessage());
                }
            }
        }

        int descartados = leidos - importados;
        LOG.info(() -> String.format("Catalogo importado: %d de %d registros",
                importados, leidos));

        return new ResultadoImportacion(leidos, importados, descartados, errores);
    }

    /** Un cambio de columnas es un aviso, no un fallo fatal. */
    private void comprobarCabecera(List<String> cabecera, List<String> errores) {
        if (cabecera.size() != CABECERA_CATALOGO.length) {
            errores.add(String.format(
                    "Cabecera con %d columnas; se esperaban %d (%s). "
                            + "Se intenta importar igualmente.",
                    cabecera.size(), CABECERA_CATALOGO.length,
                    String.join(", ", CABECERA_CATALOGO)));
        }
    }

    /** Construye el material validando cada campo. Lanza si el registro es invalido. */
    private Material aMaterial(List<String> campos, int numero) {
        if (campos.size() < 5) {
            throw new IllegalArgumentException(String.format(
                    "Registro %d: %d campos, se esperaban al menos 5", numero, campos.size()));
        }

        String tipo = campos.get(0).trim().toUpperCase(Locale.ROOT);
        if (!"LIBRO".equals(tipo)) {
            throw new IllegalArgumentException(
                    "Registro " + numero + ": tipo no soportado '" + tipo + "'");
        }

        String isbn   = campos.get(1).trim();
        String titulo = campos.get(2).trim();
        String autor  = campos.get(3).trim();

        if (isbn.isEmpty() || titulo.isEmpty()) {
            throw new IllegalArgumentException(
                    "Registro " + numero + ": ISBN o titulo vacios");
        }

        int anio;
        try {
            anio = Integer.parseInt(campos.get(4).trim());
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(String.format(
                    "Registro %d: el anio '%s' no es un numero",
                    numero, campos.get(4)), e);          // con la causa (06-03)
        }

        boolean disponible = campos.size() < 6
                || !"false".equalsIgnoreCase(campos.get(5).trim());

        return new Libro(titulo, autor.isEmpty() ? "Desconocido" : autor,
                isbn, anio, disponible);
    }

    // ---------------------- PRESTAMOS ----------------------

    /** Exporta el registro de prestamos, con los decimales en Locale.ROOT. */
    public int exportarPrestamos(List<Prestamo> prestamos) throws IOException {
        Path destino = directorio.resolve("prestamos.csv");

        try (BufferedWriter salida = Files.newBufferedWriter(destino, CHARSET,
                     StandardOpenOption.CREATE,
                     StandardOpenOption.TRUNCATE_EXISTING,
                     StandardOpenOption.WRITE);
             EscritorCsv csv = new EscritorCsv(salida, SEPARADOR, "\n")) {

            csv.escribirCabecera(CABECERA_PRESTAMOS);

            for (Prestamo p : prestamos) {
                csv.escribirRegistro(
                        p.getReferencia(),
                        p.getMaterial().getReferencia(),
                        p.getTitular().getIdentificador(),
                        String.valueOf(p.getDiaInicio()),
                        String.valueOf(p.estaDevuelto() ? p.getDiaDevolucion() : -1),
                        // Locale.ROOT: PUNTO decimal SIEMPRE, para poder releerlo
                        String.format(Locale.ROOT, "%.2f", p.calcularMulta(p.getDiaInicio())));
            }
        }
        LOG.info(() -> "Prestamos exportados: " + prestamos.size() + " en " + destino);
        return prestamos.size();
    }
}

tipo,referencia,titulo,autor,anio,disponible
LIBRO,978-0000000001,Java Efectivo,Joshua Bloch,2018,true
LIBRO,978-0000000002,Patrones de Diseno,Erich Gamma,1994,false
LIBRO,978-0000000003,Refactorizacion,Martin Fowler,1999,true
LIBRO,978-0000000004,"Java: el lenguaje, la maquina y el ecosistema",Bloch,2024,true

# Configuracion de BiblioTech - Nexus Software
# Este fichero se carga al arrancar y NO requiere recompilar la aplicacion

# --- Reglas de prestamo ---
bibliotech.prestamo.dias = 15
bibliotech.prestamo.maximo.simultaneos = 3

# --- Multas ---
bibliotech.multa.tarifa.diaria = 0.25
bibliotech.multa.maxima = 20.0
bibliotech.multa.umbral.leve = 7

# --- Rutas ---
bibliotech.datos.directorio = datos
bibliotech.datos.catalogo = catalogo.csv

# --- Registro ---
bibliotech.log.nivel = INFO

# MAL: \d se interpreta como un escape
ruta = C:\datos\catalogo.csv

# BIEN: barra invertida duplicada
ruta = C:\\datos\\catalogo.csv

# MEJOR: barras normales, que Java acepta en Windows (07-01)
ruta = C:/datos/catalogo.csv

import java.util.Properties;

Properties props = new Properties();

props.setProperty("bibliotech.prestamo.dias", "15");

String dias = props.getProperty("bibliotech.prestamo.dias");           // "15"
String falta = props.getProperty("no.existe");                         // null
String conDefecto = props.getProperty("no.existe", "valor por defecto"); // el defecto

props.containsKey("bibliotech.prestamo.dias");   // true
props.stringPropertyNames();                     // Set<String> con todas las claves
props.size();

# Antes de Java 9, la unica forma de escribir "Espanol" con enye:
mensaje.bienvenida = Bienvenido a BiblioTech en Espa\u00f1ol

import java.io.BufferedReader;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;

public class CargarProperties {

    /** Carga con charset EXPLICITO. La forma correcta, sin ambiguedades. */
    public static Properties cargar(Path fichero) throws IOException {
        Properties props = new Properties();

        try (BufferedReader lector = Files.newBufferedReader(
                fichero, StandardCharsets.UTF_8)) {     // 07-06

            props.load(lector);          // load(Reader): el charset lo decide el Reader
        }
        return props;
    }

    /** Guarda con charset explicito. */
    public static void guardar(Properties props, Path fichero, String comentario)
            throws IOException {

        try (java.io.BufferedWriter salida = Files.newBufferedWriter(
                fichero, StandardCharsets.UTF_8,
                java.nio.file.StandardOpenOption.CREATE,
                java.nio.file.StandardOpenOption.TRUNCATE_EXISTING,
                java.nio.file.StandardOpenOption.WRITE)) {

            props.store(salida, comentario);
        }
    }
}

#Configuracion generada por BiblioTech
#Wed Aug 05 09:14:22 CEST 2026
bibliotech.multa.tarifa.diaria=0.25
bibliotech.prestamo.dias=15
bibliotech.datos.directorio=datos

/** Carga desde el classpath: el fichero va dentro del jar y no se puede perder. */
public static Properties cargarDelClasspath(String recurso) throws IOException {
    Properties props = new Properties();

    try (java.io.InputStream entrada =
                 Configuracion.class.getResourceAsStream(recurso)) {

        if (entrada == null) {
            throw new java.io.FileNotFoundException(
                    "No se encontro el recurso '" + recurso + "' en el classpath");
        }
        try (java.io.Reader lector = new java.io.InputStreamReader(
                entrada, StandardCharsets.UTF_8)) {     // el PUENTE de 07-03
            props.load(lector);
        }
    }
    return props;
}

// Nivel 1: valores por defecto, en el codigo
Properties porDefecto = new Properties();
porDefecto.setProperty("bibliotech.prestamo.dias", "15");
porDefecto.setProperty("bibliotech.multa.tarifa.diaria", "0.25");
porDefecto.setProperty("bibliotech.multa.maxima", "20.0");

// Nivel 2: el fichero, CON los defectos como respaldo
Properties configuracion = new Properties(porDefecto);
configuracion.load(lector);        // el fichero solo trae 'dias'

configuracion.getProperty("bibliotech.prestamo.dias");           // del fichero
configuracion.getProperty("bibliotech.multa.tarifa.diaria");     // "0.25", del defecto
configuracion.getProperty("bibliotech.multa.maxima");            // "20.0", del defecto

configuracion.size();                       // 1: solo lo del fichero
configuracion.stringPropertyNames().size(); // 3: incluye los defectos

package com.nexussoftware.bibliotech.infraestructura;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Locale;
import java.util.Objects;
import java.util.Properties;
import java.util.TreeMap;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Configuracion de BiblioTech con jerarquia de fuentes.
 *
 * Precedencia, de menor a mayor:
 *   1. valores por defecto del codigo
 *   2. bibliotech-defecto.properties del classpath
 *   3. fichero externo bibliotech.properties
 *   4. variables de entorno (BIBLIOTECH_XXX_YYY)
 *   5. propiedades del sistema (-Dbibliotech.xxx.yyy)
 *
 * DEGRADACION ELEGANTE (06-07): si no hay ningun fichero, la aplicacion
 * arranca con los valores por defecto y lo registra. Configurar mal no debe
 * impedir arrancar; lo que SI debe impedirlo es un valor INVALIDO, porque
 * calcular multas con una tarifa desconocida produciria cobros incorrectos.
 */
public final class Configuracion {

    private static final Logger LOG = Logger.getLogger(Configuracion.class.getName());

    private static final String RECURSO_DEFECTO = "/bibliotech-defecto.properties";
    private static final String FICHERO_EXTERNO = "bibliotech.properties";
    private static final String PREFIJO = "bibliotech.";

    // ---------- Claves ----------
    public static final String PRESTAMO_DIAS       = "bibliotech.prestamo.dias";
    public static final String PRESTAMO_MAXIMO     = "bibliotech.prestamo.maximo.simultaneos";
    public static final String MULTA_TARIFA_DIARIA = "bibliotech.multa.tarifa.diaria";
    public static final String MULTA_MAXIMA        = "bibliotech.multa.maxima";
    public static final String MULTA_UMBRAL_LEVE   = "bibliotech.multa.umbral.leve";
    public static final String DATOS_DIRECTORIO    = "bibliotech.datos.directorio";
    public static final String DATOS_CATALOGO      = "bibliotech.datos.catalogo";
    public static final String CSV_SEPARADOR       = "bibliotech.csv.separador";

    /** Las propiedades ya resueltas por la jerarquia. */
    private final Properties resueltas = new Properties();

    /** De donde salio cada valor. Sirve para diagnosticar. */
    private final TreeMap<String, String> origen = new TreeMap<>();

    private static Configuracion instancia;

    private Configuracion() { }

    /**
     * Carga la configuracion. Idempotente.
     *
     * @param rutaFichero fichero externo, o null para el nombre por defecto
     */
    public static synchronized Configuracion cargar(Path rutaFichero) {
        if (instancia != null) {
            return instancia;
        }
        Configuracion c = new Configuracion();

        c.aplicarDefectosDelCodigo();
        c.aplicarRecursoDelClasspath();
        c.aplicarFicheroExterno(rutaFichero);
        c.aplicarVariablesDeEntorno();
        c.aplicarPropiedadesDelSistema();
        c.validar();

        instancia = c;
        LOG.info(() -> "Configuracion cargada: " + c.resueltas.size() + " propiedades");
        return instancia;
    }

    public static synchronized Configuracion get() {
        if (instancia == null) {
            return cargar(null);
        }
        return instancia;
    }

    /** Solo para pruebas: permite recargar entre casos. */
    static synchronized void reiniciar() { instancia = null; }

    // ---------------------- LOS CINCO NIVELES ----------------------

    /**
     * NIVEL 1: los defectos del codigo.
     *
     * Son los valores que llevan siete modulos escritos a fuego. Ahora estan
     * en un solo sitio y son solo el ULTIMO recurso, no la unica opcion.
     */
    private void aplicarDefectosDelCodigo() {
        poner(PRESTAMO_DIAS,       "15",         "defecto del codigo");
        poner(PRESTAMO_MAXIMO,     "3",          "defecto del codigo");
        poner(MULTA_TARIFA_DIARIA, "0.25",       "defecto del codigo");
        poner(MULTA_MAXIMA,        "20.0",       "defecto del codigo");
        poner(MULTA_UMBRAL_LEVE,   "7",          "defecto del codigo");
        poner(DATOS_DIRECTORIO,    "datos",      "defecto del codigo");
        poner(DATOS_CATALOGO,      "catalogo.csv", "defecto del codigo");
        poner(CSV_SEPARADOR,       ",",          "defecto del codigo");
    }

    /** NIVEL 2: el fichero de fabrica, dentro del jar. */
    private void aplicarRecursoDelClasspath() {
        try (InputStream entrada = Configuracion.class.getResourceAsStream(RECURSO_DEFECTO)) {
            if (entrada == null) {
                LOG.fine(() -> "Sin recurso " + RECURSO_DEFECTO + " en el classpath");
                return;
            }
            // El PUENTE de 07-03 con charset explicito
            try (Reader lector = new InputStreamReader(entrada, StandardCharsets.UTF_8)) {
                volcar(leer(lector), "classpath " + RECURSO_DEFECTO);
            }
        } catch (IOException e) {
            LOG.log(Level.WARNING, "No se pudo leer " + RECURSO_DEFECTO, e);
        }
    }

    /**
     * NIVEL 3: el fichero externo.
     *
     * Su ausencia NO es un error: la primera ejecucion no lo tiene.
     * Degradacion elegante (06-07, 07-01).
     */
    private void aplicarFicheroExterno(Path ruta) {
        Path fichero = (ruta != null) ? ruta : Path.of(FICHERO_EXTERNO);

        if (Files.notExists(fichero)) {
            LOG.info(() -> "No hay fichero de configuracion en "
                    + fichero.toAbsolutePath()
                    + "; se usan los valores por defecto");
            return;
        }

        try (BufferedReader lector = Files.newBufferedReader(
                fichero, StandardCharsets.UTF_8)) {          // 07-06

            volcar(leer(lector), "fichero " + fichero.toAbsolutePath());
            LOG.info(() -> "Configuracion leida de " + fichero.toAbsolutePath());

        } catch (IOException e) {
            // Un fichero ILEGIBLE si es un aviso serio: alguien lo puso ahi
            // esperando que se aplicara, y no se esta aplicando.
            LOG.log(Level.SEVERE, "No se pudo leer " + fichero.toAbsolutePath()
                    + "; se sigue con los valores anteriores", e);
        }
    }

    /**
     * NIVEL 4: variables de entorno.
     *
     * BIBLIOTECH_PRESTAMO_DIAS -> bibliotech.prestamo.dias
     */
    private void aplicarVariablesDeEntorno() {
        for (var entrada : System.getenv().entrySet()) {
            String variable = entrada.getKey();
            if (!variable.startsWith("BIBLIOTECH_")) {
                continue;
            }
            String clave = variable.toLowerCase(Locale.ROOT).replace('_', '.');
            poner(clave, entrada.getValue(), "variable de entorno " + variable);
        }
    }

    /**
     * NIVEL 5: propiedades del sistema (-D). La mayor prioridad.
     */
    private void aplicarPropiedadesDelSistema() {
        Properties sistema = System.getProperties();
        for (String clave : sistema.stringPropertyNames()) {
            if (clave.startsWith(PREFIJO)) {
                poner(clave, sistema.getProperty(clave), "-D" + clave);
            }
        }
    }

    private Properties leer(Reader lector) throws IOException {
        Properties p = new Properties();
        p.load(lector);
        return p;
    }

    private void volcar(Properties origenProps, String descripcion) {
        // stringPropertyNames, NO keySet: incluye los valores por defecto (apartado 12)
        for (String clave : origenProps.stringPropertyNames()) {
            poner(clave, origenProps.getProperty(clave), descripcion);
        }
    }

    private void poner(String clave, String valor, String descripcionOrigen) {
        if (valor == null) {
            return;
        }
        // trim: los espacios finales del valor SI se conservan en .properties
        resueltas.setProperty(clave, valor.trim());
        origen.put(clave, descripcionOrigen);
    }

    // ---------------------- VALIDACION ----------------------

    /**
     * Comprueba que los valores son coherentes.
     *
     * Distincion de 06-07: un fichero AUSENTE degrada (se usan los defectos);
     * un valor INVALIDO ABORTA, porque calcular multas con una tarifa
     * desconocida produciria cobros incorrectos, y eso es peor que no arrancar.
     */
    private void validar() {
        int dias = getEntero(PRESTAMO_DIAS, 15);
        if (dias < 1 || dias > 365) {
            throw new ConfiguracionInvalidaException(PRESTAMO_DIAS,
                    String.valueOf(dias), "debe estar entre 1 y 365");
        }

        int maximo = getEntero(PRESTAMO_MAXIMO, 3);
        if (maximo < 1 || maximo > 50) {
            throw new ConfiguracionInvalidaException(PRESTAMO_MAXIMO,
                    String.valueOf(maximo), "debe estar entre 1 y 50");
        }

        double tarifa = getDecimal(MULTA_TARIFA_DIARIA, 0.25);
        if (tarifa < 0 || tarifa > 100) {
            throw new ConfiguracionInvalidaException(MULTA_TARIFA_DIARIA,
                    String.valueOf(tarifa), "debe estar entre 0 y 100 EUR/dia");
        }

        double maxima = getDecimal(MULTA_MAXIMA, 20.0);
        if (maxima < 0) {
            throw new ConfiguracionInvalidaException(MULTA_MAXIMA,
                    String.valueOf(maxima), "no puede ser negativa");
        }
        if (maxima < tarifa) {
            throw new ConfiguracionInvalidaException(MULTA_MAXIMA,
                    String.valueOf(maxima),
                    "no puede ser menor que la tarifa diaria (" + tarifa + ")");
        }

        int umbral = getEntero(MULTA_UMBRAL_LEVE, 7);
        if (umbral < 0 || umbral > dias) {
            throw new ConfiguracionInvalidaException(MULTA_UMBRAL_LEVE,
                    String.valueOf(umbral),
                    "debe estar entre 0 y el plazo de prestamo (" + dias + ")");
        }
    }

    // ---------------------- ACCESO TIPADO ----------------------

    public String getTexto(String clave, String porDefecto) {
        return resueltas.getProperty(clave, porDefecto);
    }

    /**
     * Entero con valor por defecto.
     *
     * Un valor no numerico NO revienta la aplicacion: se avisa y se usa el
     * defecto. La validacion posterior comprobara el rango.
     */
    public int getEntero(String clave, int porDefecto) {
        String valor = resueltas.getProperty(clave);
        if (valor == null || valor.isBlank()) {
            return porDefecto;
        }
        try {
            return Integer.parseInt(valor.trim());
        } catch (NumberFormatException e) {
            LOG.warning(() -> String.format(
                    "La propiedad %s tiene el valor no numerico '%s' (origen: %s); "
                            + "se usa %d", clave, valor, origen.get(clave), porDefecto));
            return porDefecto;
        }
    }

    /** Decimal. Acepta coma o punto al leer, escribe siempre punto (apartado 7). */
    public double getDecimal(String clave, double porDefecto) {
        String valor = resueltas.getProperty(clave);
        if (valor == null || valor.isBlank()) {
            return porDefecto;
        }
        try {
            return Double.parseDouble(valor.trim().replace(',', '.'));
        } catch (NumberFormatException e) {
            LOG.warning(() -> String.format(
                    "La propiedad %s tiene el valor no numerico '%s' (origen: %s); "
                            + "se usa %s", clave, valor, origen.get(clave), porDefecto));
            return porDefecto;
        }
    }

    public boolean getBooleano(String clave, boolean porDefecto) {
        String valor = resueltas.getProperty(clave);
        if (valor == null || valor.isBlank()) {
            return porDefecto;
        }
        String limpio = valor.trim().toLowerCase(Locale.ROOT);
        return switch (limpio) {                    // switch de expresion (02-03)
            case "true", "si", "yes", "1", "on"  -> true;
            case "false", "no", "0", "off"       -> false;
            default -> {
                LOG.warning(() -> "Valor booleano no reconocido en " + clave
                        + ": '" + valor + "'; se usa " + porDefecto);
                yield porDefecto;
            }
        };
    }

    public char getCaracter(String clave, char porDefecto) {
        String valor = resueltas.getProperty(clave);
        return (valor == null || valor.isEmpty()) ? porDefecto : valor.charAt(0);
    }

    public Path getRuta(String clave, String porDefecto) {
        return Path.of(getTexto(clave, porDefecto));
    }

    /**
     * Volcado de diagnostico: cada propiedad con su valor y su ORIGEN.
     *
     * Saber DE DONDE viene cada valor es lo que permite resolver en un
     * minuto el clasico "he cambiado el fichero y no hace caso": casi
     * siempre hay una variable de entorno o un -D pisandolo.
     */
    public String volcado() {
        StringBuilder sb = new StringBuilder();
        sb.append("=== CONFIGURACION EFECTIVA ===\n");

        for (String clave : new TreeMap<>(origen).keySet()) {
            sb.append(String.format("  %-42s = %-16s [%s]%n",
                    clave, resueltas.getProperty(clave), origen.get(clave)));
        }
        return sb.toString();
    }

    /** Configuracion invalida: la aplicacion NO debe arrancar asi. */
    public static class ConfiguracionInvalidaException extends RuntimeException {

        private static final long serialVersionUID = 1L;      // 07-05

        private final String clave;
        private final String valor;

        public ConfiguracionInvalidaException(String clave, String valor, String motivo) {
            super(String.format(
                    "Configuracion invalida: %s = '%s'. %s. "
                            + "Corrige el fichero de configuracion y vuelve a arrancar.",
                    clave, valor, motivo));
            this.clave = clave;
            this.valor = valor;
        }

        public String getClave() { return clave; }
        public String getValor() { return valor; }
    }
}

// ANTES: escritas a fuego, repartidas por tres clases

public class Prestamo {
    public static final int DIAS_PRESTAMO = 15;          // 06-03
}

public abstract class Material {
    public static final double MULTA_MAXIMA = 20.0;      // 04-02
    public static final int    UMBRAL_LEVE  = 7;         // 04-02
}

public class Libro extends Material {
    public static final double TARIFA_DIARIA_LIBRO = 0.25;   // 04-02
}

public class Empleado {
    public static final int MAX_PRESTAMOS_SIMULTANEOS = 3;   // 03-03
}

package com.nexussoftware.bibliotech.dominio;

import com.nexussoftware.bibliotech.infraestructura.Configuracion;

/**
 * Reglas de negocio de BiblioTech, leidas de la configuracion.
 *
 * Sustituye a las constantes repartidas por el dominio desde el modulo 3.
 * Los valores se leen UNA VEZ al arrancar y quedan fijos durante la
 * ejecucion: cambiarlos a mitad haria que dos prestamos del mismo dia se
 * calcularan con reglas distintas, que es inaceptable en un sistema que
 * cobra dinero.
 *
 * Para recargar la configuracion hay que reiniciar la aplicacion. Es una
 * decision DELIBERADA, no una limitacion.
 */
public final class ReglasNegocio {

    private static final Configuracion CONFIG = Configuracion.get();

    /** Dias de plazo de prestamo. Antes: Prestamo.DIAS_PRESTAMO = 15 */
    public static final int DIAS_PRESTAMO =
            CONFIG.getEntero(Configuracion.PRESTAMO_DIAS, 15);

    /** Prestamos simultaneos por empleado. Antes: Empleado.MAX_PRESTAMOS = 3 */
    public static final int MAX_PRESTAMOS_SIMULTANEOS =
            CONFIG.getEntero(Configuracion.PRESTAMO_MAXIMO, 3);

    /** EUR por dia de retraso. Antes: Libro.TARIFA_DIARIA_LIBRO = 0.25 */
    public static final double TARIFA_DIARIA =
            CONFIG.getDecimal(Configuracion.MULTA_TARIFA_DIARIA, 0.25);

    /** Tope de multa. Antes: Material.MULTA_MAXIMA = 20.0 */
    public static final double MULTA_MAXIMA =
            CONFIG.getDecimal(Configuracion.MULTA_MAXIMA, 20.0);

    /** Dias hasta que el retraso deja de ser leve. Antes: Material.UMBRAL_LEVE = 7 */
    public static final int UMBRAL_LEVE =
            CONFIG.getEntero(Configuracion.MULTA_UMBRAL_LEVE, 7);

    private ReglasNegocio() { }

    /** Resumen para el arranque, para que quede constancia de con que reglas se opera. */
    public static String resumen() {
        return String.format(
                "Reglas: %d dias de prestamo, maximo %d simultaneos, "
                        + "%.2f EUR/dia, tope %.2f EUR, umbral leve %d dias",
                DIAS_PRESTAMO, MAX_PRESTAMOS_SIMULTANEOS,
                TARIFA_DIARIA, MULTA_MAXIMA, UMBRAL_LEVE);
    }
}

public abstract class Material implements Prestable, Notificable {

    // Antes: constantes literales. Ahora: leidas de la configuracion.
    // El Template Method de 04-02 no cambia ni una linea: solo cambia de
    // donde salen los numeros.

    public final double calcularMulta(int diasTranscurridos) {
        int    retraso = calcularDiasRetraso(diasTranscurridos);
        double bruta   = retraso * getTarifaDiaria();
        return Math.min(bruta, ReglasNegocio.MULTA_MAXIMA);
    }

    public final Gravedad clasificarGravedad(int diasTranscurridos) {
        int retraso = calcularDiasRetraso(diasTranscurridos);
        if (retraso == 0)                            { return Gravedad.SIN_RETRASO; }
        if (retraso <= ReglasNegocio.UMBRAL_LEVE)    { return Gravedad.LEVE; }
        return Gravedad.GRAVE;
    }
}

package com.nexussoftware.bibliotech.presentacion;

import java.io.IOException;
import java.nio.file.Path;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.dominio.ReglasNegocio;
import com.nexussoftware.bibliotech.infraestructura.ConfiguracionLog;
import com.nexussoftware.bibliotech.infraestructura.Configuracion;
import com.nexussoftware.bibliotech.servicio.Catalogo;
import com.nexussoftware.bibliotech.servicio.ExportadorCatalogoCsv;

public class BiblioTechApp {

    private static final Logger LOG = Logger.getLogger(BiblioTechApp.class.getName());

    public static void main(String[] args) {
        ConfiguracionLog.inicializar();                      // 06-07

        Configuracion config;
        try {
            Path ruta = (args.length > 0) ? Path.of(args[0]) : null;
            config = Configuracion.cargar(ruta);

        } catch (Configuracion.ConfiguracionInvalidaException e) {
            // Frontera de errores del main (06-07). Un valor invalido ABORTA:
            // arrancar con una tarifa absurda produciria cobros incorrectos.
            System.err.println("ERROR DE CONFIGURACION");
            System.err.println("  " + e.getMessage());
            LOG.log(Level.SEVERE, "Arranque abortado por configuracion invalida", e);
            System.exit(2);
            return;
        }

        LOG.config(config::volcado);

        System.out.println("BiblioTech - Nexus Software");
        System.out.println(ReglasNegocio.resumen());

        try {
            Path directorio = config.getRuta(Configuracion.DATOS_DIRECTORIO, "datos");
            ExportadorCatalogoCsv persistencia = new ExportadorCatalogoCsv(directorio);

            Catalogo catalogo = new Catalogo();
            var resultado = persistencia.importarCatalogo(catalogo);
            System.out.print(resultado.resumen());

            // Guardado al salir (07-02)
            Runtime.getRuntime().addShutdownHook(new Thread(() -> {
                try {
                    int n = persistencia.exportarCatalogo(catalogo);
                    LOG.info("Catalogo guardado al salir: " + n + " materiales");
                } catch (IOException e) {
                    LOG.log(Level.SEVERE, "NO SE PUDO GUARDAR EL CATALOGO", e);
                }
            }, "guardado-final"));

            new MenuBiblioTech(catalogo, persistencia).ejecutar();

        } catch (IOException e) {
            System.err.println("No se pudo acceder al almacen de datos: " + e.getMessage());
            LOG.log(Level.SEVERE, "Fallo de E/S en el arranque", e);
            System.exit(3);
        }
    }
}

# 1. Sin fichero de configuracion: valores por defecto
$ java -cp bibliotech.jar com.nexussoftware.bibliotech.presentacion.BiblioTechApp
BiblioTech - Nexus Software
Reglas: 15 dias de prestamo, maximo 3 simultaneos, 0,25 EUR/dia, tope 20,00 EUR, umbral leve 7 dias

# 2. Con fichero de configuracion
$ cat bibliotech.properties
bibliotech.prestamo.dias = 21
bibliotech.multa.tarifa.diaria = 0.50

$ java -cp bibliotech.jar com.nexussoftware.bibliotech.presentacion.BiblioTechApp
BiblioTech - Nexus Software
Reglas: 21 dias de prestamo, maximo 3 simultaneos, 0,50 EUR/dia, tope 20,00 EUR, umbral leve 7 dias

# 3. Variable de entorno: pisa al fichero
$ BIBLIOTECH_MULTA_MAXIMA=50.0 java -cp bibliotech.jar ...
Reglas: 21 dias de prestamo, maximo 3 simultaneos, 0,50 EUR/dia, tope 50,00 EUR, umbral leve 7 dias

# 4. -D: pisa a todo
$ java -Dbibliotech.prestamo.dias=7 -cp bibliotech.jar ...
Reglas: 7 dias de prestamo, maximo 3 simultaneos, 0,50 EUR/dia, tope 50,00 EUR, umbral leve 7 dias

# 5. Valor invalido: la aplicacion NO arranca
$ java -Dbibliotech.multa.maxima=-5 -cp bibliotech.jar ...
ERROR DE CONFIGURACION
  Configuracion invalida: bibliotech.multa.maxima = '-5.0'. no puede ser negativa.
  Corrige el fichero de configuracion y vuelve a arrancar.
$ echo $?
2

=== CONFIGURACION EFECTIVA ===
  bibliotech.csv.separador                   = ,                [defecto del codigo]
  bibliotech.datos.catalogo                  = catalogo.csv     [defecto del codigo]
  bibliotech.datos.directorio                = datos            [fichero /home/marta/bibliotech.properties]
  bibliotech.multa.maxima                    = 50.0             [variable de entorno BIBLIOTECH_MULTA_MAXIMA]
  bibliotech.multa.tarifa.diaria             = 0.50             [fichero /home/marta/bibliotech.properties]
  bibliotech.multa.umbral.leve               = 7                [defecto del codigo]
  bibliotech.prestamo.dias                   = 7                [-Dbibliotech.prestamo.dias]
  bibliotech.prestamo.maximo.simultaneos     = 3                [defecto del codigo]

# bibliotech.properties: SI va en el repositorio.
# Configuracion funcional, sin ningun secreto.

bibliotech.prestamo.dias = 15
bibliotech.multa.tarifa.diaria = 0.25

# Los secretos NO van aqui. Se leen de variables de entorno:
#   BIBLIOTECH_BD_USUARIO
#   BIBLIOTECH_BD_CLAVE
# En desarrollo, ponlos en bibliotech-local.properties, que esta en .gitignore.

/**
 * Lee un secreto. NUNCA del fichero del repositorio, y NUNCA con un valor
 * por defecto: un secreto ausente debe fallar, no funcionar a medias.
 */
public String getSecreto(String variableDeEntorno) {
    String valor = System.getenv(variableDeEntorno);

    if (valor == null || valor.isBlank()) {
        throw new IllegalStateException(String.format(
                "Falta la variable de entorno %s. Los secretos no se leen del "
                        + "fichero de configuracion. Consulta la documentacion "
                        + "de despliegue.", variableDeEntorno));
    }
    // Y NUNCA registrarlo (06-07): ni el valor, ni una parte, ni su longitud.
    LOG.config(() -> "Secreto " + variableDeEntorno + " cargado correctamente");
    return valor;
}

package com.nexussoftware.bibliotech.pruebas;

import java.io.IOException;
import java.io.StringReader;
import java.io.StringWriter;
import java.util.List;

import com.nexussoftware.bibliotech.infraestructura.EscritorCsv;
import com.nexussoftware.bibliotech.infraestructura.LectorCsv;

/**
 * Bateria de pruebas de ida y vuelta del CSV.
 *
 * La prueba de ida y vuelta —escribir, leer y comparar con el original— es
 * la unica forma seria de validar un formato: si algo vuelve distinto, hay
 * perdida de datos.
 *
 * Trabaja EN MEMORIA con StringWriter y StringReader (07-03): sin ficheros,
 * sin limpieza, sin dependencias del entorno.
 */
public class PruebaCsvCompleta {

    private static int superados = 0;
    private static int fallidos = 0;

    public static void main(String[] args) throws IOException {

        System.out.println("=== IDA Y VUELTA CON SEPARADOR ',' ===");
        char sep = ',';

        probar(sep, "1. Campo normal",            "Java Efectivo", "Bloch", "2018");
        probar(sep, "2. Con separador dentro",    "Java: el lenguaje, la maquina", "Bloch", "2018");
        probar(sep, "3. Con comillas",            "El libro \"Refactorizacion\"", "Fowler", "1999");
        probar(sep, "4. Con salto de linea",      "Titulo con\nsalto de linea", "Autor", "2020");
        probar(sep, "5. Campo vacio en medio",    "Titulo", "", "2021");
        probar(sep, "6. Campo vacio al final",    "Titulo", "Autor", "");
        probar(sep, "7. Todos vacios",            "", "", "");
        probar(sep, "8. Solo espacios",           "   ", "Autor", "2022");
        probar(sep, "9. Espacios en extremos",    "  con espacios  ", "Autor", "2022");
        probar(sep, "10. Acentos y enyes",        "Patrones de Diseño", "Martín Ñuñez", "1994");
        probar(sep, "11. Punto y coma dentro",    "campo;con;puntoycoma", "Autor", "2023");
        probar(sep, "12. Comillas en medio",      "El \"mejor\" libro de Java", "Autor", "2024");
        probar(sep, "13. Solo una comilla",       "Comilla suelta \" aqui", "Autor", "2024");
        probar(sep, "14. Campo muy largo",        "x".repeat(5000), "Autor", "2024");
        probar(sep, "15. Separador y comillas",   "a,b\"c,d", "Autor", "2024");

        System.out.println();
        System.out.println("=== IDA Y VUELTA CON SEPARADOR ';' ===");
        char sep2 = ';';
        probar(sep2, "16. Coma dentro con sep ;", "Java: el lenguaje, la maquina", "Bloch", "2018");
        probar(sep2, "17. Punto y coma dentro",   "campo;con;puntoycoma", "Autor", "2023");

        // ---- Fallo controlado: comillas sin cerrar ----
        System.out.println();
        System.out.println("=== FALLOS CONTROLADOS ===");
        probarComillasSinCerrar();

        // ---- BOM ----
        System.out.println();
        System.out.println("=== MARCA BOM ===");
        probarBom();

        System.out.println();
        System.out.printf("=== RESULTADO: %d superados, %d fallidos ===%n",
                superados, fallidos);

        if (fallidos > 0) {
            System.out.println("HAY PERDIDA DE DATOS. Revisa el escapado.");
        }
    }

    /** Escribe los campos, los vuelve a leer y compara con el original. */
    private static void probar(char separador, String nombre, String... campos)
            throws IOException {

        List<String> originales = List.of(campos);

        StringWriter memoria = new StringWriter();
        try (EscritorCsv escritor = new EscritorCsv(memoria, separador, "\n")) {
            escritor.escribirRegistro(originales);
        }

        String generado = memoria.toString();

        List<String> leidos;
        try (LectorCsv lector = new LectorCsv(new StringReader(generado), separador)) {
            leidos = lector.siguiente();
        }

        boolean ok = originales.equals(leidos);
        if (ok) { superados++; } else { fallidos++; }

        System.out.printf("  %-30s %s%n", nombre, ok ? "OK" : "FALLO");

        if (!ok) {
            System.out.println("      original: " + originales);
            System.out.println("      leido   : " + leidos);
            System.out.println("      csv     : " + generado.replace("\n", "\\n"));
        }
    }

    /** Un fichero con comillas sin cerrar debe fallar indicando la linea. */
    private static void probarComillasSinCerrar() {
        String malo = "titulo,autor\n\"Sin cerrar,Bloch";

        try (LectorCsv lector = new LectorCsv(new StringReader(malo))) {
            lector.siguiente();       // la cabecera, correcta
            lector.siguiente();       // esta debe fallar
            System.out.println("  Comillas sin cerrar          FALLO (deberia lanzar)");
            fallidos++;

        } catch (LectorCsv.CsvFormatoException e) {
            System.out.println("  Comillas sin cerrar          OK");
            System.out.println("      " + e.getMessage());
            superados++;

        } catch (IOException e) {
            System.out.println("  Comillas sin cerrar          FALLO (excepcion inesperada)");
            fallidos++;
        }
    }

    /**
     * La marca BOM que escribe Excel al principio de los ficheros UTF-8.
     *
     * Sin tratarla, la primera columna se lee como "\uFEFFtipo" y NO coincide
     * con "tipo", pese a que el fichero se ve perfecto en cualquier editor.
     */
    private static void probarBom() throws IOException {
        String conBom = "\uFEFFtipo,referencia,titulo\nLIBRO,978-0000000001,Java Efectivo";

        try (LectorCsv lector = new LectorCsv(new StringReader(conBom))) {
            List<String> cabecera = lector.siguiente();

            boolean ok = "tipo".equals(cabecera.get(0));
            if (ok) { superados++; } else { fallidos++; }

            System.out.printf("  BOM eliminado                %s%n", ok ? "OK" : "FALLO");
            System.out.println("      primera columna: '" + cabecera.get(0)
                    + "' (longitud " + cabecera.get(0).length() + ")");

            if (!ok) {
                System.out.println("      El BOM sigue ahi: la comparacion con 'tipo' falla");
            }
        }
    }
}

=== IDA Y VUELTA CON SEPARADOR ',' ===
  1. Campo normal                OK
  2. Con separador dentro        OK
  3. Con comillas                OK
  4. Con salto de linea          OK
  5. Campo vacio en medio        OK
  6. Campo vacio al final        OK
  7. Todos vacios                OK
  8. Solo espacios               OK
  9. Espacios en extremos        OK
  10. Acentos y enyes            OK
  11. Punto y coma dentro        OK
  12. Comillas en medio          OK
  13. Solo una comilla           OK
  14. Campo muy largo            OK
  15. Separador y comillas       OK

=== IDA Y VUELTA CON SEPARADOR ';' ===
  16. Coma dentro con sep ;      OK
  17. Punto y coma dentro        OK

=== FALLOS CONTROLADOS ===
  Comillas sin cerrar          OK
      Linea 2: El fichero termina con unas comillas sin cerrar

=== MARCA BOM ===
  BOM eliminado                OK
      primera columna: 'tipo' (longitud 4)

=== RESULTADO: 19 superados, 0 fallidos ===

package com.nexussoftware.bibliotech.util;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import java.util.TreeSet;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.infraestructura.EscritorCsv;
import com.nexussoftware.bibliotech.infraestructura.LectorCsv;

/**
 * Conversiones entre CSV y Properties, y entre dialectos de CSV.
 *
 * Todas las escrituras son ATOMICAS (07-06): si la conversion falla a mitad,
 * el fichero destino anterior queda intacto.
 */
public class ConversorFormatos {

    private static final Logger LOG = Logger.getLogger(ConversorFormatos.class.getName());
    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    // ---------------------- CSV -> PROPERTIES ----------------------

    /**
     * Convierte un CSV de dos columnas 'clave,valor' en un .properties.
     *
     * OJO: Properties escapa por su cuenta los caracteres especiales, asi
     * que un valor con '=' o ':' se guarda escapado y vuelve correcto.
     */
    public int csvAProperties(Path csv, Path destino, char separador) throws IOException {
        Properties props = new Properties();
        int convertidas = 0;

        try (BufferedReader lector = Files.newBufferedReader(csv, CHARSET);
             LectorCsv entrada = new LectorCsv(lector, separador)) {

            List<String> registro = entrada.siguiente();      // cabecera
            if (registro == null) {
                throw new IOException("El fichero " + csv + " esta vacio");
            }

            while ((registro = entrada.siguiente()) != null) {
                if (registro.size() < 2) {
                    LOG.warning(() -> "Registro con menos de 2 campos; se ignora");
                    continue;
                }
                String clave = registro.get(0).trim();
                if (clave.isEmpty()) {
                    continue;
                }
                props.setProperty(clave, registro.get(1));
                convertidas++;
            }
        }

        escribirPropertiesAtomico(props, destino,
                "Generado desde " + csv.getFileName());

        final int total = convertidas;
        LOG.info(() -> String.format("CSV -> Properties: %d claves en %s",
                total, destino));
        return convertidas;
    }

    // ---------------------- PROPERTIES -> CSV ----------------------

    /** Convierte un .properties en CSV, con las claves ordenadas. */
    public int propertiesACsv(Path properties, Path destino, char separador)
            throws IOException {

        Properties props = new Properties();
        try (BufferedReader lector = Files.newBufferedReader(properties, CHARSET)) {
            props.load(lector);
        }

        // stringPropertyNames, no keySet (apartado 12). TreeSet para ordenar.
        TreeSet<String> claves = new TreeSet<>(props.stringPropertyNames());

        escribirAtomico(destino, salida -> {
            try (EscritorCsv csv = new EscritorCsv(salida, separador, "\n")) {
                csv.escribirCabecera("clave", "valor");
                for (String clave : claves) {
                    csv.escribirRegistro(clave, props.getProperty(clave));
                }
            }
        });

        LOG.info(() -> String.format("Properties -> CSV: %d claves en %s",
                claves.size(), destino));
        return claves.size();
    }

    // ---------------------- CSV -> CSV ----------------------

    /**
     * Cambia el separador de un CSV respetando el escapado.
     *
     * NO es una sustitucion de texto: un campo que contenia el separador
     * NUEVO y no el viejo pasa a necesitar comillas, y al reves. Solo se
     * puede hacer bien parseando y reescribiendo.
     */
    public int csvACsv(Path origen, Path destino, char sepOrigen, char sepDestino)
            throws IOException {

        List<List<String>> registros = new ArrayList<>();

        try (BufferedReader lector = Files.newBufferedReader(origen, CHARSET);
             LectorCsv entrada = new LectorCsv(lector, sepOrigen)) {

            List<String> registro;
            while ((registro = entrada.siguiente()) != null) {
                registros.add(registro);
            }
        }

        escribirAtomico(destino, salida -> {
            try (EscritorCsv csv = new EscritorCsv(salida, sepDestino, "\n")) {
                for (List<String> r : registros) {
                    csv.escribirRegistro(r);
                }
            }
        });

        LOG.info(() -> String.format("CSV '%c' -> CSV '%c': %d registros en %s",
                sepOrigen, sepDestino, registros.size(), destino));
        return registros.size();
    }

    // ---------------------- ESCRITURA ATOMICA ----------------------

    @FunctionalInterface
    private interface Escritura {
        void escribirEn(BufferedWriter salida) throws IOException;
    }

    private void escribirAtomico(Path destino, Escritura contenido) throws IOException {
        Files.createDirectories(destino.toAbsolutePath().getParent());
        Path temporal = destino.resolveSibling(destino.getFileName() + ".tmp");

        boolean completado = false;
        try {
            try (BufferedWriter salida = Files.newBufferedWriter(temporal, CHARSET,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE)) {

                contenido.escribirEn(salida);
            }
            Files.move(temporal, destino,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completado = true;

        } catch (AtomicMoveNotSupportedException e) {
            Files.move(temporal, destino, StandardCopyOption.REPLACE_EXISTING);
            completado = true;

        } finally {
            if (!completado) {
                Files.deleteIfExists(temporal);          // compensacion (06-05)
            }
        }
    }

    private void escribirPropertiesAtomico(Properties props, Path destino, String comentario)
            throws IOException {

        escribirAtomico(destino, salida -> props.store(salida, comentario));
    }

    // ---------------------- DEMOSTRACION ----------------------

    public static void main(String[] args) throws IOException {
        Path dir = Path.of("datos/conversiones");
        Files.createDirectories(dir);

        ConversorFormatos conversor = new ConversorFormatos();

        // 1. CSV de partida con los casos dificiles
        Path csvOriginal = dir.resolve("configuracion.csv");
        Files.writeString(csvOriginal, String.join("\n",
                "clave,valor",
                "bibliotech.prestamo.dias,15",
                "bibliotech.multa.tarifa.diaria,0.25",
                "bibliotech.mensaje.bienvenida,\"Bienvenido a BiblioTech, de Nexus Software\"",
                "bibliotech.separadores,\"punto;y;coma\"",
                "bibliotech.cita,\"El libro \"\"Refactorizacion\"\" de Fowler\"",
                ""), CHARSET);

        System.out.println("=== CSV ORIGINAL ===");
        System.out.println(Files.readString(csvOriginal, CHARSET));

        // 2. CSV -> Properties
        Path props = dir.resolve("configuracion.properties");
        int n1 = conversor.csvAProperties(csvOriginal, props, ',');
        System.out.println("=== PROPERTIES GENERADO (" + n1 + " claves) ===");
        System.out.println(Files.readString(props, CHARSET));

        // 3. Properties -> CSV, con separador ';' para Excel espanol
        Path csvExcel = dir.resolve("configuracion-excel.csv");
        int n2 = conversor.propertiesACsv(props, csvExcel, ';');
        System.out.println("=== CSV PARA EXCEL ESPANOL (" + n2 + " claves) ===");
        System.out.println(Files.readString(csvExcel, CHARSET));

        // 4. CSV ',' -> CSV ';' directamente
        Path csvPuntoYComa = dir.resolve("configuracion-pyc.csv");
        int n3 = conversor.csvACsv(csvOriginal, csvPuntoYComa, ',', ';');
        System.out.println("=== CSV CON SEPARADOR ';' (" + n3 + " registros) ===");
        System.out.println(Files.readString(csvPuntoYComa, CHARSET));

        // 5. Comprobacion: ida y vuelta completa
        Path vuelta = dir.resolve("vuelta.csv");
        conversor.csvACsv(csvPuntoYComa, vuelta, ';', ',');

        boolean identicos = Files.readString(csvOriginal, CHARSET).trim()
                .equals(Files.readString(vuelta, CHARSET).trim());

        System.out.println("=== IDA Y VUELTA ',' -> ';' -> ',' ===");
        System.out.println("  ¿Identico al original? " + identicos);
    }
}

=== CSV CON SEPARADOR ';' (6 registros) ===
clave;valor
bibliotech.prestamo.dias;15
bibliotech.multa.tarifa.diaria;0.25
bibliotech.mensaje.bienvenida;Bienvenido a BiblioTech, de Nexus Software
bibliotech.separadores;"punto;y;coma"
bibliotech.cita;"El libro ""Refactorizacion"" de Fowler"

=== IDA Y VUELTA ',' -> ';' -> ',' ===
  ¿Identico al original? true

package com.nexussoftware.bibliotech.infraestructura;

import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Properties;
import java.util.Set;
import java.util.TreeMap;
import java.util.logging.Logger;

/**
 * Configuracion de BiblioTech con recarga, notificacion de cambios y
 * generacion de plantilla comentada.
 *
 * Amplia la clase del apartado 14 con lo que hace falta para operar el
 * sistema sin pararlo del todo.
 */
public class ConfiguracionRecargable {

    private static final Logger LOG =
            Logger.getLogger(ConfiguracionRecargable.class.getName());

    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    /**
     * Descripcion de una propiedad conocida.
     *
     * 'recargable' distingue lo que se puede cambiar en caliente de lo que
     * exige reiniciar. Las REGLAS DE NEGOCIO no son recargables: cambiar la
     * tarifa a mitad de ejecucion haria que dos prestamos del mismo dia se
     * calcularan con reglas distintas.
     */
    public record DescripcionPropiedad(String clave, String porDefecto,
                                       String descripcion, boolean recargable) { }

    private static final List<DescripcionPropiedad> CONOCIDAS = List.of(
            new DescripcionPropiedad("bibliotech.prestamo.dias", "15",
                    "Dias de plazo de prestamo", false),
            new DescripcionPropiedad("bibliotech.prestamo.maximo.simultaneos", "3",
                    "Prestamos simultaneos por empleado", false),
            new DescripcionPropiedad("bibliotech.multa.tarifa.diaria", "0.25",
                    "EUR por dia de retraso", false),
            new DescripcionPropiedad("bibliotech.multa.maxima", "20.0",
                    "Tope de multa por prestamo, en EUR", false),
            new DescripcionPropiedad("bibliotech.multa.umbral.leve", "7",
                    "Dias hasta que el retraso deja de ser leve", false),
            new DescripcionPropiedad("bibliotech.datos.directorio", "datos",
                    "Directorio de datos", true),
            new DescripcionPropiedad("bibliotech.datos.catalogo", "catalogo.csv",
                    "Nombre del fichero de catalogo", true),
            new DescripcionPropiedad("bibliotech.csv.separador", ",",
                    "Separador de campos del CSV: ',' o ';' para Excel espanol", true),
            new DescripcionPropiedad("bibliotech.log.nivel", "INFO",
                    "Nivel de registro: SEVERE, WARNING, INFO, CONFIG, FINE", true));

    /** Oyente de cambios de configuracion (interfaz funcional, 04-06). */
    @FunctionalInterface
    public interface OyenteConfiguracion {
        void cambiado(String clave, String anterior, String nuevo);
    }

    /** Un cambio detectado en la recarga. */
    public record Cambio(String clave, String anterior, String nuevo, boolean recargable) {

        public String linea() {
            return String.format("%-42s %-14s -> %-14s %s",
                    clave, anterior == null ? "(sin valor)" : anterior, nuevo,
                    recargable ? "" : "  [REQUIERE REINICIAR]");
        }
    }

    private final Path ficheroExterno;
    private final Map<String, String> valores = new TreeMap<>();
    private final Map<String, String> origen = new TreeMap<>();
    private final List<OyenteConfiguracion> oyentes = new ArrayList<>();

    public ConfiguracionRecargable(Path ficheroExterno) {
        this.ficheroExterno = Objects.requireNonNull(ficheroExterno);
        cargarTodo();
    }

    public void registrarOyente(OyenteConfiguracion oyente) {
        oyentes.add(Objects.requireNonNull(oyente, "El oyente no puede ser nulo"));
    }

    // ---------------------- CARGA ----------------------

    private void cargarTodo() {
        valores.clear();
        origen.clear();

        // 1. Defectos del codigo
        for (DescripcionPropiedad d : CONOCIDAS) {
            valores.put(d.clave(), d.porDefecto());
            origen.put(d.clave(), "defecto del codigo");
        }

        // 2. Fichero externo
        if (Files.exists(ficheroExterno)) {
            Properties props = new Properties();
            try (var lector = Files.newBufferedReader(ficheroExterno, CHARSET)) {
                props.load(lector);
                for (String clave : props.stringPropertyNames()) {     // no keySet
                    valores.put(clave, props.getProperty(clave).trim());
                    origen.put(clave, "fichero " + ficheroExterno.getFileName());
                }
            } catch (IOException e) {
                LOG.warning(() -> "No se pudo leer " + ficheroExterno + ": " + e.getMessage());
            }
        }

        // 3. Variables de entorno
        for (var e : System.getenv().entrySet()) {
            if (e.getKey().startsWith("BIBLIOTECH_")) {
                String clave = e.getKey().toLowerCase(java.util.Locale.ROOT).replace('_', '.');
                valores.put(clave, e.getValue().trim());
                origen.put(clave, "entorno " + e.getKey());
            }
        }

        // 4. Propiedades del sistema
        for (String clave : System.getProperties().stringPropertyNames()) {
            if (clave.startsWith("bibliotech.")) {
                valores.put(clave, System.getProperty(clave).trim());
                origen.put(clave, "-D" + clave);
            }
        }
    }

    // ---------------------- RECARGA ----------------------

    /**
     * Vuelve a leer todas las fuentes y devuelve los cambios detectados.
     *
     * Notifica a los oyentes de cada cambio, y AVISA de los que necesitan
     * un reinicio para tener efecto.
     */
    public List<Cambio> recargar() {
        Map<String, String> anteriores = new LinkedHashMap<>(valores);

        cargarTodo();

        List<Cambio> cambios = new ArrayList<>();
        Set<String> todas = new java.util.TreeSet<>(anteriores.keySet());
        todas.addAll(valores.keySet());

        for (String clave : todas) {
            String antes = anteriores.get(clave);
            String ahora = valores.get(clave);

            if (Objects.equals(antes, ahora)) {
                continue;
            }
            boolean recargable = esRecargable(clave);
            cambios.add(new Cambio(clave, antes, ahora, recargable));

            // Notificar. Un oyente que falle NO debe romper la recarga.
            for (OyenteConfiguracion oyente : oyentes) {
                try {
                    oyente.cambiado(clave, antes, ahora);
                } catch (RuntimeException e) {
                    LOG.warning(() -> "Un oyente fallo al notificar " + clave
                            + ": " + e.getMessage());
                }
            }

            if (!recargable) {
                LOG.warning(() -> String.format(
                        "La propiedad %s ha cambiado de '%s' a '%s', pero NO se aplica "
                                + "en caliente: hay que reiniciar la aplicacion.",
                        clave, antes, ahora));
            }
        }

        LOG.info(() -> "Recarga: " + cambios.size() + " propiedades cambiadas");
        return cambios;
    }

    private boolean esRecargable(String clave) {
        for (DescripcionPropiedad d : CONOCIDAS) {
            if (d.clave().equals(clave)) {
                return d.recargable();
            }
        }
        return true;      // desconocida: se asume recargable
    }

    // ---------------------- PLANTILLA ----------------------

    /**
     * Genera un .properties comentado con todas las claves conocidas.
     *
     * Se escribe a mano en lugar de con Properties.store porque store NO
     * conserva ni el orden ni los comentarios (apartado 11), y una plantilla
     * sin comentarios ni orden no sirve para nada.
     */
    public void exportarPlantilla(Path destino) throws IOException {
        Files.createDirectories(destino.toAbsolutePath().getParent());
        Path temporal = destino.resolveSibling(destino.getFileName() + ".tmp");

        boolean completado = false;
        try {
            try (BufferedWriter salida = Files.newBufferedWriter(temporal, CHARSET,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE)) {

                salida.write("# ============================================================");
                salida.newLine();
                salida.write("# Configuracion de BiblioTech - Nexus Software");
                salida.newLine();
                salida.write("# Plantilla generada automaticamente.");
                salida.newLine();
                salida.write("#");
                salida.newLine();
                salida.write("# Precedencia, de menor a mayor:");
                salida.newLine();
                salida.write("#   1. defectos del codigo");
                salida.newLine();
                salida.write("#   2. este fichero");
                salida.newLine();
                salida.write("#   3. variables de entorno (BIBLIOTECH_XXX_YYY)");
                salida.newLine();
                salida.write("#   4. propiedades del sistema (-Dbibliotech.xxx.yyy)");
                salida.newLine();
                salida.write("#");
                salida.newLine();
                salida.write("# ATENCION: NO pongas contrasenas ni claves en este fichero");
                salida.newLine();
                salida.write("# si va al control de versiones. Usa variables de entorno.");
                salida.newLine();
                salida.write("# ============================================================");
                salida.newLine();
                salida.newLine();

                for (DescripcionPropiedad d : CONOCIDAS) {
                    String actual = valores.getOrDefault(d.clave(), d.porDefecto());
                    String de = origen.getOrDefault(d.clave(), "defecto del codigo");

                    salida.write("# " + d.descripcion());
                    salida.newLine();
                    salida.write("#   por defecto : " + d.porDefecto());
                    salida.newLine();
                    salida.write("#   valor actual: " + actual + "  (origen: " + de + ")");
                    salida.newLine();
                    salida.write("#   recarga en caliente: " + (d.recargable()
                            ? "SI" : "NO, requiere reiniciar"));
                    salida.newLine();
                    salida.write(d.clave() + " = " + actual);
                    salida.newLine();
                    salida.newLine();
                }
            }

            Files.move(temporal, destino,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completado = true;

            LOG.info(() -> "Plantilla de configuracion generada en " + destino);

        } catch (AtomicMoveNotSupportedException e) {
            Files.move(temporal, destino, StandardCopyOption.REPLACE_EXISTING);
            completado = true;

        } finally {
            if (!completado) {
                Files.deleteIfExists(temporal);
            }
        }
    }

    // ---------------------- ACCESO ----------------------

    public String getTexto(String clave, String porDefecto) {
        return valores.getOrDefault(clave, porDefecto);
    }

    public String volcado() {
        StringBuilder sb = new StringBuilder("=== CONFIGURACION EFECTIVA ===\n");
        for (var e : valores.entrySet()) {
            sb.append(String.format("  %-42s = %-16s [%s]%n",
                    e.getKey(), e.getValue(), origen.get(e.getKey())));
        }
        return sb.toString();
    }

    // ---------------------- DEMOSTRACION ----------------------

    public static void main(String[] args) throws IOException {
        Path fichero = Path.of("datos/bibliotech.properties");
        Files.createDirectories(fichero.getParent());

        Files.writeString(fichero,
                "bibliotech.prestamo.dias = 15\n"
                        + "bibliotech.csv.separador = ,\n", CHARSET);

        ConfiguracionRecargable config = new ConfiguracionRecargable(fichero);

        // Oyente que reacciona a los cambios
        config.registrarOyente((clave, antes, ahora) ->
                System.out.printf("  [OYENTE] %s: '%s' -> '%s'%n", clave, antes, ahora));

        System.out.println(config.volcado());

        // Plantilla comentada para el administrador
        Path plantilla = Path.of("datos/bibliotech-plantilla.properties");
        config.exportarPlantilla(plantilla);
        System.out.println("=== PLANTILLA (primeras lineas) ===");
        try (var lineas = Files.lines(plantilla, CHARSET)) {   // cerrar el flujo (07-06)
            int[] n = { 0 };
            lineas.forEach(l -> {
                if (n[0]++ < 20) {
                    System.out.println("  " + l);
                }
            });
        }

        // Cambiar el fichero y recargar
        System.out.println();
        System.out.println("=== MODIFICANDO EL FICHERO Y RECARGANDO ===");
        Files.writeString(fichero,
                "bibliotech.prestamo.dias = 21\n"
                        + "bibliotech.csv.separador = ;\n"
                        + "bibliotech.log.nivel = FINE\n", CHARSET);

        List<Cambio> cambios = config.recargar();

        System.out.println();
        System.out.println("=== CAMBIOS DETECTADOS ===");
        for (Cambio c : cambios) {
            System.out.println("  " + c.linea());
        }
    }
}

=== MODIFICANDO EL FICHERO Y RECARGANDO ===
  [OYENTE] bibliotech.csv.separador: ',' -> ';'
  [OYENTE] bibliotech.log.nivel: 'INFO' -> 'FINE'
  [OYENTE] bibliotech.prestamo.dias: '15' -> '21'

=== CAMBIOS DETECTADOS ===
  bibliotech.csv.separador                   ,              -> ;
  bibliotech.log.nivel                       INFO           -> FINE
  bibliotech.prestamo.dias                   15             -> 21               [REQUIERE REINICIAR]