App di fitness smart: piano di implementazione in fasi e roadmap di verifica
ArtefattoQuesto è l'artefatto utilizzato nell'episodio 4: Il piano di implementazione delle app no-code. Puoi utilizzare questa roadmap per orchestrare lo sviluppo basato su tappe con verifica a doppio livello e controlli di branch/tag Git.
Accedi per visualizzare questo artefatto
Accedi con il tuo Profilo sviluppatore Google per visualizzare e copiare l'artefatto completo utilizzato nella serie Build It!.
Profilo sviluppatore richiesto
Non hai l'idoneità per un profilo sviluppatore. Chiedi all'amministratore di Workspace di attivare questa funzionalità.
Crea un Profilo sviluppatore
Crea un profilo sviluppatore Google senza costi per sbloccare tutti i prompt e gli artefatti di Build It!
Iscriviti a Builder Central per sbloccare
Richiedi il tuo badge per gli abbonati Builder senza costi con un solo clic per sbloccare tutti i prompt e gli artefatti di Build It!.
Stato: approvato e pronto per l'esecuzione
Pubblico di destinazione: agente sviluppatore AI autonomo e responsabile del progetto umano
Documenti di accompagnamento: Specifica dell'architettura dei dati, Specifica dell'architettura client, Specifica dell'agente di addestramento AI
Riepilogo esecutivo e strategia di esecuzione
Questo piano di implementazione orchestra la creazione completa dell'applicazione Smart Fitness, dagli schemi di base all'idoneità alla produzione.
Il paradigma di esecuzione: basato su milestone con verifica a due livelli
Per bilanciare l'elevata velocità degli agenti con la precisione dell'architettura, questo piano segue un framework di milestone con fasi:
- Esecuzione autonoma all'interno dei milestone: l'agente di implementazione lavora continuamente attraverso i passaggi di ogni milestone, scrivendo codice, eseguendo build, correggendo errori del compilatore e risolvendo autonomamente i problemi senza microgestione umana.
- Verifica di livello 1 - Barriera pre-gate dell'agente autonomo: prima di richiedere l'approvazione umana, l'agente deve eseguire i controlli del compilatore, eseguire gli script di test del backend e lanciare la verifica del browser autonomo Google Antigravity (utilizzando Chrome DevTools) per simulare le interazioni reali degli utenti mobile, eseguire gli scenari di test in inglese semplice, ispezionare lo stato del DOM e acquisire screenshot.
- Verifica di livello 2 - Checkpoint del gatekeeper umano: una volta superati i controlli automatici dell'agente, il gatekeeper umano esamina un elenco di controllo concreto di 2 minuti per verificare l'esperienza utente, l'allineamento aziendale e l'integrità dei dati prima di concedere l'autorizzazione per passare alla fase successiva.
Il protocollo di controllo della versione e tagging Git
Per garantire il disaster recovery, diff di revisione del codice trasparenti e zero errori di composizione tra i milestone, l'agente di implementazione deve osservare rigorosamente il seguente protocollo Git:
- Strategia di branching:
main: branch protetto. Qui vengono unite solo le release dei milestone approvate da persone.- Branch delle funzionalità dei milestone: branch dedicato per milestone (da
feat/m1-scaffolding-typesafeat/m6-pwa-production).
- Cerimonia di commit pre-gate:
git add -A git commit -m "feat(mX): complete milestone X tasks and pre-gate verifications" - Human Gatekeeper Diff Review:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Approvazione del gate e tagging dei traguardi:
git checkout main git merge --no-ff feat/mX-... -m "merge: approve milestone X" git tag -a gate-X-approved -m "Milestone X: Verified and approved by Gatekeeper" - Rollback e disaster recovery:
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
Grafico delle dipendenze dell'architettura principale
M1 [Milestone 1: Foundations, Types & Database Seed] ──> G1 {Gate 1 Sign-Off}
├──> M2 [Milestone 2: Server APIs & Gemini Coach Engine] ──> G2 {Gate 2 Sign-Off}
└──> M3 [Milestone 3: Client State & Gym-Floor Tracker] ──> G3 {Gate 3 Sign-Off}
├──> M4 [Milestone 4: Coach Chat & Staged Proposal Interface] ──> G4 {Gate 4 Sign-Off}
└──> M5 [Milestone 5: Schedule, Analytics & Profile Settings] ──> G5 {Gate 5 Sign-Off}
└──> M6 [Milestone 6: PWA Offline Sync & E2E Validation] ──> G6 {Gate 6: Final Production Acceptance}Traguardo 1: impalcatura del progetto, tipi principali e livello del database
Obiettivo: stabilire le basi del repository, i contratti di dominio TypeScript rigorosi, le connessioni all'SDK Firebase e il seeding dell'enciclopedia degli esercizi statici.
- Attività 1.0: inizializzazione del branch Git - Crea e passa a
feat/m1-scaffolding-types. - Attività 1.1: impalcatura del progetto e configurazione della toolchain - Inizializza Next.js 19 (App Router) con la modalità StrictMode di TypeScript, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, SDK Firebase, SDK Google AI generativa, Recharts e baseline PWA.
- Attività 1.2: definizioni dei tipi di dominio TypeScript canonici - Crea il modulo
src/types/(exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) che corrisponda rigorosamente alla specifica dell'architettura dei dati. - Attività 1.3: configurazione dell'SDK Firebase Client e Admin - Implementa
src/lib/firebase/client.tsesrc/lib/firebase/admin.ts. - Attività 1.4: esercizio sullo script di seeding dell'enciclopedia - Crea
scripts/seed-exercises.tsper eseguire il seeding di/exercisescon slug canonici e metadati. - Attività 1.5: regole e indici di Firestore - Esegui il deployment di
firestore.rulesefirestore.indexes.json.
Verifica di livello 1 e livello 2 (Gate 1): esegui npx tsc --noEmit, npm run lint e npx ts-node scripts/seed-exercises.ts; ispeziona git diff main..HEAD e verifica i documenti Firestore di seed prima di taggare gate-1-approved.
Milestone 2: gestori di route API di backend e pipeline del motore AI
Obiettivo: implementare i gestori delle route del server per la registrazione degli allenamenti e la pipeline di coaching di Gemini AI con memorizzazione nella cache del contesto, gestione della mutazione della memoria e proposte in fasi.
- Attività 2.0: inizializzazione del branch Git - Crea e passa a
feat/m2-backend-apisdamain. - Attività 2.1: helper middleware di autenticazione - Implementa
src/lib/auth/server-auth.tsper verificare i token ID Firebase. - Attività 2.2: endpoint di registrazione dell'allenamento (
POST /api/workouts/log) — Calcola il volume della sessione, applica la formula 1RM di Brzycki, applica l'upsert ai record personali, rendi persistente il log immutabile e contrassegna il giorno programmato comecompleted. - Attività 2.3: memorizzazione nella cache del contesto di Gemini e assemblaggio dinamico dei prompt - Configura
cachedContents.createcon le istruzioni di sistema principali e l'assemblaggio dinamico del contesto di runtime. - Attività 2.4: Endpoint di chat unificato (
POST /api/coach/chat) - Applica l'output dello schema JSON strutturato, la doppia scrittura inweekly_chatse l'isolamento delle mutazioni in fasi. - Task 2.5: Autonomous Memory Mutation Processor — Applica
memory_mutations(CREATE,UPDATE,DELETE) a/users/{userId}/profile/main. - Attività 2.6: Query Tool analitici di sola lettura - Implementa
get_historical_exercise_logs,get_volume_trendseget_pr_records.
Verifica di livello 1 e livello 2 (Gate 2): esegui npx ts-node scripts/test-api-routes.ts, verifica l'isolamento delle mutazioni in fase di staging, controlla la latenza memorizzata nella cache (<2,5 s) e tagga gate-2-approved.
Traguardo 3: infrastruttura dello stato del client e tracker principale della palestra
Obiettivo: creare la shell dell'applicazione, il dock inferiore persistente, l'architettura di stato locale di Zustand e TanStack Query e la visualizzazione di esecuzione ad alto rischio della palestra /workout/active.
- Attività 3.0: inizializzazione del branch Git - Crea e passa a
feat/m3-client-state-trackerdamain. - Attività 3.1: shell dell'applicazione e navigazione persistente - Implementa
<AppContainer />e<BottomNavigationBar />con 5 target di tocco tattili da 48 dp e un pulsante centrale dinamico. - Attività 3.2: gestione dello stato del client e appiattimento del grafo dei passaggi - Implementa
useActiveSessionStore(Zustand +localStorage) e l'algoritmo di appiattimento del grafo dei passaggi. - Attività 3.3: catalogo dei componenti dei blocchi di allenamento riutilizzabili - Implementa
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />e<ModifyWithCoachCard />. - Attività 3.4: visualizzazioni di anteprima dell'allenamento giornaliero - Implementa
DailyWorkoutViewper/todaye/workouts/:day. - Attività 3.5: schermata di esecuzione dell'allenamento attivo (
/workout/active) — Implementa l'intestazione del cronometro,<CurrentSetTargetCard />(UI ottimistica <16 ms),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />e<FinishConfirmationModal />. - Attività 3.6: visualizzazione enciclopedia dei dettagli dell'esercizio (
/exercises/:exerciseId) - Implementa il loop automatico dei<ExerciseVideoPlayer />disattivati, i muscoli target, i passaggi e i suggerimenti per la forma.
Verifica di livello 1 e livello 2 (Gate 3): esegui le suite 1, 2, 5 e 6 nell'area visibile mobile di Chrome DevTools (390 x 844), verifica il ripristino del ricaricamento di localStorage e aggiungi il tag gate-3-approved.
Milestone 4: AI Coach Conversational Hub & Staged Proposal Interface
Obiettivo: implementare l'interfaccia di coaching conversazionale (/coach) con dettatura da voce a testo, suggerimenti di chip di prompt, allegati di banner di contesto e schede di proposta interattive.
- Attività 4.0: inizializzazione del branch Git - Crea e passa a
feat/m4-coach-chatdamain. - Attività 4.1: stato della chat e sincronizzazione in tempo reale - Implementa
useCoachChatStorecon l'abbonamento a FirestoreonSnapshot. - Attività 4.2: layout della visualizzazione della chat con Coach e flusso di messaggi - Implementa
<CoachHeader />,<ChatMessageList />,<ChatBubble />e l'indicatore di caricamento di Coach. - Attività 4.3: allegato di contesto e chip di prompt - Implementa
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />e<SpeechToTextButton />. - Attività 4.4: implementazione della scheda della proposta temporanea - Implementa
<StagedProposalCard />per le differenze diUPDATE_DAYeUPDATE_WEEK. - Attività 4.5: impegno della proposta human-in-the-loop - Esegui il commit di
proposal.datain Firestoreweekly_planssolo quando viene toccato[Accept Plan].
Verifica di livello 1 e livello 2 (Gate 4): esegui la Suite 4 in Chrome DevTools, verifica l'isolamento delle mutazioni in fase di gestione e il commit [Accept Plan] e aggiungi il tag gate-4-approved.
Traguardo 5: revisione della pianificazione, analisi dei progressi e impostazioni del profilo
Obiettivo: completa le visualizzazioni rimanenti dell'applicazione: Programma settimanale (/week), Avanzamento e analisi (/progress) e Profilo/Impostazioni (/settings) con gestione della memoria a 3 livelli.
- Attività 5.0: inizializzazione del branch Git - Crea e passa a
feat/m5-schedule-progress-settingsdamain. - Attività 5.1: visualizzazione della pianificazione settimanale (
/week) - Implementa<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />e<ModifyWeekWithCoachCard />. - Attività 5.2: visualizzazione di Progress & Analytics (
/progress) - Implementa<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />e<WorkoutHistorySection />. - Attività 5.3: Profilo, Impostazioni e visualizzazione Ricordi AI (
/settings) - Implementa<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />e<MemoryTierViewerCard />con l'eliminazione di[🗑].
Verifica di livello 1 e livello 2 (Gate 5): esegui le suite 3, 7 e 8 in Chrome DevTools, verifica i pulsanti di attivazione/disattivazione dei grafici e l'eliminazione della memoria e tagga gate-5-approved.
Traguardo 6: rafforzamento della produzione, buffer offline della PWA e approvazione della matrice completa
Obiettivo: rafforzare l'applicazione per ambienti di palestra reali: configurare la memorizzazione nella cache degli asset PWA offline, implementare la sincronizzazione del log degli allenamenti offline ed eseguire la matrice di verifica completa di 42 test in inglese semplice.
- Attività 6.0: inizializzazione del branch Git - Crea e passa a
feat/m6-pwa-productiondamain. - Attività 6.1: service worker PWA e memorizzazione degli asset nella cache - Finalizza il service worker Serwist/next-pwa e il manifest PWA autonomo.
- Attività 6.2: buffer di sincronizzazione offline di Basement Gym - Implementa la coda offline in IndexedDB/localStorage per
POST /api/workouts/logcon svuotamento automatico della riconnessione. - Attività 6.3: Error Boundaries e visualizzazioni di riserva - Verifica il fallback 404, il fallback per giorno non valido e il fallback per esercizio non valido.
- Attività 6.4: esecuzione della matrice completa e controllo del rendimento - Esegui tutti i 42 scenari di test in linguaggio naturale nelle suite 1-8 ed esegui il controllo di Lighthouse (rendimento >90, LCP <2,5 s, target di tocco ≥48 dp).
Verifica di livello 1 e livello 2 (Gate 6): esegui npm run build, simula la modalità di rete offline in Chrome DevTools, verifica il superamento completo della suite di test 42/42 e tagga v1.0.0.
Riepilogo dei controlli di verifica per il revisore umano
| Cancello | Area di interesse | Branch Git e tag di release | Prodotto finale principale dell'agente | Tempo di verifica umana previsto |
|---|---|---|---|---|
| Gate 1 | Tipi, schema del database e seed | feat/m1-scaffolding-typesTag: gate-1-approved |
src/types/, script di seed eseguito, compilazione pulita |
~2 minuti (ispezione delle differenze e seeding del database) |
| Gate 2 | API di backend e pipeline di Gemini | feat/m2-backend-apisTag: gate-2-approved |
/api/workouts/log, /api/coach/chat, test di integrazione |
~3 minuti (esegui lo script di test dell'API e controlla lo schema) |
| Gate 3 | Stato client e activity tracker | feat/m3-client-state-trackerTag: gate-3-approved |
Shell, /today, /workout/active, test del browser superato |
~3 minuti (tocca i controlli dell'allenamento e testa il cronometro) |
| Gate 4 | Chat con il coach e proposte in fasi | feat/m4-coach-chatTag: gate-4-approved |
/coach, <StagedProposalCard />, commit della proposta |
~3 minuti (chatta con il coach, testa [Accept Plan]) |
| Gate 5 | Programmazione, analisi e impostazioni | feat/m5-schedule-progress-settingsTag: gate-5-approved |
/week, /progress, /settings, gestore della memoria |
~3 minuti (esamina i grafici ed elimina una memoria di test) |
| Gate 6 | Sincronizzazione offline e rilascio completo della PWA | feat/m6-pwa-productionTag: v1.0.0 |
Build di produzione, cache PWA, 42/42 test superati | ~5 minuti (esamina il report finale e il controllo di integrità per dispositivi mobili) |