Contributing e architettura

Questa guida è destinata agli sviluppatori che vogliono contribuire a Gäld o comprenderne gli aspetti interni.

Configurazione dell'ambiente di sviluppo

Docker (raccomandato)

git clone https://github.com/Scanix/Gaeld.git
cd Gaeld/api
cp .env.example .env
docker compose up -d
docker compose exec laravel.test php artisan gaeld:install --demo

L'app è disponibile su http://localhost:8080. Il flag --demo crea dati di esempio (fatture, spese, contatti) per lo sviluppo.

Servizi avviati da Docker Compose:

Servizio	Container	Porta
Laravel (PHP + Nginx)	laravel.test	8080
PostgreSQL 16	pgsql	5432
Redis 7	redis	6379
MeiliSearch	meilisearch	7700
Mailpit (email di sviluppo)	mailpit	8025 (dashboard), 1025 (SMTP)

Esecuzione dei comandi

Tutti i comandi PHP devono essere eseguiti all'interno del container Docker:

# Comandi Artisan
docker compose exec laravel.test php artisan <command>

# Composer
docker compose exec laravel.test composer <command>

# PHPStan
docker compose exec laravel.test ./vendor/bin/phpstan analyse

# Test
docker compose exec laravel.test php artisan test

Frontend

Il progetto API utilizza Inertia.js + Vue 3 per la sua interfaccia amministrativa:

pnpm install
pnpm dev    # Server dev Vite con HMR
pnpm build  # Build di produzione

Panoramica dell'architettura

Stack tecnologico

Livello	Tecnologia
Backend	Laravel 12, PHP 8.4
Frontend	Vue 3 + Inertia.js
Database	PostgreSQL 16
Cache/Queue/Session	Redis 7
Ricerca	MeiliSearch (fallback: database)
Calcolo monetario	BCMath (stringhe, mai float)

Struttura Domain-Driven

Il codebase è organizzato in domini sotto app/Domains/, ognuno dei quali incapsula una capacità aziendale:

app/Domains/
├── Accounting/      # Piano dei conti, libro mastro, registrazioni, IVA, budget
├── Api/             # Controller REST API, risorse, sistema webhook
├── Assets/          # Immobilizzazioni e ammortamenti
├── Banking/         # Conti bancari, importazione CAMT, riconciliazione
├── Contacts/        # Clienti, fornitori, persone di contatto
├── Expenses/        # Registrazione spese, categorie, workflow approvazione
├── Invoicing/       # Fatture, note di credito, fatture ricorrenti, pagamenti
├── Migration/       # Importazione dati da software contabili esterni
├── Organizations/   # Multi-tenancy, impostazioni org, onboarding
├── Payroll/         # Dipendenti, cedolini, deduzioni svizzere
├── Reporting/       # Report finanziari, esportazioni
└── Users/           # Autenticazione, profili, 2FA, passkey

Ogni dominio contiene tipicamente:

Domains/Invoicing/
├── Controllers/     # Controller HTTP
├── Models/          # Modelli Eloquent
├── Services/        # Logica di business
├── Queries/         # Query builder (filtri, ordinamento, ricerca)
├── Requests/        # Validazione Form request
├── Resources/       # Transformer risorse Inertia/API
├── Events/          # Eventi di dominio
├── Enums/           # Enum di stato, tipi
└── Policies/        # Policy di autorizzazione

Multi-tenancy

Gäld utilizza un modello database condiviso con isolamento a livello di riga:

• Ogni tabella dati ha una chiave esterna organization_id
• Il trait BelongsToOrganization aggiunge uno scope globale che filtra automaticamente le query e assegna automaticamente l'org alla creazione
• Il servizio CurrentOrganization mantiene l'org attiva per la richiesta corrente
• Il middleware EnsureHasOrganization risolve l'org dalla sessione (web) o dal token (API)

Trait principali

Trait	Scopo
BelongsToOrganization	Applica automaticamente lo scope a tutte le query sull'org corrente, assegna organization_id alla creazione
Auditable	Traccia le modifiche ai modelli nel log delle attività
HasUuids	Utilizza UUID come chiavi primarie

Feature flag

Le funzionalità sono controllate tramite variabili d'ambiente FEATURE_*:

Flag	Default	Descrizione
FEATURE_BANK_SYNC	false	Connessione bancaria e sincronizzazione automatica
FEATURE_AUTO_RECONCILIATION	false	Abbinamento automatico dei pagamenti
FEATURE_AUTOMATION	false	Motore di regole e automazione
FEATURE_MULTI_CURRENCY	false	Supporto multi-valuta
FEATURE_API_ACCESS	false	Accesso all'API REST
FEATURE_RULE_ENGINE	false	Motore di regole aziendali
FEATURE_SAAS	false	Funzionalità SaaS (plugin privato)

Sistema di plugin

I plugin estendono Gäld senza modificare il codice core. Consultate la Guida allo sviluppo dei plugin per i dettagli.

Testing

Gäld ha tre suite di test:

# Eseguire tutti i test
docker compose exec laravel.test php artisan test

# Eseguire una suite specifica
docker compose exec laravel.test php artisan test --testsuite=Feature
docker compose exec laravel.test php artisan test --testsuite=Unit
docker compose exec laravel.test php artisan test --testsuite=Security

# Eseguire un file di test specifico
docker compose exec laravel.test php artisan test --filter=InvoiceTest

Suite	Posizione	Scopo
Feature	tests/Feature/	Test di integrazione — richieste HTTP, database, full stack
Unit	tests/Unit/	Test unitari isolati — servizi, modelli, helper
Security	tests/Security/	Test di sicurezza — auth, permessi, CSRF, injection

Convenzioni di test

• Utilizzare l'attributo #[DataProvider('name')] (non l'annotazione @dataProvider)
• La validazione dei form web restituisce redirect 302 — verificare con assertSessionHasErrors()
• Tutti i test utilizzano un database di test in memoria (configurato in phpunit.xml)
• Helper di test e trait condivisi sono in tests/Traits/
• File fixture (XML CAMT di esempio, CSV) sono in tests/fixtures/

Analisi statica

docker compose exec laravel.test ./vendor/bin/phpstan analyse

PHPStan è configurato al livello 5 con una baseline in phpstan-baseline.neon.

Stile del codice

docker compose exec laravel.test ./vendor/bin/pint

Utilizza Laravel Pint per la formattazione del codice (basato su PSR-12).

Workflow dei contributi

1. Fate un fork del repository e create un branch da main
2. Configurate l'ambiente di sviluppo come descritto sopra
3. Apportate le modifiche — mantenete ogni PR focalizzato su un singolo tema
4. Aggiungete test per ogni nuovo comportamento
5. Eseguite i controlli prima del push:

   docker compose exec laravel.test php artisan test
   docker compose exec laravel.test ./vendor/bin/phpstan analyse
   docker compose exec laravel.test ./vendor/bin/pint --test

6. Aprite una pull request con una chiara descrizione del cosa e del perché

Per modifiche più ampie, aprite prima un issue per discutere l'approccio.

Messaggi di commit

Utilizzate messaggi di commit chiari e descrittivi. Aggiungete il prefisso del dominio quando pertinente:

invoicing: add recurring invoice frequency validation
banking: fix CAMT.053 duplicate detection
docs: update API reference with webhook events

Segnalare problemi

Aprite un issue su GitHub con:

• Un titolo e una descrizione chiari
• Passaggi per la riproduzione (se è un bug)
• Comportamento atteso vs. effettivo
• Il vostro ambiente (versione PHP, OS, browser)