🗄️ Diseño del Esquema de la Base de Datos

La base de datos PostgreSQL es el corazón del P2P Dashboard, donde se almacena toda la información recolectada y procesada. Un diseño de esquema robusto y normalizado es crucial para asegurar la integridad de los datos, optimizar el rendimiento de las consultas y facilitar la escalabilidad del sistema.

Visión General del Esquema

El esquema de la base de datos está compuesto por varias tablas interconectadas, diseñadas para representar las entidades clave del mercado P2P y la operación interna del sistema. A continuación, se presenta un diagrama conceptual de las relaciones entre las tablas principales:

erDiagram
    RUNS ||--o{ OFFERS : "contiene"
    OFFERS ||--o{ OFFER_PAYMENT_METHODS : "tiene"
    PAYMENT_METHODS }o--|| OFFER_PAYMENT_METHODS : "es_usado_en"
    USERS ||--o{ API_KEYS : "posee"
    USERS ||--o{ RUNS : "inicia"

    RUNS {
        uuid id PK
        timestamp fetched_at
        text error_message
        int total_offers
        uuid user_id FK
    }

    OFFERS {
        uuid id PK
        text asset
        text fiat
        float price
        text trade_type
        float amount
        float min_single_trans_amount
        float max_single_trans_amount
        text advertiser_id
        text advertiser_nick
        int month_order_count
        float month_finish_rate
        float positive_comment_rate
        int taker_coin_count
        text publisher_type
        timestamp created_at
        timestamp updated_at
        uuid run_id FK
    }

    PAYMENT_METHODS {
        uuid id PK
        text name
    }

    OFFER_PAYMENT_METHODS {
        uuid offer_id PK,FK
        uuid payment_method_id PK,FK
    }

    USERS {
        uuid id PK
        text username
        text hashed_password
        boolean is_active
        boolean is_admin
    }

    API_KEYS {
        uuid id PK
        text key_secret
        boolean is_active
        timestamp created_at
        uuid user_id FK
    }

Descripción Detallada de las Tablas

`runs`

Esta tabla registra cada ejecución de un Worker que ingesta datos. Es fundamental para la trazabilidad y el monitoreo del proceso de recolección de datos.

Columna	Tipo de Dato	Descripción	Notas
`id`	`UUID`	Clave primaria única para cada ejecución.	Generado automáticamente.
`fetched_at`	`TIMESTAMP`	Marca de tiempo de cuándo se inició la ejecución.
`error_message`	`TEXT`	Mensaje de error si la ejecución falló.	`NULL` si la ejecución fue exitosa.
`total_offers`	`INTEGER`	Número total de ofertas procesadas en esta ejecución.
`user_id`	`UUID`	Clave foránea que referencia al usuario que inició la ejecución (si aplica).	Relación con la tabla `users`.

`offers`

Almacena los detalles de cada oferta P2P recolectada de los exchanges.

Columna	Tipo de Dato	Descripción	Notas
`id`	`UUID`	Clave primaria única para cada oferta.	Generado automáticamente.
`asset`	`TEXT`	Activo de la oferta (ej. `USDT`, `BTC`).
`fiat`	`TEXT`	Moneda fiat de la oferta (ej. `ARS`, `USD`).
`price`	`FLOAT`	Precio de la oferta.
`trade_type`	`TEXT`	Tipo de operación (`BUY` o `SELL`).
`amount`	`FLOAT`	Cantidad total disponible de la oferta.
`min_single_trans_amount`	`FLOAT`	Monto mínimo por transacción.
`max_single_trans_amount`	`FLOAT`	Monto máximo por transacción.
`advertiser_id`	`TEXT`	ID único del anunciante/comerciante.
`advertiser_nick`	`TEXT`	Nickname del anunciante/comerciante.
`month_order_count`	`INTEGER`	Número de órdenes del anunciante en el último mes.	Puede ser `NULL`.
`month_finish_rate`	`FLOAT`	Tasa de finalización de órdenes del anunciante en el último mes.	Puede ser `NULL`.
`positive_comment_rate`	`FLOAT`	Tasa de comentarios positivos del anunciante.	Puede ser `NULL`.
`taker_coin_count`	`INTEGER`	Número de monedas tomadas (relevante para ofertas de venta).	Puede ser `NULL`.
`publisher_type`	`TEXT`	Tipo de publicador (ej. `merchant`).	Puede ser `NULL`.
`created_at`	`TIMESTAMP`	Marca de tiempo de cuándo se creó el registro.	Generado automáticamente.
`updated_at`	`TIMESTAMP`	Marca de tiempo de la última actualización del registro.	Generado automáticamente.
`run_id`	`UUID`	Clave foránea que referencia la ejecución (`run`) a la que pertenece esta oferta.	Relación con la tabla `runs`.

`payment_methods`

Almacena los nombres únicos de los métodos de pago disponibles en las ofertas.

Columna	Tipo de Dato	Descripción	Notas
`id`	`UUID`	Clave primaria única para cada método de pago.	Generado automáticamente.
`name`	`TEXT`	Nombre del método de pago (ej. `Mercado Pago`, `Transferencia Bancaria`).	Único.

`offer_payment_methods`

Tabla de unión para la relación muchos a muchos entre offers y payment_methods.

Columna	Tipo de Dato	Descripción	Notas
`offer_id`	`UUID`	Clave foránea que referencia a la tabla `offers`.	Parte de la clave primaria compuesta.
`payment_method_id`	`UUID`	Clave foránea que referencia a la tabla `payment_methods`.	Parte de la clave primaria compuesta.

`users`

Almacena la información de los usuarios del sistema, incluyendo administradores.

Columna	Tipo de Dato	Descripción	Notas
`id`	`UUID`	Clave primaria única para cada usuario.	Generado automáticamente.
`username`	`TEXT`	Nombre de usuario único.	Único.
`hashed_password`	`TEXT`	Contraseña del usuario hasheada.	Almacenada de forma segura.
`is_active`	`BOOLEAN`	Indica si la cuenta del usuario está activa.	`TRUE` por defecto.
`is_admin`	`BOOLEAN`	Indica si el usuario tiene privilegios de administrador.	`FALSE` por defecto.

`api_keys`

Almacena las API Keys utilizadas por los Workers para autenticarse.

Columna	Tipo de Dato	Descripción	Notas
`id`	`UUID`	Clave primaria única para cada API Key.	Generado automáticamente.
`key_secret`	`TEXT`	El secreto de la API Key.	Debe ser único y almacenado de forma segura.
`is_active`	`BOOLEAN`	Indica si la API Key está activa.	`TRUE` por defecto.
`created_at`	`TIMESTAMP`	Marca de tiempo de cuándo se creó la API Key.	Generado automáticamente.
`user_id`	`UUID`	Clave foránea que referencia al usuario propietario de la API Key.	Relación con la tabla `users`.

Consideraciones de Diseño

Normalización: El esquema está diseñado siguiendo principios de normalización para reducir la redundancia de datos y mejorar la integridad.
UUIDs: Se utilizan UUIDs (Universally Unique Identifiers) como claves primarias para facilitar la distribución y evitar colisiones en entornos distribuidos.
Índices: Se recomienda la creación de índices adecuados en columnas utilizadas frecuentemente en consultas (ej. asset, fiat, trade_type en offers, name en payment_methods, run_id en offers) para optimizar el rendimiento.
Fechas y Tiempos: Se utilizan tipos de datos TIMESTAMP con zona horaria (UTC) para asegurar la consistencia en el manejo de fechas y tiempos.

Este diseño de esquema proporciona una base sólida y flexible para el almacenamiento y la recuperación de datos en el P2P Dashboard.