Alby96/Encelado
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Aggiorna e riorganizza la documentazione del progetto

Browse Source 
- Sostituito README.md con versione avanzata e strutturata (indice, badge, quick start, deployment, troubleshooting, roadmap, credits)
- Aggiunto .gitignore completo per .NET, Docker, VSCode, log, dati locali e secrets
- Creato .env.example con tutte le variabili d’ambiente documentate per Docker/Unraid
- Aggiunti script organize-docs.ps1/.sh per strutturare e spostare la documentazione in docs/
- Aggiornate e migliorate tutte le guide tecniche (Docker, Unraid, Git workflow, troubleshooting, verifica finale)
- Documentazione ora pronta per ambienti di produzione, collaborazione e manutenzione
This commit is contained in:
Alberto Balbo
2025-12-13 00:24:58 +01:00
parent b2f04b6600
commit e414123cd0
12 changed files with 1171 additions and 2302 deletions
Download Patch File Download Diff File Expand all files Collapse all files

839
README.md
View File

@@ -1,3 +1,838 @@
# Encelado
# ?? Encelado - TradingBot
Semplice e piccolo robot di trading automatizzato
**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