---
id: "README"
title: "Especificaciones Técnicas - OQI-003 Trading y Charts"
type: "Documentation"
project: "trading-platform"
version: "1.0.0"
updated_date: "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](./ET-TRD-001-market-data.md)**
- 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](./ET-TRD-002-websocket.md)**
- 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](./ET-TRD-003-database.md)**
- 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](./ET-TRD-004-api.md)**
- 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](./ET-TRD-005-frontend.md)**
- 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](./ET-TRD-006-indicadores.md)**
- 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](./ET-TRD-007-paper-engine.md)**
- 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](./ET-TRD-008-performance.md)**
- 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](../README.md)
- **Mapa del Módulo:** [_MAP.md](../_MAP.md)
- **Requerimientos Funcionales:** [../requerimientos/](../requerimientos/)
- **Historias de Usuario:** [../historias-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

```bash
# 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

```bash
# 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