🏗️ Capa 1: Ingesta (Backend 1)
La Capa de Ingesta es el pilar fundamental del P2P Dashboard, encargada de la recolección, validación y almacenamiento inicial de los datos del mercado P2P. Su diseño se centra en la seguridad, la organización y la trazabilidad de la información. Esta capa actúa como la puerta de entrada para todos los datos que alimentarán el sistema.
Propósito Principal
Ingestar datos del mercado P2P de forma segura, organizada y trazable, asegurando que la información cruda sea validada y almacenada correctamente antes de ser procesada por capas posteriores.
Componentes Clave de la Capa de Ingesta
La Capa 1 está compuesta por varios elementos que trabajan en conjunto para cumplir su propósito:
- FastAPI (Ingest): El corazón de esta capa, una API RESTful que recibe las solicitudes de los Workers externos. Es responsable de la autenticación, validación de datos y la orquestación del almacenamiento.
- PostgreSQL: La base de datos relacional donde se almacenan los datos limpios y validados en una estructura normalizada.
- Logging + Monitoring: Un sistema robusto para registrar eventos, errores y el estado de las ejecuciones (runs), crucial para la observabilidad y auditoría.
- Workers (externos): Paquetes Python independientes que consultan datos de Binance (u otras fuentes), los transforman y los envían a esta API de Ingesta.
Checklist de Cierre de la Capa 1 (Ingest Layer)
Esta sección detalla los requisitos y verificaciones que aseguran que la Capa de Ingesta está lista para producción, preparada para recibir datos de workers, escalar y servir como base para las siguientes capas.
🧱 Estructura y Modelado de Datos
| Requisito | Estado | Verificación | Descripción Detallada |
|---|---|---|---|
Tablas: offers, payment_methods, users, api_keys, runs |
✅ | Migración aplicada con Alembic | Se han definido y creado las tablas esenciales para almacenar la información del mercado P2P, usuarios y la gestión interna del sistema. Alembic se utiliza para gestionar el esquema de la base de datos de forma versionada y controlada. |
Relaciones FK y M:N (offers ↔ payment_methods) |
✅ | Incluye tabla offer_payment_methods |
Se han establecido las relaciones entre las tablas. Específicamente, la relación muchos a muchos entre offers y payment_methods se maneja a través de una tabla intermedia (offer_payment_methods), permitiendo que una oferta pueda tener múltiples métodos de pago y un método de pago pueda estar asociado a múltiples ofertas. |
Campo run_id agregado a offers |
✅ | Útil para trazabilidad por extracción | Cada oferta registrada en la base de datos incluye un run_id. Este campo es una clave foránea que referencia a la tabla runs, permitiendo rastrear el origen de cada conjunto de ofertas a una ejecución específica del Worker. Esto es crucial para la auditoría y el análisis de la calidad de los datos. |
Tabla runs con fetched_at, error_message, total_offers |
✅ | Para versionar ejecuciones | La tabla runs registra cada intento de extracción de datos por parte de un Worker. Contiene metadatos importantes como la marca de tiempo de la extracción (fetched_at), cualquier mensaje de error asociado (error_message) y el número total de ofertas procesadas (total_offers). Esto proporciona un historial completo de las operaciones de ingesta. |
Base.metadata.create_all() reemplazado por Alembic |
✅ | Evita colisiones y desorden en schema | En lugar de usar Base.metadata.create_all() (que crea todas las tablas definidas en el modelo cada vez que se ejecuta la aplicación), se utiliza Alembic para gestionar las migraciones de la base de datos. Esto asegura que los cambios en el esquema se apliquen de forma incremental y controlada, evitando conflictos y facilitando el despliegue en diferentes entornos. |
🔐 Autenticación y Acceso
| Requisito | Estado | Verificación | Descripción Detallada |
|---|---|---|---|
Registro de users admin |
✅ | Ruta protegida en /admin/users/ |
El sistema permite el registro y gestión de usuarios con rol de administrador. Las operaciones relacionadas con estos usuarios (creación, modificación, eliminación) están protegidas y solo son accesibles a través de rutas específicas (/admin/users/) que requieren autenticación y autorización adecuadas. |
| Generación de API Keys con prefijo y secreto | ✅ | CRUD implementado | Se ha implementado un sistema para generar API Keys únicas, que incluyen un prefijo y un secreto. Estas claves son utilizadas por los Workers externos para autenticarse al enviar datos a la API de Ingesta. Se dispone de funcionalidades CRUD (Crear, Leer, Actualizar, Eliminar) para la gestión de estas claves. |
| Validación de API Key en endpoints de ingestión | ✅ | Depends(get_api_key) |
Todos los endpoints de la API de Ingesta que reciben datos de los Workers (/api/v1/binance/offers) requieren una API Key válida. La validación se realiza mediante una dependencia de FastAPI (Depends(get_api_key)), que verifica la autenticidad y validez de la clave proporcionada en la solicitud. |
| Autenticación por JWT para endpoints admin | ✅ | /admin/token + get_current_active_user |
Los endpoints administrativos están protegidos mediante autenticación basada en JWT (JSON Web Tokens). Los usuarios administradores deben obtener un token de acceso a través de la ruta /admin/token y luego incluir este token en sus solicitudes. La dependencia get_current_active_user asegura que solo los usuarios autenticados y activos puedan acceder a estas rutas. |
🚦 Ingestión y Monitoreo
| Requisito | Estado | Verificación | Descripción Detallada |
|---|---|---|---|
Endpoint /api/v1/binance/offers funcional |
✅ | Extrae, guarda, actualiza run | El endpoint principal de ingesta de datos (/api/v1/binance/offers) está completamente operativo. Es capaz de recibir los datos de ofertas P2P, validarlos, almacenarlos en la base de datos y actualizar el estado de la ejecución (run) asociada. |
| Logging estructurado en consola + archivo | ✅ | RotatingFileHandler, con logs por módulo |
Se ha implementado un sistema de logging avanzado que registra eventos tanto en la consola como en archivos. Utiliza RotatingFileHandler para gestionar el tamaño de los archivos de log y organiza los logs por módulos, facilitando la depuración y el monitoreo. Los logs incluyen información relevante como la marca de tiempo, el nivel de severidad, el módulo de origen y el mensaje. |
Función get_run_stats(db) creada |
✅ | Agrega resumen: último run, errores, volumen | Se ha desarrollado una función get_run_stats(db) que proporciona un resumen agregado del estado de las ejecuciones de ingesta. Esta función puede devolver información como el último run exitoso, el número de errores recientes, el volumen total de ofertas procesadas, etc., ofreciendo una visión rápida del rendimiento del sistema. |
Endpoint /admin/monitoring/summary funcionando |
✅ | Devuelve JSON con KPIs de ejecución | Se ha expuesto un endpoint administrativo (/admin/monitoring/summary) que utiliza la función get_run_stats(db) para devolver un JSON con los KPIs (Key Performance Indicators) de las ejecuciones de ingesta. Este endpoint es crucial para el monitoreo en tiempo real del sistema. |
Uso de logger.exception, logger.info, etc. |
✅ | Auditabilidad clara por ejecución | Se hace un uso consistente de los diferentes niveles de logging (logger.exception, logger.info, logger.warning, logger.error, logger.debug) en todo el código de la Capa de Ingesta. Esto asegura una auditabilidad clara de cada ejecución, permitiendo identificar rápidamente el origen y la naturaleza de cualquier problema. |
📁 Organización y Calidad del Código
| Requisito | Estado | Verificación | Descripción Detallada |
|---|---|---|---|
Código modular (crud, schemas, models, services) |
✅ | Separación de responsabilidades | El código de la Capa de Ingesta está organizado en módulos lógicos (crud.py para operaciones de base de datos, schemas.py para modelos de datos Pydantic, models.py para modelos SQLAlchemy, services.py para lógica de negocio). Esta separación de responsabilidades mejora la legibilidad, mantenibilidad y testabilidad del código. |
Manejo de errores con ScraperError y logs |
✅ | HTTP 503 en caso de falla controlada | Se ha implementado un manejo de errores robusto, utilizando excepciones personalizadas como ScraperError para encapsular problemas específicos de la extracción o procesamiento de datos. En caso de fallos controlados, la API devuelve un código de estado HTTP 503 (Service Unavailable) junto con un mensaje de error descriptivo, y se registran los detalles completos en los logs. |
| Diagrama de arquitectura generado | ✅ | Imagen profesional clara de las capas | Se ha creado un diagrama visual de la arquitectura del sistema (como el presentado en la sección de Arquitectura), que proporciona una representación clara y profesional de las diferentes capas y sus interacciones. Esto es fundamental para la documentación y la comprensión del sistema. |
🧠 Estratégico / Escalabilidad
| Requisito | Estado | Verificación | Descripción Detallada |
|---|---|---|---|
| Workers externos planeados como paquetes Python | ✅ | Capa 1 solo recibe, no scrapea | La Capa de Ingesta está diseñada para recibir datos de Workers externos, no para realizar el scraping directamente. Esto permite que los Workers sean desarrollados y desplegados de forma independiente, incluso en diferentes ubicaciones o máquinas, desacoplando la lógica de extracción de la lógica de ingesta. |
| Pensado para deploy multi-nodo (MiniPC, países) | ✅ | API Key + ejecución descentralizada | La arquitectura de la Capa de Ingesta soporta despliegues multi-nodo. Los Workers pueden operar desde diferentes ubicaciones (ej. MiniPCs en distintos países) y enviar datos a una instancia centralizada de la API de Ingesta, utilizando sus API Keys para autenticación. Esto facilita la recolección de datos geográficamente distribuidos. |
| Preparado para Capa 2: exposición pública | ✅ | Lectura separada de escritura | La Capa de Ingesta se enfoca exclusivamente en la escritura (ingesta) de datos. La lectura y exposición de datos procesados se delega a la Capa 2 (API de Analítica). Esta separación de responsabilidades de lectura/escritura es un patrón de diseño que mejora la escalabilidad y la seguridad. |
| Preparado para Capa 3: dashboards, MCP | ✅ | Base limpia, trazable, escalable | Al asegurar que la Capa de Ingesta proporciona una base de datos limpia, trazable y escalable, se sienta el terreno para el desarrollo de la Capa 3 (dashboards y aplicaciones de visualización) y la integración con sistemas más complejos como los modelos de Mercado de Capitales P2P (MCP). |
Conclusión de la Capa 1
La Capa de Ingesta está oficialmente:
- 💥 Lista para producción: Ha cumplido con todos los requisitos de diseño, seguridad y funcionalidad.
- ⚙️ Lista para integración con workers: Preparada para recibir datos de los Workers externos.
- 📊 Lista para ser monitoreada: Equipada con herramientas de logging y endpoints de monitoreo.
- 🧱 Base sólida para Capa 2 y 3: Proporciona los datos fundamentales y la infraestructura necesaria para el desarrollo de las capas superiores del P2P Dashboard.