Files
Anubis/docs/SPEC.md
Alby96andClaude Opus 5.5 32b95b8d68 docs: add Anubis specification, design screens and development plan
Load the full project specification renamed from the provisional "Giano"
to "Anubis" (ADR 0001), the nine reference screens with the new name,
the Unraid template draft pointing at the Gitea container registry, and
the working documents the development phases rely on: CLAUDE.md,
ROADMAP (linked to the 84 Gitea issues and 12 milestones), STATE,
development rules (SVILUPPO), ADR 0002 on Gitea issues, packages and
installer, and Gitea issue/PR templates. No application code yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 12:02:52 +01:00

1604 lines
191 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Anubis — specifica e piano di lavoro per Claude Code
Questo documento è il prompt completo per costruire **Anubis**, un bot di trading personale. Leggilo tutto una volta, poi lavora una fase per volta seguendo la sezione 17. Il nome è stato scelto dall'utente ed è registrato nel primo ADR (`docs/adr/0001-nome-anubis.md`) insieme ai nomi che ne derivano: nome mostrato `Anubis`, pacchetto `anubis`, prefisso delle variabili `ANUBIS_`, prefisso di tre lettere degli ordini `ANU`, nomi nel template Unraid. A progetto avviato si cambia solo il nome mostrato, che sta in una costante.
Se questo file non si trova già in `docs/SPEC.md`, copialo lì senza modificarlo: è la fonte di verità del progetto. Non riscriverlo e non riassumerlo. Quando una decisione cambia, registra il cambiamento in un ADR (sezione 2.4) e lascia intatta la specifica.
---
## 1. Missione
Sei l'ingegnere responsabile di un sistema che muoverà denaro vero. Costruisci da zero un bot di trading multi-strategia e multi-broker che:
1. gira dallo stesso codice in due confezioni: **container Docker** (uno solo, pensato per un server Unraid sempre acceso) e **applicazione desktop** (Windows per prima cosa; macOS e Linux dove non costano lavoro in più);
2. opera su **azioni USA** (Alpaca) e **crypto spot** (OKX Europe), con un'architettura che permetta di aggiungere altri broker senza toccare il resto;
3. prende i dati dai broker stessi o da servizi gratuiti;
4. legge notizie e calendario economico e li usa soprattutto per **ridurre il rischio**;
5. ha un modulo di **apprendimento continuo** che impara dall'esito dei propri segnali;
6. mostra in un'interfaccia web in italiano, semplice e moderna, **cosa sta facendo, come stanno i conti e se sta guadagnando o perdendo**;
7. parte e resta in **simulazione** finché ogni strategia non ha superato requisiti misurabili e l'utente non conferma di persona il passaggio ai soldi veri;
8. tiene i propri dati in **PostgreSQL oppure SQLite**: in Docker la scelta si fa nella configurazione del container, su desktop al primo avvio.
### 1.1 Chi lo usa
Un solo utente, privato, residente in Italia, sviluppatore di professione. Controlla il bot dal computer e dal telefono. Vuole capire ogni decisione senza leggere il codice. Non vuole essere interrotto: preferisce che il sistema decida, registri la scelta e prosegua.
### 1.2 Cosa significa "riuscito"
- Il bot funziona per settimane senza interventi, sopravvive a riavvii, cadute di rete e risposte anomale delle API senza perdere il controllo delle posizioni. Su desktop sopravvive anche a sospensioni e spegnimenti del computer: alla ripartenza recupera con le regole di 5.6.
- Ogni euro è tracciato: il patrimonio mostrato si ricostruisce per intero dai movimenti registrati e coincide con le posizioni e gli ordini presenti sui conti.
- Ogni decisione ha un perché leggibile in italiano, ricostruibile dai dati salvati.
- I risultati sono presentati con onestà: al netto dei costi, confrontati con il semplice comprare e tenere, con le strategie deboli segnalate come tali.
Non esiste garanzia di profitto. La letteratura dice che la maggior parte dei trader privati perde (tra il 74 e l'89% dei conti CFD secondo ESMA). Il valore di Anubis sta nella disciplina: regole semplici con evidenza pubblicata, costi realistici, limiti di rischio rigidi, nessuna promozione a soldi veri senza prove. Se una strategia non supera le verifiche, il risultato corretto è dirlo, non aggiustare i parametri finché il backtest sorride.
---
## 2. Come devi lavorare
### 2.1 Autonomia
- Non chiedere conferme e non proporre alternative da scegliere. Quando serve una decisione non coperta da questo documento, scegli l'opzione più prudente e più semplice, scrivila in un ADR e prosegui.
- Fermati solo quando serve qualcosa che solo l'utente può fornire: credenziali, approvazione di un secondo fattore, conferma per usare soldi veri. Anche in quel caso completa prima tutto ciò che non ne dipende (simulatore, dati registrati, test) e scrivi in `docs/STATE.md` cosa manca.
- Se un fatto su un'API non è verificabile, non inventarlo: isola l'ipotesi dietro un flag, scrivila in `docs/API-NOTES.md` come "non verificato" e vai avanti.
### 2.2 Sicurezza durante lo sviluppo
- Durante lo sviluppo non inviare **mai** ordini su conti reali. Usa solo il simulatore interno, il conto paper di Alpaca e il demo trading di OKX.
- Non chiedere e non usare chiavi API con permesso di prelievo.
- Gli adapter rifiutano di collegarsi a un ambiente reale se la configurazione d'avvio non consente i soldi veri (`ANUBIS_ALLOW_LIVE=1` in Docker, `allow_live = true` in `config.toml` su desktop). Non attivarla mai durante lo sviluppo: i test falliscono se la trovano attiva.
- Nessun segreto nel repository, nei log, nei messaggi di commit, negli screenshot. Fornisci `.env.example` con valori finti.
- Non scavalcare limiti di frequenza, condizioni d'uso o blocchi geografici dei servizi. Se una fonte nega l'accesso, usa un'alternativa della sezione 4.
### 2.3 Verifica prima di dichiarare finito
Ogni fase si chiude solo con prove mostrate nella conversazione: output di `make check` (lint, tipi, test), build dell'immagine Docker riuscita, e per le parti visive uno screenshot Playwright messo a confronto con il mockup. "Dovrebbe funzionare" non è una prova. Se un criterio di accettazione non è soddisfatto, la fase resta aperta e lo scrivi. Unica eccezione: un criterio che dipende solo da qualcosa che deve dare l'utente, come le chiavi di un conto, si segna "in attesa dell'utente" in `ROADMAP.md` e non tiene aperta la fase. Si chiude appena l'utente lo fornisce, con il messaggio dedicato dell'appendice A.
A fine fase lancia un subagent di revisione con contesto pulito: gli dai il diff e i criteri di accettazione della fase e gli chiedi solo difetti di correttezza o requisiti mancati, non preferenze di stile. Correggi ciò che è reale, ignora il resto.
### 2.4 Memoria del progetto
Il contesto di una sessione si riempie e viene compattato: tutto ciò che deve sopravvivere va nei file.
| File | Contenuto | Regola |
|---|---|---|
| `CLAUDE.md` | Comandi (`make check`, `make dev`, `make seed-demo`…), convenzioni non ovvie, puntatori a `docs/` | Massimo 80 righe. Solo ciò che, se mancasse, ti farebbe sbagliare |
| `docs/SPEC.md` | Questo documento | Non si modifica |
| `docs/ROADMAP.md` | Le fasi della sezione 17 come checklist | Spunta le voci quando sono verificate |
| `docs/STATE.md` | Fase corrente, cosa è fatto, cosa è in corso, prossimo passo, blocchi che dipendono dall'utente | Aggiornalo a ogni fine sessione e prima di ogni compattazione |
| `docs/adr/NNNN-titolo.md` | Decisioni architetturali (formato in appendice B) | Una per decisione, mai riscritte: si superano con una nuova |
| `docs/API-NOTES.md` | Fatti verificati sulle API con data e URL | Aggiornalo ogni volta che controlli la documentazione |
All'inizio di ogni sessione leggi `CLAUDE.md` e `docs/STATE.md`, poi le sezioni di `docs/SPEC.md` che la tabella della sezione 17 indica per la fase, più le sezioni 2, 3, 16 e 19, che valgono sempre. Non rileggere tutta la specifica ogni volta.
### 2.5 Ritmo
- **Una fase per sessione.** A fine fase: verifica, commit, aggiorna `ROADMAP.md` e `STATE.md`, scrivi il riepilogo (appendice B) e fermati. La sessione successiva riparte con il messaggio di ripresa (appendice A).
- Prima di scrivere codice in una fase, esplora e pianifica: elenca i file che toccherai, le interfacce, i test che dimostreranno che funziona. Poi implementa a piccoli passi, con i test accanto al codice.
- Commit piccoli e frequenti, messaggi in inglese in stile Conventional Commits. A fine fase crea il tag `fase-N`.
- Per le ricerche sulla documentazione delle API usa subagent, così il contesto principale resta libero.
### 2.6 Lingua
- Codice, identificatori, commenti e commit: inglese. Anche i valori interni sono in inglese (per esempio `observation`, `simulation`, `reduced_live`, `live`): in questo documento stadi e ambienti compaiono con il nome italiano mostrato nell'interfaccia.
- Documenti del progetto (ADR, `STATE.md`, `ROADMAP.md`, manuali) e tutto ciò che l'utente legge (interfaccia, Telegram, diario, messaggi d'errore mostrati a video): italiano semplice, senza gergo. Vedi le regole di scrittura in 13.3.
### 2.7 Dipendenze
- Usa le ultime versioni stabili e fissale con un lockfile. Prima di aggiungere una libreria controlla data dell'ultimo rilascio e licenza.
- Non usare progetti abbandonati o con licenze inadatte: `pandas-ta` (su PyPI c'è solo una pre-release), `backtrader`, `ib_insync`, `mlfinlab`, `timeseriescv`.
- Gli indicatori che servono (medie, ATR, RSI, canali di Donchian, volatilità) sono pochi: scrivili in casa con numpy/pandas e testali contro valori calcolati a mano. Niente libreria di analisi tecnica.
---
## 3. Decisioni già prese
Non rimetterle in discussione. Se una si rivela impraticabile, documenta il motivo in un ADR e scegli l'alternativa più vicina. Unica eccezione: se l'utente chiede la variante C#/.NET, le righe su linguaggio e librerie sono sostituite da quelle dell'appendice D.
| Tema | Decisione |
|---|---|
| Linguaggio backend | Python 3.13 (o l'ultima minor supportata da tutte le dipendenze), gestito con `uv` |
| Web/API | FastAPI + uvicorn, Pydantic v2, API REST + un canale WebSocket per gli aggiornamenti dal vivo |
| Piattaforme | Docker e desktop, dallo stesso codice. Uno strato `platform` isola le sole differenze: da dove arriva la configurazione d'avvio, dove stanno dati e segreti, come si presenta l'applicazione (15.1, 15.6) |
| Database | PostgreSQL oppure SQLite, con lo stesso schema e le stesse migrazioni (5.4). In Docker motore e connessione si scelgono nella configurazione del container e l'interfaccia li mostra soltanto (15.1); su desktop si scelgono al primo avvio, con SQLite predefinito (15.6). SQLAlchemy 2 async con `asyncpg` e `aiosqlite`, più Alembic. Niente estensioni e niente funzioni proprie di un solo motore |
| Storico per la ricerca | File Parquet nella cartella dei dati, letti con `pyarrow` o `polars`. Non entra nel database, che così resta piccolo e uguale sui due motori |
| Concorrenza | Un solo processo asyncio per motore e API, più il piccolo processo di guardia di 9.3; i lavori pesanti (addestramento, backtest) vanno in un process pool e non devono mai bloccare l'event loop. Un solo scrittore sul database: i processi di calcolo restituiscono i risultati al processo principale, che li scrive |
| Connessione ai broker | `alpaca-py` per Alpaca; `ccxt` (che include i WebSocket di `ccxt.pro`) per le crypto |
| Numeri | `Decimal` per prezzi, quantità, denaro e contabilità; `float` solo nell'analisi |
| Apprendimento | scikit-learn + LightGBM; `river` per il rilevamento della deriva; nessuna rete neurale per prevedere i prezzi (motivo in 11.1) |
| Lettura notizie | Un classificatore locale in ONNX (`onnxruntime` + `tokenizers`), senza PyTorch nell'immagine; modello linguistico opzionale e sostituibile |
| Frontend | React + TypeScript + Vite + Tailwind CSS; TanStack Query; `lightweight-charts` per le serie temporali (rispetta l'attribuzione richiesta dalla licenza); barre, misuratori e sparkline come componenti SVG scritti a mano |
| Qualità | ruff, mypy in modalità strict sui moduli `core`, `risk`, `execution`, `accounting`; pytest, pytest-asyncio, hypothesis; vitest; Playwright |
| Distribuzione | Due confezioni. Docker: una sola immagine multi-stage, un solo container, template XML per Unraid (15.3, appendice E). Desktop: avviatore con finestra propria e icona nell'area di notifica, installatore per Windows (15.6). `docker-compose.yml` solo per lo sviluppo (con un Postgres locale) |
| Configurazione | Tutta nel database, modificabile dall'interfaccia, con storico delle modifiche. Fuori dal database resta solo ciò che serve all'avvio: variabili d'ambiente in Docker (15.1), un file locale su desktop (15.6) |
| Cartella dei dati | In questo documento `/data` indica la cartella dei dati: `/data` nel container, la cartella dati dell'utente su desktop (15.6). Stessa struttura in entrambi i casi (15.2) |
| Ambienti | Simulatore interno su prezzi veri, conto di prova del broker, conto reale. Lo stadio di ogni strategia decide in quale ambiente vanno i suoi ordini; in simulazione il predefinito è il simulatore interno per le crypto e il conto di prova per le azioni (7.1) |
| Broker iniziali | Alpaca (azioni USA) e OKX Europe (crypto spot). Altri solo nelle fasi opzionali |
| Leva e vendite allo scoperto | Vietate. Solo acquisti, esposizione massima 100% del capitale |
| Valuta di riferimento | Euro. L'interfaccia può mostrare anche in dollari |
| Fuso orario | Tutto in UTC nel database e nella logica; in visualizzazione il fuso dell'utente, preso dalla configurazione d'avvio (predefinito `Europe/Rome` in Docker, il fuso del sistema su desktop): in questo documento "ora italiana" indica quel fuso. Gli orari di borsa si prendono dal calendario del broker, mai da orari fissi. Due eccezioni seguono l'ora italiana: il "giorno" dei limiti di rischio (9.2) e i lavori di manutenzione (5.5) |
---
## 4. Fatti verificati sulle API (9 ottobre 2026)
Questi fatti sono stati controllati sulle fonti ufficiali alla data indicata. Le API cambiano: **prima di scrivere ogni adapter ricontrolla la documentazione corrente** e annota le differenze in `docs/API-NOTES.md`. Dove è scritto "da verificare", il fatto non è stato confermato.
### 4.1 Alpaca (azioni USA)
Documentazione: https://docs.alpaca.markets
- **Conto paper**: chiunque può aprirne uno solo paper, con 100.000 $ finti. Riceve solo dati IEX.
- **Conto reale per residenti italiani**: Alpaca dichiara di servire più di 195 paesi ma non ne pubblica l'elenco e rimanda al supporto. Da verificare all'apertura del conto. Il bot deve funzionare per intero in paper a prescindere.
- **Crypto su Alpaca**: non disponibile per residenti UE. Non usarla.
- **Dati, piano gratuito "Basic"**: tempo reale solo da IEX; WebSocket fino a 30 simboli; storico dal 2016; dati consolidati (SIP) solo se vecchi di almeno 15 minuti (richieste storiche che finiscono almeno 15 minuti fa, oppure `DataFeed.DELAYED_SIP` nell'SDK); 200 chiamate al minuto. Il piano a pagamento costa 99 $ al mese e non serve.
- **Attenzione ai volumi**: i volumi IEX sono una piccola parte del mercato. Per i filtri di liquidità usa le barre giornaliere consolidate (disponibili con 15 minuti di ritardo), mai i volumi IEX.
- **Notizie**: fonte Benzinga, via REST e via WebSocket `wss://stream.data.alpaca.markets/v1beta1/news`, storico dal 2015, campi `headline`, `summary`, `symbols`, `created_at`, `source`. L'annuncio del 2022 le dichiara gratuite; la documentazione attuale non lo ribadisce. Da verificare con chiavi del piano gratuito; se non fossero incluse, il sistema deve funzionare con le sole fonti della sezione 4.4.
- **Ordini**: tipi market, limit, stop, stop-limit, trailing stop, bracket/OCO/OTO. Validità `day`, `gtc`, `opg`, `cls`, `ioc`, `fok`. Gli ordini `opg` sono rifiutati tra le 09:28 e le 19:00 ET, i `cls` tra le 15:50 e le 19:00 ET.
- **Frazioni di azione**: da 1 $; solo ordini market, limit, stop e stop-limit con validità `day`; niente `opg`/`cls`; niente vendite allo scoperto. Conseguenza: gli stop di protezione sulle frazioni scadono a fine giornata e vanno rimessi a ogni apertura.
- **Fuori orario**: solo ordini limit con `extended_hours=true`. Anubis opera solo in orario regolare.
- **Regola dei day trader (PDT)**: Alpaca ha tolto il requisito dei 25.000 $ il 4 giugno 2026. Nell'SDK i campi `pattern_day_trader`, `daytrade_count` e `daytrading_buying_power` sono facoltativi: non farci affidamento e usa `buying_power`. Il conto di prova non permette di verificarlo, perché parte da 100.000 $: la verifica con il broker è una voce della lista di controllo per i soldi veri (`GO-LIVE.md`). Se la regola risultasse ancora applicata, si accende la protezione descritta in 9.2.
- **Costi**: nessuna commissione, solo piccole tasse regolamentari sulle vendite; conto in dollari; conversione valutaria sui versamenti circa 1,5%.
- **Calendario e orologio di borsa**: `/v2/calendar` e `/v2/clock`. Usali per ogni orario.
- **Azioni societarie** (frazionamenti, dividendi, cambi di simbolo): `GET https://data.alpaca.markets/v1/corporate-actions`, con i parametri `symbols`, `types`, `start`, `end`. Da verificare che sia incluso nel piano gratuito: se non lo fosse, un frazionamento si riconosce dal salto nel rapporto tra serie rettificata e serie reale.
- **Ordini di segno opposto**: Alpaca rifiuta con errore 403 un ordine quando sullo stesso titolo ne esiste già uno aperto di segno opposto e uno dei due è a mercato o stop; due ordini limite di segno opposto sono rifiutati se il prezzo d'acquisto è pari o superiore a quello di vendita. Fanno eccezione gli ordini bracket, OCO e trailing stop (https://docs.alpaca.markets/docs/user-protection). Conseguenza: finché una posizione ha i suoi stop sul broker non si può comprare altro di quel titolo, e non si può posare uno stop mentre l'acquisto è ancora aperto (7.2).
- **Ricavato delle vendite**: su un conto senza margine il ricavato di una vendita può non essere spendibile fino al regolamento, il giorno dopo (da verificare). Il bot compra solo con la liquidità che il broker dichiara disponibile.
- **Elenco degli ETF**: Alpaca non espone un indicatore dedicato (da verificare). Il file pubblico `https://www.nasdaqtrader.com/dynamic/SymDir/nasdaqtraded.txt` ha la colonna `ETF` con valori Y/N per tutti i titoli quotati negli USA.
- SDK: `alpaca-py` (0.44.0 ad agosto 2026).
### 4.2 OKX Europe (crypto spot)
Documentazione per l'Europa: https://my.okx.com/docs-v5/en/
- **Entità**: OKX Europe Ltd, autorizzata MiCA (Malta) dal 27 gennaio 2025 e abilitata a operare in Italia.
- **Indirizzi**: REST `https://eea.okx.com`; WebSocket `wss://wseea.okx.com/ws/v5/public`, `/private`, `/business`.
- **Demo trading**: stessa API REST con l'intestazione `x-simulated-trading: 1`; WebSocket su `wss://wseeapap.okx.com/ws/v5/...`. Le chiavi demo si creano a parte e non scadono. Il demo europeo elenca 27 coppie in EUR e 29 in USDC.
- **Autenticazione**: chiave, segreto e passphrase. Fino a 20 indirizzi IP associabili. Una chiave con permesso di trading e senza IP associato scade dopo 14 giorni di inattività.
- **Commissioni spot** (conti senza derivati, dal 25 settembre 2026): 0,10% maker, 0,20% taker.
- **Valute di quotazione**: EUR e USDC. **USDT non è negoziabile in Europa**: non usare mai coppie in USDT per operare.
- **Liquidità**: buona su BTC/EUR, ETH/EUR, SOL/EUR; scarsa sulle altre coppie in EUR (spread tra 7 e 17 punti base, pochi migliaia di dollari vicino al prezzo). Per le monete minori le coppie in USDC sono più profonde.
- **Candele**: le ultime 1.440 da `/api/v5/market/candles`, le precedenti da `/api/v5/market/history-candles`. BTC-EUR esiste da novembre 2023. Attenzione alle giornaliere: la candela `1D` apre a mezzanotte di Hong Kong, cioè alle 16:00 UTC; quella che apre alle 00:00 UTC si chiede con `1Dutc`. ccxt ha un'opzione dedicata (`fetchOHLCV.timezone`, predefinita `UTC`): da verificare con il test di 8.1.
- **Regole degli strumenti**: `/api/v5/public/instruments` fornisce `minSz`, `lotSz`, `tickSz`. Leggile sempre, non scriverle nel codice.
- **Ordini**: market, limit, post-only, FOK, IOC; ordini algoritmici con stop/take-profit, OCO, trigger, trailing stop.
- **Identificativo dell'ordine scelto dal cliente** (`clOrdId`): solo lettere e cifre, al massimo 32 caratteri (da verificare).
- **Dati pubblici sui derivati** (senza chiave): tasso di finanziamento, open interest, rapporto long/short. Anubis non opera in derivati ma li usa come indizi.
- **ccxt**: classe `myokx` per l'Europa. Controllato sulla versione 4.5.85 (la più recente al 9 ottobre 2026): usa `eea.okx.com`; `set_sandbox_mode(True)` aggiunge l'intestazione del demo e porta i WebSocket su `wss://wseeapap.okx.com:8443/ws/v5`. Le commissioni predefinite nella libreria (0,10% e 0,15%) non coincidono con il listino: leggi quelle del conto dall'API.
- **Commissioni in natura**: sugli acquisti la commissione può essere trattenuta nella moneta comprata, quindi la quantità ricevuta è inferiore a quella ordinata. La contabilità deve registrare la valuta della commissione.
Alternative supportate dallo stesso adapter, da attivare solo se l'utente cambia exchange: **Bitvavo** (classe `bitvavo`; 0,15%/0,25%; i libri in EUR più profondi; nessun ambiente di prova) e **Kraken** (classe `kraken`; 0,40%/0,80% al livello base; l'endpoint delle candele restituisce solo le ultime 720; nessun ambiente di prova, solo `validate=true`).
**Binance non serve più i residenti italiani dal 1º luglio 2026** (nessuna autorizzazione MiCA). Non usarlo per operare. I suoi archivi storici pubblici restano scaricabili senza conto e vanno bene per la ricerca: https://data.binance.vision (candele a 1 minuto dal 2017).
### 4.3 Altri broker (solo per le fasi opzionali)
- **eToro**: API pubblica con chiavi distinte per demo e reale, REST `https://public-api.etoro.com` e WebSocket; circa 60 letture e 20 scritture al minuto; candele da 1 minuto a 1 settimana, 1.000 per richiesta; nessun ordine limite in attesa. Costi alti per un bot (crypto 1% per lato). L'API è cambiata più volte nel 2026: rileggere il portale prima di tutto.
- **Interactive Brokers**: richiede IB Gateway in un container separato e un'approvazione manuale del secondo fattore ogni settimana; dati di mercato a pagamento. Libreria mantenuta: `ib_async`.
- **cTrader Open API** (IC Markets EU, Pepperstone EU): protocollo nativo senza applicazione desktop, conti demo, solo forex e CFD, cioè strumenti a leva incompatibili con i divieti di 9.1. Escluso.
- **OANDA**: l'API v20 non è disponibile per l'entità europea. Escluso.
- **MetaTrader 5**: nessun modo supportato su Linux senza Wine. Escluso.
### 4.4 Fonti gratuite
| Uso | Fonte | Limiti e note |
|---|---|---|
| Storico crypto per la ricerca | `data.binance.vision` | Archivi giornalieri e mensili, nessuna chiave. Coppie in USDT: usale solo come dati |
| Cambio EUR/USD | BCE `https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml`, oppure `https://api.frankfurter.dev` | Un valore al giorno, pubblicato nel pomeriggio. Anubis lo scarica alle 08:00 e alle 16:30 ora italiana e usa sempre l'ultimo disponibile |
| Calendario economico | `https://nfs.faireconomy.media/ff_calendar_thisweek.json` | Solo la settimana corrente, con orario, valuta e impatto; non contiene il dato effettivo. Al massimo una richiesta ogni 5 minuti; aggiornalo una volta l'ora |
| Date future dei dati principali | FRED, `fred/release/dates` con `include_release_dates_with_no_data=true` | Date di pubblicazione di inflazione e occupazione USA oltre la settimana corrente. La chiave è gratuita e facoltativa: se manca, il calendario si ferma alla settimana corrente e l'interfaccia lo dice. FRED dà solo la data: l'orario predefinito è 08:30 di New York e l'impatto è alto. Le riunioni di Fed e BCE stanno in un elenco annuale modificabile dalle impostazioni, con data e ora dell'annuncio (Fed 14:00 di New York, BCE 14:15 ora dell'Europa centrale), compilato dai calendari ufficiali delle due banche |
| Dati macro e VIX | FRED (chiave gratuita, 120 richieste al minuto); storico VIX `https://cdn.cboe.com/api/global/us_indices/daily_prices/VIX_History.csv` | Giornalieri. Il VIX si legge dal file di Cboe, che non chiede chiave |
| Date delle trimestrali | Finnhub, piano gratuito (60 chiamate al minuto) | Chiave facoltativa: se manca, il filtro sulle trimestrali è spento e l'interfaccia lo dice. Il campo `hour` dice se i conti escono prima dell'apertura (`bmo`) o dopo la chiusura (`amc`) |
| Umore crypto | `https://api.alternative.me/fng/` | Giornaliero; richiede attribuzione |
| Comunicati societari | SEC EDGAR | Massimo 10 richieste al secondo, intestazione User-Agent con nome e contatto |
| Notizie | Feed RSS dell'elenco sotto | Lettura ogni 2 minuti |
Feed RSS che rispondevano il 9 ottobre 2026 (rendi l'elenco modificabile dall'interfaccia e segnala i feed che smettono di rispondere):
```
https://www.federalreserve.gov/feeds/press_all.xml
https://www.ecb.europa.eu/rss/press.html
https://www.sec.gov/news/pressreleases.rss
https://search.cnbc.com/rs/search/combinedcms/view.xml?partnerId=wrss01&id=100003114
https://feeds.content.dowjones.io/public/rss/mw_topstories
https://www.investing.com/rss/news.rss
https://xml.fxstreet.com/news/forex-news/index.xml
https://investinglive.com/feed/news
https://www.coindesk.com/arc/outboundfeeds/rss/
https://cointelegraph.com/rss
https://www.theblock.co/rss.xml
https://decrypt.co/feed
https://www.ilsole24ore.com/rss/finanza.xml
https://www.ansa.it/sito/notizie/economia/economia_rss.xml
```
Da non usare come fonti critiche: `yfinance` (le condizioni di Yahoo vietano la raccolta automatica), Stooq (blocca gli script), GDELT (inaffidabile), CryptoPanic (non ha più un piano gratuito), le API di X e Reddit (a pagamento o soggette ad approvazione).
### 4.5 Modelli per leggere le notizie
- **Classificatore locale predefinito**: `mrm8488/distilroberta-finetuned-financial-news-sentiment-analysis` (licenza Apache-2.0). Esiste un'esportazione ONNX già pronta nei repository `Xenova/...` su Hugging Face: scaricala fissando la revisione e controllando l'hash, così l'immagine non contiene PyTorch. Su CPU impiega 10–20 ms per titolo. È addestrato sull'inglese.
- **Modello linguistico (facoltativo)**: il fornitore deve essere sostituibile (Anthropic, qualunque API compatibile con OpenAI, un modello locale via Ollama). Come predefinito usa il modello più economico della famiglia Claude Haiku disponibile al momento: controlla nomi, identificativi e prezzi su https://platform.claude.com/docs/en/about-claude/models/overview e https://platform.claude.com/docs/en/about-claude/pricing e non fidarti della memoria. Il 9 ottobre 2026 la pagina dei prezzi elencava Claude Haiku 5.5 a 0,10 $ in ingresso e 0,50 $ in uscita per milione di token (per richieste fino a 100.000 token) e Claude Haiku 4.5 a 1 $ e 5 $; le richieste in batch costano la metà. La panoramica dei modelli non riportava ancora Haiku 5.5: controlla che esista prima di usarlo. L'identificativo del modello è una voce di configurazione, mai una costante nel codice.
### 4.6 Vincoli per un residente italiano
Non sono consulenza fiscale: servono solo a orientare il progetto.
- **ETF domiciliati negli USA**: di norma non acquistabili dai clienti privati europei (regole PRIIPs) e fiscalmente penalizzati in Italia perché non armonizzati. Anubis li usa solo come **indicatori** (per esempio SPY per capire la tendenza del mercato) e opera soltanto su **azioni singole**. Il filtro deve essere attivo per impostazione predefinita. Non è stato verificato se Alpaca applichi il blocco ai residenti europei: il filtro di Anubis non deve dipendere da questo.
- **Dichiarazione dei redditi**: entrambi i broker sono esteri e non fanno da sostituto d'imposta. Il bot deve poter esportare l'elenco completo delle operazioni con controvalore in euro al cambio BCE della data di ciascuna (se quel giorno la BCE non pubblica, l'ultimo cambio precedente), in CSV (13.3).
---
## 5. Architettura
### 5.1 Struttura del repository
```
anubis/
CLAUDE.md Makefile pyproject.toml uv.lock Dockerfile docker-compose.yml .env.example
.gitea/workflows/ci.yml
docs/ SPEC.md ROADMAP.md STATE.md API-NOTES.md MANUALE.md RUNBOOK.md GO-LIVE.md adr/ design/ backtests/
backend/anubis/
core/ clock, event bus, scheduler, settings, secrets, logging, ids, watchdog
platform/ docker.py, desktop.py: configurazione d'avvio, cartella dei dati, custodia dei segreti
db/ modelli SQLAlchemy, repository, migrazioni Alembic
brokers/ base.py (interfaccia), alpaca.py, ccxt_spot.py, paper.py, conformance/
data/ strumenti, barre, collector, qualità, importatori, cambi, calendari
news/ fonti, pipeline, classificatore, analista (LLM), impatto
strategies/ base.py, crypto_trend.py, equity_momentum.py, equity_meanrev.py, candidates/
portfolio/ allocazione, dimensionamento, ribilanciamento
risk/ regole, motore, interruttore, riconciliazione
execution/ OMS (macchina a stati), algoritmi d'ordine, misura dello scostamento
accounting/ registro, lotti, patrimonio, rendimenti, benchmark, esportazioni
ml/ feature, etichette, addestramento, registro modelli, deriva
backtest/ motore, modelli di costo, validazione, report
journal/ codici motivo, frasi in italiano
notify/ telegram
api/ router REST, WebSocket, autenticazione
demo/ modalità dimostrativa: dati dell'appendice F (13.1)
engine.py orchestrazione
backend/tests/ unit/ integration/ simulation/ live_demo/ golden/
frontend/ src/ (pages, components, charts, lib/format.ts, lib/tokens.ts) e2e/
desktop/ launcher.py (finestra, area di notifica, istanza unica), packaging/ (PyInstaller, Inno Setup)
deploy/ unraid/anubis.xml unraid/anubis-icon.png
```
### 5.2 Il percorso di una decisione
Ogni operazione nasce e viene registrata in questa catena. Nessuno stadio può essere saltato e nessuna strategia parla direttamente con un broker.
```
Strategia → Intenzione → Correttivi → Dimensione → Controlli di rischio → Ordine → Esecuzione → Registro
(con motivi) (regime, eventi, (possono ridurre (OMS)
notizie, modello) o rifiutare)
```
Ogni stadio scrive una riga nella tabella `decisions` con: identificativo della decisione, stadio, esito, **codici motivo** e valori numerici usati. Da queste righe, con modelli di testo fissi, si generano il diario e la scheda "perché" di ogni operazione. Le spiegazioni non sono mai scritte da un modello linguistico: devono dire esattamente ciò che è successo.
### 5.3 Interfacce principali
Sono schemi: adatta i dettagli, mantieni la separazione delle responsabilità.
```python
class BrokerAdapter(Protocol):
id: str
capabilities: BrokerCapabilities # frazioni, stop nativi, validità ammesse, demo, flussi dal vivo
async def connect(self) -> None: ...
async def server_time(self) -> datetime: ...
async def list_instruments(self) -> list[Instrument]: ... # con tick, lotto, minimo
async def get_account(self) -> AccountSnapshot: ... # patrimonio e liquidità per valuta
async def get_positions(self) -> list[BrokerPosition]: ...
async def get_open_orders(self) -> list[BrokerOrder]: ...
async def submit_order(self, req: OrderRequest) -> BrokerOrder: ... # idempotente su client_order_id
async def cancel_order(self, client_order_id: str) -> None: ...
async def get_order(self, client_order_id: str) -> BrokerOrder | None: ...
async def get_fills(self, since: datetime) -> list[Fill]: ... # con identificativo del broker, importo e valuta della commissione
async def get_cash_activities(self, since: datetime) -> list[CashActivity]: ... # versamenti, prelievi, dividendi
async def get_corporate_actions(self, since: date) -> list[CorporateAction]: ... # frazionamenti e dividendi, dove il broker li espone
async def fetch_bars(self, instrument: InstrumentId, timeframe: str, start: datetime, end: datetime) -> list[Bar]: ...
async def fetch_quote(self, instrument: InstrumentId) -> Quote: ...
def stream_market_data(self, instruments: list[InstrumentId]) -> AsyncIterator[MarketEvent]: ...
def stream_order_updates(self) -> AsyncIterator[OrderEvent]: ...
class Strategy(Protocol):
id: str
version: str
def schedule(self) -> list[DecisionTime]: ... # espressi rispetto al calendario del mercato
def universe(self, ctx: UniverseContext) -> list[InstrumentId]: ...
def decide(self, ctx: StrategyContext) -> list[Intent]: ... # funzione dei soli dati fino a "adesso"
```
`StrategyContext` fornisce dati **fino all'istante della decisione e non oltre**: è lo stesso oggetto nel backtest, in simulazione e in reale. Una strategia non sa in quale modalità sta girando.
`PaperBroker` implementa `BrokerAdapter` appoggiandosi ai dati dal vivo di un adapter reale e simulando esecuzioni, commissioni e saldi (7.3). È il simulatore interno di 7.1: sempre disponibile, e ambiente predefinito per le strategie crypto in simulazione.
### 5.4 Tabelle principali
`instruments`, `corporate_actions`, `bars_1d`, `bars_1m`, `fx_rates`, `market_calendar`, `accounts`, `orders`, `fills`, `positions`, `lots`, `cash_ledger`, `equity_snapshots`, `decisions`, `signals`, `strategy_state`, `strategy_stage_history`, `risk_events`, `news_items`, `news_analysis`, `calendar_events`, `market_mood`, `ml_features`, `ml_labels`, `ml_models`, `ml_predictions`, `backtest_runs`, `backtest_trials`, `journal`, `config`, `config_history`, `secrets`, `users`, `sessions`, `notifications`, `jobs`.
Regole: chiavi surrogate UUIDv7; ogni riga porta `created_at` in UTC; le tabelle contabili (`fills`, `cash_ledger`, `lots`) sono di sola aggiunta: gli errori si correggono con righe di storno, mai con UPDATE. Le esecuzioni hanno una chiave unica su conto e identificativo dato dal broker: la stessa esecuzione, arrivata sia dal flusso sia dall'interrogazione di riserva, si registra una volta sola.
**Lo stesso schema deve girare su PostgreSQL e su SQLite.** Regole:
- **Denaro, quantità e prezzi di ordini, esecuzioni e posizioni**: un tipo personalizzato che usa `NUMERIC(38,18)` su PostgreSQL e testo su SQLite, e restituisce sempre `Decimal`. Prima di scrivere arrotonda a 18 decimali su entrambi i motori, così ciò che si rilegge è identico. Mai `REAL` o `float` per questi valori. Somme, confronti e ordinamenti su di essi si fanno in Python, non in SQL: così il risultato è identico sui due motori. Le barre di mercato sono dati d'analisi e restano numeri in virgola mobile.
- **Identificativi e date**: il tipo `Uuid` di SQLAlchemy; date sempre in UTC, con un tipo che su SQLite le salva come testo ISO e rifiuta i valori senza fuso.
- **JSON**: il tipo generico `JSON`; nessun operatore proprio di un motore nelle interrogazioni.
- **Vietato** ciò che esiste in un solo motore: partizionamento, viste materializzate, `LISTEN/NOTIFY`, blocchi consultivi, SQL scritto a mano per un dialetto. Gli inserimenti con aggiornamento passano dai costrutti di SQLAlchemy disponibili per entrambi.
- **SQLite**: modalità WAL, `synchronous=FULL`, `foreign_keys=ON`, `busy_timeout` di 5 secondi; una sola connessione in scrittura, più connessioni in lettura.
- **Migrazioni**: Alembic con `render_as_batch=True`; ogni migrazione è provata su entrambi i motori.
- **Dimensione**: `bars_1m` contiene solo gli strumenti in portafoglio e conserva 400 giorni; lo storico per la ricerca sta nei file Parquet (6.6).
- **Esportazione e importazione**: `anubis db export` scrive un archivio indipendente dal motore (una riga JSON per record, una tabella per file, più un indice con versione dello schema e conteggi), leggendo tutte le tabelle in un'unica transazione di sola lettura: l'archivio è la fotografia di un solo istante. `anubis db import` lo carica in un database vuoto e verifica conteggi e totali contabili. Serve ai salvataggi, al ripristino e a passare da un motore all'altro. Dopo un'importazione il bot riparte protetto (15.1).
- **Salvataggi**: ogni notte l'esportazione appena descritta; con SQLite anche una copia coerente del file fatta con l'API di backup. Si conservano le ultime 14 copie. Un salvataggio parte anche prima di ogni migrazione, su entrambe le piattaforme.
### 5.5 Ritmo della giornata
Gli orari di mercato sono definiti rispetto all'apertura e alla chiusura date dal calendario del broker, non all'ora italiana (attenzione alle settimane in cui l'ora legale di USA ed Europa non coincide, e alle sedute a orario ridotto). Tra parentesi l'ora di New York di una seduta normale. I lavori si agganciano al pianificatore man mano che le fasi li consegnano.
| Quando | Cosa |
|---|---|
| 00:05 UTC, ogni giorno | Chiusura giornaliera crypto: segnali di `crypto_trend`, ribilanciamento, aggiornamento degli stop |
| Un'ora prima dell'apertura, giorni di borsa | Lettura delle azioni societarie (6.10) |
| 5 minuti dopo l'apertura (09:35), giorni di borsa | Rimessa degli stop giornalieri sulle frazioni di azione (7.2); poi gli ordini decisi la sera prima: prima le vendite, poi gli acquisti |
| 5 minuti prima della chiusura (15:55) | Uscite di `equity_meanrev` |
| 20 minuti dopo la chiusura (16:20) | Calcolo dei segnali sulle azioni per il giorno dopo. Le barre consolidate arrivano con 15 minuti di ritardo: se mancano, riprova ogni 5 minuti fino a 45 minuti dopo la chiusura e poi ogni ora fino all'apertura successiva. Se non arrivano nemmeno allora, in quella seduta non apre nuove posizioni sulle azioni e avvisa |
| Sempre | Flussi dei prezzi, sorveglianza degli stop, lettura notizie ogni 2 minuti |
| Ogni 5 minuti | Riconciliazione con i conti e fotografia del patrimonio |
| Ogni ora | Calendario economico, indicatori d'umore |
| 03:00 ora italiana | Controllo della deriva del modello; la domenica, verifica dello sfidante e, se serve, nuovo addestramento (11.4) |
| 03:30 ora italiana | Salvataggio del database in `/data/backups` (5.4) |
| 08:00 ora italiana | Riepilogo del mattino su Telegram; aggiornamento del cambio |
| 16:30 ora italiana | Aggiornamento del cambio |
### 5.6 Recupero dopo un'assenza
Il bot può restare spento: un riavvio del container, una caduta di rete, il computer in sospensione. Su desktop è la norma, non l'eccezione. Alla ripartenza, dopo i passi di 9.4, ogni lavoro saltato si tratta così:
| Lavoro saltato | Alla ripartenza |
|---|---|
| Azioni societarie | Si leggono per prime: gli stop si toccano solo dopo (6.10) |
| Stop di protezione | Si rimettono subito, se il mercato è aperto; se il prezzo è già al livello o sotto vale la regola dello stop già superato (7.2). Vengono prima di ogni altro lavoro di mercato |
| Uscite | Le verifiche d'uscita saltate si rifanno con i dati del momento; le uscite già decise si eseguono appena il mercato lo permette. Un'uscita in ritardo resta valida |
| Ingressi di `equity_meanrev` | Validi fino a 60 minuti dopo l'apertura; oltre si scartano |
| Ingressi settimanali di `equity_momentum` | Validi per le prime due sedute della settimana; oltre si aspetta la revisione successiva |
| Decisione giornaliera di `crypto_trend` | Valida fino alle 12:00 UTC dello stesso giorno; oltre si aggiornano solo uscite e stop e si aspetta la chiusura successiva |
| Calcolo dei segnali sulle azioni | Si rifà appena possibile, purché prima dell'apertura successiva |
| Notizie e calendario | Si rilegge l'arretrato delle ultime 24 ore; gli effetti già scaduti non si applicano |
| Etichette, controllo del modello, salvataggi | Si eseguono una volta sola, in coda |
| Cambio | Si scarica subito l'ultimo disponibile |
| Riepilogo del mattino | Si invia se non sono ancora le 12:00 ora italiana; oltre si salta |
| Simulatore interno | Ripercorre le barre a 1 minuto dell'assenza ed esegue stop e vendite che sarebbero scattati; annulla gli acquisti rimasti in attesa (7.3) |
Un ingresso recuperato passa di nuovo da correttivi e rischio con i prezzi del momento, e si scarta se il prezzo dista più dell'1% (azioni) o del 2% (crypto) da quello dell'orario previsto. Ogni recupero e ogni scarto finiscono nel diario con il loro motivo. Se l'assenza ha superato le 24 ore, la Panoramica lo dichiara in alto finché l'utente non ne prende visione. Il backtest non simula le assenze: nel confronto di coerenza di 12.3 le decisioni recuperate o scartate non si contano.
---
## 6. Dati di mercato
1. **Strumenti**: un catalogo unico con identificativo interno, broker, simbolo del broker, classe (azione, crypto), valuta, tick, lotto, importo minimo, stato. Aggiornato ogni giorno dalle API.
2. **Barre**: giornaliere per tutte le strategie; a 1 minuto solo per gli strumenti in portafoglio e per la simulazione degli ordini. Per le azioni conserva sia i prezzi rettificati per frazionamenti e dividendi (per i segnali) sia quelli reali (per gli ordini).
3. **Recupero dello storico**: all'avvio e dopo ogni buco di connessione il collector scarica ciò che manca. I buchi non recuperabili vengono registrati.
4. **Qualità**: controlli automatici su duplicati, buchi, prezzi nulli o negativi, salti oltre 8 deviazioni standard, barre con massimo inferiore al minimo. Un dato anomalo non viene corretto in silenzio: viene marcato e la strategia non apre né aumenta posizioni su quello strumento finché il dato non è confermato da una seconda lettura. Uscite e stop proseguono.
5. **Freschezza**: ogni flusso ha un'età massima (60 secondi per i prezzi dal vivo). Oltre la soglia il rischio blocca i nuovi ingressi su quello strumento (9.2).
6. **Storico per la ricerca**: importatore degli archivi `data.binance.vision` e importatore generico di CSV al minuto forniti dall'utente (cartella `/data/import`, mappatura delle colonne configurabile, formati tipo `BTCEUR`, `BTCUSDT`, `ETHUSDT`). Lo storico importato si salva in file Parquet sotto `/data/research`, uno per strumento e per anno; i backtest lo leggono da lì e non dal database.
7. **Universo azionario senza distorsioni evitabili**: costruiscilo "a una certa data", cioè scegliendo per ogni giorno i titoli più scambiati usando solo dati disponibili quel giorno, includendo se possibile i titoli poi revocati (verifica se Alpaca restituisce le barre degli asset `inactive`). Gli indicatori che l'API dà solo allo stato di oggi (frazionabile, ETF) si applicano così come sono. Documenta in `docs/API-NOTES.md` la distorsione residua.
8. **Cambi**: EUR/USD di riferimento dalla BCE (4.4). Serve a valutare il conto in dollari e ai resoconti; ogni operazione salva il cambio di riferimento in vigore quando avviene. L'esportazione per la dichiarazione usa invece il cambio della data dell'operazione (4.6), che per gli ordini del primo pomeriggio esce più tardi.
9. **Limiti del piano gratuito Alpaca**: abbonati al flusso dal vivo solo per le posizioni aperte e per SPY come indicatore, restando sotto i 30 simboli. Dall'apertura fino all'esecuzione aggiungi i candidati all'ingresso del giorno; se il totale supererebbe 30, per i candidati usa una quotazione istantanea via REST subito prima di ogni ordine.
10. **Azioni societarie** (frazionamenti, dividendi, cambi di simbolo): si leggono ogni giorno prima dell'apertura (4.1). Tre regole. Primo: i segnali si calcolano sempre sulla serie rettificata ancorata al giorno della decisione, quella in cui l'ultimo prezzo coincide con il prezzo reale; così medie, massimi e livelli di stop sono già in prezzi di oggi. Nel backtest la serie vista al giorno t è quella finale, riscalata perché il prezzo del giorno t coincida con quello reale. Secondo: quando un'azione societaria tocca uno strumento seguito si riscarica per intero la sua serie rettificata, e i livelli che la strategia ha salvato (prezzo d'ingresso, chiusura più alta, stop) si convertono con il fattore dell'operazione. Le quantità in portafoglio e il costo dei lotti cambiano solo con frazionamenti e raggruppamenti: un dividendo non li tocca. Gli stop sul broker si rimettono con i valori nuovi; alla data di un frazionamento il broker può avere già annullato gli ordini aperti (da verificare). La variazione di quantità sul conto è una differenza spiegata (7.4) e finisce nel diario. Terzo: i filtri dell'universo su prezzo e controvalore (8.2) usano i prezzi reali del giorno, non quelli rettificati, altrimenti un frazionamento futuro cambierebbe l'universo del passato.
---
## 7. Conti, ordini e contabilità
### 7.1 Conti, ambienti e capitale
- **Conto**: una connessione a un ambiente di un broker, con le sue chiavi. Per ogni broker possono esistere un conto di prova (paper di Alpaca, demo di OKX) e un conto reale. Il **simulatore interno** (7.3) è un terzo ambiente, sempre disponibile, che usa i prezzi di un conto qualsiasi.
- **Lo stadio di una strategia decide dove vanno i suoi ordini** (12.3): in osservazione da nessuna parte; in simulazione nel simulatore interno o nel conto di prova (si sceglie per strategia; predefinito: simulatore interno per le crypto, conto di prova per le azioni); in reale ridotto e in reale nel conto reale. Due strategie dello stesso broker possono quindi trovarsi in ambienti diversi.
- **Capitale affidato**: per ogni broker l'utente fissa una cifra in euro, che le strategie si dividono secondo le quote di 8.6. Per un conto in dollari la cifra si converte al cambio del giorno in cui viene fissata, e da lì il registro è in dollari. Il capitale di una strategia è la sua quota più i guadagni e meno le perdite che lei stessa ha prodotto; non attinge mai alla quota di un'altra. Il bot tiene un registro separato per ogni coppia strategia-ambiente e non usa mai più del capitale affidato e dei risultati che ha prodotto, anche se il conto contiene di più. **Il patrimonio del bot è la somma di questi registri, mai il saldo del conto.** Un versamento sul conto non cambia il capitale affidato: lo cambia solo l'utente dalle impostazioni, e quella modifica entra nel calcolo del rendimento come versamento o prelievo, insieme ai cambi di quota e di stadio (7.5). Se una strategia è nel conto reale, aumentare il capitale affidato o la sua quota richiede la procedura di 12.4.
- **Soldi veri e simulati si mostrano sempre separati.** Finché nessuna strategia è nel conto reale, tutta l'interfaccia mostra la simulazione. Dal primo passaggio al reale, totali, rendimenti e limiti di perdita si calcolano separatamente per i due mondi (alcuni limiti usano un riferimento comune ai due mondi, definito in 9.2): la Panoramica mostra i soldi veri e, in un riquadro distinto e dichiarato, il risultato delle strategie ancora in simulazione.
- **Proprietà delle posizioni**: sui conti possono esserci posizioni dell'utente. Anubis gestisce **solo ciò che ha aperto lui**, riconoscibile dal prefisso `ANU` nel `client_order_id` e dal proprio registro. Non tocca mai il resto.
- **Cambio di stadio**: quando una strategia passa al conto reale il suo registro reale parte vuoto. Le posizioni simulate restano al gemello simulato (12.3); quelle reali nascono al primo ciclo di decisione, comprando i pesi obiettivo del momento (`equity_meanrev` aspetta i segnali nuovi), e il riepilogo di 12.4 lo dice prima della conferma. In reale ridotto la strategia lavora con un quarto del suo capitale. Una strategia retrocessa o revocata resta sul conto reale in sola uscita (12.3); se viene promossa di nuovo, le posizioni rimaste tornano sotto la gestione normale, perché il registro reale è lo stesso.
### 7.2 Gestione degli ordini (OMS)
- Macchina a stati esplicita: `created → submitted → partially_filled → filled | canceled | rejected | expired`. Ogni transizione è registrata.
- `client_order_id` deterministico, solo lettere e cifre, al massimo 32 caratteri: prefisso `ANU`, poi codice dell'installazione, ambiente, strategia, tipo di ordine (ingresso, uscita, stop, vendita di protezione), identificativo compatto della decisione o della posizione e un progressivo. Il progressivo cresce a ogni invio voluto: un passo dell'inseguimento, la rimessa quotidiana di uno stop, un aggiornamento. Solo il reinvio dopo un errore di rete riusa lo stesso identificativo, e quindi non può creare un doppione. Prima di reinviare, interroga sempre il broker. Da questo identificativo si risale a strategia e ambiente di un ordine anche senza il database (15.1).
- Arrotondamenti a tick e lotto e controllo dell'importo minimo **prima** dell'invio; un ordine sotto il minimo viene scartato con il suo codice motivo.
- Aggiornamenti dal flusso WebSocket, con interrogazione periodica di riserva.
- Esecuzione predefinita "limite che insegue": ordine limite al prezzo migliore (denaro per un acquisto, lettera per una vendita); se dopo 60 secondi non è eseguito, si sposta sul nuovo prezzo migliore; dopo 3 passi diventa un limite aggressivo, che attraversa il mercato ma non oltre una tolleranza massima dal **prezzo di riferimento**: 0,3% per le azioni, 0,5% per BTC, ETH e SOL, 0,8% per le altre crypto. Il prezzo di riferimento è il punto medio tra denaro e lettera nel momento in cui parte il primo ordine: non è la chiusura su cui è nato il segnale. Ogni passo parte solo dopo che il broker ha confermato l'annullamento del precedente, e solo per la quantità rimasta. Su OKX i primi tre passi sono ordini post-only: pagano la commissione più bassa.
- Se nemmeno il limite aggressivo viene eseguito: un acquisto si annulla (le strategie a pesi obiettivo lo ripropongono da sole al ciclo successivo; `equity_meanrev` lo scarta). Una vendita non si abbandona: riparte ogni minuto con un nuovo riferimento preso dal prezzo corrente e con tolleranza doppia, e dopo 5 minuti senza esecuzione avvisa e continua. Le uscite delle 15:55 di `equity_meanrev` partono direttamente come limite aggressivo, perché alla chiusura mancano 5 minuti; ciò che resta si vende alla prima occasione della seduta successiva.
- Mai ordini a mercato per entrare o uscire su decisione di una strategia. Le eccezioni sono tre, tutte di protezione: gli stop sul server, la vendita di una posizione il cui stop è già superato o è scattato solo in parte, e "Ferma e chiudi tutte le posizioni" (9.3).
- Ritmo: per ogni conto non più di 6 invii al minuto tra acquisti e vendite, contando sia gli ordini nuovi sia i passi dell'inseguimento. Passano davanti le vendite e i passi degli ordini già in lavorazione; gli acquisti nuovi aspettano in coda. Le vendite di protezione saltano la coda e non contano. Posa, rimessa e aggiornamento degli stop hanno una coda propria e non contano.
- **Stop di protezione sul server del broker** appena l'ordine d'acquisto è completo o annullato, così la posizione è protetta anche se il bot si spegne; mentre l'acquisto è in lavorazione, pochi minuti, il livello lo sorveglia il bot: se il prezzo lo tocca, l'acquisto si annulla e vale la regola dello stop già superato. Su OKX: ordine trigger. Su Alpaca: per la parte intera della quantità uno stop valido fino a revoca (GTC), che resta sul broker anche a bot spento e va rinnovato prima che il broker lo faccia scadere (dopo 90 giorni: da verificare); per la parte frazionaria uno stop giornaliero, rimesso a ogni apertura e sorvegliato dal bot a mercato chiuso, cosa che lo stato dichiara. Gli stop di protezione sono ordini stop a mercato, perché devono essere eseguiti comunque. La quantità è quella realmente detenuta, al netto delle commissioni trattenute in natura, arrotondata per difetto al lotto. Una miglioria da valutare solo dopo la batteria di conformità: gli ordini con lo stop allegato (OTO su Alpaca per le azioni intere, stop allegato all'ordine su OKX) farebbero nascere lo stop insieme all'esecuzione.
- **Aumentare una posizione che ha già i suoi stop**: su Alpaca vanno prima annullati, perché il broker rifiuta un acquisto quando sullo stesso titolo c'è uno stop di vendita aperto (4.1). Si annullano solo per la durata dell'acquisto e si rimettono subito, per la nuova quantità, comunque l'acquisto finisca; nel frattempo il livello lo sorveglia il bot.
- **Gli stop seguono sempre la quantità detenuta.** Quando un acquisto o una vendita si conclude, anche in parte, si riallineano alla quantità rimasta; la riconciliazione lo controlla ogni 5 minuti e ripara. Prima di vendere si annullano gli stop sulla quantità in vendita; se la vendita non si completa si rimettono subito. Su Alpaca i due stop di una posizione valgono come uno solo: se ne scatta uno, il bot vende subito a mercato anche il resto.
- **Stop già superato.** Se nel momento in cui uno stop va posato o rimesso il prezzo è già al livello o sotto (apertura in ribasso, ritorno da un'assenza), lo stop vale come scattato: la quantità scoperta si vende subito a mercato e l'operazione si chiude come uscita per stop. Qui il prezzo è l'ultimo scambio, non più vecchio di 60 secondi e confermato da una seconda lettura via REST: se manca o è anomalo, la vendita aspetta la conferma. Se il prezzo sta sotto il livello di oltre il 30%, prima si controlla che non ci sia di mezzo un frazionamento (6.10). Vale anche in pausa e con "Ferma tutto" attivo. A mercato chiuso la vendita parte all'apertura.
- **Residui invendibili.** Se dopo un'uscita completa resta una quantità sotto il lotto o sotto l'importo minimo, si storna dal registro al valore di mercato, come costo dell'operazione: la posizione va a zero e l'operazione si chiude. Il residuo resta sul conto, fuori dal registro, e compare in un elenco a parte nella schermata Conti. Per lo stesso motivo il bot non compra frazioni che valgono meno del minimo ordinabile: arrotonda per difetto.
- Per ogni esecuzione misura lo scostamento tra prezzo di riferimento e prezzo ottenuto.
### 7.3 Simulatore interno
Riempimenti realistici e prudenti: prezzo denaro/lettera dal vivo più uno scostamento per fascia di liquidità (5 punti base per le azioni dell'universo e per BTC, ETH e SOL; 15 per le altre crypto); un ordine limite è eseguito solo se il prezzo lo **attraversa**; ritardo simulato tra 300 e 1.000 ms; commissioni secondo il listino del broker; gli stop scattano con scostamento sfavorevole. Stesse regole di arrotondamento e minimo del broker reale, comprese le commissioni trattenute in natura; per le azioni accredita i dividendi letti dalle azioni societarie. A bot spento il simulatore non vede i prezzi: alla ripartenza ripercorre le barre a 1 minuto dell'assenza ed esegue gli stop e le vendite che sarebbero scattati, al loro livello oppure all'apertura della barra se questa lo aveva già superato; gli acquisti rimasti in attesa si annullano.
### 7.4 Riconciliazione
All'avvio e ogni 5 minuti confronta registro interno e conto (posizioni proprie, ordini aperti, liquidità). Se differiscono:
- differenze spiegabili (un'esecuzione arrivata in ritardo, un'azione societaria di 6.10) si sanano da sole e si annotano;
- differenze non spiegabili mettono il conto in **modalità prudente**: nessun nuovo ingresso su quel conto, uscite e stop che proseguono, avviso immediato su Telegram e nel diario. Se la differenza si spiega entro 15 minuti la modalità rientra da sola; altrimenti resta finché l'utente non sceglie, dall'interfaccia, se allineare il registro al conto con una riga di storno o lasciare fuori dal registro ciò che non è del bot.
Cosa si confronta dipende dall'ambiente. Nel simulatore interno non c'è un broker con cui confrontarsi: si verifica la coerenza del registro. Sui conti di prova si riconciliano posizioni e ordini del bot; la liquidità è quella del registro interno, perché il conto di prova contiene denaro finto in quantità arbitraria. Sui conti reali si riconcilia anche la liquidità: quella del conto non deve mai essere inferiore a quella che il registro attribuisce al bot. Dove c'è un broker si controlla anche che gli stop coprano la quantità detenuta, arrotondata come in 7.2.
### 7.5 Contabilità
- Registro di sola aggiunta: esecuzioni, commissioni (con valuta), versamenti e prelievi (per il bot sono le modifiche del capitale affidato e i cambi di quota e di stadio), dividendi, storni.
- Posizioni a lotti: prezzo medio per la visualizzazione; metodo LIFO per il resoconto fiscale delle crypto (configurabile).
- **Operazione**: va da quantità zero a quantità zero per strumento e strategia (vale zero anche un residuo stornato, 7.2). I prezzi di entrata e di uscita sono medie ponderate; il risultato è al netto delle commissioni. Una vendita parziale entra subito nei guadagni incassati; l'operazione entra nei conteggi (numero, quota in guadagno, requisiti di 12.3, etichette di 11.2) quando si chiude.
- Patrimonio per strategia, per conto e totale in euro: sempre la somma dei registri del bot (7.1), fotografata ogni 5 minuti e a ogni esecuzione.
- **Rendimento corretto per versamenti e prelievi** (time-weighted): un versamento non deve sembrare un guadagno. Per il bot versamenti e prelievi sono le modifiche del capitale affidato e delle quote e, per ciascun mondo, i registri che vi entrano, ne escono o cambiano capitale con un cambio di stadio: una promozione non deve sembrare una perdita della simulazione né un guadagno dei soldi veri. I movimenti di cassa letti dalle API dei broker servono alla riconciliazione e ai dividendi, non al rendimento.
- Dividendi: vanno alla strategia che deteneva lo strumento alla chiusura prima dello stacco e si registrano alla data di stacco; se sul conto ci sono anche azioni dell'utente, in proporzione alla quantità del bot.
- Risultato per strategia, per conto, per strumento; realizzato e non realizzato; costi separati (commissioni, scostamento stimato).
- **Confronto "senza bot"**: lo stesso capitale, con gli stessi versamenti, investito il primo giorno al 40% in Bitcoin (BTC/EUR) e al 60% nell'S&P 500 (prezzi rettificati di SPY, convertiti in euro al cambio BCE) e mai toccato. È il termine di paragone onesto mostrato in Panoramica.
- **Effetto cambio**: mostra separatamente quanto del risultato del conto in dollari dipende dal cambio EUR/USD.
---
## 8. Strategie
Tre strategie di base, scelte perché semplici, a bassa frequenza e con evidenza pubblicata al netto dei costi. I parametri indicati sono i valori di partenza: non ottimizzarli sul passato oltre quanto previsto in 12.2. Tutte comprano soltanto. Gli orari citati (09:35, 15:55, 16:20 di New York) sono quelli di una seduta normale: valgono rispetto ad apertura e chiusura, come in 5.5.
### 8.1 `crypto_trend` — seguire la tendenza sulle crypto
Riferimento: Zarattini, Pagani, Barbon, "Catching Crypto Trends" (2025), e la letteratura sul momentum temporale.
- **Universo**: coppie spot in EUR dell'exchange configurato, quotate da almeno 400 giorni, con volume mediano a 30 giorni sopra 250.000 € e spread mediano a 30 giorni sotto 20 punti base (lo campiona il bot ogni ora; finché non ha 30 giorni di campioni vale lo spread del momento); esclusi stablecoin, token "wrapped" e a leva. Le prime 10 per volume (meno, se meno superano i filtri), ricalcolate il primo giorno di ogni mese. Le coppie in USDC non si usano. Una moneta in portafoglio che esce dall'universo resta gestita fino all'uscita del suo segnale, senza nuovi acquisti.
- **Storia per il backtest**: le coppie in EUR di OKX partono da novembre 2023. Per gli anni precedenti usa gli archivi Binance in USDT convertiti in euro con il cambio del giorno, e dichiaralo nel rapporto come approssimazione. Su quello storico i filtri di spread e di volume in euro non si possono calcolare, e l'universo sono le prime 10 monete per volume in USDT. Per questo il protocollo di 12.2 deve passare due volte: sull'universo ampio e sul solo insieme BTC, ETH e SOL, le tre coppie in EUR con la liquidità migliore (4.2).
- **Decisione**: una volta al giorno sulla chiusura delle 00:00 UTC; gli ordini partono subito dopo. Nel backtest si eseguono all'apertura della candela successiva, con lo scostamento previsto. Un test verifica che l'ultima barra giornaliera usata chiuda davvero alle 00:00 UTC (4.2).
- **Segnale**: per ogni periodo N in {5, 10, 20, 30, 60, 90, 150, 250, 360} giorni si calcola un canale di Donchian sulle chiusure. Lo stato vale 1 dal giorno in cui la chiusura supera la più alta delle N chiusure precedenti. Lo stop mobile del periodo è il punto medio tra la più alta e la più bassa delle ultime N chiusure, giorno corrente compreso, e finché lo stato è attivo può solo salire; lo stato torna 0 quando una chiusura finisce sotto lo stop del giorno prima. Il segnale d'insieme `e` è la media dei nove stati, tra 0 e 1. Lo stato dipende dalla storia: si salva a ogni decisione; al primo avvio si ricostruisce ripercorrendo lo storico giornaliero con le regole del backtest, e dopo un'assenza riparte dallo stato salvato e ripercorre le barre mancanti.
- **Peso**: per ogni moneta il peso grezzo è `e × (15% / volatilità)`, con la volatilità annualizzata dei rendimenti giornalieri a 90 giorni (365 giorni l'anno): pesa meno la moneta più agitata e pesa meno il segnale più debole. Poi, nell'ordine: tetto per moneta (35% del capitale della strategia per BTC ed ETH, 20% per le altre); se la somma supera il 100%, tutti i pesi si riducono nella stessa proporzione; infine un fattore unico, mai sopra 1, riduce tutti i pesi se la volatilità stimata della strategia, calcolata dalla covarianza a 90 giorni, supera il 20% annuo. Ciò che tetti e fattore tagliano resta liquidità: non si ridistribuisce.
- **Ribilanciamento**: ogni giorno, ma si opera solo se lo scarto dal peso obiettivo supera il 20% del peso stesso e lo 0,5% del capitale della strategia. Le uscite complete si eseguono sempre.
- **Stop sul server**: uno per posizione, al livello a cui tutti i periodi attivi sarebbero usciti (il più basso dei loro stop mobili), comunque non oltre il 15% sotto l'ultima chiusura. Si ricalcola a ogni chiusura. Può scendere in un solo caso: quando si attiva un periodo in più, che porta con sé uno stop più basso, e mai se sullo strumento c'è un evento grave attivo (10.5). Altrimenti può solo salire. Se scatta durante la giornata, tutti gli stati di quella moneta tornano a 0: per rientrare serve un nuovo massimo. Il backtest applica la stessa regola usando il minimo della giornata.
- **Costi nel backtest**: 0,20% di commissione più 0,05% di scostamento per lato sulle principali, 0,15% sulle altre.
### 8.2 `equity_momentum` — le azioni americane più forti, solo quando il mercato sale
Riferimenti: letteratura sul momentum (Jegadeesh e Titman) e sui filtri di tendenza.
- **Universo** (a una certa data, vedi 6.7): azioni ordinarie quotate su NYSE e Nasdaq, negoziabili a frazioni su Alpaca, prezzo reale (non rettificato) sopra 10 $, almeno 300 sedute di storia, le prime 150 per controvalore mediano a 60 giorni. **Esclusi ETF, ETN e fondi.**
- **Punteggio**: media dei rendimenti a 63, 126 e 252 sedute, ciascuno calcolato saltando le ultime 5 sedute.
- **Filtro di mercato**: nuovi ingressi solo se SPY (usato come dato, non come strumento) chiude sopra la sua media a 200 giorni. Vale anche per gli aumenti di peso delle posizioni già aperte: con SPY sotto la media la strategia può solo vendere.
- **Ingressi**: il primo giorno di borsa della settimana, alle 09:35 di New York, compra i titoli tra i primi 12 della classifica non già in portafoglio, purché sopra la propria media a 100 giorni. Massimo 12 posizioni. Prima partono le vendite della revisione; gli acquisti partono man mano che le vendite sono eseguite, con la liquidità che il broker dichiara disponibile, e ciò che non entra si ritenta alla seduta successiva, entro i termini di 5.6. Nel backtest gli ingressi si eseguono all'apertura di quella seduta, con lo scostamento previsto.
- **Uscite alla revisione settimanale**: se il titolo esce dai primi 30 o scende sotto la media a 100 giorni.
- **Stop mobile**: 3 ATR(20) sotto la chiusura più alta raggiunta dopo l'ingresso (fino alla prima chiusura, sotto il prezzo d'ingresso); si ricalcola a ogni chiusura e può solo salire. È lo stop sul server di 7.2 (permanente sulle azioni intere, giornaliero sulle frazioni), aggiornato a ogni chiusura: scatta durante la seduta. Se una chiusura finisce sotto lo stop senza che l'ordine sia scattato, si vende all'apertura successiva. Nel backtest: se il minimo della seduta tocca lo stop si esce al prezzo dello stop, oppure all'apertura se questa è già sotto.
- **Peso**: i titoli in portafoglio dopo la revisione si dividono il capitale della strategia in proporzione inversa alla loro volatilità (60 sedute). Un fattore unico, mai sopra 1, riduce tutti i pesi se la volatilità stimata della strategia supera il 20% annuo. Tetto del 15% del capitale della strategia per titolo; ciò che il tetto taglia resta liquidità. Una posizione già aperta si ritocca solo se dista dal peso obiettivo più di un quarto del peso stesso.
- **Costi nel backtest**: nessuna commissione, 0,05% di scostamento per lato.
### 8.3 `equity_meanrev` — comprare i ribassi brevi dei titoli solidi
Riferimenti: letteratura sull'inversione di breve periodo; evidenza recente debole, per questo l'allocazione è piccola e i requisiti più severi.
- **Universo**: le prime 100 azioni dell'universo di 8.2 che chiudono sopra la propria media a 200 giorni.
- **Ingresso**: alla chiusura, RSI a 2 giorni sotto 10 e chiusura sotto la media a 5 giorni. Si comprano all'apertura successiva (09:35) i candidati con RSI più basso, fino a 3 posizioni contemporanee. Niente ingresso se la trimestrale cade nella seduta d'ingresso o nelle 3 successive, o è uscita dopo la chiusura della seduta precedente (quando il calendario è disponibile), e nemmeno se c'è una restrizione da notizie (10.5). Nel backtest il filtro sulle trimestrali è spento, perché il calendario storico non c'è: il rapporto lo dichiara.
- **Uscita**: alle 15:55 di New York se il prezzo è sopra la media a 5 giorni, se l'RSI a 2 giorni supera 70, se la trimestrale del titolo esce entro la chiusura della seduta successiva (quando il calendario è disponibile), oppure dopo 5 sedute. La verifica si fa ogni giorno, anche in quello d'ingresso. Dal vivo usa il prezzo delle 15:55 come se fosse la chiusura del giorno; nel backtest usa la chiusura. Nel conto delle 5 sedute quella d'ingresso è la prima: l'uscita a tempo avviene alla quinta. Stop sul server a 2,5 ATR(14) sotto il prezzo d'ingresso.
- **Dimensione**: rischio dello 0,4% del patrimonio di riferimento di 9.2 per operazione (distanza dallo stop), con tetto del 30% del capitale della strategia per posizione. Con le quote predefinite decide quasi sempre il tetto: da qui le 3 posizioni. Se il capitale libero della strategia non basta per un candidato, quel candidato si scarta.
- **Costi nel backtest**: 0,05% di scostamento per lato. La strategia è sensibile ai costi: vedi il requisito dedicato in 12.3.
### 8.4 Strategie candidate (solo ricerca e osservazione)
Implementale dopo le tre di base, senza capitale: servono a esercitare il percorso di 12.3.
- `stock_ath_breakout`: acquisto sui nuovi massimi storici con stop mobile a 10 ATR(42) (Zarattini, Pagani, Wilcox, 2025).
- `crypto_relative_momentum`: le 3 crypto più forti a 30 giorni tra le prime 10, solo con Bitcoin in tendenza. L'evidenza al netto dei costi è debole: se il protocollo la boccia, resta in archivio con l'esito.
### 8.5 Correttivi comuni
Agiscono dopo le strategie e **possono solo ridurre o bloccare, mai aumentare**. Ogni intervento lascia il suo codice motivo.
| Correttivo | Regola predefinita |
|---|---|
| Regime crypto | Se Bitcoin chiude sotto la media a 200 giorni o la sua volatilità è oltre il 90º percentile a 2 anni, i nuovi ingressi di `crypto_trend` sono dimezzati |
| Eventi in calendario | Nessun nuovo ingresso da 30 minuti prima a 30 minuti dopo un dato USA ad alto impatto; per le decisioni sui tassi di Fed e BCE fino a 60 minuti dopo |
| Notizie | Vedi 10.5 |
| Modello | Vedi 11: moltiplicatore tra 0 e 1, fissato quando l'operazione nasce, attivo solo dopo i requisiti |
| Perdite | Vedi 9.2: limiti giornalieri, settimanali e sul calo dal massimo |
Definizioni che valgono per tutti i correttivi e per i limiti di 9.2:
- **Ingresso** è ogni acquisto che aumenta l'esposizione, compresi gli aumenti di peso di una posizione già aperta.
- **Le riduzioni** ("dimezzati", "rischio dimezzato") sono moltiplicatori sulla dimensione degli acquisti. Non fanno vendere ciò che è già in portafoglio; se sono più d'una si moltiplicano tra loro; un acquisto ridotto non viene completato finché la riduzione è attiva.
- **Un ingresso bloccato da un evento in calendario** si ritenta alla fine della finestra, nella stessa seduta. Se la seduta finisce prima, si scarta con il suo codice motivo; `equity_momentum` lo ripropone alla seduta successiva della stessa settimana. Per le crypto, che non hanno sedute, vale la scadenza di 5.6: le 12:00 UTC dello stesso giorno.
### 8.6 Ripartizione del capitale
Il bot non può spostare denaro tra i conti. Il capitale di ogni strategia è quindi una quota del capitale affidato presso il suo broker (7.1): su OKX il 100% a `crypto_trend`; su Alpaca il 75% a `equity_momentum` e il 25% a `equity_meanrev`. Con 4.000 € su OKX e 6.000 € su Alpaca, come nei dati di esempio, fanno il 40%, il 45% e il 15% del totale: l'interfaccia mostra la quota sul totale. Quote modificabili dalle impostazioni, mai automaticamente.
Due regole valgono per tutte le strategie. Il capitale di una strategia è un tetto rigido: la somma delle sue posizioni non lo supera mai. Nello stesso conto uno stesso strumento può essere in portafoglio per una sola strategia alla volta: l'altra salta l'ingresso e ne registra il motivo.
### 8.7 Migliorie in osservazione
Modifiche che potrebbero migliorare il risultato o ridurre i costi. Nessuna parte attiva. Il bot le calcola in ombra accanto alle regole in vigore, registra l'effetto che avrebbero avuto e lo riporta nel Laboratorio e tra le scoperte di 11.6. Si attivano una per volta, dall'utente, solo dopo aver superato il protocollo di 12.2.
| Miglioria | Cosa si misura |
|---|---|
| Tetto di volatilità del portafoglio | Ridurre i nuovi ingressi quando la volatilità stimata dell'intero portafoglio supera il 12% annuo |
| Tetto per settore in `equity_momentum` | Al massimo 4 titoli dello stesso settore (codice SIC di SEC EDGAR) |
| Orario d'ingresso sulle azioni | Lo scostamento che si otterrebbe a 5, 15 e 30 minuti dall'apertura |
| Scelta dei candidati con il modello | In `equity_meanrev`, quando i candidati superano i posti liberi, preferire quelli con la probabilità stimata più alta anziché l'RSI più basso |
| Filtro di mercato per `equity_meanrev` | Entrare solo se SPY chiude sopra la sua media a 200 giorni |
---
## 9. Rischio
Il motore del rischio è un modulo indipendente: ogni ordine lo attraversa e nessuna strategia può aggirarlo. È la parte del sistema con la copertura di test più alta.
### 9.1 Divieti assoluti
Non sono impostazioni: sono invarianti verificate da test.
1. Nessuna leva e nessuna vendita allo scoperto.
2. Nessun prelievo o trasferimento: il codice non contiene chiamate a quegli endpoint.
3. Nessuna azione su posizioni non aperte dal bot.
4. Nessun passaggio a soldi veri senza la procedura di conferma (12.4).
5. Nessun aumento del rischio dopo una perdita: niente raddoppi, niente recuperi.
6. Nessun correttivo, modello o notizia può aumentare una dimensione oltre quella decisa dalla strategia.
### 9.2 Limiti (valori predefiniti, modificabili solo dall'utente)
| Limite | Soglia | Cosa succede se viene superato |
|---|---|---|
| Perdita in un giorno | −2% del patrimonio | Niente nuovi ingressi per 24 ore |
| Perdita in una settimana | −5% | Rischio dimezzato per sette giorni |
| Calo dal massimo | −10% e −15% | A −10% il rischio è dimezzato; a −15% scatta l'interruttore e si aspetta l'utente |
| Capitale investito | 100% | Nessun altro acquisto |
| Peso di una sola posizione | 20% del patrimonio | La posizione è ridotta alla soglia alla prima occasione utile |
| Crypto sul totale | 40% | Niente nuovi acquisti di crypto |
| Rischio di una singola operazione | 1% del patrimonio | L'ordine è rimpicciolito prima dell'invio |
| Ordini al minuto | 10 | Il bot si ferma e avvisa: può essere un guasto |
| Età dei prezzi | 60 secondi | Nessun nuovo ingresso sullo strumento finché i dati non tornano freschi |
| Prezzo dell'ordine | entro l'1% dall'ultimo prezzo valido | L'acquisto è rifiutato |
| Orologio | scarto oltre 2 secondi dall'ora del broker | Nessun nuovo ingresso finché non rientra |
Precisazioni:
- Il "giorno" va da mezzanotte a mezzanotte, ora italiana; la "settimana" sono gli ultimi sette giorni; il "massimo" è il patrimonio più alto raggiunto dall'avvio, o dall'ultima ripartenza confermata dopo uno scatto dell'interruttore (9.3), corretto per versamenti e prelievi, compresi i registri che entrano o escono da un mondo con un cambio di stadio (7.5). Il blocco per la perdita in un giorno dura 24 ore dallo scatto, non fino a mezzanotte: così copre anche la decisione notturna sulle crypto.
- **Base dei limiti**: perdite, calo dal massimo e capitale investito si misurano sul patrimonio del proprio mondo, soldi veri o simulazione (7.1); in più ogni strategia non supera mai il proprio capitale (8.6). Peso di una posizione, quota di crypto, rischio di una singola operazione e lo 0,4% di 8.3 si misurano invece sul **patrimonio di riferimento**, che non cambia quando una strategia cambia stadio: il capitale affidato su tutti i broker più i risultati delle strategie, gemelli simulati esclusi. Una strategia in reale ridotto lavora con un quarto del capitale: i suoi risultati entrano nel riferimento moltiplicati per quattro, e alle sue posizioni i limiti si applicano su un quarto del riferimento. I risultati già contati restano nel riferimento anche dopo un cambio di stadio: da lì si sommano quelli del nuovo registro. Così nessuna strategia cambia dimensioni perché un'altra cambia stadio. Finché tutto è in simulazione il riferimento coincide con il patrimonio; nel backtest di una sola strategia è il suo capitale diviso per la sua quota sul totale (8.6), o per la quota ipotetica scritta nel piano del test se è una candidata senza capitale.
- **Scatti automatici**: un limite superato blocca o ferma solo il mondo in cui è stato superato. Se la simulazione arriva a −15% si fermano le strategie in simulazione e quelle con soldi veri proseguono, e viceversa.
- **Preavviso**: quando la perdita del giorno, quella della settimana o il calo dal massimo superano l'80% della soglia parte un avviso su Telegram (uno per ogni superamento) e si registra un evento di rischio, senza alcun blocco.
- **Ordini al minuto**: contano, per ogni conto, gli acquisti e le vendite realmente inviati al broker, passi dell'inseguimento compresi. Il gestore degli ordini ne invia al massimo 6 al minuto (7.2), quindi arrivare a 10 è un'anomalia. Stop e vendite di protezione non contano.
- **Controlli tecnici** (età dei prezzi, prezzo dell'ordine, orologio): fermano solo gli ingressi. Gli stop si posano e si rimettono sempre; le uscite proseguono con una quotazione chiesta al momento via REST. Il controllo sul prezzo riguarda il limite degli acquisti. Lo scarto dell'orologio si misura a ogni collegamento e si compensa nelle firme delle richieste; oltre i 2 secondi il bot avvisa.
- **Rischio di una singola operazione**: è la perdita che si avrebbe se scattasse lo stop, calcolata sull'intera posizione dopo l'acquisto (quantità per distanza dallo stop). Un acquisto che la porterebbe oltre la soglia viene rimpicciolito. Nella tabella della schermata Rischio, "adesso" è la media del rischio fissato all'ingresso delle posizioni aperte.
- **Blocco e restrizione**: un blocco sospende i nuovi ingressi per tutto il bot o per un intero mercato (limite superato, evento in calendario, modalità prudente, interruttore). Una restrizione è una regola temporanea su un singolo strumento (notizie, trimestrali, dati fermi). La schermata Rischio mostra i blocchi e conta le restrizioni; il dettaglio delle restrizioni sta in Notizie e nel diario.
- Nella schermata Rischio la tabella mostra i primi nove limiti. Gli altri due controlli tecnici (prezzo dell'ordine, orologio) compaiono solo tra gli eventi, quando scattano.
- **Protezione day trade** (`pdt_guard`, spenta per impostazione predefinita): se il conto azionario risultasse ancora soggetto alla regola PDT, il bot conta le operazioni aperte e chiuse nella stessa seduta nelle ultime 5 sedute, comprese quelle chiuse da uno stop, che non si possono evitare. Con la protezione accesa `equity_meanrev` non esce mai nel giorno d'ingresso e resta protetta dal solo stop, e in ogni seduta il bot apre al massimo tante posizioni sulle azioni quante ne mancano per arrivare a 3 nel conteggio: così nemmeno una giornata di stop lo supera.
### 9.3 Interruttore d'emergenza
- **Metti in pausa**: niente nuovi ingressi; uscite e stop proseguono. Si riprende dall'interfaccia o con `/riprendi`.
- **Ferma tutto**: annulla gli ordini in attesa tranne gli stop di protezione, blocca ogni nuovo ingresso, lascia le posizioni protette; se annulla un ordine che aveva fatto togliere degli stop (una vendita in corso, o su Alpaca l'aumento di una posizione) li rimette subito. Finché resta attivo il bot non compra e non vende di sua iniziativa: continua solo a rimettere ogni giorno gli stop di protezione, ad alzarli quando la regola lo prevede e a vendere ciò il cui stop risulta già superato (7.2). Azionabile dall'interfaccia (sempre visibile in alto), da Telegram (`/ferma`), da un file `/data/STOP` e automaticamente dai limiti; lo scatto automatico ferma solo il mondo il cui limite è stato superato (9.2).
- **Ferma e chiudi tutte le posizioni**: azione separata, con conferma, che vende tutto ciò che è del bot con ordini a mercato. Lo stop di ogni posizione si annulla solo nel momento in cui parte la sua vendita. Ciò che appartiene a un mercato chiuso parte all'apertura e fino ad allora conserva i suoi stop.
- Per ripartire dopo "Ferma tutto" serve una conferma esplicita nell'interfaccia: nessun comando Telegram lo fa. Il riavvio del container o dell'applicazione non riarma da solo un interruttore scattato. Se lo scatto veniva dal calo dal massimo, alla conferma il massimo di riferimento riparte dal patrimonio del momento (9.2): altrimenti l'interruttore riscatterebbe subito.
- **Processo di guardia**: fa da genitore al motore. Lo avvia, ne ascolta il battito e riceve da lui, in memoria, le credenziali dei broker; il motore tiene aggiornato per lui un file di stato con posizioni, livelli di stop e ordini in attesa. Interviene in due casi: il ciclo principale tace per 2 minuti dopo un avvio riuscito, oppure i passi di 9.4 non avanzano per 10 minuti (la pagina d'errore non conta). Allora, in quest'ordine: termina il motore; legge dal broker le posizioni e l'esito degli ordini elencati nel file di stato; annulla acquisti e vendite rimasti in attesa; rimette solo gli stop che mancano e che non sono stati eseguiti, per la quantità che risulta ancora detenuta; avvisa su Telegram; riavvia il motore. Tocca gli ordini solo a motore fermo: da quando ripartono i passi di 9.4 non interviene più. Se il motore non riparte, avvisa ogni ora e ricorda che gli stop giornalieri sulle frazioni scadono a fine seduta. Non reagisce agli arresti voluti: inoltra al motore il segnale di arresto del container, ne aspetta la chiusura ordinata e non lo riavvia, e il motore gli annuncia ogni fermata decisa da lui (uscita, importazione, ripristino, spostamento del database). Ignora gli intervalli in cui anche il suo orologio è saltato, come dopo una sospensione del computer. In Docker la guardia è il processo principale del container: il processo principale non si può terminare dall'interno, quindi il motore deve essere suo figlio. Su desktop la guardia è l'avviatore. Non scrive nel database: lascia una nota in un file, che il motore riporta nel diario alla ripartenza. Al terzo riavvio forzato in un'ora il motore riparte in "Ferma tutto".
### 9.4 Avvio e ripartenza
A ogni avvio: migrazioni (precedute da un salvataggio solo se ce ne sono da applicare), verifica dell'orologio, connessione ai broker, lettura delle azioni societarie (6.10), **riconciliazione completa**, annullamento degli acquisti e delle vendite rimasti aperti sul broker, verifica che ogni posizione abbia il suo stop per l'intera quantità (sul broker, oppure sorvegliato dal bot nelle ore in cui il broker non lo accetta), recupero dei dati mancanti. Solo dopo il motore riprende nella modalità in cui era: le uscite già decise ripartono subito, gli ingressi interrotti si ripropongono con le regole di 5.6, e agli altri lavori saltati si applica la stessa tabella. Se una migrazione fallisce il motore non parte: pagina d'errore, con il salvataggio appena fatto pronto per il ripristino. Se fallisce un altro passo: modalità prudente e avviso.
### 9.5 Scenari "Se succedesse domani"
Un calcolo semplice sulle posizioni del momento, mostrato nella schermata Rischio. Scenari predefiniti, modificabili dalle impostazioni: le crypto perdono il 20% in un giorno; le azioni USA perdono il 7%; le due cose insieme; il dollaro perde il 5% sull'euro.
- Colonna "senza stop": la variazione applicata all'intero valore delle posizioni coinvolte, in euro e in percentuale del patrimonio.
- Colonna "con gli stop": per ogni posizione la perdita minore tra quella dello scenario e la distanza dal suo stop; il totale si arrotonda ai 5 € ed è preceduto da "circa", perché uno stop non garantisce il prezzo.
- Lo scenario sul cambio si applica al valore del conto in dollari; gli stop non lo riducono.
---
## 10. Notizie, calendario e modello linguistico
### 10.1 Principio
L'evidenza dice che le notizie lette da un modello linguistico non danno a un privato un vantaggio sfruttabile per comprare e vendere: l'effetto si concentra su titoli piccoli e vendite allo scoperto e sparisce con i costi. Sono invece utili per **evitare guai**. Per questo in Anubis le notizie possono bloccare ingressi e far scattare avvisi, entrano nel modello come indizi, e non generano mai un acquisto.
### 10.2 Percorso di una notizia
1. **Raccolta**: flusso notizie di Alpaca (se incluso nel piano), feed RSS (4.4), comunicati SEC per i titoli in portafoglio. Intestazioni condizionali e pause tra le richieste. Ogni fonte ha un'etichetta "affidabile" modificabile dalle impostazioni: in partenza lo sono le fonti ufficiali (Fed, BCE, SEC), Alpaca News, CNBC, MarketWatch, CoinDesk, Il Sole 24 Ore e ANSA.
2. **Pulizia e deduplica**: normalizza, elimina i doppioni per URL e per somiglianza del titolo, raggruppa le riprese della stessa notizia e conta le fonti indipendenti.
3. **Collegamento agli strumenti**: dai simboli forniti dalla fonte e da un dizionario di nomi (società, monete, temi macro). Una notizia può riguardare uno strumento, una classe di strumenti o il mercato in generale.
4. **Primo giudizio, locale e gratuito**: tono (negativo, neutro, positivo) con il classificatore di 4.5, più regole su parole chiave per i casi gravi (attacco informatico, sospensione, frode, fallimento, indagine, revoca dalla quotazione). Il tono si mostra in cinque gradi dal punteggio (probabilità di positivo meno probabilità di negativo): fino a −0,6 negativa, fino a −0,2 leggermente negativa, fino a +0,2 neutra, fino a +0,6 leggermente positiva, oltre positiva. Il classificatore giudica solo i testi in inglese: i titoli in italiano passano dalle parole chiave (elenco in due lingue) e, se configurato, dal modello linguistico. L'importanza senza modello linguistico: 4 ai casi gravi riconosciuti dalle parole chiave; 3 a una notizia negativa (punteggio fino a −0,6) o a un evento in calendario che riguarda uno strumento in portafoglio o candidato; 2 alle altre notizie collegate a uno strumento; 1 al resto. Il 5 lo assegna solo il modello linguistico.
5. **Secondo giudizio, facoltativo**: solo le notizie che riguardano strumenti in portafoglio o candidati all'ingresso, se il modello linguistico è configurato e il tetto di spesa non è esaurito. Risposta in JSON con schema fisso (appendice B): strumenti, tipo di evento, direzione, importanza da 1 a 5, confidenza, se è una voce non confermata, riassunto di una riga in italiano. L'importanza finale è la più alta tra quella del primo giudizio e quella del modello: il modello può aggiungere una restrizione, mai toglierla. Degli strumenti che indica si accettano solo quelli già collegati al punto 3. Il riassunto si mostra come testo semplice, senza indirizzi né formattazione, al massimo 160 caratteri.
6. **Stato per strumento**: tono medio a 1 e 3 giorni con decadimento, numero di notizie rispetto alla norma, evento più grave attivo.
### 10.3 Regole di sicurezza per il modello linguistico
- Il testo delle notizie è **dato non attendibile**: può contenere istruzioni malevole. Il modello non ha strumenti, non vede chiavi né posizioni oltre al nome degli strumenti, e la sua risposta viene accettata solo se rispetta lo schema. Una risposta non valida si scarta.
- Il suo giudizio passa sempre dalle regole di 10.5: non può comprare, vendere o cambiare un limite.
- Tetto di spesa giornaliero configurabile (predefinito 0,50 €), risposte in cache per hash del contenuto, richieste raggruppate. Esaurito il tetto resta il solo classificatore locale.
- Il sistema deve funzionare per intero **senza** modello linguistico.
- Nei backtest non usare mai il giudizio di un modello linguistico su notizie precedenti alla sua data di addestramento: le ricorda. Le sue valutazioni contano solo dal vivo.
### 10.4 Calendario e umore
- Eventi economici della settimana con orario e impatto; date delle trimestrali per i titoli seguiti, se la chiave è presente.
- Indicatori d'umore, usati come indizi dal modello: indice di paura e avidità delle crypto, VIX, tasso di finanziamento e open interest di Bitcoin dai dati pubblici di OKX. L'interfaccia mostra i primi tre. Etichette: paura e avidità da 0 a 24 paura estrema, fino a 44 paura, fino a 55 neutro, fino a 75 avidità, oltre avidità estrema; VIX sotto 20 calmo, fino a 30 nervoso, oltre panico; finanziamento entro ±0,02% ogni 8 ore nella norma, oltre "troppi al rialzo" o "troppi al ribasso".
### 10.5 Come le notizie influenzano il bot
| Situazione | Effetto |
|---|---|
| Evento grave e negativo su uno strumento (importanza 4 o 5), da una fonte affidabile o da due fonti indipendenti | Nessun nuovo ingresso su quello strumento per 72 ore; avviso su Telegram; se lo strumento è in portafoglio, lo stop non viene allargato per nessun motivo |
| Notizia negativa di importanza 3, da una fonte affidabile o da due fonti indipendenti | Nessun ingresso né aumento su quello strumento per 24 ore. Le notizie solo leggermente negative non creano restrizioni |
| Notizia da una sola fonte non etichettata come affidabile | Nessuna azione finché una seconda fonte indipendente non la conferma; nuovo controllo dopo 2 ore |
| Trimestrale in arrivo | `equity_meanrev` non entra su quel titolo dalle tre sedute precedenti fino a quella della pubblicazione compresa. Se i conti escono a mercato chiuso, o se il calendario non dice l'orario, fino alla seduta successiva compresa |
| Dato macro ad alto impatto | Blocco degli ingressi da 30 minuti prima a 30 minuti dopo (60 dopo le decisioni di Fed e BCE) |
Se una notizia ricade in più righe vale la più restrittiva tra quelle di cui soddisfa le condizioni. Gli effetti su un singolo strumento sono restrizioni, non blocchi (9.2), e ognuno finisce nel diario con il suo motivo. Un ingresso fermato da una restrizione si ritenta alla scadenza, entro i termini di 5.6, e resta comunque tra gli esempi di 11.2 con il suo esito simulato: la revisione trimestrale dice quanto le restrizioni hanno evitato e quanto sono costate, e ogni riga della tabella si può spegnere dalle impostazioni.
La vendita automatica per una notizia non è prevista: prima va dimostrato in osservazione che ridurrebbe le perdite (11.5).
---
## 11. Apprendimento automatico
### 11.1 Cosa impara e cosa no
Il modello **non prevede i prezzi** e non genera operazioni. Risponde a una sola domanda: "questo segnale della strategia, in queste condizioni, quanto è probabile che vada bene?" (meta-etichettatura). In base alla risposta può **rimpicciolire** l'operazione, fino a zero. Non può ingrandirla. Moltiplicatore predefinito: 1 se la probabilità calibrata è almeno pari alla frequenza di base della strategia, 0 se sta 0,10 o più sotto, proporzionale in mezzo. Così un modello che non sa nulla, e risponde sempre la frequenza di base, lascia tutto com'è. La frequenza di base è la quota di operazioni in guadagno di quella strategia nel backtest, aggiornata a ogni revisione trimestrale: le strategie di tendenza vincono meno di una volta su due, e una soglia fissa al 50% azzererebbe quasi tutte le loro operazioni. Il moltiplicatore si fissa quando l'operazione nasce e vale fino alla sua chiusura, aumenti di peso compresi.
Niente reti neurali profonde per i prezzi: su dati finanziari piccoli e rumorosi gli alberi potenziati restano lo stato dell'arte, e i grandi modelli pre-addestrati per serie temporali danno risultati peggiori del caso sui rendimenti azionari. Le reti neurali del sistema sono due, entrambe piccole: il classificatore delle notizie e, tra gli sfidanti, un percettrone di scikit-learn, che entra in carica solo se batte gli altri alle stesse regole.
### 11.2 Dati
- **Esempi**: uno per ogni operazione potenziale, cioè per la prima intenzione di ingresso di una strategia su uno strumento che non ha in portafoglio, **anche se poi non viene eseguita** e anche per le strategie in osservazione. Aumenti di peso e riproposte dello stesso ingresso non creano esempi nuovi. Ogni esempio salva le condizioni note in quel momento. In questa sezione e nell'interfaccia "segnale" e "caso" sono sinonimi di esempio.
- **Etichetta**: 1 se l'operazione, simulata a dimensione piena con le regole d'uscita e lo stop della sua strategia e al netto dei costi, chiude in guadagno; 0 altrimenti. Si calcola allo stesso modo per le operazioni eseguite, ridotte o mai eseguite: così non dipende dalle scelte passate del modello. È nota solo quando l'operazione simulata si chiude, e un esempio non etichettato non entra mai nell'addestramento.
- **Indizi** (tutti calcolati con dati fino all'istante della decisione): strategia, forza del segnale, distanza dallo stop, volatilità recente e suo rapporto con quella lunga, volumi rispetto alla norma, regime del mercato, ampiezza (quota di titoli sopra la media), tono e numero delle notizie a 1 e 3 giorni, evento più grave attivo, paura e avidità, VIX, finanziamento e open interest di Bitcoin, giorno della settimana, giorni alla trimestrale. Ogni indizio vale com'era noto in quell'istante, tenendo conto dell'ora di pubblicazione: per i dati giornalieri (VIX, paura e avidità) l'ultimo valore già uscito. Un indizio di cui non si può ricostruire la storia resta fuori dal modello finché non ci sono almeno 200 esempi dal vivo che lo contengono; il controllo della deriva confronta solo gli indizi in uso.
- **Un solo modello per tutte le strategie**, con la strategia tra gli indizi: i casi di una sola strategia sarebbero troppo pochi.
- **Partenza**: il primo modello si addestra sugli esempi ricostruiti facendo girare le strategie sullo storico (senza indizi da modello linguistico).
### 11.3 Addestramento e scelta
- Modelli: regressione logistica (riferimento), LightGBM (principale, pochi indizi e regolarizzazione forte), percettrone (sfidante).
- Convalida con finestre che avanzano nel tempo e con K-fold "purgato" con embargo (`CombinatorialPurgedCV` di `skfolio`): mai mescolare esempi sovrapposti nel tempo tra addestramento e verifica.
- Probabilità calibrate (isotonica o Platt) su dati fuori campione.
- Il giudizio non è l'accuratezza, ma **quanto migliora il guadagno medio per operazione proposta**, fuori campione: la somma dei risultati, ciascuno pesato dal moltiplicatore, divisa per il numero di operazioni proposte e non per quelle rimaste. Così un modello che scarta quasi tutto non può sembrare migliore. Si calcola sulle sole strategie con capitale: azzerare i segnali di una candidata in osservazione non è un merito.
- **Precisione**, che l'interfaccia chiama "previsioni azzeccate": la media di due quote, quella delle operazioni finite in guadagno che il modello aveva stimato pari o sopra la frequenza di base e quella delle operazioni finite in perdita che aveva stimato sotto. Chi tira a caso, o risponde sempre allo stesso modo, si ferma al 50%.
- Ogni tentativo viene registrato: il numero di prove conta nella valutazione (12.2).
### 11.4 Ciclo continuo
- **Ogni notte**: si etichettano gli esempi maturati, si aggiornano precisione e calibrazione dal vivo, si controlla la deriva (ADWIN sull'errore; confronto delle distribuzioni degli indizi).
- **Ogni domenica**: se non c'è uno sfidante in prova se ne addestra uno su tutti i dati; se c'è, si guarda a che punto è: la decisione di promuoverlo o scartarlo si prende solo alle soglie indicate sotto. C'è un solo sfidante per volta: gira in ombra accanto al modello in carica e durante la prova non viene riaddestrato.
- **Promozione automatica e prudente**: lo sfidante sostituisce il modello in carica solo dopo almeno 100 casi di confronto diretto fuori campione e con un vantaggio distinguibile dal caso (differenza di log-loss a coppie, intervallo bootstrap a blocchi al 95% che esclude lo zero). La decisione si prende solo nella verifica domenicale in cui i casi hanno superato una nuova soglia tra 100, 150, 200, 250 e 300: decidere più spesso moltiplica le promozioni dovute al caso. Dopo 300 casi senza vantaggio viene scartato. Ogni promozione viene notificata e si può annullare con un clic.
- **Messa da parte automatica**: se la precisione dal vivo scende sotto il 50% su almeno 40 casi o scatta un allarme di deriva, il modello smette di influire (moltiplicatore 1) finché non rientra. Le strategie proseguono senza di lui.
- **Perdite e guadagni maturano in tempi diversi**: le perdite si chiudono prima dei guadagni, quindi tra gli esempi appena etichettati le perdite sono troppe. Nelle misure che decidono qualcosa (attivazione, promozione, guadagno medio) ogni esempio si pesa in modo che guadagni e perdite contino nella proporzione della frequenza di base della sua strategia, non in quella maturata finora. La precisione, che li pesa già alla pari, non ne ha bisogno.
### 11.5 Quando comincia a contare
Il modello resta **in osservazione** finché non ha valutato almeno 300 segnali dal vivo con una calibrazione accettabile (errore medio di calibrazione sotto 0,05, misurato sulle fasce con almeno 20 casi) e un miglioramento confermato (il guadagno medio per operazione proposta di 11.3 supera quello senza filtro, con un intervallo bootstrap al 90% della differenza che esclude lo zero). Il conteggio dei 300 segnali è del sistema, non della versione: una promozione non lo azzera, e calibrazione e miglioramento si misurano sulle stime che erano in carica al momento di ogni segnale. Fino ad allora il modello registra le proprie stime accanto a ogni operazione senza cambiarla. Lo stesso vale per ogni nuova regola basata su notizie: prima si misura in osservazione quanto avrebbe aiutato, poi si attiva.
### 11.6 Altri apprendimenti semplici
- **Scostamento**: una regressione mensile sulle esecuzioni ottenute da un broker (conto reale o conto di prova, mai il simulatore interno, che restituirebbe la propria ipotesi) propone nuove stime per simulatore e backtest. In automatico una stima può solo salire; un ribasso si applica solo se lo conferma l'utente dal Laboratorio, e solo se viene da esecuzioni con soldi veri. Nei requisiti di 12.3 "previsto" resta comunque il valore del rapporto di qualifica.
- **Impatto delle notizie**: per ogni tipo di evento si misura il rendimento medio nei giorni successivi. La tabella è informativa e compare tra le scoperte: da sola non cambia né le importanze di 10.2 né le regole di 10.5.
- **Scoperte in chiaro**: il sistema riporta in italiano le relazioni più solide, con numero di casi e un giudizio sull'affidabilità: meno di 20 casi "troppo pochi per fidarsi", da 20 a 99 "un indizio discreto", da 100 in su "conclusione solida".
---
## 12. Backtest, validazione e percorso verso i soldi veri
### 12.1 Motore
A eventi, sulle stesse classi `Strategy`, sugli stessi correttivi e sullo stesso motore del rischio usati dal vivo. Modella commissioni, scostamento, ritardo, arrotondamenti e minimi. Riproducibile: stessi dati e stessi parametri danno lo stesso risultato. I correttivi che non hanno una storia ricostruibile (notizie, calendario economico, trimestrali, modello) nei backtest storici non ricevono dati e quindi non intervengono, e il rapporto lo dichiara; regime e limiti di rischio restano attivi. Dove quei dati esistono, come nei test con dati registrati, il motore li applica come dal vivo. Il motore sa anche ripartire da uno stato registrato dal vivo e calcolare un solo ciclo di decisione: serve al confronto di coerenza di 12.3.
### 12.2 Protocollo anti-illusioni
Si applica a ogni strategia, parametro o modello prima di farlo avanzare.
1. Regole e griglia dei parametri scritte **prima** di guardare i risultati; ogni prova registrata.
2. Dati "a una certa data" e senza guardare avanti. Test automatico: il segnale del giorno t non deve cambiare se si aggiungono dati successivi a t.
3. Costi realistici, poi doppi e tripli: una strategia che muore al doppio dei costi non passa.
4. Convalida a finestre che avanzano più K-fold purgato combinatorio. Si riportano Sharpe corretto per il numero di prove (Deflated Sharpe Ratio) e probabilità di sovra-adattamento (PBO).
5. Si preferiscono le zone di parametri dove il risultato cambia poco agli scelti "migliori".
6. Rapporto finale con: rendimento, volatilità, calo massimo, rapporto guadagni/perdite, numero di operazioni, risultato per anno, confronto con comprare e tenere, sensibilità ai costi.
Soglie predefinite per superare il protocollo: risultato netto positivo anche a costi doppi; DSR almeno 0,90; PBO non oltre 0,40 quando si confrontano più varianti; calo massimo non oltre il 25%. Per `crypto_trend` il protocollo deve passare su entrambi gli universi di 8.1. Le soglie si fissano prima di lanciare i test: cambiarle dopo aver visto i risultati richiede un ADR.
**Revisione trimestrale**: ogni tre mesi il bot rifà da solo i backtest delle strategie attive con i dati nuovi, li confronta con il comportamento dal vivo e pubblica il rapporto nel Laboratorio. Nella stessa occasione riprova le strategie di base rimaste in osservazione e aggiorna le frequenze di base di 11.1.
Implementa DSR e PBO in casa con test su casi noti: non ci sono librerie mantenute e affidabili che li offrano entrambi. I casi noti sono gli esempi numerici degli articoli originali di Bailey e López de Prado e alcune serie sintetiche di cui si conosce l'esito: su strategie di puro rumore la PBO sta intorno a 0,5; con una variante costruita per dominare scende verso 0.
### 12.3 Stadi di una strategia
`osservazione` (solo segnali) → `simulazione` (ordini finti su prezzi veri, o conto di prova) → `reale ridotto` (soldi veri, con un quarto del capitale della strategia: pesi, tetti e soglie restano gli stessi e si applicano a quel quarto) → `reale`.
Al primo avvio le tre strategie di base partono in simulazione se nella Fase 5 hanno superato il protocollo di 12.2: l'esito viaggia con il codice, in un file versionato di `docs/backtests/` (dati usati, parametri, metriche) che il primo avvio carica nel Laboratorio. Una strategia di base che non lo supera parte in osservazione, l'interfaccia dice perché, e viene riprovata a ogni revisione trimestrale. "Archiviata" non è uno stadio: indica una candidata di 8.4 bocciata dal protocollo, tenuta solo come documentazione.
Requisiti per passare da simulazione a reale ridotto, tutti verificati automaticamente e mostrati nell'interfaccia:
| Requisito | Valore |
|---|---|
| Giorni in simulazione | almeno 60 |
| Operazioni chiuse | almeno 8 per `crypto_trend`, 10 per `equity_momentum`, 30 per `equity_meanrev` |
| Coerenza con il backtest | differenze sotto il 2% nel confronto a un passo: per ogni ciclo di decisione il backtest riparte dallo stato registrato dal vivo e ricalcola solo quel ciclo, con i dati definitivi. Si confrontano le intenzioni della strategia, prima di correttivi e controlli di rischio, per gli strumenti in portafoglio e per quelli su cui una delle due versioni propone un ingresso; un'intenzione è diversa se l'azione non coincide o se la dimensione differisce di oltre il 10%. L'effetto di correttivi e rischio si riporta a parte, senza soglia |
| Prezzi ottenuti | scostamento medio non oltre il doppio di quello previsto (nel simulatore interno è vero per costruzione: conta davvero nel conto di prova e con i soldi veri) |
| Incidenti | nessuno critico negli ultimi 30 giorni |
| Solo `equity_meanrev` | guadagno medio per operazione almeno doppio del costo stimato di andata e ritorno, e distinguibile dal caso: intervallo al 90% del guadagno medio tutto sopra lo zero. Il confronto con il costo si mostra sempre; la verifica statistica si fa a 30, 60, 120 e 240 operazioni chiuse, poi ogni 120 |
Non avanza una strategia che ha in corso una delle condizioni di retrocessione elencate sotto. È **critico** un incidente che ha tolto al bot il controllo di una posizione o del registro: posizione senza stop per più di 5 minuti a mercato aperto (fuori dalle finestre previste: tra l'apertura e la rimessa degli stop sulle frazioni, durante un acquisto o una vendita in corso), differenza di riconciliazione non spiegata, ordine duplicato, limite di 9.2 superato senza il blocco previsto, riavvio forzato dal processo di guardia. In questi requisiti e nelle condizioni di retrocessione "previsto" e "backtest" sono quelli del rapporto con cui la strategia si è qualificata: non si spostano quando 11.6 aggiorna le stime.
Da osservazione a simulazione: protocollo di 12.2 superato sui dati storici e almeno 90 giorni di segnali raccolti dal vivo. Una candidata bocciata dal protocollo va in archivio con il suo esito e non riceve capitale.
Da reale ridotto a reale: almeno 30 giorni in reale ridotto senza incidenti critici né condizioni di retrocessione, e conferma dell'utente con la procedura di 12.4.
**Retrocessione automatica** a simulazione, con avviso: calo massimo (in percentuale del capitale usato) oltre 1,5 volte quello del backtest, scostamento oltre il triplo del previsto, 20 sedute consecutive sotto il 5º percentile del percorso atteso, oppure una revisione trimestrale in cui, con le stime di costo aggiornate, la strategia non supera più il protocollo di 12.2. Il percorso atteso è la distribuzione dei risultati cumulati dal giorno della promozione, ottenuta ricampionando a blocchi i rendimenti giornalieri del backtest.
**Sola uscita**: una strategia retrocessa, o a cui l'utente revoca i soldi veri, non abbandona le posizioni reali. Resta sul conto reale in sola uscita: non apre e non aumenta nulla, ma uscite, stop e rimessa quotidiana degli stop proseguono finché ogni posizione reale è a zero. Intanto prosegue in simulazione sul registro che era del gemello, e i conteggi dei requisiti ripartono dal giorno della retrocessione. Se viene promossa di nuovo, le posizioni reali rimaste tornano sotto la gestione normale.
**Gemello simulato**: una strategia passata ai soldi veri continua a girare anche in simulazione, nell'ambiente in cui si è qualificata e con le stesse regole. La differenza tra i due risultati, in percentuale del capitale usato, dà un'idea di quanto costa l'esecuzione reale ed è una delle cifre della schermata Strategie; nei primi mesi risente anche del diverso punto di partenza dei due registri. Il gemello non entra nei totali mostrati né nel patrimonio di riferimento; i suoi ordini passano dagli stessi controlli e seguono i blocchi della strategia reale, non quelli della simulazione.
### 12.4 Conferma per i soldi veri
Solo dall'interfaccia, per singola strategia e singolo conto, con: requisiti tutti verdi, riepilogo di ciò che cambia (capitale usato, acquisti che partiranno al primo ciclo, limiti che valgono e su quale base), digitazione di una frase di conferma, password e, se attivo, codice a due fattori. Ogni conferma e ogni revoca finiscono nel registro delle modifiche. Nessun comando Telegram può attivare i soldi veri. Il controllo vale sull'API, non solo sulla schermata: l'endpoint richiede una riautenticazione recente e funziona solo se la configurazione d'avvio consente i soldi veri (`ANUBIS_ALLOW_LIVE=1` in Docker, `allow_live = true` su desktop: 15.1 e 15.6).
La stessa procedura serve per ogni modifica che può aumentare l'esposizione di una strategia già nel conto reale: capitale affidato, quote di 8.6, limiti di 9.2, passaggio da reale ridotto a reale. Ridurre non la richiede. Per queste modifiche non si rimisurano i requisiti del passaggio da simulazione a reale ridotto: valgono le condizioni proprie di ciascuna (per il passaggio a reale, i 30 giorni di 12.3) e l'assenza di condizioni di retrocessione in corso. Cambiare i parametri di una strategia in reale equivale invece a revocarla: riparte dalla simulazione con le regole nuove e deve superare di nuovo i requisiti, mentre le posizioni reali restano in sola uscita (12.3). L'interfaccia lo dice prima di salvare.
---
## 13. Interfaccia
### 13.1 Riferimenti grafici
In `docs/design/` ci sono gli screen di riferimento, un'immagine JPG per schermata. Guardane uno solo per volta, quando implementi quella schermata, e per i dettagli ritaglia la zona che ti serve: le immagini sono alte e a doppia densità (2880 pixel di larghezza per gli screen da 1440, 780 per quello del telefono).
| File | Schermata |
|---|---|
| `01-panoramica.jpg` | Panoramica |
| `02-conti-e-posizioni.jpg` | Conti e posizioni |
| `03-operazioni.jpg` | Operazioni, con una riga aperta sul "perché" |
| `04-strategie.jpg` | Strategie e requisiti |
| `05-notizie-e-mercato.jpg` | Notizie e mercato |
| `06-apprendimento.jpg` | Apprendimento |
| `07-rischio.jpg` | Rischio |
| `08-diario-e-sistema.jpg` | Diario e sistema |
| `09-panoramica-telefono.jpg` | Panoramica su telefono |
Le immagini fissano l'aspetto. Colori, caratteri e misure dei componenti sono nell'appendice C. I dati mostrati (numeri, date, titoli delle notizie, voci di diario) sono nell'appendice F, da cui vanno copiati; i testi fissi dell'interfaccia (titoli, didascalie, etichette, descrizioni delle strategie) si leggono dalle immagini, ritagliando la zona. Se nella cartella trovi anche `docs/design/html/`, sono gli stessi screen in HTML con stili in linea: usali per le misure esatte.
I numeri e le notizie negli screen sono **dati di esempio**. `make seed-demo` avvia l'applicazione in **modalità dimostrativa**: usa un database SQLite a parte, creato in una cartella temporanea e mai quello configurato; lo riempie con i dati dell'appendice F; tiene l'orologio fermo a venerdì 9 ottobre 2026, ore 08:21 italiane; non si collega ai broker. Serve a confrontare a occhio la tua interfaccia con gli screen. Dove l'appendice dà le righe (posizioni, operazioni, serie giornaliere, diario, notizie) si caricano quelle, e gli elenchi mostrano solo quelle; dove dà solo un totale o una statistica (contatori delle notizie, statistiche del modello, requisiti, risorse, stato del sistema con piattaforma e database) si carica il valore così com'è, da un file di aggregati che solo questa modalità legge. Le serie per conto e per strategia non sono fornite: generale in modo che finiscano sui valori indicati. In modalità dimostrativa il piè di pagina lo dichiara, come negli screen. In produzione l'interfaccia non mostra mai dati finti: dove non c'è nulla, lo dice e spiega cosa fare.
Per ogni schermata: implementa, apri con Playwright sui dati dimostrativi a 1440 e a 390 pixel di larghezza, fotografa, confronta con lo screen zona per zona, elenca le differenze e correggile. Ripeti finché restano solo differenze trascurabili. Gli screen sono costruiti per essere fluidi: a 390 pixel il contenuto si impila in una colonna dentro il guscio del telefono (13.4).
Schermate senza screen, da disegnare con gli stessi componenti e lo stesso tono: **Laboratorio** (elenco dei backtest, avvio di un nuovo test, rapporto di 12.2, confronto tra due test, migliorie in osservazione di 8.7, stime di costo da confermare di 11.6), **Impostazioni** (13.5), **Accesso**, **Primo avvio** (procedura guidata: database, password, conti, capitale affidato, Telegram; i primi due passi cambiano con la piattaforma: in Docker il database è già scelto e la procedura lo mostra soltanto, e la password iniziale va sostituita al primo accesso; su desktop si scelgono entrambi: 15.1 e 15.6) e la **pagina d'errore** quando il database manca o non è raggiungibile.
### 13.2 Principi
1. **La Panoramica risponde a tre domande, in quest'ordine**: sto guadagnando o perdendo? cosa sta facendo il bot? i conti stanno bene? Il blocco in alto è diviso in due metà: "Finora" (il risultato, guardando indietro) e "Adesso e dopo" (cosa sorveglia, le prossime mosse con l'orario, le ultime azioni).
2. **Il colore significa qualcosa, non decora.** Verde-petrolio per i guadagni, rosso-vermiglio per le perdite, ambra per ciò che richiede attenzione, tre tinte fisse per le tre strategie. Tutto il resto è inchiostro su carta chiara. Un'informazione non è mai affidata al solo colore: sempre segno, freccia o parola insieme.
3. **Il bot parla in prima persona**: al presente per ciò che fa ("Sorveglio 10 posizioni", "Rimetto gli stop del giorno"), al passato nelle spiegazioni ("Perché l'ho comprata"). Le voci del diario e le ultime azioni usano la forma breve, senza soggetto: "Alzato lo stop di BTC", "Venduta 1 MSFT". Mai sigle o termini da trader senza spiegazione.
4. **Ogni numero importante ha il suo termine di paragone**: il limite accanto al valore, il "senza bot" accanto al risultato, il numero di casi accanto a ogni percentuale statistica.
5. **Bordi sottili, niente ombre, niente gradienti.** Pannelli con filetto di un pixel e angoli arrotondati; sezioni secondarie senza riquadro, separate da un filetto scuro in alto.
6. **Stato sempre visibile in alto**: bot attivo, in pausa o fermo; ambiente (simulazione finché nessuna strategia usa soldi veri, poi soldi veri); valuta; pulsanti "Metti in pausa" e "Ferma tutto". Con i soldi veri l'etichetta dell'ambiente cambia colore e testo in modo inequivocabile.
### 13.3 Regole di scrittura e di formato
- Numeri all'italiana: virgola decimale, punto per le migliaia, simbolo di valuta dopo il numero con spazio non separabile (`1.299,84 €`), segno meno tipografico `−`, segno `+` sui risultati positivi. Centralizza tutto in `frontend/src/lib/format.ts` e testalo.
- Percentuali con una o due cifre decimali a seconda del contesto, mai più precise del dato. Le quote di un intero (ripartizione del patrimonio, peso degli indizi) si arrotondano con il metodo del resto più alto, così sommano sempre a 100.
- Date in forma breve e parlata ("Oggi 06:10", "Ieri 21:58", "mar 6 ott"), ora italiana.
- Maiuscola solo a inizio frase. Niente etichette tutte in maiuscolo.
- Pulsanti con il verbo dell'azione ("Metti in pausa", "Esporta CSV"). Gli errori dicono cosa è successo e cosa fare.
- Cifre tabellari nelle colonne; cifre proporzionali nei numeri grandi.
- Esportazioni CSV: separatore `;`, virgola decimale, UTF-8 con BOM, intestazioni in italiano.
### 13.4 Componenti e comportamento
- Menu verticale a sinistra, comprimibile alle sole icone, con lo stato ricordato. Su telefono: barra in basso con Panoramica, Conti, Diario, Rischio, Altro; la barra superiore mostra solo stato, ambiente e "Ferma tutto", mentre "Metti in pausa", valuta e le altre schermate stanno in "Altro".
- Panoramica su telefono (screen 09): risultato dall'avvio con le cifre di oggi, 7 e 30 giorni e il grafico; le prime due mosse del bot in programma (gli eventi del calendario qui non compaiono); i conti; le prime quattro posizioni per valore; due limiti (capitale investito, calo dal massimo). Il resto si raggiunge dai collegamenti. Le altre schermate, a 390 pixel, impilano il contenuto dei rispettivi mockup dentro lo stesso guscio.
- Aggiornamenti dal vivo via WebSocket, senza ricaricare e senza sfarfallii: quando arriva un dato nuovo il vecchio resta visibile fino alla sostituzione. Se il collegamento cade, un avviso discreto dice da quanto i dati sono fermi.
- Grafici: una sola scala per grafico (mai due assi verticali); linee di 2 pixel; griglia e assi appena visibili e mai tratteggiati; etichette dirette sull'ultimo punto; legenda quando le serie sono più di una; al passaggio del mouse un riquadro con i valori; ogni grafico ha una tabella equivalente raggiungibile.
- Tabelle: su schermi stretti scorrono dentro il proprio riquadro, la pagina non scorre mai in orizzontale.
- Accessibilità: elementi nativi (`button`, `a`, `input` con etichetta), tutto raggiungibile da tastiera con fuoco visibile, contrasto del testo almeno 4,5:1, rispetto di `prefers-reduced-motion`, area cliccabile di almeno 44 pixel su telefono.
- Tema chiaro e tema scuro con i token dell'appendice C. Aggiungi un test che calcola i contrasti dei token e fallisce sotto soglia: i sette colori di testo (principale, secondario, attenuato, collegamenti, guadagno, perdita, attenzione) almeno 4,5:1 sullo sfondo della pagina e sulla superficie dei pannelli; il bordo dei controlli almeno 3:1 sulla superficie dei pannelli, dove stanno sempre i campi di inserimento. Le tinte delle strategie non hanno soglia perché portano sempre il nome accanto.
- Carattere: Instrument Sans, servito dall'applicazione stessa (pacchetto npm `@fontsource-variable/instrument-sans`; niente richieste a server esterni a runtime).
### 13.5 Impostazioni
Conti e chiavi (mai rimostrate dopo il salvataggio; verifica automatica che la chiave non abbia il permesso di prelievo); modalità e attivazione dei soldi veri; capitale affidato e ripartizione; limiti di rischio e scenari; parametri principali delle strategie (gli altri in una sezione avanzata); notizie (fonti, regole di 10.5, chiave del modello linguistico, tetto di spesa); calendario (riunioni delle banche centrali, chiavi di FRED e di Finnhub); modello (soglie del moltiplicatore, messa da parte a mano, annullamento dell'ultima promozione); Telegram e segnale di vita (con pulsante di prova); aspetto (tema, valuta); sicurezza (password, due fattori); dati (importazione CSV, salvataggi, esportazione per la dichiarazione); sistema (piattaforma, motore del database e cartella dei dati, in sola lettura in Docker; esportazione e importazione; su desktop anche lo spostamento su un altro database e le opzioni di 15.6: accesso dalla rete, computer sveglio, avvio automatico; versione, registri tecnici). Ogni modifica è registrata con data, valore precedente e nuovo. Un valore che arriva dalla configurazione d'avvio prevale su quello salvato e compare in sola lettura, con l'indicazione di dove si cambia. Le modifiche che possono aumentare l'esposizione di una strategia in reale passano da 12.4.
### 13.6 Cosa mostra ogni schermata
I mockup fissano l'aspetto; questa tabella fissa il contenuto e le regole di calcolo.
| Schermata | Contenuto e regole |
|---|---|
| Barra superiore, in tutte | Titolo e riga di stato. Pillola del bot: attivo, in pausa, fermo; se uno scatto automatico ha fermato un solo mondo (9.2) lo dice per nome, "Simulazione ferma" o "Soldi veri fermi". Pillola della modalità: "Simulazione: nessun soldo reale" finché nessuna strategia usa soldi veri (vale sia per il simulatore interno sia per i conti di prova); "Soldi veri" nel colore dell'attenzione appena una lo fa. Valuta di visualizzazione. "Metti in pausa" blocca i nuovi ingressi e lascia stop e uscite; "Ferma tutto" è l'interruttore di 9.3 |
| Panoramica | "Finora": risultato in euro e in percentuale per il periodo scelto (dall'avvio, 30 giorni, 7 giorni, oggi), al netto dei costi e corretto per i versamenti; confronto "senza bot" (7.5); grafico del patrimonio contro il confronto. Se il risultato è negativo la frase diventa "Sei in perdita di". "Adesso e dopo": frase di stato, prossime mosse prese dal pianificatore e dal calendario con il loro orario, ultime azioni dal diario. Sotto: una scheda per conto, i quattro limiti principali (perdita di oggi, calo dal massimo, capitale investito, posizione più grande), le posizioni aperte in ordine di valore, le strategie con stadio e avanzamento, tre notizie (prima quelle con un effetto in corso, poi le più recenti sulle posizioni o sui loro mercati), lo stato del modello e del sistema. Quando convivono soldi veri e simulazione vale 7.1 |
| Conti e posizioni | Totali e ripartizione per strategia. Per conto: patrimonio, liquidità, investito, guadagni incassati e aperti, commissioni, modalità, permessi della chiave, esito dell'ultima riconciliazione (per il simulatore interno, la coerenza del registro). Tabella delle posizioni con esportazione. Ordini in attesa. Residui invendibili, se ce ne sono (7.2). Quando c'è una differenza non spiegata, la scelta di 7.4. Esposizione per valuta, con l'effetto del cambio (7.5) quando è diverso da zero |
| Operazioni | Rapporto tra guadagni e perdite ("per ogni euro perso ne ha guadagnati…": somma dei guadagni divisa per la somma delle perdite), quota di operazioni in guadagno, guadagno medio, perdita media, commissioni. Grafico a barre con il risultato di ogni operazione in ordine di tempo. Filtri e tabella. Ogni riga si apre sul "perché", generato dai codici motivo: ragione dell'ingresso e dell'uscita, rischio, notizie, stima del modello, scostamento, commissioni, prezzo durante l'operazione |
| Strategie | Il percorso a quattro stadi di 12.3. Per strategia: descrizione in parole semplici, regole principali, conto e capitale, risultato, calo peggiore, operazioni, ogni requisito con il suo stato, pulsante di avanzamento attivo solo con i requisiti tutti soddisfatti; per chi è in reale, la differenza dal gemello simulato e l'eventuale stato di sola uscita (12.3). In fondo le strategie in osservazione e quelle archiviate |
| Notizie e mercato | Elenco "cosa ho letto e cosa ne ho fatto" sulle ultime 24 ore, con tre filtri (con effetto in corso, sulle tue posizioni, tutte): fonte, ora, strumento, titolo, tono, importanza, azione presa oppure motivo per cui non ha fatto nulla. Umore del mercato (10.4). Calendario con l'effetto previsto di ogni evento. Fonti con frequenza e stato. Spesa del giorno per il modello linguistico |
| Apprendimento | Stato (in osservazione, attivo, messo da parte) e avanzamento verso i 300 segnali. Precisione su casi mai visti. Calibrazione: stime raggruppate per fasce con il numero di casi; le fasce con meno di 20 casi sono dichiarate poco affidabili. Peso degli indizi, normalizzato a 100. Confronto tra modello in carica e sfidante. Sorveglianza, con la precisione settimana per settimana e la soglia d'allarme. Scoperte in chiaro (11.6). Storia delle versioni |
| Rischio | Interruttore. Blocchi attivi, prossimo in programma, ultimo scattato, numero di restrizioni su singoli strumenti (9.2). Tabella dei limiti: valore attuale, quota di soglia usata, conseguenza. Grafico del calo dal massimo. Scenari (9.5). Divieti fissi (9.1). Eventi di rischio: limiti superati, preavvisi, restrizioni per dati fermi, ordini rifiutati, differenze di riconciliazione, nuovo calo peggiore |
| Diario e sistema | Diario in ordine di tempo, con filtri per tipo e ricerca; le voci sugli ordini portano alla scheda "perché". Stato dei componenti: motore, flussi dei due conti, notizie, database con il motore in uso, Telegram. Lavori in programma. Risorse usate dal container o dal computer. Versione, piattaforma (Docker o desktop) e durata dell'attività. Scaricamento dei registri tecnici |
---
## 14. Telegram
- Messaggi: riepilogo del mattino; ogni acquisto e vendita con il risultato; avvisi di rischio; blocchi e sblocchi; promozioni e messe da parte del modello; errori che richiedono attenzione; stato periodico facoltativo (mai, ogni ora, ogni giorno).
- Comandi, accettati solo dalla chat autorizzata: `/stato`, `/posizioni`, `/oggi`, `/pausa`, `/riprendi`, `/ferma` (con richiesta di conferma), `/aiuto`.
- `/riprendi` fa ripartire solo da una pausa, mai dopo "Ferma tutto" (9.3).
- Nessun comando può attivare i soldi veri, cambiare limiti o mostrare segreti.
- **Segnale di vita** (facoltativo): se è configurato l'indirizzo di un servizio di controllo esterno (per esempio healthchecks.io, da verificare), il bot lo chiama ogni minuto. Quando le chiamate si fermano è quel servizio ad avvisare l'utente: è l'unico modo per sapere che il bot è spento quando è spento. Su desktop la procedura di primo avvio lo consiglia.
- **Non dichiarare mai inviata una notifica che non è partita**: ogni invio ha uno stato (inviato, fallito, in coda), i falliti vengono ritentati e l'interfaccia mostra l'ultimo invio riuscito.
---
## 15. Installazione, piattaforme, sicurezza, CI
### 15.1 Docker: configurazione del container
In Docker tutto ciò che serve all'avvio arriva da variabili d'ambiente, impostate nella configurazione del container (su Unraid, nei campi del template). **Motore e connessione del database si scelgono qui e solo qui**: l'interfaccia li mostra in sola lettura.
| Variabile | Uso |
|---|---|
| `ANUBIS_DB_ENGINE` | `postgres` oppure `sqlite`. Obbligatoria: se manca, il container mostra la pagina d'errore |
| `ANUBIS_DB_HOST`, `ANUBIS_DB_PORT`, `ANUBIS_DB_NAME`, `ANUBIS_DB_USER`, `ANUBIS_DB_PASSWORD` | Solo con `postgres`. Predefiniti: porta `5432`, nome `anubis`, utente `anubis` |
| `ANUBIS_DB_URL` | Facoltativa, per casi particolari: un indirizzo completo che sostituisce i cinque campi |
| `ANUBIS_SECRET_KEY` | Chiave con cui si cifrano i segreti nel database, almeno 32 caratteri. Obbligatoria; se cambia, i segreti salvati vanno reinseriti |
| `ANUBIS_ADMIN_PASSWORD` | Password iniziale. Vale al primo accesso, quando l'interfaccia chiede di sceglierne una nuova, e resta la chiave delle scelte della pagina d'errore. Obbligatoria |
| `TZ` | Fuso orario dell'utente: orari mostrati, "giorno" dei limiti di rischio, lavori di manutenzione. Predefinito `Europe/Rome` |
| `PUID`, `PGID` | Utente e gruppo a cui va la cartella dei dati e con cui gira l'applicazione (15.2). Predefiniti `99` e `100`, quelli di Unraid |
| `PORT` | Porta interna, predefinita `8787` |
| `ANUBIS_ALLOW_LIVE` | `0` per impostazione predefinita. Solo con `1` gli adapter accettano un conto reale e la procedura di 12.4 si può completare |
| `ANUBIS_HEARTBEAT_URL` | Facoltativa: indirizzo del segnale di vita (14) |
| `ALPACA_API_KEY`, `ALPACA_API_SECRET`, `OKX_API_KEY`, `OKX_API_SECRET`, `OKX_API_PASSPHRASE`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `LLM_API_KEY`, `FINNHUB_API_KEY`, `FRED_API_KEY` | Facoltative: alternative all'inserimento dall'interfaccia. Con il suffisso `_DEMO` per i conti di prova |
Con `sqlite` non serve altro: il file è `/data/db/anubis.sqlite3`. Una variabile facoltativa, se presente, prevale sul valore salvato dall'interfaccia, che la mostra in sola lettura.
Regole:
- **Configurazione mancante, incompleta o database irraggiungibile**: il container resta acceso, mostra una pagina d'errore che dice cosa manca e come rimediare, e riprova; il motore non parte. Mai ripiegare da soli su un altro database.
- Il bot crea da solo schema e tabelle in un database vuoto. Con PostgreSQL usa un database dedicato già creato dall'utente: non crea e non cancella database.
- **Identità dell'installazione**: al primo avvio nasce un identificativo, salvato sia nel database sia in `/data/installation.json`. Se a un avvio successivo i due non coincidono, oppure il database è vuoto mentre `/data` appartiene a un'installazione esistente, il motore non parte e la pagina d'errore fa scegliere all'utente tra ripristinare un salvataggio, importare un archivio o cominciare da capo. Queste scelte chiedono la password della configurazione d'avvio, perché utenti e sessioni stanno nel database che manca.
- **Dopo un'importazione o un ripristino il bot riparte protetto**: "Ferma tutto" attivo e ogni strategia che era nel conto reale da riconfermare; finché non lo è resta in sola uscita (12.3). La riconferma chiede password e secondo fattore e mostra il riepilogo di 12.4, ma non azzera i conteggi e non rimisura i requisiti. Prima di tutto il bot ricostruisce dal broker le esecuzioni successive all'archivio: il `client_order_id` dice a quale strategia e a quale ambiente appartengono (7.2). Solo dopo l'utente conferma la ripartenza. Senza questa regola un salvataggio vecchio riarmerebbe un interruttore scattato e riporterebbe in reale una strategia revocata.
- **Un solo database vivo per installazione**: ogni importazione, ripristino o spostamento genera una nuova impronta, scritta nel database di arrivo e in `/data/installation.json`. All'avvio il bot opera solo se le due impronte coincidono: un database vecchio, rimasto con l'impronta precedente, porta alla pagina d'errore. Due registri sullo stesso conto produrrebbero ordini doppi.
- Per cambiare motore: a motore fermo, esportazione e importazione di 5.4, poi nuova configurazione del container.
### 15.2 Container e cartella dei dati
- Immagine multi-stage: build del frontend, poi runtime Python slim. Ricorda `libgomp1` per LightGBM.
- L'applicazione gira come utente non privilegiato. L'entrypoint parte come root solo per creare `/data` e assegnarla a `PUID:PGID` (predefiniti 99 e 100, la convenzione di Unraid), poi abbandona i privilegi e avvia il processo di guardia, che a sua volta avvia il motore (9.3). Se il container è avviato con `--user`, salta il passo dei permessi.
- Volume unico `/data`, da mappare su `/mnt/user/appdata/anubis`, con questa struttura: `db/` (solo con SQLite), `models/`, `research/`, `import/`, `backups/`, `logs/`, `installation.json`.
- `HEALTHCHECK` su un endpoint che controlla database, ciclo del motore e flussi dei dati.
- Arresto ordinato: la guardia inoltra al motore il segnale di arresto (SIGTERM); il motore completa o annulla gli ordini in corso, rimette gli stop tolti per un ordine in lavorazione e salva lo stato. Il template concede 60 secondi.
- Uso di risorse previsto: sotto 2 GB di memoria e una frazione di CPU; nessuna GPU.
### 15.3 Unraid
`deploy/unraid/anubis.xml`, nel formato dei template Docker di Unraid (`<Container version="2">`). Parti dalla bozza dell'appendice E e sostituisci i segnaposto con il registry e l'utente reali. Requisiti:
- il database si sceglie da un campo a tendina (`Default="postgres|sqlite"`), seguito dai campi di PostgreSQL;
- ogni variabile della bozza compare una sola volta, con descrizione in italiano; i segreti hanno `Mask="true"`; i campi di uso raro (soldi veri, Telegram, segnale di vita, utente e gruppo, indirizzo completo del database) stanno tra quelli avanzati; le chiavi dei conti restano fuori dal template e si inseriscono dall'interfaccia;
- porta dell'interfaccia, cartella dei dati, limite di memoria e tempo di arresto come nella bozza;
- icona `deploy/unraid/anubis-icon.png`, ricavata dal segno dei due semicerchi degli screen;
- un test controlla che il file sia XML ben formato e che contenga le stesse variabili della bozza, ognuna presente anche in 15.1.
In `docs/MANUALE.md` spiega l'installazione passo per passo: dove copiare il template, come creare database e utente dedicati su PostgreSQL, come raggiungere un PostgreSQL che gira in un altro container dello stesso server (indirizzo IP del server e porta pubblicata, oppure nome del container su una rete personalizzata), quando conviene SQLite.
### 15.4 Sicurezza
- Accesso con password (hash Argon2id), sessione in cookie `HttpOnly` e `SameSite=Strict`, protezione CSRF, limite ai tentativi di accesso. Secondo fattore TOTP facoltativo, richiesto per attivare i soldi veri se configurato.
- Segreti cifrati nel database con una chiave che in Docker deriva da `ANUBIS_SECRET_KEY` e su desktop sta nel portachiavi del sistema operativo (15.6); mai nei log, mai restituiti dalle API.
- L'interfaccia è pensata per la rete di casa. Nel manuale scrivi chiaramente di non esporla su Internet senza un proxy con autenticazione. Su desktop ascolta solo sul computer stesso, salvo scelta contraria dell'utente.
- Registro delle modifiche per configurazione, attivazioni e interruttore.
### 15.5 CI
Flusso compatibile con Gitea Actions e GitHub Actions (stessa sintassi) in `.gitea/workflows/ci.yml`: lint, tipi, test del backend su entrambi i motori di database, test del frontend, build dell'immagine; solo sui tag di versione (`v*`, non sui tag `fase-N`), pubblicazione nel registry indicato da variabili (`REGISTRY`, `REGISTRY_USER`, `REGISTRY_TOKEN`). L'installatore desktop si costruisce in CI solo se esiste un esecutore Windows; altrimenti in locale. Se non c'è un remoto configurato lavora in locale e non tentare pubblicazioni: `make ci` esegue in locale gli stessi passi, ed è la prova che vale quando manca un esecutore.
### 15.6 Applicazione desktop
Stesso motore, stesse API, stessa interfaccia: cambia solo l'involucro.
- **Avviatore** (`desktop/launcher.py`): avvia il server su `127.0.0.1`, porta 8787 o la prima libera; apre l'interfaccia in una finestra propria (`pywebview`; se il componente di sistema manca, nel browser predefinito); mette un'icona nell'area di notifica (`pystray`) con le voci Apri, Metti in pausa, Ferma tutto, Esci. Una sola istanza per cartella dei dati. L'avviatore fa anche da processo di guardia (9.3).
- **Chiudere la finestra non ferma il bot**: resta nell'area di notifica, e la prima volta lo spiega. "Esci" chiede conferma se ci sono posizioni aperte e ricorda quali stop restano sul broker.
- **Cartella dei dati** (`platformdirs`): `%APPDATA%\Anubis` su Windows, `~/Library/Application Support/Anubis` su macOS, `~/.local/share/anubis` su Linux. Stessa struttura di 15.2.
- **Configurazione d'avvio**: `config.toml` nella cartella dei dati, scritto dalla procedura di primo avvio. Contiene motore e connessione del database (senza la password), porta, accesso dalla rete, fuso orario se diverso da quello del sistema, e la voce `allow_live`, equivalente di `ANUBIS_ALLOW_LIVE`, che nasce `false`: per accenderla l'utente deve modificare il file a mano, mai dall'interfaccia.
- **Database**: è il primo passo della procedura guidata. SQLite è la scelta predefinita (un file nella cartella dei dati, niente da installare); PostgreSQL è l'alternativa, con i campi di connessione e il pulsante "Prova la connessione". Per cambiare in seguito: Impostazioni, Sistema, "Sposta su un altro database", che ferma il motore, esporta, importa, verifica, rinnova l'impronta e riavvia. Valgono le regole di 15.1 su identità dell'installazione, impronta del database e ripartenza protetta.
- **Segreti**: la chiave che cifra i segreti nasce al primo avvio e sta nel portachiavi del sistema operativo (`keyring`), insieme alla password di PostgreSQL quando si usa quel motore. Mai in `config.toml`. Dove il portachiavi non esiste (una sessione Linux senza interfaccia, i test) si usa un file con permessi ristretti nella cartella dei dati, e l'interfaccia lo dichiara.
- **Accesso**: solo dal computer stesso. L'opzione "Consenti l'accesso dalla rete di casa" apre l'ascolto agli altri dispositivi, così il telefono può collegarsi. La password resta sempre obbligatoria. Le scelte della pagina d'errore (15.1) si possono fare solo dal computer stesso.
- **Sospensione e avvio**: opzione "Tieni sveglio il computer mentre ci sono posizioni aperte" (accesa in partenza) e opzione "Avvia insieme al computer".
- **Limite dichiarato**: su desktop il bot lavora solo a computer acceso. L'interfaccia lo dice al primo avvio e dopo ogni assenza applica 5.6. Per questo la procedura guidata consiglia il segnale di vita (14).
- **Confezione**: PyInstaller in modalità cartella e installatore Inno Setup per Windows 10 e 11 a 64 bit, con `make desktop-win` da eseguire su Windows, perché PyInstaller non compila per un sistema diverso da quello su cui gira. Su macOS e Linux: avvio da sorgente documentato (`uv run anubis-desktop`); pacchetti nativi solo se l'utente li chiede.
- **Aggiornamenti**: manuali, reinstallando. Le migrazioni partono da sole e prima fanno un salvataggio.
---
## 16. Test
| Tipo | Cosa copre |
|---|---|
| Unitari | Indicatori contro valori calcolati a mano; dimensionamento; ogni regola di rischio; formati numerici |
| Basati su proprietà (hypothesis) | Invarianti contabili: liquidità più valore delle posizioni uguale al patrimonio; nessuna sequenza di esecuzioni produce quantità negative; il rischio non lascia mai passare un ordine oltre i limiti |
| Anti-sguardo-avanti | Per ogni strategia: aggiungere dati futuri non cambia i segnali passati |
| Parità | Le decisioni del backtest e quelle del motore in simulazione sullo stesso periodo coincidono; il confronto a un passo di 12.3 rileva una differenza iniettata apposta |
| Integrazione | Catena completa con `PaperBroker`; adapter contro risposte registrate |
| Conformità degli adapter (`live_demo`) | Una stessa batteria per ogni adapter, eseguita sul conto di prova quando le chiavi ci sono: strumenti, ordine minimo, esecuzione parziale, annullamento, stop, aumento di una posizione che ha già i suoi stop, flussi, idempotenza |
| Simulazione con guasti | Disconnessione dei flussi, esecuzioni duplicate, ordini rifiutati, dati fermi, orologio sfasato, riavvio a metà ordine, database irraggiungibile, stop già superato al momento della rimessa, ciclo principale bloccato con una vendita a metà, avvio che non avanza, arresto voluto con ordini in corso, frazionamento di un titolo in portafoglio, ripristino di un salvataggio vecchio: il sistema resta in uno stato sicuro e riconciliato |
| Regressione dei backtest | Metriche "d'oro" su un insieme di dati fisso |
| Interfaccia | Vitest per componenti e formati; Playwright per i percorsi principali e gli screenshot |
| Due motori | Tutti i test del backend girano su SQLite e su PostgreSQL. Un test fa il giro completo di decimali, date e identificativi su entrambi; un altro esporta da un motore, importa nell'altro e confronta conteggi e totali contabili |
| Piattaforme | Avvio in Docker con ogni configurazione del database, comprese quelle sbagliate o incomplete; avvio dell'applicazione desktop in una cartella dati vuota e in una già usata; recupero dopo un'assenza (5.6) con orologio simulato |
Tutto il tempo passa da un orologio iniettabile: nessun test dipende dall'ora reale o dalla rete. I test `live_demo` sono esclusi dal giro normale.
---
## 17. Piano a fasi
Ogni fase ha un obiettivo, un elenco di lavori e criteri di accettazione verificabili. Riporta i criteri in `docs/ROADMAP.md` come checklist.
Sezioni da leggere per ogni fase, oltre a 2, 3, 16 e 19 che valgono sempre:
| Fase | Sezioni |
|---|---|
| 0 | 1, 4, 5.1, 15.5 |
| 1 | 5, 13.1–13.5, 15.1, 15.2, 15.4, 15.6, appendici C e F |
| 2 | 4, 5.3, 6, 10.4 |
| 3 | 4.1, 4.2, 5.3, 6, 7, 13.1–13.6 |
| 4 | 5.3, 8.7, 12.1, 12.2, 13.1–13.4 |
| 5 | 7.1, 7.5, 8, 9, 12, 13.1–13.6 |
| 6 | 5.5, 5.6, 7.4, 9.3, 9.4, 13, 14 |
| 7 | 4.4, 4.5, 5.6, 10, 13.1–13.6 |
| 8 | 5.6, 11, 13.1–13.6 |
| 9 | 4.6, 5.4, 8.4, 8.7, 10.5, 12.2–12.4, 15.1–15.5, 18, appendice E |
| 10 | 5.4, 5.6, 9.3, 13.1, 13.5, 15.1, 15.4, 15.6 |
Per ogni schermata servono anche l'appendice C (colori e misure) e l'appendice F (i dati mostrati).
Quattro cose attraversano le fasi. La schermata **Impostazioni** nasce nella Fase 1 con aspetto, sicurezza e sistema, e ogni fase vi aggiunge la propria parte: conti nella 3; strategie, limiti e scenari nella 5; Telegram nella 6; notizie e calendario nella 7; modello nella 8. La **procedura di primo avvio** nasce nella Fase 1 con database e password, e si completa con i conti nella Fase 3 e con Telegram nella Fase 6. Lo **strato di piattaforma** nasce completo nella Fase 1: configurazione d'avvio dalle variabili d'ambiente o da `config.toml`, cartella dei dati, custodia della chiave dei segreti. Fino alla Fase 10 il desktop si prova avviando lo stesso server con la configurazione desktop, senza finestra; la Fase 10 aggiunge finestra, area di notifica, opzioni del desktop, spostamento del database e confezione. Il **test di recupero dopo un'assenza** (5.6) nasce nella Fase 6 con i lavori che esistono allora, e le fasi 7 e 8 vi aggiungono i propri.
### Fase 0 — Preparazione
Lavori: leggi questa specifica; con subagent ricontrolla sulla documentazione corrente i fatti della sezione 4, un paragrafo per volta, e scrivi `docs/API-NOTES.md` segnalando ogni differenza; crea la struttura del repository, `CLAUDE.md`, `ROADMAP.md`, `STATE.md`, i primi ADR; configura `uv`, ruff, mypy, pytest, vitest, Playwright, pre-commit, `Makefile` (`check`, `dev`, `test`, `build`, `ci`), un'applicazione minima con il solo endpoint `/health`, un Dockerfile minimo, `docker-compose.yml` con Postgres, lo scheletro della CI con i test del backend su SQLite e su PostgreSQL.
Accettazione: `make check` passa su un progetto vuoto ma completo di toolchain; `docker compose up` avvia l'applicazione minima, che risponde su `/health`; `docs/API-NOTES.md` elenca per ogni fatto della sezione 4 "confermato", "cambiato" o "non verificabile"; `docs/STATE.md` dice quali chiavi serviranno e da quale fase (conto paper di Alpaca dalla Fase 2, demo di OKX dalla Fase 3).
### Fase 1 — Fondamenta
Lavori: strato di piattaforma con la configurazione d'avvio per Docker e per desktop (15.1, 15.6: variabili d'ambiente, `config.toml`, cartella dei dati, chiave dei segreti nel portachiavi), scelta del motore, identità dell'installazione; tipi portabili, modelli e migrazioni su entrambi i motori (5.4); esportazione e importazione; impostazioni e segreti cifrati; registri strutturati; orologio iniettabile, bus degli eventi, pianificatore con orari fissi e orari relativi ad apertura e chiusura (provato con un calendario finto: quello vero arriva nella Fase 2); salvataggio notturno e salvataggio prima delle migrazioni; autenticazione; scheletro delle API e del WebSocket; guscio dell'interfaccia (menu, barra superiore, temi, formati, pagina d'errore del database, accesso, primo avvio con i passi di database e password nelle due forme, Docker e desktop, prima parte di Impostazioni); modalità dimostrativa con i dati dell'appendice F e comando `make seed-demo` (13.1); Dockerfile definitivo con l'entrypoint di 15.2, che fino alla Fase 6 avvia direttamente il motore.
Accettazione: accesso funzionante; il guscio corrisponde ai mockup per menu e barra superiore a 1440 pixel e per barra superiore e barra in basso a 390 pixel (screenshot allegati); i formati numerici superano i test; l'immagine si costruisce e parte con `ANUBIS_DB_ENGINE=sqlite` e con `postgres`; con una configurazione mancante o sbagliata compare la pagina d'errore e non nasce alcun altro database; staccando il database compare la pagina d'errore e al ritorno l'applicazione riprende da sola; la stessa batteria di test passa su entrambi i motori; un archivio esportato da un motore e importato nell'altro dà gli stessi conteggi; con la configurazione desktop il server parte da una cartella dei dati vuota e la chiave dei segreti non finisce in `config.toml`; la modalità dimostrativa non tocca il database configurato (test).
### Fase 2 — Dati di mercato
Lavori: catalogo degli strumenti; la parte dati degli adapter di OKX Europe e di Alpaca (strumenti, barre, quotazioni, flussi); collector storico e dal vivo; recupero dei buchi; controlli di qualità; importatori (archivi Binance, CSV dell'utente) verso i file Parquet di 6.6; calendario di borsa; cambi; calendario economico e date delle trimestrali (10.4); azioni societarie e serie rettificate (6.10); universi "a una certa data" con esclusione degli ETF.
Accettazione: storico giornaliero delle crypto dall'inizio disponibile (coppie in EUR di OKX, più gli archivi Binance dal 2017) e delle azioni dal 2016; senza chiavi Alpaca la parte azionaria si prova su dati sintetici e sulle risposte d'esempio della documentazione, e il criterio resta in attesa dell'utente (2.3); un test stacca il flusso per 10 minuti e verifica che il buco venga recuperato; rapporto di qualità dei dati; l'elenco dell'universo azionario a tre date passate non contiene ETF.
### Fase 3 — Conti, ordini, contabilità
Lavori: la parte conti e ordini di `BrokerAdapter`; `PaperBroker`; OMS; ambienti e capitale affidato (7.1); registro, lotti, patrimonio, rendimento corretto per i versamenti; stop che seguono la quantità, stop già superato e residui invendibili (7.2); azioni societarie nel registro e negli stop (6.10); riconciliazione; adapter Alpaca (paper) e OKX (demo); batteria di conformità; schermata "Conti e posizioni"; parte di Impostazioni e del primo avvio che riguarda i conti.
Accettazione: i test di proprietà contabili passano; la batteria di conformità passa sul simulatore e, se le chiavi demo ci sono, sui due conti di prova (altrimenti su risposte d'esempio prese dalla documentazione, e il criterio resta in attesa dell'utente, 2.3); i test con guasti di questa parte passano; un test dimostra che gli adapter rifiutano un ambiente reale senza il consenso della configurazione d'avvio, in Docker e su desktop; la schermata corrisponde al mockup.
### Fase 4 — Backtest e laboratorio
Lavori: motore a eventi, con i punti d'innesto per correttivi e motore del rischio (arrivano nella Fase 5: fino ad allora lasciano passare tutto); modelli di costo; metriche; convalide (finestre che avanzano, K-fold purgato combinatorio, DSR, PBO); registro delle prove; rapporto; schermata "Laboratorio".
Accettazione: una strategia giocattolo con risultato noto dà esattamente il risultato atteso; il test anti-sguardo-avanti esiste e fallisce su una strategia volutamente scorretta; DSR e PBO riproducono i casi noti di 12.2; il rapporto si apre dall'interfaccia.
### Fase 5 — Strategie, portafoglio, rischio
Lavori: le tre strategie di base; correttivi di regime e di calendario; ripartizione e dimensionamento; motore del rischio completo con interruttore; stadi, requisiti con il confronto a un passo, gemello simulato, sola uscita e procedura di conferma per i soldi veri (12.3, 12.4), provata solo contro un conto reale finto; backtest delle tre strategie secondo 12.2; schermate "Strategie", "Rischio", "Operazioni" con la scheda "perché"; parte di Impostazioni su strategie, limiti e scenari.
Accettazione: ogni regola di 9.1 e 9.2 ha il suo test; un test dimostra che senza la procedura di 12.4 nessun ordine raggiunge un conto reale, e un altro che una strategia retrocessa continua a gestire uscite e stop delle sue posizioni reali fino a zero; per ciascuna strategia un rapporto di backtest onesto in `docs/backtests/`, con costi doppi e tripli e confronto con comprare e tenere, **qualunque sia l'esito**, più il file versionato con l'esito che il primo avvio caricherà (12.3); senza chiavi Alpaca i backtest azionari non si possono fare: le due strategie restano in osservazione e il criterio resta in attesa dell'utente (2.3); i test anti-sguardo-avanti passano; le tre schermate corrispondono ai mockup.
### Fase 6 — Motore dal vivo in simulazione
Lavori: orchestrazione della giornata (5.5) con i lavori disponibili finora; diario con frasi in italiano dai codici motivo; Panoramica completa (i riquadri di notizie e modello dichiarano "non ancora attivo" finché le fasi 7 e 8 non li riempiono); "Diario e sistema"; Telegram; confronto "senza bot"; processo di guardia con il suo file di stato; avvio e ripartenza sicuri; recupero dopo un'assenza (5.6); segnale di vita.
Accettazione: il test di parità tra backtest e motore in simulazione passa, con correttivi e rischio attivi; una prova accelerata con orologio simulato copre almeno 10 giorni di mercato con guasti iniettati (rete, riavvio a metà ordine, database irraggiungibile) e termina con registro e conti riconciliati e senza ordini duplicati; un test blocca il ciclo principale con una vendita a metà e verifica che, dopo l'intervento del processo di guardia, la posizione abbia di nuovo i suoi stop e il motore sia ripartito; la stessa prova si ripete dentro l'immagine Docker, dove la guardia è il processo principale; un test con orologio simulato spegne il bot per 3 ore, per 20 ore e per 3 giorni e verifica le righe della tabella di 5.6 i cui lavori esistono già; a fine fase parte una prova di durata in tempo reale di almeno 48 ore, a cavallo di almeno due sedute USA (solo crypto se mancano le chiavi Alpaca), il cui rapporto si verifica come primo passo della Fase 7; in modalità dimostrativa la Panoramica corrisponde allo screen 01 a 1440 pixel e allo screen 09 a 390 (lì i riquadri di notizie e modello mostrano i dati dell'appendice F); il Diario corrisponde allo screen 08 a 1440 pixel e a 390 non scorre in orizzontale; i comandi Telegram funzionano (o, senza token, superano i test con un finto server).
### Fase 7 — Notizie
Lavori: verifica del rapporto della prova di durata; raccolta, deduplica, collegamento agli strumenti; classificatore locale; analista con modello linguistico facoltativo e tetto di spesa; indicatori d'umore; regole di 10.5; righe di 5.6 su notizie e calendario nel test di recupero; schermata "Notizie e mercato"; parte di Impostazioni su notizie e calendario.
Accettazione: il rapporto della prova di durata è in `docs/` e non riporta ordini duplicati né differenze non spiegate; su un archivio di notizie registrate la deduplica e il collegamento superano i test; un testo con istruzioni malevole non produce alcun effetto fuori dallo schema (test dedicato); senza chiave del modello linguistico tutto funziona; il tetto di spesa viene rispettato; ogni restrizione generata da una notizia compare nel diario con il suo motivo; la schermata corrisponde al mockup.
### Fase 8 — Apprendimento
Lavori: archivio degli indizi "a una certa data"; etichette; addestramento e convalida; registro dei modelli; versione in carica e sfidante; ombra; deriva; messa da parte automatica; scoperte in chiaro e gli altri apprendimenti di 11.6; righe di 5.6 su etichette e controllo del modello nel test di recupero; schermata "Apprendimento"; parte di Impostazioni sul modello.
Accettazione: un test dimostra che nessun indizio usa dati successivi alla decisione; il primo modello è addestrato sugli esempi storici con rapporto di convalida; il moltiplicatore non può superare 1 (test di proprietà); promozione, scarto e messa da parte sono coperti da test con dati sintetici; la schermata corrisponde al mockup.
### Fase 9 — Rifinitura e consegna in Docker
Lavori: revisione della sicurezza; salvataggi e ripristino provati su entrambi i motori; impronta del database e ripartenza protetta (15.1); template Unraid dall'appendice E, con la sua icona; CI completa; `MANUALE.md` (installazione, primo avvio, uso quotidiano, cosa fare se), `RUNBOOK.md` (incidenti: conto non riconciliato, flusso fermo, interruttore scattato, chiave scaduta), `GO-LIVE.md` (lista di controllo per i soldi veri, compresa la verifica con il broker della regola PDT e dell'accesso al conto reale dall'Italia); esportazione per la dichiarazione; strategie candidate di 8.4 e migliorie di 8.7 in osservazione; revisione trimestrale (12.2), con la retrocessione di 12.3 e il bilancio delle restrizioni di 10.5.
Accettazione: installazione da zero con `docker run` seguendo solo il manuale, una volta con SQLite e una con PostgreSQL; il template Unraid supera il test di 15.3 (la prova su Unraid la fa l'utente); ripristino da un salvataggio verificato, con la ripartenza protetta di 15.1; un database vecchio, riavviato dopo un'importazione, porta alla pagina d'errore (test); `make check` e `make ci` passano, e la CI remota se esiste; `STATE.md` elenca con franchezza ciò che resta debole.
### Fase 10 — Applicazione desktop
Lavori: avviatore con finestra, icona nell'area di notifica e istanza unica, che fa anche da processo di guardia; spostamento su un altro database; opzioni di accesso dalla rete, sospensione e avvio automatico; conferma all'uscita; confezione con PyInstaller e Inno Setup; capitolo del manuale sul desktop; revisione finale con un subagent a contesto pulito su tutta la specifica.
Accettazione: in una cartella dei dati vuota l'applicazione parte, la procedura guidata crea il database SQLite e l'interfaccia risponde solo dal computer stesso (test); la stessa procedura con PostgreSQL passa contro il Postgres di sviluppo; le voci dell'area di notifica producono gli stessi effetti dei pulsanti dell'interfaccia (test sulle API); il recupero dopo un'assenza passa con la configurazione desktop; la prova del processo di guardia della Fase 6 passa anche con l'avviatore al posto della guardia; lo spostamento da SQLite a PostgreSQL conserva conteggi e totali; `make desktop-win` produce l'installatore se la sessione gira su Windows, altrimenti lo script è pronto, provato fin dove possibile, e la mancanza è scritta in `STATE.md`; ogni sezione di questa specifica ha un riscontro nel codice o un ADR che spiega lo scostamento.
### Fasi opzionali (solo se l'utente le chiede)
A. Adapter eToro. B. Adapter Interactive Brokers con ETF europei armonizzati. C. Bitvavo o Kraken come secondo exchange. Ognuna segue lo stesso schema: verifica della documentazione, adapter, batteria di conformità, simulazione.
---
## 18. Fuori perimetro
Non costruire, nemmeno "per completezza": alta frequenza, arbitraggi tra exchange, market making; leva, margine, vendite allo scoperto, derivati; griglie, martingale, panieri "coperti"; reinforcement learning; reti profonde per prevedere i prezzi; acquisti generati da notizie; copy trading; gestione di più utenti; app native per telefono; qualsiasi automatismo che sposti denaro.
---
## 19. Trappole note
1. **Guardare avanti**: usare la chiusura di oggi per operare alla chiusura di oggi; indicatori calcolati su tutta la serie; universi costruiti con i titoli di oggi.
2. **Orari**: l'ora legale di USA ed Europa cambia in settimane diverse; le crypto chiudono a mezzanotte UTC tutto l'anno. Usa sempre i calendari.
3. **Denaro in virgola mobile**: mai. `Decimal` e arrotondamenti espliciti.
4. **Ordini duplicati dopo un errore di rete**: identificativo deterministico e interrogazione prima del nuovo invio.
5. **Esecuzioni parziali, importi minimi, arrotondamenti**: ogni broker ha i suoi; leggili dalle API.
6. **Frazioni di azione su Alpaca**: solo validità giornaliera, stop compresi.
7. **Commissioni trattenute nella moneta comprata**: la quantità in portafoglio è minore di quella ordinata.
8. **Volumi IEX**: non rappresentano il mercato.
9. **Frazionamenti e dividendi**: prezzi rettificati per i segnali, reali per gli ordini. A ogni azione societaria valgono le regole di 6.10: altrimenti uno stop salvato in prezzi vecchi resta sopra il mercato e fa vendere tutto.
10. **Flussi che cadono in silenzio**: controlla l'età dell'ultimo dato, non solo lo stato della connessione; alla riconnessione recupera il buco.
11. **Calcoli pesanti nell'event loop**: bloccano prezzi e ordini. Process pool.
12. **Test che dipendono dall'ora o dalla rete**: orologio iniettabile e risposte registrate.
13. **Simulazione troppo ottimista**: niente impatto sul prezzo, niente code. Tieni gli scostamenti prudenti e confrontali con quelli reali appena esistono.
14. **Coppie in USDT**: non negoziabili in Europa.
15. **Chiavi OKX senza IP associato**: scadono dopo 14 giorni di inattività.
16. **Istruzioni nascoste nelle notizie** e **memoria del modello linguistico nei backtest**: vedi 10.3.
17. **Segreti nei registri**: filtra chiavi, firme e intestazioni di autenticazione prima di scrivere.
18. **Aggiustare i parametri finché il backtest migliora**: è il modo più rapido per perdere soldi veri. Vale il protocollo di 12.2.
19. **Decimali su SQLite**: senza il tipo personalizzato di 5.4 diventano numeri in virgola mobile, in silenzio.
20. **Ripiegare da soli su un altro database** quando quello configurato non risponde: nasce un secondo registro. Pagina d'errore e basta (15.1).
21. **Computer in sospensione**: l'orologio salta in avanti e i lavori saltati non vanno eseguiti alla cieca. Valgono le regole di 5.6.
22. **Due ordini di vendita sulla stessa posizione** (stop permanente e stop giornaliero su Alpaca): prima di vendere vanno annullati entrambi, altrimenti il broker rifiuta la vendita.
23. **Candele giornaliere di OKX**: quelle normali chiudono alle 16:00 UTC, non a mezzanotte (4.2, 8.1).
24. **Stop posato sopra il prezzo**: dopo un'apertura in ribasso o un'assenza il livello può essere già superato. Vale la regola dello stop già superato (7.2).
25. **Controlli che fermano anche le uscite**: prezzi fermi o orologio sfasato devono bloccare gli ingressi, mai stop e vendite (9.2).
26. **Due registri sullo stesso conto**: un database vecchio riavviato per errore opera sulle stesse posizioni. Impronta del database, ripartenza protetta e codice dell'installazione negli ordini (15.1, 7.2).
27. **Dati dimostrativi nel database vero**: la modalità dimostrativa usa sempre un database a parte (13.1).
28. **Ordini di segno opposto su Alpaca**: con uno stop di vendita aperto il broker rifiuta ogni acquisto sullo stesso titolo, e con un acquisto aperto rifiuta lo stop (4.1, 7.2).
29. **Processo principale del container**: non si può terminare dall'interno. Se il motore è il processo principale, la guardia non riesce a riavviarlo (9.3).
30. **Cambi di stadio letti come perdite**: un registro che lascia la simulazione per i soldi veri è un prelievo per quel mondo, non un crollo del patrimonio (7.5, 9.2).
---
## Appendice A — Messaggi da incollare in Claude Code
**Primo avvio** (cartella vuota contenente `docs/SPEC.md` e, in `docs/design/`, i nove file JPG degli screen):
```
Leggi docs/SPEC.md per intero. È la specifica completa del progetto: seguila alla lettera.
Esegui la Fase 0 della sezione 17. Non chiedermi conferme: decidi, annota in un ADR e prosegui.
Quando tutti i criteri di accettazione della fase sono verificati, mostrami le prove,
aggiorna docs/ROADMAP.md e docs/STATE.md, fai il commit e fermati.
```
Una riga facoltativa, da aggiungere in fondo allo stesso messaggio, per avere il bot in C# invece che in Python: `Usa la variante C#/.NET dell'appendice D.` Il nome non va indicato: è già fissato nell'ADR 0001.
Conviene creare subito il conto paper di Alpaca e le chiavi demo di OKX Europe: senza, restano in sospeso i dati azionari (Fase 2), gli ordini sui conti di prova (Fase 3) e i backtest sulle azioni (Fase 5).
**Ripresa** (ogni sessione successiva):
```
Leggi CLAUDE.md e docs/STATE.md, poi la parte di docs/SPEC.md che riguarda la prossima fase
non completata di docs/ROADMAP.md. Eseguila fino in fondo con le regole della sezione 2.
Alla fine mostrami le prove dei criteri di accettazione, aggiorna ROADMAP e STATE, fai il commit e fermati.
```
**Per lasciarlo lavorare senza presidio** (comando `/goal`, da usare in modalità automatica):
```
/goal Tutti i criteri di accettazione della prossima fase non completata di docs/ROADMAP.md sono verificati con output mostrato in conversazione oppure segnati "in attesa dell'utente" secondo la sezione 2.3, make check termina senza errori, docs/STATE.md e docs/ROADMAP.md sono aggiornati e il lavoro è nel commit con il tag della fase; oppure fermati dopo 60 turni e scrivi in docs/STATE.md cosa manca.
```
**Revisione indipendente** (in una sessione nuova, a fine fase):
```
Leggi in docs/SPEC.md le sezioni che la tabella della sezione 17 indica per la Fase [N] e i criteri
di accettazione della stessa fase in docs/ROADMAP.md. Esamina le modifiche dal tag fase-[N-1] al tag
fase-[N]. Segnala solo difetti di correttezza, violazioni delle sezioni 9 e 19 e requisiti non
soddisfatti, con file e riga. Niente preferenze di stile. Non modificare nulla: le correzioni
andranno in commit nuovi, senza spostare i tag.
```
**Quando arrivano le chiavi dei conti di prova**:
```
Ho inserito nel file .env le chiavi del conto paper di Alpaca e le chiavi demo di OKX Europe.
Chiudi i criteri rimasti "in attesa dell'utente" in docs/ROADMAP.md: dati azionari della Fase 2,
batteria di conformità live_demo della Fase 3, backtest azionari della Fase 5 se ci sei già arrivato.
Correggi ciò che non passa, aggiorna docs/API-NOTES.md con le differenze trovate rispetto alla
documentazione e riportami l'esito.
```
---
## Appendice B — Formati
**ADR** (`docs/adr/0007-titolo-breve.md`):
```markdown
# 0007 — Titolo breve
Data: 2026-10-14 · Stato: accettata
## Contesto
Due o tre frasi sul problema e sul vincolo.
## Decisione
Cosa si fa.
## Alternative scartate
Elenco, con il motivo in una riga.
## Conseguenze
Cosa diventa più facile, cosa più difficile, come si verifica.
```
**Riepilogo di fine fase** (ultimo messaggio della sessione):
```
Fase N — titolo: COMPLETATA / INCOMPLETA
Criteri di accettazione: per ciascuno, verificato o no, con la prova (comando e risultato).
Decisioni prese: elenco degli ADR nuovi.
Scostamenti dalla specifica: nessuno, oppure elenco con motivo.
Serve l'utente per: nessuna cosa, oppure elenco.
Prossimo passo: una riga.
```
**Voce di diario**: una frase principale e, se serve, una seconda con il motivo. Esempi del tono richiesto:
```
Buono: "Alzato lo stop di BTC/EUR da 65.400 € a 66.180 €. Lo stop segue il prezzo quando sale."
Buono: "Azioni: nessun nuovo acquisto. AAPL resta aperta: non è ancora tornata sopra la media a 5 giorni."
Da evitare: "Trailing stop update BTC-EUR SL 66180 (Donchian mid N=20 ratchet)."
Da evitare: "Ottima notizia! Il bot ha brillantemente protetto i tuoi profitti."
```
**Risposta del modello linguistico sulle notizie** (schema da validare, tutto il resto si scarta):
```json
{
"instruments": ["SOL"],
"scope": "instrument | asset_class | market",
"event_type": "network_upgrade | earnings | guidance | regulation | security_incident | fraud_or_investigation | bankruptcy | trading_halt | listing | delisting | macro_data | central_bank | analyst_opinion | rumor | other",
"direction": "negative | neutral | positive",
"importance": 3,
"confidence": 0.7,
"unconfirmed": false,
"summary_it": "Rinviato di una settimana l'aggiornamento della rete Solana"
}
```
---
## Appendice C — Token grafici
Valori di partenza, già controllati per contrasto e per distinguibilità con le forme più comuni di daltonismo. Mettili in `frontend/src/lib/tokens.ts` e nelle variabili CSS; non usare colori fuori da questo elenco.
| Ruolo | Chiaro | Scuro |
|---|---|---|
| Sfondo della pagina | `#f1f3f0` | `#101412` |
| Superficie dei pannelli | `#fbfcfa` | `#181d1a` |
| Superficie secondaria (binari, selezioni) | `#e9ede8` | `#222924` |
| Binario dei misuratori | `#dfe4de` | `#2c342f` |
| Filetto | `#d9ded8` | `#2c342f` |
| Filetto interno alle tabelle | `#e3e7e2` | `#262d28` |
| Bordo dei controlli | `#8a948e` | `#6c766f` |
| Testo principale | `#141a17` | `#f2f5f1` |
| Testo secondario | `#46504a` | `#c3cbc4` |
| Testo attenuato | `#5f6963` | `#9aa39c` |
| Collegamenti | `#1c5cab` | `#86b6ef` |
| Sfondo informativo | `#e3eefb` | `#17304f` |
| Guadagno (testo e segni) | `#0a6b55` | `#4cc9a4` |
| Sfondo guadagno | `#dff2ea` | `#12372d` |
| Perdita (testo e segni) | `#b42f1a` | `#ff8d78` |
| Sfondo perdita | `#fbe5df` | `#45201a` |
| Attenzione (testo) | `#7a5000` | `#f2c14e` |
| Sfondo attenzione | `#fbefcf` | `#3d2f0c` |
| Strategia `crypto_trend` | `#2a78d6` | `#17a2b8` |
| Strategia `equity_momentum` | `#eb6834` | `#d95926` |
| Strategia `equity_meanrev` | `#4a3aa7` | `#9085e9` |
| Serie di confronto, liquidità | `#8a948e`, `#c5cbc4` | `#6c766f`, `#3a433d` |
Regole: la linea del portafoglio è nel colore del testo principale, il confronto in grigio; le tinte delle strategie compaiono solo come punti, barre e linee con il nome accanto, mai come testo; guadagno e perdita non si usano per altro. Nel tema scuro le tinte delle strategie sono vicine tra loro per chi non distingue bene i colori: per questo il nome accanto è obbligatorio.
Tipografia: Instrument Sans; titolo di pagina 22/28 peso 650; titoli di sezione 17/24 peso 650; testo 14/20; note 13/18; numero principale della Panoramica 60/60 peso 650 con spaziatura −0,025em. Spaziatura su multipli di 4 pixel; raggio 14 per i pannelli, 8–10 per controlli e avvisi, pillole per gli stati.
Misure dei componenti, dagli screen a 1440 pixel (valori in pixel):
| Elemento | Misure |
|---|---|
| Menu laterale | Largo 220; margini interni 20 sopra, 12 ai lati, 24 sotto; voci alte almeno 40, raggio 8, margini interni 8 e 12, icona di 20 e testo a 12 di distanza; voce attiva sulla superficie secondaria, peso 600; gruppi di voci separati da 22 |
| Barra superiore | Margini interni 16 e 32, filetto sotto; pillole di stato alte 32, a tutto raggio; pulsanti alti 40, raggio 8, bordo dei controlli, testo 14 peso 550 |
| Corpo della pagina | Margini interni 28 sopra, 32 ai lati, 36 sotto; 28 tra un blocco e l'altro (24 nelle pagine dense); 20 tra pannelli affiancati |
| Pannello | Raggio 14, filetto di 1, margini interni 20 e 22 (24 e 28 nei blocchi in testa alla pagina) |
| Blocco in testa alla Panoramica | Due metà divise da un filetto verticale, la sinistra più larga (rapporto 1,35 a 1); grafico del patrimonio alto 284 |
| Tabelle | Testo 13,5 su 20 con cifre tabellari; intestazioni 12,5, peso 500, colore attenuato; celle con 9–10 sopra e sotto; filetto interno tra le righe; importi allineati a destra |
| Numeri in evidenza | 60 su 60 il risultato della Panoramica; 30 su 36 i totali di pagina; 28 su 34 il patrimonio di un conto; 18 su 24 le cifre secondarie; peso 650; spaziatura −0,025em per il numero principale di una pagina (60 su 60 nella Panoramica, 48 su 52 in Operazioni, 46 su 48 su telefono), −0,015em per gli altri |
| Misuratori | Binario alto 6–8, raggio 3–4, riempimento nel colore del testo secondario; tacca verticale di 2 per il valore peggiore |
| Grafici | Linea di 2; area sotto la linea del portafoglio al 5% di opacità; punto finale di 10 con anello di 2 nel colore della superficie; griglia nel filetto interno |
| Etichette e avvisi | Raggio 8–10, margini interni 10 e 12, testo 13–13,5 sul proprio sfondo morbido, sempre con icona di 15–16 |
| Icone | Tratto lineare, spessore 1,8–2,2, estremi arrotondati |
| Telefono | Margini di pagina 16 e 14 tra i pannelli; pannelli con margini interni 18; barra in basso con cinque voci alte almeno 52, icona sopra ed etichetta a 11,5; aree da toccare di almeno 44 |
---
## Appendice D — Variante C#/.NET
Lo stack della sezione 3 è Python perché lì stanno le librerie più mature per broker e apprendimento. Se l'utente chiede questa variante, le righe qui sotto sostituiscono quelle corrispondenti della sezione 3 (la riga Accesso sostituisce l'Argon2id di 15.4); adatta di conseguenza struttura del repository (5.1), interfacce (5.3, da riscrivere come `interface` C#), comandi e strumenti di qualità. Tutto il resto della specifica vale identico: strategie, rischio, notizie, apprendimento, interfaccia, fasi e criteri di accettazione. Le versioni indicate sono le ultime stabili su NuGet al 9 ottobre 2026.
| Tema | Variante |
|---|---|
| Linguaggio | C# su .NET 10 |
| Web/API | ASP.NET Core (minimal API) con un canale WebSocket; il motore è un `BackgroundService` nello stesso processo; i lavori pesanti in thread dedicati con priorità bassa |
| Concorrenza | Un solo scrittore sul database, come nella sezione 3; il processo di guardia di 9.3 è un piccolo eseguibile a parte, che fa da genitore al motore |
| Database | PostgreSQL con `Npgsql` (10.0.3) oppure SQLite con `Microsoft.Data.Sqlite`, stesso schema (5.4): `decimal` salvato come testo su SQLite, somme in C#; accesso con Dapper o EF Core; migrazioni versionate e provate su entrambi i motori |
| Connessione ai broker | `Alpaca.Markets` (8.0.0, SDK ufficiale) per Alpaca; `ccxt` per .NET (4.5.85: contiene la classe `myokx` con gli indirizzi europei e l'intestazione del demo) per le crypto. In alternativa un client scritto in casa su `HttpClient` e `ClientWebSocket`: l'API di OKX chiede solo una firma HMAC-SHA256 |
| Numeri | `decimal` per prezzi, quantità e denaro; `double` solo nell'analisi |
| Storico per la ricerca | File Parquet con `Parquet.Net` (6.1.0, licenza MIT) |
| Apprendimento | ML.NET con `Microsoft.ML.LightGbm` (5.0.0); regressione logistica di ML.NET come riferimento e, al posto del percettrone, una foresta casuale (`Microsoft.ML.FastTree`) come sfidante; calibrazione con i calibratori di ML.NET; convalida purgata con embargo, ADWIN, DSR e PBO scritti in casa con test su casi noti |
| Lettura notizie | `Microsoft.ML.OnnxRuntime` (1.31.0) e `Microsoft.ML.Tokenizers` (2.0.0) con lo stesso modello ONNX; controlla che il tokenizzatore produca gli stessi identificativi dell'originale su un campione di titoli. Feed RSS con `System.ServiceModel.Syndication` |
| Accesso | Hash delle password con `PasswordHasher` di ASP.NET Core Identity (PBKDF2) al posto di Argon2id; codice a due fattori scritto in casa (RFC 6238) con test sui vettori ufficiali |
| Frontend | Invariato: React + TypeScript + Vite, servito come file statici da ASP.NET Core |
| Qualità | Analizzatori .NET con avvisi trattati come errori e `Nullable` attivo; xUnit; FsCheck (3.4.0) per i test basati su proprietà; Playwright |
| Distribuzione Docker | Immagine multi-stage con `mcr.microsoft.com/dotnet/sdk:10.0` per la build e `mcr.microsoft.com/dotnet/aspnet:10.0` per l'esecuzione; LightGBM e ONNX Runtime portano librerie native: verifica che l'immagine finale le carichi (`libgomp1`) |
| Applicazione desktop | Lo stesso progetto pubblicato come eseguibile autonomo (`dotnet publish -r win-x64 --self-contained`, anche da Linux); finestra con WebView2 su Windows, oppure Photino.NET se servono anche macOS e Linux; icona nell'area di notifica; segreti nel portachiavi del sistema (DPAPI su Windows); installatore Inno Setup. Valgono tutte le regole di 15.6 |
Dipendenze in questa variante: solo i pacchetti elencati e quelli di Microsoft. Ogni altro pacchetto richiede un ADR che spieghi perché non conviene scriverlo in casa.
---
## Appendice E — Bozza del template Unraid
Punto di partenza per `deploy/unraid/anubis.xml` (15.3). I segnaposto `gitea.example.lan/UTENTE` vanno sostituiti con il registry e l'utente reali.
```xml
<?xml version="1.0"?>
<!--
Anubis: bozza del template Docker per Unraid.
Prima di usarla sostituisci gitea.example.lan/UTENTE con il registry e l'utente
dove viene pubblicata l'immagine (Repository, Registry, Support, Project, Icon).
Copia il file in /boot/config/plugins/dockerMan/templates-user/ e scegli
"anubis" tra i template nella scheda Docker di Unraid.
-->
<Container version="2">
<Name>anubis</Name>
<Repository>gitea.example.lan/UTENTE/anubis:latest</Repository>
<Registry>https://gitea.example.lan/UTENTE/-/packages/container/anubis/latest</Registry>
<Network>bridge</Network>
<Shell>sh</Shell>
<Privileged>false</Privileged>
<Support>https://gitea.example.lan/UTENTE/anubis/issues</Support>
<Project>https://gitea.example.lan/UTENTE/anubis</Project>
<Overview>Anubis è un bot di trading personale: azioni USA su Alpaca e crypto spot su OKX Europe, senza leva. Parte in simulazione e passa ai soldi veri solo con requisiti misurati e la conferma dell'utente. Il database si sceglie qui: PostgreSQL (un database vuoto, già creato, con un utente dedicato) oppure SQLite (un file nella cartella dei dati).</Overview>
<Category>Tools:Utilities Status:Beta</Category>
<WebUI>http://[IP]:[PORT:8787]/</WebUI>
<TemplateURL/>
<Icon>https://gitea.example.lan/UTENTE/anubis/raw/branch/main/deploy/unraid/anubis-icon.png</Icon>
<ExtraParams>--restart unless-stopped --memory=4g --stop-timeout 60</ExtraParams>
<Requires>Con PostgreSQL: un database vuoto e un utente dedicato, raggiungibili dal container.</Requires>
<Config Name="Porta dell'interfaccia" Target="8787" Default="8787" Mode="tcp" Description="Porta su cui si apre l'interfaccia web." Type="Port" Display="always" Required="true" Mask="false">8787</Config>
<Config Name="Cartella dei dati" Target="/data" Default="/mnt/user/appdata/anubis" Mode="rw" Description="Modelli, salvataggi, storico per la ricerca e registri tecnici. Con SQLite contiene anche il database." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/anubis</Config>
<Config Name="Database" Target="ANUBIS_DB_ENGINE" Default="postgres|sqlite" Mode="" Description="postgres: usa il server PostgreSQL indicato nei campi qui sotto. sqlite: un file nella cartella dei dati, senza altri campi da compilare. La scelta si fa qui e non si cambia dall'interfaccia." Type="Variable" Display="always" Required="true" Mask="false">postgres</Config>
<Config Name="PostgreSQL: indirizzo" Target="ANUBIS_DB_HOST" Default="" Mode="" Description="Solo con postgres. Di solito l'indirizzo IP di Unraid; il nome del container PostgreSQL se i due stanno sulla stessa rete Docker personalizzata." Type="Variable" Display="always" Required="false" Mask="false"></Config>
<Config Name="PostgreSQL: porta" Target="ANUBIS_DB_PORT" Default="5432" Mode="" Description="Solo con postgres." Type="Variable" Display="always" Required="false" Mask="false">5432</Config>
<Config Name="PostgreSQL: nome del database" Target="ANUBIS_DB_NAME" Default="anubis" Mode="" Description="Solo con postgres. Deve esistere già ed essere dedicato a Anubis." Type="Variable" Display="always" Required="false" Mask="false">anubis</Config>
<Config Name="PostgreSQL: utente" Target="ANUBIS_DB_USER" Default="anubis" Mode="" Description="Solo con postgres." Type="Variable" Display="always" Required="false" Mask="false">anubis</Config>
<Config Name="PostgreSQL: password" Target="ANUBIS_DB_PASSWORD" Default="" Mode="" Description="Solo con postgres." Type="Variable" Display="always" Required="false" Mask="true"></Config>
<Config Name="Chiave dei segreti" Target="ANUBIS_SECRET_KEY" Default="" Mode="" Description="Stringa lunga e casuale, almeno 32 caratteri: cifra nel database le chiavi dei conti. Conservala: se cambia, le chiavi vanno reinserite." Type="Variable" Display="always" Required="true" Mask="true"></Config>
<Config Name="Password iniziale" Target="ANUBIS_ADMIN_PASSWORD" Default="" Mode="" Description="Password per il primo accesso all'interfaccia, dove se ne sceglie subito una nuova. Resta la chiave per le scelte della pagina d'errore del database." Type="Variable" Display="always" Required="true" Mask="true"></Config>
<Config Name="Fuso orario" Target="TZ" Default="Europe/Rome" Mode="" Description="Il tuo fuso orario: decide gli orari mostrati, il giorno dei limiti di rischio e i lavori notturni." Type="Variable" Display="always" Required="false" Mask="false">Europe/Rome</Config>
<Config Name="Soldi veri consentiti" Target="ANUBIS_ALLOW_LIVE" Default="0|1" Mode="" Description="0: il bot non può collegarsi a conti reali, qualunque cosa si faccia dall'interfaccia. 1: la procedura di conferma per i soldi veri diventa disponibile." Type="Variable" Display="advanced" Required="false" Mask="false">0</Config>
<Config Name="Telegram: token del bot" Target="TELEGRAM_BOT_TOKEN" Default="" Mode="" Description="Facoltativo: si può inserire anche dall'interfaccia. Se lo compili qui, l'interfaccia lo mostra in sola lettura." Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
<Config Name="Telegram: chat autorizzata" Target="TELEGRAM_CHAT_ID" Default="" Mode="" Description="Facoltativo: identificativo della chat che riceve gli avvisi e può dare comandi." Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
<Config Name="Segnale di vita" Target="ANUBIS_HEARTBEAT_URL" Default="" Mode="" Description="Facoltativo: indirizzo di un servizio esterno da chiamare ogni minuto, che avvisa quando il bot smette di rispondere." Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
<Config Name="Utente (PUID)" Target="PUID" Default="99" Mode="" Description="Utente a cui va la cartella dei dati e con cui gira l'applicazione. 99 è il valore normale su Unraid." Type="Variable" Display="advanced" Required="false" Mask="false">99</Config>
<Config Name="Gruppo (PGID)" Target="PGID" Default="100" Mode="" Description="Gruppo a cui va la cartella dei dati. 100 è il valore normale su Unraid." Type="Variable" Display="advanced" Required="false" Mask="false">100</Config>
<Config Name="Database: indirizzo completo" Target="ANUBIS_DB_URL" Default="" Mode="" Description="Facoltativo, per casi particolari: sostituisce i campi PostgreSQL separati." Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
</Container>
```
---
## Appendice F — Dati dimostrativi
Sono i dati di esempio che compaiono negli screen. La modalità dimostrativa (13.1) li carica così come sono, senza ricalcolarli: gli importi sono quelli da mostrare, mentre quantità e prezzi sono arrotondati, quindi rifacendo un conto si può trovare un centesimo di differenza. Importi in euro salvo dove è indicato il dollaro; cambio fisso 1 € = 1,1601 $; orari italiani. Qui ci sono i dati; i testi fissi delle schermate si leggono dalle immagini.
### F.1 Scenario e totali
- Avvio: mercoledì 12 agosto 2026, con 10.000,00 € (4.000 su OKX Europe, 6.000 su Alpaca). "Adesso": venerdì 9 ottobre 2026, ore 08:21. Giorno 58, senza interruzioni. Dati aggiornati 4 secondi fa.
- Piattaforma Docker, database PostgreSQL, versione 0.9.2. Bot attivo, nessuna strategia con soldi veri.
- L'universo di 10 monete e le operazioni su ADA e LINK sono illustrativi: quante coppie in EUR superino davvero i filtri di 8.1 lo dirà il mercato.
| Voce | Valore |
|---|---|
| Patrimonio | 10.412,46 € |
| Risultato dall'avvio | +412,46 € (+4,12%) |
| Oggi | +18,40 € (+0,18%) |
| Ultimi 7 giorni | +96,10 € (+0,93%) |
| Ultimi 30 giorni | +251,70 € (+2,48%) |
| Senza bot (40% Bitcoin e 60% S&P 500 comprati il 12 agosto e tenuti) | 9.974,00 €, cioè −26,00 € (−0,26%) |
| Investito | 6.671,13 € (64,1%) |
| Liquidità | 3.741,33 € (35,9%) |
| Risultato delle posizioni aperte | +173,18 € (7 in guadagno, 3 in perdita) |
| Calo dal massimo | adesso 0,00%; peggiore −2,82% il 5 settembre |
| Ripartizione del patrimonio | Trend crypto 22,3%; Momentum azioni 37,5%; Mean reversion azioni 4,3%; liquidità 35,9% |
| Valute | Dollari (conto Alpaca) 6.180,86 €, 59,4%; euro e crypto (conto OKX) 4.231,60 €, 40,6% |
### F.2 Conti
| Conto | Ambiente | Capitale affidato | Patrimonio | Risultato | Liquidità | Investito | Guadagni incassati | Guadagni aperti | Commissioni | Ultimi 30 giorni | Risposta |
|---|---|---|---|---|---|---|---|---|---|---|---|
| OKX Europe (Crypto) | simulatore interno | 4.000,00 | 4.231,60 | +231,60 (+5,79%) | 1.905,10 | 2.326,50 | +163,45 | +68,15 | 14,49 | +158,20 | 84 ms |
| Alpaca (Azioni USA) | conto di prova | 6.000,00 | 6.180,86 (7.170,41 $) | +180,86 (+3,01%) | 1.836,23 (2.130,21 $) | 4.344,63 (5.040,20 $) | +75,83 | +105,03 | 0,33 | +93,50 | 61 ms |
OKX Europe: 3 posizioni, 3 stop attivi; la chiave può solo leggere e fare ordini; registro interno coerente (controllo delle 08:20). Alpaca: 7 posizioni; mercato chiuso, apre alle 15:30; conto e registro interno coincidono (controllo delle 08:20).
### F.3 Strategie
| Strategia | Conto | Stadio | Capitale assegnato | Risultato | Calo peggiore | Operazioni chiuse | Posizioni aperte | Differenza dal backtest |
|---|---|---|---|---|---|---|---|---|
| Trend crypto (`crypto_trend`) | OKX Europe | simulazione, giorno 58 di 60 | 40%, cioè 4.000 € | +231,60 € (+5,79%) | −4,1% | 9, di cui 5 in guadagno | BTC, ETH, SOL | 0,7% (massimo 2%) |
| Momentum azioni USA (`equity_momentum`) | Alpaca | simulazione, giorno 58 di 60 | 45%, cioè 4.500 € | +169,50 € (+3,77%) | −3,2% | 11, di cui 7 in guadagno | 6 azioni | 1,1% (massimo 2%) |
| Mean reversion azioni USA (`equity_meanrev`) | Alpaca | simulazione, giorno 58 di 60 | 15%, cioè 1.500 € | +11,36 € (+0,76%) | −1,1% | 21, di cui 10 in guadagno | AAPL | 1,6% (massimo 2%) |
Requisiti: per tutte e tre, prezzi ottenuti vicini a quelli previsti e nessun incidente negli ultimi 30 giorni. Trend crypto: almeno 8 operazioni chiuse, sono 9. Momentum: almeno 10, sono 11. Mean reversion: 21 operazioni su 30, e guadagna troppo poco (0,66 € a operazione contro i 0,90 necessari). Trend crypto e Momentum possono passare al reale ridotto tra 2 giorni; Mean reversion resta in simulazione.
In osservazione: "Nuovi massimi storici sulle azioni USA" (`stock_ath_breakout`), 14 segnali in 31 giorni su 90. Archiviata: "Momentum relativo tra crypto" (`crypto_relative_momentum`), scartata nei test perché tolti i costi il risultato è vicino a zero.
### F.4 Posizioni aperte
| Strumento | Nome | Conto | Strategia | Quantità | Prezzo medio | Prezzo ora | Valore € | Risultato € | Risultato % | Stop | Aperta da (giorni) | Rischio all'ingresso % |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| BTC/EUR | Bitcoin | OKX Europe | Trend crypto | 0,0182 | 68.950,00 € | 71.420,00 € | 1.299,84 | +44,95 | +3,58 | 66.180 € | 23 | 0,95 |
| ETH/EUR | Ether | OKX Europe | Trend crypto | 0,262 | 2.488,00 € | 2.611,00 € | 684,08 | +32,23 | +4,94 | 2.395 € | 19 | 0,62 |
| AVGO | Broadcom | Alpaca | Momentum | 2,1 | 352,10 $ | 367,90 $ | 665,97 | +28,60 | +4,49 | 338,50 $ | 18 | 0,48 |
| NVDA | Nvidia | Alpaca | Momentum | 4,2 | 171,30 $ | 182,45 $ | 660,54 | +40,37 | +6,51 | 166,00 $ | 25 | 0,52 |
| LLY | Eli Lilly | Alpaca | Momentum | 0,9 | 812,00 $ | 846,30 $ | 656,56 | +26,61 | +4,22 | 795,00 $ | 11 | 0,41 |
| JPM | JPMorgan Chase | Alpaca | Momentum | 2,6 | 291,40 $ | 287,15 $ | 643,56 | −9,53 | −1,46 | 276,90 $ | 4 | 0,36 |
| XOM | Exxon Mobil | Alpaca | Momentum | 6,1 | 118,90 $ | 121,35 $ | 638,08 | +12,89 | +2,06 | 115,20 $ | 11 | 0,33 |
| COST | Costco | Alpaca | Momentum | 0,75 | 968,20 $ | 981,60 $ | 634,60 | +8,66 | +1,38 | 941,00 $ | 4 | 0,30 |
| AAPL | Apple | Alpaca | Mean reversion | 2 | 259,80 $ | 258,31 $ | 445,32 | −2,57 | −0,57 | 249,40 $ | 1 | 0,17 |
| SOL/EUR | Solana | OKX Europe | Trend crypto | 2,68 | 131,20 € | 127,83 € | 342,58 | −9,03 | −2,57 | 118,40 € | 6 | 0,38 |
Ordine di visualizzazione: per valore decrescente. Stop su OKX: tre ordini trigger (BTC aggiornato oggi alle 02:06, da 65.400 € a 66.180 €; ETH attivo dal 7 ottobre; SOL dal 3 ottobre). Stop su Alpaca: 5 permanenti sulle azioni intere (AVGO 2, NVDA 4, JPM 2, XOM 6, AAPL 2) e 6 giornalieri sulle frazioni (AVGO 0,1; NVDA 0,2; LLY 0,9; JPM 0,6; XOM 0,1; COST 0,75), da rimettere alle 15:35.
### F.5 Operazioni chiuse
41 operazioni chiuse, 22 in guadagno (53,7%). Guadagno medio +28,42 € su 22 operazioni; perdita media −20,31 € su 19. Per ogni euro perso ne ha guadagnati 1,62. Guadagni incassati +239,28 €; commissioni 14,82 €, già tolte. Il guadagno più grande è +89,54 € su LINK, la perdita più grande −67,16 € su TSLA.
Le ultime otto, come nella tabella dello screen:
| Chiusa | Strumento | Strategia | Durata | Entrata e uscita | Risultato | Perché è stata chiusa |
|---|---|---|---|---|---|---|
| Gio 8 ott, 21:58 | MSFT Microsoft | Mean reversion | 3 giorni | 512,30 $ → 522,14 $ | +8,48 € (+1,92%) | Tornata sopra la media a 5 giorni |
| Mer 7 ott, 21:59 | KO Coca-Cola | Mean reversion | 5 sedute | 71,20 $ → 70,05 $ | −6,94 € (−1,62%) | Tempo scaduto: nessun rimbalzo in 5 sedute |
| Mar 6 ott, 15:41 | UNH UnitedHealth | Momentum | 15 giorni | 389,00 $ → 371,40 $ | −27,31 € (−4,52%) | Stop di protezione raggiunto |
| Lun 5 ott, 15:42 | AMD Advanced Micro Devices | Momentum | 21 giorni | 148,60 $ → 163,90 $ | +59,35 € (+10,30%) | Non era più tra i 30 titoli più forti |
| Sab 3 ott, 02:06 | ADA/EUR Cardano | Trend crypto | 9 giorni | 0,612 € → 0,571 € | −22,14 € (−6,70%) | La tendenza si è interrotta: prezzo sotto lo stop mobile |
| Mer 30 set, 21:57 | V Visa | Mean reversion | 2 giorni | 341,10 $ → 347,25 $ | +7,95 € (+1,80%) | Tornata sopra la media a 5 giorni |
| Lun 28 set, 02:05 | LINK/EUR Chainlink | Trend crypto | 31 giorni | 14,85 € → 18,92 € | +89,54 € (+27,41%) | Stop mobile raggiunto dopo il rialzo |
| Ven 25 set, 21:58 | PG Procter & Gamble | Mean reversion | 5 sedute | 158,40 $ → 156,95 $ | −3,75 € (−0,92%) | Tempo scaduto: nessun rimbalzo in 5 sedute |
Dettaglio aperto di MSFT. Perché l'ho comprata: "Era scesa per tre sedute di fila, ma restava sopra la sua media a 200 giorni. Questa strategia compra i ribassi brevi dei titoli che nel lungo periodo salgono." Rischio dell'operazione 0,2% del capitale (massimo 1%); nessuna trimestrale nei tre giorni successivi; nessuna notizia negativa sul titolo; il modello stimava il 61% di riuscita (solo osservazione: non ha cambiato la dimensione). Perché l'ho venduta: "Il prezzo è tornato sopra la media a 5 giorni: il rimbalzo che cercavo è arrivato, quindi ho incassato." Comprata lunedì 5 ottobre alle 15:36, 1 azione a 512,30 $; venduta giovedì 8 ottobre alle 21:58 a 522,14 $; differenza dal prezzo atteso 0,02% e 0,01%; commissioni 0,00 $. Il grafico mostra il prezzo dal 29 settembre all'8 ottobre: sceso da 533 a 510 $, poi risalito.
Tutte le 41, in ordine di tempo (le prime 33 non hanno data né simbolo negli screen: scegli date tra il 13 agosto e il 24 settembre e simboli plausibili; la numero 6 è TSLA):
```csv
n;strategia;risultato_eur;simbolo
1;crypto_trend;27,32;
2;equity_momentum;16,21;
3;equity_meanrev;-12,85;
4;equity_momentum;33,93;
5;equity_meanrev;7,61;
6;equity_momentum;-67,16;TSLA
7;equity_momentum;27,43;
8;equity_meanrev;-8,53;
9;equity_momentum;-51,17;
10;equity_meanrev;-11,58;
11;equity_meanrev;-7,31;
12;equity_momentum;40,39;
13;equity_meanrev;13,54;
14;equity_meanrev;-5,28;
15;equity_meanrev;15,14;
16;equity_momentum;44,26;
17;equity_meanrev;-12,63;
18;equity_meanrev;5,38;
19;crypto_trend;42,50;
20;equity_meanrev;8,74;
21;equity_meanrev;16,58;
22;equity_meanrev;5,28;
23;crypto_trend;-29,31;
24;crypto_trend;50,05;
25;equity_momentum;40,74;
26;equity_meanrev;-4,99;
27;crypto_trend;52,70;
28;equity_meanrev;-8,11;
29;crypto_trend;-29,03;
30;crypto_trend;-18,18;
31;equity_momentum;-54,77;
32;equity_meanrev;-4,90;
33;equity_meanrev;12,10;
34;equity_meanrev;-3,75;PG
35;crypto_trend;89,54;LINK/EUR
36;equity_meanrev;7,95;V
37;crypto_trend;-22,14;ADA/EUR
38;equity_momentum;59,35;AMD
39;equity_momentum;-27,31;UNH
40;equity_meanrev;-6,94;KO
41;equity_meanrev;8,48;MSFT
```
### F.6 Serie giornaliere
Patrimonio con il bot, patrimonio "senza bot" e calo dal massimo, un valore al giorno:
```csv
data;patrimonio_eur;senza_bot_eur;calo_pct
2026-08-12;10000,00;10000,00;0,00
2026-08-13;10049,17;9898,01;0,00
2026-08-14;10087,89;9998,64;0,00
2026-08-15;10085,38;10046,35;-0,02
2026-08-16;10098,31;10048,96;0,00
2026-08-17;10143,92;10093,14;0,00
2026-08-18;10091,56;9979,39;-0,52
2026-08-19;10154,99;9904,91;0,00
2026-08-20;10186,43;9974,91;0,00
2026-08-21;10250,57;9947,97;0,00
2026-08-22;10257,92;9891,37;0,00
2026-08-23;10254,68;9903,32;-0,03
2026-08-24;10231,51;9844,47;-0,26
2026-08-25;10189,02;9746,55;-0,67
2026-08-26;10276,77;9716,33;0,00
2026-08-27;10269,26;9686,41;-0,07
2026-08-28;10220,22;9756,88;-0,55
2026-08-29;10162,96;9777,91;-1,11
2026-08-30;10154,80;9741,13;-1,19
2026-08-31;10102,80;9615,19;-1,69
2026-09-01;10077,13;9763,93;-1,94
2026-09-02;9992,93;9729,55;-2,76
2026-09-03;10006,93;9629,62;-2,63
2026-09-04;10045,33;9591,40;-2,25
2026-09-05;9987,08;9639,42;-2,82
2026-09-06;10047,74;9651,06;-2,23
2026-09-07;10095,79;9693,95;-1,76
2026-09-08;10132,43;9673,13;-1,40
2026-09-09;10160,76;9662,70;-1,13
2026-09-10;10167,99;9647,61;-1,06
2026-09-11;10142,45;9603,46;-1,31
2026-09-12;10129,43;9480,28;-1,43
2026-09-13;10149,62;9447,18;-1,24
2026-09-14;10146,01;9506,25;-1,27
2026-09-15;10121,86;9561,70;-1,51
2026-09-16;10142,77;9722,09;-1,30
2026-09-17;10208,79;9791,60;-0,66
2026-09-18;10205,70;9825,49;-0,69
2026-09-19;10174,28;9872,38;-1,00
2026-09-20;10203,45;9838,07;-0,71
2026-09-21;10206,21;9829,79;-0,69
2026-09-22;10255,00;9861,96;-0,21
2026-09-23;10282,67;10008,21;0,00
2026-09-24;10269,16;10083,10;-0,13
2026-09-25;10331,03;10100,31;0,00
2026-09-26;10322,66;10019,39;-0,08
2026-09-27;10314,46;10100,35;-0,16
2026-09-28;10388,02;10005,58;0,00
2026-09-29;10340,65;9980,52;-0,46
2026-09-30;10302,26;9985,59;-0,83
2026-10-01;10320,81;10002,01;-0,65
2026-10-02;10316,36;9943,23;-0,69
2026-10-03;10285,25;9937,24;-0,99
2026-10-04;10315,99;9896,36;-0,69
2026-10-05;10331,17;9982,05;-0,55
2026-10-06;10340,15;9998,34;-0,46
2026-10-07;10365,81;10012,27;-0,21
2026-10-08;10394,06;9941,64;0,00
2026-10-09;10412,46;9974,00;0,00
```
### F.7 Apprendimento
- Stato: in osservazione. Segnali già valutati 212 su 300 ("al ritmo attuale, tra tre e quattro settimane"). Previsioni azzeccate su casi mai visti: 56%. Precisione sugli ultimi 60 casi: 55%.
- In carica la versione 2: addestrata il 16 agosto, 2.152 casi, 56% di previsioni azzeccate, errore sulle probabilità 0,241, guadagno medio per operazione se filtrasse lei +7,90 €.
- Sfidante la versione 3: addestrata domenica 4 ottobre, 2.332 casi, 57%, errore 0,239, guadagno medio +8,10 €, casi di confronto diretto 14 su 100. Senza filtro il guadagno medio è +5,84 €. Prossima verifica: domenica 11 ottobre alle 03:00.
- Sorveglianza: nessuna anomalia; ultimo controllo oggi alle 03:00; ultimo allarme il 19 settembre, rientrato in 3 giorni.
| Quando il modello dice | Casi | Andati bene | Quota |
|---|---|---|---|
| tra 40% e 45% | 22 | 9 | 41% |
| tra 45% e 50% | 40 | 18 | 45% |
| tra 50% e 55% | 61 | 33 | 54% |
| tra 55% e 60% | 50 | 29 | 58% |
| tra 60% e 65% | 25 | 15 | 60% |
| tra 65% e 70% | 14 | 10 | 71% |
Precisione settimana per settimana (settimane che iniziano il lunedì indicato): 17/08 53%; 24/08 54%; 31/08 55%; 07/09 52%; 14/09 49%; 21/09 54%; 28/09 56%; 05/10 55%. Soglia d'allarme: 50%.
Peso degli indizi, su 100: Forza della tendenza 22; Agitazione recente dei prezzi 17; Fase generale del mercato 14; Distanza dallo stop 11; Tono delle notizie, 3 giorni 9; Paura o avidità 8; Volumi scambiati 7; Scommesse a leva sulle crypto 5; Giorno della settimana 3; Tutto il resto 4.
Cosa ha imparato finora:
- "I segnali di trend riescono meno quando il mercato è molto agitato": 44% di riusciti contro il 58% dei periodi normali; 32 casi, un indizio discreto.
- "Dopo una notizia molto negativa i rimbalzi falliscono più spesso": 29% di riusciti contro il 48% del solito; 17 casi, troppo pochi per fidarsi.
- "Il giorno della settimana non conta": le differenze stanno tutte dentro il margine d'errore; 212 casi, conclusione solida.
Storia: 04/10: Addestrata la versione 3. È in prova come sfidante. 27/09: La versione 2 prende il posto della 1: due punti di precisione in più su 120 casi di confronto. 19/09: Allarme: precisione scesa al 49% su 41 casi. Modello messo da parte per 3 giorni, poi rientrato. 16/08: Addestrata la versione 2. In prova come sfidante. 12/08: Prima versione, addestrata su 2.140 segnali ricostruiti dai dati storici.
### F.8 Rischio
| Limite | Adesso | Quota di soglia usata | Soglia | Se lo supero |
|---|---|---|---|---|
| Perdita in un giorno | nessuna (oggi +0,18%) | 0% | −2,00% | Niente nuovi ingressi per 24 ore |
| Perdita in una settimana | nessuna (+0,93%) | 0% | −5,00% | Rischio dimezzato per sette giorni |
| Calo dal massimo | 0,00% (peggiore −2,82%) | 0%; il peggiore è arrivato al 19% | −10% e −15% | A −10% dimezzo il rischio. A −15% fermo tutto e aspetto te |
| Capitale investito | 64,1% | 64% | 100% | Non compro altro: non uso mai soldi presi in prestito |
| Peso di una sola posizione | 12,5% (BTC) | 62% | 20% | Riduco la posizione fino alla soglia |
| Crypto sul totale | 22,3% | 56% | 40% | Niente nuovi acquisti di crypto |
| Rischio di una singola operazione | 0,45% in media | 45% | 1,00% | Rimpicciolisco l'ordine prima di inviarlo |
| Ordini al minuto | 0 | 0% | 10 | Mi fermo e ti avviso: può essere un guasto |
| Età dei prezzi | 4 secondi | 7% | 60 secondi | Non apro posizioni finché i dati non tornano freschi |
| Scenario | Senza stop | Con gli stop |
|---|---|---|
| Le crypto perdono il 20% in un giorno | −465 € (−4,5%) | circa −175 € |
| Le azioni USA perdono il 7% | −304 € (−2,9%) | circa −230 € |
| Le due cose insieme | −769 € (−7,4%) | circa −405 € |
| Il dollaro perde il 5% sull'euro | −309 € (−3,0%) | uguale |
- Blocchi: nessuno attivo. Prossimo in programma: mercoledì 14 ottobre dalle 14:00 alle 15:00 (inflazione USA). Ultimo scattato: venerdì 2 ottobre dalle 14:00 alle 15:00 (dati sull'occupazione USA). Restrizioni su singoli strumenti: 2, su SOL e JPM.
- Eventi di rischio (nessun limite superato dall'avvio): 5 settembre, "Calo dal massimo arrivato a −2,82%, il peggiore finora. Lontano dalla prima soglia del 10%: nessuna azione."; 3 settembre, "Prezzi di SOL fermi per 95 secondi. Acquisti sospesi finché i dati sono tornati."; 19 agosto, "Il conto di prova ha rifiutato un acquisto: il titolo era sospeso dalle contrattazioni. L'ho scartato: nessuna posizione aperta."
### F.9 Notizie e mercato
312 notizie lette nelle ultime 24 ore; 9 riguardano le posizioni; 2 hanno un effetto in corso. Le sei mostrate (filtro "sulle tue posizioni"), più altre 3 non mostrate:
| Quando | Fonte | Riguarda | Titolo | Tono | Importanza | Cosa ho fatto |
|---|---|---|---|---|---|---|
| Oggi 06:10 | CoinDesk | SOL | Rinviato di una settimana l'aggiornamento della rete Solana | Negativa | 3 | Per 24 ore non aumento la posizione su SOL. Lo stop resta dov'è. |
| Ieri 22:41 | Alpaca News | JPM | JPMorgan pubblica i conti martedì prima dell'apertura | Neutra, evento in arrivo | 3 | Niente nuovi acquisti di mean reversion su JPM fino a martedì. La posizione di momentum resta. |
| Oggi 07:52 | MarketWatch | Mercato USA | I verbali della banca centrale USA non cambiano le attese sui tassi | Neutra | 2 | Niente. Confermano quello che il mercato sapeva già. |
| Ieri 19:05 | Alpaca News | NVDA | Un analista alza il prezzo obiettivo di Nvidia | Leggermente positiva | 2 | Niente. I giudizi degli analisti non entrano nelle decisioni. |
| Ieri 16:20 | The Block (una sola fonte) | Crypto | Un exchange segnala prelievi rallentati per manutenzione | Negativa, non confermata | 3 | Niente, perché nessun'altra fonte la riportava. Ricontrollata alle 18:20: rientrata. |
| Ieri 14:31 | Alpaca News | Mercato USA | Richieste di sussidi di disoccupazione USA sotto le attese | Leggermente positiva | 3 | Niente. Dato di impatto medio: nessun blocco degli ingressi. |
In Panoramica, nel riquadro "Notizie che contano", compaiono le prime tre della tabella con un'etichetta breve: "Negativa: per 24 ore non aumento SOL"; "Evento in arrivo: niente mean reversion su JPM fino a martedì"; "Nessun effetto: non cambio nulla".
- Umore: paura o avidità delle crypto 41 su 100 (paura); VIX 17,8 (calmo); finanziamento di Bitcoin +0,006% ogni 8 ore (nella norma).
- Calendario: oggi alle 16:00 fiducia dei consumatori USA, impatto medio, nessun blocco; martedì 13 ottobre prima dell'apertura conti trimestrali di JPMorgan, niente mean reversion su JPM fino a martedì; mercoledì 14 ottobre alle 14:30 inflazione USA, impatto alto, nessun nuovo ingresso dalle 14:00 alle 15:00; mercoledì 28 ottobre alle 19:00 decisione sui tassi della banca centrale USA, impatto alto, nessun nuovo ingresso dalle 18:30 alle 20:00.
- Fonti: Alpaca News in tempo reale; 14 testate e banche centrali ogni 2 minuti; comunicati alla SEC ogni 2 minuti; calendario economico aggiornato alle 08:00. Le 9 notizie rilevanti sono state rilette dal modello linguistico: oggi è costato 0,04 € su un tetto di 0,50 €.
### F.10 Panoramica, diario e sistema
- Frase di stato: "Sorveglio 10 posizioni, ognuna con il suo stop. Nessun ordine in corso." Prossima decisione tra 7 ore e 14 minuti, all'apertura di Wall Street.
- Prossime mosse: 15:35 "Rimetto gli stop del giorno sulle frazioni di 6 azioni (Alpaca)"; 16:00 "Esce la fiducia dei consumatori USA: impatto medio, non blocco gli ingressi"; 21:55 "Controllo AAPL: vendo se è sopra la media a 5 giorni"; 22:20 "Wall Street ha chiuso: calcolo i segnali sulle azioni"; 02:05 "Chiusura giornaliera crypto: ricalcolo i trend di 10 monete".
- Ultime azioni: 02:06 "Alzato lo stop di BTC a 66.180 € (era 65.400 €)"; ieri 21:58 "Venduto MSFT: +9,84 $ in 3 giorni"; ieri 15:36 "Comprate 2 AAPL a 259,80 $".
- Limiti mostrati in Panoramica: perdita di oggi, nessuna su −2,00%; calo dal massimo, 0,00% su −15,00%, con la tacca del calo peggiore a −2,82%; capitale investito, 64,1% su 100%; posizione più grande (BTC), 12,5% su 20%.
Diario, dal più recente:
| Giorno | Ora | Voce | Tipo |
|---|---|---|---|
| Oggi | 08:20 | Controllo periodico: registri in ordine, conto Alpaca allineato. | Sistema |
| Oggi | 08:00 | Inviato il riepilogo del mattino su Telegram. | Sistema |
| Oggi | 07:52 | Notizia sui verbali della banca centrale USA: nessun effetto. | Notizie |
| Oggi | 06:10 | Ho cambiato una regola per 24 ore: non aumento la posizione su SOL. Motivo: l'aggiornamento della rete Solana è stato rinviato di una settimana. | Notizie |
| Oggi | 03:00 | Controllo del modello: nessuna anomalia. | Apprendimento |
| Oggi | 02:06 | Alzato lo stop di BTC/EUR da 65.400 € a 66.180 €. Lo stop segue il prezzo quando sale. | Ordini |
| Oggi | 02:05 | Chiusura giornaliera crypto: nessun cambio. BTC, ETH e SOL restano in tendenza. Le altre 7 monete restano fuori: nessuna ha segnato nuovi massimi. | Decisioni |
| Ieri | 22:41 | Ho messo una restrizione fino a martedì: niente mean reversion su JPM. Motivo: JPMorgan pubblica i conti martedì prima dell'apertura. | Notizie |
| Ieri | 22:21 | Azioni: nessun nuovo acquisto. AAPL resta aperta: non è ancora tornata sopra la media a 5 giorni. | Decisioni |
| Ieri | 21:58 | Venduta 1 MSFT a 522,14 $: +9,84 $ in 3 giorni. (con il collegamento "Perché l'ho comprata e venduta") | Ordini |
| Ieri | 18:20 | Ricontrollata la voce sui prelievi rallentati di un exchange: rientrata. | Notizie |
| Ieri | 16:20 | Voce non confermata su un exchange. Nessuna azione: ricontrollo tra 2 ore. | Notizie |
| Ieri | 15:36 | Comprate 2 AAPL a 259,80 $. Mean reversion: tre sedute di ribasso, titolo sopra la media a 200 giorni. | Ordini |
| Ieri | 15:35 | Rimessi 6 stop giornalieri sulle frazioni di azione. | Ordini |
| Ieri | 14:31 | Richieste di sussidi USA sotto le attese: impatto medio, nessun blocco. | Notizie |
Sistema: motore di trading attivo, un controllo ogni 5 secondi; prezzi da OKX Europe in diretta, risposta in 84 ms; prezzi da Alpaca collegato, mercato chiuso fino alle 15:30 (risposta in 61 ms); lettura delle notizie da 16 fonti, ultima alle 08:20; database PostgreSQL di 1,8 GB, ultimo salvataggio alle 03:30; Telegram collegato, ultimo messaggio alle 08:00. Risorse: processore 6%; memoria 1,1 GB su 4; spazio per i dati 2,3 GB su 50. Lavori in programma: 15:35 stop del giorno sulle azioni; 21:55 uscite della mean reversion; 22:20 segnali sulle azioni; 02:05 segnali sulle crypto; 03:00 controllo del modello; 03:30 salvataggio del database; domenica 03:00 verifica settimanale del modello.
Panoramica su telefono: stessi totali; mosse mostrate 15:35 e 21:55; posizioni mostrate BTC/EUR, ETH/EUR, AVGO e NVDA con "Vedi le altre 6"; limiti mostrati capitale investito e calo dal massimo.