אפליקציית כושר חכמה: תוכנית הטמעה בשלבים ומפת דרכים לאימות
Artifactזהו פריט המידע שנעשה בו שימוש בפרק 4: תוכנית ההטמעה של אפליקציה בלי צורך בתכנות. אתם יכולים להשתמש במפת הדרכים הזו כדי לתזמן פיתוח מבוסס-אבני דרך עם אימות דו-שכבתי ושערי Git של הסתעפויות או תגים.
כדי לגשת לפריט המידע הזה, צריך להיכנס לחשבון
כדי לראות ולהעתיק את קובץ ה-artifact המלא שמשמש בסדרת הסרטונים Build It!, צריך להיכנס לפרופיל המפתח ב-Google.
נדרש פרופיל מפַתח
אין לך אפשרות ליצור פרופיל מפתח. כדי להפעיל את התכונה הזו, צריך לפנות לאדמין ב-Workspace.
יצירת פרופיל מפתח
כדי לקבל גישה לכל ההנחיות והתוצרים של Build It!, צריך ליצור פרופיל מפתח ב-Google בחינם.
מצטרפים ל-Builder Central ומקבלים גישה
בלחיצה אחת אתם יכולים לקבל את תג מועדון החברים בחינם ב-Builder, ולקבל גישה לכל ההנחיות ופריטי המידע של Build It!.
סטטוס: אושר ומוכן לביצוע
קהל יעד: סוכן פיתוח AI אוטונומי ומוביל פרויקט אנושי
מסמכים נלווים: מפרט ארכיטקטורת נתונים, מפרט ארכיטקטורת לקוח, מפרט סוכן מאמן AI
תקציר מנהלים ואסטרטגיית ביצוע
תוכנית ההטמעה הזו מתזמרת את הפיתוח המלא של אפליקציית Smart Fitness, החל מסכימות בסיסיות ועד למוכנות לייצור.
מודל הביצוע: מבוסס-אבני דרך עם אימות דו-שכבתי
כדי לאזן בין מהירות גבוהה של הסוכן לבין דיוק ארכיטקטוני, התוכנית הזו פועלת לפי מסגרת של אבני דרך עם שלבים מוגדרים:
- ביצוע אוטונומי של אבני דרך: הסוכן המטמיע עובד ברציפות על השלבים של כל אבן דרך, כותב קוד, מריץ גרסאות build, מתקן שגיאות קומפילציה ופותר בעיות באופן עצמאי בלי ניהול אנושי קפדני.
- אימות בשכבה 1 – מחסום טרום-שער של סוכן אוטונומי: לפני בקשת אישור אנושי, הסוכן חייב להריץ בדיקות קומפיילר, להפעיל סקריפטים של בדיקות בקצה העורפי ולהפעיל את Google Antigravity Autonomous Browser Verification (באמצעות כלי הפיתוח ל-Chrome) כדי לדמות אינטראקציות אמיתיות של משתמשים בנייד, להפעיל את מקרי הבדיקה באנגלית פשוטה, לבדוק את מצב ה-DOM ולצלם צילומי מסך.
- שכבת אימות 2 – נקודת ביקורת אנושית: אחרי שהסוכן עובר את הבדיקות האוטומטיות, בודק אנושי עובר על רשימת משימות קונקרטית של 2 דקות כדי לאמת את חוויית המשתמש, ההתאמה לעסק ותקינות הנתונים, לפני שהוא נותן אישור להתקדם לאבן הדרך הבאה.
פרוטוקול ניהול הגרסאות והתיוג ב-Git
כדי להבטיח תוכנית התאוששות מאסון (DR), סקרי קוד שקופים והשוואות ואפס שגיאות מצטברות באבני הדרך, הסוכן המטמיע חייב לפעול לפי פרוטוקול 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" - חזרה למצב קודם ותוכנית התאוששות מאסון (DR):
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: הגדרת תבנית הפרויקט ו-toolchain — הפעילו את Next.js 19 (App Router) עם מצב קפדני של TypeScript, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDKs, Google generative AI SDK, Recharts ו-PWA baseline.
- משימה 1.2: הגדרות קנוניות של סוגי דומיינים ב-TypeScript — יוצרים מודול
src/types/(exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) שתואם בדיוק למפרט של ארכיטקטורת הנתונים. - משימה 1.3: הגדרת Firebase Client ו-SDK לאדמינים – מטמיעים את
src/lib/firebase/client.tsו-src/lib/firebase/admin.ts. - משימה 1.4: סקריפט להזנת נתונים באנציקלופדיית התרגילים — יוצרים את
scripts/seed-exercises.tsכדי להזין נתונים ב-/exercisesעם מטא-נתונים וכתובות URL קנוניות. - משימה 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: פונקציות לטיפול בנתיבים של Backend API וצינור עיבוד נתונים של מנוע AI
המטרה: להטמיע את ה-handlers של נתיבי השרת לרישום אימונים ואת צינור עיבוד הנתונים של אימון מבוסס-AI ב-Gemini עם שמירת הקשר במטמון, טיפול בשינויים בזיכרון והצעות בשלבים.
- משימה 2.0: הפעלת הסתעפות Git – יוצרים את
feat/m2-backend-apisועוברים אליה מ-main. - משימה 2.1: עוזר תווכה לאימות — הטמעת
src/lib/auth/server-auth.tsלאימות טוקנים של מזהי Firebase. - משימה 2.2: נקודת קצה לרישום אימונים (
POST /api/workouts/log) — חישוב נפח האימון, שימוש בנוסחת Brzycki 1RM, עדכון או הוספה (upsert) של שיאים אישיים, שמירת יומן שלא ניתן לשינוי וסימון היום המתוזמן כ-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: תשתית למצב הלקוח ומעקב אחר הפעילות בחדר הכושר
המטרה: לפתח את מעטפת האפליקציה (app shell), את ה-dock התחתון הקבוע, את ארכיטקטורת המצב המקומית של Zustand ו-TanStack Query ואת תצוגת הביצועים החשובה של /workout/active רצפת חדר הכושר.
- משימה 3.0: הפעלת הסתעפות Git – יוצרים את
feat/m3-client-state-trackerועוברים אליה מ-main. - משימה 3.1: מעטפת האפליקציה (app shell) וניווט קבוע — מטמיעים את
<AppContainer />ו-<BottomNavigationBar />עם 5 יעדי הקשה בגודל 48dp ולחצן מרכזי דינמי. - משימה 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 בתצוגה של מכשיר נייד (390x844), מאמתים את השחזור של הטעינה מחדש של localStorage ומתייגים את gate-3-approved.
אבן דרך 4: מרכז השיחות של AI Coach וממשק ההצעות המדורגות
המטרה: להטמיע את ממשק האימון בשיחה (/coach) עם הכתבה באמצעות המרת דיבור לטקסט, המלצות להצעות לפרומפט, צירוף באנרים של הקשר וכרטיסי הצעות אינטראקטיביים בשלבים.
- משימה 4.0: הפעלת הסתעפות Git – יוצרים את
feat/m4-coach-chatועוברים אליה מ-main. - משימה 4.1: מצב הצ'אט וסנכרון בזמן אמת — מטמיעים את
useCoachChatStoreעם מינוי ל-FirestoreonSnapshot. - משימה 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): מריצים את Suite 4 בכלי הפיתוח ל-Chrome, מאמתים את הבידוד של המוטציה בשלב הביניים ואת ה-commit של [Accept Plan], ומתייגים את gate-4-approved.
אבן דרך 5: שינוי יסודי של לוח הזמנים, ניתוח ההתקדמות והגדרות הפרופיל
המטרה: להשלים את התצוגות הנותרות של האפליקציה: לוח זמנים שבועי (/week), התקדמות וניתוח נתונים (/progress) ופרופיל/הגדרות (/settings) עם ניהול זיכרון ב-3 רמות.
- משימה 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): מריצים את חבילות הבדיקות 3, 7 ו-8 בכלי הפיתוח ל-Chrome, מאמתים את מתגי התרשימים ואת מחיקת הזיכרון, ומתייגים את gate-5-approved.
אבן דרך 6: הקשחת סביבת הייצור, מאגר נתונים זמני (buffer) במצב אופליין של PWA ואישור מטריצה מלאה
המטרה: להקשיח את האפליקציה לסביבות אמיתיות של חדר כושר: להגדיר שמירת נכסי PWA במטמון אופליין, להטמיע סנכרון של יומן אימונים אופליין ולהפעיל את מטריצת האימות המלאה של 42 בדיקות באנגלית פשוטה.
- משימה 6.0: הפעלת הסתעפות Git — יוצרים את
feat/m6-pwa-productionמ-mainועוברים אליה. - משימה 6.1: קובץ השירות (service worker) של ה-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.5s, יעדי מגע ≥48dp).
אימות שכבה 1 ושכבה 2 (שער 6): מריצים את npm run build, מדמים מצב רשת אופליין בכלי הפיתוח ל-Chrome, מוודאים שכל 42 חבילות המקרים לבדיקה עברו בהצלחה ומתייגים את v1.0.0.
סיכום של שערי האימות לשער אנושי
| שער | אזור ההתמקדות | הסתעפות Git ותג גרסה | התוצר העיקרי של הסוכן | זמן צפוי לאימות בעזרת בודקים אנושיים |
|---|---|---|---|---|
| שער 1 | סוגים, סכימת מסד נתונים וערך בסיס | feat/m1-scaffolding-typesתג: gate-1-approved |
src/types/, סקריפט ה-seed הופעל, הידור נקי |
כ-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 דקות (בדיקת הדוח הסופי ובדיקת תקינות בנייד) |