davide/CRAPP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Riscrive AGENTS.md e riallinea la documentazione allo stato reale.

Browse Source 
I riferimenti ai documenti in AGENTS.md erano rotti: una venticinquina di link
nella forma docs/[README.md](http://README.md), che spezzavano il nome del file
a meta e puntavano a domini inesistenti. Ora sono percorsi relativi verificati,
con CHANGELOG.md e DESIGN_DECISIONS.md sotto docs/ e PROJECT_STATE.md in root.

Tolte da AGENTS.md le sezioni Architettura, Documentazione e Struttura della
documentazione: duplicavano ARCHITECTURE.md e docs/README.md con uno stack ormai
parziale, contro la regola "ogni informazione ha una sola casa" che docs/README.md
stesso impone. Aggiunti invece i comandi, bun e la guardia minimumReleaseAge:
Codex e Cursor leggono solo AGENTS.md e non avevano modo di sapere come si
verifica una modifica. Scritta la checklist "Fine lavoro" che CLAUDE.md citava
senza che esistesse.

Nuova regola: chi aggiunge o modifica una funzione scrive o aggiorna il test nello
stesso lavoro, i test devono essere verdi e la doc del modulo va aggiornata se il
comportamento cambia (DD-020). Serve perche con main come branch di lavoro non
c'e piu un ambiente di prova tra il codice e i giocatori.

Il flusso git documentato non descriveva piu la realta: main e arrivato a 43
commit di vantaggio su develop, rimasto fermo. DD-003 e ora sostituita da DD-019:
il branch dei commit lo decide l'utente, l'assistente al massimo consiglia un
branch dedicato e non committa, non pusha e non apre PR di propria iniziativa.

Allineati di conseguenza ARCHITECTURE.md (sezione branch), README.md (flusso,
install con bun, comandi di test e lint), ROADMAP.md e TODO.md (le voci spuntate
sono in produzione, non su develop) e PROJECT_STATE.md (auth e profilo giocatore
in produzione, 20 migration fino a M9, passaggi 1-3 e 5 fatti).

Corretti poi sei disallineamenti tra documentazione e codice, ognuno verificato
sul sorgente:

- badge.md e obiettivi-squadra.md dicevano che le serie sono inerti e che
  serieAllenamenti e sempre 0, quindi badge e obiettivo "Continuita di squadra"
  non sbloccabili. Falso da 7237e8f: presenze.ts:48 le calcola e rosa.ts:64-67 le
  attacca al Giocatore. Il limite che resta e un altro, ora scritto: risposto_il
  non e ricostruibile prima di m9, quindi sulle risposte vecchie serieConferme e
  un'approssimazione.
- TODO.md e PROJECT_STATE.md davano il tracciamento tesseramento CSI come da
  fare, mentre ROADMAP, CHANGELOG e DATABASE lo davano per fatto. Lo e:
  admin.tsx:264-278 registra numero e data, :472 mostra Tesserato/Da tesserare,
  :676 il contatore.
- collegamento-csi.md indicava il check di parsing in src/lib/csi-core.test.ts;
  sta in test/unit/csi-core.test.ts, in src/lib non esiste nessun .test.ts.
- profilo-giocatore.md annunciava cinque aree del profilo e ne elencava sette.
- "Segnala un bug" e "Suggerisci una nuova funzionalita" (profilo.tsx:259-276,
  commit 72a9864) non erano documentati da nessuna parte, contro DD-002: ora
  stanno in profilo-giocatore.md e nel CHANGELOG.

npm run test: 28/28 file ok. npm run lint: 12 problemi, identici a prima di
questa modifica e tutti in src/, non toccato qui.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
davide
2026-09-04 23:24:22 +02:00
co-authored by Claude Opus 5
parent 7237e8ff39
commit 822180bffc
13 changed files with 271 additions and 532 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+103 -410
View File
@@ -1,449 +1,142 @@
# CrAPP - AI Development Guide # CrAPP — regole per gli assistenti AI
Questo documento definisce le regole che qualsiasi assistente AI (Cursor, Claude Code, Codex, ChatGPT o altri) deve seguire quando lavora su questo progetto. Regole vincolanti per qualsiasi assistente AI (Claude Code, Codex, Cursor, ChatGPT) che lavora
su questo repository. Valgono integralmente; `CLAUDE.md` le richiama e non le ripete.
--- CrAPP è una PWA per la gestione di una squadra di pallavolo. Deve ridurre il lavoro degli
amministratori, aumentare il coinvolgimento dei giocatori, centralizzare le informazioni della
squadra e usare l'AI solo quando porta un beneficio reale. Il perché sta in
[docs/VISION.md](docs/VISION.md).
# Obiettivo del progetto ## Prima di modificare il codice
CrAPP è una Progressive Web App sviluppata per digitalizzare completamente la gestione di una squadra di pallavolo. 1. Leggi l'indice [docs/README.md](docs/README.md) e segui l'ordine di lettura che indica; poi
il documento del modulo interessato in [docs/modules/](docs/modules/).
2. Verifica lo stato attuale del repository: commit recenti, modifiche non committate, lavoro
introdotto da altri collaboratori o da altri assistenti.
3. Non presumere che il progetto sia come l'hai lasciato nell'ultima sessione: la fonte di
verità è il repository, non la cronologia della conversazione.
L'obiettivo principale è: Non implementare funzionalità non documentate: prima si documenta
([DD-002](docs/DESIGN_DECISIONS.md#dd-002--sviluppo-document-first)), poi si scrive il codice.
- ridurre il lavoro amministrativo degli amministratori; ## Comandi
- aumentare il coinvolgimento dei giocatori; Le dipendenze si installano con **bun** (`bun.lock`). `bunfig.toml` impone
`minimumReleaseAge = 24h` come guardia supply-chain: aggiungere un pacchetto a
`minimumReleaseAgeExcludes` richiede conferma esplicita dell'utente.
- centralizzare tutte le informazioni della squadra; ```bash
npm run dev # vite dev su http://localhost:8080
npm run build # build di produzione (nitro)
npm run lint # eslint (include prettier come regola)
npm run format # prettier --write .
npm run test # suite di test (test/); npm run test:all per quella completa
- utilizzare l'intelligenza artificiale solo quando porta un reale beneficio. npx supabase start # database locale in Docker (migration applicate + seed)
npx supabase db reset # ricrea il database locale da zero
npx supabase db push # applica le migration al progetto cloud
```
--- ## Test
# Prima di modificare il codice **Chi aggiunge o modifica una funzione scrive anche il test.** Non è opzionale e non si
rimanda: una funzione nuova senza test non è finita, una funzione modificata il cui test non
copre più il comportamento nuovo va aggiornata nello stesso lavoro.
Prima di implementare qualsiasi modifica leggere sempre: - I test devono **risultare verdi**: non si consegna con test rossi, non si commenta un test
che fallisce e non si indebolisce un'asserzione per farla passare. Se un test rosso segnala
un comportamento voluto che è cambiato, si aggiorna il test spiegando perché.
- La logica di dominio pura sta in `src/lib/` ed è quella da coprire in `test/unit/`: se una
funzione è difficile da testare perché mischia calcolo e hook, separala (`*-core.ts`) come
già fatto per palloni e pagelle.
- Convenzioni, struttura delle cartelle e comandi in [test/README.md](test/README.md).
- Se il comportamento cambia, cambia anche la documentazione: modulo in
[docs/modules/](docs/modules/), più i file elencati in Tracciabilità.
1. docs/[README.md](http://README.md) ## Fine lavoro
2. docs/[VISION.md](http://VISION.md) Prima di dire che hai finito:
3. docs/[ROADMAP.md](http://ROADMAP.md) 1. i test delle funzioni aggiunte o modificate esistono e sono verdi;
2. `npm run lint` e `npm run test` passano (`test:all` se hai toccato database o flussi e2e);
3. la documentazione toccata dalla modifica è aggiornata (vedi Test e Tracciabilità);
4. hai detto all'utente cosa hai cambiato, cosa hai lasciato fuori e quali rischi vedi.
4. docs/[ARCHITECTURE.md](http://ARCHITECTURE.md) ## Git
5. docs/[DATABASE.md](http://DATABASE.md) `main` è la versione in produzione: qualsiasi commit deve lasciare l'app funzionante.
`develop` pubblica una preview Vercel, ma oggi è fermo indietro rispetto a `main` e non
rappresenta lo stato attuale (DD-019). I branch `feature/…`, `fix/…`, `refactor/…` servono per
lavori paralleli o rischiosi.
6. docs/DESIGN_[DECISIONS.md](http://DECISIONS.md) **È l'utente a decidere su quale branch va un commit.** L'assistente può consigliare un branch
dedicato quando la modifica è rischiosa o parallela ad altro lavoro, ma non cambia branch né
apre PR di propria iniziativa. In assenza di indicazioni si lavora dove si trova il repository.
7. docs/[TODO.md](http://TODO.md) Non committare, non fare push e non aprire PR senza che l'utente lo abbia chiesto.
8. il documento interessato in docs/modules/ ## Tracciabilità
Inoltre, prima di iniziare una nuova attività: Ogni modifica significativa deve lasciare una traccia leggibile senza la cronologia delle
conversazioni: commit con messaggio descrittivo, più il documento giusto tra
[docs/CHANGELOG.md](docs/CHANGELOG.md) (cosa è stato rilasciato e quando),
[PROJECT_STATE.md](PROJECT_STATE.md) (stato generale del progetto),
[docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md) (decisioni architetturali, voci `DD-XXX`),
[docs/ROADMAP.md](docs/ROADMAP.md), [docs/TODO.md](docs/TODO.md),
[docs/DATABASE.md](docs/DATABASE.md) (se cambia lo schema).
- verificare lo stato attuale del repository; Quali contenuti vanno in quale file, e le convenzioni di scrittura, stanno nelle regole di
manutenzione di [docs/README.md](docs/README.md): ogni informazione ha una sola casa, non
duplicarla altrove.
- controllare le modifiche e i commit recenti; ## Database
- verificare eventuali modifiche introdotte da altri sviluppatori o assistenti AI; Il database è Supabase; lo schema documentato sta in [docs/DATABASE.md](docs/DATABASE.md),
allineato alle migration in `supabase/migrations/`.
- leggere la documentazione aggiornata relativa alla funzionalità interessata. - Ogni modifica allo schema è una **nuova** migration: le migration già applicate sono storia
e non si riscrivono.
- Non eliminare tabelle esistenti, non modificare lo schema senza motivazione.
- Ordine: progetta → documenta → crea la migration → testala in locale (`npx supabase db reset`)
→ verifica l'assenza di regressioni → solo dopo applicala in produzione.
- Preferisci strutture scalabili, evita duplicazione dei dati.
Non implementare funzionalità non documentate. ## Codice e interfaccia
Non presumere che il progetto sia nello stesso stato dell'ultima sessione o conversazione. L'architettura tecnica (stack, struttura delle cartelle, punti fermi da non rompere) sta in
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): leggila prima di toccare routing, `vite.config.ts`,
client Supabase o autenticazione.
--- Componenti piccoli, riutilizzabili, a responsabilità singola. Prima di crearne uno nuovo,
verifica se esiste già in `src/components/`. L'interfaccia resta semplice, moderna, veloce,
ottimizzata per smartphone: poche schermate, pochi click, stile coerente con l'esistente.
# Workflow di sviluppo ## Regola anti-regressione
Ogni nuova funzionalità segue sempre questo processo. Le nuove versioni aggiungono funzionalità. Non riscrivere moduli già funzionanti senza una
motivazione esplicita, e non fare refactoring trasversali mentre sviluppi altro. Prima di
modificare un modulo esistente verifica quali altre parti dell'app lo usano.
Idea ## L'AI non deve
↓
Progettazione
↓
Documentazione
↓
Database
↓
Implementazione
↓
Test
↓
Pull Request
↓
Merge su develop
↓
Verifica
↓
Merge su main
↓
Deploy
Le funzionalità possono essere sviluppate in parallelo da persone diverse, ciascuna sul proprio branch.
---
# Git
Il repository utilizza due branch principali.
## main
Versione stabile.
Qualsiasi modifica deve mantenere l'app perfettamente funzionante.
`main` rappresenta la versione destinata alla produzione.
## develop
Branch di integrazione e test.
Le nuove funzionalità vengono integrate in `develop` prima di arrivare in `main`.
Non lavorare direttamente su `main`.
Evitare modifiche dirette a `develop`, salvo attività esplicitamente concordate.
---
# Branch di sviluppo
Ogni sviluppatore deve lavorare su un branch dedicato creato a partire da `develop`.
Esempi:
- `feature/profilo-giocatore`
- `feature/integrazione-csi`
- `fix/presenze`
- `refactor/supabase-client`
Non utilizzare lo stesso branch contemporaneamente per attività indipendenti.
Prima di iniziare un'attività verificare che il branch sia aggiornato rispetto a `develop`.
---
# Integrazione delle modifiche
Le modifiche significative devono essere integrate tramite Pull Request verso `develop`.
Una Pull Request dovrebbe permettere di capire:
- cosa è stato modificato;
- perché è stato modificato;
- quali file o moduli sono coinvolti;
- se il database è stato modificato;
- quali test sono stati eseguiti;
- eventuali rischi o conseguenze.
Prima del merge verificare eventuali conflitti con il lavoro sviluppato nel frattempo dagli altri collaboratori.
---
# Tracciabilità delle modifiche
Ogni modifica significativa deve lasciare una traccia nel progetto.
Devono essere utilizzati:
- commit con messaggi descrittivi;
- Pull Request per l'integrazione;
- [CHANGELOG.md](http://CHANGELOG.md) quando una modifica deve essere registrata nella cronologia del progetto;
- PROJECT_[STATE.md](http://STATE.md) quando cambia lo stato generale del progetto;
- DESIGN_[DECISIONS.md](http://DECISIONS.md) per decisioni architetturali significative.
La documentazione deve permettere a uno sviluppatore o a un assistente AI di ricostruire cosa è successo senza dipendere dalla cronologia delle conversazioni.
---
# Aggiornamento del contesto dopo la sincronizzazione
Quando vengono scaricate modifiche da GitHub, l'assistente AI deve considerare il repository come fonte di verità.
Prima di iniziare una nuova attività deve:
1. verificare i nuovi commit;
2. identificare le modifiche rilevanti;
3. leggere la documentazione modificata;
4. verificare eventuali modifiche al database;
5. tenere conto delle nuove decisioni architetturali.
Non ignorare modifiche introdotte da altri collaboratori.
Non sovrascrivere modifiche esistenti senza averne compreso lo scopo.
---
# Architettura
Frontend
- React
- TypeScript
- TanStack Start
- Tailwind CSS
Backend
- Supabase
Hosting
- Vercel
Repository
- GitHub
---
# Database
Il database utilizza Supabase.
Regole:
- non eliminare tabelle esistenti;
- non modificare lo schema senza creare una migration;
- preferire strutture scalabili;
- evitare duplicazione dei dati;
- non modificare migration già applicate;
- ogni modifica allo schema deve essere rappresentata da una nuova migration.
Fare sempre riferimento a:
docs/[DATABASE.md](http://DATABASE.md)
---
# Componenti
Preferire:
- componenti piccoli;
- componenti riutilizzabili;
- responsabilità singola;
- codice semplice da mantenere.
Evitare duplicazioni.
Prima di creare un nuovo componente verificare se esiste già un componente riutilizzabile.
---
# Interfaccia
Lo stile dell'app deve rimanere coerente.
Principi:
- semplice;
- moderna;
- pulita;
- veloce;
- ottimizzata per smartphone;
- poche schermate;
- pochi click.
---
# Documentazione
Ogni nuova funzionalità deve essere documentata prima dello sviluppo.
La documentazione dei moduli si trova in:
docs/modules/
Aggiornare sempre, quando necessario:
- [ROADMAP.md](http://ROADMAP.md)
- [CHANGELOG.md](http://CHANGELOG.md)
- [TODO.md](http://TODO.md)
- [DATABASE.md](http://DATABASE.md) (se il database cambia)
- DESIGN_[DECISIONS.md](http://DECISIONS.md) (se si prende una decisione architetturale importante)
- PROJECT_[STATE.md](http://STATE.md) (se cambia lo stato generale del progetto)
---
# Struttura della documentazione
La cartella `docs/` rappresenta la documentazione ufficiale del progetto.
## Documenti principali
- [README.md](http://README.md) → panoramica del progetto
- [VISION.md](http://VISION.md) → obiettivi e filosofia
- [ROADMAP.md](http://ROADMAP.md) → evoluzione prevista
- [ARCHITECTURE.md](http://ARCHITECTURE.md) → architettura tecnica
- [DATABASE.md](http://DATABASE.md) → struttura del database
- DESIGN_[DECISIONS.md](http://DECISIONS.md) → registro delle decisioni di progetto
- [CHANGELOG.md](http://CHANGELOG.md) → cronologia delle modifiche
- [TODO.md](http://TODO.md) → attività pianificate
- PROJECT_[STATE.md](http://STATE.md) → stato attuale del progetto
## Moduli
La cartella `docs/modules/` contiene una specifica funzionale per ogni modulo dell'applicazione.
Ogni nuovo modulo deve essere progettato e documentato prima dell'implementazione.
---
# Regola anti-regressione
Le nuove versioni devono principalmente aggiungere funzionalità.
Non riscrivere o modificare profondamente moduli già funzionanti senza una motivazione esplicita e una verifica degli impatti.
Evitare refactoring trasversali durante lo sviluppo di nuove funzionalità, salvo quando sono necessari per la funzionalità stessa.
Prima di modificare un modulo esistente verificare quali altre parti dell'app lo utilizzano.
---
# Regole per il database e le migration
Le migration già applicate sono parte della storia del database e non devono essere riscritte.
Per modificare il database:
1. progettare la modifica;
2. documentarla quando necessario;
3. creare una nuova migration;
4. testarla;
5. applicarla all'ambiente di sviluppo;
6. verificare l'assenza di regressioni;
7. solo successivamente applicarla all'ambiente di produzione.
---
# Regole
L'AI non deve:
- introdurre librerie senza necessità;
- modificare il database senza motivazione;
- introdurre librerie senza necessità, né aggirare `minimumReleaseAge`;
- modificare il database o il comportamento dell'app senza richiesta esplicita;
- eliminare funzionalità esistenti; - eliminare funzionalità esistenti;
- sovrascrivere modifiche di altri collaboratori senza averne compreso lo scopo;
- modificare il comportamento dell'app senza richiesta esplicita;
- sovrascrivere modifiche di altri collaboratori senza comprenderle;
- riscrivere migration già applicate; - riscrivere migration già applicate;
- committare, pushare o cambiare branch di propria iniziativa.
- lavorare direttamente su `main`; ## L'AI deve
- assumere che il repository sia invariato rispetto all'ultima sessione.
L'AI deve:
- spiegare le modifiche importanti;
- mantenere compatibilità con il codice esistente;
- spiegare le modifiche importanti e segnalare rischi, conflitti e possibili regressioni
**prima** di toccare parti sensibili;
- mantenere la compatibilità con il codice esistente e riutilizzare i componenti;
- privilegiare la semplicità; - privilegiare la semplicità;
- tenere aggiornata la documentazione quando serve.
- riutilizzare i componenti esistenti; ## Filosofia
- controllare il lavoro recente degli altri collaboratori; Prima di scrivere codice: questa modifica rende CrAPP più semplice? Riduce il lavoro degli
amministratori? Migliora l'esperienza dei giocatori? È coerente con la documentazione? Riduce
- mantenere aggiornata la documentazione quando necessario; o aumenta la complessità futura? Se almeno una risposta è negativa, rivaluta la soluzione.
- segnalare conflitti, rischi e possibili regressioni prima di modificare parti sensibili.
---
# Filosofia del progetto
Prima di scrivere codice chiedersi sempre:
Questa modifica rende CrAPP più semplice?
Riduce il lavoro degli amministratori?
Migliora l'esperienza dei giocatori?
È coerente con la documentazione?
Riduce oppure aumenta la complessità futura?
Se almeno una risposta è negativa, rivalutare la soluzione proposta.
CLAUDE.md
+5 -22
View File
@@ -1,26 +1,9 @@
# CLAUDE.md # CLAUDE.md
Le regole di progetto stanno in @AGENTS.md: valgono integralmente e non sono ripetute qui. Le regole di progetto stanno in @AGENTS.md: valgono integralmente e non sono ripetute qui —
La documentazione tecnica è indicizzata in [docs/README.md](docs/README.md); l'architettura compresi i comandi (`npm run dev/lint/test`, supabase) e la checklist «Fine lavoro» da eseguire
in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). prima di dire che hai finito. La documentazione tecnica è indicizzata in
[docs/README.md](docs/README.md); l'architettura in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
**Non aggiungere regole in questo file.** Una regola nuova va in `AGENTS.md`, che leggono **Non aggiungere regole in questo file.** Una regola nuova va in `AGENTS.md`, che leggono
anche Codex e Cursor; scritta qui la vedrebbe solo Claude Code. Vale per qualsiasi aggiunta o anche Codex e Cursor; scritta qui la vedrebbe solo Claude Code.
modifica: prima di dire che hai finito, esegui la checklist «Fine lavoro» di `AGENTS.md`.
## Comandi
```bash
npm run dev # vite dev su http://localhost:8080
npm run build # build di produzione (nitro)
npm run lint # eslint (include prettier come regola)
npm run format # prettier --write .
npm run test # suite di test (test/); npm run test:all per quella completa
npx supabase start # database locale in Docker (migration applicate + seed)
npx supabase stop # spegne i container
npx supabase db reset # ricrea il database locale da zero
npx supabase db push # applica le migration al progetto cloud
```
Verifica minima prima di consegnare: `npm run lint` + `npm run test`.
PROJECT_STATE.md
+21 -20
View File
@@ -1,29 +1,28 @@
# Project State # Project State
Ultimo aggiornamento: 03/09/2026 Ultimo aggiornamento: 04/09/2026
## Stato generale ## Stato generale
Fase corrente: Fase corrente:
Backend migrato al nuovo Supabase proprietario. M1 completata. M2 scritta e da applicare. Backend migrato al nuovo Supabase proprietario. Autenticazione Google, dashboard
Autenticazione Google, dashboard amministratore e Profilo Giocatore (lato giocatore e lato amministratore e Profilo Giocatore (lato giocatore e lato admin) sono in produzione su `main`.
admin) implementati su `develop`, da attivare in produzione seguendo i passaggi più sotto.
Foto profilo (M6) e Scout Live (M7) non dipendono più da `localStorage`: entrambi ora Foto profilo (M6) e Scout Live (M7) non dipendono più da `localStorage`: entrambi ora
sincronizzano tra dispositivi tramite Supabase. sincronizzano tra dispositivi tramite Supabase. Le serie di presenze sono calcolate sui dati
reali (M9).
--- ---
## Infrastruttura ## Infrastruttura
- GitHub configurato con branch `main` e `develop` - Si lavora direttamente su `main` (DD-019): `develop` esiste ma è fermo indietro, quindi la
- Cursor come ambiente di sviluppo sua preview Vercel non rappresenta lo stato attuale
- Cursor e Claude Code come ambienti di sviluppo
- Vercel configurato; Environment Variables aggiornate al nuovo Supabase (Preview e Production) - Vercel configurato; Environment Variables aggiornate al nuovo Supabase (Preview e Production)
- Supabase proprietario attivo — Project Ref: `kfkcldwncxqaixetsjes` - Supabase proprietario attivo — Project Ref: `kfkcldwncxqaixetsjes`
- 18 migration locali applicate con successo al nuovo database - 20 migration in `supabase/migrations/`, fino a `m9_risposte_presenze_risposto_il`
- Sviluppo locale verificato con il nuovo Supabase - Sviluppo locale verificato con il nuovo Supabase
- Preview Vercel di `develop` verificata con successo (presenza scritta su `risposte_presenze` confermata nel nuovo database)
- Produzione (`main`): non ancora verificata in questa fase
--- ---
@@ -37,7 +36,7 @@ sincronizzano tra dispositivi tramite Supabase.
## Database ## Database
- Schema v1.0 + M1 applicati al nuovo Supabase - Schema v1.0 e migration da M1 a M9 applicate al nuovo Supabase
- `public.giocatori_squadra`: rosa iniziale di 17 giocatori (migration `m5_email_giocatori_squadra`) - `public.giocatori_squadra`: rosa iniziale di 17 giocatori (migration `m5_email_giocatori_squadra`)
più quelli aggiunti da `/admin` a stagione in corso; da settembre 2026 tutti i giocatori più quelli aggiunti da `/admin` a stagione in corso; da settembre 2026 tutti i giocatori
attivi hanno l'email registrata (colonna `email`, DD-018), impostabile da `/admin` senza attivi hanno l'email registrata (colonna `email`, DD-018), impostabile da `/admin` senza
@@ -65,13 +64,14 @@ sincronizzano tra dispositivi tramite Supabase.
- Pagelle - Pagelle
- MVP - MVP
- Notifiche - Notifiche
- Profilo Giocatore (su `develop`, specifica in `docs/modules/profilo-giocatore.md`) - Profilo Giocatore (specifica in `docs/modules/profilo-giocatore.md`)
- Serie di presenze (specifica in `docs/modules/serie-presenze.md`)
--- ---
## Autenticazione e dashboard amministratore ## Autenticazione e dashboard amministratore
Implementate su `develop`. **Il login è l'unica via d'accesso** (31/08/2026): la selezione In produzione su `main`. **Il login è l'unica via d'accesso** (31/08/2026): la selezione
libera del giocatore non esiste più, senza sessione Google si resta su `/benvenuto`, e i libera del giocatore non esiste più, senza sessione Google si resta su `/benvenuto`, e i
permessi di amministrazione arrivano solo da `user_roles`. permessi di amministrazione arrivano solo da `user_roles`.
@@ -82,12 +82,12 @@ Google» risponde
{"code":400,"error_code":"validation_failed","msg":"Unsupported provider: provider is not enabled"} {"code":400,"error_code":"validation_failed","msg":"Unsupported provider: provider is not enabled"}
``` ```
e **nessuno entra nell'app**, né in dev né sulla preview di `develop`. Il passo 1 qui sotto e **nessuno entra nell'app**. Vale ancora per chi allestisce un ambiente nuovo (per esempio
va fatto prima di mandare questa versione in produzione. lo stack Supabase locale): il passo 1 qui sotto va fatto per primo.
Passaggi in ordine, nessuno dei quali è reversibile a metà. **Stato al 03/09/2026: fatti i Passaggi in ordine, nessuno dei quali è reversibile a metà. **Stato al 04/09/2026: fatti i
passaggi 1-3; il passaggio 4 è un processo continuo (7 dei 16 giocatori attivi hanno già passaggi 1, 2, 3 e 5 (M4 applicata); il passaggio 4 è un processo continuo (7 dei 16 giocatori
fatto il primo accesso); il passaggio 5 (M4) è stato applicato.** attivi hanno già fatto il primo accesso).**
1. **Provider Google in Supabase** — Google Cloud Console: consent screen _External_ (scope 1. **Provider Google in Supabase** — Google Cloud Console: consent screen _External_ (scope
`email` e `profile`, non sensibili: nessuna verifica richiesta, e la modalità _Testing_ `email` e `profile`, non sensibili: nessuna verifica richiesta, e la modalità _Testing_
@@ -125,8 +125,9 @@ collega uno slot lo occupa anche in produzione, e va liberato da un admin.
## Prossimo sviluppo ## Prossimo sviluppo
Gestione tesseramenti CSI: la raccolta dati e l'export CSV sono pronti, manca il Niente di assegnato: la v1.1 è completa, tesseramento CSI incluso (numero e data di tessera
tracciamento di chi è già tesserato (numero e data di tessera). registrabili da `/admin`, migration `m8_tesseramento_csi`). Le voci ancora aperte stanno in
[docs/ROADMAP.md](docs/ROADMAP.md).
--- ---
README.md
+22 -56
View File
@@ -14,58 +14,37 @@ CrAPP è una Progressive Web App sviluppata per digitalizzare completamente la g
- Gestione amministrativa - Gestione amministrativa
- AI per la pianificazione degli allenamenti (in sviluppo) - AI per la pianificazione degli allenamenti (in sviluppo)
---
## Stack tecnologico ## Stack tecnologico
- React 19 React 19, TypeScript, TanStack Start (SSR), Vite 8, Tailwind CSS 4, Radix UI / shadcn,
- TypeScript Supabase (PostgreSQL, Auth, Storage), Vercel, GitHub. Dettagli in
- TanStack Start [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
- Vite
- Tailwind CSS
- Supabase
- GitHub
- Vercel
---
## Ambienti
- `main` → Produzione
- `develop` → Sviluppo
---
## Avvio locale ## Avvio locale
```bash Le dipendenze si installano con **bun** (`bun.lock`):
npm install
npm run dev
```
L'app sarà disponibile su:
```
http://localhost:8080
```
---
## Build
```bash ```bash
npm run build bun install
npm run dev # http://localhost:8080
``` ```
--- ## Comandi
```bash
npm run build # build di produzione
npm run lint # eslint (include prettier)
npm run test # test unit; npm run test:all per la suite completa
```
Chi aggiunge o modifica una funzione scrive anche il test e lo lascia verde
([test/README.md](test/README.md)).
## Deploy ## Deploy
Il deploy è automatico tramite Vercel ad ogni push sul branch `main`. Deploy automatico su Vercel a ogni push su `main`, che è anche il branch di lavoro corrente.
`develop` pubblica un Preview Deployment, ma oggi è indietro rispetto a `main`. Su quale branch
Le modifiche sviluppate nel branch `develop` vengono pubblicate automaticamente come Preview Deployment. committare lo decide chi sviluppa (DD-019).
---
## Variabili d'ambiente ## Variabili d'ambiente
@@ -76,20 +55,7 @@ Il progetto richiede le seguenti variabili:
- `VITE_SUPABASE_URL` - `VITE_SUPABASE_URL`
- `VITE_SUPABASE_PUBLISHABLE_KEY` - `VITE_SUPABASE_PUBLISHABLE_KEY`
--- ## Documentazione
## Repository Indice in [docs/README.md](docs/README.md). Le regole per gli assistenti AI stanno in
[AGENTS.md](AGENTS.md), lo stato corrente del lavoro in [PROJECT_STATE.md](PROJECT_STATE.md).
Il codice sorgente è gestito tramite GitHub.
Flusso di sviluppo:
```
develop
↓
Test
↓
Merge su main
↓
Deploy automatico Vercel
```
docs/ARCHITECTURE.md
+6 -5
View File
@@ -116,9 +116,10 @@ dove provare le migration distruttive senza toccare i dati veri.
## Branch e flusso di sviluppo ## Branch e flusso di sviluppo
- `main` → produzione, deploy automatico su Vercel. - `main` → produzione, deploy automatico su Vercel. È anche il branch di lavoro corrente.
- `develop` → sviluppo; si lavora qui, mai direttamente su `main` (DD-003). - `develop` → preview Vercel; oggi indietro rispetto a `main`, non rappresenta lo stato attuale.
- `feature/…`, `fix/…`, `refactor/…` → lavori rischiosi o paralleli.
``` Su quale branch va un commit lo decide l'utente (DD-019): un assistente AI può consigliare un
develop → test → merge su main → deploy automatico su Vercel branch dedicato, non sceglierlo. Poiché si lavora su `main`, la rete di sicurezza sono i test,
``` che vanno scritti insieme al codice e devono essere verdi (DD-020, [test/README.md](../test/README.md)).
docs/CHANGELOG.md
+8
View File
@@ -22,6 +22,14 @@ qui: sta in [ROADMAP.md](ROADMAP.md).
successivo: prima usava `valore/prossimo` e tornava indietro a ogni traguardo (2/3 = 67%, successivo: prima usava `valore/prossimo` e tornava indietro a ogni traguardo (2/3 = 67%,
poi 3/6 = 50%). poi 3/6 = 50%).
### Segnalazioni dal profilo
- «Segnala un bug» e «Suggerisci una nuova funzionalità» in `/profilo` → Impostazioni: due
link che aprono una issue GitHub sul template giusto
(`.github/ISSUE_TEMPLATE/bug_report.yml`, `feature_request.yml`). Nessuna tabella e nessuna
schermata di gestione: la segnalazione vive su GitHub
(vedi [modules/profilo-giocatore.md](modules/profilo-giocatore.md)).
### Autenticazione e dashboard amministratore (in produzione) ### Autenticazione e dashboard amministratore (in produzione)
- Login con Google tramite Supabase Auth (DD-011). Al primo accesso l'account si collega a - Login con Google tramite Supabase Auth (DD-011). Al primo accesso l'account si collega a
docs/DESIGN_DECISIONS.md
+79 -3
View File
@@ -20,7 +20,6 @@ Serve a rispondere a domande del tipo:
| --------------------------------------------------------------------------------- | ------------------------------------- | | --------------------------------------------------------------------------------- | ------------------------------------- |
| [DD-001](#dd-001--crapp-deve-restare-indipendente-da-lovable) | Indipendenza da Lovable | | [DD-001](#dd-001--crapp-deve-restare-indipendente-da-lovable) | Indipendenza da Lovable |
| [DD-002](#dd-002--sviluppo-document-first) | Sviluppo document-first | | [DD-002](#dd-002--sviluppo-document-first) | Sviluppo document-first |
| [DD-003](#dd-003--due-branch-main-stabile-develop-per-il-lavoro) | Branch main / develop |
| [DD-004](#dd-004--ogni-versione-aggiunge-non-riscrive) | Ogni versione aggiunge, non riscrive | | [DD-004](#dd-004--ogni-versione-aggiunge-non-riscrive) | Ogni versione aggiunge, non riscrive |
| [DD-005](#dd-005--mobile-first-pochi-click-pochi-schermi) | Mobile-first | | [DD-005](#dd-005--mobile-first-pochi-click-pochi-schermi) | Mobile-first |
| [DD-006](#dd-006--intelligenza-artificiale-solo-se-porta-beneficio-reale) | AI solo se utile | | [DD-006](#dd-006--intelligenza-artificiale-solo-se-porta-beneficio-reale) | AI solo se utile |
@@ -35,6 +34,8 @@ Serve a rispondere a domande del tipo:
| [DD-016](#dd-016--schema-dati-profilo-giocatore-v11-f0) | Schema dati Profilo Giocatore v1.1 | | [DD-016](#dd-016--schema-dati-profilo-giocatore-v11-f0) | Schema dati Profilo Giocatore v1.1 |
| [DD-017](#dd-017--lamministratore-può-compilare-i-dati-al-posto-del-giocatore) | L'admin scrive al posto del giocatore | | [DD-017](#dd-017--lamministratore-può-compilare-i-dati-al-posto-del-giocatore) | L'admin scrive al posto del giocatore |
| [DD-018](#dd-018--collegamento-automatico-giocatoreaccount-per-email) | Collegamento automatico per email | | [DD-018](#dd-018--collegamento-automatico-giocatoreaccount-per-email) | Collegamento automatico per email |
| [DD-019](#dd-019--il-branch-dei-commit-lo-decide-lutente) | Il branch lo decide l'utente |
| [DD-020](#dd-020--una-funzione-modificata-senza-test-non-è-finita) | Test obbligatori e verdi |
**In valutazione** **In valutazione**
@@ -42,6 +43,12 @@ Serve a rispondere a domande del tipo:
| ----------------------------------------------------------------- | ---------------------- | | ----------------------------------------------------------------- | ---------------------- |
| [DD-014](#dd-014--convergenza-schema-database-eventi-e-presenze) | Convergenza schema DB | | [DD-014](#dd-014--convergenza-schema-database-eventi-e-presenze) | Convergenza schema DB |
**Sostituite**
| ID | Titolo |
| ---------------------------------------------------------------- | --------------------- |
| [DD-003](#dd-003--due-branch-main-stabile-develop-per-il-lavoro) | Branch main / develop |
--- ---
## Come usare questo registro ## Come usare questo registro
@@ -139,7 +146,7 @@ Se il team diventa molto piccolo e la documentazione smette di essere consultata
### DD-003 — Due branch: main stabile, develop per il lavoro ### DD-003 — Due branch: main stabile, develop per il lavoro
**Data:** agosto 2026 **Data:** agosto 2026
**Stato:** Accettata **Stato:** Sostituita da [DD-019](#dd-019--il-branch-dei-commit-lo-decide-lutente) (settembre 2026)
**Contesto** **Contesto**
Serve separare ciò che i giocatori usano ogni giorno da ciò che è ancora in prova. Serve separare ciò che i giocatori usano ogni giorno da ciò che è ancora in prova.
@@ -160,7 +167,8 @@ Serve separare ciò che i giocatori usano ogni giorno da ciò che è ancora in p
- Ogni release su `main` deve includere verifica delle funzionalità esistenti. - Ogni release su `main` deve includere verifica delle funzionalità esistenti.
**Riesame** **Riesame**
Se il team cresce e servono review più granulari (pull request per feature). Sostituita: nella pratica il lavoro è finito direttamente su `main` e `develop` è rimasto
indietro. Vedi DD-019.
--- ---
@@ -592,3 +600,71 @@ agganciati allo stesso hook o, lato server, a `leggiGiocatoriSquadra()`
fonte viva. fonte viva.
--- ---
### DD-019 — Il branch dei commit lo decide l'utente
**Data:** 4 settembre 2026
**Stato:** Accettata — sostituisce [DD-003](#dd-003--due-branch-main-stabile-develop-per-il-lavoro)
**Contesto**
DD-003 prevedeva di lavorare su `develop` e portare su `main` solo dopo i test. Nella pratica
è successo il contrario: `main` è arrivato a 43 commit di vantaggio su `develop`, che è rimasto
fermo. Una regola che nessuno segue è peggio di nessuna regola, perché rende inaffidabile tutto
il resto del documento — e con più assistenti AI in gioco il rischio vero non era il branch
sbagliato, ma un agente che committa o pusha per conto suo.
**Decisione**
È l'utente a dire su quale branch va un commit. L'assistente può **consigliare** un branch
dedicato quando la modifica è rischiosa o parallela ad altro lavoro, ma non cambia branch, non
committa, non fa push e non apre PR di propria iniziativa. In assenza di indicazioni si lavora
dove si trova il repository, di fatto `main`.
**Alternative scartate**
- Tenere DD-003 e riallineare `develop` → si sarebbe rotta di nuovo alla prima fretta.
- Dismettere `develop` → si perderebbero le preview Vercel, utili quando servono davvero.
**Conseguenze**
- `main` è insieme produzione e branch di lavoro: ogni commit deve lasciare l'app funzionante,
quindi la rete di sicurezza sono i test (vedi DD-020), non il branch.
- `develop` esiste ancora ma è indietro: la sua preview Vercel non rappresenta lo stato attuale
finché non viene riallineata.
**Riesame**
Se il team cresce oltre una persona che scrive codice, o se un lavoro lungo ha bisogno di stare
fuori produzione per più di qualche giorno.
---
### DD-020 — Una funzione modificata senza test non è finita
**Data:** 4 settembre 2026
**Stato:** Accettata
**Contesto**
Con `main` come branch di lavoro (DD-019) non c'è più un ambiente di prova tra il codice e i
giocatori. La suite in `test/` esisteva già ma scriverla era di fatto facoltativo, e i difetti
trovati dai test sono arrivati a posteriori (la sessione Scout Live che non scadeva mai, le
serie di presenze ferme a zero per settimane).
**Decisione**
Chi aggiunge o modifica una funzione scrive o aggiorna il test nello stesso lavoro, e i test
devono essere verdi prima di consegnare. Non si commenta un test che fallisce né si indebolisce
un'asserzione per farla passare: se il comportamento voluto è cambiato, si aggiorna il test
dicendo perché.
**Alternative scartate**
- Test solo sui moduli critici → il confine «critico» si sposta a ogni fretta.
- Introdurre un framework di test → la suite bun con `node:assert` funziona e non aggiunge
dipendenze (vedi [test/README.md](../test/README.md)).
**Conseguenze**
- La logica di dominio va tenuta separabile dagli hook (`*-core.ts`), altrimenti non è
testabile in `test/unit/` senza rete.
- Le modifiche costano un po' di più; le regressioni in produzione costano di più.
**Riesame**
Se comparisse un ambiente di staging stabile che rende superflua parte della copertura.
docs/ROADMAP.md
+2 -2
View File
@@ -19,8 +19,8 @@ sta facendo adesso.
## Versione 1.1 ## Versione 1.1
Le voci spuntate sono implementate su `develop` e non ancora attive in produzione: lo stato Le voci spuntate sono in produzione su `main`. I passaggi di attivazione ancora aperti (per
di attivazione sta in [PROJECT_STATE.md](../PROJECT_STATE.md). esempio il collegamento dei singoli account) stanno in [PROJECT_STATE.md](../PROJECT_STATE.md).
- [x] Certificati medici — caricamento, scadenza, stato e download; lo storico dei - [x] Certificati medici — caricamento, scadenza, stato e download; lo storico dei
certificati resta un'estensione futura certificati resta un'estensione futura
docs/TODO.md
+8 -4
View File
@@ -6,8 +6,8 @@ Solo il lavoro in corso o imminente. L'elenco completo delle funzionalità previ
## In corso ## In corso
- Documentazione tecnica del progetto. - Documentazione tecnica del progetto.
- Autenticazione Google e dashboard amministratore: il codice è completo su `develop` e il - Autenticazione Google e dashboard amministratore: il codice è in produzione su `main` e il
login è ora l'unica via d'accesso. La migration M4, che chiude gli accessi `anon` alle login è l'unica via d'accesso. La migration M4, che chiude gli accessi `anon` alle
tabelle v1.0, è stata applicata in produzione (03/09/2026). Resta il collegamento dei tabelle v1.0, è stata applicata in produzione (03/09/2026). Resta il collegamento dei
singoli account: ogni giocatore si aggancia al proprio profilo al primo login (DD-018), un singoli account: ogni giocatore si aggancia al proprio profilo al primo login (DD-018), un
processo continuo — vale anche per chi viene aggiunto a stagione in corso da `/admin`. processo continuo — vale anche per chi viene aggiunto a stagione in corso da `/admin`.
@@ -15,8 +15,12 @@ Solo il lavoro in corso o imminente. L'elenco completo delle funzionalità previ
## Prossimo ## Prossimo
- Gestione tesseramenti CSI (roadmap v1.1): la raccolta dati e l'export CSV ci sono, manca - Niente di assegnato. Le voci ancora aperte in [ROADMAP.md](ROADMAP.md) sono «Calendario
il tracciamento di chi è già tesserato (numero e data di tessera). ufficiale» (v2.0, i dati delle gare future arrivano già dal feed CSI) e la v1.2.
La gestione tesseramenti CSI della v1.1 è completa: raccolta dati, export CSV e tracciamento
di chi è già tesserato (numero e data di tessera, migration `m8_tesseramento_csi`, registrabili
da `/admin`).
Il profilo giocatore lato giocatore e i certificati medici sono fatti: `ProfiloAmministrativo` Il profilo giocatore lato giocatore e i certificati medici sono fatti: `ProfiloAmministrativo`
in `src/routes/profilo.tsx` carica documento, certificato e foto con le date di scadenza, e in `src/routes/profilo.tsx` carica documento, certificato e foto con le date di scadenza, e
docs/modules/badge.md
+7 -5
View File
@@ -56,9 +56,11 @@ badge assegnati per voto dai compagni.
## Limiti noti ## Limiti noti
- **Dipendenza dal modulo [Serie](serie-presenze.md)**, che oggi è inerte con dati reali: i - **Dipendenza dal modulo [Serie](serie-presenze.md)**: i badge "Sempre in palestra",
badge "Sempre in palestra", "Risposta lampo" e il segreto "Mai un forfait" non possono "Risposta lampo" e il segreto "Mai un forfait" si muovono solo se cambiano le serie. Le
sbloccarsi finché le serie non vengono calcolate davvero. serie sono calcolate sui dati reali dalla migration `m9` in avanti, ma "Risposta lampo" e
"Mai un forfait" dipendono da `serieConferme`, e `risposto_il` non è ricostruibile per le
risposte precedenti a `m9`: su quelle righe la serie è un'approssimazione.
- Nessuno storico dei badge sbloccati: se cambiano le soglie o i dati sorgente, un badge già - Nessuno storico dei badge sbloccati: se cambiano le soglie o i dati sorgente, un badge già
"ottenuto" può sparire o apparire retroattivamente. "ottenuto" può sparire o apparire retroattivamente.
- RLS permissiva su `badge_social_voti` (stesso schema di `mvp_voti`): nessun controllo - RLS permissiva su `badge_social_voti` (stesso schema di `mvp_voti`): nessun controllo
@@ -71,5 +73,5 @@ badge assegnati per voto dai compagni.
## Evoluzioni possibili ## Evoluzioni possibili
- Sincronizzare lo stato "visto" su Supabase invece che solo in localStorage. - Sincronizzare lo stato "visto" su Supabase invece che solo in localStorage.
- Una volta risolta la dipendenza dal modulo Serie, verificare che i badge collegati si - Verificare sui dati di stagione che i tre badge legati alle serie si sblocchino davvero,
sblocchino correttamente. ora che le serie sono calcolate.
docs/modules/collegamento-csi.md
+1 -1
View File
@@ -61,7 +61,7 @@ useCsi() → src/lib/csi.ts (React Query, staleTime 6h)
- **`src/routes/api/public/csi.ts`** — unica route che contatta il CSI. Cache in memoria di - **`src/routes/api/public/csi.ts`** — unica route che contatta il CSI. Cache in memoria di
6 ore; in caso di errore restituisce l'ultimo dato buono (`503` solo se non ne esiste uno). 6 ore; in caso di errore restituisce l'ultimo dato buono (`503` solo se non ne esiste uno).
- **`src/lib/csi.ts`** — hook client, una lettura per sessione. - **`src/lib/csi.ts`** — hook client, una lettura per sessione.
- **`src/lib/csi-core.test.ts`** — check del parsing: `bun src/lib/csi-core.test.ts`. - **`test/unit/csi-core.test.ts`** — check del parsing: `bun test/unit/csi-core.test.ts`.
Con `CSI_LIVE=1` verifica anche gli endpoint reali. Con `CSI_LIVE=1` verifica anche gli endpoint reali.
### Regole rispettate ### Regole rispettate
docs/modules/obiettivi-squadra.md
+4 -3
View File
@@ -42,8 +42,10 @@ smart (`notifiche-smart.ts`).
## Limiti noti ## Limiti noti
- **"Continuità di squadra" dipende da `serieAllenamenti`, che oggi è sempre 0** (vedi - "Continuità di squadra" dipende da `serieAllenamenti` (vedi
[Serie di presenze](serie-presenze.md)): resta strutturalmente a 0/12 con i dati reali. [Serie di presenze](serie-presenze.md)), calcolato sui dati reali: un evento passato senza
risposta vale come assenza e azzera la serie, quindi l'obiettivo misura anche quanto la
squadra risponde alle convocazioni, non solo la presenza.
- **Il mese di riferimento è una costante fissa nel codice** (agosto 2026): gli obiettivi - **Il mese di riferimento è una costante fissa nel codice** (agosto 2026): gli obiettivi
legati al mese corrente vanno aggiornati manualmente a ogni cambio di mese o stagione, oggi legati al mese corrente vanno aggiornati manualmente a ogni cambio di mese o stagione, oggi
sono "congelati" su un mese già passato. sono "congelati" su un mese già passato.
@@ -57,4 +59,3 @@ smart (`notifiche-smart.ts`).
## Evoluzioni possibili ## Evoluzioni possibili
- Calcolare il mese di riferimento dinamicamente invece di una costante hardcoded. - Calcolare il mese di riferimento dinamicamente invece di una costante hardcoded.
- Risolvere la dipendenza dal modulo Serie.
docs/modules/profilo-giocatore.md
+5 -1
View File
@@ -69,7 +69,7 @@ Quando tutte le sezioni sono complete il widget scompare automaticamente.
## Profilo ## Profilo
Il profilo viene suddiviso in cinque aree. Il profilo viene suddiviso in sette aree.
### Dati Giocatore ### Dati Giocatore
@@ -146,6 +146,10 @@ Contiene.
- Logout - Logout
- Preferenze notifiche - Preferenze notifiche
- Impostazioni applicazione - Impostazioni applicazione
- Segnala un bug e Suggerisci una nuova funzionalità: due link che aprono una issue GitHub
già impostata sul template giusto (`.github/ISSUE_TEMPLATE/bug_report.yml` e
`feature_request.yml`). Nessun dato passa dall'app — la segnalazione vive interamente su
GitHub, così non servono né una tabella né una schermata di gestione.
## Dashboard amministratore ## Dashboard amministratore