App de fitness inteligente: Plan de implementación por fases y hoja de ruta de verificación
ArtefactoEste es el artefacto que se usa en el episodio 4: El plan de implementación de apps sin código. Puedes usar esta hoja de ruta para organizar el desarrollo basado en hitos con verificación de doble capa y puertas de rama o etiqueta de Git.
Accede para ver este artefacto
Accede con tu Perfil del desarrollador de Google para ver y copiar el artefacto completo que se usa en la serie Build It!
Se requiere un perfil de desarrollador
No cumples con los requisitos para tener un perfil del desarrollador. Notifica a tu administrador de Workspace para que habilite esta función.
Crear un Perfil del desarrollador
Crea un Perfil del desarrollador de Google gratuito para desbloquear todas las instrucciones y los artefactos de Build It!
Únete a Builder Central para desbloquear
Reclama tu insignia de miembro de Builder sin costo con un solo clic para desbloquear todas las instrucciones y los artefactos de Build It.
Estado: Aprobado y listo para la ejecución
Público objetivo: Agente de desarrollo de IA autónomo y líder de proyecto humano
Documentos complementarios: Especificación de la arquitectura de datos, Especificación de la arquitectura del cliente, Especificación del agente de entrenamiento de IA
Resumen ejecutivo y estrategia de ejecución
Este plan de implementación organiza la compilación completa de la aplicación Smart Fitness, desde los esquemas básicos hasta la preparación para publicar en producción.
El paradigma de ejecución: Basado en hitos con verificación de doble capa
Para equilibrar la alta velocidad de los agentes con la precisión de la arquitectura, este plan sigue un framework de hitos con fases:
- Ejecución autónoma dentro de los hitos: El agente de implementación trabaja de forma continua en los pasos de cada hito, escribiendo código, ejecutando compilaciones, corrigiendo errores del compilador y resolviendo problemas de forma autónoma sin microgestión humana.
- Verificación de capa 1: Barrera previa al punto de control del agente autónomo: Antes de solicitar la aprobación humana, el agente debe ejecutar verificaciones del compilador, ejecutar secuencias de comandos de prueba de backend y lanzar la verificación autónoma del navegador de Google Antigravity (con las Herramientas para desarrolladores de Chrome) para simular interacciones reales de usuarios de dispositivos móviles, ejecutar los casos de prueba en lenguaje natural, inspeccionar el estado del DOM y capturar capturas de pantalla.
- Verificación de capa 2: Punto de control de guardián de acceso humano: Una vez que se aprueban las verificaciones automatizadas del agente, el guardián de acceso humano revisa una lista de verificación concreta de 2 minutos para verificar la UX, la alineación empresarial y la integridad de los datos antes de otorgar el permiso para avanzar al siguiente hito.
Protocolo de control de versiones y etiquetado de Git
Para garantizar la recuperación ante desastres, las diferencias transparentes en la revisión de código y cero errores acumulativos en los hitos, el agente de implementación debe seguir estrictamente el siguiente protocolo de Git:
- Estrategia de ramificación:
main: Es la rama protegida. Aquí solo se combinan las versiones de hitos aprobadas por humanos.- Ramas de funciones de hitos: Rama dedicada por hito (de
feat/m1-scaffolding-typesafeat/m6-pwa-production).
- Ceremonia de confirmación previa a la puerta de enlace:
git add -A git commit -m "feat(mX): complete milestone X tasks and pre-gate verifications" - Revisión de diferencias de Human Gatekeeper:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Aprobación de fases y etiquetado de hitos:
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" - Reversión y recuperación ante desastres:
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
Gráfico de dependencias de la arquitectura 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}Hito 1: Estructura del proyecto, tipos principales y capa de base de datos
Objetivo: Establecer la base del repositorio, los contratos de dominio estrictos de TypeScript y las conexiones del SDK de Firebase, y propagar la enciclopedia de ejercicios estáticos.
- Tarea 1.0: Inicialización de la rama de Git: Crea
feat/m1-scaffolding-typesy cambia a ella. - Tarea 1.1: Configuración de la estructura del proyecto y la cadena de herramientas — Inicializa Next.js 19 (App Router) con el modo estricto de TypeScript, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, los SDKs de Firebase, el SDK de IA generativa de Google, Recharts y la base de PWA.
- Tarea 1.2: Definiciones de tipos de dominio canónicos de TypeScript — Crea el módulo
src/types/(exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) que coincida estrictamente con la especificación de la arquitectura de datos. - Tarea 1.3: Configuración del SDK de cliente y administrador de Firebase: Implementa
src/lib/firebase/client.tsysrc/lib/firebase/admin.ts. - Tarea 1.4: Ejecuta la secuencia de comandos de propagación de la enciclopedia de ejercicios: Crea
scripts/seed-exercises.tspara propagar/exercisescon slugs canónicos y metadatos. - Tarea 1.5: Reglas e índices de Firestore: Implementa
firestore.rulesyfirestore.indexes.json.
Verificación de capa 1 y capa 2 (puerta 1): Ejecuta npx tsc --noEmit, npm run lint y npx ts-node scripts/seed-exercises.ts; inspecciona git diff main..HEAD y verifica los documentos de Firestore propagados antes de etiquetar gate-1-approved.
Hito 2: Controladores de rutas de la API de backend y canalización del motor de IA
Objetivo: Implementar los controladores de rutas del servidor para el registro de entrenamientos y la canalización de entrenamiento de la IA de Gemini con almacenamiento en caché de contexto, control de mutaciones de memoria y propuestas por etapas.
- Tarea 2.0: Inicialización de la rama de Git: Crea
feat/m2-backend-apisdesdemainy cambia a ella. - Tarea 2.1: Middleware de autenticación auxiliar: Implementa
src/lib/auth/server-auth.tspara verificar los tokens de ID de Firebase. - Tarea 2.2: Extremo de registro de entrenamiento (
POST /api/workouts/log) — Calcula el volumen de la sesión, aplica la fórmula de 1RM de Brzycki, actualiza o inserta los PR, conserva el registro inmutable y marca el día programado comocompleted. - Tarea 2.3: Almacenamiento en caché de contexto de Gemini y ensamblaje de instrucciones dinámicas: Configura
cachedContents.createcon instrucciones del sistema principales y ensamblaje de contexto de entorno de ejecución dinámico. - Tarea 2.4: Extremo de chat unificado (
POST /api/coach/chat) — Aplica el resultado del esquema JSON estructurado, realiza una escritura doble enweekly_chatsy aplica el aislamiento de mutaciones en etapas. - Tarea 2.5: Procesador de mutación de memoria autónomo: Aplica
memory_mutations(CREATE,UPDATE,DELETE) a/users/{userId}/profile/main. - Tarea 2.6: Herramientas de consulta analítica de solo lectura: Implementa
get_historical_exercise_logs,get_volume_trendsyget_pr_records.
Verificación de capa 1 y capa 2 (puerta 2): Ejecuta npx ts-node scripts/test-api-routes.ts, verifica el aislamiento de mutaciones en etapa de pruebas, comprueba la latencia almacenada en caché (<2.5 s) y etiqueta gate-2-approved.
Hito 3: Infraestructura de estado del cliente y seguimiento principal de la sala de entrenamiento
Objetivo: Compilar la shell de la aplicación, el panel inferior persistente, la arquitectura de estado local de Zustand y TanStack Query, y la vista de ejecución de alta importancia de /workout/active en el gimnasio.
- Tarea 3.0: Inicialización de la rama de Git: Crea
feat/m3-client-state-trackery cambia a ella desdemain. - Tarea 3.1: Shell de la aplicación y navegación persistente: Implementa
<AppContainer />y<BottomNavigationBar />con 5 objetivos táctiles de 48 dp y un botón central dinámico. - Tarea 3.2: Administración del estado del cliente y aplanador de gráficos de pasos: Implementa
useActiveSessionStore(Zustand +localStorage) y el algoritmo de aplanador de gráficos de pasos. - Tarea 3.3: Catálogo de componentes de bloques de entrenamiento reutilizables: Implementa
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />y<ModifyWithCoachCard />. - Tarea 3.4: Vistas previas de entrenamientos diarios: Implementa
DailyWorkoutViewpara/todayy/workouts/:day. - Tarea 3.5: Pantalla de ejecución de entrenamiento activo (
/workout/active) — Implementa el encabezado del cronómetro,<CurrentSetTargetCard />(IU optimista de <16 ms),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />y<FinishConfirmationModal />. - Tarea 3.6: Vista de enciclopedia de detalles del ejercicio (
/exercises/:exerciseId): Implementa un<ExerciseVideoPlayer />silenciado que se repita automáticamente, músculos objetivo, pasos y sugerencias de postura.
Verificación de la capa 1 y la capa 2 (puerta 3): Ejecuta los conjuntos 1, 2, 5 y 6 en el viewport para dispositivos móviles de las Herramientas para desarrolladores de Chrome (390 x 844), verifica la recuperación de la recarga de localStorage y etiqueta gate-3-approved.
Hito 4: Centro de conversación del coach potenciado por IA y la interfaz de propuesta por etapas
Objetivo: Implementar la interfaz de asesoramiento conversacional (/coach) con dictado de voz a texto, recomendaciones de chips de instrucciones, archivos adjuntos de banners de contexto y tarjetas de propuestas por etapas interactivas.
- Tarea 4.0: Inicialización de la rama de Git: Crea
feat/m4-coach-chaty cambia a ella desdemain. - Tarea 4.1: Estado del chat y sincronización en tiempo real: Implementa
useCoachChatStorecon la suscripción aonSnapshotde Firestore. - Tarea 4.2: Diseño de la vista de chat del entrenador y flujo de mensajes: Implementa
<CoachHeader />,<ChatMessageList />,<ChatBubble />y el ícono giratorio de pensamiento del entrenador. - Tarea 4.3: Adjunto de contexto y chips de instrucciones: Implementa
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />y<SpeechToTextButton />. - Tarea 4.4: Implementación de la tarjeta de propuesta por etapas: Implementa
<StagedProposalCard />para las diferencias deUPDATE_DAYyUPDATE_WEEK. - Tarea 4.5: Compromiso de propuesta con intervención humana: Confirma
proposal.dataen Firestoreweekly_planssolo cuando se presione[Accept Plan].
Verificación de la capa 1 y la capa 2 (puerta 4): Ejecuta el paquete 4 en las Herramientas para desarrolladores de Chrome, verifica el aislamiento de mutaciones en etapa de pruebas y la confirmación de [Accept Plan], y etiqueta gate-4-approved.
Hito 5: Renovación de la programación, estadísticas de progreso y configuración del perfil
Objetivo: Completar las vistas restantes de la aplicación: Week Schedule (/week), Progress & Analytics (/progress) y Profile/Settings (/settings) con administración de la memoria de 3 niveles.
- Tarea 5.0: Inicialización de la rama de Git: Crea
feat/m5-schedule-progress-settingsdesdemainy cambia a ella. - Tarea 5.1: Vista de programación semanal (
/week): Implementa<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />y<ModifyWeekWithCoachCard />. - Tarea 5.2: Vista de análisis y estadísticas (
/progress) — Implementa<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />y<WorkoutHistorySection />. - Tarea 5.3: Vista de perfil, configuración y memoria de IA (
/settings) — Implementa<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />y<MemoryTierViewerCard />con eliminación de[🗑].
Verificación de la capa 1 y la capa 2 (puerta 5): Ejecuta los conjuntos 3, 7 y 8 en las Herramientas para desarrolladores de Chrome, verifica los botones de activación de gráficos y la eliminación de memoria, y etiqueta a gate-5-approved.
Hito 6: Refuerzo de la producción, búfer sin conexión de la AWP y aprobación de la matriz completa
Objetivo: Reforzar la aplicación para entornos de gimnasio reales: configurar el almacenamiento en caché de recursos de AWP sin conexión, implementar la sincronización de registros de entrenamiento sin conexión y ejecutar la matriz de verificación completa de 42 pruebas en lenguaje natural.
- Tarea 6.0: Inicialización de la rama de Git: Crea
feat/m6-pwa-productiondesdemainy cambia a ella. - Tarea 6.1: Service worker de AWP y almacenamiento en caché de recursos — Finaliza el service worker de Serwist/next-pwa y el manifiesto de AWP independiente.
- Tarea 6.2: Almacenamiento en búfer de sincronización sin conexión de Basement Gym: Implementa una cola sin conexión en IndexedDB/localStorage para
POST /api/workouts/logcon vaciado automático de reconexión. - Tarea 6.3: Límites de errores y vistas de resguardo: Verifica el resguardo 404, el resguardo de día no válido y el resguardo de ejercicio no válido.
- Tarea 6.4: Ejecución de la matriz completa y auditoría de rendimiento: Ejecuta los 42 casos de prueba en lenguaje natural en los paquetes del 1 al 8 y ejecuta la auditoría de Lighthouse (rendimiento >90, LCP <2.5 s, objetivos táctiles ≥48 dp).
Verificación de capa 1 y capa 2 (puerta 6): Ejecuta npm run build, simula el modo de red sin conexión en las Herramientas para desarrolladores de Chrome, verifica que se apruebe el paquete de pruebas completo de 42/42 y etiqueta v1.0.0.
Resumen de los puntos de control de verificación para el responsable de aprobación humano
| Puerta | Área de enfoque | Rama de Git y etiqueta de versión | Entregable clave del agente | Tiempo esperado de verificación humana |
|---|---|---|---|---|
| Puerta 1 | Tipos, esquema de base de datos y semilla | feat/m1-scaffolding-typesEtiqueta: gate-1-approved |
src/types/, se ejecutó la secuencia de comandos de origen, compilación limpia |
~2 minutos (inspeccionar la diferencia y la base de datos propagada) |
| Puerta 2 | APIs de backend y canalización de Gemini | feat/m2-backend-apisEtiqueta: gate-2-approved |
/api/workouts/log, /api/coach/chat, pruebas de integración |
~3 minutos (ejecutar la secuencia de comandos de prueba de la API y verificar el esquema) |
| Puerta 3 | Estado del cliente y monitor de actividad | feat/m3-client-state-trackerEtiqueta: gate-3-approved |
Shell, /today, /workout/active, se aprobó la prueba del navegador |
~3 minutos (presiona los controles de entrenamiento y prueba el cronómetro) |
| Puerta 4 | Chat de Coach y propuestas por etapas | feat/m4-coach-chatEtiqueta: gate-4-approved |
/coach, <StagedProposalCard />, confirmación de la propuesta |
~3 minutos (chatear con el entrenador, probar [Accept Plan]) |
| Puerta 5 | Programación, estadísticas y configuración | feat/m5-schedule-progress-settingsEtiqueta: gate-5-approved |
/week, /progress, /settings, administrador de memoria |
~3 minutos (revisar gráficos y borrar una memoria de prueba) |
| Puerta 6 | Sincronización sin conexión y lanzamiento completo de la PWA | feat/m6-pwa-productionEtiqueta: v1.0.0 |
Compilación de producción, caché de PWA, 42 de 42 pruebas aprobadas | ~5 minutos (revisar el informe final y realizar una verificación de estado en dispositivos móviles) |