Files
Rail_Enterprise/docs/ARCHITECTURE.md
T
Alby96andClaude Opus 5.5 c1a0049bcf
CI / Build e test (pull_request) Successful in 1m20s
CI / Immagine Docker (pull_request) Successful in 37s
Infrastruttura: nome «Rail Enterprise», CI e rilasci su Gitea, documentazione
Il progetto adotta il nome «Rail Enterprise» ovunque (codice RailEnterprise.*,
variabili RE_*, intestazioni RESV/RECL, immagine rail-enterprise-server) per
allinearsi al repository Gitea. Aggiunge Gitea Actions sul modello di Chronos:
CI su PR e main, rilascio da tag con gioco Windows (client Godot + server in
server/), server Windows/Linux e immagine Docker nel registro Gitea, nightly.
Aggiunge i riferimenti visivi 06–09, i modelli di PR e issue, l'ADR 0014 e
aggiorna README (comandi locali), STATE e CLAUDE.md. 120 test verdi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 11:14:54 +01:00

130 lines
15 KiB
Markdown
Raw 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.
# Rail Enterprise — Architettura
Questo documento descrive come è fatto il codice. Va aggiornato a ogni fase: le parti non ancora implementate sono marcate *(pianificato, Fn)*.
## 1. Progetti e dipendenze
```
RailEnterprise.Core (net10.0; net8.0) simulazione deterministica, dati, mappa, economia, rete, salvataggi
RailEnterprise.Protocol (net10.0; net8.0) frame binari, messaggi, SpanWriter/SpanReader → Core
RailEnterprise.Server (net10.0, Web SDK) Kestrel, WebSocket, GameLoop, API HTTP, autosave → Core, Protocol
RailEnterprise.Tools (net10.0) railenterprise-tools: validate-data, genmap, profile, simulate, bench, smoke, replay → Core, Protocol
RailEnterprise.Tests (net10.0) harness interno, test di unità, scenari → Core, Protocol, Server
client/RailEnterprise.Client (Godot .NET) rendering, input, UI; anteprime con Core → Core, Protocol
```
Regole:
- Nessun `PackageReference` (controllato da `scripts/check-nuget.sh`). Il solo SDK esterno è `Godot.NET.Sdk` nel client, fuori dalla soluzione principale.
- Core e Protocol compilano anche per net8.0 perché il client Godot li referenzia direttamente: niente API successive a .NET 8 in questi due progetti (per esempio `System.Threading.Lock`).
- Il client non decide nulla: invia comandi, riceve stato, e usa Core solo per anteprime (profilo del binario, stime nei tooltip) che il server ricalcola.
## 2. Core: struttura dei namespace
| Namespace | Contenuto |
|---|---|
| `RailEnterprise.Core.Common` | `Rng` (xoshiro256**), `StableHash`, `XxHash64`, `DMath` (funzioni trascendenti deterministiche), `Money`, identità tipizzate, `Vec2`. |
| `RailEnterprise.Core.Time` | `GameClock`, `GameDate`, costanti di calendario. |
| `RailEnterprise.Core.Data` | Definizioni immutabili caricate da `data/*.json` (`GameData`), contesto JSON con source generator, validatore di schema e validatore semantico. |
| `RailEnterprise.Core.Map` | `Terrain` (altezze `ushort` in decimetri, tipi cella `byte`, larghezza dei fiumi), `MapGenerator` (ADR 0005), `ValueNoise`, `TerrainSampler`, `NameGenerator`, chunk 64×64. |
| `RailEnterprise.Core.Economy` | Città, industrie, hub, mercato, compagnie, registro contabile a partita doppia, finanza. |
| `RailEnterprise.Core.Rail` | `TrackGeometry` (raccordi), `TrackPlanner` (profilo a 25 m, opere, costi, tempi, vincoli per era), `RailNetwork` (nodi, archi campionati, stazioni, depositi, cantieri, indice spaziale), `Pathfinder` (A* sugli archi orientati), veicoli, treni, linee, pacchetti, `LineGraph` con maschere dei carichi (ADR 0007, 0008). |
| `RailEnterprise.Core.Commands` | Comandi di gioco (record immutabili) ed esiti. Sono l'unico modo di cambiare il mondo dall'esterno, anche per le IA. |
| `RailEnterprise.Core.Simulation` | `World`, `WorldContext`, `SystemPipeline` e `Systems/`, `WorldFactory`, `IndustryPlacer`, `CommandProcessor` e gestori dei comandi, `Corporate` (fusioni, liquidazioni, fine partita), `Estimators` (stime condivise da IA e tooltip), `ChronicleReport`, `Ai/` (agenti delle compagnie IA, ricerca del percorso sulle celle), eventi in uscita. |
| `RailEnterprise.Core.Persistence` | `SaveWriter`/`SaveReader`, `SaveFile` (Brotli), `StateHasher`. |
## 3. Il tick
`World.Tick()` esegue i sistemi in ordine fisso (`SystemPipeline.CreateDefault`) e poi avanza l'orologio. L'ordine della guida è:
```
Clock → Commands → Construction → Trains → Signals → Stations → Maintenance (treni)
→ Demand (giornaliero) → Commuting → Industries → IndustryMaintenance → Towns → Market
→ Finance → StockMarket → AiAgents (mensile) → Events → Contracts → Hash (giornaliero)
```
Sistemi implementati (F1–F5), nella loro posizione:
| Sistema | Frequenza | Cosa fa |
|---|---|---|
| `ClockSystem` | tick | calcola una volta gli indicatori di giorno, mese, trimestre, anno |
| `CommandSystem` | tick | drena la coda dei comandi (`CommandProcessor`), registra esiti ed eventualmente il log per il replay |
| `ConstructionSystem` | giorno | squadre e cantieri, usura e manutenzione del binario, ispezioni e invecchiamento di ponti e gallerie |
| `TrainSystem` | tick | percorsi, prenotazioni di blocchi, versi e binari di stazione fino al punto sicuro, fisica, soste, carico e scarico (`StationWork`), `Stalled` |
| `StationSystem` | giorno | bacini (mensili), scadenze dei pacchetti, consegne in attesa del consumatore, ritiro della produzione verso la destinazione migliore |
| `LocalTransportSystem` | giorno | trasporto locale su strada tra produttori, consumatori e hub entro 3 km (posto di «Stations», ADR 0004) |
| `FleetMaintenanceSystem` | giorno | usura per componente in km di servizio, rischio e guasti (lieve, grave con soccorso, deragliamento), pianificatore predittivo e prenotazioni, officine con stalli, ricambi e personale, riserve, avvisi (posto di «Maintenance», ADR 0010); formule senza stato in `Fleet` |
| `DemandSystem` | giorno | domanda delle città (con elasticità) e input richiesti dalle industrie |
| `EmploymentSystem` | giorno/mese | servizi cittadini, lavoratori in sede, contratti a piedi e su rotaia per industrie e depositi (`IWorkplace`, abbinamento mensile sul `LineGraph`), motivi dei posti scoperti, convenzioni, pacchetti giornalieri dei pendolari, presenze e coperture (posto di «Commuting», ADR 0008 e 0010) |
| `IndustrySystem` | giorno/trimestre/anno | produzione (nulla durante i fermi), esaurimento giacimenti, salari, crescita delle industrie servite, chiusure, nascite |
| `IndustryMaintenanceSystem` | giorno/mese | condizione degli impianti (usura con l'utilizzo, recupero del budget), consumo di ricambi, fermi e incidenti, revisioni e ammodernamenti in attesa di macchinari, scelte dei proprietari privati, conguaglio con il proprietario (ADR 0011) |
| `TownSystem` | giorno/mese/anno | consumo e soddisfazione, crescita, migrazione, espansione dell'abitato |
| `MarketSystem` | giorno | prezzi globali con componente mondiale e shock, domanda insoddisfatta |
| `FinanceSystem` | giorno/mese/anno | costi di esercizio di veicoli, stazioni e depositi, valori di libro, cassa negativa e bancarotta, rate dei prestiti, rating, livelli (`Tiers`), utile mensile nell'anello dei 12 mesi, chiusura dei conti |
| `StockMarketSystem` | giorno/mese/anno | prezzi e sentiment, valore delle partecipazioni, offerte pubbliche (adesioni, esito), controllo e utili delle controllate, amministrazione controllata del giocatore, fallimenti e aste, storico annuale, nuovi concorrenti (ADR 0012) |
| `AiSystem` | giorno/mese | agenti delle compagnie IA: progetti, stalli, offerte; una volta al mese (giorno diverso per IA) finanza, treni aggiuntivi, borsa, industrie, linee dei ricambi e nuovi progetti, tutto con i comandi (ADR 0013) |
| `HashSystem` | giorno | hash dello stato dinamico |
- Ogni sistema implementa `ISimSystem.Step(WorldContext ctx)`; i sistemi giornalieri o mensili controllano `ctx.IsNewDay` / `ctx.IsNewMonth` e ritornano subito negli altri tick: nei 239 tick su 240 lavora solo `TrainSystem`.
- `SystemPipeline.Profile` misura tempo e allocazioni per sistema (usato da `bench`).
- `WorldContext` espone il mondo, i dati e il calendario; gli eventi in uscita (notifiche, notizie) vanno in `World.Events`, che il server svuota.
- I comandi arrivano in una coda; il server la riempie dai socket e il sistema `Commands` la drena a inizio tick. Le IA eseguono i loro comandi direttamente con `CommandProcessor` dal sistema `AiAgents` (stesse validazioni, esito immediato, numeri di sequenza ≥ 0x80000000, non registrati per il replay: le IA si rigiocano da sole). Per il replay si registrano `(tick, comando)` in `World.CommandLog`.
- I flussi pseudo-casuali dei sottosistemi si ottengono con `World.Stream(nome)` (derivati dalla radice con `Rng.Fork`, salvati per nome).
## 4. Determinismo
Requisito: stesso seme + stessi comandi agli stessi tick ⇒ stesso hash di stato, su Windows e Linux.
- Un solo generatore pseudo-casuale, `Rng` (xoshiro256**), con un flusso per sottosistema ottenuto da `Fork(nome)`; i flussi fanno parte del salvataggio.
- Vietati nella simulazione: `System.Random`, `Guid.NewGuid`, `DateTime.Now`, `Environment.TickCount`, `string.GetHashCode`, iterazione su `Dictionary`/`HashSet` per produrre effetti, parallelismo che cambia l'ordine delle operazioni.
- Aritmetica in virgola mobile IEEE a doppia precisione solo con operazioni elementari (`+ − × ÷ √`), che .NET garantisce identiche su x64 e ARM64. Le funzioni trascendenti (`exp`, `log`, `pow`, `sin`, `cos`, `atan2`) passano da `DMath`, implementata in Core, perché le librerie C delle piattaforme possono differire nell'ultimo bit (ADR 0003).
- Denaro in `long` centesimi (`Money`); quantità di merci intere, con accumulatori frazionari per la produzione.
- Lo stato è in liste ordinate per id; i dizionari sono solo indici.
- `StateHasher` calcola ogni giorno un XxHash64 dello stato dinamico serializzato (il terreno, immutabile salvo opere, ha un proprio hash calcolato alla generazione e alle modifiche).
## 5. Dati
- File in `data/*.json`, schema in `data/schema/*.schema.json` (sottoinsieme di JSON Schema validato da Core senza librerie esterne), deserializzazione rigorosa (proprietà sconosciute vietate, proprietà `required`), validazione semantica (id univoci, riferimenti risolti, limiti) in `DataValidator` (ADR 0002).
- Caricamento con `System.Text.Json` e source generator (`DataJsonContext`), nessuna reflection.
- `GameData.Hash` (XxHash64 dei file normalizzati) viaggia nel `Welcome`: client e server devono avere gli stessi dati.
## 6. Economia e contabilità
- Entità in `RailEnterprise.Core.Economy`: `Town`, `Industry`, `Hub`, `ResourceSite`, `Company` (con `Loan`), `CommuteContract`, `Market`, `Tariffs`.
- Ogni movimento di denaro passa dal registro (`MoneyLedger.Transfer`) tra conti: compagnie, industrie e il conto `Esterno` (famiglie, clienti delle tariffe, mercato mondiale). La somma di tutti i saldi è sempre zero: è l'invariante «denaro» dei test. Le voci del conto economico delle compagnie (`LedgerEntry`) si accumulano per mese e per anno.
- Ogni unità di merce sta in un magazzino tracciato (industrie, città, pacchetti in stazione e a bordo dei treni) e `GoodsCounters` registra prodotto, consumato, deperito, importato, esportato: giacenza = prodotto + importato − consumato − deperito − esportato. È l'invariante «merci».
- Interpretazioni delle formule della guida: ADR 0004.
## 7. Salvataggi
- `SaveFile`: intestazione `RESV` leggibile senza decomprimere, corpo Brotli scritto da `WorldSerializer` con `SaveWriter` (little endian, nessuna reflection).
- Definizioni salvate per id testuale e rimappate al caricamento; terreno salvato per intero.
- `StateHasher` = XxHash64 di `WorldSerializer.WriteDynamic` (stato senza terreno, impostazioni ed eventi; il terreno entra con il suo hash). Dettagli: ADR 0006.
- Corpo versione 2 (F4): `MaintenanceSerializer` aggiunge in coda allo stato dinamico manutenzione di veicoli e treni, officine, politiche, convenzioni e motivi dei posti scoperti; i salvataggi della versione 1 si migrano (ADR 0010).
- Corpo versione 3 (F5): `CorporateSerializer` aggiunge manutenzione e proprietà delle industrie, libro dei soci, prezzi, controllo e storico delle compagnie, offerte, aste, fine partita e stato degli agenti IA (progetti, candidati scartati); i salvataggi precedenti si migrano (ADR 0012).
## 8. Server
- `ServerProgram`: Kestrel minimale, log JSON su stdout, configurazione da ambiente (`ServerConfig`: `RE_PORT`, `RE_TOKEN`, `RE_DATA_DIR`, `RE_TICK_MS`, `RE_AUTOSAVE_MIN`, `RE_SEED`, `RE_MAP_SIZE`, `RE_DIFFICULTY`, `RE_LOG_LEVEL`) e argomenti `--local` (127.0.0.1 su porta casuale, stampa `LISTENING porta`), `--healthcheck`, `--token`, `--port`, `--data`.
- `GameHost`: possiede il mondo su un thread dedicato. Ogni giro drena la coda delle azioni (messaggi delle sessioni, richieste HTTP), esegue i tick dovuti con un accumulatore (velocità 0/1/2/4/8, budget `RE_TICK_MS`), adegua la velocità effettiva se i tick costano troppo (`slow`), pubblica e fa l'autosave a rotazione.
- `Session` / `SessionEndpoint`: WebSocket su `/ws`, primo frame `Hello`, coda d'invio a due classi (affidabili e moti scartabili), ripresa con `sessionId` entro 120 s.
- `Projection`: mondo → record del protocollo (entità, archi, chunk, moto dei treni, resoconti, cartelle di manutenzione, registri officina, Registro degli impieghi); i delta per sessione si calcolano con gli hash dei record; i dettagli F4 si mandano su `RequestDetail`, gli avvisi di manutenzione (`World.Alerts`) come `MaintenanceAlert`.
- `SaveStore`: salvataggi `.vfsave` in `$RE_DATA_DIR/saves`, ultimi cinque automatici; all'avvio si riprende il più recente.
- HTTP: `/health`, `/metrics` (Prometheus), `GET/POST /api/saves`, `GET /api/saves/{id}`.
- Docker: `docker/Dockerfile` (build in due stadi, utente non root, healthcheck), `docker-compose.yml`, `unraid-template.xml`; `scripts/publish-image.sh` per il registry Gitea.
## 9. Client
- Progetto Godot 4.7 .NET in `client/RailEnterprise.Client` (fuori dalla soluzione), compilato con `Godot.NET.Sdk`; referenzia Core e Protocol (net8.0). I file dati e gli schemi si copiano in `res://data` a ogni build.
- `Main` → `MenuScreen` / `ConnectScreen` / `GameScreen`. `LocalServerLauncher` avvia il server come processo figlio per la partita locale.
- `GameSession` applica i messaggi a `ClientWorld` (Protocol) sul thread principale; i comandi sono l'unico modo di cambiare il mondo; le anteprime del tracciato usano `TrackPreview` di Core.
- `MapView` (Node2D + Camera2D): `TerrainLayer` (texture per chunk con fasce, ombreggiatura, sponde e curve di livello; shader per le rive), `EntityLayer` (case, industrie, stazioni, depositi, alberi in MultiMesh), `TrackLayer` (massicciata, traversine, rotaie, opere, cantieri, segnali), `TrainLayer` (veicoli interpolati, fumo, avvisi), `ToolOverlay`; `LabelLayer` disegna le etichette in coordinate schermo.
- HUD: `TopBar`, `Toolbar`, pannello destro (pannelli degli strumenti e schede) con `Minimap`, `Ticker`. Pannelli: binari con profilo, stazione, deposito, treni, linee, officine (politica della flotta, avvisi, flotta per condizione, cartella di manutenzione, Registro officina, scorta di ricambi, mappa di calore), impieghi (Registro degli impieghi e convenzioni), mercato, finanze, scheda dell'entità (con manutenzione del treno, lavoratori dell'industria, dove lavorano gli abitanti).
- Collaudo: pilota automatico (`-- --autopilot cartella`, `scripts/client-autopilot.sh`) con schermate.
## 10. Prestazioni
- Treni e pacchetti in liste di struct riutilizzate; nel tick ordinario si alloca meno di 1 KB (crescita delle liste), nessuna raccolta gen0 durante `bench`.
- Sistemi giornalieri e mensili distribuiti: i calcoli pesanti (abbinatore del pendolarismo, pianificatore di manutenzione, IA) girano una volta al giorno o al mese.
- Misure reali in `docs/STATE.md`.