Vai al contenuto

Gate Stampa Compila V3 RAS - 2026-08-02

Obiettivo

Verificare se Compila V3 puo' usare in modo affidabile il motore stampa RAS esterno senza dipendere da Compila V2 come runtime applicativo.

Decisione confermata: il motore stampa resta esterno/ReportLab. V3 non deve incorporare un renderer PDF proprio.

Flusso Attuale

  1. V3 espone in pagina i pulsanti:
  2. Genera PDF
  3. Apri PDF
  4. Il template V3 usa:
  5. runtime_ctx.generate_reportlab_v2_url
  6. runtime_ctx.open_reportlab_v2_url
  7. La route DynamicDocumentBuilderView.generate_reportlab_v2 avvia _run_ras_v2_print_job_async.
  8. Il job chiama run_ras_reportlab_v2_job.
  9. run_ras_reportlab_v2_job costruisce il payload con _build_ras_print_payload_for_doc(RasRuntimeService, doc, cliente).
  10. Il payload viene inviato al motore esterno se abilitato:
  11. endpoint /api/v1/render/ras
  12. render ras_v2_vertical
  13. L'output viene persistito con:
  14. persist_ras_outputs
  15. ras_v2_output_documento_id
  16. ras_v2_output_version_no
  17. ras_v2_sections_count
  18. libretto PDF se generato

Evidenze Da Codice

  • V3 non chiama direttamente un renderer PDF.
  • V3 passa dalle route esistenti di generazione/apertura PDF.
  • run_ras_reportlab_v2_job imposta:
  • render_engine = reportlab_v2
  • render_engine_version = reportlab_demo_parallel_v1
  • Se il provider esterno e' abilitato, il job usa send_print_engine_json.
  • Se il provider esterno fallisce e non e' forzato come unico provider, resta fallback interno.
  • Il payload stampa e' costruito da RasRuntimeService, non da Compila V2 frontend.
  • Le risposte V3 salvate in legacy_dynamic_answer entrano nel percorso letto dal runtime.

Test Eseguiti

pytest -q tests/test_print_engine_ras_external_contract.py

Risultato:

  • 2 passed
  • warning non bloccanti su dipendenze requests/urllib3 e PyPDF2

Copertura del test:

  • il servizio esterno accetta il render ras_v2_vertical;
  • il payload consegnato ai renderer mantiene render_engine = reportlab_v2;
  • le schede verticali mantengono render_engine_version = reportlab_demo_parallel_v1;
  • SafeOps decodifica correttamente gli output PDF base64.
pytest -q tests/test_compila_v3_runtime.py

Risultato:

  • 32 passed
  • conferma che il template V3 espone ancora le action PDF e gli URL runtime richiesti.

Stato Del Gate

Punto Stato Note
V3 usa motore esterno invece di motore proprio OK Passa da route ReportLab/external esistenti.
Contratto servizio esterno ras_v2_vertical OK Test dedicato passato.
Audit payload pre-PDF OK run_ras_reportlab_v2_job salva payload_audit in ras_v2_job e ras_v2_payload_audit.
Persistenza output PDF OK persist_ras_outputs e id output in legacy_payload.
Apertura PDF generato da V3 OK tecnico Stesso open_reportlab_v2_url; da provare con sessione reale.
Lettura risposte V3 nel payload stampa OK strutturale V3 salva in legacy_dynamic_answer; runtime stampa legge quel canale.
Foto V3 in stampa Parziale Le foto domanda salvate entrano. Da verificare parcheggio/destinazioni e annotate su PDF reale.
Annotazioni foto in stampa Parziale Le copie annotate sono salvate come foto; serve confronto visivo PDF.
Galleria extra domanda OK tecnico Le foto extra domanda non duplicano le immagini principali e restano in question_gallery_items.
Document check in stampa OK tecnico Il payload conserva document_check; su 7176 audit reale 1/1 answered.
NC in stampa OK tecnico Il job stampa sincronizza le NC risk-based e salva ras_v2_nc_sync_summary.
Condizionali Easy Builder in stampa Non chiuso Se V3 non applica ancora tutte le condizioni, anche la stampa puo' mostrare dati non filtrati come legacy.

Rischi Residui

  1. Il nome interno e' ancora v2 (ras_v2_output_documento_id, route generate-reportlab-v2). Questo e' un naming storico del motore, non una dipendenza dal frontend V2. Va rinominato solo quando il gate e' chiuso, per evitare refactor cosmetici rischiosi.
  2. Lo stato live del document_check viene mostrato in V3 ma non salvato automaticamente. Se il tecnico non conferma una risposta, la stampa potrebbe non riflettere quello stato live.
  3. Le foto annotate sono copie nuove parcheggiate/salvate: va verificato che il PDF mostri la copia annotata nel punto corretto e non l'originale.
  4. Il documento demo 7176 contiene dati misti da prove precedenti; non e' una baseline ideale per certificare la stampa.

Audit Automatico Payload

Prima di inviare il payload al renderer PDF, il job calcola:

  • sections_count
  • questions_count
  • answered_count
  • questions_with_images_count
  • images_count
  • image_refs_count
  • print_image_keys_count
  • image_questions_without_refs_count
  • questions_with_details_count
  • document_check_count
  • document_check_answered_count
  • nc_like_count
  • warning diagnostici (no_sections, no_questions, image_refs_missing_for_images, document_check_not_fully_answered, missing_question_ids, missing_question_labels)

Questo non sostituisce il controllo visuale del PDF, ma permette di capire subito se V3 sta consegnando al motore stampa risposte, foto, refs, document check e NC in modo coerente.

Nota: nel payload stampa normalizzato le foto possono arrivare solo come image_refs. Questo e' valido; il warning scatta solo quando una domanda contiene images senza refs stampabili.

Verifica Reale Documento 7176

Generazione eseguita il 2026-08-02 sul documento demo 7176.

  • output documento: 7186
  • schede persistite: 15
  • provider stampa: local_docx_pdf
  • fallback esterno: assente
  • sezioni payload: 15
  • domande payload: 400
  • risposte valorizzate: 183
  • domande con foto: 56
  • riferimenti foto stampabili: 121
  • domande con dettagli: 82
  • document check: 1
  • document check answered: 1
  • NC-like rilevate: 77
  • NC backend sincronizzate dal job stampa: 19 aperte risk-based
  • question id mancanti: 0
  • label mancanti: 0
  • warning audit: nessuno

Aggiornamento successivo: il mapping stampa ora porta meta.document_check dalle domande Easy Builder al payload PDF anche quando la domanda e' inclusa come non compilata. Il documento 7176 conferma document_check_count = 1.

Aggiornamento NC: la generazione RAS V3 esegue anche sync_ras_non_conformita(risk_only=True) prima della stampa e salva il riepilogo in ras_v2_nc_sync_summary / ras_v2_job.nc_sync_summary. Sul documento 7176 la verifica reale ha creato 19 NC aperte.

Aggiornamento foto/libretto: l'adapter distingue le foto extra domanda da image_refs principali e porta anno_costruzione dal libretto in cliente.meta.

Problema risolto durante la verifica: il servizio print engine esterno non aveva SECRET_KEY configurata nell'app Flask e falliva con HTTP 500 quando il renderer toccava la sessione. Il servizio ora imposta SECRET_KEY da env o dal secret HMAC obbligatorio del print engine.

Prova Manuale Necessaria

Preparare un documento RAS baseline pulito oppure clonare il demo e compilare:

  1. una domanda OK senza foto;
  2. una domanda NC con nota;
  3. una domanda NC con foto originale;
  4. una domanda NC con foto annotata;
  5. una domanda con 4 foto;
  6. una domanda document_check con documento valido;
  7. una domanda document_check con risposta manuale Non presente;
  8. una domanda In attesa con detail field note;
  9. una posizione GPS acquisita.

Poi generare PDF da V3 e verificare:

  • intestazione/branding;
  • sezioni e numerazione;
  • valori risposta;
  • note;
  • foto corrette;
  • annotazioni visibili;
  • stato documentale;
  • NC generate;
  • data/posizione se prevista;
  • numero schede verticali e libretto.

Decisione Operativa

Il gate stampa e' tecnicamente agganciato, ma non ancora chiuso funzionalmente.

V2 puo' essere dismesso come sviluppo, ma non rimosso come fallback finche' non esiste almeno un PDF V3 baseline confrontato e approvato contro legacy/V2.

Prossima Azione Consigliata

Creare o ripulire un documento RAS baseline dedicato alla stampa V3, generare il PDF e confrontare l'audit salvato con il risultato visuale: risposte, foto, annotazioni, document check, NC, data e posizione.