智慧健身應用程式：分階段實作計畫和驗證藍圖
Artifact這是第 4 集「無程式碼應用程式導入計畫」使用的構件。您可以運用這份藍圖，透過雙層驗證和 Git 分支/標記閘道，安排以里程碑為導向的開發作業。
登入即可存取這個構件
登入 Google 開發人員個人檔案，即可查看及複製「Build It!」系列中使用的完整構件。
須具備開發人員設定檔
您不符合建立開發人員設定檔的資格。請通知 Workspace 管理員啟用這項功能。
建立開發人員設定檔
免費建立 Google 開發人員個人檔案，即可解鎖所有 Build It! 提示和構件。
加入 Builder Central 即可解鎖
一鍵領取免費的 Builder 會員徽章，即可解鎖所有 Build It! 提示和構件。
狀態：已核准，可執行
目標對象：自主 AI 開發人員代理和人類專案負責人
隨附文件： 資料架構規格、 用戶端架構規格、 AI 訓練代理規格
內容提要和執行策略
這項實作計畫會協調整個 Smart Fitness 應用程式的建構作業，從基礎結構定義到正式版完備性。
執行模式：以里程碑為導向，並採用雙層驗證
為兼顧代理的高速運作和架構精確度，這項計畫採用階段式里程碑架構：
- 在里程碑內自主執行：執行代理會持續執行每個里程碑的步驟，包括編寫程式碼、執行建構作業、修正編譯器錯誤，以及自我修復問題，不需人為微觀管理。
- 第 1 層驗證 - 代理自主預先檢查：代理必須先執行編譯器檢查、後端測試指令碼，以及 Google Antigravity Autonomous Browser Verification (使用 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 - Gate Approval & Milestone Tagging：
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 生成式 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 層驗證 (閘道 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：客戶狀態基礎架構和核心健身房追蹤工具
目標：建構應用程式殼層、永久底部停駐區、本機 Zustand 和 TanStack Query 狀態架構，以及高風險的 /workout/active 健身房執行檢視畫面。
- 工作 3.0：Git 分支版本初始化 - 建立
feat/m3-client-state-tracker並從main切換至該分支版本。 - 工作 3.1：應用程式殼層和永久導覽：使用 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：Active Workout Execution 畫面 (
/workout/active)：實作碼錶標頭、<CurrentSetTargetCard />(樂觀 UI <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：Coach 對話檢視畫面版面配置和訊息串流 - 實作
<CoachHeader />、<ChatMessageList />、<ChatBubble />和 Coach 思考中旋轉圖示。 - 工作 4.3：內容附件和提示詞方塊 - 實作
<ContextBanner />、<ContextualPromptsBar />、<ChatInputBar />和<SpeechToTextButton />。 - 工作 4.4：實作分階段提案資訊卡：實作
<StagedProposalCard />，用於UPDATE_DAY和UPDATE_WEEK差異。 - 工作 4.5：人工介入迴路提案提交：只有在輕觸
[Accept Plan]時，才將proposal.data提交至 Firestoreweekly_plans。
第 1 層和第 2 層驗證 (閘道 4)：在 Chrome 開發人員工具中執行測試套件 4，驗證暫存變異隔離和 [Accept Plan] 提交，以及標記 gate-4-approved。
里程碑 5：時間表大翻修、進度分析和個人資料設定
目標：使用 3 層記憶體管理，完成其餘的應用程式檢視畫面：本週時間表 (/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：個人資料、設定和 AI 記憶檢視畫面 (
/settings)：實作<UserProfileCard />、<EquipmentSelectorCard />、<PreferencesGroup />和<MemoryTierViewerCard />，並提供[🗑]刪除功能。
第 1 層和第 2 層驗證 (Gate 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 層驗證 (Gate 6)：執行 npm run build，在 Chrome 開發人員工具中模擬離線網路模式，確認 42/42 測試套件全部通過，並標記 v1.0.0。
人工守門員驗證關卡摘要
| 門型摺 | 重點雕塑部位 | 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 |
殼層、/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 分鐘 (查看圖表並刪除測試記憶體) |
| Gate 6 | PWA 離線同步和完整版本 | feat/m6-pwa-production標記： v1.0.0 |
正式版本、PWA 快取、42/42 項測試通過 | 約 5 分鐘 (查看最終報告和行動裝置健全狀態檢查) |