traccia-calorica/docs/REQUIREMENTS.md

Requisiti — CalorieTracker (Precision Vitality)

Documento di riferimento per tutti i requisiti funzionali e sistemistici del progetto. Ultimo aggiornamento: 16/04/2026

---

Indice Requisiti

ID	Tipo	Priorità	Titolo	Dipendenze
REQ-001	SISTEMISTICO	CRITICA	Scaffolding Ionic + Capacitor	—
REQ-002	SISTEMISTICO	CRITICA	Setup Firebase Firestore	REQ-001
REQ-003	EVOLUTIVO	ALTA	Home screen + FAB	REQ-002
REQ-004	EVOLUTIVO	ALTA	Modal input numerico	REQ-003
REQ-005	EVOLUTIVO	ALTA	Modal input LLM	REQ-003, REQ-006
REQ-006	EVOLUTIVO	ALTA	Servizio Claude API	REQ-001
REQ-007	EVOLUTIVO	ALTA	CRUD pasti Firestore	REQ-002
REQ-008	EVOLUTIVO	MEDIA	Statistiche giornaliere	REQ-007
REQ-009	EVOLUTIVO	MEDIA	Statistiche settimanali	REQ-007
REQ-010	EVOLUTIVO	MEDIA	Ricerca pasti	REQ-007
REQ-011	REWORK	MEDIA	Design brief Google Stitch	—

---

REQ-001 — Scaffolding Ionic + Capacitor

Tipo: SISTEMISTICO | Priorità: CRITICA

Obiettivo: Scaffolding del progetto Ionic 7+ con Capacitor 5+. Configurazione build nativa Android/iOS. Setup ambiente con struttura cartelle, linting e variabili d'ambiente.

Stato Target:

• Progetto Ionic Angular inizializzato con routing e tab layout (Journal, Stats, Plans, Profile)
• Capacitor configurato per Android e iOS
• Variabili ambiente: ANTHROPIC_API_KEY, FIREBASE_*
• Struttura moduli: core/, shared/, features/home, features/stats, features/search
• Proxy sviluppo configurato per CORS Anthropic API

Passi Implementativi:

1. ionic start calorie-tracker tabs --type=angular --capacitor
2. Aggiungere @capacitor/android e @capacitor/ios
3. Configurare capacitor.config.ts con appId e server URL
4. Creare struttura moduli features/ con lazy loading
5. Aggiungere @ionic/storage-angular per cache locale
6. Configurare environment.ts e environment.prod.ts
7. Verificare build ionic build + npx cap sync

Criteri Accettazione:

• ionic serve avvia l'app senza errori
• ionic build produce www/ senza errori
• npx cap sync completa senza errori
• Struttura a 4 tab visibile nel browser (Journal, Stats, Plans, Profile)
• Variabili d'ambiente lette correttamente in environment.ts

---

REQ-002 — Setup Firebase Firestore

Tipo: SISTEMISTICO | Priorità: CRITICA | Dipende da: REQ-001

Obiettivo: Setup Firebase con Firestore come database. Schema dati, regole sicurezza e SDK Angular.

Schema Firestore:

users/{userId}/
  meals/{mealId}/
    - id: string
    - timestamp: Timestamp
    - calories: number
    - inputType: 'manual' | 'llm'
    - description?: string
    - llmConfidence?: 'high' | 'medium' | 'low'
    - llmExplanation?: string
    - createdAt: Timestamp

Regole Sicurezza:

• Lettura/scrittura solo all'utente autenticato proprietario
• Nessun accesso cross-user

Auth: Anonymous auth abilitato (upgrade Google Sign-In futuro)

Passi Implementativi:

1. Creare Firebase project su console
2. Abilitare Firestore in modalità produzione
3. Abilitare Anonymous Authentication
4. Scaricare google-services.json e GoogleService-Info.plist
5. Installare @angular/fire e configurare in app.module.ts
6. Definire regole Firestore in firestore.rules
7. Creare FirestoreService con CRUD per collection meals
8. Testare lettura/scrittura da ionic serve

Criteri Accettazione:

• Scrittura documento su Firestore funzionante
• Lettura documenti da Firestore funzionante
• Regole sicurezza bloccano accesso non autenticato
• FirestoreService espone: addMeal(), getMealsByDate(), getMealsRange()
• Offline persistence abilitata e testata

---

REQ-003 — Home Screen + FAB

Tipo: EVOLUTIVO | Priorità: ALTA | Dipende da: REQ-002

Obiettivo: Home screen (tab Journal) con totale kcal giornaliero, lista pasti e FAB per aggiunta.

Specifiche UI (da design Precision Vitality):

• Header: data odierna centrata (es. "MERCOLEDÌ 16 APRILE")
• Titolo: "Il tuo progresso giornaliero"
• Numero kcal grande (56px, Lexend Bold, verde #006b1b)
• Label "calorie oggi"
• Barra progresso: kcal / obiettivo (default 2000)
• Sezione "Diario Alimentare": lista card pasti (ora, descrizione, kcal)
• Badge "AI" (arancione) o "M" (grigio) su ogni pasto
• FAB arancione #FF7043 in basso a destra con icona "+"
• Empty state: "Nessun pasto registrato oggi. Inizia!"

Criteri Accettazione:

• Totale kcal odierno visibile e aggiornato real-time
• Lista pasti del giorno visibile e scrollabile
• FAB visibile e cliccabile su tutti i device
• Empty state quando nessun pasto registrato
• Aggiornamento immediato dopo salvataggio nuovo pasto

---

REQ-004 — Modal Input Numerico

Tipo: EVOLUTIVO | Priorità: ALTA | Dipende da: REQ-003

Obiettivo: Modal per inserimento diretto kcal con tastiera numerica.

Specifiche UI (da design):

• Titolo: "Inserisci calorie"
• Icona fulmine verde
• Motivazionale: "Ogni dato conta per il tuo obiettivo."
• Campo numerico grande (font 40px), placeholder "0", label "KCAL"
• Campo "Descrizione (opzionale)"
• Bottone "Salva" verde a tutta larghezza
• Suggerimenti veloci: 150 (Spuntino), 450 (Pranzo), 600 (Cena)

Validazione: valore > 0 e ≤ 9999

Criteri Accettazione:

• Modal si apre dal FAB
• Tastiera numerica nativa su mobile
• Validazione blocca valori ≤ 0 e > 9999
• Salvataggio corretto su Firestore
• Toast conferma dopo salvataggio
• Modal si chiude e Home aggiorna totale

---

REQ-005 — Modal Input LLM (Descrizione Pasto)

Tipo: EVOLUTIVO | Priorità: ALTA | Dipende da: REQ-003, REQ-006

Obiettivo: Modal per descrizione testuale del pasto con stima AI.

Specifiche UI (da design):

• Titolo: "Descrivi il pasto"
• Sottotitolo: "Usa il linguaggio naturale per stimare i tuoi nutrienti in pochi secondi."
• Textarea "IL TUO PASTO" con placeholder
• Bottone "Stima calorie" arancione
• Risultato: badge "ALTA PRECISIONE" / "MEDIA" / "BASSA"
• Kcal stimate in grande + breakdown (carbi, proteine, grassi)
• Campo kcal modificabile
• Bottone "Salva" verde

Criteri Accettazione:

• Textarea accetta input testuale
• Bottone "Stima calorie" chiama API (REQ-006)
• Loading spinner durante chiamata
• Risultato kcal e badge confidence corretti
• Campo kcal modificabile dopo stima
• Salvataggio su Firestore con inputType: 'llm'
• Gestione errore timeout (messaggio + retry)

---

REQ-006 — Servizio Claude API

Tipo: EVOLUTIVO | Priorità: ALTA | Dipende da: REQ-001

Obiettivo: Servizio Angular per stima calorica via Claude API con proxy sicuro.

Architettura: Firebase Cloud Function come proxy (API key mai nel bundle)

Specifiche:

• Model: claude-haiku-4-5-20251001
• Max tokens: 256
• Food dictionary incluso nel system prompt
• Parser JSON robusto (strip markdown code blocks)
• Timeout: 10 secondi
• Risposta: { calories, confidence, explanation }

Criteri Accettazione:

• Stima kcal corretta per descrizioni test
• Food dictionary nel system prompt
• API key non nel bundle app
• Parser gestisce JSON wrapped in markdown
• Timeout 10s con errore esplicito

---

REQ-007 — CRUD Pasti Firestore

Tipo: EVOLUTIVO | Priorità: ALTA | Dipende da: REQ-002

Obiettivo: Servizio Angular per CRUD pasti su Firestore.

Metodi:

• addMeal(data) — scrittura con timestamp e userId
• getMealsForDate(date) — query filtrata per giorno (Observable)
• getMealsInRange(from, to) — query per range date
• deleteMeal(mealId) — hard delete
• getTotalCaloriesForDate(date) — aggregazione client-side

Criteri Accettazione:

• addMeal() scrive documento corretto
• getMealsForDate() restituisce solo pasti del giorno richiesto
• getMealsInRange() restituisce pasti nel range
• deleteMeal() rimuove documento
• Observable aggiorna componenti senza reload
• Funziona offline

---

REQ-008 — Statistiche Giornaliere

Tipo: EVOLUTIVO | Priorità: MEDIA | Dipende da: REQ-007

Obiettivo: Vista giornaliera nel tab Stats con totale kcal, breakdown pasti e progresso obiettivo.

Specifiche UI:

• Tab selector: "Oggi" | "Settimana"
• Navigazione tra giorni (frecce)
• Totale kcal, barra progresso (verde/rosso)
• Lista pasti con swipe-to-delete
• Obiettivo calorico: salvato in @ionic/storage (default 2000)

Criteri Accettazione:

• Totale kcal giornaliero corretto
• Navigazione tra giorni funzionante
• Barra progresso aggiornata real-time
• Colore cambia se obiettivo superato
• Swipe-to-delete funzionante

---

REQ-009 — Statistiche Settimanali

Tipo: EVOLUTIVO | Priorità: MEDIA | Dipende da: REQ-007

Obiettivo: Grafico a barre 7 giorni con media settimanale.

Specifiche UI (da design):

• Periodo corrente (es. "14-20 apr") con frecce navigazione
• Grafico barre: barre verdi ≤ obiettivo, rosse > obiettivo
• Asse X: LUN, MAR, MER... (giorno corrente evidenziato)
• Legenda: "In target" (verde), "Eccesso" (rosso)
• Card "RIEPILOGO PRESTAZIONI": media kcal/giorno
• Indicatori: variazione % vs settimana precedente, giorni in target

Criteri Accettazione:

• Grafico a barre con dati reali
• Colori corretti sopra/sotto obiettivo
• Media settimanale calcolata
• Navigazione settimane funzionante
• Tap su barra apre dettaglio giornaliero
• Grafico responsive

---

REQ-010 — Ricerca Pasti

Tipo: EVOLUTIVO | Priorità: MEDIA | Dipende da: REQ-007

Obiettivo: Tab ricerca per trovare pasti passati per testo o intervallo date.

Specifiche:

• Searchbar con debounce 300ms
• Filtro date opzionale (da/a)
• Risultati: data, ora, kcal, descrizione, badge tipo
• Funzione "Ri-registra": crea nuovo pasto con stesse kcal e timestamp corrente
• Ordinamento: data DESC
• Range: ultimi 30 giorni (client-side)

Criteri Accettazione:

• Ricerca per testo funzionante con debounce
• Filtro date funzionante
• Badge tipo visibili
• "Ri-registra" crea nuovo documento
• Empty state "Nessun risultato"

---

REQ-011 — Design Brief Google Stitch

Tipo: REWORK | Priorità: MEDIA

Stato: COMPLETATO — I mockup sono disponibili in stitch_calorietracker_design_brief_brief/

Schermate generate:

1. Home (Journal) — home_calorietracker/
2. Bottom sheet scelta input — scelta_input_calorietracker/
3. Modal input numerico — inserisci_calorie_calorietracker/
4. Modal descrizione LLM — descrizione_ai_calorietracker/
5. Statistiche settimanali — statistiche_calorietracker/

Design System: vitality_pulse/DESIGN.md