App de fitness inteligente: plano de implementação em fases e roteiro de verificação
ArtefatoEste é o artefato usado no Episódio 4: O plano de implementação de apps sem código. Use esse roteiro para organizar o desenvolvimento orientado por marcos com verificação de camada dupla e portas de ramificação/tag do Git.
Faça login para acessar este artefato
Faça login com seu Perfil do Desenvolvedor do Google para conferir e copiar o artefato completo usado na série Build It!.
O perfil do desenvolvedor é obrigatório
Você não se qualifica para um perfil de desenvolvedor. Peça para o administrador do Workspace ativar esse recurso.
Criar um perfil de desenvolvedor
Crie um Perfil do Desenvolvedor do Google sem custo financeiro para acessar todos os comandos e artefatos do Build It!
Participe do Builder Central para desbloquear
Resgate seu selo de membro Builder sem custo financeiro com um clique para desbloquear todos os comandos e artefatos do Build It!
Status: aprovado e pronto para execução
Público-alvo: agente de desenvolvimento de IA autônomo e líder de projeto humano
Documentos complementares: Especificação da arquitetura de dados, Especificação da arquitetura do cliente, Especificação do agente de treinamento de IA
Resumo executivo e estratégia de execução
Este plano de implementação organiza a criação completa do aplicativo Smart Fitness, desde os esquemas básicos até a prontidão para produção.
O paradigma de execução: orientado por marcos com verificação em duas camadas
Para equilibrar a alta velocidade do agente com a precisão arquitetônica, este plano segue um Framework de marcos com fases:
- Execução autônoma dentro de marcos: o agente de implementação trabalha continuamente nas etapas de cada marco, escrevendo código, executando builds, corrigindo erros de compilador e resolvendo problemas de autorrecuperação sem microgerenciamento humano.
- Verificação de camada 1 — barreira pré-gate do agente autônomo: antes de solicitar a aprovação humana, o agente precisa executar verificações do compilador, executar scripts de teste de back-end e iniciar a Verificação autônoma do navegador do Google Antigravity (usando o Chrome DevTools) para simular interações reais de usuários de dispositivos móveis, executar os casos de teste em inglês simples, inspecionar o estado do DOM e capturar capturas de tela.
- Verificação de camada 2 — Checkpoint de controle humano: depois que as verificações automatizadas do agente são aprovadas, o controlador humano analisa uma lista de verificação concreta de 2 minutos para verificar a UX, o alinhamento comercial e a integridade de dados antes de conceder permissão para avançar para o próximo marco.
O protocolo de controle de versões e inclusão de tags do Git
Para garantir a recuperação de desastres, diferenças transparentes na revisão de código e zero erros cumulativos entre as etapas, o agente de implementação precisa seguir rigorosamente o seguinte protocolo Git:
- Estratégia de ramificação:
main: ramificação protegida. Somente as versões de marcos aprovadas por humanos são mescladas aqui.- Ramificações de recursos de marcos: ramificação dedicada por marco (
feat/m1-scaffolding-typesafeat/m6-pwa-production).
- Cerimônia de compromisso pré-portão:
git add -A git commit -m "feat(mX): complete milestone X tasks and pre-gate verifications" - Análise de diferenças do Gatekeeper humano:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Aprovação de portão e marcação de marcos:
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" - Reversão e recuperação de desastres:
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
Gráfico de dependência da arquitetura principal
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}Marco 1: scaffolding do projeto, tipos principais e camada de banco de dados
Objetivo: estabelecer a base do repositório, contratos de domínio TypeScript estritos, conexões do SDK do Firebase e preencher a enciclopédia de exercícios estáticos.
- Tarefa 1.0: inicialização da ramificação do Git: crie e mude para
feat/m1-scaffolding-types. - Tarefa 1.1: scaffolding do projeto e configuração do conjunto de ferramentas — Inicialize o Next.js 19 (App Router) com o modo estrito do TypeScript, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, SDKs do Firebase, SDK de IA generativa do Google, Recharts e baseline do PWA.
- Tarefa 1.2: Definições de tipo de domínio canônico do TypeScript — Crie o módulo
src/types/(exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) que corresponda estritamente à especificação da arquitetura de dados. - Tarefa 1.3: configuração do SDK Admin e do cliente do Firebase: implemente
src/lib/firebase/client.tsesrc/lib/firebase/admin.ts. - Tarefa 1.4: script de propagação da enciclopédia de exercícios — Crie
scripts/seed-exercises.tspara propagar/exercisescom slugs canônicos e metadados. - Tarefa 1.5: regras e índices do Firestore: implante
firestore.rulesefirestore.indexes.json.
Verificação da camada 1 e da camada 2 (Gate 1): execute npx tsc --noEmit, npm run lint e npx ts-node scripts/seed-exercises.ts; inspecione git diff main..HEAD e verifique os documentos do Firestore propagados antes de marcar gate-1-approved.
Marco 2: gerenciadores de rotas de API de back-end e pipeline do mecanismo de IA
Objetivo: implementar os gerenciadores de rota do servidor para o registro de treinos e o pipeline de coaching da IA do Gemini com armazenamento em cache de contexto, gerenciamento de mutação de memória e propostas em etapas.
- Tarefa 2.0: inicialização da ramificação do Git: crie e mude para
feat/m2-backend-apisdemain. - Tarefa 2.1: auxiliar de middleware de autenticação: implemente
src/lib/auth/server-auth.tspara verificar os tokens de ID do Firebase. - Tarefa 2.2: endpoint de registro de treino (
POST /api/workouts/log) — Calcular o volume da sessão, aplicar a fórmula de 1RM de Brzycki, fazer upsert de recordes pessoais, persistir o registro imutável e marcar o dia programado comocompleted. - Tarefa 2.3: armazenamento em cache de contexto do Gemini e montagem de comandos dinâmicos: configure o
cachedContents.createcom as instruções principais do sistema e a montagem de contexto de ambiente de execução dinâmico. - Tarefa 2.4: endpoint de chat unificado (
POST /api/coach/chat) — Aplicar a saída de esquema JSON estruturado, gravação dupla emweekly_chatse aplicar o isolamento de mutação em etapas. - Tarefa 2.5: processador de mutação de memória autônoma — aplique
memory_mutations(CREATE,UPDATE,DELETE) a/users/{userId}/profile/main. - Tarefa 2.6: ferramentas de consulta analítica somente leitura — Implemente
get_historical_exercise_logs,get_volume_trendseget_pr_records.
Verificação da camada 1 e da camada 2 (Gate 2): execute npx ts-node scripts/test-api-routes.ts, verifique o isolamento da mutação em fase, verifique a latência em cache (<2,5s) e marque gate-2-approved.
Marco 3: infraestrutura de estado do cliente e rastreador principal de academia
Objetivo: criar o shell do aplicativo, o dock inferior persistente, a arquitetura de estado local do Zustand e do TanStack Query e a visualização de execução de alto risco /workout/active na academia.
- Tarefa 3.0: inicialização da ramificação do Git: crie e mude para
feat/m3-client-state-trackerdemain. - Tarefa 3.1: shell do aplicativo e navegação persistente — Implemente
<AppContainer />e<BottomNavigationBar />com cinco áreas de toque táteis de 48 dp e um botão central dinâmico. - Tarefa 3.2: gerenciamento de estado do cliente e nivelador de gráfico de etapas — Implemente
useActiveSessionStore(Zustand +localStorage) e o algoritmo de nivelador de gráfico de etapas. - Tarefa 3.3: catálogo de componentes reutilizáveis do bloco de treino — Implemente
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />e<ModifyWithCoachCard />. - Tarefa 3.4: visualizações de prévia do treino diário — Implemente
DailyWorkoutViewpara/todaye/workouts/:day. - Tarefa 3.5: tela de execução do treino ativo (
/workout/active) — Implemente o cabeçalho do cronômetro,<CurrentSetTargetCard />(interface otimista de <16 ms),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />e<FinishConfirmationModal />. - Tarefa 3.6: visualização de enciclopédia de detalhes do exercício (
/exercises/:exerciseId) — Implemente o<ExerciseVideoPlayer />silenciado em loop automático, os músculos-alvo, as etapas e as dicas de forma.
Verificação de camada 1 e camada 2 (Gate 3): execute os pacotes 1, 2, 5 e 6 na janela de visualização para dispositivos móveis do Chrome DevTools (390 x 844), verifique a recuperação de recarga de localStorage e marque gate-3-approved.
Marco 4: hub de conversação do coach de IA e interface de proposta em etapas
Objetivo: implementar a interface de coaching de conversação (/coach) com ditado de conversão de voz em texto, recomendações de botões de comando, anexos de banner de contexto e cards de proposta interativos em etapas.
- Tarefa 4.0: inicialização da ramificação do Git: crie e mude para
feat/m4-coach-chatdemain. - Tarefa 4.1: estado do chat e sincronização em tempo real: implemente
useCoachChatStorecom a assinaturaonSnapshotdo Firestore. - Tarefa 4.2: layout da visualização de chat do Coach e fluxo de mensagens — Implemente
<CoachHeader />,<ChatMessageList />,<ChatBubble />e o ícone de carregamento do Coach. - Tarefa 4.3: anexos de contexto e botões de comando — Implemente
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />e<SpeechToTextButton />. - Tarefa 4.4: implementação do card de proposta em etapas — Implemente
<StagedProposalCard />para as diferenças deUPDATE_DAYeUPDATE_WEEK. - Tarefa 4.5: human-in-the-loop de proposta de compromisso — confirme
proposal.datano Firestoreweekly_planssomente quando[Accept Plan]for tocado.
Verificação da camada 1 e da camada 2 (Gate 4): execute o Suite 4 no Chrome DevTools, verifique o isolamento da mutação em fase de teste e o commit de [Accept Plan] e marque gate-4-approved.
Marco 5: reformulação do cronograma, análise de progresso e configurações de perfil
Objetivo: concluir as visualizações restantes do aplicativo: Programação da semana (/week), Progresso e análise (/progress) e Perfil/Configurações (/settings) com gerenciamento de memória em três níveis.
- Tarefa 5.0: inicialização da ramificação do Git: crie e mude para
feat/m5-schedule-progress-settingsdemain. - Tarefa 5.1: visualização da programação semanal (
/week) — Implemente<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />e<ModifyWeekWithCoachCard />. - Tarefa 5.2: visualização de análise e progresso (
/progress) — Implemente<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />e<WorkoutHistorySection />. - Tarefa 5.3: Visualização de perfil, configurações e memória de IA (
/settings) — Implemente<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />e<MemoryTierViewerCard />com exclusão de[🗑].
Verificação da camada 1 e da camada 2 (Gate 5): execute os pacotes 3, 7 e 8 no Chrome DevTools, verifique as alternâncias de gráficos e a exclusão de memória e marque gate-5-approved.
Marco 6: proteção da produção, buffer off-line do PWA e aprovação da matriz completa
Objetivo: reforçar o aplicativo para ambientes reais de academia: configurar o armazenamento em cache de recursos de PWA off-line, implementar a sincronização de registros de treino off-line e executar a matriz de verificação completa de 42 testes em linguagem simples.
- Tarefa 6.0: inicialização da ramificação do Git: crie e mude para
feat/m6-pwa-productiondemain. - Tarefa 6.1: service worker do PWA e armazenamento em cache de recursos: finalize o service worker do Serwist / next-pwa e o manifesto do PWA independente.
- Tarefa 6.2: buffer de sincronização off-line da Basement Gym — Implemente uma fila off-line no IndexedDB/localStorage para
POST /api/workouts/logcom limpeza automática de reconexão. - Tarefa 6.3: limites de erro e visualizações substitutas: verifique o substituto 404, o substituto de dia inválido e o substituto de exercício inválido.
- Tarefa 6.4: execução da matriz completa e auditoria de desempenho: execute todos os 42 casos de teste em linguagem simples nos pacotes de 1 a 8 e faça a auditoria do Lighthouse (desempenho >90, LCP <2,5s, áreas de toque ≥48 dp).
Verificação da camada 1 e da camada 2 (Gate 6): execute npm run build, simule o modo de rede off-line no Chrome DevTools, verifique se o pacote de testes 42/42 foi aprovado e marque v1.0.0.
Resumo das fases de verificação para o gatekeeper humano
| Portão | Área de foco | Ramificação do Git e tag de lançamento | Entrega do agente principal | Tempo esperado para a verificação humana |
|---|---|---|---|---|
| Portão 1 | Tipos, esquema de banco de dados e semente | feat/m1-scaffolding-typesTag: gate-1-approved |
src/types/, script de semente executado, compilação limpa |
~2 minutos (inspecionar as diferenças e o banco de dados propagado) |
| Portão 2 | APIs de back-end e pipeline do Gemini | feat/m2-backend-apisTag: gate-2-approved |
/api/workouts/log, /api/coach/chat, testes de integração |
~3 minutos (executar o script de teste da API e verificar o esquema) |
| Portão 3 | Estado do cliente e monitor fitness ativo | feat/m3-client-state-trackerTag: gate-3-approved |
Shell, /today, /workout/active, teste de navegador aprovado |
~3 minutos (toque nos controles de treino e teste o cronômetro) |
| Portão 4 | Chat do Coach e propostas em etapas | feat/m4-coach-chatTag: gate-4-approved |
/coach, <StagedProposalCard />, compromisso da proposta |
Cerca de 3 minutos (conversa com o coach, teste do [Accept Plan]) |
| Portão 5 | Programação, análise e configurações | feat/m5-schedule-progress-settingsTag: gate-5-approved |
/week, /progress, /settings, gerenciador de memória |
~3 minutos (analisar gráficos e excluir uma memória de teste) |
| Portão 6 | Sincronização off-line e lançamento completo do PWA | feat/m6-pwa-productionTag: v1.0.0 |
Build de produção, cache de PWA, 42/42 testes aprovados | ~5 minutos (revisão do relatório final e verificação de integridade em dispositivos móveis) |