trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/especificaciones

id	title	type	project	version	updated_date
README	Especificaciones Técnicas - OQI-003 Trading y Charts	Documentation	trading-platform	1.0.0	2026-01-04

Especificaciones Técnicas - OQI-003 Trading y Charts

Este directorio contiene las especificaciones técnicas detalladas para el módulo de Trading y Charts de Trading Platform.

Índice de Especificaciones

1. Integración de Datos de Mercado

ET-TRD-001: Market Data Integration

• Integración con Binance API (REST + WebSocket)
• Obtención de klines/candles, tickers, order book
• Caché con Redis
• Rate limiting y optimización de requests
• Tecnologías: Axios, Redis, PostgreSQL

2. Conexiones WebSocket

ET-TRD-002: WebSocket Connections

• WebSocket server para clientes (ws library)
• Conexión a Binance WebSocket
• Sistema de suscripciones por símbolo
• Reconexión automática y heartbeat
• Stream manager para multiplexación
• Tecnologías: ws, EventEmitter, JWT auth

3. Modelo de Datos

ET-TRD-003: Database Schema

• Schema trading completo en PostgreSQL 15+
• Tablas: watchlists, watchlist_symbols, paper_orders, paper_positions, paper_balances, paper_trades
• ENUMs personalizados para tipos de datos
• Funciones y triggers para lógica de negocio
• Vistas para consultas optimizadas
• Tecnologías: PostgreSQL 15+, SQL

4. API REST

ET-TRD-004: REST API Endpoints

• Endpoints de market data (klines, tickers, orderbook, symbols)
• Endpoints de watchlists (CRUD completo)
• Endpoints de paper trading (balances, orders, positions, trades)
• Endpoints de estadísticas
• Validación con Zod
• Tecnologías: Express.js, TypeScript, Zod

5. Componentes Frontend

ET-TRD-005: Frontend Components

• TradingPage con layout completo
• ChartComponent con Lightweight Charts v4
• OrderPanel, PositionsPanel, WatchlistPanel, OrderBookPanel
• Stores con Zustand (tradingStore, orderStore, chartStore)
• Hooks personalizados (useWebSocket, useMarketData)
• Tecnologías: React 18, Lightweight Charts v4, Zustand, TailwindCSS

6. Indicadores Técnicos

ET-TRD-006: Technical Indicators

• SMA (Simple Moving Average)
• EMA (Exponential Moving Average)
• RSI (Relative Strength Index)
• MACD (Moving Average Convergence Divergence)
• Bollinger Bands
• Fórmulas matemáticas y optimizaciones
• Integración con Lightweight Charts
• Tecnologías: TypeScript, Lightweight Charts

7. Motor de Paper Trading

ET-TRD-007: Paper Trading Engine

• OrderExecutionService (market, limit, stop orders)
• PositionService (gestión de posiciones long/short)
• BalanceService (gestión de balances multi-asset)
• Cálculo de PnL (realizado y no realizado)
• Simulación de slippage y comisiones
• Tecnologías: TypeScript, PostgreSQL

8. Optimizaciones de Performance

ET-TRD-008: Performance Optimizations

• Web Workers para cálculos pesados
• Virtualización de listas con react-window
• Caché con IndexedDB y LRU cache
• React.memo, useMemo, useCallback
• Lazy loading y code splitting
• Debouncing y throttling
• Tecnologías: Web Workers, react-window, IndexedDB

---

Stack Tecnológico Completo

Backend

• Runtime: Node.js 20+
• Framework: Express.js + TypeScript
• Database: PostgreSQL 15+ (schema: trading)
• Cache: Redis 7+
• WebSocket: ws library
• API Client: Axios
• Validation: Zod

Frontend

• Framework: React 18
• State Management: Zustand
• Charts: Lightweight Charts v4
• Styling: TailwindCSS
• HTTP Client: Axios
• Virtualization: react-window
• Storage: IndexedDB

External APIs

• Market Data: Binance API (REST + WebSocket)
  • REST: https://api.binance.com
  • WebSocket: wss://stream.binance.com:9443/ws

Infrastructure

• Container: Docker
• Reverse Proxy: Nginx (opcional)

---

Relación entre Especificaciones

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend Layer                           │
│                                                                 │
│  ET-TRD-005 (Components)                                       │
│  ├── ChartComponent ──uses──> ET-TRD-006 (Indicators)         │
│  ├── OrderPanel ──uses──> ET-TRD-004 (API)                    │
│  └── Optimizations ──uses──> ET-TRD-008 (Performance)         │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         │ HTTP/WSS
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Backend Layer                            │
│                                                                 │
│  ET-TRD-004 (API Endpoints)                                    │
│  ├── Routes ──uses──> ET-TRD-007 (Paper Engine)               │
│  ├── Market Data ──uses──> ET-TRD-001 (Binance API)           │
│  └── WebSocket ──uses──> ET-TRD-002 (WS Server)               │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Data Layer                               │
│                                                                 │
│  ET-TRD-003 (Database Schema)                                  │
│  ├── Watchlists Tables                                         │
│  ├── Paper Trading Tables                                      │
│  └── Market Data Tables                                        │
└─────────────────────────────────────────────────────────────────┘

---

Orden de Implementación Recomendado

1. ET-TRD-003 - Database Schema (base de datos primero)
2. ET-TRD-001 - Market Data Integration (datos externos)
3. ET-TRD-002 - WebSocket Connections (tiempo real)
4. ET-TRD-007 - Paper Trading Engine (lógica de negocio)
5. ET-TRD-004 - REST API Endpoints (interfaz backend)
6. ET-TRD-006 - Technical Indicators (cálculos)
7. ET-TRD-005 - Frontend Components (UI)
8. ET-TRD-008 - Performance Optimizations (refinamiento)

---

Archivos Relacionados

• Épica: OQI-003 README
• Mapa del Módulo: _MAP.md
• Requerimientos Funcionales: ../requerimientos/
• Historias de Usuario: ../historias-usuario/

---

Convenciones de Nomenclatura

Archivos

• ET-TRD-XXX-nombre.md - Especificación Técnica

Código Backend

• *.service.ts - Servicios de lógica de negocio
• *.controller.ts - Controladores de endpoints
• *.routes.ts - Definición de rutas
• *.types.ts - Interfaces y tipos TypeScript

Código Frontend

• *.tsx - Componentes React
• *.store.ts - Stores de Zustand
• use*.ts - Custom hooks

Base de Datos

• trading.* - Schema de trading
• *_enum - Tipos ENUM
• idx_* - Índices
• *_trigger - Triggers

---

Notas de Desarrollo

Variables de Entorno Requeridas

# Binance API
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/trading
DB_SCHEMA=trading

# Redis
REDIS_URL=redis://localhost:6379
REDIS_DB_MARKET_DATA=1

# JWT
JWT_SECRET=your_jwt_secret

# API
API_URL=http://localhost:3001
WS_URL=ws://localhost:3001

Comandos Útiles

# Crear schema de base de datos
psql -d trading -f migrations/001_create_trading_schema.sql

# Ejecutar tests
npm run test:backend
npm run test:frontend

# Desarrollo
npm run dev:backend
npm run dev:frontend

# Build producción
npm run build

---

Contacto y Soporte

Para preguntas sobre estas especificaciones técnicas:

• Revisar documentación en /docs
• Consultar ejemplos de código en /examples
• Crear issue en repositorio del proyecto

---

Última actualización: 2025-12-05 Versión de especificaciones: 1.0.0