docs/QUICK_START_REFACTORING.md

# 🚀 Quick Start - Refactorización SOLID

**Para**: Desarrollador que inicia la refactorización  
**Tiempo estimado**: 15 minutos de setup inicial  
**Objetivo**: Entender y comenzar la refactorización

---

## 📖 Contexto Rápido

### Estado Actual (v2.1.1)
- 1 archivo Python monolítico (680 líneas)
- 1 archivo JavaScript monolítico (1,105 líneas)
- 0% cobertura de tests
- 25% cumplimiento SOLID

### Estado Objetivo (v3.0.0)
- 20+ archivos Python modulares (<150 líneas c/u)
- 6+ archivos JavaScript modulares
- 70% cobertura de tests
- 85% cumplimiento SOLID

---

## 🎯 Principios Clave

### SOLID en 1 Minuto

```
S - Single Responsibility    → 1 clase = 1 trabajo
O - Open/Closed              → Extender sin modificar
L - Liskov Substitution      → Interfaces intercambiables
I - Interface Segregation    → Interfaces pequeñas
D - Dependency Inversion     → Depender de abstracciones
```

### Arquitectura en Capas

```
┌─────────────────┐
│  API Layer      │  ← Endpoints (FastAPI)
├─────────────────┤
│  Domain Layer   │  ← Lógica de negocio
├─────────────────┤
│  Infrastructure │  ← Implementaciones (Chronos, DB)
└─────────────────┘
```

---

## 🛠️ Setup Inicial

### 1. Preparar Entorno

```bash
# Navegar al proyecto
cd /var/home/joss/Proyectos/chronos2-server

# Crear branch de refactorización
git checkout -b refactor/solid-architecture

# Backup del código actual
cp app/main.py app/main_v2.1.1_backup.py
cp static/taskpane/taskpane.js static/taskpane/taskpane_v2.1.1_backup.js

# Instalar dependencias de desarrollo
pip install pytest pytest-cov black flake8 mypy
```

### 2. Crear Estructura de Carpetas

```bash
# Backend
mkdir -p app/{api/{routes,middleware},domain/{models,services,interfaces},infrastructure/{ml,config},schemas/{requests,responses},utils}

# Frontend
mkdir -p static/taskpane/js/{services,excel,ui,features,config}

# Tests
mkdir -p tests/{unit,integration,fixtures}

# Docs
mkdir -p docs
```

### 3. Verificar Estructura

```bash
tree -L 3 app/
```

**Output esperado**:
```
app/
├── api/
│   ├── routes/
│   └── middleware/
├── domain/
│   ├── models/
│   ├── services/
│   └── interfaces/
├── infrastructure/
│   ├── ml/
│   └── config/
├── schemas/
│   ├── requests/
│   └── responses/
└── utils/
```

---

## 📝 Primera Tarea: Settings Centralizados

### ¿Por qué empezar aquí?
- Fácil de implementar
- Sin dependencias
- Base para todo lo demás

### Código a Crear

**app/infrastructure/config/settings.py**:
```python
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # API
    api_title: str = "Chronos-2 Forecasting API"
    api_version: str = "3.0.0"
    
    # Model
    model_id: str = "amazon/chronos-2"
    device_map: str = "cpu"
    
    # CORS
    cors_origins: list = ["*"]
    
    class Config:
        env_file = ".env"

settings = Settings()
```

### Test Rápido

```python
# En Python REPL
from app.infrastructure.config.settings import settings
print(settings.api_title)  # "Chronos-2 Forecasting API"
print(settings.model_id)    # "amazon/chronos-2"
```

---

## 📝 Segunda Tarea: Logger Centralizado

**app/utils/logger.py**:
```python
import logging

def setup_logger(name: str) -> logging.Logger:
    logger = logging.getLogger(name)
    logger.setLevel(logging.INFO)
    
    if not logger.handlers:
        handler = logging.StreamHandler()
        formatter = logging.Formatter(
            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
        )
        handler.setFormatter(formatter)
        logger.addHandler(handler)
    
    return logger
```

### Uso

```python
from app.utils.logger import setup_logger

logger = setup_logger(__name__)
logger.info("Test message")
logger.error("Error message")
```

---

## 📝 Tercera Tarea: Primera Interface

**app/domain/interfaces/forecast_model.py**:
```python
from abc import ABC, abstractmethod
from typing import List, Dict, Any
import pandas as pd

class IForecastModel(ABC):
    """Interface para modelos de forecasting"""
    
    @abstractmethod
    def predict(
        self,
        context_df: pd.DataFrame,
        prediction_length: int,
        quantile_levels: List[float],
        **kwargs
    ) -> pd.DataFrame:
        pass
    
    @abstractmethod
    def get_model_info(self) -> Dict[str, Any]:
        pass
```

### ¿Por qué una interface?
- **Abstracción**: No depender de implementación específica
- **Testeable**: Fácil de mockear
- **Extensible**: Agregar modelos (Prophet, ARIMA) sin cambiar código

---

## 🧪 Primer Test

**tests/unit/test_settings.py**:
```python
import pytest
from app.infrastructure.config.settings import Settings

def test_settings_defaults():
    settings = Settings()
    assert settings.api_title == "Chronos-2 Forecasting API"
    assert settings.api_version == "3.0.0"
    assert settings.model_id == "amazon/chronos-2"

def test_settings_from_env(monkeypatch):
    monkeypatch.setenv("MODEL_ID", "amazon/chronos-t5-small")
    settings = Settings()
    assert settings.model_id == "amazon/chronos-t5-small"
```

### Correr Test

```bash
pytest tests/unit/test_settings.py -v
```

**Output esperado**:
```
tests/unit/test_settings.py::test_settings_defaults PASSED
tests/unit/test_settings.py::test_settings_from_env PASSED
```

---

## 🎯 Checklist de Hoy (2-3 horas)

- [ ] Setup entorno (git branch, dependencias)
- [ ] Crear estructura de carpetas
- [ ] Implementar Settings
- [ ] Implementar Logger
- [ ] Crear primera Interface (IForecastModel)
- [ ] Escribir primeros tests
- [ ] Commit: "chore: setup SOLID architecture foundation"

---

## 📚 Recursos de Referencia

### Documentación del Proyecto
1. `ANALISIS_SOLID.md` - Problemas identificados
2. `PLAN_REFACTORIZACION.md` - Plan completo
3. `docs/QUICK_START_REFACTORING.md` - Este archivo

### Lectura Recomendada
- [Clean Architecture - Robert Martin](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
- [SOLID Principles - Python](https://realpython.com/solid-principles-python/)
- [FastAPI Best Practices](https://fastapi.tiangolo.com/tutorial/bigger-applications/)

---

## 🚨 Problemas Comunes

### "ModuleNotFoundError: No module named 'app.infrastructure'"

**Solución**: Agregar `__init__.py` en cada carpeta:
```bash
touch app/__init__.py
touch app/infrastructure/__init__.py
touch app/infrastructure/config/__init__.py
# etc...
```

### "Settings no carga .env"

**Solución**: Instalar `python-dotenv`:
```bash
pip install python-dotenv
```

### "Tests no encuentran módulos"

**Solución**: Agregar `__init__.py` en `tests/`:
```bash
touch tests/__init__.py
touch tests/unit/__init__.py
```

---

## 💡 Tips de Productividad

### 1. Usar VSCode Tasks

Crear `.vscode/tasks.json`:
```json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Run Tests",
            "type": "shell",
            "command": "pytest tests/ -v",
            "group": "test"
        },
        {
            "label": "Type Check",
            "type": "shell",
            "command": "mypy app/",
            "group": "test"
        }
    ]
}
```

### 2. Pre-commit Hooks

```bash
# Instalar pre-commit
pip install pre-commit

# Crear .pre-commit-config.yaml
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black
  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
EOF

# Instalar hooks
pre-commit install
```

### 3. Snippets para Interfaces

VSCode snippet para crear interfaces rápidamente:
```json
{
    "Python Interface": {
        "prefix": "interface",
        "body": [
            "from abc import ABC, abstractmethod",
            "",
            "class I${1:Name}(ABC):",
            "    \"\"\"${2:Description}\"\"\"",
            "    ",
            "    @abstractmethod",
            "    def ${3:method}(self, ${4:params}):",
            "        pass"
        ]
    }
}
```

---

## 📞 Siguiente Paso

Una vez completado el checklist de hoy:

1. **Leer**: `PLAN_REFACTORIZACION.md` - Fase 2
2. **Implementar**: Modelos de Dominio (TimeSeries, ForecastConfig)
3. **Commit**: Código con mensaje descriptivo
4. **Review**: Auto-review del código antes de continuar

---

## 🎉 ¡Felicitaciones!

Has completado el setup inicial. Ahora tienes:
- ✅ Estructura de carpetas organizada
- ✅ Configuración centralizada
- ✅ Logger consistente
- ✅ Primera interface (abstracción)
- ✅ Primeros tests

**Tiempo invertido**: 2-3 horas  
**Progreso**: ~5% de la refactorización  
**Próxima sesión**: Modelos de Dominio (4-5 horas)

---

**Actualizado**: 2025-11-09  
**Versión**: 1.0  
**Autor**: Claude AI