Esquema versionado y BD de usuarios en volumen persistente si lo hay

ARCHITECTURE_REVIEW §3.4.

MIGRACIONES. El esquema era un único `CREATE TABLE IF NOT EXISTS`: creaba las
tablas en una BD vacía y no hacía NADA sobre una existente, así que añadir una
columna era una operación manual sobre un fichero al que, en Spaces, nadie puede
llegar. Ahora `PRAGMA user_version` con pasos numerados; sólo se aplican los
pendientes. Los pasos son reejecutables sobre lo ya existente porque las BD
creadas antes de esto están en la versión 0 con las tablas del paso 1 ya dentro
—ese es el caso de la instancia desplegada, y hay prueba de que se pone al día
sin perder cuentas—. Paso 2: índice para el throttle de login, que filtraba por
email+ip+momento con scan completo en cada intento.

PERSISTENCIA. `db_path` apuntaba siempre a `instance/`, que en Spaces no
sobrevive al reinicio: cada rebuild se llevaba cuentas, hashes e historial. Ahora
se elige /data si hay un volumen persistente montado ahí, y si no se cae a
`instance/` AVISANDO al arrancar. Se elige solo porque el fallo del defecto
anterior era silencioso: la app arrancaba igual y sólo se notaba cuando los
usuarios ya no podían entrar. Sigue forzable con MORPHOS_DB_PATH.

MYSQL FANTASMA. `mysql_dsn`/`mysql_user`/`mysql_password` decían «si se define, se
usa en vez de SQLite» y NADA en el código los leía: quien los configurara seguiría
sobre SQLite sin enterarse. Se eliminan. Una opción de configuración que miente es
peor que no tenerla.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/.env.example

@@ -21,8 +21,12 @@ MORPHOS_COOKIE_SECURE=false     # true en prod (HTTPS)
 # MORPHOS_REGISTRO_ALLOWLIST=vet1@clinica.com,vet2@clinica.com
 MORPHOS_REGISTRO_ABIERTO=false   # true SÓLO en desarrollo local
 
-# --- Base de datos de usuarios (SQLite fuera del webroot por defecto) ---
-# MORPHOS_DB_PATH=/ruta/fuera/webroot/morphos.db
+# --- Base de datos de usuarios (SQLite fuera del webroot) ---
+# Por defecto se usa /data/morphos.db si existe un volumen PERSISTENTE ahí (es donde HF Spaces
+# monta el almacenamiento contratado); si no, instance/morphos.db, que es EFÍMERO: cada
+# reinicio borra cuentas, contraseñas e historial de intentos y todo el mundo se vuelve a
+# registrar. Se avisa al arrancar. NO hay soporte de MySQL pese a lo que decía la config vieja.
+# MORPHOS_DB_PATH=/data/morphos.db
 
 # --- Ruta IA por defecto ---
 MORPHOS_IA_BACKEND_DEFECTO=medgemma   # medgemma | claude

backend/app/config.py

@@ -21,6 +21,23 @@ log = logging.getLogger(__name__)
 # Raíz del repo (…/morphos). La BD y el índice RAG viven FUERA del directorio servido.
 RAIZ_REPO = Path(__file__).resolve().parents[2]
 
+# Punto de montaje del almacenamiento persistente en HF Spaces.
+VOLUMEN_PERSISTENTE = Path("/data")
+
+
+def _ruta_db_por_defecto() -> Path:
+    """Volumen persistente si lo hay; si no, `instance/` (efímero) con aviso al arrancar.
+
+    En HF Spaces `instance/` se pierde en cada reinicio y con él TODAS las cuentas. Si el Space
+    tiene almacenamiento persistente contratado, se monta en /data y ahí sí sobreviven. Se elige
+    solo en vez de exigir configuración porque el fallo del defecto anterior era silencioso: la
+    app arrancaba igual y el problema sólo se veía cuando los usuarios ya no podían entrar.
+    Siempre se puede forzar con MORPHOS_DB_PATH.
+    """
+    if VOLUMEN_PERSISTENTE.is_dir() and os.access(VOLUMEN_PERSISTENTE, os.W_OK):
+        return VOLUMEN_PERSISTENTE / "morphos.db"
+    return RAIZ_REPO / "instance" / "morphos.db"
+
 
 # El `.env` del desarrollador NO debe filtrarse a las pruebas: son las mismas que corren en CI,
 # donde ese fichero no existe, así que cualquier valor que se cuele hace que pasen o fallen según
@@ -66,10 +83,16 @@ class Configuracion(BaseSettings):
     registro_allowlist: Annotated[list[str], NoDecode] = Field(default_factory=list)
 
     # --- Base de datos (usuarios). Ruta fuera del webroot. ---
-    db_path: Path = Field(default=RAIZ_REPO / "instance" / "morphos.db")
-    mysql_dsn: str = Field(default="")  # si se define, se usa en vez de SQLite
-    mysql_user: str = Field(default="")
-    mysql_password: str = Field(default="")
+    # Se prefiere el volumen persistente si existe (ver `_ruta_db_por_defecto`). `instance/` NO
+    # sobrevive a un reinicio en Spaces: allí cada rebuild se llevaba por delante las cuentas,
+    # los hashes y el historial de throttling, y los usuarios tenían que volver a registrarse.
+    db_path: Path = Field(default_factory=lambda: _ruta_db_por_defecto())
+
+    # NO hay soporte de MySQL. Existían `mysql_dsn`/`mysql_user`/`mysql_password` con el
+    # comentario «si se define, se usa en vez de SQLite», pero NADA en el código los leía: quien
+    # los configurara seguiría sobre SQLite sin enterarse. Se eliminan en vez de dejarlos: una
+    # opción de configuración que miente es peor que no tenerla. Para sacar los usuarios de
+    # SQLite, el camino es un volumen persistente (MORPHOS_DB_PATH) o portar `db.py`.
 
     # --- Ruta IA por defecto y proveedores ---
     ia_backend_defecto: str = Field(default="medgemma")  # medgemma | claude

backend/app/db.py

@@ -10,14 +10,29 @@ from __future__ import annotations
 
 import hashlib
 import hmac
+import logging
 import secrets
 import sqlite3
 from collections.abc import Iterator
 from contextlib import contextmanager
 
-from .config import obtener_config
-
-_ESQUEMA = """
+from .config import VOLUMEN_PERSISTENTE, obtener_config
+
+log = logging.getLogger("morphos.db")
+
+# Migraciones versionadas con `PRAGMA user_version`. Antes esto era un único script de
+# `CREATE TABLE IF NOT EXISTS`: creaba el esquema en una BD vacía y no hacía NADA sobre una
+# existente, así que añadir una columna era una operación manual sobre un fichero al que, en
+# Spaces, nadie puede llegar. Cada entrada de la lista es un paso; el índice+1 es la versión
+# resultante, y sólo se aplican los pasos por encima de la versión actual.
+#
+# Reglas: nunca se edita un paso ya publicado (una BD que lo aplicó no volvería a ejecutarlo),
+# los pasos se añaden al final, y cada uno debe poder correr sobre una BD que ya lo tuviera
+# —de ahí los `IF NOT EXISTS`—, porque las BD creadas antes de este mecanismo están en la
+# versión 0 con las tablas del paso 1 ya presentes.
+_MIGRACIONES: list[str] = [
+    # 1 — esquema inicial (el que ya existía).
+    """
 CREATE TABLE IF NOT EXISTS usuarios (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     nombre TEXT NOT NULL,
@@ -39,14 +54,40 @@ CREATE TABLE IF NOT EXISTS resultados_lab (
     recibido_en DATETIME DEFAULT CURRENT_TIMESTAMP,
     payload_json TEXT NOT NULL
 );
-"""
+""",
+    # 2 — índice para el throttle de login: `intentos_recientes` filtra por email+ip+momento en
+    # cada intento y hacía scan completo de la tabla.
+    """
+CREATE INDEX IF NOT EXISTS idx_intentos_email_ip_momento
+    ON intentos_login (email, ip, momento);
+""",
+]
+
+
+def _migrar(con: sqlite3.Connection) -> int:
+    """Aplica los pasos pendientes y devuelve la versión resultante."""
+    version = con.execute("PRAGMA user_version").fetchone()[0]
+    for indice in range(version, len(_MIGRACIONES)):
+        con.executescript(_MIGRACIONES[indice])
+        # `PRAGMA` no admite parámetros; el valor es un índice entero nuestro, no entrada.
+        con.execute(f"PRAGMA user_version = {indice + 1}")
+    return len(_MIGRACIONES)
 
 
 def inicializar_db() -> None:
     cfg = obtener_config()
     cfg.db_path.parent.mkdir(parents=True, exist_ok=True)
     with _conexion() as con:
-        con.executescript(_ESQUEMA)
+        version = _migrar(con)
+    persistente = cfg.db_path.is_relative_to(VOLUMEN_PERSISTENTE)
+    log.info("BD en %s (esquema v%d, %s).", cfg.db_path, version,
+             "persistente" if persistente else "EFÍMERA: las cuentas no sobreviven al reinicio")
+    if not persistente:
+        log.warning(
+            "La base de usuarios está en almacenamiento EFÍMERO (%s): cada reinicio borra "
+            "cuentas, contraseñas e historial de intentos. Monta un volumen persistente o "
+            "apunta MORPHOS_DB_PATH a uno.", cfg.db_path,
+        )
 
 
 @contextmanager

backend/tests/test_migraciones_db.py

@@ -0,0 +1,117 @@
+"""Versionado del esquema de la BD de usuarios.
+
+Antes era un único `CREATE TABLE IF NOT EXISTS`: creaba el esquema en una BD vacía y no hacía
+NADA sobre una existente. Añadir una columna era una operación manual sobre un fichero al que,
+en HF Spaces, nadie puede llegar.
+
+Lo que hay que sostener: los pasos se aplican una sola vez, se aplican en orden, y una BD creada
+ANTES de este mecanismo (versión 0 con las tablas del paso 1 ya dentro) se pone al día sin
+romperse. Ese último es el caso real de la instancia desplegada.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+import pytest
+
+from app import db
+
+
+@pytest.fixture
+def bd(tmp_path, monkeypatch):
+    """BD temporal aislada de la del resto de la suite."""
+    ruta = tmp_path / "prueba.db"
+    monkeypatch.setattr(db.obtener_config(), "db_path", ruta)
+    return ruta
+
+
+def _version(ruta) -> int:
+    con = sqlite3.connect(ruta)
+    try:
+        return con.execute("PRAGMA user_version").fetchone()[0]
+    finally:
+        con.close()
+
+
+def _tablas(ruta) -> set[str]:
+    con = sqlite3.connect(ruta)
+    try:
+        filas = con.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+        return {f[0] for f in filas}
+    finally:
+        con.close()
+
+
+def test_bd_nueva_queda_en_la_ultima_version(bd):
+    db.inicializar_db()
+    assert _version(bd) == len(db._MIGRACIONES)
+    assert {"usuarios", "intentos_login", "resultados_lab"} <= _tablas(bd)
+
+
+def test_reejecutar_es_idempotente(bd):
+    """Arrancar dos veces no debe reaplicar nada ni fallar."""
+    db.inicializar_db()
+    db.inicializar_db()
+    assert _version(bd) == len(db._MIGRACIONES)
+
+
+def test_bd_anterior_al_versionado_se_pone_al_dia(bd):
+    """El caso real: tablas del paso 1 ya presentes y `user_version` en 0.
+
+    Si los pasos no fueran reejecutables sobre lo ya existente, esto reventaría con
+    «table usuarios already exists» y la app no arrancaría contra la BD desplegada.
+    """
+    con = sqlite3.connect(bd)
+    con.executescript(db._MIGRACIONES[0])  # esquema viejo, sin tocar user_version
+    con.commit()
+    con.close()
+    assert _version(bd) == 0
+
+    db.inicializar_db()
+
+    assert _version(bd) == len(db._MIGRACIONES)
+    assert {"usuarios", "intentos_login", "resultados_lab"} <= _tablas(bd)
+
+
+def test_los_datos_sobreviven_a_la_migracion(bd):
+    """Migrar no puede perder cuentas: es exactamente lo que se está intentando dejar de hacer."""
+    con = sqlite3.connect(bd)
+    con.executescript(db._MIGRACIONES[0])
+    con.execute(
+        "INSERT INTO usuarios (nombre, apellido, email, password) VALUES (?,?,?,?)",
+        ("Ana", "Vet", "ana@example.com", "scrypt$x$y"),
+    )
+    con.commit()
+    con.close()
+
+    db.inicializar_db()
+
+    assert db.buscar_usuario("ana@example.com") is not None
+
+
+def test_se_aplica_un_paso_nuevo_sobre_una_bd_ya_migrada(bd, monkeypatch):
+    """Comprueba el mecanismo, no un paso concreto: sin esto, sólo se probaría el estado final."""
+    db.inicializar_db()
+    ya = len(db._MIGRACIONES)
+
+    monkeypatch.setattr(
+        db, "_MIGRACIONES", [*db._MIGRACIONES, "CREATE TABLE IF NOT EXISTS futura (x INTEGER);"]
+    )
+    db.inicializar_db()
+
+    assert _version(bd) == ya + 1
+    assert "futura" in _tablas(bd)
+
+
+def test_el_indice_del_throttle_existe(bd):
+    """Paso 2: `intentos_recientes` filtra por email+ip+momento en cada intento de login."""
+    db.inicializar_db()
+    con = sqlite3.connect(bd)
+    try:
+        indices = {f[0] for f in con.execute(
+            "SELECT name FROM sqlite_master WHERE type='index'"
+        ).fetchall()}
+    finally:
+        con.close()
+    assert "idx_intentos_email_ip_momento" in indices