diff --git a/AGENTS.md b/AGENTS.md index 9d95662..bc4d845 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 - -↓ - -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; +## L'AI non deve +- introdurre librerie senza necessità, né aggirare `minimumReleaseAge`; +- modificare il database o il comportamento dell'app senza richiesta esplicita; - eliminare funzionalità esistenti; - -- modificare il comportamento dell'app senza richiesta esplicita; - -- sovrascrivere modifiche di altri collaboratori senza comprenderle; - +- sovrascrivere modifiche di altri collaboratori senza averne compreso lo scopo; - riscrivere migration già applicate; +- committare, pushare o cambiare branch di propria iniziativa. -- lavorare direttamente su `main`; - -- assumere che il repository sia invariato rispetto all'ultima sessione. - -L'AI deve: - -- spiegare le modifiche importanti; - -- mantenere compatibilità con il codice esistente; +## L'AI deve +- 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à; +- tenere aggiornata la documentazione quando serve. -- riutilizzare i componenti esistenti; +## Filosofia -- controllare il lavoro recente degli altri collaboratori; - -- mantenere aggiornata la documentazione quando necessario; - -- 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. +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 +o aumenta la complessità futura? Se almeno una risposta è negativa, rivaluta la soluzione. diff --git a/CLAUDE.md b/CLAUDE.md index 1395b1b..bdd4a94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,26 +1,9 @@ # CLAUDE.md -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 -in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). +Le regole di progetto stanno in @AGENTS.md: valgono integralmente e non sono ripetute qui — +compresi i comandi (`npm run dev/lint/test`, supabase) e la checklist «Fine lavoro» da eseguire +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 -anche Codex e Cursor; scritta qui la vedrebbe solo Claude Code. Vale per qualsiasi aggiunta o -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`. +anche Codex e Cursor; scritta qui la vedrebbe solo Claude Code. diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 1432bb3..c80063a 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -1,29 +1,28 @@ # Project State -Ultimo aggiornamento: 03/09/2026 +Ultimo aggiornamento: 04/09/2026 ## Stato generale Fase corrente: -Backend migrato al nuovo Supabase proprietario. M1 completata. M2 scritta e da applicare. -Autenticazione Google, dashboard amministratore e Profilo Giocatore (lato giocatore e lato -admin) implementati su `develop`, da attivare in produzione seguendo i passaggi più sotto. +Backend migrato al nuovo Supabase proprietario. Autenticazione Google, dashboard +amministratore e Profilo Giocatore (lato giocatore e lato admin) sono in produzione su `main`. 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 -- GitHub configurato con branch `main` e `develop` -- Cursor come ambiente di sviluppo +- Si lavora direttamente su `main` (DD-019): `develop` esiste ma è fermo indietro, quindi la + 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) - 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 -- 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 -- 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`) 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 @@ -65,13 +64,14 @@ sincronizzano tra dispositivi tramite Supabase. - Pagelle - MVP - 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 -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 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"} ``` -e **nessuno entra nell'app**, né in dev né sulla preview di `develop`. Il passo 1 qui sotto -va fatto prima di mandare questa versione in produzione. +e **nessuno entra nell'app**. Vale ancora per chi allestisce un ambiente nuovo (per esempio +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 1-3; il passaggio 4 è un processo continuo (7 dei 16 giocatori attivi hanno già -fatto il primo accesso); il passaggio 5 (M4) è stato applicato.** +Passaggi in ordine, nessuno dei quali è reversibile a metà. **Stato al 04/09/2026: fatti i +passaggi 1, 2, 3 e 5 (M4 applicata); il passaggio 4 è un processo continuo (7 dei 16 giocatori +attivi hanno già fatto il primo accesso).** 1. **Provider Google in Supabase** — Google Cloud Console: consent screen _External_ (scope `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 -Gestione tesseramenti CSI: la raccolta dati e l'export CSV sono pronti, manca il -tracciamento di chi è già tesserato (numero e data di tessera). +Niente di assegnato: la v1.1 è completa, tesseramento CSI incluso (numero e data di tessera +registrabili da `/admin`, migration `m8_tesseramento_csi`). Le voci ancora aperte stanno in +[docs/ROADMAP.md](docs/ROADMAP.md). --- diff --git a/README.md b/README.md index 7fe66f9..3b76514 100644 --- a/README.md +++ b/README.md @@ -14,58 +14,37 @@ CrAPP è una Progressive Web App sviluppata per digitalizzare completamente la g - Gestione amministrativa - AI per la pianificazione degli allenamenti (in sviluppo) ---- - ## Stack tecnologico -- React 19 -- TypeScript -- TanStack Start -- Vite -- Tailwind CSS -- Supabase -- GitHub -- Vercel - ---- - -## Ambienti - -- `main` → Produzione -- `develop` → Sviluppo - ---- +React 19, TypeScript, TanStack Start (SSR), Vite 8, Tailwind CSS 4, Radix UI / shadcn, +Supabase (PostgreSQL, Auth, Storage), Vercel, GitHub. Dettagli in +[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## Avvio locale -```bash -npm install -npm run dev -``` - -L'app sarà disponibile su: - -``` -http://localhost:8080 -``` - ---- - -## Build +Le dipendenze si installano con **bun** (`bun.lock`): ```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 -Il deploy è automatico tramite Vercel ad ogni push sul branch `main`. - -Le modifiche sviluppate nel branch `develop` vengono pubblicate automaticamente come Preview Deployment. - ---- +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 +committare lo decide chi sviluppa (DD-019). ## Variabili d'ambiente @@ -76,20 +55,7 @@ Il progetto richiede le seguenti variabili: - `VITE_SUPABASE_URL` - `VITE_SUPABASE_PUBLISHABLE_KEY` ---- +## Documentazione -## Repository - -Il codice sorgente è gestito tramite GitHub. - -Flusso di sviluppo: - -``` -develop - ↓ -Test - ↓ -Merge su main - ↓ -Deploy automatico Vercel -``` +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). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 385e6d9..47d5f15 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -116,9 +116,10 @@ dove provare le migration distruttive senza toccare i dati veri. ## Branch e flusso di sviluppo -- `main` → produzione, deploy automatico su Vercel. -- `develop` → sviluppo; si lavora qui, mai direttamente su `main` (DD-003). +- `main` → produzione, deploy automatico su Vercel. È anche il branch di lavoro corrente. +- `develop` → preview Vercel; oggi indietro rispetto a `main`, non rappresenta lo stato attuale. +- `feature/…`, `fix/…`, `refactor/…` → lavori rischiosi o paralleli. -``` -develop → test → merge su main → deploy automatico su Vercel -``` +Su quale branch va un commit lo decide l'utente (DD-019): un assistente AI può consigliare un +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)). diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 6463cf8..416f238 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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%, 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) - Login con Google tramite Supabase Auth (DD-011). Al primo accesso l'account si collega a diff --git a/docs/DESIGN_DECISIONS.md b/docs/DESIGN_DECISIONS.md index 4844e5b..60d6909 100644 --- a/docs/DESIGN_DECISIONS.md +++ b/docs/DESIGN_DECISIONS.md @@ -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-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-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 | @@ -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-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-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** @@ -42,6 +43,12 @@ Serve a rispondere a domande del tipo: | ----------------------------------------------------------------- | ---------------------- | | [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 @@ -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 **Data:** agosto 2026 -**Stato:** Accettata +**Stato:** Sostituita da [DD-019](#dd-019--il-branch-dei-commit-lo-decide-lutente) (settembre 2026) **Contesto** 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. **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. --- + +### 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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 216bd4d..113b080 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -19,8 +19,8 @@ sta facendo adesso. ## Versione 1.1 -Le voci spuntate sono implementate su `develop` e non ancora attive in produzione: lo stato -di attivazione sta in [PROJECT_STATE.md](../PROJECT_STATE.md). +Le voci spuntate sono in produzione su `main`. I passaggi di attivazione ancora aperti (per +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 certificati resta un'estensione futura diff --git a/docs/TODO.md b/docs/TODO.md index 07c17b7..c521fd7 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -6,8 +6,8 @@ Solo il lavoro in corso o imminente. L'elenco completo delle funzionalità previ ## In corso - Documentazione tecnica del progetto. -- Autenticazione Google e dashboard amministratore: il codice è completo su `develop` e il - login è ora l'unica via d'accesso. La migration M4, che chiude gli accessi `anon` alle +- Autenticazione Google e dashboard amministratore: il codice è in produzione su `main` e il + 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 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`. @@ -15,8 +15,12 @@ Solo il lavoro in corso o imminente. L'elenco completo delle funzionalità previ ## Prossimo -- Gestione tesseramenti CSI (roadmap v1.1): la raccolta dati e l'export CSV ci sono, manca - il tracciamento di chi è già tesserato (numero e data di tessera). +- Niente di assegnato. Le voci ancora aperte in [ROADMAP.md](ROADMAP.md) sono «Calendario + 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` in `src/routes/profilo.tsx` carica documento, certificato e foto con le date di scadenza, e diff --git a/docs/modules/badge.md b/docs/modules/badge.md index ea6542a..c8e5b14 100644 --- a/docs/modules/badge.md +++ b/docs/modules/badge.md @@ -56,9 +56,11 @@ badge assegnati per voto dai compagni. ## Limiti noti -- **Dipendenza dal modulo [Serie](serie-presenze.md)**, che oggi è inerte con dati reali: i - badge "Sempre in palestra", "Risposta lampo" e il segreto "Mai un forfait" non possono - sbloccarsi finché le serie non vengono calcolate davvero. +- **Dipendenza dal modulo [Serie](serie-presenze.md)**: i badge "Sempre in palestra", + "Risposta lampo" e il segreto "Mai un forfait" si muovono solo se cambiano le serie. Le + 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à "ottenuto" può sparire o apparire retroattivamente. - 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 - 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 - sblocchino correttamente. +- Verificare sui dati di stagione che i tre badge legati alle serie si sblocchino davvero, + ora che le serie sono calcolate. diff --git a/docs/modules/collegamento-csi.md b/docs/modules/collegamento-csi.md index 88b861f..58709ef 100644 --- a/docs/modules/collegamento-csi.md +++ b/docs/modules/collegamento-csi.md @@ -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 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-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. ### Regole rispettate diff --git a/docs/modules/obiettivi-squadra.md b/docs/modules/obiettivi-squadra.md index 0d36f2b..10d4e31 100644 --- a/docs/modules/obiettivi-squadra.md +++ b/docs/modules/obiettivi-squadra.md @@ -42,8 +42,10 @@ smart (`notifiche-smart.ts`). ## Limiti noti -- **"Continuità di squadra" dipende da `serieAllenamenti`, che oggi è sempre 0** (vedi - [Serie di presenze](serie-presenze.md)): resta strutturalmente a 0/12 con i dati reali. +- "Continuità di squadra" dipende da `serieAllenamenti` (vedi + [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 legati al mese corrente vanno aggiornati manualmente a ogni cambio di mese o stagione, oggi sono "congelati" su un mese già passato. @@ -57,4 +59,3 @@ smart (`notifiche-smart.ts`). ## Evoluzioni possibili - Calcolare il mese di riferimento dinamicamente invece di una costante hardcoded. -- Risolvere la dipendenza dal modulo Serie. diff --git a/docs/modules/profilo-giocatore.md b/docs/modules/profilo-giocatore.md index 0f3df10..7f6893b 100644 --- a/docs/modules/profilo-giocatore.md +++ b/docs/modules/profilo-giocatore.md @@ -69,7 +69,7 @@ Quando tutte le sezioni sono complete il widget scompare automaticamente. ## Profilo -Il profilo viene suddiviso in cinque aree. +Il profilo viene suddiviso in sette aree. ### Dati Giocatore @@ -146,6 +146,10 @@ Contiene. - Logout - Preferenze notifiche - 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