diff --git a/docs/API-NOTES.md b/docs/API-NOTES.md index a7ebd94..34f3b34 100644 --- a/docs/API-NOTES.md +++ b/docs/API-NOTES.md @@ -157,6 +157,36 @@ Ogni fatto non verificabile resta dietro una protezione. I nomi delle impostazio | M3 velocità del classificatore | Misura nella Fase 7; sopra i 50 ms per titolo si segnala all'utente. | 7 | | V2 blocco ETF di Alpaca | Filtro ETF di Anubis attivo di base, indipendente dal broker. | 2 | | V3 fiscalità | Esportazione CSV delle operazioni con il cambio BCE. | 3 | +| Storia dei flag ETF e frazionabile | Gli universi passati usano i flag di oggi; il limite è scritto nel rapporto della prova storica. | 4 | +| Barre dei titoli tolti dalla borsa su Alpaca | Da controllare con le chiavi del conto di prova; fino ad allora gli universi passati vanno letti come ottimisti. | 2, 4 | +| Minuti senza scambi su OKX | Il buco si riscarica una volta, poi resta segnato come non recuperabile e non blocca nulla. | 2 | + +## Verifiche della Fase 2 (dati di mercato) + +Fatti controllati scrivendo gli adapter dei dati, il 10/11/2026. Le risposte registrate stanno in `tests/Anubis.Tests/Fixtures` e i test le leggono senza rete. + +| Fonte | Fatto | Come è stato verificato | +|---|---|---| +| OKX | `history-candles` con `1Dutc` dà lo storico giornaliero intero di BTC-EUR, ETH-EUR e SOL-EUR dal 21/11/2023: 1.085 giorni ciascuna, senza buchi né anomalie. | Prova reale `RealHistoryProof` (categoria LiveDemo) | +| OKX | Una candela con `confirm` = 0 è ancora aperta: lo storico la scarta e il flusso dal vivo la salva solo quando si chiude. | Risposte registrate di `candles` e del WebSocket | +| OKX | Finanziamento e open interest di BTC-USDT-SWAP rispondono senza chiave su eea.okx.com. | Risposte registrate | +| Alpaca | Con il piano gratuito una richiesta `feed=sip` che arriva a meno di 15 minuti fa risponde `{"code":42210000,"message":"subscription does not permit querying recent SIP data"}`. | Esempio della FAQ di Alpaca (`errors.md` nei fixture) | +| Alpaca | Le barre giornaliere hanno l'orario della mezzanotte di New York: il giorno della barra è la data di New York. `adjustment=raw` e `adjustment=all` si chiedono separatamente. | Esempi della documentazione | +| Alpaca | Le chiavi si leggono solo da `ALPACA_API_KEY_DEMO` e `ALPACA_API_SECRET_DEMO`, quelle del conto di prova. Senza chiavi nessuna chiamata parte verso Alpaca. | Test `ServerCollectsWithoutAlpacaKeysAndSaysWhatIsOff` | +| BCE | Lo storico completo è nello zip `eurofxref-hist.zip` (CSV dal più recente, virgola finale su ogni riga, `N/A` dove manca); poi basta il file a 90 giorni o quello giornaliero. | Risposte registrate | +| Forex Factory | Se al posto del JSON arriva una pagina di blocco, la lettura fallisce e conta come errore della fonte; il calendario già salvato resta. | Test | +| Fed e BCE | Calendari 2026–2027 letti dalle pagine ufficiali; la Fed avverte che ogni data è provvisoria fino alla riunione precedente. Per questo l'elenco è un'impostazione modificabile in Impostazioni → Dati. | `central-banks.md` nei fixture | +| alternative.me | Valori giornalieri con timestamp Unix in secondi. Anubis chiede 400 giorni la prima volta e poi solo gli ultimi 2. | Risposte registrate | +| nasdaqtraded.txt | La colonna ETF non segna molti ETN e nessun fondo chiuso: Anubis legge anche il nome del titolo. I codici delle borse comprendono ora anche `F` (Texas Stock Exchange) e `M` (NYSE Texas). | File del 10/11/2026 | +| Binance | Ogni zip mensile ha accanto un file `.CHECKSUM` con lo SHA-256; i timestamp passano dai millisecondi ai microsecondi da gennaio 2025. Il primo giorno di BTCUSDT è il 17/08/2017; il mese in corso non è ancora pubblicato. | Prova reale: 3.363 giorni dal 17/08/2017 al 31/10/2026 | + +**Distorsioni che restano negli universi a una data passata** +- I flag di oggi (frazionabile su Alpaca, ETF in `nasdaqtraded.txt`) valgono anche per le date passate: le fonti gratuite non hanno la storia di questi flag. +- Un titolo che ha cambiato simbolo è riconosciuto come fondo solo se il nome lo dice. +- Non è verificato che Alpaca dia le barre dei titoli tolti dalla borsa: se mancano, gli universi passati sono un po' troppo ottimisti (distorsione dei sopravvissuti). Si controlla con le chiavi del conto di prova. + +**Non verificabile senza scambi reali** +- Se OKX ometta i minuti senza scambi o li dia a volume zero. Il collector tratta un minuto mancante come buco, lo riscarica una volta e poi lo segna "non recuperabile, forse minuti senza scambi". ## Versioni di .NET e dei pacchetti ammessi diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index e5eb4d8..e5a9be6 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -86,22 +86,22 @@ Storico e dati dal vivo affidabili, controllati e senza sguardi in avanti. **Lavori** -- [ ] [#18](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/18) Catalogo degli strumenti e parte dati dell'adapter OKX Europe -- [ ] [#19](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/19) Parte dati dell'adapter Alpaca (piano gratuito) -- [ ] [#20](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/20) Collector storico e dal vivo, recupero dei buchi, controlli di qualità, freschezza -- [ ] [#21](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/21) Importatori: archivi Binance e CSV dell'utente verso lo storico di ricerca -- [ ] [#22](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/22) Calendari e cambi: calendario di borsa, EUR/USD BCE, calendario economico, trimestrali, umore -- [ ] [#23](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/23) Azioni societarie e serie rettificate ancorate al giorno della decisione -- [ ] [#24](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/24) Universi "a una certa data" con esclusione degli ETF -- [ ] [#25](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/25) Chiusura della fase, revisione indipendente e tag `fase-2` +- [x] [#18](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/18) Catalogo degli strumenti e parte dati dell'adapter OKX Europe +- [x] [#19](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/19) Parte dati dell'adapter Alpaca (piano gratuito) +- [x] [#20](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/20) Collector storico e dal vivo, recupero dei buchi, controlli di qualità, freschezza +- [x] [#21](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/21) Importatori: archivi Binance e CSV dell'utente verso lo storico di ricerca +- [x] [#22](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/22) Calendari e cambi: calendario di borsa, EUR/USD BCE, calendario economico, trimestrali, umore +- [x] [#23](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/23) Azioni societarie e serie rettificate ancorate al giorno della decisione +- [x] [#24](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/24) Universi "a una certa data" con esclusione degli ETF +- [x] [#25](https://gitea.encke-hake.ts.net/BalboSoft/Anubis/issues/25) Chiusura della fase, revisione indipendente e tag `fase-2` **Criteri di 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 risposte d'esempio, e il criterio resta in attesa dell'utente -- [ ] 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 +- [ ] Storico giornaliero delle crypto dall'inizio disponibile (coppie in EUR di OKX, più gli archivi Binance dal 2017) e delle azioni dal 2016 — **crypto fatto** (BTC, ETH e SOL in EUR dal 21/11/2023, BTCUSDT dal 17/08/2017); **azioni in attesa dell'utente** (chiavi del conto di prova Alpaca) +- [x] Senza chiavi Alpaca la parte azionaria si prova su dati sintetici e risposte d'esempio, e il criterio resta in attesa dell'utente +- [x] Un test stacca il flusso per 10 minuti e verifica che il buco venga recuperato +- [x] Rapporto di qualità dei dati +- [x] L'elenco dell'universo azionario a tre date passate non contiene ETF ## Fase 3 — Conti, ordini, contabilità diff --git a/docs/STATE.md b/docs/STATE.md index c8aeed4..77fe03e 100644 --- a/docs/STATE.md +++ b/docs/STATE.md @@ -4,7 +4,7 @@ Aggiornato: 2026-11-10 ## Fase corrente -**Fase 1 — Fondamenta: completata.** La prossima è la Fase 2 (Dati di mercato), da iniziare con il via dell'utente. +**Fase 2 — Dati di mercato: completata**, con la parte azionaria in attesa delle chiavi del conto di prova Alpaca. La prossima è la Fase 3 (Conti, ordini, contabilità), da iniziare con il via dell'utente. ## Fatto @@ -45,6 +45,15 @@ Aggiornato: 2026-11-10 - Immagine Docker definitiva: `PUID`/`PGID`, controllo di salute, l'applicazione non gira come root. Provata con SQLite, PostgreSQL, configurazione sbagliata e database staccato. - `tasks screenshots` per confrontare le schermate con i mockup. - Dopo la chiusura, con il permesso dell'utente: carattere Instrument Sans incluso nell'applicazione (ADR 0007, punto 5). +- **Fase 2** (scelte nell'ADR 0008, fatti verificati in `docs/API-NOTES.md`): + - Catalogo degli strumenti e parte dati degli adapter OKX Europe (coppie in EUR, candele, prezzi, libro, WebSocket) e Alpaca (barre consolidate reali e rettificate, minuti, calendario, orologio, azioni societarie, flusso IEX). + - Collector storico e dal vivo dentro il server: recupero dei buchi, controlli di qualità con seconda lettura immediata, freschezza dei dati, ripresa con attese crescenti. + - Storico di ricerca in file `csv.gz` per anno; importatori degli archivi Binance (con controllo SHA-256) e dei CSV dell'utente (`anubis data binance`, `anubis data csv`). + - Fonti gratuite: cambi BCE, calendario economico, date FRED e trimestrali Finnhub (con chiave facoltativa), riunioni di Fed e BCE modificabili, umore (Fear & Greed, VIX, finanziamento e open interest di OKX). + - Azioni societarie e serie rettificate ancorate al giorno della decisione. + - Universi azionario e crypto "a una certa data", senza ETF né fondi. + - Rapporto di qualità dei dati (`anubis data report`, `/api/data/quality`) e sezione Dati in Impostazioni con lo stato di ogni fonte. + - Prova sui dati reali: BTC, ETH e SOL in EUR dal 21/11/2023 (1.085 giorni ciascuna, nessun buco) e BTCUSDT di Binance dal 17/08/2017 (3.363 giorni). ## In corso @@ -52,7 +61,7 @@ Nulla. ## Prossimo passo -Fase 2, dati di mercato: storico e dati dal vivo, controlli di qualità, cambi del giorno. Servono le chiavi del conto paper di Alpaca (vedi sotto); senza, la parte azionaria si prova su dati sintetici. +Fase 3, conti, ordini e contabilità: simulatore interno, gestione degli ordini, stop di protezione, contabilità, riconciliazione. Servono le chiavi demo di OKX Europe e quelle del conto di prova Alpaca (vedi sotto); senza, la batteria di conformità gira su risposte d'esempio. ## Da sapere @@ -61,6 +70,9 @@ Fase 2, dati di mercato: storico e dati dal vivo, controlli di qualità, cambi d - `tasks dev` fuori da Docker usa la cartella dei dati vera dell'utente: per prove usa `tasks seed-demo`. - Alpaca non ha più conti senza margine: il divieto di leva lo impone Anubis (API-NOTES A14). - OKX: WebSocket sulla porta 443, la 8443 è chiusa (API-NOTES O3). +- Le coppie in EUR di OKX esistono da novembre 2023: prima di allora la storia crypto viene dagli archivi Binance in USDT, da convertire in euro nella Fase 4. +- I dati di mercato si spengono con `ANUBIS_MARKET_DATA=off`; nella modalità dimostrativa sono sempre spenti. +- Gli universi passati usano i flag ETF e "frazionabile" di oggi: è un limite delle fonti gratuite (API-NOTES, Fase 2). - Gitea ha un esecutore delle Actions attivo: la CI gira a ogni push (prima esecuzione: run 169 del branch `fase-0`, test verdi su SQLite e PostgreSQL). `tasks ci` resta per provarla in locale. - Su questo PC Docker Desktop non partiva: erano rimasti due file di comunicazione di una sessione di ottobre, che Windows non riusciva a cancellare. Le cartelle che li contengono sono state rinominate, non cancellate: `%LOCALAPPDATA%\Docker\run.stale*` e `%LOCALAPPDATA%\docker-secrets-engine.stale*`. Si possono eliminare dopo un riavvio. @@ -68,12 +80,12 @@ Fase 2, dati di mercato: storico e dati dal vivo, controlli di qualità, cambi d | Cosa | Da quando serve | Senza | |---|---|---| -| Via libera per la Fase 2 | Subito | Non si parte | -| Chiavi del conto paper di Alpaca | Fase 2 (dati azionari) | La parte azionaria si prova su dati sintetici; criteri in attesa | +| Via libera per la Fase 3 | Subito | Non si parte | +| Chiavi del conto paper di Alpaca (`ALPACA_API_KEY_DEMO`, `ALPACA_API_SECRET_DEMO`) | Già dalla Fase 2 (dati azionari) | Parte azionaria spenta; storico azionario dal 2016 in attesa | | Chiavi demo di OKX Europe | Fase 3 (ordini sui conti di prova) | Batteria di conformità su risposte d'esempio; criteri in attesa | | Un token Gitea con permesso `write:package` come segreto `REGISTRY_TOKEN` | Fase 9 (pubblicazione dell'immagine) | Pubblicazione a mano | | Token del bot Telegram e chat autorizzata (facoltativi) | Fase 6 | Test con un finto server | -| Chiavi FRED e Finnhub (facoltative, gratuite) | Fase 2 | Calendario limitato alla settimana corrente; filtro trimestrali spento | +| Chiavi FRED e Finnhub (facoltative, gratuite) | Già dalla Fase 2 | Calendario limitato alla settimana corrente; filtro trimestrali spento | | Chiave di un modello linguistico (facoltativa) | Fase 7 | Solo classificatore locale | | Prova del template su Unraid | Fase 9 | Criterio in attesa | | Permesso per ogni componente esterno non elencato nell'ADR 0004 | Quando serve | Si scrive in casa | diff --git a/docs/adr/0008-scelte-fase-2.md b/docs/adr/0008-scelte-fase-2.md new file mode 100644 index 0000000..c82e09f --- /dev/null +++ b/docs/adr/0008-scelte-fase-2.md @@ -0,0 +1,65 @@ +# 0008 — Scelte della Fase 2: dati di mercato + +Data: 2026-11-10 · Stato: accettata · Precisa la specifica (sezioni 4, 5.3, 6, 10.4) e gli ADR 0003 e 0007, senza aggiungere componenti esterni + +## Contesto + +La Fase 2 porta in Anubis i dati di mercato: catalogo degli strumenti, storico e flusso dal vivo, controlli di qualità, cambi, calendari, umore del mercato, azioni societarie e universi. Alcune scelte non sono scritte nella specifica, o la precisano. Le raccolgo qui. + +## Decisione + +**1. Storico di ricerca in CSV compresso, non Parquet.** +- La specifica (6.6) parla di file Parquet. Leggerli e scriverli richiede un pacchetto che l'ADR 0004 non elenca. +- Al suo posto: un file `csv.gz` per strumento, intervallo e anno, in `research/{mercato}/{simbolo}/{intervallo}/{anno}.csv.gz`. Usa solo `System.IO.Compression`, che fa parte di .NET. +- I prezzi restano nel testo decimale scritto dalla fonte: andata e ritorno dal file senza perdere cifre. Le prove storiche li convertono in `double` quando li leggono. +- Ogni file si scrive con un nome temporaneo e poi si sposta: un'interruzione non lascia mai mezzo file. +- Se un giorno servirà Parquet, si chiederà il pacchetto all'utente; il formato sta dietro `ResearchStore`. + +**2. Scritture idempotenti.** Barre, cambi, eventi e letture dell'umore si salvano con `INSERT … ON CONFLICT … DO UPDATE`, che entrambi i motori capiscono. Riscaricare lo stesso periodo non crea doppioni. + +**3. Dato anomalo: seconda lettura subito.** +- Un dato che non passa i controlli (prezzo zero o negativo, massimo sotto il minimo, salto improbabile) si salva come "sospetto" e si apre un problema. +- La fonte si interroga di nuovo subito per lo stesso periodo: + - stessi valori: il dato è **confermato**; + - valori diversi: i nuovi lo sostituiscono (**corretto**); + - nessun dato o ancora impossibile: il dato si scarta (**non recuperabile**). +- Un buco si riscarica una volta. Ciò che manca ancora resta segnato come non recuperabile ("forse minuti senza scambi") e non blocca nulla. +- I buchi al minuto si cercano solo per la crypto, che scambia sempre. Per le azioni il controllo dei minuti arriva con il flusso dal vivo (Fase 3). + +**4. Solo le coppie in EUR di OKX Europe.** Il catalogo tiene le coppie spot quotate in EUR. Le coppie in USDC (più profonde per le monete minori, API-NOTES O18) restano fuori finché la Fase 3 non verifica con le chiavi demo quali si possono davvero negoziare. + +**5. Alpaca solo con le chiavi del conto di prova.** +- Le chiavi si leggono da `ALPACA_API_KEY_DEMO` e `ALPACA_API_SECRET_DEMO`, mai da altre variabili. +- Senza chiavi la parte azionaria è spenta: nessuna chiamata parte verso Alpaca, e Impostazioni → Dati dice cosa manca. +- I criteri azionari della fase restano "in attesa dell'utente" e si provano su risposte d'esempio e dati sintetici. + +**6. Azioni societarie gestite.** Frazionamenti (diretti e inversi), dividendi in contanti, dividendi in azioni e cambi di simbolo. Gli altri tipi di Alpaca (unità, scorpori, fusioni) non si scaricano: un titolo che li subisce compare come salto nelle serie e il controllo dei salti lo segnala. + +**7. Fondi riconosciuti anche dal nome.** La colonna ETF di `nasdaqtraded.txt` non segna molti ETN e nessun fondo chiuso. Un titolo è escluso dall'universo azionario se il file lo segna come ETF, oppure se il nome contiene parole come "ETF", "ETN", "Fund", "Closed-End", "Beneficial Interest", "Index", "Leveraged", "Preferred", "Warrant", "Right", "Unit", "Notes" (l'elenco completo è in `NasdaqTraded`). Meglio escludere un'azione vera che comprare un fondo vietato (SPEC 4.6). + +**8. Universi a una data passata.** +- Azioni: NYSE e NASDAQ, frazionabili, non fondi, almeno 300 sedute di storia, ultima barra entro 7 giorni, chiusura reale sopra 10 $, le prime 150 per controvalore mediano su 60 sedute. +- Crypto: coppie in EUR quotate da almeno 400 giorni, controvalore mediano a 30 giorni sopra 250.000 €, spread mediano sotto 20 punti base (senza spread noto la coppia è esclusa), niente stablecoin, monete "wrapped" o token a leva; le prime 10. +- Si usano solo i dati fino alla data: un test lo verifica. +- Limite noto: i flag di oggi (frazionabile, ETF) valgono anche per il passato (API-NOTES, "Distorsioni che restano"). + +**9. I lavori lunghi in un esecutore a parte.** Il pianificatore esegue i lavori uno dopo l'altro. Lo scaricamento dello storico può durare ore, quindi i lavori del pianificatore svegliano soltanto un esecutore in sottofondo (`MarketDataService`), che fa un giro alla volta. + +**10. Dati di mercato spenti dove non servono.** +- Nella modalità dimostrativa, con `ANUBIS_MARKET_DATA=off` (o `0`, `false`) e nei test del server, salvo quelli che passano una rete finta. +- I test non toccano mai la rete. La prova sui dati reali (`RealHistoryProof`) sta nella categoria `LiveDemo`, esclusa dal giro normale. + +**11. Archivi Binance per la ricerca.** +- Si tengono le candele giornaliere in USDT di 25 monete dal 2017, per avere storia prima della nascita delle coppie in EUR (novembre 2023). +- Ogni zip si controlla con il suo SHA-256. Il giro si ripete al massimo ogni 25 giorni. +- La conversione da USDT a EUR, e la scelta di come usarle nelle prove, spetta alla Fase 4. + +**12. Flusso dal vivo solo per la crypto.** Il flusso WebSocket segue l'universo crypto (o BTC, ETH e SOL finché l'universo non c'è). Il flusso IEX delle azioni, limitato a 30 simboli, arriva con la Fase 3, quando ci sono le chiavi e le posizioni da seguire. + +**13. Calendario delle banche centrali modificabile.** La Fed avverte che le date sono provvisorie. L'elenco delle riunioni è un'impostazione (`calendar.central_banks`), con un valore iniziale letto dalle pagine ufficiali e un controllo del formato prima di salvarlo. + +## Conseguenze + +- Nessun componente esterno nuovo: l'elenco dell'ADR 0004 non cambia. +- Il rapporto di qualità (`anubis data report`, `/api/data/quality`) mostra per ogni strumento storia, buchi, anomalie e come sono finite, i problemi aperti e lo stato di ogni fonte. +- Le prove storiche della Fase 4 leggono dai file di ricerca, mai dal database.