diff --git a/.cursor/architecture-summary.md b/.cursor/architecture-summary.md deleted file mode 100644 index e37235c..0000000 --- a/.cursor/architecture-summary.md +++ /dev/null @@ -1,37 +0,0 @@ -# Architecture Summary - -Frontend - -- React -- TanStack Start -- Tailwind -- TypeScript - -Backend - -- Supabase - -Hosting - -- Vercel - -Repository - -- GitHub - -Branch - -- main -- develop - -Documentazione - -- docs/ - -Database - -- Supabase - -Storage - -- Supabase Storage \ No newline at end of file diff --git a/.cursor/coding-style.md b/.cursor/coding-style.md deleted file mode 100644 index a695ac0..0000000 --- a/.cursor/coding-style.md +++ /dev/null @@ -1,12 +0,0 @@ -# Coding Style - -Preferenze del progetto. - -- Utilizzare TypeScript. -- Preferire funzioni piccole. -- Evitare duplicazione di codice. -- Utilizzare componenti React riutilizzabili. -- Commentare solamente il codice realmente complesso. -- Preferire nomi descrittivi. -- Non introdurre librerie senza reale necessità. -- Mantenere la struttura esistente del progetto. \ No newline at end of file diff --git a/.cursor/crapp-context.md b/.cursor/crapp-context.md deleted file mode 100644 index d03bd8a..0000000 --- a/.cursor/crapp-context.md +++ /dev/null @@ -1,22 +0,0 @@ -# CrAPP Context - -CrAPP è una Progressive Web App dedicata alla gestione di una squadra di pallavolo amatoriale. - -L'obiettivo principale NON è solamente registrare dati. - -L'obiettivo è ridurre il lavoro amministrativo degli amministratori e aumentare il coinvolgimento dei giocatori attraverso gamification, statistiche e strumenti intelligenti. - -Quando implementi nuove funzionalità: - -- privilegia semplicità -- mantieni la coerenza dell'interfaccia -- evita duplicazioni -- leggi sempre la documentazione presente in `docs/` - -Prima di scrivere codice consulta: - -- README -- ROADMAP -- DATABASE -- ARCHITECTURE -- il modulo interessato in `docs/modules` \ No newline at end of file diff --git a/.cursor/development-workflow.md b/.cursor/development-workflow.md deleted file mode 100644 index fe70802..0000000 --- a/.cursor/development-workflow.md +++ /dev/null @@ -1,11 +0,0 @@ -# Development Workflow - -Ogni nuova funzionalità segue questo flusso. - -1. Discussione funzionale. -2. Documento in `docs/modules`. -3. Progettazione database. -4. Implementazione su branch `develop`. -5. Test. -6. Merge su `main`. -7. Deploy automatico tramite Vercel. \ No newline at end of file diff --git a/.cursor/project-rules.md b/.cursor/project-rules.md deleted file mode 100644 index cbd9c92..0000000 --- a/.cursor/project-rules.md +++ /dev/null @@ -1,29 +0,0 @@ -# Project Rules - -Queste regole devono essere rispettate per qualsiasi modifica al progetto. - -## Regole generali - -- Non modificare il branch `main` direttamente. -- Tutte le nuove funzionalità vengono sviluppate su `develop`. -- Prima di implementare una funzionalità leggere sempre la documentazione presente in `docs/`. -- Non creare codice duplicato. -- Riutilizzare sempre componenti già esistenti quando possibile. -- Mantenere uno stile coerente con il progetto. - -## Database - -- Non modificare il database senza creare una nuova migration Supabase. -- Non eliminare tabelle esistenti senza esplicita richiesta. -- Preferire nuove tabelle rispetto all'aggiunta di molte colonne quando il modulo è indipendente. - -## Componenti - -- Preferire componenti piccoli e riutilizzabili. -- Evitare componenti con responsabilità multiple. - -## Documentazione - -Ogni nuova funzionalità deve essere documentata prima dell'implementazione. - -La documentazione tecnica si trova nella cartella `docs/`. \ No newline at end of file diff --git a/.cursor/rules/crapp.mdc b/.cursor/rules/crapp.mdc new file mode 100644 index 0000000..32b9f25 --- /dev/null +++ b/.cursor/rules/crapp.mdc @@ -0,0 +1,16 @@ +--- +description: Regole di progetto CrAPP +alwaysApply: true +--- + +Prima di qualsiasi modifica leggi @AGENTS.md e seguine le regole: sono vincolanti e valgono +per intero. + +- Non implementare funzionalità non documentate in `docs/`. +- Lavora su `develop`, mai direttamente su `main`. +- Codice, commenti e documentazione in italiano. + +Non aggiungere regole in questo file: una regola nuova va in `AGENTS.md`, che leggono anche +Claude Code e Codex. Vale per qualsiasi aggiunta o modifica — regola, funzionalità, decisione, +schema database: prima di considerare finito il lavoro esegui la checklist «Fine lavoro» di +`AGENTS.md`. diff --git a/AGENTS.md b/AGENTS.md index bdcdc8a..9a774ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,231 +1,127 @@ -# AGENTS.md - -# CrAPP - AI Development Guide - -Questo documento definisce le regole che qualsiasi assistente AI (Cursor, Claude Code, Codex, ChatGPT o altri) deve seguire quando lavora su questo progetto. - ---- - -# Obiettivo del progetto - -CrAPP è una Progressive Web App sviluppata per digitalizzare completamente la gestione di una squadra di pallavolo. - -L'obiettivo principale è: - -- ridurre il lavoro amministrativo degli amministratori; -- aumentare il coinvolgimento dei giocatori; -- centralizzare tutte le informazioni della squadra; -- utilizzare l'intelligenza artificiale solo quando porta un reale beneficio. - ---- - -# Prima di modificare il codice - -Prima di implementare qualsiasi modifica leggere sempre: - -1. docs/README.md -2. docs/VISION.md -3. docs/ROADMAP.md -4. docs/ARCHITECTURE.md -5. docs/DATABASE.md -6. docs/DESIGN_DECISIONS.md -7. docs/TODO.md -8. il documento interessato in docs/modules/ - -Non implementare funzionalità non documentate. - ---- - -# Workflow di sviluppo - -Ogni nuova funzionalità segue sempre questo processo. - -Idea - -↓ - -Progettazione - -↓ - -Documentazione - -↓ - -Database - -↓ - -Implementazione - -↓ - -Test - -↓ - -Merge su main - -↓ - -Deploy automatico - ---- - -# Git - -Il repository utilizza due branch principali. - -## main - -Versione stabile. - -Qualsiasi modifica deve mantenere l'app perfettamente funzionante. - -## develop - -Branch utilizzato per lo sviluppo delle nuove funzionalità. - -Tutte le nuove implementazioni devono essere realizzate qui. - ---- - -# 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. - -Fare sempre riferimento a: - -docs/DATABASE.md - ---- - -# Componenti - -Preferire: - -- componenti piccoli; -- componenti riutilizzabili; -- responsabilità singola; -- codice semplice da mantenere. - -Evitare duplicazioni. - ---- - -# 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 -- CHANGELOG.md -- TODO.md -- DATABASE.md (se il database cambia) -- DESIGN_DECISIONS.md (se si prende una decisione architetturale importante) ---- - -# Struttura della documentazione - -La cartella `docs/` rappresenta la documentazione ufficiale del progetto. - -## Documenti principali - -- README.md → panoramica del progetto -- VISION.md → obiettivi e filosofia -- ROADMAP.md → evoluzione prevista -- ARCHITECTURE.md → architettura tecnica -- DATABASE.md → struttura del database -- DESIGN_DECISIONS.md → registro delle decisioni di progetto -- CHANGELOG.md → cronologia delle modifiche -- TODO.md → attività pianificate - -## 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. ---- - -# Regole - -L'AI non deve: +# AGENTS.md — CrAPP + +Regole che qualsiasi assistente AI (Claude Code, Codex, Cursor, ChatGPT o altri) deve seguire +quando lavora su questo progetto. **È l'unica fonte delle regole**: `CLAUDE.md` e +`.cursor/rules/` rimandano qui, non ripetono nulla. + +> **Qualsiasi cosa venga aggiunta o modificata — una regola, una funzionalità, una decisione, +> una tabella — va registrata nei file di riferimento del progetto prima di considerare il +> lavoro finito**, indipendentemente dall'assistente con cui è stata fatta. Vedi +> [Fine lavoro](#fine-lavoro-cosa-aggiornare-sempre): non è un passaggio opzionale. + +CrAPP è una Progressive Web App per la gestione di una squadra di pallavolo amatoriale (CRAP +Volley). Obiettivi e principi in [docs/VISION.md](docs/VISION.md), architettura in +[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). + +**Codice, commenti, nomi di variabili e documentazione sono in italiano**: mantieni questa +convenzione. + +## Prima di modificare il codice + +Leggere sempre, nell'ordine: + +1. [docs/README.md](docs/README.md) — indice della documentazione +2. [docs/VISION.md](docs/VISION.md) +3. [docs/ROADMAP.md](docs/ROADMAP.md) +4. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) +5. [docs/DATABASE.md](docs/DATABASE.md) +6. [docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md) +7. [docs/TODO.md](docs/TODO.md) +8. il documento del modulo interessato in [docs/modules/](docs/modules/) + +**Non implementare funzionalità non documentate** (DD-002). + +## Workflow + +``` +idea → progettazione → documento in docs/modules/ → database → implementazione su develop +→ test → merge su main → deploy automatico Vercel +``` + +- `main` = produzione, sempre funzionante: **non si modifica direttamente**. Qualsiasi + modifica deve mantenere l'app perfettamente funzionante. +- `develop` = sviluppo e preview; tutte le nuove implementazioni nascono qui. + +## Vincoli tecnici da non violare + +- `src/routeTree.gen.ts` e `src/integrations/supabase/{client.ts,types.ts}` sono **generati**: + non modificarli a mano. +- **Non ri-aggiungere** i plugin Vite (devtools, tanstackStart, viteReact, tailwind, + tsconfig-paths, nitro) già inclusi da `@lovable.dev/vite-tanstack-config` in + `vite.config.ts`: l'app si rompe. +- Nessun accesso al database dai componenti: solo tramite i moduli in `src/lib/`, così il + backend resta sostituibile in un solo punto (DD-013). +- Efficienza cloud: niente polling, cache lunga, e dopo una mutazione `setQueryData` invece di + `invalidateQueries`. Regole complete in [docs/EFFICIENZA_CLOUD.md](docs/EFFICIENZA_CLOUD.md). +- Badge e statistiche si calcolano a runtime, non si persistono (DD-007); la gamification + resta equa tra ruoli (DD-008): niente metriche che favoriscano attaccanti o liberi. +- L'app deve poter girare su Node.js + PostgreSQL standard: niente servizi esclusivi + Lovable/Vercel (DD-001, DD-013, [docs/PORTABILITA.md](docs/PORTABILITA.md)). + +## Database + +- Non eliminare tabelle esistenti. +- Non modificare lo schema senza creare una migration in `supabase/migrations/`. +- Preferire una nuova tabella all'aggiunta di molte colonne, quando il modulo è indipendente. +- Preferire strutture scalabili; evitare duplicazione dei dati. +- Riferimento: [docs/DATABASE.md](docs/DATABASE.md), da aggiornare nella stessa modifica che + cambia lo schema. + +## Codice e componenti + +- TypeScript, funzioni piccole, nomi descrittivi. +- Componenti piccoli, riutilizzabili, a responsabilità singola. +- Nessuna duplicazione: riusare sempre i componenti e i moduli esistenti. +- Commentare solo il codice realmente complesso. +- Nessuna nuova dipendenza senza reale necessità; mantenere la struttura esistente. +- Le dipendenze si installano con **bun**; `bunfig.toml` impone `minimumReleaseAge = 24h` come + guardia supply-chain: aggiungere un pacchetto a `minimumReleaseAgeExcludes` richiede + conferma esplicita dell'utente. + +## Interfaccia + +Stile coerente con l'esistente: semplice, moderna, pulita, veloce, ottimizzata per +smartphone, poche schermate e pochi click (DD-005). Riusare i componenti in +`src/components/crapp/` (`ui-bits.tsx` per `PageHeader`, `Section`, `StatTile`) e le primitive +shadcn in `src/components/ui/`. + +## Fine lavoro: cosa aggiornare sempre + +Il lavoro **non è finito** finché non è registrato dove va. Vale per tutti gli assistenti allo +stesso modo: chi fa la modifica aggiorna i file, chiunque la stia facendo e da qualunque +strumento. Un cambiamento che vive solo nel codice o solo nella chat è un cambiamento perso. + +| Cosa hai aggiunto o cambiato | Dove va registrato | +|---|---| +| Una **regola** per gli assistenti (convenzione, divieto, vincolo di lavoro) | **Questo file, e solo questo.** Mai in `CLAUDE.md` o `.cursor/rules/`: rimandano qui, e una regola scritta lì la vedrebbe un assistente solo | +| Una **funzionalità** | `docs/modules/.md` (**prima** di scrivere il codice), poi `docs/ROADMAP.md` e `docs/CHANGELOG.md` | +| Una **decisione** architetturale o di prodotto | `docs/DESIGN_DECISIONS.md`, formato `DD-XXX` (copiare `docs/_template-dd.md`) e aggiungerla all'indice in cima | +| Una **modifica allo schema** del database | una migration in `supabase/migrations/` **e** `docs/DATABASE.md`, nella stessa modifica | +| Lavoro iniziato, sospeso o concluso | `docs/TODO.md` e `PROJECT_STATE.md` | +| Un **comando** o uno script nuovo | `docs/ARCHITECTURE.md` (sezione Comandi) e `CLAUDE.md` | + +Quale informazione vive in quale file — e perché non va duplicata altrove — è spiegato in +[docs/README.md](docs/README.md). + +## Cosa l'AI non deve fare - introdurre librerie senza necessità; - modificare il database senza motivazione; - eliminare funzionalità esistenti; - modificare il comportamento dell'app senza richiesta esplicita. -L'AI deve: +## Cosa l'AI deve fare - spiegare le modifiche importanti; - mantenere compatibilità con il codice esistente; - privilegiare la semplicità; - riutilizzare i componenti esistenti. ---- +## Filosofia -# Filosofia del progetto +Prima di scrivere codice, chiedersi sempre: -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? - -Se almeno una risposta è negativa, rivalutare la soluzione proposta. \ No newline at end of file +- questa modifica rende CrAPP più semplice? +- riduce il lavoro degli amministratori? +- migliora l'esperienza dei giocatori? +- è coerente con la documentazione? diff --git a/CLAUDE.md b/CLAUDE.md index 5ba70f4..4157f10 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,54 +1,21 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +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). -CrAPP — PWA per la gestione di una squadra di pallavolo amatoriale (CRAP Volley). Codice, commenti, nomi di variabili e documentazione sono **in italiano**: mantieni questa convenzione. - -## Regole di progetto - -[AGENTS.md](AGENTS.md) contiene le regole vincolanti per gli assistenti AI. In sintesi: - -- **Document-first**: nessuna funzionalità va implementata se non è già documentata in [docs/](docs/) (in particolare `docs/modules/.md`). Leggi il documento del modulo prima di scrivere codice. -- Lavora sul branch `develop`, mai direttamente su `main` (`main` = produzione, deploy automatico Vercel). -- Dopo una modifica aggiorna, quando pertinente: `docs/ROADMAP.md`, `docs/CHANGELOG.md`, `docs/TODO.md`, `docs/DATABASE.md` (se cambia lo schema), `docs/DESIGN_DECISIONS.md` (decisioni architetturali, formato DD-XXX con indice in fondo al file), `PROJECT_STATE.md`. -- Nessuna nuova dipendenza senza reale necessità; riusa i componenti esistenti. -- Il DB si modifica solo con una nuova migration in `supabase/migrations/`; non eliminare tabelle. -- [docs/PORTABILITA.md](docs/PORTABILITA.md) / DD-001 / DD-013: l'app deve poter girare su Node.js + PostgreSQL standard. Evita servizi esclusivi Lovable/Vercel. +**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 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 ``` -Non esiste una suite di test automatici: la verifica è manuale via `npm run dev` + `npm run lint`. - -Le dipendenze sono installate con **bun** (`bun.lock`, `bunfig.toml`). `bunfig.toml` impone `minimumReleaseAge = 24h` come guardia supply-chain: aggiungere un pacchetto a `minimumReleaseAgeExcludes` richiede conferma esplicita dell'utente. - -## Architettura - -**Stack**: React 19 + TanStack Start (SSR) + Vite 8 + Tailwind 4 + Radix/shadcn, Supabase come backend, Vercel per l'hosting. - -- **Routing**: file-based in [src/routes/](src/routes/); `src/routeTree.gen.ts` è generato — non modificarlo a mano. -- **Configurazione Vite**: [vite.config.ts](vite.config.ts) usa `@lovable.dev/vite-tanstack-config`, che include già devtools, tanstackStart, viteReact, tailwind, tsconfig-paths, nitro e l'alias `@` → `src/`. **Non ri-aggiungere questi plugin** o l'app si rompe. -- **Entry point server**: [src/server.ts](src/server.ts) avvolge l'entry di TanStack Start per intercettare gli errori SSR che h3 trasforma silenziosamente in un 500 JSON, e renderizza `renderErrorPage()`. [src/start.ts](src/start.ts) registra i middleware globali (error handler, CSRF sui server functions, `attachSupabaseAuth`). -- **Supabase**: `src/integrations/supabase/client.ts` (browser/SSR, chiave publishable — file generato) e `client.server.ts` (`supabaseAdmin`, solo server). `types.ts` è generato dallo schema. - -**Livello dati** — tutta la logica di dominio sta in [src/lib/](src/lib/), un file per modulo (`presenze`, `eventi`, `pagelle`, `mvp-voti`, `palloni`, `cacche`, `badges`, `scout-*`, `infortuni`, …). Il pattern ricorrente: - -- ogni modulo esporta hook TanStack Query (`useX`) con `staleTime` lungo e mutation che invalidano la propria chiave; -- le funzioni pure di calcolo sono separate dagli hook (es. `palloni-core.ts` vs `palloni.ts`, `mediePagelle()` vs `usePagelle()`); -- [src/lib/rosa.ts](src/lib/rosa.ts) è l'aggregatore: compone tutti gli hook e restituisce la rosa completa con le statistiche derivate, **senza query aggiuntive** rispetto a quelle già in cache. Le route consumano `useRosa()`, non i singoli moduli. - -Vincoli di efficienza cloud (vedi `mem/`): niente polling, cache lunga, aggregati precalcolati. - -**Badge e statistiche** sono calcolati a runtime dai dati, non persistiti (DD-007). La gamification deve restare equa tra ruoli (DD-008): niente metriche che favoriscano attaccanti o liberi. - -La rosa è tuttora **hardcoded** in `src/lib/crapp-data.ts` (`rosaCSI`); la migrazione verso la tabella `giocatori_squadra` (migration `20260828170400_m1_giocatori_squadra.sql`) è in corso — vedi DD-015 e DD-016. - -## UI - -Componenti condivisi in [src/components/crapp/](src/components/crapp/) (`ui-bits.tsx` per `PageHeader`, `Section`, `StatTile`), primitive shadcn in `src/components/ui/`, animazioni in `src/components/motion/`. Mobile-first (DD-005): poche schermate, pochi click. +Verifica minima prima di consegnare: `npm run lint` + `npm run test`. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5335322..f8bcc39 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,71 +1,105 @@ # Architettura del progetto -## Frontend +Come è fatta CrAPP: stack, organizzazione del codice, flusso di sviluppo. È il documento di +riferimento tecnico — `CLAUDE.md` non ripete questi contenuti, li richiama. -- React 19 -- TypeScript -- TanStack Start -- Vite -- Tailwind CSS -- Radix UI +## Stack ---- +| Livello | Tecnologie | +|---|---| +| Frontend | React 19, TypeScript, TanStack Start (SSR), Vite 8, Tailwind CSS 4, Radix UI / shadcn | +| Backend | Supabase (PostgreSQL, Auth, Storage) | +| Hosting | Vercel | +| Versionamento | Git, GitHub | -## Backend - -- Supabase - ---- - -## Hosting - -- Vercel - ---- - -## Versionamento - -- Git -- GitHub - ---- - -## Branch - -- main → Produzione -- develop → Sviluppo - ---- +Le dipendenze sono installate con **bun** (`bun.lock`, `bunfig.toml`). `bunfig.toml` impone +`minimumReleaseAge = 24h` come guardia supply-chain: aggiungere un pacchetto a +`minimumReleaseAgeExcludes` richiede conferma esplicita. ## Struttura del progetto +``` src/ + components/ componenti condivisi (crapp/, ui/, motion/) + routes/ routing file-based + lib/ logica di dominio, un file per modulo + integrations/ client Supabase e integrazioni esterne + hooks/ + assets/ +supabase/ migration SQL +test/ suite di test (unit, integration, end-to-end) +docs/ documentazione ufficiale +``` -- components/ -- routes/ -- lib/ -- integrations/ -- hooks/ -- assets/ +## Punti fermi -supabase/ +- **Routing**: file-based in `src/routes/`. `src/routeTree.gen.ts` è **generato**, non si + modifica a mano. +- **Configurazione Vite**: `vite.config.ts` usa `@lovable.dev/vite-tanstack-config`, che + include già devtools, tanstackStart, viteReact, tailwind, tsconfig-paths, nitro e l'alias + `@` → `src/`. **Non ri-aggiungere questi plugin**: l'app si rompe. +- **Entry point server**: `src/server.ts` avvolge l'entry di TanStack Start per intercettare + gli errori SSR che h3 trasformerebbe in un 500 JSON silenzioso, e renderizza + `renderErrorPage()`. `src/start.ts` registra i middleware globali (error handler, CSRF sui + server functions, `attachSupabaseAuth`). +- **Supabase**: `src/integrations/supabase/client.ts` (browser/SSR, chiave publishable — file + generato) e `client.server.ts` (`supabaseAdmin`, solo server). `types.ts` è generato dallo + schema. -docs/ +## Livello dati ---- +Tutta la logica di dominio sta in `src/lib/`, un file per modulo (`presenze`, `eventi`, +`pagelle`, `mvp-voti`, `palloni`, `cacche`, `badges`, `scout-*`, `infortuni`, …). Il pattern +ricorrente: -## Flusso di sviluppo +- ogni modulo esporta hook TanStack Query (`useX`); i default globali stanno in + `src/router.tsx` (`staleTime` 5 min, `gcTime` 30 min, `refetchOnWindowFocus/Mount/Reconnect` + disattivati, `retry: 1`); +- dopo una mutazione la cache si aggiorna con `setQueryData`, **non** con + `invalidateQueries`: invalidare provoca una rilettura e costa una query in più (unica + eccezione oggi: `scout-live.ts`); +- le funzioni pure di calcolo sono separate dagli hook (es. `palloni-core.ts` vs + `palloni.ts`, `mediePagelle()` vs `usePagelle()`); +- `src/lib/rosa.ts` è l'aggregatore: compone tutti gli hook e restituisce la rosa completa + con le statistiche derivate, **senza query aggiuntive** rispetto a quelle già in cache. Le + route consumano `useRosa()`, non i singoli moduli. -develop +Nessun accesso al database dai componenti: solo attraverso i moduli in `src/lib/`, così il +backend resta sostituibile in un solo punto (DD-013, [PORTABILITA.md](PORTABILITA.md)). -↓ +Vincoli di efficienza cloud — niente polling, cache lunga, `setQueryData` invece di +`invalidateQueries` — in [EFFICIENZA_CLOUD.md](EFFICIENZA_CLOUD.md). -Test +Badge e statistiche sono calcolati a runtime dai dati, non persistiti (DD-007). La +gamification deve restare equa tra ruoli (DD-008). -↓ +La rosa è tuttora **hardcoded** in `src/lib/crapp-data.ts` (`rosaCSI`); la migrazione verso +la tabella `giocatori_squadra` è in corso — vedi DD-015 e DD-016. -Merge su main +## UI -↓ +Componenti condivisi in `src/components/crapp/` (`ui-bits.tsx` per `PageHeader`, `Section`, +`StatTile`), primitive shadcn in `src/components/ui/`, animazioni in +`src/components/motion/`. Mobile-first (DD-005): poche schermate, pochi click. -Deploy automatico su Vercel \ No newline at end of file +## 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 # test unit (veloci, senza rete né database) +npm run test:integration # route server vere +npm run test:e2e # percorsi sull'app servita +npm run test:all # tutto +``` + +## Branch e flusso di sviluppo + +- `main` → produzione, deploy automatico su Vercel. +- `develop` → sviluppo; si lavora qui, mai direttamente su `main` (DD-003). + +``` +develop → test → merge su main → deploy automatico su Vercel +``` diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 05cf4ba..196999b 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,10 +1,10 @@ # Changelog -Tutte le modifiche significative del progetto vengono registrate in questo documento. +Tutte le modifiche significative del progetto vengono registrate in questo documento, in +ordine dalla più recente. L'elenco delle funzionalità disponibili e previste non si ripete +qui: sta in [ROADMAP.md](ROADMAP.md). ---- - -## Versione attuale +## Versione attuale — agosto 2026 ### Test @@ -18,7 +18,7 @@ Tutte le modifiche significative del progetto vengono registrate in questo docum - Classifica e risultati ufficiali letti dal portale Livescore CSI Bologna (stagione 2025/26, Campionato Open Misto Eccellenza, Girone B). - La pagina Campionato non usa più dati dimostrativi. -- Dettagli e limiti in `docs/modules/collegamento-csi.md`. +- Dettagli e limiti in [modules/collegamento-csi.md](modules/collegamento-csi.md). ### Infrastruttura @@ -28,17 +28,7 @@ Tutte le modifiche significative del progetto vengono registrate in questo docum - Deploy automatico tramite Vercel. - Branch main e develop. ---- +## Versione 1.0 — luglio 2026 -## Funzionalità implementate - -- Gestione squadra -- Calendario -- Presenze -- Scout Live -- Badge -- Obiettivi di squadra -- Pagelle -- Badge social -- Serie di presenze -- Notifiche intelligenti \ No newline at end of file +Prima versione usata dalla squadra. Funzionalità incluse: vedi +[ROADMAP.md § Versione 1.0](ROADMAP.md#versione-10--rilasciata). diff --git a/docs/DATABASE.md b/docs/DATABASE.md index 738d2e6..0cd85bb 100644 --- a/docs/DATABASE.md +++ b/docs/DATABASE.md @@ -1,159 +1,60 @@ # Database CrAPP -## Obiettivo +Struttura del database Supabase (PostgreSQL) e ruolo di ogni tabella. Lo schema autoritativo +sono le migration in `supabase/migrations/`: **una tabella nuova va documentata qui nella +stessa modifica che la crea**. Le funzionalità future stanno in [ROADMAP.md](ROADMAP.md), +non in questo file. -Questo documento descrive la struttura del database Supabase e il ruolo di ogni tabella. +## Anagrafica e utenti ---- +| Tabella | Scopo | Note | +|---|---|---| +| `giocatori_squadra` | Anagrafica operativa della squadra, con ID testuali (`g1`…`gN`), dati gestiti dagli admin (nome, cognome, numero, ruolo) e collegamento all'account (`auth_user_id`). | Introdotta dalla migration `m1_giocatori_squadra`, già popolata (17 giocatori) ma **non ancora letta dal codice**: la rosa arriva tuttora da `src/lib/crapp-data.ts`, che resta il fallback anche dopo il passaggio. Destinata a diventare la source of truth. Vedi DD-015 e DD-016. | +| `giocatori` | Anagrafica giocatori con UUID. | Presente ma **non usata** dal codice attuale: la convergenza è rinviata (DD-012, DD-014). | +| `profili_giocatore` | Dati personali, metadati del documento d'identità, certificato medico e path dei file, in relazione 1:1 con `giocatori_squadra`. | **Prevista** per la v1.1 (DD-016), non ancora creata. | +| `user_roles` | Ruoli applicativi (es. amministratore, giocatore). | | -# Utenti +`giocatori_squadra` / `giocatori` sono usate da: Squadra, Profili, Presenze, Scout, Badge, Pagelle. -## giocatori +## Eventi e presenze -Contiene l'anagrafica dei giocatori. +| Tabella | Scopo | Note | +|---|---|---| +| `eventi_app` | Eventi gestionali utilizzati dall'app. | Modello in uso dal codice attuale. | +| `risposte_presenze` | Risposte dei giocatori agli eventi. | Modello in uso dal codice attuale. | +| `eventi` | Calendario generale: allenamenti, partite, eventi della squadra. | Modello "nuovo" con autenticazione e vincoli, non ancora adottato (DD-014). | +| `presenze` | Presenze agli eventi. | Come sopra (DD-014). | -Utilizzato da: +## Scout -- Squadra -- Profili -- Presenze -- Scout -- Badge -- Pagelle +| Tabella | Scopo | Note | +|---|---|---| +| `scout_sessioni` | Sessioni di Scout Live: una sessione corrisponde a una partita. | **Non ancora usata dal codice**: oggi lo stato della sessione vive in `localStorage` (`src/lib/scout-live.ts`, `scout-store.ts`) e sul database finiscono solo le azioni in `scout_live`. | +| `scout_live` | Eventi registrati durante lo Scout Live. | Serve esclusivamente per statistiche di squadra, mai per classifiche individuali (DD-008). | ---- +## Votazioni -## user_roles +| Tabella | Scopo | Note | +|---|---|---| +| `mvp_voti` | Voti MVP assegnati a fine partita. | | +| `pagelle_voti` | Voti anonimi assegnati ai giocatori. | Usati per il voto medio. | +| `badge_social_voti` | Voti social per i badge. | | -Definisce i ruoli applicativi. +## Turni e notifiche -Esempi: +| Tabella | Scopo | Note | +|---|---|---| +| `turni_palloni` | Gestione dei turni palloni. | | +| `push_subscriptions` | Dispositivi registrati per le notifiche Push. | | +| `promemoria_push` | Storico dei promemoria inviati. | | -- amministratore -- giocatore +## Funzioni speciali ---- +| Tabella | Scopo | Note | +|---|---|---| +| `cacche_partita` | Sondaggio prepartita. | Usato per statistiche e badge segreti. | -# Eventi +## Badge -## eventi - -Calendario generale. - -Comprende: - -- allenamenti -- partite -- eventi della squadra - ---- - -## eventi_app - -Eventi gestionali utilizzati dall'app. - ---- - -# Presenze - -## presenze - -Gestisce le presenze agli eventi. - ---- - -## risposte_presenze - -Memorizza le risposte dei giocatori. - ---- - -# Scout - -## scout_sessioni - -Sessioni di Scout Live. - -Una sessione corrisponde ad una partita. - ---- - -## scout_live - -Eventi registrati durante lo Scout Live. - -Serve esclusivamente per statistiche di squadra. - ---- - -# Votazioni - -## mvp_voti - -Voti MVP assegnati a fine partita. - ---- - -## pagelle_voti - -Voti anonimi assegnati ai giocatori. - -Utilizzati per il voto medio. - ---- - -## badge_social_voti - -Voti social per i badge. - ---- - -# Badge - -Attualmente i badge vengono calcolati dall'applicazione. - -Non esiste una tabella dedicata. - ---- - -# Turni - -## turni_palloni - -Gestione dei turni palloni. - ---- - -# Notifiche - -## push_subscriptions - -Dispositivi registrati per le notifiche Push. - ---- - -## promemoria_push - -Storico dei promemoria inviati. - ---- - -# Funzioni speciali - -## cacche_partita - -Sondaggio prepartita. - -Utilizzato per statistiche e badge segreti. - ---- - -# Moduli futuri - -Da implementare - -- Certificati medici -- Tesseramenti CSI -- Database allenamenti -- AI Allenamenti -- Integrazione CSI \ No newline at end of file +Non esiste una tabella dedicata: i badge vengono **calcolati a runtime** dall'applicazione a +partire dai dati esistenti (DD-007). diff --git a/docs/DESIGN_DECISIONS.md b/docs/DESIGN_DECISIONS.md index be82aa4..384643d 100644 --- a/docs/DESIGN_DECISIONS.md +++ b/docs/DESIGN_DECISIONS.md @@ -12,6 +12,36 @@ Serve a rispondere a domande del tipo: --- +## Indice + +**Accettate** + +| ID | Titolo | +|---|---| +| [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 | +| [DD-007](#dd-007--badge-calcolati-dallapp-non-salvati-nel-database) | Badge calcolati, non in DB | +| [DD-008](#dd-008--gamification-equa-tra-ruoli) | Gamification equa tra ruoli | +| [DD-009](#dd-009--tesseramento-csi-manuale-in-v11-integrazione-api-in-v20) | CSI manuale v1.1, API v2.0 | +| [DD-010](#dd-010--profilo-giocatore-niente-storico-certificati-in-v1) | Niente storico certificati v1 | +| [DD-011](#dd-011--autenticazione-reale-prima-del-profilo-amministrativo-completo) | Auth reale prima del profilo | +| [DD-012](#dd-012--non-migrare-gli-id-giocatore-in-v11) | Non migrare ID in v1.1 | +| [DD-013](#dd-013--portabilità-lapp-non-deve-dipendere-da-servizi-esclusivi) | Portabilità dello stack | +| [DD-016](#dd-016--schema-dati-profilo-giocatore-v11-f0) | Schema dati Profilo Giocatore v1.1 | + +**In valutazione** + +| ID | Titolo | +|---|---| +| [DD-014](#dd-014--convergenza-schema-database-eventi-e-presenze) | Convergenza schema DB | +| [DD-015](#dd-015--rosa-anagrafica-da-codice-hardcoded-a-database) | Rosa da hardcoded a DB | + +--- + ## Come usare questo registro Ogni decisione segue lo stesso schema: @@ -39,6 +69,11 @@ Ogni decisione segue lo stesso schema: - scelte estetiche minori; - bugfix o correzioni puntuali. +**Come registrare una nuova decisione** + +Copiare [`_template-dd.md`](_template-dd.md) in fondo al documento, assegnare il primo ID +libero e aggiungerlo all'indice. + --- ## Decisioni accettate @@ -442,57 +477,3 @@ Il profilo v1.1 può agganciarsi agli ID attuali; la migrazione rosa può essere In parallelo o subito dopo il rollout auth. --- - -## Template per nuove decisioni - -Copiare questo blocco in fondo al documento quando serve registrare una nuova scelta. - ---- - -### DD-XXX — [Titolo breve della decisione] - -**Data:** -**Stato:** Accettata · In valutazione · Sostituita · Obsoleta - -**Contesto** -[Quale problema stavamo risolvendo?] - -**Decisione** -[Cosa abbiamo scelto?] - -**Alternative scartate** -- [Alternativa 1] → [perché no] -- [Alternativa 2] → [perché no] - -**Conseguenze** -[Cosa cambia per utenti, admin e team di sviluppo] - -**Riesame** -[Quando o in quali condizioni rivedere la decisione] - ---- - -## Indice rapido - -| ID | Titolo | Stato | -|---|---|---| -| DD-001 | Indipendenza da Lovable | Accettata | -| DD-002 | Sviluppo document-first | Accettata | -| DD-003 | Branch main / develop | Accettata | -| DD-004 | Ogni versione aggiunge, non riscrive | Accettata | -| DD-005 | Mobile-first | Accettata | -| DD-006 | AI solo se utile | Accettata | -| DD-007 | Badge calcolati, non in DB | Accettata | -| DD-008 | Gamification equa tra ruoli | Accettata | -| DD-009 | CSI manuale v1.1, API v2.0 | Accettata | -| DD-010 | Niente storico certificati v1 | Accettata | -| DD-011 | Auth reale prima del profilo | Accettata | -| DD-012 | Non migrare ID in v1.1 | Accettata | -| DD-013 | Portabilità dello stack | Accettata | -| DD-016 | Schema dati Profilo Giocatore v1.1 | Accettata | -| DD-014 | Convergenza schema DB | In valutazione | -| DD-015 | Rosa da hardcoded a DB | In valutazione | - ---- - -*Ultimo aggiornamento: 28 agosto 2026* diff --git a/docs/EFFICIENZA_CLOUD.md b/docs/EFFICIENZA_CLOUD.md new file mode 100644 index 0000000..21a0d5b --- /dev/null +++ b/docs/EFFICIENZA_CLOUD.md @@ -0,0 +1,36 @@ +# Efficienza cloud + +Regola di progetto: CrAPP gira su un piano cloud minimo (Supabase + Vercel) per ~17 utenti. +Query, traffico e invocazioni vanno tenuti al minimo **per costruzione**, non ottimizzati dopo. + +## Regole da rispettare + +1. **Niente polling**: mai `refetchInterval` verso il database. Per sincronizzare più schede + aperte si usano `BroadcastChannel` o gli eventi di `storage`. +2. **Cache lunga e passiva**: i default del `QueryClient` stanno in `src/router.tsx` + (`staleTime` 5 min, `gcTime` 30 min, `refetchOnWindowFocus/Mount/Reconnect` disattivati, + `retry: 1`). Non alzare la frequenza di refetch modulo per modulo. +3. **Dopo una mutazione si aggiorna la cache con `setQueryData`**, non con + `invalidateQueries`: invalidare costa una rilettura. Unica eccezione oggi: + `src/lib/scout-live.ts`. +4. **Scout Live**: scrive solo chi sta segnando; gli altri leggono dati già salvati. +5. **Write once, read many**: statistiche, badge e classifiche si calcolano una volta e non + si ricalcolano a ogni apertura di pagina. I badge restano calcolati a runtime dai dati già + in cache, senza query aggiuntive (DD-007): `src/lib/rosa.ts` aggrega ciò che è già stato + letto. +6. **Push solo per eventi importanti**: convocazioni, promemoria allenamento/partita, turno + palloni, esito finale. +7. **Niente funzionalità pesanti**: foto, video, chat. +8. **Indici** sui campi usati per filtri e relazioni in ogni nuova migration. + +## Obiettivi non ancora attuati + +Questi punti sono stati definiti come direzione, ma **non sono implementati**: non descrivono +il comportamento attuale. + +- **Dati CSI**: sincronizzazione periodica server-side salvata su una tabella locale, con + l'app che legge solo dal database interno. Oggi la lettura è live dal portale a ogni + richiesta, tramite `/api/public/csi` (vedi [modules/collegamento-csi.md](modules/collegamento-csi.md)). +- **Aggregati persistiti**: uno schema con `statistiche_aggregate` e `classifica_csi` è stato + ipotizzato ma non esiste; nessuna di quelle tabelle è in `supabase/migrations/`. Va valutato + con una decisione dedicata, perché tocca DD-007 (badge e statistiche calcolati a runtime). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d5dbd10 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,44 @@ +# Documentazione CrAPP + +Indice della documentazione ufficiale del progetto. Ogni file risponde a una domanda +precisa: se l'informazione che cerchi non è nel file indicato, probabilmente non esiste +ancora e va **prima documentata** (vedi [DD-002](DESIGN_DECISIONS.md#dd-002--sviluppo-document-first)). + +## Dove sta cosa + +| Documento | Risponde a | +|---|---| +| [VISION.md](VISION.md) | Perché esiste CrAPP, quali principi deve rispettare una funzionalità | +| [ROADMAP.md](ROADMAP.md) | Cosa è fatto e cosa è previsto, versione per versione | +| [ARCHITECTURE.md](ARCHITECTURE.md) | Com'è fatta l'app: stack, struttura del codice, flusso di sviluppo | +| [DATABASE.md](DATABASE.md) | Quali tabelle esistono, a cosa servono, chi le usa | +| [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) | Perché abbiamo scelto così, cosa abbiamo escluso e quando riaprire la scelta | +| [PORTABILITA.md](PORTABILITA.md) | Cosa lega l'app a un fornitore e cosa no, come spostarla su server proprio | +| [EFFICIENZA_CLOUD.md](EFFICIENZA_CLOUD.md) | Come tenere basso il consumo cloud: cache, query, push | +| [TODO.md](TODO.md) | A cosa si sta lavorando adesso | +| [CHANGELOG.md](CHANGELOG.md) | Cosa è cambiato e quando | +| [modules/](modules/) | Specifica funzionale di ogni modulo, una per file | + +Le regole vincolanti per gli assistenti AI stanno in [AGENTS.md](../AGENTS.md); +lo stato corrente del lavoro in [PROJECT_STATE.md](../PROJECT_STATE.md). + +## Ordine di lettura + +Prima di modificare il codice, nell'ordine: questo indice → `VISION.md` → `ROADMAP.md` → +`ARCHITECTURE.md` → `DATABASE.md` → `DESIGN_DECISIONS.md` → `TODO.md` → il documento del +modulo interessato in `modules/`. + +## Regole di manutenzione + +Ogni informazione ha **una sola casa**, per evitare che le copie divergano: + +- l'elenco delle funzionalità (fatte e previste) sta solo in `ROADMAP.md`; +- `CHANGELOG.md` registra *quando* qualcosa è stato rilasciato, non ripete l'elenco; +- `TODO.md` contiene solo il lavoro in corso o imminente, e rimanda alla roadmap; +- lo schema del database sta solo in `DATABASE.md`, allineato alle migration in + `supabase/migrations/`: una tabella nuova si documenta nella stessa modifica che la crea; +- le motivazioni stanno solo in `DESIGN_DECISIONS.md`, in voci `DD-XXX`; per aggiungerne + una si copia [\_template-dd.md](_template-dd.md). + +Convenzioni di scrittura: un solo titolo `#` per file (le sezioni interne partono da `##`), +niente `---` come riempitivo tra i paragrafi, tabelle al posto degli elenchi ripetitivi. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 30846d9..8559122 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,16 +1,21 @@ # Roadmap -## Versione 1.0 +Elenco unico delle funzionalità di CrAPP, fatte e previste. È la fonte di riferimento per +il *cosa*: `CHANGELOG.md` registra *quando* una voce è stata rilasciata, `TODO.md` cosa si +sta facendo adesso. + +## Versione 1.0 — rilasciata - [x] Gestione squadra - [x] Calendario - [x] Presenze +- [x] Serie di presenze - [x] Scout Live - [x] Badge +- [x] Badge social +- [x] Pagelle - [x] Obiettivi di squadra -- [x] Notifiche Push - ---- +- [x] Notifiche Push (promemoria intelligenti) ## Versione 1.1 @@ -19,16 +24,12 @@ - [ ] Dashboard amministratore - [ ] Download CSV dati ---- - ## Versione 1.2 - [ ] Database esercizi - [ ] AI Allenamenti - [ ] Archivio allenamenti ---- - ## Versione 2.0 - [x] Collegamento CSI (stagione 2025/26) @@ -36,11 +37,11 @@ - [x] Risultati campionato - [ ] Calendario ufficiale ---- - ## Idee future - [ ] Gestione quote - [ ] Calendario Google - [ ] Backup automatici -- [ ] Analisi statistiche avanzate \ No newline at end of file +- [ ] Analisi statistiche avanzate +- [ ] Widget meteo +- [ ] Analisi Scout con AI diff --git a/docs/TODO.md b/docs/TODO.md index 3e98a9d..e1967ba 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -1,30 +1,35 @@ # TODO +Solo il lavoro in corso o imminente. L'elenco completo delle funzionalità previste sta in +[ROADMAP.md](ROADMAP.md); le idee non ancora valutate pure. + ## In corso - Documentazione tecnica del progetto. ---- - ## Prossimo -- Certificati medici. -- Gestione tesseramenti CSI. +- Certificati medici (roadmap v1.1). +- Gestione tesseramenti CSI (roadmap v1.1). ---- +## Debito di documentazione + +Moduli v1.0 in produzione senza scheda in [modules/](modules/) — DD-002 ne prevede la +retro-documentazione: Presenze, Scout Live, Badge, Pagelle, MVP, Palloni, Obiettivi di +squadra, Notifiche, Serie di presenze, Infortuni (`src/lib/infortuni.ts`, usato ma non +documentato in nessun punto). + +Non documentate nemmeno le route API pubbliche in `src/routes/api/public/` (`csi`, +`promemoria-palloni`, `push-config`, `push-messaggio`, `push-subscribe`, +`sollecita-presenze`). + +## Manutenzione ricorrente + +- Collegamento CSI: aggiornare `project_id` e `team_id` a inizio stagione 2026/27 + (vedi [modules/collegamento-csi.md](modules/collegamento-csi.md)). ## Backlog -- AI Allenamenti. -- Dashboard amministratore. -- Collegamento CSI: aggiornare `project_id` e `team_id` per la stagione 2026/27 - (base implementata, vedi `docs/modules/collegamento-csi.md`). - ---- - -## Idee - -- Gestione quote. -- Widget meteo. -- Analisi Scout con AI. -- Backup automatici. \ No newline at end of file +- AI Allenamenti (roadmap v1.2). +- Dashboard amministratore (roadmap v1.1). +- Backup automatici (roadmap, idee future). diff --git a/docs/VISION.md b/docs/VISION.md index 6aa2495..bfe6a71 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -6,8 +6,6 @@ CrAPP nasce con un obiettivo semplice: Digitalizzare completamente la gestione di una squadra di pallavolo, eliminando il maggior numero possibile di attività manuali e aumentando il coinvolgimento dei giocatori attraverso strumenti moderni e intuitivi. ---- - ## Principi del progetto Ogni funzionalità sviluppata deve rispettare almeno uno di questi principi: @@ -18,8 +16,6 @@ Ogni funzionalità sviluppata deve rispettare almeno uno di questi principi: - Automatizzare le attività ripetitive. - Sfruttare l'intelligenza artificiale solo quando porta un reale beneficio. ---- - ## Filosofia CrAPP deve essere: @@ -31,8 +27,6 @@ CrAPP deve essere: - Accessibile da smartphone - Utilizzabile anche da persone poco esperte ---- - ## Obiettivo finale Diventare il punto di riferimento per la gestione quotidiana della squadra, sostituendo chat, fogli Excel e strumenti separati con un'unica applicazione. \ No newline at end of file diff --git a/docs/_template-dd.md b/docs/_template-dd.md new file mode 100644 index 0000000..7a2d48c --- /dev/null +++ b/docs/_template-dd.md @@ -0,0 +1,20 @@ +### DD-XXX — [Titolo breve della decisione] + +**Data:** +**Stato:** Accettata · In valutazione · Sostituita · Obsoleta + +**Contesto** +[Quale problema stavamo risolvendo?] + +**Decisione** +[Cosa abbiamo scelto?] + +**Alternative scartate** +- [Alternativa 1] → [perché no] +- [Alternativa 2] → [perché no] + +**Conseguenze** +[Cosa cambia per utenti, admin e team di sviluppo] + +**Riesame** +[Quando o in quali condizioni rivedere la decisione] diff --git a/docs/modules/profilo-giocatore.md b/docs/modules/profilo-giocatore.md index 5c5fb4e..ed4f0c9 100644 --- a/docs/modules/profilo-giocatore.md +++ b/docs/modules/profilo-giocatore.md @@ -1,4 +1,4 @@ -# Profilo Giocatore +# Modulo — Profilo Giocatore ## Obiettivo @@ -6,11 +6,9 @@ Il modulo "Profilo Giocatore" raccoglie tutte le informazioni personali, amminis L'obiettivo è centralizzare in un'unica schermata tutti i dati necessari sia al giocatore sia agli amministratori, eliminando la gestione tramite chat, documenti cartacei e fogli Excel. ---- +## Utenti -# Utenti - -## Giocatore +### Giocatore Può: @@ -20,9 +18,7 @@ Può: - aggiornare i documenti - caricare le immagini richieste ---- - -## Amministratore +### Amministratore Può: @@ -31,11 +27,9 @@ Può: - esportare i dati necessari al tesseramento CSI - verificare lo stato di completamento dei profili ---- +## Flusso utente -# Flusso utente - -## Primo accesso +### Primo accesso 1. Login tramite Google oppure Email. 2. Selezione del proprio giocatore. @@ -43,23 +37,13 @@ Può: Se il profilo non è completo compare automaticamente un widget di completamento. ---- - -# Home +## Home Il giocatore visualizza un widget dedicato. -## Completa il tuo profilo +### Completa il tuo profilo -Viene mostrata una barra di avanzamento. - -Esempio - -Profilo completato - -85% - -La barra è composta dalle seguenti sezioni. +Viene mostrata una barra di avanzamento (esempio: *Profilo completato — 85%*), composta dalle seguenti sezioni. - Dati personali - Documento di identità @@ -68,32 +52,20 @@ La barra è composta dalle seguenti sezioni. Quando tutte le sezioni sono complete il widget scompare automaticamente. ---- - -# Profilo +## Profilo Il profilo viene suddiviso in cinque aree. -## Dati Giocatore +### Dati Giocatore -Contiene. - -### Dati squadra - -Solo lettura. +**Dati squadra** — solo lettura, gestiti esclusivamente dagli amministratori. - Nome - Cognome - Numero di maglia - Ruolo -Questi dati sono gestiti esclusivamente dagli amministratori. - ---- - -### Dati personali - -Modificabili dal giocatore. +**Dati personali** — modificabili dal giocatore. - Data di nascita - Luogo di nascita @@ -101,9 +73,7 @@ Modificabili dal giocatore. - Telefono - Email ---- - -## Documento di identità +### Documento di identità Campi. @@ -118,9 +88,7 @@ Upload. - Foto fronte - Foto retro ---- - -## Certificato medico +### Certificato medico Campi. @@ -134,21 +102,15 @@ Il giocatore può aggiornare liberamente sia la data sia il file. Lo storico non viene mantenuto nella prima versione. ---- - -## Foto tessera +### Foto tessera Upload di una fotografia formato tessera. Utilizzata dagli amministratori per il tesseramento CSI. ---- +### Statistiche -## Statistiche - -Sezione già presente. - -Contiene. +Sezione già presente. Contiene. - Presenze - Voto medio @@ -156,17 +118,13 @@ Contiene. - Serie - Altre statistiche disponibili ---- - -## Badge +### Badge Sezione già presente. Contiene tutti i badge ottenuti e quelli ancora da sbloccare. ---- - -## Impostazioni +### Impostazioni Contiene. @@ -174,9 +132,7 @@ Contiene. - Preferenze notifiche - Impostazioni applicazione ---- - -# Dashboard amministratore +## Dashboard amministratore Gli amministratori dispongono di una schermata dedicata. @@ -194,9 +150,7 @@ Azioni disponibili. - Scarica documento - Scarica foto tessera ---- - -# Esportazione CSI +## Esportazione CSI Gli amministratori possono esportare un file CSV contenente esclusivamente i dati richiesti per il tesseramento. @@ -215,51 +169,26 @@ Campi esportati. - Data emissione - Data scadenza ---- - -# Completamento profilo +## Completamento profilo Ogni sezione contribuisce alla percentuale di completamento. -## Pesi - -Dati personali - -30% - -Documento di identità - -30% - -Certificato medico - -30% - -Foto tessera - -10% +| Sezione | Peso | +|---|---| +| Dati personali | 30% | +| Documento di identità | 30% | +| Certificato medico | 30% | +| Foto tessera | 10% | Quando tutte le sezioni risultano complete il profilo raggiunge il 100%. ---- +## Permessi -# Permessi +**Giocatore** — può modificare esclusivamente il proprio profilo. -## Giocatore +**Amministratore** — può visualizzare tutti i profili, scaricare tutti i documenti ed esportare i dati. -Può modificare esclusivamente il proprio profilo. - -## Amministratore - -Può visualizzare tutti i profili. - -Può scaricare tutti i documenti. - -Può esportare i dati. - ---- - -# Versione 1 +## Versione 1 - Profilo giocatore - Completamento profilo @@ -270,12 +199,10 @@ Può esportare i dati. - Dashboard amministratore - Esportazione CSV CSI ---- - -# Versioni future +## Versioni future - Storico certificati medici - Gestione documenti aggiuntivi - Consensi privacy - Firma digitale -- Verifica automatica documenti \ No newline at end of file +- Verifica automatica documenti diff --git a/mem/features/cloud-efficienza.md b/mem/features/cloud-efficienza.md deleted file mode 100644 index a33330d..0000000 --- a/mem/features/cloud-efficienza.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: Efficienza Cloud -description: Regole per minimizzare query, traffico e invocazioni Cloud (piano 20 crediti/mese, 17 utenti) -type: feature ---- -- Nessun polling (`refetchInterval`) verso il database; sincronizzazione locale via BroadcastChannel/storage dove possibile. -- QueryClient globale: staleTime 5 min, gcTime 30 min, refetchOnWindowFocus/Mount/Reconnect disattivati, retry 1. -- Dopo una mutazione aggiornare la cache con `setQueryData`, non `invalidateQueries` (evita riletture). -- Scout live: scrive solo l'utente che segna; gli altri leggono dati già salvati. -- Statistiche, badge e classifiche: "write once, read many" — calcolate e salvate una volta a fine partita, mai ricalcolate a ogni apertura pagina. -- Dati CSI: sincronizzazione periodica server-side salvata su tabella locale; l'app legge solo dal database interno. -- Push solo per eventi importanti: convocazioni, promemoria allenamento/partita, turno palloni, esito finale. -- Niente foto/video/chat o funzionalità pesanti. -- Schema target: team_id, eventi, presenze, azioni_scout, statistiche_aggregate, classifica_csi, notifiche, con indici sui campi di filtro/relazione. diff --git a/mem/features/portabilita.md b/mem/features/portabilita.md deleted file mode 100644 index 6819684..0000000 --- a/mem/features/portabilita.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: Portabilità su Node.js + PostgreSQL -description: Vincolo di architettura — l'app deve girare su un normale server Node.js con PostgreSQL, senza servizi esclusivi Lovable Cloud -type: constraint ---- -L'app deve restare completamente portabile: ogni funzionalità deve poter girare su un normale server Node.js con PostgreSQL. - -Regole: -- Accesso ai dati solo tramite i moduli in `src/lib/*.ts`; i componenti non parlano mai direttamente col database. -- Vietato usare funzionalità proprietarie Lovable/Supabase non self-hostable (edge functions proprietarie, auth Lovable come unico login, storage proprietario). `src/integrations/lovable/*` resta opzionale e non importato. -- SQL standard PostgreSQL nelle migrazioni; niente estensioni esclusive del provider. -- Configurazione solo via variabili d'ambiente standard; niente valori hardcoded. -- Job pianificati sempre richiamabili con un semplice HTTP POST, così funzionano con qualsiasi scheduler. -- Web push implementato con Web Crypto (compatibile Node 18+), non con SDK proprietari. - -Dettaglio e guida di migrazione: `docs/PORTABILITA.md`. diff --git a/mem/index.md b/mem/index.md index 9def87e..ce78dd3 100644 --- a/mem/index.md +++ b/mem/index.md @@ -1,2 +1,4 @@ -- [Efficienza Cloud](mem://features/cloud-efficienza) — Regole anti-consumo: niente polling, cache lunga, aggregati precalcolati, sync CSI server-side -- [Portabilità](mem://features/portabilita) — L'app deve girare su Node.js + PostgreSQL standard, nessun servizio esclusivo Lovable Cloud +Le regole di progetto non vivono più qui: sono in `docs/`. + +- Efficienza cloud → `docs/EFFICIENZA_CLOUD.md` +- Portabilità → `docs/PORTABILITA.md`