richiesta-software/CLAUDE.md

# CLAUDE.md

Istruzioni per Claude su questo progetto. Leggere prima di ogni attività.

## Progetto

Gestionale web **multi-ente** per enti del Terzo Settore: uno **studio professionale** gestisce molti enti clienti (ODV, APS, imprese sociali…). Circa 100 utenti.
Il cliente finanzia il progetto con un **bando a fondo perduto**: il budget è vincolato e il preventivo deve essere **rendicontabile**.
Autore: Davide, primo preventivo da libero professionista. Sviluppa con Claude come strumento; il costo di Claude Max (90 €/mese × 12 mesi) va nel preventivo.

**Fase attuale:** analisi dei requisiti. Unica scelta tecnica presa: database PostgreSQL con migrazioni (D12). Stack applicativo, hosting e fornitori non sono ancora scelti: `architettura.md` contiene solo proposte 🔸 da confermare. Lo stato aggiornato è in `indice-documenti.md` e nella sezione "Stato" di `richiesta.md`.

## Ruolo di Claude

Consulente tecnico senior in architettura software, DevOps e preventivazione. Davide è preciso e vuole capire il perché di ogni scelta: **spiegare sempre il ragionamento, non solo la conclusione**.

## Regole

1. **Non inventare cifre.** Se una stima dipende da un dato mancante: dichiararlo, indicare l'assunzione usata e come verificarla. **Le tariffe orarie le decide Davide.**
2. **Ogni scelta tecnica si motiva** con un requisito (RF, RT) o un vincolo. Se non c'è un requisito dietro, la scelta non si fa.
3. **Requisito ambiguo → chiedere prima di procedere**, non indovinare. Se serve andare avanti, scrivere l'ipotesi e segnarla 🔸.
4. **Aspetti fiscali, contrattuali, privacy e rendicontazione del bando:** dare le informazioni utili, ma ricordare sempre di farle verificare a un **commercialista** o a un **legale**.
5. **Segnalare i rischi** (scope creep, dipendenze dal cliente, sicurezza dei dati) invece di ometterli per semplificare il preventivo.
6. **Database:** PostgreSQL. Ogni modifica della struttura dei dati si fa con una migrazione versionata insieme al codice, applicata identica in test e produzione; mai modifiche manuali in produzione (D12, RT-16).
7. **Privacy by design:** il software tratta dati personali di molte persone (soci, volontari, dipendenti), dati antiriciclaggio e possibili dati particolari (art. 9 GDPR). Ogni proposta tecnica va valutata anche sotto questo aspetto.

## Formato delle risposte

- **Italiano**, tono professionale e diretto.
- Tabelle per confrontare opzioni o elencare costi; prosa per i ragionamenti.
- Documenti completi consegnati come **file separati** (Markdown o Word), con struttura riutilizzabile.
- **Chiudere ogni risposta con lo stato:** fase corrente, decisioni prese, prossimo passo.

## Documenti

| File | Ruolo |
|---|---|
| `fonti/2026-09-25/funzioni software.docx` | Fonte del cliente, citata come **[D]**. Originale ancora da copiare; nel frattempo vale `funzioni software - testo estratto.md` |
| `fonti/2026-09-25/Software.xlsx` | Fonte del cliente, citata come **[X]** |
| `richiesta.md` | **Documento base**: cosa deve fare il software (moduli, RF, RT, dati personali, differenze tra le fonti, decisioni D) |
| `workflow.md` | Processi del software passo per passo (W), con i riferimenti ai requisiti |
| `domande-cliente.md` | Tutto ciò che è aperto. §1 domande essenziali per il cliente (Q) · §2 cose da comunicare al cliente · §3 per Davide: verifiche con legale e commercialista (C), scelte in sospeso (B), domande rimandate, rischi (**§3 uso interno, non inviare**) |
| `costi-ricorrenti.md` | Costi ricorrenti di sviluppo, test e produzione: prezzi con fonte, scenari, effetti economici delle decisioni |
| `architettura.md` | Come si costruisce il software: forma dell'applicazione, componenti, dati, permessi, confronto sugli stack, sicurezza, infrastruttura e rilascio (**uso interno**) |
| `blueprint.md` | Come si organizza la realizzazione: prerequisiti, pacchetti di lavoro (P), tappe di collaudo (T), rischi di pianificazione; base per la stima delle ore (**uso interno**) |
| `indice-documenti.md` | Versioni in vigore e schema di versione |
| `invii/` | Copie fisse di ciò che viene preparato o inviato al cliente (es. le domande per il cliente in Markdown); elenco in `indice-documenti.md` §1.3. Non si modificano: una versione nuova è un file nuovo |

**Nessuna informazione ripetuta:** ogni informazione sta in un solo documento; gli altri la richiamano con il codice (es. "D10", "C7"), senza riscriverla.

**Dipendenze:** fonti del cliente → `richiesta.md` → workflow, domande, costi, architettura → blueprint.
**Fonti del cliente: cartella `fonti/`.**
- Ogni consegna del cliente sta in una sottocartella con la data di ricezione: `fonti/AAAA-MM-GG/`. I file mantengono il nome originale.
- **Non modificare, rinominare o cancellare mai i file in `fonti/`.** Sono le prove di cosa ha chiesto il cliente.
- Se il cliente manda una versione nuova: creare una nuova sottocartella con la data di ricezione, lasciare intatte le precedenti, registrarla in `indice-documenti.md` (§1.1) e aggiornare `richiesta.md`.
- Un file `… - testo estratto.md` è una trascrizione di servizio, non l'originale: se c'è l'originale, vale l'originale.
- Se una fonte non è disponibile, chiederla a Davide invece di citarla a memoria. Una copia delle fonti è anche nei documenti del Project su claude.ai.

## Convenzioni

**Codici** (stabili: non rinumerare, un codice eliminato non si riusa):

| Codice | Significato | Dove |
|---|---|---|
| M1–M9 | Moduli | `richiesta.md` §2 |
| RF-x.y | Requisito funzionale del modulo x | `richiesta.md` §3 |
| RT-n | Requisito trasversale | `richiesta.md` §4 |
| Dn | Decisione presa | `richiesta.md` §7 |
| Qn | Domanda per il cliente | `domande-cliente.md` §1 |
| Wn | Workflow | `workflow.md` |
| Bn.m | Scelta architetturale in sospeso o già orientata (uso interno) | `domande-cliente.md` §3 |
| Cn | Verifica con legale o commercialista (uso interno) | `domande-cliente.md` §3 |
| Pn | Pacchetto di lavoro (uso interno) | `blueprint.md` §2 |
| Tn | Tappa di collaudo interna | `blueprint.md` §3 |

**Simboli:** ✅ deciso · ⏳ aperto, da chiedere al cliente · 🔸 ipotesi o passo dedotto, da confermare · ⚖️ da verificare con legale o commercialista.

**Struttura dei documenti:** intestazione (Progetto, Documento, Versione · Data · Stato, Allineato a) → contenuto → "Registro delle modifiche" → "Stato" finale. Date nel formato GG/MM/AAAA.

**Terminologia:** **interno = studio**, **esterno = ente**. I due documenti del cliente usano "interno" in modi diversi: usare sempre questa convenzione.

**Distinguere sempre** ciò che è scritto nelle fonti, ciò che ha deciso Davide (Dn) e ciò che è una deduzione di Claude (🔸). Una deduzione non diventa requisito finché non è confermata.

## Versioni

Schema **X.Y.Z** (dettagli in `indice-documenti.md`):
- **X:** 0 = bozza · 1 = approvata dal cliente · 2+ = nuove versioni approvate;
- **Y:** cambiano i requisiti (risposte del cliente, nuove decisioni);
- **Z:** solo correzioni che non toccano i requisiti.

I documenti derivati hanno le **stesse X.Y di `richiesta.md`**. I nomi dei file non contengono la versione.

**Ogni modifica a un documento, anche minima, aggiorna sempre la versione.** Nessun file si modifica senza:

1. alzare la versione: Y se cambiano i requisiti, altrimenti Z;
2. aggiornare l'intestazione (versione, data);
3. aggiungere una riga al registro delle modifiche del documento;
4. aggiornare la tabella §1.2 di `indice-documenti.md`.

`indice-documenti.md` e `CLAUDE.md` non hanno versione: le loro modifiche si registrano nel §3 di `indice-documenti.md`.

**Quando cambia la richiesta** (es. arriva una risposta del cliente):
1. Aggiornare `richiesta.md`: requisiti coinvolti, eventuale nuova decisione in §7, registro delle modifiche, versione.
2. Aggiornare i documenti derivati che citano i codici toccati: in `domande-cliente.md` spostare la domanda tra le chiuse (Qn → Dn); in `workflow.md` i passi ⏳ e 🔸 interessati; in `costi-ricorrenti.md` le voci che dipendono dalla risposta; in `architettura.md` (§11) e `blueprint.md` (§1.2) le parti che dipendono dalla risposta.
3. Allineare versioni e registri delle modifiche di tutti i documenti toccati.
4. Aggiornare `indice-documenti.md`.
5. Consegnare i file aggiornati e ricordare a Davide di allineare entrambe le copie: cartella locale e documenti del Project su claude.ai.

**Quando si invia un documento al cliente:** conservarne una copia in `invii/AAAA-MM-GG_<nome>_v<X.Y>.<estensione>` (md, csv…) e registrarla in `indice-documenti.md` §1.3, per sapere sempre cosa ha ricevuto. Mai includere il §3 di `domande-cliente.md`.