Files
Anubis/docs/adr/0003-csharp-dotnet.md
T
Alby96andClaude Opus 5.5 f4cd411ab6 docs: switch to C# .NET 10, restrict external components, new scale logo
The user prefers C# and asked for no SDKs or extra components without
permission. Speed is not a factor at this trading frequency and Python's
advantages were exactly the SDKs now excluded, so ADR 0003 adopts the
appendix D variant with Blazor instead of React, in-house broker clients,
ADO.NET, .csv.gz research storage, a C# task runner instead of make and an
in-house Windows installer instead of Inno Setup.

ADR 0004 lists the only packages the user authorized (Microsoft.Data.Sqlite,
ProtectedData, WebView2, MSTest, Npgsql, ML.NET with LightGBM/FastTree,
ONNX Runtime, Tokenizers) and the ask-first rule for anything else.

ADR 0005 records why the bot is called Anubis (he weighs and protects) and
replaces the two-semicircle mark with the scale of the weighing of the
heart: SVG, PNG, ICO and Unraid icon, applied to all nine screens.

CLAUDE.md, SVILUPPO, STATE, README, ROADMAP and templates follow; the 84
Gitea issues were rewritten to match and verified against the source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 13:06:39 +01:00

8.7 KiB

0003 — Anubis si scrive in C# su .NET 10

Data: 2026-11-09 · Stato: accettata

Contesto

La sezione 3 della specifica sceglie Python perché lì stanno le librerie più mature per broker e apprendimento automatico. L'appendice D prevede una variante C#/.NET da usare se l'utente la chiede. L'utente conosce meglio C# e ha posto due vincoli:

  • nessun SDK né componente aggiuntivo senza il suo permesso (ADR 0004);
  • niente da installare su Windows e su Unraid per far girare il bot.

Valutazione:

  • Velocità. Non decide nulla. Il bot lavora su candele, ribilanciamenti e ordini a frequenza bassa; il tempo se ne va nelle chiamate ai broker, non nel calcolo. Backtest e addestramento sono più veloci in C#, ma sarebbero accettabili anche in Python.
  • Motivi tecnici per Python. Non ce ne sono più. I vantaggi di Python erano alpaca-py, ccxt e l'ecosistema scikit-learn, cioè proprio gli SDK e i componenti che il vincolo esclude. Senza di quelli, i client verso Alpaca e OKX si scrivono a mano in entrambi i linguaggi. L'apprendimento ha un equivalente Microsoft (ML.NET con LightGBM), che l'utente ha autorizzato.
  • Distribuzione. C# è nettamente meglio:
    • su Windows esce un eseguibile autosufficiente, che non chiede di installare nulla;
    • in Docker si usa l'immagine ufficiale mcr.microsoft.com/dotnet/aspnet:10.0;
    • in Python servirebbe impacchettare l'interprete con PyInstaller, che spesso fa scattare gli antivirus.

Decisione

Vale l'appendice D della specifica, con gli adattamenti chiesti dall'ADR 0004 (nessun componente esterno non autorizzato). Le righe qui sotto sostituiscono quelle della sezione 3; tutto il resto della specifica vale identico.

Tema Scelta
Linguaggio C# su .NET 10 (versione LTS), Nullable attivo, analizzatori .NET con avvisi trattati come errori
Web/API ASP.NET Core: API REST (minimal API) e un canale WebSocket. Il motore è un BackgroundService nello stesso processo. Il processo di guardia di 9.3 è un piccolo eseguibile a parte che fa da genitore al motore
Interfaccia Blazor con rendering interattivo lato server, già compreso in ASP.NET Core: niente React, niente Node, niente pacchetti npm. Grafici, misuratori e sparkline sono componenti SVG scritti in casa. Le regole (soldi veri, conferme, permessi) stanno nel livello dei servizi, usato sia dalle pagine sia dall'API: il controllo vale anche fuori dalla schermata (12.4)
Concorrenza Un solo scrittore sul database. I lavori pesanti (addestramento, backtest) girano in thread dedicati a priorità bassa e restituiscono i risultati al motore, che li scrive
Database PostgreSQL con Npgsql oppure SQLite con Microsoft.Data.Sqlite, stesso schema (5.4). Accesso con ADO.NET e una mappatura scritta in casa, senza EF Core né Dapper. Migrazioni: file SQL numerati, applicati da un esecutore scritto in casa e provati su entrambi i motori
Numeri decimal per prezzi, quantità e denaro; double solo nell'analisi. Su PostgreSQL NUMERIC(38,18), su SQLite testo. Attenzione: decimal di C# tiene circa 28 cifre significative, quindi i valori si arrotondano a 18 decimali e un test controlla i casi estremi (prezzi crypto minuscoli per quantità enormi)
Broker Client scritti in casa su HttpClient e ClientWebSocket: Alpaca con chiave e segreto nelle intestazioni, OKX con firma HMAC-SHA256 e intestazione del demo. Niente Alpaca.Markets e niente ccxt
Storico per la ricerca File .csv.gz, uno per strumento e per anno, sotto /data/research, letti e scritti con GZipStream (già nel framework). Niente Parquet
Apprendimento ML.NET con Microsoft.ML.LightGbm; regressione logistica di ML.NET come riferimento; foresta casuale (Microsoft.ML.FastTree) come sfidante; 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 e Microsoft.ML.Tokenizers con lo stesso modello ONNX della specifica; si controlla che il tokenizzatore dia gli stessi identificativi dell'originale. Feed RSS e Atom letti con System.Xml.Linq, senza System.ServiceModel.Syndication
Accesso Password con PBKDF2 (Rfc2898DeriveBytes.Pbkdf2, SHA-512) al posto di Argon2id; codice a due fattori scritto in casa (RFC 6238) con test sui vettori ufficiali
Segreti su desktop DPAPI (ProtectedData) su Windows; ANUBIS_SECRET_KEY in Docker; altrove un file con permessi ristretti, segnalato nell'interfaccia
Configurazione d'avvio su desktop Resta config.toml, come nella specifica (15.6). Il parser è scritto in casa e capisce solo il sottoinsieme che serve: sezioni, testi, numeri, vero/falso
Qualità MSTest per i test; test basati su proprietà con un piccolo generatore casuale a seme fisso, scritto in casa; niente xUnit, FsCheck, Playwright
Schermate Le fotografie per il confronto con docs/design/ si fanno con Microsoft Edge in modalità senza finestra (msedge --headless --screenshot), già presente in Windows, a 1440 e 390 pixel. Dove Edge non c'è (CI Linux) il confronto si fa nella sessione Windows e lo si dice nella prova
Distribuzione Docker Immagine multi-stage: mcr.microsoft.com/dotnet/sdk:10.0 per la build, mcr.microsoft.com/dotnet/aspnet:10.0 per l'esecuzione, più libgomp1 richiesto da LightGBM. Si verifica che l'immagine carichi le librerie native di LightGBM e ONNX Runtime
Applicazione desktop Lo stesso codice pubblicato come eseguibile autosufficiente (dotnet publish -r win-x64 --self-contained). Finestra WinForms con WebView2 (il runtime è già in Windows 11; se manca si apre il browser predefinito). Icona nell'area di notifica con NotifyIcon, istanza unica. Su macOS e Linux si avvia il server da sorgente e si usa il browser
Installatore Windows Scritto in casa (Anubis.Setup): un eseguibile che contiene l'applicazione e la installa per l'utente corrente in %LOCALAPPDATA%\Programs\Anubis senza permessi di amministratore. Crea le scorciatoie, si registra tra i programmi installati con la propria disinstallazione e lascia intatta la cartella dei dati. Niente Inno Setup
Comandi del progetto Niente make, che su Windows non c'è. I comandi sono un piccolo programma C#, tools/Anubis.Tasks, richiamato da tasks.ps1 (Windows) e tasks.sh (Linux): tasks check, tasks dev, tasks test, tasks build, tasks ci, tasks seed-demo, tasks desktop-win
CI su Gitea Il flusso .gitea/workflows/ci.yml usa solo passi run: (git, dotnet, docker), senza azioni esterne scaricate da GitHub

Struttura del repository, al posto di quella di 5.1. La Fase 0 la rifinisce e la fissa:

anubis/
  Anubis.slnx  Directory.Build.props  Directory.Packages.props  tasks.ps1  tasks.sh
  .gitea/workflows/ci.yml
  docs/            come nella specifica
  src/Anubis/          libreria: Core, Platform, Db, Brokers, Data, News, Strategies, Portfolio,
                       Risk, Execution, Accounting, Ml, Backtest, Journal, Notify, Demo (una cartella
                       e un namespace per ogni modulo di 5.1)
  src/Anubis.Server/   ASP.NET Core: API, WebSocket, autenticazione, interfaccia Blazor, motore
  src/Anubis.Guard/    processo di guardia (9.3)
  src/Anubis.Desktop/  finestra WebView2, area di notifica, istanza unica
  src/Anubis.Setup/    installatore Windows
  tests/Anubis.Tests/  categorie Unit, Integration, Simulation, LiveDemo, Golden
  tools/Anubis.Tasks/  comandi del progetto
  deploy/          docker/Dockerfile  unraid/anubis.xml  unraid/anubis-icon.png

Le interfacce di 5.3 si riscrivono come interface C# con gli stessi metodi e gli stessi significati.

Alternative scartate

  • Restare su Python. I suoi vantaggi sono le librerie che il vincolo esclude, e la distribuzione su Windows è più fragile.
  • Interfaccia React come nell'appendice D. Porterebbe Node e centinaia di pacchetti npm, cioè proprio i componenti aggiuntivi da evitare.
  • Blazor WebAssembly. Richiede pacchetti in più e scarica il runtime nel browser. Per un solo utente il rendering lato server basta ed è già nel framework.
  • EF Core. È di Microsoft ma non è tra i pacchetti autorizzati. Con ADO.NET lo schema si controlla meglio sui due motori.

Conseguenze

  • Le 84 issue su Gitea e docs/ROADMAP.md sono stati riscritti con i nuovi strumenti; contenuto delle fasi e criteri di accettazione non cambiano.
  • Dove la specifica nomina strumenti Python (uv, FastAPI, Alembic, pytest, make, frontend/src/lib/format.ts …), vale l'equivalente di questa tabella. Per esempio la formattazione dei numeri sta in src/Anubis/Core/Format.cs.
  • I client dei broker scritti in casa costano più lavoro nelle Fasi 2 e 3, ma si testano meglio. La batteria di conformità di 7.5 resta l'arbitro.
  • Per sviluppare servono solo .NET 10 SDK, Docker (per PostgreSQL nei test e per l'immagine) e git.