Manuale Template - Document Engine¶

Questo manuale descrive come creare, mantenere e pubblicare template per il microservizio document-engine.

Obiettivi del manuale¶

Garantire template consistenti, versionabili e stabili nel tempo
Evitare errori in fase di merge dei dati JSON
Ridurre i problemi in conversione DOCX → PDF
Standardizzare lo sviluppo di template DOCX e ReportLab

1) Concetti base¶

1.1 Template¶

Un template e' un file con segnaposto e strutture dinamiche. Il motore sostituisce i segnaposto usando il context JSON.

1.2 Document Type¶

document_type e' una label funzionale (es. ras, rapportino, dvr). Serve per scegliere il template e l'engine.

1.3 Engine¶

docx: merge JSON → DOCX (e opzionale conversione PDF)
reportlab: PDF nativo generato da Python
convert: usato internamente per DOCX → PDF

1.4 Versioning template¶

Regola consigliata: - ras_base_v1, ras_base_v2, rapportino_base_v1 - non sovrascrivere versioni gia' in produzione, pubblicare nuova versione

2) Regole generali (naming e struttura)¶

2.1 Code del template¶

Regola:

<document_type>_<variant>_v<numero>

Esempi: - ras_base_v1 - ras_condominio_v2 - rapportino_base_v1

2.2 Struttura cartelle consigliata¶

templates/
  docx/
  reportlab/
  assets/

2.3 Dati JSON¶

Tutti i template devono avere un JSON di esempio in:

examples/payloads/

3) Template DOCX (docxtpl)¶

3.1 Placeholder semplici¶

Sintassi:

{{ cliente.ragione_sociale }}
{{ cliente.indirizzo }}

3.2 Blocchi ripetibili (loop)¶

Sintassi:

{% for s in sezioni %}
{{ s.titolo }}
{{ s.contenuto }}
{% endfor %}

3.3 Condizioni¶

{% if cliente.piva %}
P.IVA: {{ cliente.piva }}
{% endif %}

3.4 Tabelle dinamiche¶

Inserire nel DOCX una tabella con una riga "template":

| Descrizione | Quantita' | Prezzo |
| {{ r.descrizione }} | {{ r.qta }} | {{ r.prezzo }} |

E usare:

{% for r in righe %}
... riga template ...
{% endfor %}

3.5 Immagini¶

Inserire immagini con campo immagine docxtpl:

{{ foto[0].path }}

Nel contesto JSON:

"foto": [{"path": "examples/assets/foto1.jpg", "caption": "Ingresso"}]

3.6 Firme¶

Usare immagini PNG trasparenti. Nel JSON:

"firme": [{"path": "examples/assets/firma_tecnico.png", "label": "Firma tecnico"}]

3.7 Header e footer¶

Inserire elementi statici nel DOCX (logo, note)
Campi dinamici: usare placeholder come nel body

3.8 Compatibilita' PDF¶

Regole: - Evitare font custom non installati - Evitare campi Word complessi (SmartArt, campi dinamici Word) - Preferire layout semplice (tabelle e paragrafi)

4) Template ReportLab¶

4.1 Template base¶

Un template ReportLab e' un file Python (es: rapportino_base_v1.py).

4.2 Struttura minima consigliata¶

Header (logo, titolo)
Sezione cliente
Sezione intervento
Tabelle o liste
Firma finale

4.3 Esempio minimale¶

from reportlab.lib.pagesizes import A4
from reportlab.pdfgen import canvas


def render(context, output_path):
    c = canvas.Canvas(output_path, pagesize=A4)
    c.setFont("Helvetica", 12)
    c.drawString(50, 800, context["cliente"]["ragione_sociale"])
    c.save()

4.4 Linee guida¶

Sempre usare coordinate coerenti
Gestire pagina multipla se il testo e' lungo
Usare assets statici (logo) da templates/assets/

5) Placeholder standard consigliati¶

Cliente¶

cliente.ragione_sociale
cliente.indirizzo
cliente.citta
cliente.piva

Tecnico¶

tecnico.nome
tecnico.ruolo

Documento¶

documento.numero
documento.data
documento.titolo

6) Checklist di pubblicazione¶

Prima di pubblicare un template: 1. Verifica payload JSON di esempio 2. Testa generazione DOCX o PDF 3. Testa conversione PDF (se DOCX) 4. Controlla watermark (se richiesto) 5. Controlla preview (prima pagina) 6. Controlla che non ci siano placeholder non risolti

7) Esempi reali¶

7.1 RAS (DOCX)¶

Template: examples/templates/ras_base_v1.docx
Payload: examples/payloads/ras_payload.json

7.2 Rapportino (ReportLab)¶

Template: examples/templates/rapportino_base_v1.py
Payload: examples/payloads/rapportino_payload.json

8) Errori comuni¶

Placeholder errato: campo mancante nel JSON
Tabelle loop: riga template non corretta
Conversione PDF: layout Word troppo complesso
Immagini: path non valido o file mancante

9) Pubblicazione template via API¶

Esempio:

curl -X POST http://localhost:8085/api/templates \
  -F "code=ras_base_v1" \
  -F "name=RAS base v1" \
  -F "document_type=ras" \
  -F "engine=docx" \
  -F "file=@ras_base_v1.docx"

Aggiornamento template esistente:

curl -X POST http://localhost:8085/api/templates/{template_id}/update \
  -F "name=RAS base v1" \
  -F "document_type=ras" \
  -F "engine=docx" \
  -F "file=@ras_base_v1.docx"

10) Note per futura integrazione Collabora¶

Usare template DOCX puliti e standard
Evitare estensioni Word non compatibili
Salvare sempre DOCX e convertirlo a PDF dopo le modifiche