# 🤖 Trading Bot - Semanas 1-2: Data Pipeline

Bot de trading algorítmico desarrollado desde cero. Esta es la primera fase enfocada en el pipeline de datos.

## 📋 Tabla de Contenidos

- [Requisitos](#requisitos)
- [Instalación](#instalación)
- [Configuración](#configuración)
- [Uso](#uso)
- [Estructura del Proyecto](#estructura-del-proyecto)
- [Testing](#testing)
- [Próximos Pasos](#próximos-pasos)

## 🔧 Requisitos

### Software
- Python 3.10 o superior
- PostgreSQL 13 o superior
- Redis 6 o superior (opcional, para caché)
- Git

### Hardware (mínimo para desarrollo)
- 8GB RAM
- 20GB espacio en disco

## 📦 Instalación

### 1. Clonar el repositorio

```bash
git clone <tu-repositorio>
cd trading-bot
```

### 2. Crear entorno virtual

```bash
python -m venv venv

# En Linux/Mac:
source venv/bin/activate

# En Windows:
venv\Scripts\activate
```

### 3. Instalar dependencias

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

### 4. Instalar PostgreSQL

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
```

**macOS (con Homebrew):**
```bash
brew install postgresql
brew services start postgresql
```

**Windows:**
Descargar instalador desde [postgresql.org](https://www.postgresql.org/download/windows/)

### 5. Configurar base de datos

```bash
# Conectar a PostgreSQL
sudo -u postgres psql

# Crear base de datos y usuario
CREATE DATABASE trading_bot;
CREATE USER trading_user WITH PASSWORD 'tu_password_seguro';
GRANT ALL PRIVILEGES ON DATABASE trading_bot TO trading_user;
\q
```

### 6. Instalar Redis (opcional)

**Ubuntu/Debian:**
```bash
sudo apt install redis-server
sudo systemctl start redis
```

**macOS:**
```bash
brew install redis
brew services start redis
```

**Windows:**
Descargar desde [redis.io](https://redis.io/download) o usar WSL

## ⚙️ Configuración

### 1. Copiar archivo de configuración

```bash
cp .env.example .env
```

### 2. Editar `.env` con tus credenciales

```bash
# Exchange (para datos públicos no se necesita API key)
EXCHANGE_NAME=binance
API_KEY=
API_SECRET=

# Base de datos
DB_HOST=localhost
DB_PORT=5432
DB_NAME=trading_bot
DB_USER=trading_user
DB_PASSWORD=tu_password_seguro

# Redis (opcional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# General
ENVIRONMENT=development
LOG_LEVEL=INFO
```

### 3. Verificar configuración de settings.yaml

El archivo `config/settings.yaml` contiene configuraciones generales que puedes ajustar:

```yaml
trading:
  symbols:
    - BTC/USDT
    - ETH/USDT
  timeframes:
    - 1h
    - 4h
```

## 🚀 Uso

### Ejecutar demo completo

```bash
python main.py
```

Este comando ejecutará el pipeline completo:
1. Conexión al exchange (Binance por defecto)
2. Descarga de datos históricos
3. Procesamiento y limpieza
4. Almacenamiento en PostgreSQL
5. Verificación de datos

### Uso programático

```python
from src.data.fetcher import DataFetcher
from src.data.processor import DataProcessor
from src.data.storage import StorageManager

# Inicializar fetcher
fetcher = DataFetcher('binance')

# Obtener datos
df = fetcher.fetch_historical('BTC/USDT', timeframe='1h', days=7)

# Procesar
processor = DataProcessor()
df_clean = processor.clean_data(df)

# Guardar
storage = StorageManager(...)
storage.save_ohlcv(df_clean)
```

## 📁 Estructura del Proyecto

```
trading-bot/
├── config/                 # Configuración
│   ├── settings.yaml      # Configuración general
│   └── .env              # Variables de entorno (no subir a git)
├── src/                   # Código fuente
│   ├── data/             # Módulo de datos
│   │   ├── fetcher.py   # Obtención de datos
│   │   ├── processor.py # Procesamiento
│   │   └── storage.py   # Almacenamiento
│   └── utils/            # Utilidades
│       └── logger.py    # Sistema de logging
├── tests/                # Tests unitarios
│   └── test_data.py     # Tests del módulo de datos
├── data/                 # Datos locales
│   └── historical/      # Datos históricos
├── logs/                 # Archivos de log
├── requirements.txt      # Dependencias Python
├── main.py              # Punto de entrada
└── README.md            # Este archivo
```

## 🧪 Testing

### Ejecutar todos los tests

```bash
pytest tests/ -v
```

### Ejecutar tests con cobertura

```bash
pytest tests/ --cov=src --cov-report=html
```

### Ejecutar test específico

```bash
pytest tests/test_data.py::TestDataProcessor::test_clean_data_removes_duplicates -v
```

## 📊 Funcionalidades Implementadas

### ✅ Completado (Semanas 1-2)

- [x] Sistema de logging robusto
- [x] Conexión a exchanges vía CCXT
- [x] Descarga de datos históricos
- [x] Descarga incremental (continuar desde último timestamp)
- [x] Procesamiento y limpieza de datos
- [x] Detección de gaps y outliers
- [x] Resampleo de timeframes
- [x] Cálculo de retornos
- [x] Almacenamiento en PostgreSQL
- [x] Caché con Redis
- [x] Tests unitarios
- [x] Manejo de errores y reintentos

## 🔜 Próximos Pasos (Semanas 3-4)

- [ ] Engine de backtesting
- [ ] Métricas de performance (Sharpe, Sortino, Max Drawdown)
- [ ] Visualizaciones de resultados
- [ ] Estrategia simple de trading
- [ ] Simulación histórica

## 🐛 Troubleshooting

### Error: "No se puede conectar a PostgreSQL"

**Solución:**
```bash
# Verificar que PostgreSQL está corriendo
sudo systemctl status postgresql

# Verificar credenciales en .env
# Verificar que el usuario tiene permisos
```

### Error: "ModuleNotFoundError: No module named 'ccxt'"

**Solución:**
```bash
# Asegurarse de que el entorno virtual está activado
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Reinstalar dependencias
pip install -r requirements.txt
```

### Error: Rate limit exceeded

**Solución:**
El código ya incluye manejo de rate limiting, pero si persiste:
- Aumentar delays en `config/settings.yaml`
- Reducir el número de símbolos/timeframes
- Usar API keys para límites más altos

## 📝 Notas Importantes

⚠️ **IMPORTANTE**: Este bot es para fines educativos. No ejecutes trading real sin:
1. Backtesting exhaustivo (mínimo 3-5 años)
2. Paper trading extensivo (varios meses)
3. Gestión de riesgo robusta
4. Comprensión completa del código

## 🤝 Contribuir

Este es un proyecto de aprendizaje personal. Si encuentras bugs o tienes sugerencias:
1. Documenta el issue claramente
2. Incluye logs y pasos para reproducir
3. Propón solución si es posible

## 📄 Licencia

MIT License - Usar bajo tu propio riesgo

## 📧 Contacto

Para dudas sobre el código o siguiente fase de desarrollo, consulta conmigo.

---

**Versión actual:** 0.1.0 (Semanas 1-2 completadas)  
**Última actualización:** Enero 2026