# Extensiones 16–30 — Especificación Operativa

> Complemento a `ARCHITECTURE.md`. Indica supuestos y estado de implementación.

## Supuestos globales

| Supuesto | Decisión |
|----------|----------|
| Timezone canónico | UTC; reset pérdida diaria 00:00 UTC |
| Particionado | PostgreSQL nativo por mes; TimescaleDB opcional en prod |
| Velas para estrategias | Solo velas **cerradas** (close_time < now) |
| Testnet vs prod | Liquidez testnet no extrapolable; fase canary obligatoria |
| Jurisdicción fiscal | Colombia (DIAN); export CSV para declaración |
| Secretos prod | Vault cloud; `.env` solo dev/local |

## 16. Gestión de datos históricos y calidad

**Implementado:** `MarketDataService`
- Backfill inicial y automático por gaps
- Validación: duplicados, faltantes, orden temporal, precios ≤ 0
- Flag `is_suspicious` + `quality_flags` JSON (no eliminar)
- Política retención configurable por intervalo
- Filtro `get_closed_candles()` excluye vela en formación

**Pendiente:** TimescaleDB hypertables; job de purga automática en prod

## 17. Reglas operativas Binance

**Implementado:** `ExchangeFiltersService` + extensión `BinanceService`
- `exchangeInfo` → LOT_SIZE, MIN_NOTIONAL, PRICE_FILTER
- Redondeo stepSize/tickSize; rechazo local si MIN_NOTIONAL
- `clientOrderId` determinístico: `tb_{signal_id}_{side}`
- Fills parciales → ajuste SL/TP a qty ejecutada
- Tipos orden por estrategia (MARKET/LIMIT/STOP_LOSS_LIMIT)
- Rate limit weight + backoff 429/418
- recvWindow + serverTime sync
- Dust ignorado en lógica de posición

**Pendiente:** User data stream listenKey keepalive 30 min (prod)

## 18. Máquina de estados y reconciliación

**Implementado:** `OrderStateMachine` + `ReconciliationService`
- Estados: CREATED → SUBMITTED → PARTIALLY_FILLED → FILLED | CANCELED | REJECTED | EXPIRED
- Tabla `order_events` con cada transición
- Reconciliación al startup: órdenes/posiciones Binance vs DB
- Posición sin SL → alerta + SL de emergencia

## 19. Detección de régimen de mercado

**Implementado:** `RegimeClassifier`
- Regímenes: TREND_UP, TREND_DOWN, RANGE, EXTREME_VOL, NO_DATA
- ADX + pendiente EMA + BB width + ATR normalizado
- Estrategias activadas/desactivadas por régimen
- `market_regime` en `decision_logs`

## 20. Backtesting avanzado

**Implementado:** `AdvancedBacktestingService`
- Split in-sample / out-of-sample
- Walk-forward analysis
- Anti look-ahead (solo velas cerradas hasta t)
- Grid search acotado
- Mínimo 100 trades para validar
- Slippage variable + latencia simulada
- Sensibilidad de parámetros
- Monte Carlo sobre orden de trades

## 21. Criterios go/no-go producción

**Implementado:** `GoNoGoEvaluator`
- 50+ trades paper, Sharpe ≥ 1.0, DD ≤ 10%, PF ≥ 1.3
- Slippage simulado vs real dentro de umbral
- Cero incidentes críticos
- Aprobación admin + audit log (2FA pendiente en dashboard)

## 22. Transición testnet → producción

**Documentado:** `docs/TRANSITION_PLAN.md`
- Fase canary 50–100 USDT, 2–4 semanas
- Comparación slippage real vs modelo
- Escalado gradual; rollback a paper con un comando

## 23. Exposición agregada y correlación

**Implementado:** `ExposureService`
- Correlación entre símbolos activos
- Max 3% capital en riesgo agregado
- Bloqueo si correlación > 0.8 misma dirección
- Max 3 posiciones simultáneas (configurable)

## 24. Concurrencia e idempotencia

**Implementado:** Redis locks por símbolo + dedup hash señal
- `signal_hash = sha256(symbol|strategy|candle_close_time)`
- Dead-letter en Redis list `dlq:orders`

## 25. Kill switch, circuit breakers, watchdog

**Implementado:** `CircuitBreakerService` + `scripts/watchdog.py`
- Triggers: pérdida diaria, N pérdidas, WS down, reconciliación, flash crash
- Watchdog verifica heartbeat Redis cada 60s
- Kill switch: dashboard + API + Telegram

## 26. Observabilidad

**Implementado:** `app/core/metrics.py`
- Prometheus: order_latency, ws_lag, api_weight, signals_vs_executed, drawdown
- correlation_id en logs por señal/orden

**Pendiente:** Grafana dashboards, Sentry DSN

## 27. Versionado estrategias

**Implementado:** `StrategyVersion` + `ConfigHistory`
- Semver por estrategia; trade registra versión+params
- Feature flags en `bot_configs.strategy_flags`

## 28. Seguridad ampliada

**Documentado:** IP whitelist, rotación keys 90d, verificación permisos retiro
**Pendiente:** 2FA TOTP, Dependabot en CI, escaneo imágenes

## 29. Operación y costos

**Documentado:** `docs/RUNBOOK.md`, `docs/DISASTER_RECOVERY.md`
- Backups RDS diarios, RTO 4h / RPO 1h
- Región recomendada: ap-northeast-1 para baja latencia

## 30. Contexto legal y fiscal

- Disclaimer en UI y API root
- Export CSV trades para DIAN (`/api/v1/reports/tax-export`)
- Uso personal; no asesoramiento financiero

## Roadmap por fases

| Fase | Semanas | Entregable | Estado |
|------|---------|------------|--------|
| 1 Fundación | 1–2 | Binance, velas, indicadores | ✅ Base |
| 2 Motor y riesgo | 3–4 | Estrategias, riesgo, paper, FSM órdenes | ✅ + ext. |
| 3 Backtesting | 5–6 | Walk-forward, Monte Carlo | ✅ |
| 4 Operación | 7–8 | Dashboard, circuit breakers, reconciliación | ✅ Parcial |
| 5 Endurecimiento | 9–10 | Caos, 2FA, runbook completo | 🔄 Pendiente |