Reorganize documentation and unify the AI assistant rules
Documentation: - Add docs/README.md, the documentation index that AGENTS.md pointed to as the first file to read but which did not exist. - One home per piece of information: the feature list stays in ROADMAP.md, CHANGELOG.md records only when something shipped, TODO.md only ongoing work. Reconcile the entries that had drifted (CSI was both done and pending; pagelle, badge social and serie were missing from the roadmap). - Rewrite DATABASE.md as tables: add giocatori_squadra (already created by a migration) and profili_giocatore (planned in DD-016), fix the wrong heading levels, drop the duplicated roadmap. - DESIGN_DECISIONS.md: move the index to the top and sort it, extract the template into _template-dd.md. - ARCHITECTURE.md becomes the technical reference; CLAUDE.md no longer duplicates it. - Add docs/EFFICIENZA_CLOUD.md with the rules previously kept in mem/, separating what the code enforces from the goals not yet implemented. - Fix statements the code contradicted: mutations use setQueryData rather than invalidateQueries, and scout_sessioni and giocatori_squadra are not read by the code yet. - Track the v1.0 modules with no spec in docs/modules/ from TODO.md. AI assistants: - AGENTS.md is the single source of the rules, now including the technical constraints only Claude Code knew about (generated files, Vite plugins, data access) and an end-of-work checklist that applies to every assistant. - CLAUDE.md and .cursor/rules/crapp.mdc point to AGENTS.md instead of restating it. - Remove the five .cursor/*.md files, which Cursor never loaded. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
+84
-50
@@ -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
|
||||
## 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
|
||||
```
|
||||
|
||||
+8
-18
@@ -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
|
||||
Prima versione usata dalla squadra. Funzionalità incluse: vedi
|
||||
[ROADMAP.md § Versione 1.0](ROADMAP.md#versione-10--rilasciata).
|
||||
|
||||
+43
-142
@@ -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
|
||||
Non esiste una tabella dedicata: i badge vengono **calcolati a runtime** dall'applicazione a
|
||||
partire dai dati esistenti (DD-007).
|
||||
|
||||
+35
-54
@@ -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*
|
||||
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
+12
-11
@@ -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
|
||||
- [ ] Analisi statistiche avanzate
|
||||
- [ ] Widget meteo
|
||||
- [ ] Analisi Scout con AI
|
||||
|
||||
+23
-18
@@ -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.
|
||||
- AI Allenamenti (roadmap v1.2).
|
||||
- Dashboard amministratore (roadmap v1.1).
|
||||
- Backup automatici (roadmap, idee future).
|
||||
|
||||
@@ -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.
|
||||
@@ -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]
|
||||
@@ -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
|
||||
- Verifica automatica documenti
|
||||
|
||||
Reference in New Issue
Block a user