Files
Anubis/docs/adr/0003-csharp-dotnet.md
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

81 lines
8.7 KiB
Markdown

# 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.