Add project documentation and AI development guidelines

2026-08-07 15:36:02 +02:00
parent 6dc63d9250
commit 7a2b26ec89
15 changed files with 1124 additions and 114 deletions
@@ -0,0 +1,71 @@
+# Architettura del progetto
+
+## Frontend
+
+- React 19
+- TypeScript
+- TanStack Start
+- Vite
+- Tailwind CSS
+- Radix UI
+
+---
+
+## Backend
+
+- Supabase
+
+---
+
+## Hosting
+
+- Vercel
+
+---
+
+## Versionamento
+
+- Git
+- GitHub
+
+---
+
+## Branch
+
+- main → Produzione
+- develop → Sviluppo
+
+---
+
+## Struttura del progetto
+
+src/
+
+- components/
+- routes/
+- lib/
+- integrations/
+- hooks/
+- assets/
+
+supabase/
+
+docs/
+
+---
+
+## Flusso di sviluppo
+
+develop
+
+↓
+
+Test
+
+↓
+
+Merge su main
+
+↓
+
+Deploy automatico su Vercel
@@ -0,0 +1,30 @@
+# Changelog
+
+Tutte le modifiche significative del progetto vengono registrate in questo documento.
+
+---
+
+## Versione attuale
+
+### Infrastruttura
+
+- Migrazione completa da Lovable a sviluppo locale.
+- Configurazione Git.
+- Repository GitHub indipendente.
+- Deploy automatico tramite Vercel.
+- Branch main e develop.
+
+---
+
+## Funzionalità implementate
+
+- Gestione squadra
+- Calendario
+- Presenze
+- Scout Live
+- Badge
+- Obiettivi di squadra
+- Pagelle
+- Badge social
+- Serie di presenze
+- Notifiche intelligenti
@@ -0,0 +1,159 @@
+# Database CrAPP
+
+## Obiettivo
+
+Questo documento descrive la struttura del database Supabase e il ruolo di ogni tabella.
+
+---
+
+# Utenti
+
+## giocatori
+
+Contiene l'anagrafica dei giocatori.
+
+Utilizzato da:
+
+- Squadra
+- Profili
+- Presenze
+- Scout
+- Badge
+- Pagelle
+
+---
+
+## user_roles
+
+Definisce i ruoli applicativi.
+
+Esempi:
+
+- amministratore
+- giocatore
+
+---
+
+# Eventi
+
+## 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
@@ -0,0 +1,46 @@
+# Roadmap
+
+## Versione 1.0
+
+- [x] Gestione squadra
+- [x] Calendario
+- [x] Presenze
+- [x] Scout Live
+- [x] Badge
+- [x] Obiettivi di squadra
+- [x] Notifiche Push
+
+---
+
+## Versione 1.1
+
+- [ ] Certificati medici
+- [ ] Gestione tesseramenti CSI
+- [ ] Dashboard amministratore
+- [ ] Download CSV dati
+
+---
+
+## Versione 1.2
+
+- [ ] Database esercizi
+- [ ] AI Allenamenti
+- [ ] Archivio allenamenti
+
+---
+
+## Versione 2.0
+
+- [ ] Collegamento CSI
+- [ ] Classifica automatica
+- [ ] Risultati campionato
+- [ ] Calendario ufficiale
+
+---
+
+## Idee future
+
+- [ ] Gestione quote
+- [ ] Calendario Google
+- [ ] Backup automatici
+- [ ] Analisi statistiche avanzate
@@ -0,0 +1,29 @@
+# TODO
+
+## In corso
+
+- Documentazione tecnica del progetto.
+
+---
+
+## Prossimo
+
+- Certificati medici.
+- Gestione tesseramenti CSI.
+
+---
+
+## Backlog
+
+- AI Allenamenti.
+- Dashboard amministratore.
+- Collegamento CSI.
+
+---
+
+## Idee
+
+- Gestione quote.
+- Widget meteo.
+- Analisi Scout con AI.
+- Backup automatici.
@@ -0,0 +1,38 @@
+# Visione del progetto
+
+## Missione
+
+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:
+
+- Ridurre il lavoro amministrativo.
+- Migliorare il coinvolgimento della squadra.
+- Centralizzare tutte le informazioni in un'unica piattaforma.
+- Automatizzare le attività ripetitive.
+- Sfruttare l'intelligenza artificiale solo quando porta un reale beneficio.
+
+---
+
+## Filosofia
+
+CrAPP deve essere:
+
+- Semplice
+- Veloce
+- Divertente
+- Intuitiva
+- 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.
@@ -0,0 +1,281 @@
+# Profilo Giocatore
+
+## Obiettivo
+
+Il modulo "Profilo Giocatore" raccoglie tutte le informazioni personali, amministrative e documentali di ciascun membro della squadra.
+
+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
+
+## Giocatore
+
+Può:
+
+- visualizzare il proprio profilo
+- modificare i propri dati personali
+- aggiornare il certificato medico
+- aggiornare i documenti
+- caricare le immagini richieste
+
+---
+
+## Amministratore
+
+Può:
+
+- visualizzare il profilo di tutti i giocatori
+- scaricare documenti e certificati
+- esportare i dati necessari al tesseramento CSI
+- verificare lo stato di completamento dei profili
+
+---
+
+# Flusso utente
+
+## Primo accesso
+
+1. Login tramite Google oppure Email.
+2. Selezione del proprio giocatore.
+3. Accesso alla Home.
+
+Se il profilo non è completo compare automaticamente un widget di completamento.
+
+---
+
+# Home
+
+Il giocatore visualizza un widget dedicato.
+
+## Completa il tuo profilo
+
+Viene mostrata una barra di avanzamento.
+
+Esempio
+
+Profilo completato
+
+85%
+
+La barra è composta dalle seguenti sezioni.
+
+- Dati personali
+- Documento di identità
+- Certificato medico
+- Foto tessera
+
+Quando tutte le sezioni sono complete il widget scompare automaticamente.
+
+---
+
+# Profilo
+
+Il profilo viene suddiviso in cinque aree.
+
+## Dati Giocatore
+
+Contiene.
+
+### Dati squadra
+
+Solo lettura.
+
+- Nome
+- Cognome
+- Numero di maglia
+- Ruolo
+
+Questi dati sono gestiti esclusivamente dagli amministratori.
+
+---
+
+### Dati personali
+
+Modificabili dal giocatore.
+
+- Data di nascita
+- Luogo di nascita
+- Indirizzo di residenza
+- Telefono
+- Email
+
+---
+
+## Documento di identità
+
+Campi.
+
+- Tipo documento
+- Numero documento
+- Rilasciato da
+- Data emissione
+- Data scadenza
+
+Upload.
+
+- Foto fronte
+- Foto retro
+
+---
+
+## Certificato medico
+
+Campi.
+
+- Data di scadenza
+
+Upload.
+
+- Certificato medico
+
+Il giocatore può aggiornare liberamente sia la data sia il file.
+
+Lo storico non viene mantenuto nella prima versione.
+
+---
+
+## Foto tessera
+
+Upload di una fotografia formato tessera.
+
+Utilizzata dagli amministratori per il tesseramento CSI.
+
+---
+
+## Statistiche
+
+Sezione già presente.
+
+Contiene.
+
+- Presenze
+- Voto medio
+- MVP
+- Serie
+- Altre statistiche disponibili
+
+---
+
+## Badge
+
+Sezione già presente.
+
+Contiene tutti i badge ottenuti e quelli ancora da sbloccare.
+
+---
+
+## Impostazioni
+
+Contiene.
+
+- Logout
+- Preferenze notifiche
+- Impostazioni applicazione
+
+---
+
+# Dashboard amministratore
+
+Gli amministratori dispongono di una schermata dedicata.
+
+Per ogni giocatore vengono mostrati.
+
+- Stato del profilo
+- Certificato medico
+- Documento di identità
+- Foto tessera
+
+Azioni disponibili.
+
+- Visualizza profilo
+- Scarica certificato
+- Scarica documento
+- Scarica foto tessera
+
+---
+
+# Esportazione CSI
+
+Gli amministratori possono esportare un file CSV contenente esclusivamente i dati richiesti per il tesseramento.
+
+Campi esportati.
+
+- Nome
+- Cognome
+- Data di nascita
+- Luogo di nascita
+- Indirizzo
+- Telefono
+- Email
+- Tipo documento
+- Numero documento
+- Rilasciato da
+- Data emissione
+- Data scadenza
+
+---
+
+# Completamento profilo
+
+Ogni sezione contribuisce alla percentuale di completamento.
+
+## Pesi
+
+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
+
+## Giocatore
+
+Può modificare esclusivamente il proprio profilo.
+
+## Amministratore
+
+Può visualizzare tutti i profili.
+
+Può scaricare tutti i documenti.
+
+Può esportare i dati.
+
+---
+
+# Versione 1
+
+- Profilo giocatore
+- Completamento profilo
+- Gestione dati personali
+- Documento di identità
+- Certificato medico
+- Foto tessera
+- Dashboard amministratore
+- Esportazione CSV CSI
+
+---
+
+# Versioni future
+
+- Storico certificati medici
+- Gestione documenti aggiuntivi
+- Consensi privacy
+- Firma digitale
+- Verifica automatica documenti