Cantieri - Protocolli e Cantieri in Esecuzione

🏗️ Gestione Cantieri - Protocolli e Strutture Standard

Protocolli operativi standardizzati, strutture organizzative e standard per la gestione completa dei cantieri

Protocollo repo V2.2 (riferimento incrociato): sequenza Git, verifica anagrafica CRM (conteggio aziende, id 1 = Frigerio Legnami) e deploy SSH produzione sono in app/index.php → Sync Git e tracciamento accessi.

CMS / pagine dinamiche (non sono cantieri): contenuti in SQLite serviti da page.php in root; istruzioni per AI in app/index.php → Gestione CMS Dinamico (SQLite).

🛡️ Protocollo di Sicurezza e Regole Operative (Agenti AI)

🔒 PROTOCOLLO PRIVACY E RESE 2.0 (Direttive inderogabili)

PARTE I - STRUTTURA ORGANIZZATIVA

1. Organizzazione Cantieri

I cantieri sono organizzati per anno e stato di avanzamento in una struttura gerarchica standardizzata.

📁 Struttura Directory (Standard Magenta Cantieri 2.0)

cantieri/
├── index.php (pagina principale cantieri + protocolli)
└── [ANNO]/
    ├── in_esecuzione/
    │   └── [nome_cantiere]/
    │       ├── index.php                    (1 – Dashboard)
    │       ├── diario_di_cantiere.php       (2 – Cronaca Pubblica)
    │       ├── consuntivo_ore.php           (3 – Registro Contabile)
    │       ├── rese_di_posa.php             (4 – Database Tecnico Interno)
    │       ├── programma.php                (5 – Pianificazione)
    │       ├── analisi_fattibilita_consegna.php  (6 – Strategia)
    │       ├── previsioni_meteo.php         (7 – Dati Esterni)
    │       ├── storico_note.php             (8 – Archivio note giornate concluse)
    │       ├── notes.txt                    (note correnti; schema Silos)
    │       ├── storico_note.json            (archivio JSON; generato da API)
    │       └── Documenti_Cantiere/           (opzionale)
    └── completati/
        └── [cantieri completati]

📋 Criteri Organizzativi

• Anno (es: 2026/): Cartella per anno di inizio lavori
• in_esecuzione/: Cantieri attualmente in corso
• completati/: Cantieri terminati. Spostare l'intera cartella da in_esecuzione/ a completati/. Standard Magenta Manager 2.0: sostituire index.php con versione "archiviato" (solo link al diario); eliminare programma.php, previsioni_meteo.php, analisi_fattibilita_consegna.php; aggiornare breadcrumb nel diario e negli eventuali file rimanenti (consuntivo, rese) da path in_esecuzione a completati. Il box in "In Esecuzione" scompare automaticamente (lista generata da users_db_list_cantieri_available()). Struttura legacy: disegni/, istruzioni.html, programma.html.
• Nome cantiere: Formato località_via (es: legnano_via_milano)

2. Struttura Standard Cantiere – Magenta Cantieri 2.0

📄 I 8 file (ordine e funzioni)

🔒 Regole di Data Integrity

Cartella opzionale: Documenti_Cantiere/ per allegati. File opzionali: sopralluogo_tecnico.php (verbali, collaudi) se previsto dal cantiere.

🔗 Breadcrumbs Standard

Tutti i file devono avere breadcrumbs corretti. Per un cantiere in cantieri/2026/in_esecuzione/nome_cantiere/:

$breadcrumbs = [
    ['label' => 'Home', 'url' => '../../../../index.php'],
    ['label' => 'Cantieri', 'url' => '../../../index.php'],
    ['label' => 'Nome Cantiere', 'url' => 'index.php'],
    ['label' => 'Diario di Cantiere'], // o altro file
];

🎨 Template di Riferimento

Quando si crea un nuovo cantiere, utilizzare come riferimento:

• Cantiere completo: cantieri/2026/in_esecuzione/legnano_via_milano/
• Cantiere template vuoto: cantieri/2026/in_esecuzione/milano_via_ampere/
• Template base: app/templates/cantieri_in_esecuzione/ (vedi sezione sotto)

2b. Sistema Note decentralizzato (Silos)

Riferimento tecnico: architettura file, API, tag, regex e prompt. Per dettagli condivisi con App vedi anche app/index.php#note-silos.

Le note non sono più globali: ogni cantiere ha cantieri/[ANNO]/[STATO]/[SLUG]/notes.txt (note correnti) e storico_note.json (archivio giornate concluse). Consultazione: storico_note.php in ogni cartella.

API (app/api/notes.php): POST standard sovrascrive notes.txt. Archiviazione SOLO con parametro esplicito action=archive: contenuto spostato in storico_note.json con timestamp, notes.txt svuotato.

Tag [CANTIERE: slug]: gestito dal frontend (app/includes/notes-modal.php). Se slug è "slug" o "nome_cantiere" il tag non viene iniettato. Regex pulizia: /^\[CANTIERE:\s*[^\]]+\]\s*\n*/gi.

Prompt: Solo «Salvataggio note giornata lavorativa» (app/cursor/ai_prompt) può inviare action=archive, come ultimo atto dopo aver messo in sicurezza tutti i file. Creazione nuovo cantiere: 8 file PHP + _consuntivo_ore_tabelle.html + notes.txt/storico_note.json (generati a richiesta).

3. Template Cantieri

I template per la creazione di nuovi cantieri si trovano in app/templates/cantieri_in_esecuzione/.

📄 File Template (ordine Magenta Cantieri 2.0)

Gli 8 file obbligatori nell’ordine di §2: index.php, diario_di_cantiere.php, consuntivo_ore.php, rese_di_posa.php, programma.php, analisi_fattibilita_consegna.php, previsioni_meteo.php, storico_note.php. Obbligatorio anche _consuntivo_ore_tabelle.html (incluso da consuntivo_ore.php). Esiste un template per ogni file incluso rese_di_posa.php.template. In ogni cartella cantiere: notes.txt e storico_note.json (schema Note Silos). Opzionali: sopralluogo_tecnico.php, cartella Documenti_Cantiere/.

Consuntivo ore: consuntivo_ore.php deve includere (tramite include o file_get_contents) esattamente il file _consuntivo_ore_tabelle.html nella sezione #registrazione-ore. Non usare altri nomi di file per le tabelle presenze.

📋 Placeholder da sostituire

[ANNO], [NOME_CANTIERE_SNAKE], [NOME_CANTIERE_DISPLAY], [DATA_CONSEGNA], [PERIODO_INIZIO], [PERIODO_FINE], [GIORNATE_LAVORATIVE], [COMUNE], [COMUNE_LOWERCASE], [PROVINCIA], [DATA_CREAZIONE], [DATA_AGGIORNAMENTO], [DESCRIZIONE_CANTIERE]

Prompt creazione cantiere: Vedi prompt «Creazione nuovo cantiere» in app/cursor/ai_prompt/prompts.csv. Sorgente unica: app/templates/cantieri_in_esecuzione/ (non usare cantieri esistenti come modello).

PARTE II - PROTOCOLLI OPERATIVI

4. Protocollo SOP-01: Standard Diario di Cantiere

📊 Campi Obbligatori Tabella Standard

1. Meteo: Condizioni meteo (es: "Sole", "Pioggia", "Nuvoloso", "Poco nuvoloso"). Includere temperatura e precipitazioni se disponibili.
2. Supervisore: Nome supervisore (es: "Davide Gobbi") o "Assente" se non presente. Specificare ore se parziale.
3. Totale Ore Uomo: Somma di TUTTE le ore lavorate nella giornata (es: "42.5 ore uomo (5 operai × 8.5h)")
4. Lavorazione Prevalente: La voce principale del giorno con ore dedicate (es: "Travi perimetrali gronda (22.5 ore uomo)")
5. Resa Giornaliera: Se applicabile, resa mq/h o unità/h. Se non calcolabile scrivere "Non applicabile" o "Non calcolata" con motivazione
6. Note Assenze: Se un operaio della squadra manca, DEVE esserci la motivazione (es: "Luca: febbre", "Omar: ordine supervisore"). Se tutti presenti: "Tutti presenti"
7. Materiali Ricevuti: Note su consegne materiali (es: "Chiodi del 70 consegnati") o "Nessuna consegna"
8. Criticità Operative (opzionale): Eventi critici che hanno impattato la produttività (es: ritardi, problemi tecnici, condizioni avverse)

⚠️ Colonna Alert - Regole

• Se un dato NON è disponibile → "⚠️ MANCANTE"
• Se manca la motivazione di un'assenza → "🚨 MOTIVARE ASSENZA"
• Se c'è una criticità operativa → "🚨 IMPATTO PRODUTTIVITÀ" o simile
• Se tutto OK → Lasciare vuoto

📋 Esempio Tabella Standard

📅 ATTIVO DAL: 27/01/2026 | VERSIONE: 1.0 | REVISIONE: Annuale

5. Obbligo Motivazioni Assenze

🔍 Regola di Controllo

Se un operaio ha 0 ore in una giornata lavorativa:

1. Cercare nelle note fornite la motivazione (Malattia, Ferie, Permesso, Infortunio, ecc.)
2. Se trovata: scrivere la motivazione nella colonna "Note Assenze" della tabella
3. Se mancante: inserire l'alert "🚨 MOTIVARE ASSENZA" nella colonna "Alert"

📝 Esempi Note Assenze

• "Assente per malattia"
• "Assente per permesso"
• "Assente al pomeriggio per appuntamento medico"
• "Assente per ferie"
• "Assente per infortunio"

📋 Cantiere Fermo – Propagazione Motivazione

In caso di cantiere fermo (es. mancanza materiale, mancanza tegole, maltempo, ecc.), la motivazione inserita nel diario deve essere automaticamente propagata come giustificativo assenza per tutti gli operai nel file consuntivo ore. Questo evita falsi positivi negli alert "Assenze senza motivazione" in Home, poiché la motivazione della fermata cantiere vale come giustificativo collettivo per tutto il team assegnato.

Regola assoluta: MAI lasciare la colonna "Note" vuota quando un operaio è assente - le motivazioni sono informazioni molto importanti per la gestione amministrativa e legale.

6. Standard Tabellare Programma

✅ Formato Programma Corretto

Struttura:

1. Sezione iniziale: Elenco conciso delle lavorazioni rimanenti (senza cronistoria)
2. Tabella HTML: Una tabella con le colonne [DATA | FASCIA | LAVORAZIONE | SQUADRA | TARGET]
3. Calcoli matematici: Tutti i target devono essere calcolati con la formula ufficiale: Ore_Uomo = Quantità / Resa_Reale_Diario
4. Commenti HTML: Sotto la tabella, commenti con i calcoli dettagliati per audit

Esempio Elenco Lavorazioni:

<h3>Lavorazioni Rimanenti</h3>
<ul>
    <li><strong>Posa isolante sopra perlina:</strong> 300 mq rimanenti</li>
    <li><strong>Telo traspirante:</strong> 511 mq (non iniziata)</li>
    <li><strong>Assi di ventilazione:</strong> 511 mq (non iniziata)</li>
    <li><strong>Listoni fermategola:</strong> 511 mq (non iniziata)</li>
    <li><strong>Posa tegole:</strong> 511 mq (non iniziata)</li>
</ul>

<strong>FONTE:</strong> Estrai SEMPRE dal diario_di_cantiere.php, sezione "Lavorazioni Restanti"

Esempio Tabella HTML:

<table>
    <thead>
        <tr>
            <th>Data</th>
            <th>Fascia</th>
            <th>Lavorazione</th>
            <th>Squadra</th>
            <th>Target</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Martedì 21/01</td>
            <td>08:00-12:30</td>
            <td>Posa isolante sopra perlina</td>
            <td>5 operai</td>
            <td>81 mq</td>
        </tr>
        <tr>
            <td>Martedì 21/01</td>
            <td>12:30-17:00</td>
            <td>Posa isolante sopra perlina</td>
            <td>5 operai</td>
            <td>81 mq</td>
        </tr>
    </tbody>
</table>

Esempio Commenti Calcoli:

<!-- CALCOLI MATEMATICI PROGRAMMA -->
<!-- Resa isolante sopra perlina: 3.6 mq/ora per operaio (fonte: diario cantiere, sezione Rese Effettive) -->
<!-- Quantità rimanente: 300 mq -->
<!-- Operai disponibili: 5 -->
<!-- Ore necessarie: 300 ÷ 3.6 = 83.3 ore uomo = 1.96 giorni (2 giorni arrotondati) -->
<!-- Target giornaliero: 5 operai × 8.5 ore × 3.6 mq/ora = 153 mq/giorno -->

⚠️ SCOPO: Questi commenti permettono di verificare la correttezza dei calcoli e rendono il programma auditable.

⚠️ Rese Stimate per Posa Tegole

📊 Rese Standard per Squadra 4 Operai

📐 Formula Calcolo Tempi

Giornate = superficie_mq ÷ resa_mq_giornata
Ore lavorative = giornate × 8.5 ore/giorno
Ore uomo = ore_lavorative × numero_operai

Esempio:
511 mq ÷ 70 mq/giornata = 7.3 giorni
7.3 giorni × 8.5 ore = 62 ore lavorative
62 ore × 4 operai = 248 ore uomo totali

⚙️ Fattori che Influenzano la Resa

• Tipo di tegola: Portoghesi/marsigliesi più veloci di coppi tradizionali
• Complessità tetto: Abbaini, camini, colmi, pendenze elevate → più lento
• Logistica materiali: Se già in quota → più veloce
• Preparazione supporto: Se già pronta → più veloce

7. Logica Decisionale Meteo

📋 Procedura Obbligatoria per Giornate Sospese

1. Creare voce nel Diario Giornaliero con stato "⚠️ LAVORI SOSPESI PER MALTEMPO"
2. CREARE LE RIGHE NEL REGISTRO ORE OPERAI con 0 ore per TUTTI gli operai della squadra
3. Nella colonna "Note" scrivere "Cantiere chiuso per maltempo" (o motivo sospensione)

📝 Esempio REGISTRO ORE per giornata sospesa (28/01/2026)

<tr>
    <td rowspan="6"><strong>28/01/2026</strong></td>
    <td>Davide Gobbi</td>
    <td>0 ore</td>
    <td></td>
    <td>Cantiere chiuso per maltempo</td>
</tr>
<tr>
    <td>Nicola Pedrazzoli</td>
    <td>0 ore</td>
    <td></td>
    <td>Cantiere chiuso per maltempo</td>
</tr>
[... ripetere per tutti gli operai della squadra ...]

8. Gestione Registro Ore Operai

⏰ Regola Base Ore Operai

📊 Struttura Registro Ore

• Struttura mensile: Una tabella separata per ogni mese (es. Gennaio 2026, Febbraio 2026)
• Colonne: Data | Operaio | Ore Lavorate | Note Assenza/Presenza (registro puramente contabile; descrizioni lavorazioni nel diario_di_cantiere.php)
• Formato: Ogni tabella è in un div con classe registro-mese-pdf

⚠️ Assenze Parziali

Se un operaio lavora meno ore del previsto, specificare nella colonna Note:

• "Nicola: 2 ore poi malato"
• "Omar: uscito alle 14:30 per appuntamento medico (6.5 ore lavorate)"
• "Luca: entrato alle 10:00, ha fatto 6 ore"

9. Logica di Calcolo e Verità Dati

🎯 Regole Assolute

1. NON STIMARE MAI: Somma ogni riga della tabella ore. Non usare approssimazioni o "circa". Ogni dato deve essere calcolato o derivato da fonti verificabili.
2. DIVIETO DI INVENZIONE DATI: L'AI non deve mai, in nessun caso, generare, stimare o dedurre quantità numeriche (mq, metri lineari, pezzi, rese) se non sono esplicitamente scritte dall'utente nel file notes.txt o nello storico_note.php. Se un'attività è citata nelle note (es. "posa tegole") ma manca la quantità (mq), il file rese_di_posa.php NON deve essere aggiornato per quella data. L'allucinazione di dati numerici è una violazione gravissima che porta al fallimento del task.
3. FONTE DI VERITÀ UTENTE: Se l'utente scrive "restano X mq", quel valore è la verità assoluta. Ricalcola il "già fatto" sottraendo X dal totale cantiere.
4. ORDINE CRONOLOGICO: Mantieni SEMPRE l'ordine cronologico crescente (dal più vecchio al più recente) nelle sezioni "Rese Effettive Registrate" e "Diario Giornaliero".
5. VERIFICA COERENZA: Dopo ogni aggiornamento, verifica che:
   • Totale posato = Somma di tutte le quantità giornaliere
   • Quantità rimanente = Totale superficie - Totale posato
   • Percentuale completamento = (Totale posato / Totale superficie) × 100

📝 Esempio Pratico - Logica "Restano X mq"

Già posato = Totale - Rimanente
Già posato = 500 mq - 50 mq = 450 mq ← Questa è la verità

10. Standard Interfaccia Dashboard

📐 Classi CSS per Dimensioni Box

I box della dashboard possono avere dimensioni diverse usando le seguenti classi CSS:

📱 Comportamento Responsive

• Desktop (>1200px): 4 colonne
• Tablet (≤1200px): 3 colonne
• Mobile (≤768px): 2 colonne
• Small mobile (≤480px): 1 colonna

🔧 Implementazione

Box Note nella Dashboard:

• Mostra anteprima delle note (max 500 caratteri)
• Caricata automaticamente al caricamento pagina
• API GET fa automaticamente pull da GitHub prima di restituire le note
• Pulsante "Modifica" apre modal note
• Modal incluso con includeComponent('notes-modal')
• API path: BASE_PATH . 'app/api/notes.php'

11. Sistema Alert e Notifiche Telegram

📊 Dove vengono mostrati gli Alert

• Homepage (Bacheca): Box giallo "⚠️ Cantieri da Verificare" o box verde "✅ Cantieri Aggiornati" — generato ad ogni caricamento di index.php
• Telegram: Messaggio push inviato automaticamente in due fasce orarie se ci sono alert attivi (vedi sotto).

🔍 Cosa verifica il sistema

Per ogni cantiere in cantieri/[anno]/in_esecuzione/ (fonte: solo consuntivo_ore.php):

1. ORE E PRESENZE OPERAI MANCANTI: Controlla la sezione #registrazione-ore del consuntivo. Per gli ultimi 7 giorni lavorativi, verifica che ogni giorno abbia almeno una riga con data DD/MM/YYYY. Se manca → alert.
2. ASSENZE SENZA MOTIVAZIONE: Se un operaio ha 0 ore in una giornata, deve avere una nota motivata (malattia, permesso, maltempo, ecc.). Se la nota manca → alert. Cantiere fermo: note come "Cantiere fermo", "mancanza tegole", "mancanza materiale" fungono da giustificativo collettivo per tutto il team → nessun alert.
3. RESE ORA UOMO DA AGGIORNARE: Estratte dal box alert presente nel consuntivo (se presente).
4. CONSUNTIVO ORE VUOTO: Se manca la sezione id="registrazione-ore" o non ci sono date nelle tabelle → alert.

Requisiti tecnici per consuntivo_ore.php (e file inclusi): ogni riga della tabella ore deve avere 4 colonne; il tag <h2 id="registrazione-ore"> è obbligatorio per l'aggancio degli script di parsing in app/includes/. Dati consuntivo: le tabelle presenze devono risiedere solo in _consuntivo_ore_tabelle.html (vedi §2 Struttura Standard).

⏰ Finestra oraria e "include oggi"

Regola: Da le 15:30 (ora Italia), il sistema considera oggi come giorno da verificare. Prima delle 15:30, considera solo fino a ieri. Questo evita alert falsi quando il consuntivo non è ancora stato aggiornato nella mattinata.

🎨 Colore Alert in Bacheca

• Giallo (⚠️ Cantieri da Verificare - oggi): Se mancano dati solo per oggi — segnalazione da completare.
• Rosso (🚨 Dati mancanti per giornate passate): Se mancano dati per giorni precedenti a oggi — molto più evidente, azione prioritaria.

📁 File coinvolti

📱 Notifiche Telegram – Orari e Flusso

Due invii giornalieri (Lun–Ven):

• Ore 19:00 (sera): Prima notifica — ricorda di aggiornare i diari dopo la giornata lavorativa.
• Ore 7:40 (mattina): Follow-up del giorno prima — se ieri sera c'erano alert e non sono stati risolti. Escluso sabato: la notifica che sarebbe sabato 7:40 viene inviata il lunedì alle 7:40 (follow-up del venerdì sera).

Cron Job (configurare 2 job):

0 19 * * 1-5   →  Lun-Ven ore 19:00
40 7 * * 1-5   →  Lun-Ven ore 7:40 (sabato non incluso)

Flusso:

1. Finestra oraria: Lo script invia solo tra 7:00–8:59 (mattina) o 17:00–20:59 (sera). Fuori da questi range esce senza inviare.
2. Verifica: Chiama getCantieriAlertData() — stessa logica della bacheca.
3. Se nessun alert: Esce senza inviare nulla.
4. Se ci sono alert: Prepara testo tecnico → passa a Groq AI per formattare in messaggio colloquiale (max 3–4 righe) → invia su Telegram.

12. Protocollo di Analisi Note

✅ Checklist Completa

🔢 Calcoli Automatici

Se hai mq + ore + operai, calcola automaticamente:

resa_per_operaio = mq / (ore × operai)

Esempio:
50 mq posati, 5 operai, 8.5 ore ciascuno
resa_per_operaio = 50 / (8.5 × 5) = 50 / 42.5 = 1.18 mq/ora per operaio

✅ Verifica Finale

🤖 Prompt Ricorrenti

Ultimo aggiornamento: 26 Febbraio 2026 — Flusso dati 7 file, regola action=archive ultimo atto, sospensione mancanza materiale in rese

Questo documento definisce i protocolli operativi standard e le strutture organizzative per la gestione completa dei cantieri e deve essere seguito rigorosamente.