FIRE DD-TRADE-REASON-TRACKING.md

Versione: 1.0
Data: 2025-10-29
Scopo: Descrivere l’architettura, l’implementazione e le best practice del sistema di tracciamento dei motivi di ingresso e uscita per i trade nel backtesting.
Documento Principale: FIRE 25.07 - ARCHITECTURE-OVERVIEW

1. Filosofia: Dal “Cosa” al “Perché”

Il trade log tradizionale risponde a una domanda fondamentale: “Cosa è successo?” (es. profitto/perdita, durata). Tuttavia, per trasformare FIRE in un vero strumento di diagnostica strategica, dobbiamo rispondere a una domanda più profonda: “Perché è successo?“.

Il sistema di tracciamento dei motivi di ingresso e uscita (entry_reason, exit_reason) è stato progettato per colmare questa lacuna. La sua filosofia è quella di dare allo sviluppatore di strategie il potere di annotare ogni decisione operativa con un contesto semantico. Questo trasforma il trade log da un semplice registro contabile a una potente fonte di dati per l’analisi comportamentale e l’ottimizzazione mirata delle strategie.

L’obiettivo è abilitare analisi come:

“Qual è la regola di uscita che contribuisce maggiormente ai profitti?”
“La mia regola di ‘Stop Loss’ viene attivata più spesso del previsto?”
“Quale segnale di ingresso produce i trade più performanti?“

2. Architettura del Flusso Dati

Il sistema è progettato per essere minimamente invasivo e disaccoppiato. L’informazione (il “motivo”) fluisce attraverso quattro layer architetturali distinti, ognuno con una responsabilità specifica:

codeMermaid

graph TD
    A[<b>Fase 1: Strategia</b><br><i>(BaseStrategy)</i><br>Lo sviluppatore fornisce un commento stringa.] --> B
    B[<b>Fase 2: Engine</b><br><i>(BacktestEngine)</i><br>L'engine riceve il commento e lo registra nel dizionario del trade.] --> C
    C[<b>Fase 3: Worker</b><br><i>(BacktestWorker)</i><br>Il worker costruisce il DataFrame finale, pulendo e ordinando le nuove colonne.] --> D
    D[<b>Fase 4: Modello UI</b><br><i>(TradeLogModel)</i><br>Il modello espone i dati alla tabella della UI in modo leggibile.]

2.1. Layer 1: L’API della Strategia (BaseStrategy)

Responsabilità: Fornire un’interfaccia semplice e opzionale allo sviluppatore.
Implementazione: I metodi buy(), sell() e close_position() sono stati estesi per accettare un parametro opzionale comment: Optional[str]. Questo è l’unico punto di interazione per lo sviluppatore di strategie.

2.2. Layer 2: Il Motore di Registrazione (BacktestEngine)

Responsabilità: Ricevere il commento dalla strategia e persisterlo come dato strutturato.
Implementazione: Quando buy() viene chiamato, il commento viene salvato in una nuova chiave entry_reason. Quando sell() o close_position() vengono chiamati, il commento viene salvato come exit_reason nel dizionario del trade attivo.

2.3. Layer 3: Il Processore di Dati (BacktestWorker)

Responsabilità: Trasformare i dati grezzi del backtest in un formato pulito e standardizzato per la UI.
Implementazione: Dopo aver creato il DataFrame dal log dei trade, il worker:
1. Sostituisce i valori None/NaN nelle colonne entry_reason e exit_reason con stringhe vuote.
2. Applica un ordinamento di colonne predefinito per garantire che le nuove colonne appaiano in una posizione logica e coerente nella UI.

2.4. Layer 4: Il Modello Dati della UI (TradeLogModel)

Responsabilità: Esporre i dati del DataFrame alla QTableView in modo efficiente e leggibile.
Implementazione: Il modello, essendo già generico, gestisce dinamicamente le nuove colonne. È stata aggiunta una logica per garantire che i valori nulli vengano visualizzati come celle vuote.

3. Guida Pratica per Sviluppatori di Strategie

L’utilizzo del sistema è intenzionalmente semplice.

3.1. Come Tracciare un Motivo di Ingresso

Quando chiami il metodo buy(), passa il motivo come una stringa descrittiva nel parametro comment.

codePython

# Esempio: Ingresso su breakout di volatilità
if current_volatility > threshold and not self.position:
    self.buy(comment="Volatility Breakout")

3.2. Come Tracciare un Motivo di Uscita

Fai lo stesso per i metodi sell() o close_position(). Se la tua strategia ha più condizioni di uscita, assicurati di fornire il commento corretto per ciascuna.

codePython

# Esempio: Uscita con logiche multiple
if self.position:
    # Uscita 1: Stop Loss
    if self.close < self.stop_loss_price:
        self.sell(comment="Stop Loss")

    # Uscita 2: Take Profit
    elif self.close >= self.take_profit_price:
        self.sell(comment="Take Profit")

    # Uscita 3: Time Exit
    elif self.trade_bars >= 10:
        self.sell(comment="Time Exit (10 bars)")

4. Best Practices per i Commenti

Poiché il sistema si basa su stringhe libere per massimizzare la flessibilità, la coerenza è responsabilità dello sviluppatore. Seguire queste linee guida è fondamentale per rendere i dati analizzabili.

Sii Coerente: Usa la stessa identica stringa per la stessa ragione logica in tutte le tue strategie. “Stop Loss” è diverso da “SL”.
Sii Chiaro ma Conciso: Il commento deve essere immediatamente comprensibile. Evita abbreviazioni troppo criptiche.
Usa una Convenzione di Capitalizzazione: Si consiglia di usare il “Title Case” (es. Take Profit, RSI Crossover).
Adotta Standard Comuni: Quando possibile, utilizza termini standard del settore.

Tabella di Riferimento dei Motivi Consigliati


Tipo	Motivo Consigliato	Descrizione
Entry	RSI Crossover	Ingresso basato su un incrocio dell’indicatore RSI.
Entry	MA Crossover	Ingresso basato su un incrocio di medie mobili.
Entry	Breakout	Ingresso sulla rottura di un livello di prezzo (es. massimo precedente).
Entry	Volume Spike	Ingresso basato su un picco anomalo di volume.
Exit	Stop Loss	Uscita a un livello di prezzo predefinito per limitare le perdite.
Exit	Take Profit	Uscita a un livello di prezzo predefinito per realizzare un profitto.
Exit	Trailing Stop	Uscita basata su uno stop loss dinamico.
Exit	Time Exit	Uscita dopo un numero predefinito di barre.
Exit	Signal Reversal	Uscita perché si è verificato un segnale di trading opposto.
Exit	End of Data	Uscita automatica alla fine dei dati storici (impostata dall’engine).

5. Visione Futura e Sviluppi Potenziali

Questa funzionalità è la base per future evoluzioni dell’analisi di backtesting in FIRE. I prossimi passi potrebbero includere:

Widget di Analisi Dedicati: Creazione di componenti UI (es. grafici a torta) nel pannello di riepilogo per visualizzare la distribuzione percentuale dei motivi di ingresso e uscita.
Statistiche per Motivo: Calcolo automatico di metriche di performance (es. Profit Factor, Win Rate) raggruppate per entry_reason o exit_reason, per identificare rapidamente le logiche più e meno efficaci.

Quartz 4

Explorer

Trade Reason Tracking System