Приложение Smart Fitness: план поэтапного внедрения и дорожная карта проверки
АртефактЭто артефакт, используемый в Эпизоде 4: План реализации приложения без кода. Вы можете использовать эту дорожную карту, чтобы организовать разработку на основе контрольных точек с двухуровневой проверкой и шлюзами ветвей/тегов Git.
Чтобы получить доступ к этому объекту, войдите в аккаунт.
Войдите в профиль разработчика Google, чтобы посмотреть и скопировать полный артефакт, используемый в серии Build It!.
Требуется профиль разработчика
Вы не можете создать профиль разработчика. Попросите администратора Workspace включить эту функцию.
Создать профиль разработчика
Создайте бесплатный профиль разработчика Google, чтобы получить доступ ко всем подсказкам и артефактам Build It!.
Присоединяйтесь к Builder Central, чтобы получить доступ
Получите бесплатный значок участника Builder, чтобы разблокировать все запросы и артефакты Build It!
Статус: одобрено и готово к выполнению.
Целевая аудитория: автономный ИИ-агент разработчика и руководитель проекта.
Сопутствующие документы: спецификация архитектуры данных, спецификация архитектуры клиента, спецификация ИИ-агента тренера.
Основная информация и стратегия реализации
Этот план реализации координирует полную сборку приложения Smart Fitness от базовых схем до готовности рабочей версии.
Парадигма выполнения: на основе этапов с двухслойной проверкой
Чтобы обеспечить высокую скорость работы агента и точность архитектуры, в этом плане используется поэтапная структура контрольных точек:
- Автономное выполнение этапов. Агент непрерывно выполняет шаги каждого этапа, пишет код, запускает сборки, исправляет ошибки компилятора и самостоятельно устраняет проблемы без микроменеджмента со стороны человека.
- Уровень 1. Проверка автономным агентом. Прежде чем запрашивать подтверждение от человека, агент должен выполнить проверку компилятора, запустить сценарии тестирования бэкенда и запустить автономную проверку браузера Google Antigravity (с помощью инструментов разработчика Chrome), чтобы смоделировать реальные взаимодействия мобильных пользователей, выполнить отчеты о тестировании на простом английском языке, проверить состояние DOM и сделать скриншоты.
- Уровень 2. Проверка человеком. После того как агент завершит автоматические проверки, человек-контролер выполняет двухминутную проверку по контрольному списку, чтобы оценить UX, соответствие бизнес-целям и целостность данных, прежде чем разрешить переход к следующему этапу.
Протокол управления версиями и тегами Git
Чтобы обеспечить аварийное восстановление, прозрачные diff-файлы код-ревью и отсутствие составных ошибок на всех этапах, агент реализации должен строго соблюдать следующий протокол Git:
- Стратегия ветвления.
main– защищенная ветвь. Здесь объединяются только одобренные человеком выпуски вех.- Ветви для функций, связанных с вехами. Отдельная ветвь для каждой вехи (от
feat/m1-scaffolding-typesдоfeat/m6-pwa-production).
- Церемония перед воротами:
git add -A git commit -m "feat(mX): complete milestone X tasks and pre-gate verifications" - Проверка изменений человеком:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Одобрение этапов и пометка контрольных точек.
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" - Откат и аварийное восстановление.
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
График зависимости основной архитектуры
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}Этап 1. Создание каркаса проекта, основных типов и уровня базы данных
Цель. Создать основу репозитория, строгие контракты доменов TypeScript, подключения Firebase SDK и заполнить статическую энциклопедию упражнений.
- Задача 1.0. Инициализация ветки Git. Создайте ветку
feat/m1-scaffolding-typesи переключитесь на нее. - Задача 1.1. Создание каркаса проекта и настройка тулчейна. Инициализируйте Next.js 19 (App Router) со строгим режимом TypeScript, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDK, Google generative AI SDK, Recharts и базовым PWA.
- Задача 1.2. Канонические определения типов доменов TypeScript. Создайте модуль
src/types/(exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts), строго соответствующий спецификации архитектуры данных. - Задача 1.3. Настройка Firebase Client и Admin SDK. Реализуйте
src/lib/firebase/client.tsиsrc/lib/firebase/admin.ts. - Задача 1.4. Скрипт для заполнения энциклопедии упражнений. Создайте
scripts/seed-exercises.ts, чтобы заполнить/exercisesканоническими ярлыками и метаданными. - Задача 1.5. Правила и индексы Firestore. Разверните
firestore.rulesиfirestore.indexes.json.
Проверка уровня 1 и уровня 2 (Gate 1). Запустите npx tsc --noEmit, npm run lint и npx ts-node scripts/seed-exercises.ts. Проверьте git diff main..HEAD и документы Firestore, прежде чем добавлять тег gate-1-approved.
Этап 2. Обработчики маршрутов API серверной части и конвейер ИИ-движка
Цель. Реализовать обработчики маршрутов сервера для ведения журнала тренировок и конвейера ИИ-тренера Gemini с кешированием контекста, обработкой изменений памяти и поэтапными предложениями.
- Задача 2.0. Инициализация ветки Git. Создайте ветку
feat/m2-backend-apisи переключитесь на нее из веткиmain. - Задача 2.1. Вспомогательное ПО промежуточного слоя для аутентификации. Реализуйте
src/lib/auth/server-auth.ts, проверяющий идентификационные токены Firebase. - Задача 2.2. Конечная точка для записи тренировок (
POST /api/workouts/log). Вычислите объем тренировки, примените формулу Бржицки для расчета 1ПМ, обновите личные рекорды, сохраните неизменяемый журнал и отметьте запланированный день какcompleted. - Задача 2.3. Кеширование контекста Gemini и динамическая сборка запросов. Настройте
cachedContents.createс основными системными инструкциями и динамической сборкой контекста во время выполнения. - Задача 2.4. Унифицированная конечная точка чата (
POST /api/coach/chat). Обеспечьте вывод структурированной схемы JSON, двойную запись вweekly_chatsи изоляцию поэтапных изменений. - Задача 2.5. Автономный процессор мутации памяти. Примените
memory_mutations(CREATE,UPDATE,DELETE) к/users/{userId}/profile/main. - Задача 2.6. Инструменты запросов только для чтения для аналитики. Реализуйте
get_historical_exercise_logs,get_volume_trendsиget_pr_records.
Проверка уровней 1 и 2 (Gate 2). Запустите npx ts-node scripts/test-api-routes.ts, проверьте изоляцию поэтапных изменений, проверьте задержку кеширования (< 2,5 с) и добавьте тег gate-2-approved.
Этап 3. Инфраструктура состояния клиента и основной трекер Gym-Floor
Цель. Создать оболочку приложения, закрепленную нижнюю панель, локальную архитектуру состояния Zustand и TanStack Query, а также представление /workout/active для выполнения упражнений.
- Задача 3.0. Инициализация ветки Git. Создайте ветку
feat/m3-client-state-trackerи переключитесь на нее из веткиmain. - Задача 3.1. Оболочка приложения и постоянная навигация. Реализуйте
<AppContainer />и<BottomNavigationBar />с пятью тактильными областями нажатия размером 48 dp и динамической центральной кнопкой. - Задача 3.2. Управление состоянием клиента и алгоритм Step-Graph Flattener. Реализуйте
useActiveSessionStore(Zustand +localStorage) и алгоритм Step-Graph Flattener. - Задача 3.3. Каталог компонентов многократно используемых блоков тренировок. Реализуйте
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />и<ModifyWithCoachCard />. - Задача 3.4. Просмотр ежедневных тренировок. Реализуйте
DailyWorkoutViewдля/todayи/workouts/:day. - Задача 3.5. Экран выполнения активной тренировки (
/workout/active). Реализуйте заголовок секундомера,<CurrentSetTargetCard />(оптимистичный интерфейс < 16 мс),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />и<FinishConfirmationModal />. - Задача 3.6. Энциклопедия упражнений (
/exercises/:exerciseId). Добавьте зацикленные видео без звука (<ExerciseVideoPlayer />), целевые мышцы, шаги и советы по технике выполнения.
Проверка уровней 1 и 2 (этап 3). Выполните наборы 1, 2, 5 и 6 в области просмотра инструментов разработчика Chrome для мобильных устройств (390 x 844), проверьте восстановление после перезагрузки localStorage и тег gate-3-approved.
Этап 4. Центр общения с ИИ-тренером и интерфейс для поэтапных предложений
Цель. Реализовать интерфейс разговорного коучинга (/coach) с преобразованием речи в текст, рекомендациями чипов запросов, прикреплением контекстных баннеров и интерактивными карточками поэтапных предложений.
- Задача 4.0. Инициализация ветки Git. Создайте ветку
feat/m4-coach-chatна основеmainи переключитесь на нее. - Задача 4.1. Статус чата и синхронизация в реальном времени. Реализуйте
useCoachChatStoreс подпиской наonSnapshot. - Задача 4.2. Макет чата с тренером и поток сообщений. Реализуйте
<CoachHeader />,<ChatMessageList />,<ChatBubble />и индикатор ожидания ответа тренера. - Задача 4.3. Прикрепление контекста и чипы запросов. Реализуйте
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />и<SpeechToTextButton />. - Задача 4.4. Реализация карточки предложения с поэтапным внедрением. Реализуйте
<StagedProposalCard />для различийUPDATE_DAYиUPDATE_WEEK. - Задача 4.5. Подтверждение предложения с участием человека. Зафиксируйте
proposal.dataв Firestoreweekly_plansтолько после нажатия[Accept Plan].
Проверка уровня 1 и уровня 2 (этап 4). Выполните набор 4 в инструментах разработчика Chrome, проверьте изоляцию поэтапных изменений и фиксацию [Accept Plan], а также тег gate-4-approved.
Этап 5. Обновление расписания, аналитика прогресса и настройки профиля
Цель. Создать оставшиеся представления приложения: "Расписание на неделю" (/week), "Прогресс и аналитика" (/progress) и "Профиль/Настройки" (/settings) с трехуровневым управлением памятью.
- Задача 5.0. Инициализация ветки Git. Создайте ветку
feat/m5-schedule-progress-settingsиз веткиmainи переключитесь на нее. - Задача 5.1. Расписание на неделю (
/week). Реализуйте<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />и<ModifyWeekWithCoachCard />. - Задача 5.2. Просмотр прогресса и аналитики (
/progress) – реализуйте<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />и<WorkoutHistorySection />. - Задача 5.3. Профиль, настройки и раздел воспоминаний ИИ (
/settings). Реализуйте<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />и<MemoryTierViewerCard />с удалением[🗑].
Проверка уровней 1 и 2 (этап 5). Выполните наборы 3, 7 и 8 в инструментах разработчика Chrome, проверьте переключатели диаграмм и удаление памяти, а также отметьте gate-5-approved.
Этап 6. Повышение надежности, офлайн-буфер PWA и полное тестирование
Цель. Подготовить приложение к работе в реальных условиях тренажерного зала: настроить офлайн-кеширование объектов PWA, реализовать офлайн-синхронизацию журнала тренировок и выполнить полную матрицу проверки из 42 тестов на простом английском языке.
- Задача 6.0. Инициализация ветки Git. Создайте ветку
feat/m6-pwa-productionизmainи переключитесь на нее. - Задача 6.1. Сервис-воркер PWA и кеширование объектов. Завершите работу над сервис-воркером Serwist/next-pwa и манифестом отдельного PWA.
- Задача 6.2. Буфер офлайн-синхронизации Basement Gym. Реализуйте офлайн-очередь в IndexedDB/localStorage для
POST /api/workouts/logс автоматической очисткой при повторном подключении. - Задача 6.3. Границы ошибок и резервные представления. Проверьте резервные представления для ошибки 404, недействительного дня и недействительного упражнения.
- Задача 6.4. Полное выполнение матрицы и аудит производительности. Выполните все 42 тестовых сценария на простом английском языке в наборах 1–8 и запустите аудит Lighthouse (производительность >90, LCP <2,5 с, области прикосновения ≥48 dp).
Проверка уровней 1 и 2 (этап 6). Запустите npm run build, смоделируйте режим офлайн-сети в Chrome DevTools, убедитесь, что все 42 теста пройдены, и отметьте v1.0.0.
Сводка по проверкам для специалиста по проверке
| Выход | Область фокуса | Ветвь Git и тег выпуска | Основной результат работы агента | Ожидаемое время проверки специалистом |
|---|---|---|---|---|
| Выход 1 | Типы, схема БД и начальные данные | feat/m1-scaffolding-typesТег: gate-1-approved |
src/types/, скрипт начального заполнения выполнен, компиляция завершена без ошибок |
~2 минуты (проверка различий и заполненной БД) |
| Выход 2 | Серверные API и конвейер Gemini | feat/m2-backend-apisТег: gate-2-approved |
/api/workouts/log, /api/coach/chat, интеграционные тесты |
~3 минуты (запуск тестового скрипта API и проверка схемы) |
| Выход 3 | Состояние клиента и активный трекер физической активности | feat/m3-client-state-trackerТег: gate-3-approved |
Shell, /today, /workout/active, тест браузера пройден |
~3 минуты (нажмите на элементы управления тренировкой и проверьте секундомер) |
| Выход на посадку: 4 | Чат с тренером и поэтапные предложения | feat/m4-coach-chatТег: gate-4-approved |
/coach, <StagedProposalCard />, подтверждение предложения |
~3 минуты (чат с тренером, тест [Accept Plan]) |
| Выход 5 | Расписание, аналитика и настройки | feat/m5-schedule-progress-settingsТег: gate-5-approved |
/week, /progress, /settings, менеджер памяти |
~3 минуты (просмотр диаграмм и удаление тестового воспоминания) |
| Выход 6 | Офлайн-синхронизация и полный выпуск PWA | feat/m6-pwa-productionТег: v1.0.0 |
Рабочая сборка, кеш PWA, 42 из 42 тестов пройдены | ~5 минут (проверка итогового отчета и проверка работоспособности мобильного приложения) |