Skip to content

dev-guide.md

Latest commit

 

History

History
164 lines (123 loc) · 6.11 KB

dev-guide.md

File metadata and controls

164 lines (123 loc) · 6.11 KB
Raw

Guida Operativa per lo Sviluppo

Guida pratica e comandi essenziali per sviluppatori che lavorano sulla repository di CardMaker.

1. Prerequisiti

  • .NET 10 SDK (versione 10.0.100 o superiore).
  • Dipendenze native (su Linux): libwebkit2gtk-4.1-0, libfontconfig1, libfreetype6.

Verifica installazione:

dotnet --version

2. Script di Avvio Rapido

La root del repository contiene script pronti all'uso con gestione automatica di pulizia binari, ripristino pacchetti e build:

Linux / macOS

# Avvio dell'applicazione Desktop nativa (Photino.Blazor)
./run-desktop.sh

# Avvio dell'applicazione Web (Kestrel su http://localhost:5240)
./run-web.sh

Windows

:: Avvio Desktop nativo
run-desktop.bat

:: Avvio Web (http://localhost:5240)
run-web.bat

3. Comandi CLI Manuali

# 1. Ripristino dei tool locali (dotnet-ef)
dotnet tool restore

# 2. Ripristino dei pacchetti NuGet
dotnet restore CardMaker.slnx

# 3. Compilazione della solution (TreatWarningsAsErrors attivo)
dotnet build CardMaker.slnx

# 4. Esecuzione dell'intera suite di collaudo (200 test)
dotnet test CardMaker.slnx

# 5. Avvio manuale host Web
dotnet run --project src/CardMaker.Web/CardMaker.Web.csproj --urls http://localhost:5240

# 6. Avvio manuale host Desktop
dotnet run --project src/CardMaker.Desktop/CardMaker.Desktop.csproj

4. Gestione Database ed EF Core Migrations

Le migrazioni del database vengono applicate automaticamente all'avvio dell'applicazione tramite DatabaseInitializer.

Per generare una nuova migrazione dopo modifiche al modello di dominio:

dotnet ef migrations add <NomeMigrazione> \
  --project src/CardMaker.Infrastructure \
  --startup-project src/CardMaker.Web \
  --output-dir Persistence/Migrations

Per applicare le migrazioni manualmente al database locale:

dotnet ef database update \
  --project src/CardMaker.Infrastructure \
  --startup-project src/CardMaker.Web

5. Primo Avvio e Credenziali di Default

Al primo avvio, se il database non contiene alcun account, viene creato automaticamente l'amministratore con le seguenti credenziali predefinite:

  • Email: admin@cardmaker.local
  • Password: Admin123!456 (oppure definita in Bootstrap:AdminPassword)

Note

Nell'host Desktop l'autenticazione è gestita dal provider in-process DesktopAuthenticationStateProvider: l'utente entra direttamente come amministratore senza necessità di credenziali.

6. Struttura dei Dati Locali

Tutti i dati generati localmente sono conservati nella directory specificata da Storage:DataRoot (predefinita in sviluppo: <repo>/data o percorsi utente OS in produzione):

data/
├── CardMaker.db          # Database SQLite in modalità WAL
├── CardMaker.db-wal      # File WAL per letture concorrenti
├── CardMaker.db-shm      # File di memoria condivisa SQLite
├── ai-settings.json      # Configurazione motore AI locale (modello attivo, parametri)
├── models/               # Modelli LLM quantizzati GGUF (scaricati all'avvio)
│   └── gemma-2-2b.gguf
└── assets/               # Archivio binario content-addressed (SHA-256)
    └── ab/
        └── cd/
            └── abcdef...bin

Per ripristinare completamente l'ambiente da zero è sufficiente eliminare la cartella data/ o il database. All'avvio successivo il seeder ripopolerà i dati e i template base per tutti i giochi.

7. Pagine e Rotte Applicative

Rotta Accesso Descrizione
/ Pubblico Home page di benvenuto e panoramica
/cards Autenticato Collezione "Le mie carte" (filtri, ricerca, duplicazione, eliminazione)
/cards/create Autenticato Creazione guidata nuova carta con selettore gioco e tipo
/cards/edit/{id} Autenticato Editor carta dinamico con anteprima 60 FPS, export e generazione testi AI
/guida Pubblico Guida utente sui campi e sintassi token {sym:...}
/disclaimer Pubblico Note legali e clausola fan-made non commerciale
/admin/content Admin Gestione CRUD giochi, tipi, tratti, simboli, liste opzioni
/admin/schema/{id} Admin Editor interattivo dello schema campi del tipo carta
/admin/templates/{id} Admin Template Studio WYSIWYG a 3 pannelli per la composizione dei layer
/admin/ai Admin Gestione motore AI: profili RAM, download modello con resume, parametri inferenza
/admin/assets Admin Libreria asset con upload multiplo, filtri per gioco e safe delete
/admin/fonts Admin Catalogo font con registrazione TTF/OTF per alias di ruolo
/admin/placeholders Admin Generatore procedurale di frame e simboli segnaposto
/admin/audit Admin Registro immutabile di audit log
/admin/invitations Admin Gestione inviti e token SHA-256 a tempo
/admin/backups Admin Snapshot online SQLite (VACUUM INTO) con integrity check
/admin/render-test Admin Banco di collaudo interattivo per il motore SkiaSharp
/healthz Sistema Endpoint di monitoraggio per container / reverse proxy

8. Workflow CI/CD e Packaging

Il repository adotta workflow nativi per GitHub Actions:

  • Fast CI (.github/workflows/ci-fast.yml):
    • Trigger: ogni push e pull_request su main o feature branch.
    • Verifica compilazione con TreatWarningsAsErrors=true e lancia il sottoinsieme di test essenziali: 
      dotnet test CardMaker.slnx -c Release --filter "FullyQualifiedName!~GoldenImageTests"
  • Release Pipeline (.github/workflows/release.yml):
    • Trigger: push di tag v* (es. git tag v1.0.0 && git push origin v1.0.0) o trigger manuale da interfaccia GitHub (Actions → Release → Run workflow).
    • Esegue la compilazione su runner windows-latest e ubuntu-latest.
    • Produce:
      • Installer Windows Inno Setup: packaging/windows/installer.iss
      • Pacchetto Debian Linux .deb: packaging/linux/build-deb.sh
      • Archivi portatili .zip e .tar.gz (Self-Contained e Framework-Dependent).
      • Checksum crittografici SHA256SUMS.txt.
      • GitHub Release automatica con asset pronti al download.