# ?? Encelado - TradingBot

**Sistema automatizzato di trading su criptovalute con interfaccia web moderna**

[![.NET](https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet)](https://dotnet.microsoft.com/)
[![Blazor](https://img.shields.io/badge/Blazor-Server-512BD4?logo=blazor)](https://blazor.net/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-Private-red)](LICENSE)

> ?? **Robot di trading automatizzato** con strategie personalizzabili, analisi tecnica in tempo reale e interfaccia web intuitiva.

---

## ?? Indice

- [Panoramica](#-panoramica)
- [Caratteristiche](#-caratteristiche-principali)
- [Come Funziona](#-come-funziona)
- [Quick Start](#-quick-start)
- [Installazione](#-installazione)
- [Deployment](#-deployment)
- [Configurazione](#-configurazione)
- [Utilizzo](#-utilizzo)
- [Architettura](#-architettura)
- [Manutenzione](#-manutenzione)
- [Troubleshooting](#-troubleshooting)
- [Documentazione](#-documentazione-completa)
- [Roadmap](#-roadmap)
- [Licenza](#-licenza)

---

## ?? Panoramica

**Encelado TradingBot** è un'applicazione **Blazor Server** che implementa un sistema di trading automatizzato su criptovalute. Il bot analizza il mercato in tempo reale, applica strategie di trading configurabili e gestisce automaticamente l'esecuzione delle operazioni.

### ?? Demo

```
http://localhost:8080       # Locale
http://[UNRAID-IP]:8080     # Produzione
```

### ? Highlights

- ?? **Trading Automatico** - 15 asset supportati con strategie personalizzabili
- ?? **Dashboard Real-time** - Aggiornamenti live ogni 3 secondi
- ?? **Analisi Tecnica** - RSI, MACD, EMA integrate
- ?? **UI Moderna** - Dark theme, responsive, glassmorphism
- ?? **Docker Ready** - Deploy semplificato con containerizzazione
- ?? **Persistenza Dati** - Settings e configurazioni salvate
- ?? **Sicuro** - Modalità simulazione per testing

---

## ?? Caratteristiche Principali

### ?? Dashboard Completo
- **Portfolio Overview**: Valore totale, profitto, asset attivi
- **Top Performers**: Asset più redditizi
- **Attività Recente**: Ultime 8 operazioni
- **Aggiornamenti Real-time**: Via SignalR

### ?? Gestione Strategie
- **6 Strategie Predefinite**: RSI+MACD, SMA, Scalping, Trend Following, Mean Reversion, Conservative
- **Parametri Configurabili**: Stop Loss, Take Profit, condizioni entry/exit
- **Backtesting Ready**: Template per test storici

### ?? Asset Management
- **15 Criptovalute**: BTC, ETH, BNB, SOL, ADA, XRP, DOT, AVAX, MATIC, LINK, UNI, ATOM, LTC, ALGO, VET
- **Grid/List View**: Visualizzazioni multiple
- **Assegnazione Strategie**: Per singolo asset
- **Toggle On/Off**: Controllo granulare

### ?? Analisi Tecnica
- **Indicatori**: RSI (14), MACD (12,26,9), EMA (12,26)
- **Grafici SVG**: Rendering performante client-side
- **Time Series**: Storico prezzi e variazioni

### ?? Analisi Mercato
- **Grafici Interattivi**: Visualizzazione prezzi
- **Selector Asset**: Cambio asset dinamico
- **States Colorati**: Overbought/Oversold/Neutral

### ?? Statistiche Dettagliate
- **Performance Portfolio**: Metriche aggregate
- **Breakdown per Asset**: ROI, win rate, trades
- **Best/Worst Performers**: Identificazione automatica
- **Drilldown**: Analisi approfondita singolo asset

### ?? Impostazioni
- **Persistenza Automatica**: Salvataggio su file JSON
- **Configurazioni**: Intervallo aggiornamento, log level, auto-start
- **Notifiche**: Feedback visivo

---

## ?? Come Funziona

### ?? Architettura del Sistema

```
???????????????????????????????????????????????????????????
?                    BLAZOR SERVER UI                      ?
?  (Dashboard, Strategie, Trading, Market, Stats)         ?
???????????????????????????????????????????????????????????
                     ? SignalR Real-time
                     ?
???????????????????????????????????????????????????????????
?              TRADING BOT SERVICE (Core)                  ?
?  - Gestione Asset                                        ?
?  - Esecuzione Strategie                                  ?
?  - Risk Management                                       ?
?  - Event System                                          ?
???????????????????????????????????????????????????????????
     ?                 ?                  ?
     ?                 ?                  ?
???????????   ????????????????   ????????????????????
? Market  ?   ?  Technical   ?   ?    Settings      ?
?  Data   ?   ?  Analysis    ?   ?    Service       ?
? Service ?   ?   Service    ?   ?                  ?
???????????   ????????????????   ????????????????????
     ?
     ?
???????????????????????????????????????????????????????????
?           SIMULATED / REAL MARKET DATA                   ?
?  (CoinGecko API / Simulazione)                          ?
???????????????????????????????????????????????????????????
```

### ?? Ciclo di Trading

1. **?? Acquisizione Dati**
   - Market Data Service recupera prezzi ogni 3 secondi
   - Aggiorna cache interna per tutti gli asset

2. **?? Analisi Tecnica**
   - Calcolo indicatori (RSI, MACD, EMA)
   - Valutazione trend e momentum
   - Identificazione pattern

3. **?? Valutazione Strategia**
   - Verifica condizioni BUY/SELL
   - Controllo risk management
   - Validazione budget disponibile

4. **? Esecuzione Trade**
   - Calcolo dimensione posizione
   - Esecuzione ordine (simulato/reale)
   - Aggiornamento portfolio

5. **?? Logging & Notifica**
   - Salvataggio operazione
   - Aggiornamento statistiche
   - Notifica UI via SignalR

### ?? Strategia di Default: RSI + MACD

```csharp
BUY quando:
  - RSI < 40 (asset ipervenduto)
  - MACD Histogram > 0 (momentum positivo)
  - Budget disponibile >= MinTradeAmount

SELL quando:
  - RSI > 60 (asset ipercomprato)
  - MACD Histogram < 0 (momentum negativo)
  - Holdings > 0
  OPPURE
  - Profitto >= Take Profit (10%)
  - Perdita >= Stop Loss (5%)
```

### ?? Gestione Rischio

```
? Max Daily Trades: 50 per asset
? Max Position Size: $5000 per asset  
? Min Trade Amount: $10
? Trade Size: 30% del balance disponibile (max)
? Min Interval: 10 secondi tra trades
? Stop Loss: 5% configurabile
? Take Profit: 10% configurabile
```

---

## ?? Quick Start

### Locale (Windows)

```powershell
# Clone repository
git clone https://192.168.30.23/Alby96/Encelado
cd Encelado\TradingBot

# Restore e Build
dotnet restore
dotnet build

# Run
dotnet run

# Accesso
# http://localhost:5001
```

### Docker (Cross-platform)

```bash
# Build
docker-compose build

# Run
docker-compose up -d

# Accesso
# http://localhost:8080
```

### Unraid (Production)

Vedi [Deployment su Unraid](#deployment-su-unraid)

---

## ?? Installazione

### Prerequisiti

**Per Sviluppo Locale**:
- ? [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
- ? Visual Studio 2022+ o VS Code
- ? Git

**Per Docker**:
- ? [Docker Desktop](https://www.docker.com/products/docker-desktop) (Windows/Mac)
- ? Docker Engine (Linux)
- ? Docker Compose

**Per Unraid**:
- ? Unraid 6.10+
- ? Docker installato
- ? Portainer (opzionale ma consigliato)

### Installazione Passo-Passo

#### 1. Clone Repository

```bash
git clone https://192.168.30.23/Alby96/Encelado
cd Encelado/TradingBot
```

#### 2. Restore Dipendenze

```bash
dotnet restore
```

#### 3. Configurazione (Opzionale)

Crea `appsettings.Development.json`:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "TradingBot": {
    "SimulationMode": true,
    "UpdateIntervalSeconds": 3
  }
}
```

#### 4. Build

```bash
dotnet build -c Release
```

#### 5. Run

```bash
dotnet run
```

#### 6. Verifica

Apri browser su: `https://localhost:5001` o `http://localhost:5000`

---

## ?? Deployment

### Deployment Locale

```bash
# Development
dotnet run

# Production build
dotnet publish -c Release -o ./publish
cd publish
dotnet TradingBot.dll
```

### Deployment Docker

#### Build Immagine

```bash
# Windows
.\build-docker.bat

# Linux/Mac
chmod +x build-docker.sh
./build-docker.sh
```

#### Run Container

```bash
docker-compose up -d
```

#### Verifica

```bash
# Status
docker ps | grep tradingbot

# Logs
docker logs tradingbot -f

# Health
curl http://localhost:8080/health
```

### Deployment su Unraid

#### Metodo 1: Portainer Stack (Consigliato)

1. **Portainer** ? Stacks ? Add stack
2. **Name**: `tradingbot`
3. **Git Repository**: `https://192.168.30.23/Alby96/Encelado`
4. **Compose path**: `TradingBot/docker-compose.yml`
5. **Deploy**

**Setup Webhook Auto-deploy**:
- Portainer ? Webhooks ? Create
- Gitea ? Settings ? Webhooks ? Add
- Ogni push ? Auto-deploy!

#### Metodo 2: SSH Manuale

```bash
# SSH su Unraid
ssh root@[UNRAID-IP]

# Clone
cd /mnt/user/appdata
git clone https://192.168.30.23/Alby96/Encelado.git tradingbot
cd tradingbot/TradingBot

# Deploy
docker-compose up -d
```

**Guida Completa**: [docs/deployment/UNRAID_DEPLOYMENT.md](TradingBot/docs/deployment/UNRAID_DEPLOYMENT.md)

---

## ?? Configurazione

### File Configurazione

**Locale**: `%LocalAppData%/TradingBot/appsettings.json`
**Docker**: Volume `tradingbot-data`

### Parametri Principali

```json
{
  "SimulationMode": true,           // true = simulazione, false = reale
  "AutoStartBot": true,             // Avvio automatico
  "UpdateIntervalSeconds": 3,       // Intervallo aggiornamento (2-10)
  "DesktopNotifications": false,    // Notifiche desktop
  "ConfirmManualTrades": false,     // Conferma trades manuali
  "LogLevel": "Info",               // Error, Warning, Info, Debug
  "SidebarCollapsed": false         // Stato sidebar UI
}
```

### Environment Variables (Docker)

```bash
# .env file
TZ=Europe/Rome
ASPNETCORE_ENVIRONMENT=Production
TRADINGBOT__SimulationMode=true
TRADINGBOT__AutoStartBot=true
TRADINGBOT__UpdateIntervalSeconds=3
```

### Configurazione Asset

Modifica in UI: **Asset** ? Seleziona asset ? **Configura**

O nel codice: `Services/TradingBotService.cs` ? `InitializeAssets()`

---

## ?? Utilizzo

### Navigazione UI

#### ?? Dashboard
- Overview portfolio e performance
- Top 6 asset attivi
- Ultimi 8 trades

#### ?? Strategie
- Visualizza strategie disponibili
- Strategia attiva: RSI + MACD Cross
- Template predefiniti

#### ?? Asset
- **Grid View**: Card dettagliate
- **List View**: Tabella compatta
- **Assegna Strategie**: Dropdown per asset
- **Toggle**: Attiva/disattiva trading

#### ?? Trading
- Grid tutti asset
- Toggle on/off
- Storico operazioni con filtri

#### ?? Analisi Mercato
- Grafici interattivi
- Indicatori tecnici live
- Selector asset

#### ?? Statistiche
- Metriche aggregate
- Performance per asset
- Best/Worst performers
- Drilldown dettagliato

#### ?? Impostazioni
- Configurazioni globali
- Salvataggio automatico
- Reset a defaults

### Operazioni Comuni

#### Avviare/Fermare Bot

```
Top Bar ? Button "Avvia" / "Stop"
```

#### Cambiare Strategia per Asset

```
Asset ? Grid/List ? Dropdown "Strategia Assegnata" ? Seleziona
```

#### Attivare/Disattivare Asset

```
Asset ? Toggle switch per ogni asset
```

#### Monitorare Performance

```
Dashboard ? Vedi summary
Statistics ? Dettagli completi
```

---

## ??? Architettura

### Stack Tecnologico

```
Frontend:  Blazor Server (.NET 10)
           SignalR (Real-time)
           CSS Custom (Dark theme)
           SVG Charts

Backend:   ASP.NET Core
           Services (Singleton)
           Event-driven architecture

Data:      In-memory (runtime)
           JSON files (settings)
           
Deploy:    Docker
           Docker Compose
           Unraid compatible
```

### Componenti Principali

```
TradingBot/
??? Components/
?   ??? Layout/
?   ?   ??? MainLayout.razor          # Sidebar + Layout
?   ??? Pages/
?   ?   ??? Dashboard.razor           # Homepage
?   ?   ??? Strategies.razor          # Strategie
?   ?   ??? Assets.razor              # Asset management
?   ?   ??? Trading.razor             # Trading view
?   ?   ??? Market.razor              # Analisi mercato
?   ?   ??? Statistics.razor          # Statistiche
?   ?   ??? Settings.razor            # Impostazioni
?   ??? Shared/
?       ??? AdvancedChart.razor       # Grafico SVG
?       ??? AssetSettings.razor       # Config asset
?
??? Services/
?   ??? TradingBotService.cs          # Core trading logic
?   ??? SimulatedMarketDataService.cs # Dati simulati
?   ??? SettingsService.cs            # Persistenza settings
?   ??? ITradingStrategy.cs           # Strategy interface
?   ??? SimpleMovingAverageStrategy.cs
?   ??? TechnicalAnalysis.cs          # Calcolo indicatori
?
??? Models/
?   ??? AssetConfiguration.cs         # Config asset
?   ??? AssetStatistics.cs            # Statistiche
?   ??? MarketPrice.cs                # Dati mercato
?   ??? Trade.cs                      # Operazione
?   ??? TechnicalIndicators.cs        # RSI, MACD, EMA
?   ??? AppSettings.cs                # Settings app
?
??? wwwroot/
    ??? app.css                        # Stili globali
```

### Pattern & Practices

- ? **Singleton Services**: Per state management
- ? **Event-driven**: OnStatusChanged, OnPriceUpdated, OnTradeExecuted
- ? **Dependency Injection**: ASP.NET Core DI
- ? **Component Isolation**: Scoped CSS
- ? **Real-time Updates**: SignalR
- ? **Responsive Design**: Mobile-first

---

## ?? Manutenzione

### Backup

#### Backup Automatico (Unraid)

Script: `/root/scripts/backup-tradingbot.sh`

```bash
#!/bin/bash
BACKUP_DIR="/mnt/user/backups/tradingbot"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

docker run --rm \
  -v tradingbot_tradingbot-data:/data \
  -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/tradingbot-data-$DATE.tar.gz -C /data .

# Mantieni 7 giorni
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
```

Crontab:
```
0 3 * * * /root/scripts/backup-tradingbot.sh
```

#### Backup Manuale

```bash
# Locale
cp -r %LocalAppData%/TradingBot backup/

# Docker
docker run --rm -v tradingbot_tradingbot-data:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz -C /data .
```

### Aggiornamenti

#### Via Git (Locale)

```bash
cd Encelado/TradingBot
git pull origin main
dotnet build
dotnet run
```

#### Via Docker

```bash
git pull origin main
docker-compose build
docker-compose up -d
```

#### Via Unraid (SSH)

```bash
cd /mnt/user/appdata/tradingbot/TradingBot
git pull
docker-compose up -d --build
```

#### Via Webhook (Automatico)

Ogni push su Gitea ? Auto-deploy se webhook configurato!

### Monitoring

#### Health Check

```bash
curl http://localhost:8080/health
```

Output atteso: `Healthy`

#### Logs

```bash
# Docker
docker logs tradingbot -f

# Locale
# Vedi console di Visual Studio
```

#### Resource Usage

```bash
docker stats tradingbot
```

### Pulizia

```bash
# Stop container
docker-compose down

# Remove volumes (ATTENZIONE: dati persi!)
docker-compose down -v

# Clean images
docker system prune -a
```

---

## ?? Troubleshooting

### Problemi Comuni

#### Bot non si avvia

**Sintomo**: Container esce immediatamente

**Soluzione**:
```bash
docker logs tradingbot
# Verifica errori
# Controlla porta 8080 libera
```

#### Cache Browser

**Sintomo**: UI non si aggiorna

**Soluzione**:
```
Ctrl + Shift + R (hard refresh)
O vedi: docs/troubleshooting/BROWSER_CACHE_GUIDE.md
```

#### Sidebar non collassa

**Sintomo**: Toggle non funziona

**Soluzione**:
```
1. Hard refresh: Ctrl + Shift + R
2. Vedi: docs/troubleshooting/SIDEBAR_TOGGLE_DEBUG.md
3. Check console: F12 ? Console
```

#### Porta in uso

**Sintomo**: `Address already in use`

**Soluzione**:
```yaml
# docker-compose.yml
ports:
  - "8081:8080"  # Cambia porta esterna
```

#### Out of Memory

**Sintomo**: Container crashato

**Soluzione**:
```yaml
# docker-compose.yml
deploy:
  resources:
    limits:
      memory: 2G  # Aumenta da 1G
```

### Log Debug

```bash
# Aumenta log level
# Settings ? Log Level ? Debug

# O via environment
TRADINGBOT__LogLevel=Debug
```

### Support

1. ?? Leggi [docs/troubleshooting/COMMON_ISSUES.md](TradingBot/docs/troubleshooting/COMMON_ISSUES.md)
2. ?? Cerca issue simili su Gitea
3. ?? Apri issue con:
   - Descrizione problema
   - Logs rilevanti
   - Environment (OS, Docker version, etc.)
   - Steps to reproduce

---

## ?? Documentazione Completa

Tutta la documentazione è organizzata in `TradingBot/docs/`:

- ?? **[docs/README.md](TradingBot/docs/README.md)** - Indice completo
- ?? **[docs/installation/](TradingBot/docs/installation/)** - Guide installazione
- ??? **[docs/architecture/](TradingBot/docs/architecture/)** - Architettura sistema
- ?? **[docs/deployment/](TradingBot/docs/deployment/)** - Guide deployment
- ?? **[docs/configuration/](TradingBot/docs/configuration/)** - Configurazione
- ?? **[docs/trading/](TradingBot/docs/trading/)** - Strategie e indicatori
- ?? **[docs/development/](TradingBot/docs/development/)** - Workflow sviluppo
- ?? **[docs/troubleshooting/](TradingBot/docs/troubleshooting/)** - Risoluzione problemi
- ?? **[docs/verification/](TradingBot/docs/verification/)** - Testing e QA
- ?? **[docs/api/](TradingBot/docs/api/)** - API Reference

---

## ??? Roadmap

### v1.0 (Current) ?
- [x] Core trading engine
- [x] 15 asset supportati
- [x] Strategie base
- [x] UI completa
- [x] Docker deployment
- [x] Unraid support

### v1.1 (Planned)
- [ ] Dati reali (CoinGecko API integration completa)
- [ ] Multi-strategy per asset
- [ ] Alert system con notifiche
- [ ] Export/Import configurazioni
- [ ] Paper trading mode

### v1.2 (Future)
- [ ] Backtesting su dati storici
- [ ] Machine Learning per ottimizzazione
- [ ] Mobile app (MAUI)
- [ ] Multi-user support
- [ ] API REST pubblica

### v2.0 (Vision)
- [ ] Exchange integration (Binance, Coinbase)
- [ ] Real money trading
- [ ] Advanced risk management
- [ ] Portfolio rebalancing
- [ ] Tax reporting

---

## ?? Contributing

Progetto privato. Contributi benvenuti previo contatto con il maintainer.

Vedi: [docs/development/CONTRIBUTING.md](TradingBot/docs/development/CONTRIBUTING.md)

---

## ?? Licenza

Progetto privato - Tutti i diritti riservati
© 2024 Alberto - Encelado Project

**DISCLAIMER**: Questa è un'applicazione di simulazione a scopo educativo. Non utilizzare con denaro reale senza test approfonditi e comprensione completa dei rischi del trading.

---

## ?? Contatti

- **Maintainer**: Alberto (Alby96)
- **Repository**: https://192.168.30.23/Alby96/Encelado
- **Gitea**: https://192.168.30.23

---

## ?? Ringraziamenti

Grazie a:
- Microsoft per .NET e Blazor
- CoinGecko per API dati mercato
- Community open source per librerie e tools

---

**Ultima modifica**: 2024-12-12  
**Versione**: 1.0.0  
**Status**: ? Production Ready