update

README.md

@@ -51,6 +51,85 @@ app/
 └── main.py       Punto de entrada (crea la app).
 ```
 
+### Cómo extender
+
+Añadir una nueva entidad es directo gracias al `BaseService`
+(`app/services/base.py`), que implementa el CRUD genérico:
+
+1. Define el modelo en `models/` y los esquemas en `schemas/`.
+2. Crea un servicio que herede de `BaseService` (fija `collection_name`).
+3. Añade el router en `rutas/` e inclúyelo en `rutas/__init__.py`.
+4. (Opcional) Declara índices en `database/indexes.py`.
+
+## Requisitos
+
+- Python 3.11+
+- MongoDB 4.4+ en ejecución (local o remoto)
+
+## Instalación
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # En Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Configuración
+
+Copia `.env.example` a `.env` y ajusta los valores:
+
+```bash
+cp .env.example .env
+```
+
+Genera una clave secreta segura para `SECRET_KEY`:
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+| Variable                      | Descripción                                   | Por defecto                 |
+|-------------------------------|-----------------------------------------------|-----------------------------|
+| `APP_NAME`                    | Nombre de la aplicación                       | `Directorio Online API`     |
+| `APP_VERSION`                 | Versión                                       | `1.0.0`                     |
+| `APP_DESCRIPTION`             | Descripción de la API                         | (ver `.env.example`)        |
+| `DEBUG`                       | Modo depuración                               | `false`                     |
+| `API_PREFIX`                  | Prefijo de las rutas                          | `/api/v1`                   |
+| `PORT`                        | Puerto de escucha del contenedor              | `7860`                      |
+| `MONGODB_URI`                 | URI de conexión a MongoDB                     | `mongodb://localhost:27017` |
+| `MONGODB_DB_NAME`             | Nombre de la base de datos                    | `directorio_online`         |
+| `SECRET_KEY`                  | Clave para firmar los JWT (**obligatoria**)   | —                           |
+| `ALGORITHM`                   | Algoritmo de firma del JWT                    | `HS256`                     |
+| `ACCESS_TOKEN_EXPIRE_MINUTES` | Validez del token de acceso (minutos)         | `60`                        |
+| `CORS_ORIGINS`                | Orígenes permitidos (lista por comas o `*`)   | `*`                         |
+
+## Ejecución
+
+```bash
+uvicorn app.main:app --reload
+```
+
+- Documentación interactiva (Swagger): `http://localhost:8000/docs`
+- Documentación alternativa (ReDoc): `http://localhost:8000/redoc`
+- Comprobación de salud: `http://localhost:8000/health`
+
+## Docker
+
+La aplicación se empaqueta con el `Dockerfile` incluido. El contenedor
+escucha en el puerto indicado por la variable `PORT` (por defecto `7860`).
+
+```bash
+# Construir la imagen
+docker build -t directorio-online-backend .
+
+# Ejecutar (las variables se pasan con -e o con --env-file)
+docker run --rm -p 7860:7860 \
+  -e SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')" \
+  -e MONGODB_URI="mongodb+srv://usuario:password@cluster.mongodb.net" \
+  -e MONGODB_DB_NAME="directorio_online" \
+  directorio-online-backend
+```
+
 La API quedará disponible en `http://localhost:7860` (Swagger en `/docs`).
 
 ## Despliegue en HuggingFace Spaces (Docker)

app/core/app.py

@@ -27,7 +27,19 @@ def create_app() -> FastAPI:
 
     @app.get("/health", tags=["Salud"], summary="Estado del servicio")
     async def health() -> dict[str, str]:
-        """Endpoint de comprobación de salud."""
+        """Liveness: responde siempre y rápido (no depende de la base de datos)."""
         return {"status": "ok"}
 
+    @app.get(
+        "/health/db",
+        tags=["Salud"],
+        summary="Estado de la conexión a MongoDB",
+    )
+    async def health_db() -> dict[str, str]:
+        """Readiness: comprueba si MongoDB responde en este momento."""
+        from app.database.mongodb import mongodb
+
+        conectado = await mongodb.ping()
+        return {"database": "connected" if conectado else "disconnected"}
+
     return app

app/core/config.py

@@ -32,6 +32,8 @@ class Settings(BaseSettings):
     # --- Base de datos (MongoDB) ---
     MONGODB_URI: str = "mongodb://localhost:27017"
     MONGODB_DB_NAME: str = "directorio_online"
+    # Tiempo máximo (ms) para seleccionar un servidor de MongoDB.
+    MONGODB_TIMEOUT_MS: int = 5000
 
     # --- Seguridad / JWT ---
     SECRET_KEY: str

app/core/lifespan.py

@@ -1,11 +1,13 @@
 """Ciclo de vida de la aplicación.
 
-Abre la conexión con MongoDB y asegura los índices al arrancar; cierra
-la conexión de forma ordenada al apagar.
+Crea el cliente de MongoDB y, si responde, asegura los índices. Si la base
+de datos no está disponible al arrancar, la aplicación arranca igualmente
+(no se cae) y la conexión se reintentará en cada petición.
 """
 
 from __future__ import annotations
 
+import logging
 from contextlib import asynccontextmanager
 from typing import AsyncIterator
 
@@ -14,12 +16,24 @@ from fastapi import FastAPI
 from app.database.indexes import ensure_indexes
 from app.database.mongodb import mongodb
 
+logger = logging.getLogger(__name__)
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     """Gestiona los recursos de la aplicación durante su ciclo de vida."""
     await mongodb.connect()
-    await ensure_indexes()
+    if await mongodb.ping():
+        try:
+            await ensure_indexes()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("No se pudieron crear los índices: %s", exc)
+    else:
+        logger.warning(
+            "La aplicación arranca SIN conexión a MongoDB. Se reintentará "
+            "en cada petición. Revisa MONGODB_URI y el IP Access List de "
+            "Atlas (debe incluir 0.0.0.0/0 para hosts en la nube)."
+        )
     try:
         yield
     finally:

app/database/mongodb.py

@@ -3,11 +3,16 @@
 Se utiliza el driver oficial ``pymongo`` con su API asíncrona
 (:class:`pymongo.AsyncMongoClient`), disponible de forma estable a
 partir de PyMongo 4.13.
+
+El cliente se crea de forma perezosa: la conexión real se abre en la
+primera operación, por lo que la aplicación puede arrancar aunque la
+base de datos no esté disponible todavía (no se bloquea el arranque).
 """
 
 from __future__ import annotations
 
 import logging
+import socket
 
 from pymongo import AsyncMongoClient
 from pymongo.asynchronous.collection import AsyncCollection
@@ -22,23 +27,72 @@ class MongoDB:
     """Contenedor del cliente y la base de datos de MongoDB.
 
     Mantiene una única instancia del cliente durante el ciclo de vida de
-    la aplicación. La conexión se abre en el ``lifespan`` y se cierra al
-    apagar el servidor.
+    la aplicación.
     """
 
     client: AsyncMongoClient | None = None
     database: AsyncDatabase | None = None
 
     async def connect(self) -> None:
-        """Abre la conexión con MongoDB y verifica su disponibilidad."""
+        """Crea el cliente de MongoDB sin bloquear el arranque.
+
+        No se hace ``ping`` aquí a propósito: el cliente es perezoso y la
+        conexión se abre en la primera operación. Así la app arranca aunque
+        Mongo no responda todavía.
+        """
         if self.client is not None:
             return
-        logger.info("Conectando a MongoDB en %s", settings.MONGODB_URI)
-        self.client = AsyncMongoClient(settings.MONGODB_URI, tz_aware=True)
+        self.client = AsyncMongoClient(
+            settings.MONGODB_URI,
+            tz_aware=True,
+            serverSelectionTimeoutMS=settings.MONGODB_TIMEOUT_MS,
+        )
         self.database = self.client[settings.MONGODB_DB_NAME]
-        # Verifica que la conexión es válida.
-        await self.client.admin.command("ping")
-        logger.info("Conexión a MongoDB establecida (db=%s)", settings.MONGODB_DB_NAME)
+
+    async def ping(self) -> bool:
+        """Comprueba si MongoDB responde. No lanza excepción."""
+        if self.client is None:
+            return False
+        try:
+            await self.client.admin.command("ping")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("MongoDB no responde: %s", exc)
+            self._diagnostico_red()
+            return False
+        logger.info("MongoDB conectado (db=%s).", settings.MONGODB_DB_NAME)
+        return True
+
+    def _diagnostico_red(self) -> None:
+        """Registra un diagnóstico de red hacia los nodos de MongoDB.
+
+        Resuelve el DNS y prueba un socket TCP crudo a cada nodo para
+        distinguir un bloqueo de red de un problema del driver/credenciales.
+        """
+        try:
+            nodos = self.client.topology_description.server_descriptions()
+        except Exception:  # noqa: BLE001
+            return
+        for host, port in nodos:
+            try:
+                ip = socket.gethostbyname(host)
+            except OSError as exc:
+                logger.warning("DIAG DNS %s -> FALLA (%s)", host, exc)
+                continue
+            sock = socket.socket()
+            sock.settimeout(5)
+            try:
+                sock.connect((host, port))
+                logger.warning("DIAG TCP %s:%s (%s) -> OK", host, port, ip)
+            except OSError as exc:
+                logger.warning(
+                    "DIAG TCP %s:%s (%s) -> BLOQUEADO/timeout (%s)",
+                    host,
+                    port,
+                    ip,
+                    type(exc).__name__,
+                )
+            finally:
+                sock.close()
 
     async def close(self) -> None:
         """Cierra la conexión con MongoDB."""