智能健身应用：分阶段实施计划和验证路线图
宇宙文物这是第 4 集“无代码应用实现计划”中使用的工件。您可以使用此路线图，通过双层验证和 Git 分支/标记门控来协调里程碑驱动的开发。
登录即可访问此制品
使用您的 Google 开发者资料登录，即可查看和复制“Build It!”系列中使用的完整工件。
必须提供开发者资料
您不符合创建开发者资料的条件。请通知您的 Workspace 管理员启用此功能。
创建开发者资料
创建免费的 Google 开发者资料，解锁所有 Build It! 提示和工件。
加入 Builder Central 即可解锁
一键领取免费的 Builder 会员徽章，即可解锁所有 Build It! 提示和工件。
状态：已批准，可执行
目标受众群体：自主 AI 开发者智能体和人类项目负责人
配套文档： 数据架构规范、 客户端架构规范、 AI 训练器智能体规范
摘要和执行策略
此实施计划将协调 Smart Fitness 应用的完整构建过程，从基础架构到正式版发布准备情况。
执行范式：里程碑驱动，双层验证
为了在智能体的高速开发与架构的精确性之间取得平衡，本计划遵循分阶段里程碑框架：
- 里程碑内的自主执行：执行智能体会持续完成每个里程碑的步骤，编写代码、执行构建、修复编译器错误并自行解决问题，无需人工微观管理。
- 第 1 层验证 - 自主智能体预门控屏障：在请求人工签核之前，智能体必须运行编译器检查、执行后端测试脚本，并启动 Google Antigravity 自主浏览器验证（使用 Chrome 开发者工具）来模拟真实的移动用户互动、执行简明英语测试用例、检查 DOM 状态并截取屏幕截图。
- 第 2 层验证 - 人工守门人检查点：智能体通过自动化检查后，人工守门人会根据一份具体的 2 分钟核对清单进行审核，验证用户体验、业务一致性和数据完整性，然后才允许进入下一个里程碑。
版本控制和 Git 标记协议
为确保灾难恢复、透明的代码审核差异以及各里程碑之间零复合错误，执行代理必须严格遵守以下 Git 协议：
- 分支策略：
main：受保护的分支。此处仅合并经过人工批准的里程碑版本。- 里程碑功能分支：每个里程碑（
feat/m1-scaffolding-types到feat/m6-pwa-production）都有专用分支。
- Pre-Gate Commit Ceremony：
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（应用路由器），并配置 TypeScript 严格模式、Tailwind CSS v4、Tailwind Variants、Lucide React、Zustand、TanStack Query、Firebase SDK、Google 生成式 AI SDK、Recharts 和 PWA 基准。
- 任务 1.2：规范 TypeScript 领域类型定义 - 创建严格符合数据架构规范的
src/types/模块（exercise.ts、plan.ts、session.ts、profile.ts、chat.ts、pr.ts）。 - 任务 1.3：Firebase 客户端和 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 层验证（第 1 关）：运行 npx tsc --noEmit、npm run lint 和 npx ts-node scripts/seed-exercises.ts；检查 git diff main..HEAD 并验证已植入的 Firestore 文档，然后再标记 gate-1-approved。
里程碑 2：后端 API 路由处理程序和 AI 引擎流水线
目标：实现用于锻炼记录和 Gemini AI 教练流水线的服务器路由处理程序，并支持上下文缓存、记忆变更处理和分阶段建议。
- 任务 2.0：Git 分支初始化 - 创建
feat/m2-backend-apis并从main切换到该分支。 - 任务 2.1：身份验证中间件辅助程序 - 实现
src/lib/auth/server-auth.ts验证 Firebase ID 令牌。 - 任务 2.2：锻炼记录端点 (
POST /api/workouts/log) - 计算锻炼量、应用 Brzycki 1RM 公式、更新个人记录、保留不可变日志，并将预定日期标记为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 层验证（第 2 关）：运行 npx ts-node scripts/test-api-routes.ts，验证暂存变更隔离，检查缓存延迟时间（<2.5 秒），并标记 gate-2-approved。
里程碑 3：客户端状态基础架构和核心健身房跟踪器
目标：构建应用 Shell、持久性底部停靠栏、本地 Zustand 和 TanStack Query 状态架构，以及高风险的 /workout/active 健身房执行视图。
- 任务 3.0：Git 分支初始化 - 创建
feat/m3-client-state-tracker并从main切换到该分支。 - 任务 3.1：应用 Shell 和常驻导航栏 - 使用 5 个 48dp 的触感点按目标和动态中心按钮实现
<AppContainer />和<BottomNavigationBar />。 - 任务 3.2：客户端状态管理和步骤图扁平化工具 - 实现
useActiveSessionStore（Zustand +localStorage）和步骤图扁平化工具算法。 - 任务 3.3：可重复使用的锻炼块组件目录 - 实现
<WorkoutHeader />、<WorkoutExerciseSummary />、<WorkoutBlock />、<ExerciseCard />、<EmptyDayPlaceholder />和<ModifyWithCoachCard />。 - 任务 3.4：每日锻炼预览视图 - 为
/today和/workouts/:day实现DailyWorkoutView。 - 任务 3.5：活跃锻炼执行界面 (
/workout/active) - 实现秒表标题、<CurrentSetTargetCard />（<16 毫秒乐观界面）、<ActiveRestTimerDock />、<ExerciseSetsTable />、<SwapExerciseModal />和<FinishConfirmationModal />。 - 任务 3.6：锻炼详情百科视图 (
/exercises/:exerciseId) - 实现自动循环播放静音<ExerciseVideoPlayer />、目标肌肉、步骤和姿势提示。
第 1 层和第 2 层验证（第 3 关）：在 Chrome 开发者工具移动设备视口 (390x844) 中执行套件 1、2、5 和 6，验证 localStorage 重新加载恢复，并标记 gate-3-approved。
里程碑 4：AI 教练对话中心和分阶段提案界面
目标：实现对话式辅导界面 (/coach)，其中包含语音转文字听写、提示词条状标签建议、上下文横幅附件和互动式分阶段提案卡片。
- 任务 4.0：Git 分支初始化 - 创建
feat/m4-coach-chat并从main切换到该分支。 - 任务 4.1：聊天状态和实时同步 - 使用 Firestore
onSnapshot订阅实现useCoachChatStore。 - 任务 4.2：教练聊天视图布局和消息流 - 实现
<CoachHeader />、<ChatMessageList />、<ChatBubble />和教练思考旋转图标。 - 任务 4.3：上下文附件和提示词条状标签 - 实现
<ContextBanner />、<ContextualPromptsBar />、<ChatInputBar />和<SpeechToTextButton />。 - 任务 4.4：分阶段提案卡片实现 - 为
UPDATE_DAY和UPDATE_WEEK差异实现<StagedProposalCard />。 - 任务 4.5：人机协同提案提交 - 仅在点按
[Accept Plan]时将proposal.data提交到 Firestoreweekly_plans。
第 1 层和第 2 层验证（第 4 关）：在 Chrome 开发者工具中执行套件 4，验证暂存变更隔离和 [Accept Plan] 提交，并标记 gate-4-approved。
里程碑 5：日程安排大改、进度分析和个人资料设置
目标：完成剩余的应用视图：Week Schedule (/week)、Progress & Analytics (/progress) 和 Profile/Settings (/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：个人资料、设置和 AI 记忆视图 (
/settings) - 实现<UserProfileCard />、<EquipmentSelectorCard />、<PreferencesGroup />和<MemoryTierViewerCard />，并支持[🗑]删除。
第 1 层和第 2 层验证（第 5 关）：在 Chrome 开发者工具中执行套件 3、7 和 8，验证图表切换和记忆删除，并添加 gate-5-approved 标签。
里程碑 6：生产环境安全加固、PWA 离线缓冲区和完整矩阵签核
目标：强化应用以适应真实的健身房环境：配置离线 PWA 资源缓存，实现离线锻炼日志同步，并执行完整的 42 项测试（使用通俗易懂的英语）验证矩阵。
- 任务 6.0：Git 分支初始化 - 创建
feat/m6-pwa-production并从main切换到该分支。 - 任务 6.1：PWA Service Worker 和资源缓存 - 最终确定 Serwist/next-pwa Service Worker 和独立 PWA 清单。
- 任务 6.2：Basement Gym 离线同步缓冲区 - 在 IndexedDB/localStorage 中为
POST /api/workouts/log实现离线队列，并在重新连接时自动刷新。 - 任务 6.3：错误边界和后备视图 - 验证 404 后备、无效日期后备和无效练习后备。
- 任务 6.4：完整矩阵执行和性能审计 - 执行套件 1-8 中的所有 42 个普通英语测试用例，并运行 Lighthouse 审计（性能 >90、LCP <2.5 秒、触摸目标 ≥48dp）。
第 1 层和第 2 层验证（第 6 关）：运行 npm run build，在 Chrome 开发者工具中模拟离线网络模式，验证所有 42 个测试套件是否全部通过，并标记 v1.0.0。
人工 Gatekeeper 验证门控摘要
| 登机口 | 聚焦区域 | Git 分支和版本标记 | 代理的主要交付成果 | 预计人工验证时间 |
|---|---|---|---|---|
| Gate 1 | 类型、数据库架构和种子 | feat/m1-scaffolding-types代码： gate-1-approved |
src/types/，已执行种子脚本，干净编译 |
约 2 分钟（检查差异和种子数据库） |
| Gate 2 | 后端 API 和 Gemini 流水线 | feat/m2-backend-apis代码： gate-2-approved |
/api/workouts/log、/api/coach/chat、集成测试 |
约 3 分钟（运行 API 测试脚本并检查架构） |
| Gate 3 | 客户端状态和活动追踪器 | feat/m3-client-state-tracker代码： gate-3-approved |
Shell、/today、/workout/active、浏览器测试通过 |
约 3 分钟（点按锻炼控件并测试秒表） |
| Gate 4 | Coach Chat 和分阶段提案 | 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 |
正式版 build、PWA 缓存、42/42 项测试通过 | 约 5 分钟（查看最终报告和移动设备健全性检查） |