# NetGescon - Macchina Git e Distribuzione (Blueprint 2026)

Obiettivo: una piattaforma unica per piu progetti con:

- repository Git self-hosted,
- distribuzione aggiornamenti,
- accesso selettivo con scadenza,
- moduli premium con pagamento.

## Scelta consigliata

Stack consigliato:

- Forgejo (o Gitea) per Git, issue, release e accessi team.
- API Update/Licensing separata (Laravel) per manifest, package, code/auth e policy licenza.
- MinIO per storage pacchetti release e asset aggiornamenti.
- Reverse proxy (Caddy o Nginx) con TLS e domini separati.
- Keycloak opzionale se vuoi SSO enterprise multi-progetto.

## Perche Forgejo/Gitea

1. Leggero rispetto a GitLab e facile da mantenere.
2. Multi-progetto nativo con org/team/permessi granulari.
3. Runner CI disponibili per pipeline build package.
4. Facile integrazione con API esterne per licenze e billing.

## Architettura consigliata

- `git.netgescon.it`: Forgejo UI/API/SSH.
- `updates.netgescon.it`: API update/licensing (manifest/package/license).
- `storage.netgescon.it`: MinIO S3 (privato, firmato).
- `registry.netgescon.it` opzionale: container registry.

## Modello accessi aggiornamenti

Canali:

- `free`: accesso manifest/package pubblico o con token base.
- `licensed`: accesso con `code+auth` e controlli avanzati.

Controlli raccomandati:

- scadenza licenza (`expires_at`),
- limite nodi (`max_nodes`),
- modulo abilitato (`modules[]`),
- versione minima consentita (`min_supported`),
- revoca immediata (`revoked_at`).

## Modello commerciale moduli premium

Dati minimi backend licenze:

- `customers`
- `licenses`
- `license_modules`
- `payments`
- `entitlements_audit`

Flusso:

1. Cliente acquista piano base o modulo.
2. Payment provider invia webhook.
3. Sistema aggiorna entitlement e scadenza.
4. Nodo client chiama endpoint license-check.
5. Feature gate lato app abilita/disabilita moduli.

Provider pagamento consigliati:

- Stripe (piu rapido per subscription e webhook).
- Paddle se vuoi gestione VAT UE piu assistita.

## Sicurezza minima obbligatoria

1. 2FA obbligatoria per admin Forgejo.
2. Backup giornaliero DB+repository+bucket MinIO.
3. Firma manifest release (Ed25519) e verifica lato client.
4. Logging audit su download package e apply update.
5. Secrets solo da vault/env sicuri, mai nel repo.

## Setup rapido locale

La base Docker e in:

- `scripts/ops/git-stack/docker-compose.yml`
- `scripts/ops/git-stack/.env.example`

Avvio:

```bash
cd scripts/ops/git-stack
cp .env.example .env
# modifica password, domini e secret

docker compose --env-file .env up -d
```

## Roadmap operativa consigliata

1. Porta online Forgejo + TLS + backup.
2. Crea org/progetti NetGescon e branch policy.
3. Attiva API update/licensing su `updates.netgescon.it`.
4. Pubblica primo pacchetto baseline e manifest firmato.
5. Aggiorna staging con `php artisan netgescon:update --apply`.
6. Integra billing moduli premium (Stripe webhook).
7. Estendi stessa piattaforma agli altri progetti.