Marchi e Loghi (Brandings)

I Brandings sono preset riutilizzabili del look & feel aziendale applicato a ogni PDF che esce dalla piattaforma. Invece di incollare il logo e i colori in ogni report, configuri un brand una volta e ogni report lo referenzia tramite branding_id. Cambiare il logo è un solo click.

Riepilogo esecutivo

Il cambio di passo: un preset centrale del brand — il report di un cliente cambia look senza toccare la struttura; il brand di default si applica automaticamente a tutto ciò che la piattaforma genera.

A cosa serve

• Coerenza visuale — il PDF mensile di fatturazione ha esattamente lo stesso header del report settimanale di manutenzione.
• Multi-cliente — un fornitore di servizi di manutenzione tiene un branding per cliente con il proprio logo e colori.
• Rebrand indolore — nuova identità visuale, una modifica, tutto eredita.
• Default del tenant — se un report non specifica branding, si applica il default del tenant.

Come funziona

flowchart LR
  B[(brandings<br/>per-tenant)] -->|resolve by id| P[PDF generator]
  R1[Report on-demand] --> P
  R2[Report programmato] --> P
  R3[Agente IA genera PDF] --> P
  P --> F[PDF con header/footer/<br/>logo/colori]

Ogni report ha due modi per specificare il branding:

1. branding_id — referenzia un preset salvato. Ha priorità.
2. branding inline — dict con gli stessi campi, non salvato come preset.

Se nessuno dei due, si usa il branding con is_default=true del tenant (se esiste).

Parametri di un branding

Come usarlo

Creare un branding

1. Amministrazione → Marchi e Loghi → Nuovo.
2. Assegnare un nome ("Cliente Nord").
3. Caricare il logo (PNG/JPG, massimo 2 MB — ideale 300×100 px).
4. Impostare il nome aziendale visualizzato accanto al logo.
5. (Opzionale) Aggiungere linee dell'header — una per linea: divisione, telefono, sito web.
6. (Opzionale) Testo destro — es: "Confidenziale — non distribuire".
7. Scegliere i colori dell'header e del footer. L'editor mostra l'anteprima in tempo reale.
8. (Opzionale) Colore di accento per gli header delle tabelle.
9. Scegliere il font (Courier, Helvetica o Times).
10. (Opzionale) Marcarlo come default del tenant.
11. Salvare.

Il branding è pronto per essere referenziato dai report.

Usare un branding in un report

In un report on-demand:

• Aprire l'editor di report.
• Nel selettore Branding, scegliere il preset salvato.
• Generare. Il PDF esce con quel look.

In un report programmato:

• Modificare il report programmato.
• Selezionare il branding nel campo Branding.
• La prossima esecuzione lo applica.

Da un agente IA:

• Un agente WhatsApp o email che genera report può ricevere un branding_id nei suoi default. Alla generazione, il PDF esce con quel brand. Utile se lo stesso agente serve più clienti con brand diversi.

Marcare come default

Il branding con is_default=true viene applicato automaticamente a qualsiasi report che non specifichi branding_id o branding inline. È consentito solo uno default per tenant — marcarne uno nuovo smarca automaticamente il precedente.

Endpoint REST

POST   /api/v1/brandings          # creare
GET    /api/v1/brandings          # elencare
GET    /api/v1/brandings/{id}     # dettaglio
PATCH  /api/v1/brandings/{id}     # aggiornare
DELETE /api/v1/brandings/{id}     # eliminare

Casi d'uso

1 · Fornitore di servizi multi-cliente. Azienda che fa manutenzione per 12 impianti diversi. Ogni cliente ha il suo branding salvato: logo, colore aziendale, footer con numero di contratto. Ogni report mensile del cliente referenzia il suo branding_id. Il cliente C riceve il PDF con il suo brand; il cliente D con il suo. Zero lavoro di design.

2 · Rebrand aziendale. L'azienda cambia identità visuale. Nuovo logo, nuova palette. Invece di modificare 15 template di report: si modifica il branding "Aziendale" e si salva. La settimana successiva tutti i report programmati escono con il nuovo brand.

3 · Default del tenant + un caso speciale. Il tenant ha un branding "Standard" marcato come default: si applica a tutti i report on-demand e programmati. Un report specifico — l'audit annuale per il cliente top — porta il suo branding_id con il logo co-branded. Tutto il resto eredita il default senza configurare nulla.

Limiti e assunzioni

• Un branding per tenant può essere is_default. Marcarne uno nuovo smarca automaticamente il precedente.
• Il logo deve essere pubblico — il PDF generator fa un fetch HTTP del logo_url. Se il logo è dietro auth o in un bucket privato, il report esce senza logo. Caricare su GCS pubblico o su un CDN.
• Colori hex a 6 cifre. #FFF (3 cifre) o red (nome) non validano. Usare #FFFFFF.
• Nessun gradiente o immagine di sfondo. Solo colori solidi. Per un header grafico, il logo è l'unico componente visuale.
• Font families limitate a 3. Courier / Helvetica / Times. Nessun font custom — sono gli standard di fpdf2 per garantire compatibilità con qualsiasi lettore PDF.
• Dimensione del logo: nessuna validazione automatica. PNG molto grandi gonfiano il PDF senza migliorare la qualità. Ideale 300×100 px ottimizzato.

Vantaggi chiave

• Un preset centrale → coerenza visuale automatica su ogni PDF.
• Rebrand in secondi — modifichi il branding, tutti i futuri report ereditano.
• Multi-cliente senza sforzo — un branding per cliente, branding_id seleziona.
• Default del tenant elimina decisioni banali quando configuri un report nuovo.
• Anteprima in tempo reale nell'editor — vedi header/footer mentre imposti.
• Compatibile con report on-demand, programmati e generati da agenti IA.