Ứng dụng theo dõi thể chất thông minh: Kế hoạch triển khai theo giai đoạn và lộ trình xác minh
Tạo tácĐây là cấu phần phần mềm được dùng trong Tập 4: Kế hoạch triển khai ứng dụng không cần lập trình. Bạn có thể sử dụng lộ trình này để điều phối quá trình phát triển theo mốc quan trọng bằng quy trình xác minh hai lớp và cổng nhánh/thẻ Git.
Đăng nhập để truy cập vào dữ liệu này
Đăng nhập bằng Hồ sơ nhà phát triển của Google để xem và sao chép toàn bộ cấu phần phần mềm được dùng trong loạt bài Build It! (Xây dựng).
Bắt buộc phải có Hồ sơ nhà phát triển
Bạn không đủ điều kiện để tạo hồ sơ nhà phát triển. Hãy thông báo cho quản trị viên Workspace của bạn để bật tính năng này.
Tạo hồ sơ nhà phát triển
Tạo Hồ sơ nhà phát triển của Google miễn phí để sử dụng tất cả câu lệnh và cấu phần phần mềm của Build It!
Tham gia Builder Central để mở khoá
Chỉ cần một cú nhấp chuột là bạn có thể nhận huy hiệu hội viên Builder miễn phí để mở khoá tất cả câu lệnh và dữ liệu của Build It!
Trạng thái: Đã phê duyệt và sẵn sàng thực thi
Đối tượng mục tiêu: Tác nhân nhà phát triển AI tự động và Trưởng nhóm dự án là con người
Tài liệu đi kèm: Thông số kỹ thuật về cấu trúc dữ liệu, Thông số kỹ thuật về cấu trúc ứng dụng, Thông số kỹ thuật về tác nhân huấn luyện AI
Tóm tắt chung và chiến lược thực thi
Kế hoạch triển khai này điều phối toàn bộ quá trình xây dựng ứng dụng Smart Fitness, từ giản đồ nền tảng đến mức độ sẵn sàng phát hành công khai.
Mô hình thực thi: Dựa trên mốc quan trọng với quy trình xác minh hai lớp
Để cân bằng giữa tốc độ cao của tác nhân và độ chính xác của cấu trúc, kế hoạch này tuân theo Khung mốc quan trọng theo giai đoạn:
- Thực thi tự động trong các mốc quan trọng: Tác nhân triển khai hoạt động liên tục qua các bước của từng mốc quan trọng, viết mã, thực thi bản dựng, sửa lỗi trình biên dịch và tự khắc phục vấn đề mà không cần con người quản lý vi mô.
- Xác minh lớp 1 — Rào cản trước cổng của tác nhân tự động: Trước khi yêu cầu con người phê duyệt, tác nhân phải chạy quy trình kiểm tra trình biên dịch, thực thi tập lệnh kiểm thử phần phụ trợ và khởi chạy Xác minh trình duyệt tự động Google Antigravity (bằng Chrome DevTools) để mô phỏng hoạt động tương tác thực tế của người dùng thiết bị di động, thực thi các trường hợp kiểm thử bằng tiếng Anh đơn giản, kiểm tra trạng thái DOM và chụp ảnh màn hình.
- Xác minh lớp 2 — Điểm kiểm tra của người giám sát: Sau khi tác nhân vượt qua quy trình kiểm tra tự động, người giám sát sẽ xem xét một danh sách kiểm tra cụ thể trong 2 phút để xác minh trải nghiệm người dùng, mức độ phù hợp với doanh nghiệp và tính toàn vẹn của dữ liệu trước khi cấp quyền chuyển sang mốc tiếp theo.
Giao thức gắn thẻ Git và quản lý phiên bản
Để đảm bảo khả năng khôi phục sau thảm hoạ, sự khác biệt rõ ràng khi xem xét mã và không có lỗi tích luỹ qua các mốc, tác nhân triển khai phải tuân thủ nghiêm ngặt giao thức Git sau:
- Chiến lược phân nhánh:
main: Nhánh được bảo vệ. Chỉ những bản phát hành quan trọng được con người phê duyệt mới được hợp nhất tại đây.- Nhánh tính năng theo mốc quan trọng: Nhánh chuyên biệt cho từng mốc quan trọng (
feat/m1-scaffolding-typesđếnfeat/m6-pwa-production).
- Lễ cam kết trước khi vào cổng:
git add -A git commit -m "feat(mX): complete milestone X tasks and pre-gate verifications" - Đánh giá điểm khác biệt của người kiểm duyệt:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Phê duyệt theo giai đoạn và gắn thẻ mốc quan trọng:
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" - Khôi phục và khắc phục sau thảm hoạ:
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
Biểu đồ phần phụ thuộc của cấu trúc chính
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}Cột mốc 1: Khung dự án, các loại cốt lõi và lớp cơ sở dữ liệu
Mục tiêu: Thiết lập nền tảng kho lưu trữ, hợp đồng miền TypeScript nghiêm ngặt, kết nối Firebase SDK và tạo bách khoa toàn thư về bài tập tĩnh.
- Nhiệm vụ 1.0: Khởi chạy nhánh Git — Tạo và chuyển sang
feat/m1-scaffolding-types. - Nhiệm vụ 1.1: Thiết lập khung dự án và chuỗi công cụ – Khởi chạy Next.js 19 (App Router) với chế độ nghiêm ngặt của TypeScript, Tailwind CSS phiên bản 4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDK, SDK AI tạo sinh của Google, Recharts và PWA cơ bản.
- Nhiệm vụ 1.2: Định nghĩa kiểu miền TypeScript chuẩn — Tạo mô-đun
src/types/(exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) khớp chính xác với Thông số kỹ thuật kiến trúc dữ liệu. - Nhiệm vụ 1.3: Thiết lập SDK ứng dụng và SDK dành cho quản trị viên Firebase — Triển khai
src/lib/firebase/client.tsvàsrc/lib/firebase/admin.ts. - Nhiệm vụ 1.4: Tập lệnh gieo mầm bách khoa toàn thư về bài tập — Tạo
scripts/seed-exercises.tsđể gieo mầm/exercisesbằng các slug chuẩn và siêu dữ liệu. - Nhiệm vụ 1.5: Quy tắc và chỉ mục Firestore — Triển khai
firestore.rulesvàfirestore.indexes.json.
Xác minh Lớp 1 và Lớp 2 (Cổng 1): Chạy npx tsc --noEmit, npm run lint và npx ts-node scripts/seed-exercises.ts; kiểm tra git diff main..HEAD và xác minh các tài liệu Firestore được gieo mầm trước khi gắn thẻ gate-1-approved.
Cột mốc 2: Trình xử lý tuyến API phụ trợ và quy trình của công cụ AI
Mục tiêu: Triển khai trình xử lý tuyến máy chủ để ghi nhật ký bài tập thể dục và quy trình huấn luyện AI của Gemini bằng tính năng lưu vào bộ nhớ đệm ngữ cảnh, xử lý đột biến bộ nhớ và đề xuất theo giai đoạn.
- Nhiệm vụ 2.0: Khởi chạy nhánh Git — Tạo và chuyển sang
feat/m2-backend-apistừmain. - Nhiệm vụ 2.1: Trình trợ giúp phần mềm trung gian xác thực — Triển khai
src/lib/auth/server-auth.tsxác minh mã thông báo Firebase ID. - Nhiệm vụ 2.2: Điểm cuối ghi nhật ký tập luyện (
POST /api/workouts/log) — Tính toán khối lượng buổi tập, áp dụng công thức Brzycki 1RM, cập nhật PR, duy trì nhật ký bất biến và đánh dấu ngày đã lên lịch làcompleted. - Nhiệm vụ 2.3: Lưu vào bộ nhớ đệm ngữ cảnh Gemini và tập hợp câu lệnh động – Thiết lập
cachedContents.createbằng Chỉ dẫn hệ thống chính và tập hợp ngữ cảnh thời gian chạy động. - Nhiệm vụ 2.4: Điểm cuối trò chuyện hợp nhất (
POST /api/coach/chat) — Thực thi kết quả lược đồ JSON có cấu trúc, ghi kép vàoweekly_chatsvà thực thi Cách ly đột biến theo giai đoạn. - Nhiệm vụ 2.5: Bộ xử lý đột biến bộ nhớ tự động — Áp dụng
memory_mutations(CREATE,UPDATE,DELETE) cho/users/{userId}/profile/main. - Nhiệm vụ 2.6: Công cụ truy vấn phân tích chỉ có thể đọc — Triển khai
get_historical_exercise_logs,get_volume_trendsvàget_pr_records.
Xác minh Lớp 1 và Lớp 2 (Cổng 2): Chạy npx ts-node scripts/test-api-routes.ts, xác minh việc tách biệt đột biến theo giai đoạn, kiểm tra độ trễ được lưu vào bộ nhớ đệm (<2,5 giây) và gắn thẻ gate-2-approved.
Cột mốc 3: Cơ sở hạ tầng trạng thái ứng dụng và Trình theo dõi phòng tập cốt lõi
Mục tiêu: Xây dựng giao diện ứng dụng, thanh cố định ở dưới cùng, cấu trúc trạng thái Zustand và TanStack Query cục bộ, cũng như chế độ xem thực thi quan trọng /workout/active tại phòng tập.
- Nhiệm vụ 3.0: Khởi chạy nhánh Git — Tạo và chuyển sang
feat/m3-client-state-trackertừmain. - Nhiệm vụ 3.1: Giao diện ứng dụng và thanh điều hướng cố định — Triển khai
<AppContainer />và<BottomNavigationBar />với 5 mục tiêu nhấn xúc giác 48dp và nút giữa linh động. - Nhiệm vụ 3.2: Quản lý trạng thái ứng dụng và làm phẳng đồ thị bước — Triển khai
useActiveSessionStore(Zustand +localStorage) và thuật toán làm phẳng đồ thị bước. - Nhiệm vụ 3.3: Danh mục thành phần khối tập luyện có thể sử dụng lại – Triển khai
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />và<ModifyWithCoachCard />. - Bài tập 3.4: Chế độ xem trước bài tập hằng ngày — Triển khai
DailyWorkoutViewcho/todayvà/workouts/:day. - Bài tập 3.5: Màn hình thực hiện bài tập đang hoạt động (
/workout/active) — Triển khai tiêu đề đồng hồ bấm giờ,<CurrentSetTargetCard />(giao diện người dùng lạc quan <16 mili giây),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />và<FinishConfirmationModal />. - Bài tập 3.6: Chế độ xem bách khoa toàn thư về chi tiết bài tập (
/exercises/:exerciseId) — Triển khai<ExerciseVideoPlayer />tắt tiếng tự động lặp lại, cơ mục tiêu, các bước và mẹo về tư thế.
Xác minh Lớp 1 và Lớp 2 (Cổng 3): Thực thi Bộ 1, 2, 5 và 6 trong khung nhìn di động của Chrome DevTools (390x844), xác minh khả năng khôi phục khi tải lại localStorage và gắn thẻ gate-3-approved.
Cột mốc 4: Trung tâm trò chuyện của Huấn luyện viên AI và Giao diện đề xuất theo giai đoạn
Mục tiêu: Triển khai giao diện huấn luyện trò chuyện (/coach) có tính năng đọc chính tả chuyển lời nói thành văn bản, đề xuất khối câu lệnh, tệp đính kèm biểu ngữ bối cảnh và thẻ đề xuất theo giai đoạn có tính tương tác.
- Nhiệm vụ 4.0: Khởi chạy nhánh Git — Tạo và chuyển sang
feat/m4-coach-chattừmain. - Nhiệm vụ 4.1: Trạng thái trò chuyện và đồng bộ hoá theo thời gian thực — Triển khai
useCoachChatStorebằng gói thuê bao FirestoreonSnapshot. - Nhiệm vụ 4.2: Bố cục chế độ xem cuộc trò chuyện với huấn luyện viên và luồng tin nhắn – Triển khai
<CoachHeader />,<ChatMessageList />,<ChatBubble />và vòng quay suy nghĩ của huấn luyện viên. - Nhiệm vụ 4.3: Đính kèm bối cảnh và khối câu lệnh – Triển khai
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />và<SpeechToTextButton />. - Nhiệm vụ 4.4: Triển khai thẻ đề xuất theo giai đoạn — Triển khai
<StagedProposalCard />cho các điểm khác biệt củaUPDATE_DAYvàUPDATE_WEEK. - Nhiệm vụ 4.5: Cam kết đề xuất có sự tham gia của con người — Chỉ cam kết
proposal.datavới Firestoreweekly_planskhi người dùng nhấn vào[Accept Plan].
Xác minh Lớp 1 và Lớp 2 (Cổng 4): Thực thi Bộ 4 trong Chrome DevTools, xác minh việc tách biệt đột biến theo giai đoạn và cam kết [Accept Plan], đồng thời gắn thẻ gate-4-approved.
Cột mốc 5: Cải tiến lịch biểu, phân tích tiến trình và cài đặt hồ sơ
Mục tiêu: Hoàn tất các chế độ xem còn lại của ứng dụng: Lịch biểu hằng tuần (/week), Tiến trình và số liệu phân tích (/progress) và Hồ sơ/Cài đặt (/settings) bằng tính năng quản lý bộ nhớ 3 tầng.
- Nhiệm vụ 5.0: Khởi chạy nhánh Git — Tạo và chuyển sang
feat/m5-schedule-progress-settingstừmain. - Nhiệm vụ 5.1: Chế độ xem lịch biểu hằng tuần (
/week) — Triển khai<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />và<ModifyWeekWithCoachCard />. - Nhiệm vụ 5.2: Chế độ xem tiến trình và số liệu phân tích (
/progress) — Triển khai<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />và<WorkoutHistorySection />. - Nhiệm vụ 5.3: Chế độ xem Hồ sơ, Cài đặt và Bộ nhớ AI (
/settings) — Triển khai<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />và<MemoryTierViewerCard />bằng tính năng xoá[🗑].
Xác minh Lớp 1 và Lớp 2 (Cổng 5): Thực thi Bộ 3, 7 và 8 trong Chrome DevTools, xác minh nút bật/tắt biểu đồ và xoá bộ nhớ, đồng thời gắn thẻ gate-5-approved.
Cột mốc 6: Tăng cường bảo mật cho môi trường phát hành công khai, vùng đệm ngoại tuyến của PWA và phê duyệt toàn bộ ma trận
Mục tiêu: Tăng cường ứng dụng cho môi trường phòng tập thực tế: định cấu hình lưu tài sản PWA vào bộ nhớ đệm khi không có mạng, triển khai đồng bộ hoá nhật ký tập luyện khi không có mạng và thực thi ma trận xác minh hoàn chỉnh gồm 42 bài kiểm thử bằng tiếng Anh đơn giản.
- Nhiệm vụ 6.0: Khởi chạy nhánh Git — Tạo và chuyển sang
feat/m6-pwa-productiontừmain. - Nhiệm vụ 6.1: Trình chạy dịch vụ PWA và lưu tài sản vào bộ nhớ đệm – Hoàn tất trình chạy dịch vụ Serwist/next-pwa và tệp kê khai PWA độc lập.
- Nhiệm vụ 6.2: Bộ đệm đồng bộ hoá ngoại tuyến của Basement Gym — Triển khai hàng đợi ngoại tuyến trong IndexedDB/localStorage cho
POST /api/workouts/logbằng tính năng tự động xoá khi kết nối lại. - Nhiệm vụ 6.3: Ranh giới lỗi và chế độ xem dự phòng – Xác minh chế độ dự phòng 404, chế độ dự phòng ngày không hợp lệ và chế độ dự phòng bài tập không hợp lệ.
- Nhiệm vụ 6.4: Thực thi toàn bộ ma trận và kiểm tra hiệu suất — Thực thi tất cả 42 trường hợp kiểm thử bằng tiếng Anh đơn giản trên các Bộ kiểm thử từ 1 đến 8 và chạy quy trình kiểm tra Lighthouse (Hiệu suất > 90, LCP < 2,5 giây, đích chạm ≥ 48 dp).
Xác minh Lớp 1 và Lớp 2 (Cổng 6): Chạy npm run build, mô phỏng chế độ mạng ngoại tuyến trong Chrome DevTools, xác minh rằng tất cả 42/42 bộ kiểm thử đều đạt và gắn thẻ v1.0.0.
Tóm tắt về các cổng xác minh dành cho người kiểm duyệt
| Cổng | Lĩnh vực trọng tâm | Nhánh Git và thẻ phát hành | Sản phẩm chính của tác nhân | Thời gian dự kiến để con người xác minh |
|---|---|---|---|---|
| Cổng 1 | Loại, giản đồ cơ sở dữ liệu và hạt giống | feat/m1-scaffolding-typesThẻ: gate-1-approved |
src/types/, đã thực thi tập lệnh gốc, biên dịch sạch |
~2 phút (kiểm tra sự khác biệt và cơ sở dữ liệu được gieo hạt) |
| Cổng 2 | API phụ trợ và quy trình Gemini | feat/m2-backend-apisThẻ: gate-2-approved |
/api/workouts/log, /api/coach/chat, kiểm thử tích hợp |
~3 phút (chạy tập lệnh kiểm thử API và kiểm tra giản đồ) |
| Cổng 3 | Trạng thái ứng dụng khách và bộ theo dõi hoạt động | feat/m3-client-state-trackerThẻ: gate-3-approved |
Shell, /today, /workout/active, đã vượt qua bài kiểm tra trình duyệt |
~3 phút (nhấn vào các nút điều khiển bài tập và kiểm tra đồng hồ bấm giờ) |
| Cổng 4 | Tính năng trò chuyện với huấn luyện viên và đề xuất theo giai đoạn | feat/m4-coach-chatThẻ: gate-4-approved |
/coach, <StagedProposalCard />, cam kết đề xuất |
~3 phút (trò chuyện với huấn luyện viên, kiểm tra [Accept Plan]) |
| Cổng 5 | Lịch biểu, số liệu phân tích và chế độ cài đặt | feat/m5-schedule-progress-settingsThẻ: gate-5-approved |
/week, /progress, /settings, trình quản lý bộ nhớ |
~3 phút (xem biểu đồ và xoá một kỷ niệm thử nghiệm) |
| Cổng 6 | Đồng bộ hoá ngoại tuyến và phát hành đầy đủ PWA | feat/m6-pwa-productionThẻ: v1.0.0 |
Bản dựng chính thức, bộ nhớ đệm PWA, vượt qua 42/42 bài kiểm thử | ~5 phút (xem báo cáo cuối cùng và kiểm tra tính hợp lý trên thiết bị di động) |