تطبيق اللياقة البدنية الذكي: خطة التنفيذ على مراحل وخريطة طريق التحقّق
القطع الأثريةهذا هو النموذج المستخدَم في الحلقة 4: خطة تنفيذ التطبيق بدون استخدام رمز برمجي. يمكنك استخدام هذه الخطة لتنظيم عملية التطوير المستندة إلى المراحل الرئيسية من خلال التحقّق من الطبقة المزدوجة وبوابات Git branch/tag.
يجب تسجيل الدخول للوصول إلى هذا العنصر
سجِّل الدخول باستخدام ملفك الشخصي للمطوّر على Google لعرض ونسخ العنصر الكامل المستخدَم في سلسلة Build It!.
يجب تحديد ملف شخصي للمطوّر
لست مؤهلاً لإنشاء ملف شخصي للمطوّر. يُرجى إبلاغ مشرف Workspace بتفعيل هذه الميزة.
إنشاء ملف شخصي كمطوّر
أنشئ ملفًا شخصيًا مجانيًا للمطوّر على Google للاستفادة من جميع الطلبات والمواد في Build It!.
انضم إلى Builder Central للاستفادة من الميزات
يمكنك الحصول على شارة عضوية Builder المجانية بنقرة واحدة للاستفادة من جميع الطلبات والمواد في Build It!.
الحالة: تمت الموافقة وجاهز للتنفيذ
الجمهور المستهدف: وكيل مطوّر الذكاء الاصطناعي المستقل ورئيس المشروع البشري
المستندات المصاحبة: مواصفات بنية البيانات، مواصفات بنية العميل، مواصفات وكيل مدرّب الذكاء الاصطناعي
الملخّص التنفيذي واستراتيجية التنفيذ
تنسّق خطة التنفيذ هذه عملية إنشاء تطبيق Smart Fitness بالكامل، بدءًا من المخططات الأساسية وحتى الجاهزية لإصدار التطبيق.
نموذج التنفيذ: قائم على الإنجازات مع التحقّق من طبقتين
لتحقيق التوازن بين سرعة الوكيل العالية والدقة البنيوية، تتّبع هذه الخطة إطار عمل المراحل الرئيسية المقسّمة إلى مراحل:
- التنفيذ المستقل ضمن المراحل الرئيسية: يعمل وكيل التنفيذ بشكل مستمر خلال خطوات كل مرحلة رئيسية، ويكتب الرموز البرمجية، وينفّذ عمليات الإنشاء، ويصلح أخطاء برنامج التجميع، ويعالج المشاكل ذاتيًا بدون تدخّل بشري دقيق.
- الطبقة الأولى من التحقّق: حاجز ما قبل البوابة للوكيل المستقل: قبل طلب موافقة المراجعين، على الوكيل إجراء عمليات تحقّق من برنامج التجميع، وتنفيذ نصوص برمجية لاختبار الخلفية، وتشغيل Google Antigravity Autonomous Browser Verification (باستخدام "أدوات مطوري البرامج في Chrome") لمحاكاة تفاعلات المستخدمين الحقيقية على الأجهزة الجوّالة، وتنفيذ إطارات الاختبار باللغة الإنجليزية البسيطة، وفحص حالة نموذج العناصر في المستند (DOM)، والتقاط لقطات شاشة.
- الطبقة الثانية من التحقّق: نقطة تفتيش حارس البوابة البشري: بعد اجتياز الوكيل لعمليات التحقّق الآلية، يراجع حارس البوابة البشري قائمة تحقّق ملموسة مدتها دقيقتان للتحقّق من تجربة المستخدم، والتوافق مع النشاط التجاري، وصحة البيانات قبل منح الإذن بالانتقال إلى المرحلة التالية.
التحكّم في الإصدارات وبروتوكول Git Tagging
لضمان التعافي من الكوارث، ومراجعة الرمز البرمجي بشفافية، واختلافات الرمز البرمجي، وعدم تراكم الأخطاء عبر المراحل الرئيسية، يجب على وكيل التنفيذ الالتزام الصارم ببروتوكول Git التالي:
- استراتيجية التفريع:
main: فرع محمي Only human-approved milestone releases are merged here.- فروع الميزات الرئيسية: فرع مخصّص لكل ميزة رئيسية (من
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 (App Router) مع وضع التدقيق الصارم في TypeScript وTailwind CSS v4 وTailwind Variants وLucide React وZustand وTanStack Query وFirebase SDKs وحزمة تطوير البرامج (SDK) للذكاء الاصطناعي التوليدي من Google وRecharts والحد الأدنى لتطبيق الويب التقدّمي (PWA).
- المهمة 1.2: تعريفات أنواع النطاقات الأساسية في TypeScript: أنشئ وحدة
src/types/(exercise.tsوplan.tsوsession.tsوprofile.tsوchat.tsوpr.ts) تتطابق تمامًا مع مواصفات بنية البيانات. - المهمة 1.3: إعداد حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase وعميله: نفِّذ
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: معالِجات مسارات واجهة برمجة التطبيقات للواجهة الخلفية ومسار معالجة محرّك الذكاء الاصطناعي
الهدف: تنفيذ معالِجات مسارات الخادم لتسجيل التمارين ومسار التدريب بالذكاء الاصطناعي من 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، وتحديث الأرقام القياسية الشخصية، والاحتفاظ بسجلّ غير قابل للتغيير، ووضع علامة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: هيكل التطبيق والتنقّل المستمر: نفِّذ
<AppContainer />و<BottomNavigationBar />باستخدام 5 أهداف نقر ملموسة بحجم 48 بكسل مستقل الكثافة وزر مركزي ديناميكي. - المهمة 3.2: إدارة حالة العميل وأداة تسوية الرسم البياني للخطوات: تنفيذ
useActiveSessionStore(Zustand وlocalStorage) وخوارزمية أداة تسوية الرسم البياني للخطوات. - المهمة 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×844)، وتحقَّق من استرداد البيانات بعد إعادة تحميل localStorage، وضَع علامة على gate-3-approved.
المرحلة الرابعة: مركز المحادثات في المدرّب بالذكاء الاصطناعي وواجهة الاقتراحات المرحلية
الهدف: تنفيذ واجهة التدريب الحواري (/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): نفِّذ المجموعة 4 في "أدوات مطوّري البرامج في Chrome"، وتحقَّق من عزل التغييرات المرحلية و[Accept Plan]، وأضِف العلامة gate-4-approved.
المرحلة الخامسة: إصلاح الجدول الزمني وتحليلات مستوى التقدّم وإعدادات الملف الشخصي
الهدف: إكمال طرق العرض المتبقية في التطبيق: "الجدول الأسبوعي" (/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: الملف الشخصي والإعدادات وعرض ذاكرة الذكاء الاصطناعي (
/settings): تنفيذ<UserProfileCard />و<EquipmentSelectorCard />و<PreferencesGroup />و<MemoryTierViewerCard />مع حذف[🗑].
التحقّق من الطبقة 1 والطبقة 2 (البوابة 5): نفِّذ المجموعات 3 و7 و8 في "أدوات مطوّري البرامج في Chrome"، وتحقَّق من مفاتيح تبديل الرسم البياني وحذف الذاكرة، وأضِف علامة gate-5-approved.
الإنجاز 6: تعزيز الإنتاج، والتخزين المؤقت في وضع عدم الاتصال لتطبيقات الويب التقدّمية، والموافقة على المصفوفة الكاملة
الهدف: تعزيز التطبيق لبيئات الصالات الرياضية الحقيقية: ضبط التخزين المؤقت لمواد عرض تطبيق الويب التقدّمي بلا إنترنت، وتنفيذ مزامنة سجلّ التمارين بلا إنترنت، وتنفيذ مصفوفة التحقّق الكاملة المكوّنة من 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 بكسل مستقل الكثافة).
التحقّق من الطبقة 1 والطبقة 2 (البوابة 6): شغِّل npm run build، وحاكِ وضع الشبكة بلا إنترنت في "أدوات مطوّري البرامج في Chrome"، وتأكَّد من اجتياز الحزمة الاختبارية الكاملة التي تتضمّن 42 اختبارًا، وأضِف علامة v1.0.0.
ملخّص حول إجراءات التحقّق من الهوية التي يتّخذها الموظّف المسؤول عن التحقّق
| بوابة | منطقة التركيز | فرع Git وعلامة الإصدار | المنجزات المستهدفة الرئيسية للوكيل | الوقت المتوقّع للتحقّق من المحتوى من قِبل المراجعين |
|---|---|---|---|---|
| البوابة 1 | الأنواع ومخطط قاعدة البيانات والقيمة الأساسية | feat/m1-scaffolding-typesالعلامة: gate-1-approved |
src/types/، تم تنفيذ النص البرمجي الأولي، وتم تجميع البيانات بشكل صحيح |
دقيقتان تقريبًا (فحص الاختلاف وقاعدة البيانات الأولية) |
| البوابة 2 | واجهات برمجة التطبيقات للواجهة الخلفية ومسار معالجة البيانات في Gemini | feat/m2-backend-apisالعلامة: gate-2-approved |
/api/workouts/log و/api/coach/chat واختبارات التكامل |
3 دقائق تقريبًا (تشغيل نص برمجي لاختبار واجهة برمجة التطبيقات والتحقّق من المخطط) |
| Gate 3 | حالة العميل وأداة تتبّع النشاط الرياضي | feat/m3-client-state-trackerالعلامة: gate-3-approved |
Shell، /today، /workout/active، تم اجتياز اختبار المتصفّح |
3 دقائق تقريبًا (النقر على عناصر التحكّم في التمرين واختبار ساعة الإيقاف) |
| البوابة 4 | Coach Chat & Staged Proposals | 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 |
إصدار الإنتاج، ذاكرة التخزين المؤقت لتطبيق الويب التقدّمي، تم اجتياز 42 اختبارًا من أصل 42 | ~5 دقائق (مراجعة التقرير النهائي والتحقّق من سلامة الأجهزة الجوّالة) |