SignalDashPro - Project Guide (Unificado)#

Documento unico de referencia para estado, operacion y roadmap del proyecto.

1) Objetivo y alcance#

SignalDashPro opera en enfoque Binance-first:

Backend FastAPI ejecuta validacion de riesgo, cola, ejecucion y trazabilidad.
Frontend Next.js funciona como consola operativa.

Definicion de "sistema decente" (objetivo operativo):

no operar por noticia aislada ni por LLM aislado.
combinar contexto macro + confirmacion tecnica intradia + riesgo hard.
usar OpenAI como interprete estructurado (score/escenarios JSON), no como fuente de noticias.
mantener decision automatica con rollback inmediato (assist <-> guarded-live) por gate cuantitativo.

1.1) Criterio documental keep/migrate/archive#

Para mantener coherencia vNext, la documentación se clasifica así:

KEEP: documento canónico activo para operación o implementación vigente.
MIGRATE: contenido útil pero ubicado en ruta incorrecta o con naming legacy; se mueve a ruta canónica.
ARCHIVE: contenido histórico de trazabilidad; no debe gobernar decisiones actuales.

Tabla mínima de referencia:

KEEP: estado operativo vigente y contrato técnico actual (docs/, docs/matvard/).
MIGRATE: contenido útil en ruta legacy (reubicar y actualizar links).
ARCHIVE: snapshots/metodologías cerradas (docs/archive/, docs/matvard/archive/).

Canon MATVARD vNext:

docs/matvard/IMPLEMENTATION_PLAN_VNEXT_SAM.md
docs/matvard/MATVARD_RUNTIME_CONTRACT.md
docs/matvard/PLAYBOOK_SOLUSDC_REAL.md

2) Estado actual (resumen)#

Backend, frontend y DB corren en local y en Docker.
Flujo de ejecucion Binance con cola idempotente y retries.
Kill-switch y limites de sesion/simbolo/notional.
Job market_sync para refresco automatico de velas Binance, volatility_stats y market_windows.
E2E por entorno (spot/futures) con evidencia automatica.
Demo en futures testnet validado para XAUUSDT y PAXGUSDT.
Gate autonomo production en verde con walk-forward (H1, EURUSDT+PAXGUSDT).
Ingesta de noticias resiliente: fallback RSS cuando proveedor API falla (ej. FMP 403).
TradingEconomics News integrado (mejor proveedor para MVP), con filtros por type/tickers.
Autopilot (robot intradia) disponible para Spot Demo:
Encola señales (baseline ma_crossover) y deja trazabilidad en autopilot_decisions.
Timeframe recomendado para operar "decente" (MVP): M15 (evita ruido de M5, mantiene mas actividad que H1).
Filtros de confluencia (pre-senal): spread (AUTOPILOT_MAX_SPREAD_PCT) y volumen relativo (AUTOPILOT_MIN_VOL_REL).
Sizing: notional (AUTOPILOT_ORDER_NOTIONAL_PCT) o por riesgo con stop ATR (AUTOPILOT_RISK_PCT + AUTOPILOT_ATR_*).
Trade lifecycle minimo (spot) para autonomia:
- Tabla live_trades + TradeManager (virtual SL/TP) con salidas via signal_queue.
- Observa posiciones: GET /ops/live-trades.
- TP opcional: AUTOPILOT_TAKE_PROFIT_MULT (si >0).
News impact scoring (price-based) disponible para auditar impacto real por velas:
escribe market_news.impact_score (abs return; 0.01 == 1%)
puede correr en job (NEWS_IMPACT_AUTO_RUN=true) o manual (scripts/score_news_price_impact.py)
Guard de ejecucion por “news regime” en cola:
bloquea o reduce size segun high-impact en ultimas 3h (config NEWS_REGIME_*).
Scoring IA ahora incorpora contexto macro minimo desde macro_events:
features recientes/proximas por moneda relevante.
regla de cautela (macro_event_caution) para reducir tamano ante eventos high-impact cercanos.
Validacion de estabilidad del ciclo diario disponible en:
scripts/validate_daily_cycle.py (salida storage/logs/ops/daily-cycle-validate-*.{md,json}).

Estado vivo detallado: ver TODO.md.

2.1) Estado de despliegue externo (Proxmox)#

Para disponibilidad 24/7, el proyecto se esta operando en un VPS/Proxmox:

Frontend: https://sdp.perlatec.net
API: https://api.sdp.perlatec.net

Topologia y operacion (con comandos de deploy/troubleshooting): HANDOFF.md y operational/proxmox.md.

3) Modos de entorno#

env/.env.binance: spot.
env/.env.binance.futures: futures testnet base.
env/.env.binance.demo.month: demo mensual activo (actualmente futures testnet).
env/.env.binance.futures.demo.month: demo mensual futures.

4) Operacion diaria recomendada#

Validar salud:

./.venv/bin/python scripts/db_health_check.py

Validar E2E:

./.venv/bin/python scripts/run_binance_e2e.py --base-url http://127.0.0.1:8096 --with-private auto

Ingestar noticias de hoy (sin depender de proveedor premium):

./.venv/bin/python scripts/import_market_news.py --symbols EURUSDT PAXGUSDT --hours 24 --no-summarize

(Opcional) Calcular impacto por precio de noticias ya persistidas:

./.venv/bin/python scripts/score_news_price_impact.py --days 30 --limit 2000

Validar gate de autonomia (production + walk-forward):

./.venv/bin/python scripts/run_research_gate.py \
  --symbols EURUSDT PAXGUSDT \
  --timeframes H1 \
  --profile production \
  --lookback-hours 2160 \
  --backtest-hours 2160 \
  --training-source backtest \
  --wf-enabled \
  --wf-timeframes H1 \
  --wf-window-hours 168 \
  --wf-step-hours 24 \
  --wf-max-windows 4

Capturar evidencia:

./.venv/bin/python scripts/capture_operational_evidence.py

Revisar UI:
/binance: cuenta, estado, ordenes.
/control-tower: estado consolidado robot+backend+analisis+noticias.
/signals: cola y eventos.
/market: comparacion grafica y guard de alineacion.
/jobs: verificar market_sync y demas jobs automaticos.

4.0) Preparar datos históricos en BD#

Requisito: Todos los backtests reproducibles necesitan datos históricos consistentes en la BD PostgreSQL. No se debe depender de Binance API en tiempo real durante backtests.

Estado actual (2026-03-18):

✅ PAXGUSDT M15: 35,040 velas (1 año: 2025-03-18 → 2026-03-18) en pgad.perlatec.net
✅ Script disponible: scripts/backfill_paxg_m15_history.py

Sincronización diaria (obligatorio):

Ejecutar cada medianoche UTC para mantener actualizado el histórico:

cd /path/to/SignalDashPro
set -a && source env/.env.binance && set +a
.venv/bin/python scripts/backfill_paxg_m15_history.py \
  --symbol PAXGUSDT \
  --interval 15m \
  --days 30

Automatización (cron en CT110):

# /etc/cron.d/signaldashpro
0 0 * * * cd /opt/signaldashpro/current && \
          set -a && source env/.env.binance && set +a && \
          .venv/bin/python scripts/backfill_paxg_m15_history.py \
          --symbol PAXGUSDT --interval 15m --days 30 \
          >> /var/log/signaldashpro/backfill.log 2>&1

Script: El backfill es idempotente (upsert por constraint único (symbol, timeframe, timestamp)), así que re-ejecutar no produce duplicados.

4.1) Backtests reproducibles (baseline)#

Para validar que el sistema tiene "senal suficiente" y que los filtros (p.ej. news_regime_filter) no destruyen el trade count:

Walk-forward rapido (4 ventanas, 7 dias c/u) sobre M15 y H1:

./.venv/bin/python scripts/run_walkforward_backtest.py \
  --symbols EURUSDT PAXGUSDT \
  --timeframes M15 H1 \
  --window-hours 168 \
  --step-hours 24 \
  --max-windows 4 \
  --mode ma_crossover \
  --fast-ma 14 \
  --slow-ma 21 \
  --position-size 1000 \
  --strategy-prefix WFBASE

Comparativo con filtro de news-regime:

./.venv/bin/python scripts/run_walkforward_backtest.py \
  --symbols EURUSDT PAXGUSDT \
  --timeframes M15 H1 \
  --window-hours 168 \
  --step-hours 24 \
  --max-windows 4 \
  --mode ma_crossover \
  --fast-ma 14 \
  --slow-ma 21 \
  --position-size 1000 \
  --strategy-prefix WFNEWS \
  --news-regime-filter

Salida/evidencia:

storage/logs/backtests/walkforward-*.md (incluye JSON completo del run).

4.2) M15 Optimizer (promocion/rollback/auditoria)#

Endpoints operativos (Ops):

GET /ops/strategy/m15-optimizer
baseline + A/B shadow + candidatos de promotion.
POST /ops/strategy/m15-optimizer/promote-best
aplica mejor variante elegible y guarda snapshot de baseline.
POST /ops/strategy/m15-optimizer/rollback-last
restaura CFG_MODE::* y CFG_MANUAL::* desde el ultimo snapshot.
GET /ops/strategy/m15-promotions
salud post-promotion (improved|neutral|regressed|insufficient_sample).
incluye timeline unificado (promotion/rollback) para trazabilidad de ciclo.
POST /ops/strategy/m15-promotions/audit
auditoria consolidada (con auto_case opcional).
GET /ops/strategy/m15-automation-status
estado de frescura de jobs m15-autopromote y shadow-maintenance.

Jobs CT110:

signaldashpro-m15-autopromote.timer (cada 30 minutos).
signaldashpro-shadow-maintenance.timer (diario, retencion/log cleanup).

Alerting recomendado (CT110):

OPS_M15_AUTOPROMOTE_STALE_MINUTES=60
OPS_SHADOW_MAINT_STALE_MINUTES=1440
ALERT_M15_AUTOMATION_ENABLED=true
ALERT_M15_AUTOMATION_MIN_REPEAT=2

5) Riesgo y controles#

Controles principales:

Kill-switch: GET/POST /risk/kill-switch*
Guard de alineacion de mercado: GET/POST /risk/alignment-guard*
Pre-trade-check Binance: /binance/pre-trade-check
Endurecimiento por rol: con AUTH_ENABLED=true, todas las mutaciones operativas (risk/signals/binance orders/pipeline/AI runtime/backtests/brainstorm/diary create) requieren admin.
adicionalmente, GET /ai/runtime/mode tambien queda restringido a admin (no solo POST).

Cuando el guard de alineacion esta activo, se bloquean:

ordenes directas /binance/orders
procesamiento de cola signals/queue/process

Nota operativa (MVP):

market_sync ejecuta un alignment-check automatico (por defecto H1) y puede activar/desactivar el guard.
Para reducir falsos bloqueos por diferencias pequenas entre velas locales vs Binance:
MARKET_SYNC_ALIGNMENT_THRESHOLD_PCT (recomendado 0.5)
MARKET_SYNC_ALIGNMENT_AUTO_ENFORCE_GUARD=true|false (si false, el guard queda solo manual via /risk/alignment-guard).

6) Plan demo 30 dias#

Objetivo operativo:

30 dias de ejecucion demo con evidencia diaria.
KPIs semanales de estabilidad y riesgo.

Detalle operativo: docs/guides/binance_demo_30d.md.

Nota importante:

La corrida de 30 dias se inicia despues de pasar el gate de readiness (ver TODO.md -> "Gate: listo para 30 dias").
Primero se valida trading end-to-end, ingesta historica, backtests baseline, alertas y hardening minimo.
Referencia reciente en verde: storage/logs/research_gate/research-gate-20260211T192618Z.md.

7) Roadmap simplificado#

La prioridad ahora es un MVP autonomo intradia en Binance spot demo con ordenes reales.

Contrato del robot (definicion ejecutable, sin codigo):
universo (simbolos/timeframes),
riesgo (1%/trade, max trades, kill-switch),
bloqueos (alignment/news-regime/datos tardios),
tipo de orden (market/limit) + slippage guard.
Auditoria/logging primero:
guardar raw inputs, features, decision (permitido/bloqueado + razon) y resultado (PnL 30/60/180).
Señales generadas (no manual):
estrategia baseline simple y robusta,
gate por noticias como filtro (no trigger directo),
confirmacion tecnica + liquidez/volumen relativo.
Ejecucion spot demo (orden real) + safety:
sizing por riesgo, limites por sesion, slippage guard, kill-switch y auto-pausa por degradacion.
Dashboard “Robot Live”:
que esta haciendo el sistema en tiempo real (jobs, decisiones, trades, razones, news impact).
Validacion:
backtests reproducibles + walk-forward + costos/slippage,
stress tests minimos antes de iniciar 30 dias.
Operacion 30 dias:
evidencia diaria + reportes semanales + Go/No-Go.

7.1) Roadmap por fases (alineado)#

Este roadmap operativo se gestiona en TODO.md (checklist maestro) y se detalla en docs/guides/operational/ai_intelligence_plan.md.

Fases vigentes:

F0 base operativa/observabilidad.
F1 capa macro/intermarket confiable.
F2 regimen + confluencia + no_trade explicito.
F3 flujo no-indicador (agresor/imbalance/absorcion).
F4 motor probabilistico + gestion adaptativa.
F5 degradacion/autopausa + stress tests.
F6 validacion final + corrida 30 dias.

Regla de gobierno:

no iniciar una fase nueva sin criterios de salida minimos de la fase anterior.
toda fase debe dejar evidencia en logs/reportes y estado visible en /ops o /control-tower.

7.0) Contrato del robot (MVP, ejecutable sin codigo)#

Objetivo: que cualquiera (incluyendo otra sesion de ChatGPT) pueda leer esto y entender que hace el robot, cuando opera y por que.

Universo:

Mercado: Binance Spot Demo.
Simbolos MVP: EURUSDT, PAXGUSDT.
Direccion: solo long (Spot; no shorts). Nota: el sistema SI puede hacer SELL como salida de una posicion long (TradeManager).

Timeframes:

Contexto / ventanas / research gate: H1 (baseline).
Autopilot (intradia):
default KPI/estabilidad: M15.
perfil agresivo (solo observacion/debug del ciclo): M1.

Ventana horaria (UTC):

Default: 24/7 (sin “weekend mode”).
Filtro opcional (momentos efectivos): AUTOPILOT_ALLOW_HOURS_UTC (allowlist de horas 0-23 o rangos).
Si se configura y el modo (CFG_MODE::AUTOPILOT_ALLOW_HOURS_UTC) es manual o auto, el Autopilot hace skip fuera de horas con reason=hour_edge_blocked.
Evidencia/inspeccion: GET /autopilot/edge/hours y tarjeta “Edge horario” en Analisis -> Robot Live (/control-tower).

Datos (fuentes):

Mercado: velas Binance (via market_sync) + proxy de liquidez (volume/num_trades -> tick_volume).
Noticias: TradingEconomics + fallback RSS (persistidas en market_news).
Macro (MVP-minimo): macro_events (si existe) como cautela (no como trigger).
LLM/OpenAI: no es fuente; solo interprete/normalizador (fase siguiente).

Señal (entrada):

Estrategia base (MVP): range_breakout.
Regla: el robot NO abre una orden por noticia sola. La noticia es filtro/contexto.

Ejecucion:

El robot encola intenciones en signal_queue (idempotente).
El worker de ejecucion decide si envia orden a Binance segun risk/guards y estado runtime.

Salida (trade lifecycle):

Se persisten trades en live_trades.
TradeManager aplica salidas automaticas (virtual SL/TP) y encola el SELL de cierre via signal_queue.

Riesgo (MVP):

Riesgo por trade objetivo: 1% (AUTOPILOT_RISK_PCT=0.01) cuando se valide estabilidad.
Cap de notional por orden: AUTOPILOT_ORDER_NOTIONAL_PCT + limites Binance de sesion.
Limites de sesion (enforcement):
BINANCE_MAX_ORDERS_PER_SESSION
BINANCE_MAX_TOTAL_NOTIONAL_PER_SESSION
BINANCE_MAX_SYMBOL_NOTIONAL_PER_SESSION
Guardrails previstos (contrato; parte aun puede estar "pendiente" de enforcement):
max 3 trades/dia/simbolo
kill-switch diario por DD -2.5%
slippage/spread guard pre-orden (hard)

Bloqueos (NO TRADE):

Kill-switch activo.
Alignment-guard activo.
Fuera de ventana permitida (para demo 24/7: BINANCE_TRADE_DAYS=1..7 y 0/0).
Spread demasiado alto / rVol demasiado bajo (guards Autopilot).
News-regime hot: bloquear o reducir size (config NEWS_REGIME_*).
Datos tardios / falta de velas recientes (market_sync atrasado).

Auditabilidad (no negociable):

Cada decision debe dejar razon y contexto:
autopilot_decisions.details_json (features/thresholds/summary).
eventos en signal_queue_events (blocked/allowed + motivo).
executions (orden/fills/retries) y trading_diary (bitacora automatica).
Todo cambio "manual vs auto" se hace en Cuenta -> Configuracion (/settings) y queda en auditoria (/settings/audit?prefix=CFG_).

Modo manual vs automatico:

El admin puede:
aplicar perfiles Conservador/Agresivo (presets) o Custom.
ejecutar Run now del Autopilot para diagnostico.
aceptar recomendaciones CFG_AUTO::* (Autotune) manualmente.

7.1) Bloques funcionales para llegar a "decente"#

Capa de fuentes (verdad de datos):
calendario macro real (consenso/actual/anterior/timestamp).
titulares financieros y comunicados oficiales (si aplica por proveedor).
series proxy USD/riesgo (DXY, yields 2Y/10Y, opcional VIX proxy).
mercado Binance (spot): velas con un proxy de liquidez estable (ver nota abajo).

Nota (importante): candles.tick_volume

En este proyecto tick_volume se usa como proxy de liquidez/actividad para filtros intradia (p.ej. low_relative_volume).
En Binance, el campo volume viene como string float y si se castea a int puede quedar en 0 (sobre todo en demo o baja liquidez).
El ingestor prioriza num_trades cuando esta disponible; si no, usa volumen quote/base escalado para no perder decimales.
Si existen velas legacy con tick_volume=0, el sync de mercado puede backfillear tick_volume sin borrar historico.
Capa de inteligencia (interpretacion):
normalizar evento macro en schema JSON estricto.
calcular impact_score, sesgo USD, sesgo oro y escenarios con probabilidad.
almacenar salida y version de modelo para auditoria.
Capa de decision (ejecucion):
regla hibrida: news_score/contexto + confirmacion tecnica (VWAP/rango/ruptura/volumen relativo).
filtros de microestructura (spread/slippage/latencia).
riesgo por operacion (1%), limites por sesion, kill-switch diario.

Nota MVP (pragmatica):

Proxies externos (DXY/yields) y calendario con consenso son fase 2 si bloquean el avance.
Para MVP intradia decente: Binance candles + volumen + news (TE/RSS) + scoring estructurado + riesgo hard + auditoria + dashboard.
Capa de validacion:
backtest reproducible por simbolo/timeframe.
evaluacion por ventanas 30/60/180 min post-evento.
gate bootstrap/production antes de habilitar autonomia plena.

8) Plan de inteligencia (IA)#

La ejecucion por fases para incorporar IA (shadow -> assist -> guarded-live) esta en:

docs/guides/operational/ai_intelligence_plan.md

9) Convencion documental#

Para reducir dispersion:

README.md: entrada rapida.
PROJECT_GUIDE.md: guia principal del proyecto.
TODO.md: estado vivo / backlog.
docs/HANDBOOK.md: manual tecnico-operativo consolidado.

Los documentos historicos se mantienen solo como alias o referencia.