trading-platform/docs/90-transversal/requerimientos/RF-DATA-001-sincronizacion-batch-activos.md

id	title	type	status	priority	epic	project	version	created_date	updated_date
RF-DATA-001	Sincronizacion Batch de Datos de Activos con Priorizacion	Requirement	To Do	Alta	Transversal	trading-platform	1.0.0	2026-01-04	2026-01-04

RF-DATA-001: Sincronizacion Batch de Datos de Activos con Priorizacion

Version: 1.0.0 Fecha: 2026-01-04 Modulo: Data Service Prioridad: P0 Story Points: 13

---

Descripcion

El sistema debe implementar un proceso batch automatizado que actualice los datos de activos financieros desde la API de Polygon.io/Massive.com hacia la base de datos PostgreSQL cada 5 minutos, respetando el rate limit de 5 llamadas API por minuto (cuenta gratuita) y priorizando la actualizacion de activos criticos (Oro/XAU, EUR/USD, Bitcoin/BTC).

---

Requisitos Funcionales

RF-DATA-001.1: Ejecucion Programada del Batch

El sistema debe:

• Ejecutar un proceso batch cada 5 minutos
• Iniciar automaticamente al arrancar el Data Service
• Permitir ejecucion manual via API endpoint
• Registrar logs de cada ejecucion

Configuracion:

batch:
  interval_minutes: 5
  auto_start: true
  retry_on_failure: true
  max_retries: 3

RF-DATA-001.2: Priorizacion de Activos

El sistema debe actualizar primero los activos prioritarios antes que cualquier otro:

Prioridad	Simbolo	Tipo	Ticker Polygon
1	XAU/USD	Commodity	C:XAUUSD
2	EUR/USD	Forex	C:EURUSD
3	BTC/USD	Crypto	X:BTCUSD

Comportamiento:

• Los 3 activos prioritarios se actualizan en CADA ciclo de 5 minutos
• Utilizan 3 de las 5 llamadas API disponibles por minuto
• No pueden ser omitidos por ningun motivo

RF-DATA-001.3: Rate Limiting

El sistema debe:

• Respetar el limite de 5 llamadas API por minuto
• Distribuir las llamadas de manera uniforme (espaciado de ~12 segundos)
• Esperar automaticamente si se alcanza el limite
• Registrar metricas de uso de API

Distribucion de Llamadas por Ciclo:

Minuto 0:
  - 0s:  Llamada 1 - XAU/USD (Priority)
  - 12s: Llamada 2 - EUR/USD (Priority)
  - 24s: Llamada 3 - BTC/USD (Priority)
  - 36s: Llamada 4 - Asset de cola
  - 48s: Llamada 5 - Asset de cola

RF-DATA-001.4: Sistema de Cola para Activos Secundarios

El sistema debe:

• Mantener una cola de prioridad para activos no prioritarios
• Procesar activos encolados con las 2 llamadas API restantes por minuto
• Implementar deduplicacion (no encolar duplicados)
• Soportar reintentos con backoff exponencial

Activos Secundarios (ejemplos):

• ETH/USDT (Crypto)
• GBP/USD (Forex)
• USD/JPY (Forex)
• XAG/USD (Plata)
• Indices (SPX, NDX)

RF-DATA-001.5: Actualizacion de Base de Datos

El sistema debe actualizar las siguientes tablas:

Tabla trading.symbols:

• updated_at: Timestamp de ultima actualizacion
• metadata: JSON con precios actuales (bid, ask, last_price)

Tabla data_sources.data_sync_status:

• last_sync_timestamp: Cuando se sincronizo
• sync_status: success | failed | pending
• last_sync_rows: Cantidad de datos actualizados

RF-DATA-001.6: Notificacion de Actualizaciones

El sistema debe:

• Publicar eventos via Redis Pub/Sub al actualizar un activo
• Formato del canal: asset:update:{SYMBOL}
• Incluir en el mensaje: symbol, bid, ask, last_price, timestamp
• Permitir a otros servicios suscribirse a actualizaciones

---

Datos de Entrada

Campo	Tipo	Descripcion	Requerido
symbol	string	Simbolo del activo (ej: XAUUSD)	Si
polygon_ticker	string	Ticker en formato Polygon (ej: C:XAUUSD)	Si
asset_type	enum	forex, crypto, index, commodity	Si
priority	enum	CRITICAL, HIGH, MEDIUM, LOW	No (default: MEDIUM)

---

Datos de Salida

Respuesta de Snapshot por Activo

interface AssetSnapshot {
  symbol: string;
  bid: number;
  ask: number;
  spread: number;
  last_price: number;
  daily_open: number;
  daily_high: number;
  daily_low: number;
  daily_close: number;
  daily_volume: number;
  timestamp: string;  // ISO 8601
}

Resultado del Batch Job

interface BatchResult {
  started_at: string;
  completed_at: string;
  duration_ms: number;
  priority_assets: {
    updated: string[];
    failed: Array<{ symbol: string; error: string }>;
  };
  queued_assets: {
    processed: number;
    remaining: number;
  };
  api_calls_used: number;
  rate_limit_waits: number;
}

Ejemplo:

{
  "started_at": "2026-01-04T18:00:00.000Z",
  "completed_at": "2026-01-04T18:00:48.250Z",
  "duration_ms": 48250,
  "priority_assets": {
    "updated": ["XAUUSD", "EURUSD", "BTCUSD"],
    "failed": []
  },
  "queued_assets": {
    "processed": 2,
    "remaining": 15
  },
  "api_calls_used": 5,
  "rate_limit_waits": 0
}

---

Reglas de Negocio

1. Activos Prioritarios Obligatorios: XAU, EURUSD y BTCUSD SIEMPRE se actualizan primero
2. Rate Limit Estricto: Nunca exceder 5 llamadas por minuto
3. Reintentos: Maximo 3 reintentos por activo fallido
4. Timeout: 30 segundos maximo por llamada API
5. Datos Stale: Marcar activo como stale si no se actualiza en 15 minutos
6. Cache: Las llamadas exitosas actualizan cache Redis (TTL: 5 min)

---

Criterios de Aceptacion

Escenario: Actualizacion exitosa de activos prioritarios
  DADO que el servicio Data Service esta corriendo
  Y la API de Polygon.io esta disponible
  CUANDO el batch job se ejecuta
  ENTONCES los activos XAU, EURUSD y BTCUSD se actualizan
  Y la tabla trading.symbols tiene datos recientes
  Y se publica un evento por cada activo actualizado

Escenario: Respeto del rate limit
  DADO que el rate limit es de 5 llamadas/minuto
  CUANDO el batch intenta hacer mas de 5 llamadas
  ENTONCES espera hasta que el minuto reinicie
  Y registra la espera en los logs

Escenario: Activos secundarios en cola
  DADO que hay 10 activos secundarios pendientes
  Y quedan 2 llamadas API disponibles en el minuto
  CUANDO el batch procesa la cola
  ENTONCES solo se procesan 2 activos
  Y los 8 restantes permanecen en cola para el siguiente ciclo

Escenario: Fallo de API
  DADO que la API de Polygon.io retorna error 500
  CUANDO el batch intenta actualizar un activo
  ENTONCES registra el error en data_sources.data_sync_status
  Y reintenta hasta 3 veces con backoff exponencial
  Y notifica si todos los reintentos fallan

Escenario: Ejecucion manual del batch
  DADO que el usuario tiene permisos de admin
  CUANDO hace POST /api/data/batch/run
  ENTONCES se ejecuta el batch inmediatamente
  Y retorna el resultado del batch job

---

Dependencias

Tecnicas:

• PolygonClient (existente): apps/data-service/src/providers/polygon_client.py
• APScheduler 3.x: Programacion de jobs
• asyncpg: Conexion a PostgreSQL
• aioredis: Publicacion de eventos
• aiohttp: Cliente HTTP async

Funcionales:

• INT-DATA-001: Integracion base de Data Service
• OQI-006 ML Signals: Consume datos actualizados

---

Notas Tecnicas

API Key

POLYGON_API_KEY=f09bA2V7OG7bHn4HxIT6Xs45ujg_pRXk

Nota: Esta key es para cuenta gratuita. Para produccion, considerar upgrade a plan Starter ($47/mes) para rate limit ilimitado.

Endpoints de Polygon.io Utilizados

Endpoint	Uso
/v2/snapshot/locale/global/markets/forex/tickers/{ticker}	Snapshot Forex/Commodities
/v2/snapshot/locale/global/markets/crypto/tickers/{ticker}	Snapshot Crypto
/v3/snapshot?ticker.any_of={tickers}	Universal snapshot (multiple)

Consideraciones de Performance

• Usar conexiones HTTP persistentes (connection pooling)
• Implementar circuit breaker para fallos de API
• Mantener metricas de latencia para monitoreo
• Considerar batch de snapshots cuando se tenga plan de pago

---

Historias de Usuario Relacionadas

ID	Titulo	SP
US-DATA-001	Como sistema, quiero actualizar precios de XAU cada 5 min	3
US-DATA-002	Como sistema, quiero actualizar precios de EURUSD cada 5 min	3
US-DATA-003	Como sistema, quiero actualizar precios de BTC cada 5 min	3
US-DATA-004	Como sistema, quiero encolar activos secundarios	5
US-DATA-005	Como admin, quiero ejecutar batch manualmente	2
US-DATA-006	Como sistema, quiero publicar eventos de actualizacion	3

Total Story Points: 19

---

Referencias

• Polygon.io Documentation
• INT-DATA-001: Data Service Base
• INT-DATA-003: Batch Actualizacion Activos

---

Creado por: Orquestador Agent Fecha: 2026-01-04 Ultima actualizacion: 2026-01-04