# PROMPT.md — Prompt atomici per Claude Code Sequenza di prompt da dare a Claude Code **uno alla volta**, in ordine. Ogni prompt è atomico e verificabile. A fine di ogni fase, aggiornare la checklist in `CLAUDE.md` (sezione 8). > Regole generali (valide per ogni prompt): > - Leggi prima `CLAUDE.md`. Rispetta stack, vincoli deploy e schema dati lì definiti. > - PDO + prepared statement ovunque, Twig autoescaped, CSRF sui form di scrittura. > - Nessun framework full-stack, niente bundler JS. Tailwind solo via CLI. > - Migrazioni = file SQL numerati in `database/migrations/` (si applicano via phpMyAdmin in prod). > - Dopo ogni fase: spiega come testare in locale e cosa aggiornare nel manifest/deploy. --- ## FASE 0 — Bootstrap progetto **Prompt 0.1** > Inizializza la struttura del progetto come descritto in CLAUDE.md (sezione "Layout cartelle"). > Crea `composer.json` con dipendenze: twig/twig, phpmailer/phpmailer, vlucas/phpdotenv, dompdf/dompdf. > Crea `.env.example` con: DB (host, name, user, pass), APP_URL, APP_ENV, MAIL (host, port, user, > pass, from, from_name) per SMTP OVH, e credenziali SFTP/FTPS per il deploy. Crea `.gitignore` > (escludi `.env`, `/vendor`, `/node_modules`, `/storage/cache`, `/public/assets/app.css`). > Esegui `composer install` in locale. **Prompt 0.2** > Implementa il nucleo in `src/Support/`: > - `Config`: carica `.env` via phpdotenv, espone i valori. > - `Db`: singleton PDO MySQL (utf8mb4, ERRMODE_EXCEPTION, prepared statement by default). > - `Router`: front controller `public/index.php` con routing minimale (GET/POST, parametri, > middleware/guard `requireAuth`/`requireRole`), gestione 404/403/500. > - `View`: wrapper Twig (cache in `/storage/cache`, autoescape on, funzione globale `csrf_field()` > e `url()`). > Crea un layout Twig base `templates/layout.html.twig` (header con nav, slot contenuto, flash > messages) e una home placeholder protetta da auth. Verifica che la home risponda. **Prompt 0.3** > Configura Tailwind via CLI standalone: `tailwind.config.js` (content = templates + js), > `assets/css/input.css` con le direttive base. Aggiungi uno script/documenta il comando > `tailwindcss -i assets/css/input.css -o public/assets/app.css --minify`. Applica uno stile base > pulito al layout (nav, container, bottoni, tabelle, form). Aggiungi Alpine.js (file statico in > `public/assets/` o CDN) al layout. --- ## FASE 1 — Schema DB + seed **Prompt 1.1** > Crea `database/migrations/001_init.sql` con TUTTE le tabelle definite in CLAUDE.md sezione 5 > (sezioni, luoghi, settimane, elementi, varianti, attivita, attivita_settimane, attivita_risorse, > attivita_storico, gruppi, gruppo_movimenti, mangimi, mangimi_acquisti, mangimi_somministrazioni, > spese_categorie, spese, users, magic_tokens, preferenze_utente). Usa InnoDB, utf8mb4, FK con > ON DELETE coerente (RESTRICT dove cancellare romperebbe lo storico, CASCADE dove sensato), > DECIMAL per importi/kg, ENUM come da specifica, indici sulle FK e su (attivita_id, settimana). > Mantieni `database/migrations/CHANGELOG.md`. **Prompt 1.2** > Crea `database/seeds/001_seed.sql`: > - 52 righe in `settimane` con numero, mese di appartenenza, date nominali (anno non bisestile) ed > etichetta tipo "Apr · sett. 2". Genera i dati con uno script PHP locale `database/seeds/gen_settimane.php` > che produce l'SQL (1 gen + 7 giorni a settimana, 52 settimane, ultimi giorni assorbiti nella 52). > - sezioni: Orto (colturale), Animali (animale). > - spese_categorie: Carburante, Materiali, Attrezzature, Riparazioni, Consumabili. > - utente admin: matteo@disetti.it (ruolo admin, attivo). > Documenta che in produzione questi SQL si incollano in phpMyAdmin nell'ordine del CHANGELOG. **Prompt 1.3** *(opzionale ma utile)* > Crea uno script locale `database/import_excel.php` che, dato `Orto_Calendario.xlsx`, importa le > lavorazioni esistenti: ogni riga (sezione, coltivazione, lavorazione) diventa elemento+attività, > e le celle colorate verde/giallo per mese vengono espanse alle settimane corrispondenti del mese > (verde→migliore, giallo→medio). I link in colonna NOTE diventano `attivita_risorse`. > Output: SQL di insert da rivedere prima di applicare. (Granularità di partenza mensile → tutte le > settimane del mese colorate; poi le rifinisco a mano a livello settimanale.) --- ## FASE 2 — Auth magic link + ruoli **Prompt 2.1** > Implementa `src/Services/Mailer` (PHPMailer su SMTP OVH da `.env`, invio HTML+testo) e una > `MailerInterface` per poter testare in locale (in APP_ENV=local scrivi l'email in `/storage/logs` > invece di inviarla). **Prompt 2.2** > Implementa il flusso magic link come da CLAUDE.md sezione 4: > - `/login` (form email) → genera token (random_bytes 32), salva sha256 in `magic_tokens` con > scadenza 15 min, invia link `APP_URL/auth/verify?token=...`. Rate limiting per email/IP. > - `/auth/verify` → verifica hash (hash_equals), non scaduto, non usato → marca usato → crea > sessione (rigenera id), reindirizza alla home. Errori gestiti con messaggi chiari. > - `/logout`. Cookie HttpOnly/Secure/SameSite=Lax. > Aggiungi i guard `requireAuth` e `requireRole($ruolo)` al router. Scrivi una pagina di test che > mostra utente e ruolo correnti. --- ## FASE 3 — Admin: sezioni, luoghi, collaboratori **Prompt 3.1** > CRUD **sezioni** (solo admin): nome, modello (colturale/animale), colore, ordine, attiva. > CRUD **luoghi** (admin/editor): nome, ambito, note. > UI con Tailwind, validazione server, CSRF, conferme di cancellazione, flash messages. **Prompt 3.2** > CRUD **collaboratori/utenti** (solo admin): crea utente con email + nome + ruolo (editor/viewer), > attiva/disattiva, NON si impostano password (login solo via magic link). Impedisci di > cancellare/declassare l'unico admin. Mostra l'elenco con stato e ultimo accesso. --- ## FASE 4 — Elementi / razze / attività + calendario editor + risorse + storico **Prompt 4.1** > CRUD **elementi** (coltivazione/tipo animale), filtrati e raggruppati per sezione. L'etichetta UI > cambia in base al `modello` della sezione ("Coltivazione" vs "Tipo animale"). > CRUD **varianti SOLO per elementi di modello `animale`** (= razze: nome, origine, origine_link, > origine_venditore, note), annidate sotto l'elemento, con etichetta UI "Razza". Per le coltivazioni > (modello `colturale`) NON esiste la gestione varietà: la varietà si scrive nel campo note. **Prompt 4.2** > CRUD **attività** sotto l'elemento (nome, ordine, note). Per ogni attività, **editor del calendario > settimanale**: griglia delle 52 settimane raggruppate per mese; click su una settimana cicla tra > niente → verde → giallo → niente, salvataggio in `attivita_settimane` (auto-save via Alpine/fetch, > CSRF). Verde=migliore, giallo=medio. **Prompt 4.3** > Per ogni attività: gestione **risorse** (`attivita_risorse`: url + descrizione facoltativa) e > **storico** (`attivita_storico`: anno, data, luogo, origine, esito; il campo **razza** = variante_id > compare **solo** per gli elementi di modello `animale`, per le coltivazioni resta NULL). Lo storico è > multi-entry e ordinato per data desc. UI per aggiungere/modificare/eliminare entry. Editor in > scrittura, viewer in sola lettura. --- ## FASE 5 — Vista calendario comune **Prompt 5.1** > Implementa la **vista calendario comune** (CLAUDE.md sezione 6): griglia 52 settimane raggruppate > per mese (intestazioni mese), righe = attività raggruppate per sezione → elemento → attività, > celle verde/giallo da `attivita_settimane`. Tooltip con nome attività + tipo periodo. **Prompt 5.2** > Aggiungi i **checkbox per sezione** per mostrare/nascondere le righe di ciascuna sezione (toggle > client con Alpine), e la persistenza opzionale in `preferenze_utente.sezioni_visibili`. > Cura il responsive (scroll orizzontale su mobile o vista compatta). Evidenzia la settimana corrente. **Prompt 5.3 — Ottimizzazione mobile** > Rendi l'app comoda da smartphone (viewport stretto ~375px), mantenendo Tailwind: > - Aggiungi il meta viewport e verifica che tutte le pagine non abbiano overflow orizzontale. > - Tutte le tabelle larghe (liste coltivazioni, gruppi, movimenti, mangimi, spese) su mobile diventano > **schede impilate** (card) invece di righe; su desktop restano tabelle. > - Aree di tocco ≥44px per bottoni, link d'azione e toggle; niente icone-azione minuscole affiancate. > - **Calendario (vista)**: su mobile sostituisci la griglia 52 colonne con una vista alternativa — un > accordion per mese che mostra le settimane di quel mese, oppure una vista "agenda" che elenca, per > ogni attività, le prossime settimane verdi/gialle a partire da quella corrente. Su desktop resta la griglia. > - **Editor calendario**: su mobile, selezione dell'attività e poi toggle delle settimane raggruppate > per mese con controlli grandi, invece delle 52 celle cliccabili. > - Form di **data entry rapida** (somministrazione mangime, nascita/morte/macellazione): pochi campi, > input numerici con tastiera numerica (`inputmode="decimal"`), bottone di salvataggio sticky in basso > raggiungibile col pollice. > - Nav principale collassabile (hamburger) su mobile. > Testa a 375px, 768px e desktop. --- ## FASE 6 — Animali: gruppi + movimenti + consistenza **Prompt 6.1** > CRUD **gruppi** (elemento=tipo animale, variante=razza opzionale, nome, luogo corrente, stato, > note). Vista dettaglio gruppo con consistenza attuale calcolata dai movimenti. **Prompt 6.2** > Gestione **`gruppo_movimenti`**: form per registrare nascita, morte (con causa: predatore/ > macellazione/naturale/alla_nascita), acquisto (con origine_tipo incubazione/acquisto_vivo, fonte, > link, venditore, costo), trasferimento tra gruppi (genera trasferimento_out su A + trasferimento_in > su B, con gruppo_collegato_id incrociati), spostamento_luogo (aggiorna gruppi.luogo_id), fusione > gruppi (trasferimento totale + chiusura gruppo origine). Per la morte con causa=macellazione, mostra > e salva il campo `peso_lavorato_kg` (peso totale post-lavorazione); calcola il peso medio/capo. > Timeline movimenti per gruppo. **Prompt 6.3** > Implementa il servizio `ConsistenzaService`: consistenza puntuale a una data e **consistenza media > ponderata sul tempo** in un periodo (serve ai report mangimi). Test con dati di esempio. --- ## FASE 7 — Mangimi: magazzino + somministrazioni + scorte/alert + report **Prompt 7.1** > CRUD **mangimi** (anagrafica + soglia_minima_kg), **mangimi_acquisti** (entrate magazzino: kg, > costo, fornitore, data) e **mangimi_somministrazioni** (uscite: mangime, gruppo, kg, data). **Prompt 7.2** > Calcolo **scorta** per mangime (Σ acquisti − Σ somministrazioni), **prezzo medio al kg**, e > **alert scorte** (badge/elenco quando scorta < soglia). Mostra l'alert in dashboard e nella sezione > mangimi. **Prompt 7.3** > **Report consumo/costo per capo**: dato un gruppo e un periodo, calcola kg somministrati, > consistenza media (da ConsistenzaService), consumo medio/capo e costo/capo (consumo × prezzo medio > kg + eventuale costo acquisto animali). Tabella + eventuale grafico semplice. --- ## FASE 8 — Spese **Prompt 8.1** > CRUD **spese_categorie** (configurabili, admin) e **spese** (categoria, data, descrizione, importo, > fornitore, link, note, allegato opzionale con upload protetto). Per l'attribuzione, l'utente sceglie > il **livello**: Generale / Sezione / Elemento (coltivazione o tipo animale) / Variante (= razza, > **solo animali**), valorizzando uno solo tra `sezione_id`/`elemento_id`/`variante_id` come da > CLAUDE.md 5.5. Per le coltivazioni il livello più profondo è Elemento. UI con select dipendenti > (sezione → elemento → razza, dove la razza appare solo se l'elemento è animale). **Prompt 8.2** > **Report spese**: totali per categoria, per periodo, e per **livello gerarchico** risalendo > (variante=razza) → elemento → sezione (CLAUDE.md 5.5): il totale di una sezione include sia le spese > attribuite alla sezione sia quelle di elementi (e, per animali, razze) che vi appartengono; mostra il > dettaglio per singola coltivazione/tipo animale e, per gli animali, per singola razza. Filtri data. > Includi nei totali generali anche la spesa mangimi (aggregata dal modulo mangimi). **Prompt 8.3 — Export PDF per elemento (e razza, solo animali)** > Implementa l'export PDF con **Dompdf** (CLAUDE.md 5.7), tramite template Twig di stampa dedicati > in `templates/pdf/`. Endpoint protetti da auth: > - **Elemento coltivazione** (es. Pomodori): PDF con sezione+nome, calendario attività (settimane > verde/giallo per mese), risorse online, storico completo (varietà annotate nelle note), e **spese > specifiche** a livello elemento (con totale). > - **Elemento animale** (es. Galline): come sopra + gruppi e sintesi movimenti/consistenza + razze. > - **Razza** (solo animali): PDF con origine, calendario/attività dell'elemento padre, storico filtrato > sulla razza, gruppi/consistenza di quella razza, e **spese specifiche** della razza (con totale). > CSS print-friendly con palette di brand, bottone "Esporta PDF" nelle pagine di dettaglio > elemento/razza. Attenzione a `memory_limit` (PDF leggeri). --- ## FASE 9 — Dashboard / report generali **Prompt 9.1** > **Dashboard** home: alert scorte mangimi, prossime attività (settimana corrente + successive dal > calendario), riepilogo spese del periodo, consistenza animali per gruppo. Solo dati, niente fronzoli. **Prompt 9.2** > Report **costo totale per capo** (mangimi + quota spese animali attribuite) e **riepilogo annuale > orto** (attività svolte da `attivita_storico`, con esiti/note per pianificare l'anno dopo). > Includi un **riepilogo macellazioni** per gruppo/periodo: numero capi macellati, peso totale > lavorato e peso medio per capo (da `gruppo_movimenti.peso_lavorato_kg`). --- ## FASE 10 — Deploy incrementale + documentazione **Prompt 10.1** > Implementa lo script di deploy in `deploy/` (CLAUDE.md sezione 3): (1) `composer install --no-dev > --optimize-autoloader`, (2) build Tailwind minificata, (3) upload incrementale via SFTP/FTPS dei > soli file con hash cambiato rispetto a `deploy/manifest.json`, escludendo `.env`, `.git`, > `node_modules`, sorgenti di sviluppo. Primo deploy = full (incluso `vendor/`). Aggiorna il manifest > a fine upload. Credenziali da `.env`. Usa `phpseclib3` come dev-dependency dello script se l'estensione > ftp/ssh2 non è disponibile. **Prompt 10.2** > Scrivi `deploy/README.md`: prerequisiti, primo deploy, deploy incrementali, come applicare le > migrazioni via phpMyAdmin (ordine dal CHANGELOG), configurazione `.htaccess` per proteggere > `/src`, `/templates`, `/storage`, `/vendor`, `/database` e nascondere `.env`, e checklist di > verifica post-deploy (login magic link, invio email SMTP OVH, calendario, permessi ruoli). --- --- ## FASE 11 — Interventi per luogo (registro operativo) **Prompt 11.1** > Crea il modulo **interventi** (CLAUDE.md 5.8), distinto dalle `attivita` stagionali. Migrazione SQL: > tabella `tipi_intervento` (lookup configurabile: nome, ambito colturale/animale/generico, ordine, > attivo) e tabella `interventi` (luogo_id, tipo_intervento_id, data, elemento_id opzionale, descrizione, > costo opzionale, eseguito_da, created_at). Seed dei tipi: Concimazione, Pulizia, Irrigazione, > Trattamento, Manutenzione, Raccolta. Ricorda il CHANGELOG e l'applicazione via phpMyAdmin in prod. **Prompt 11.2** > CRUD **tipi_intervento** (admin) e **interventi** (admin/editor; viewer in sola lettura). Form di > **inserimento rapido** mobile-friendly (luogo, tipo, data preimpostata a oggi, note, costo opzionale; > i tipi proposti filtrati per ambito del luogo). Vista **timeline per luogo** (storico interventi di > quel luogo) e **elenco generale** con filtri luogo/tipo/periodo. In **dashboard**: ultimi interventi. **Modifica M1 — Rimozione varietà colturali (migrazione)** > Rimuovi la gestione delle **varianti per gli elementi di sezioni con modello `colturale`**: niente > CRUD varietà per le coltivazioni, le varietà si scrivono nel campo note dell'elemento o dello storico. > Mantieni le `varianti` come **razze** solo per gli elementi di modello `animale`. Aggiorna: lo storico > colturale non referenzia più una variante (variante_id NULL); l'attribuzione **spese** per il colturale > arriva al massimo a livello **elemento**, mentre per gli animali resta il livello razza; l'export PDF > del colturale è solo a livello elemento. **Migra i dati**: se ci sono varianti colturali già inserite, > riportane il nome nelle note dell'elemento prima di rimuoverle. Non rompere le foreign key. **Modifica M2 — Fix report consumo/costo per capo (consistenza media)** > Nel report consumo/costo per capo: di default imposta "Dal" al **primo movimento di popolazione del > gruppo** (non un anno fisso indietro) e "Al" a oggi. Calcola la **consistenza media ponderata solo sui > giorni in cui il gruppo ha avuto capi > 0** nel periodo selezionato, così i giorni a zero capi non > diluiscono la media facendo esplodere il consumo/capo. Mostra accanto al risultato il numero di giorni > effettivi considerati. ## Note finali - Procedere **una fase alla volta**, verificando in locale prima di passare oltre. - Tenere `CLAUDE.md` come unica fonte di verità: se emergono modifiche al modello dati, aggiornarlo lì. - Dare priorità in produzione a: protezione file sensibili (.env, vendor, src) e funzionamento SMTP. - Prompt integrativi rimasti da eseguire alla fine: **5.3** (mobile) e **8.3** (export PDF).