Smart Fitness App: Phased Implementation Plan & Verification Roadmap
مصنوعاین مصنوع در قسمت ۴ استفاده شده است: طرح پیاده‌سازی برنامه بدون کد. می‌توانید از این نقشه راه برای هماهنگ کردن توسعه مبتنی بر نقطه عطف با درستی‌سنجی دولایه و دروازه‌های شاخه/برچسب Git استفاده کنید.
برای دسترسی به این آرتیفکت، به سیستم وارد شوید
با «نمایه توسعه‌دهنده Google» خود به سیستم وارد شوید تا بتوانید کل مصنوع استفادهشده در مجموعه Build It! را مشاهده و کپی کنید.
نمایه توسعه‌دهندگان نرم‌افزار لازم است
واجدشرایط نمایه توسعه‌دهندگان نیستید. به سرپرست فضای کاریتان اطلاع دهید تا این ویژگی را فعال کند.
ایجاد نمایه تولیدکننده
برای باز کردن قفل همه پیاموارهها و مصنوعات Build It!، «نمایه توسعه‌دهنده Google» رایگان ایجاد کنید.
برای باز کردن قفل، به Builder Central بپیوندید
با یک کلیک، نشان عضویت رایگان «سازنده» را مطالبه کنید تا قفل همه پیاموارهها و خروجیهای ساختاریافته Build It! باز شود.
وضعیت: تأییدشده و آماده اجرا
مخاطب هدف: عامل توسعه‌دهنده هوش مصنوعی خودکار و رهبر پروژه انسانی
اسناد همراه: مشخصات معماری داده، مشخصات معماری مشتری، مشخصات عامل آموزش‌دهنده هوش مصنوعی
چکیده مدیریتی و استراتژی اجرا
این طرح پیاده‌سازی، ساخت کامل برنامه Smart Fitness را از طرح‌واره‌های پایه‌ای تا سطح آمادگی تولید هماهنگ می‌کند.
الگوی اجرا: مبتنی بر نقطه عطف با درستی‌سنجی دولایه
برای ایجاد تعادل بین سرعت بالای عامل و دقت معماری، این طرح از چارچوب نقطه عطف فازبندی‌شده پیروی می‌کند:
- اجرای خودکار در نقاط عطف: عامل پیاده‌سازی به‌طور مداوم مراحل هر نقطه عطف را طی می‌کند، کد می‌نویسد، ساخت‌ها را اجرا می‌کند، خطاهای کامپایلر را برطرف می‌کند، و مشکلات را بدون مدیریت جزئی انسان به‌طور خودکار حل می‌کند.
- درستی‌سنجی لایه ۱ — مانع پیش‌دروازه عامل خودکار: قبل‌از درخواست تأیید نهایی انسانی، عامل باید بررسی‌های کامپایلر را اجرا کند، اسکریپت‌های آزمایش پس‌بک را اجرا کند، و درستی‌سنجی مرورگر خودکار Google Antigravity (بااستفاده از Chrome DevTools) را راه‌اندازی کند تا تعامل‌های واقعی کاربر تلفن همراه را شبیه‌سازی کند، چارچوب‌های تست انگلیسی ساده را اجرا کند، وضعیت DOM را بازرسی کند، و نماگرفت‌ها را ضبط کند.
- درستی‌سنجی لایه ۲ — ایست بازرسی دروازه‌بان انسانی: پس‌از اینکه بررسی‌های خودکار نماینده با موفقیت انجام شد، دروازه‌بان انسانی یک بازبینه ۲ دقیقه‌ای مشخص را مرور می‌کند تا حس تجربه کاربری، هم‌راستایی کسب‌وکار، و تمامیت داده‌ها را پیش‌از اعطای اجازه برای رفتن به نقطه عطف بعدی درستی‌سنجی کند.
پروتکل برچسب‌گذاری Git و کنترل نسخه
برای اطمینان از بازیابی پس‌از فاجعه، تفاوت‌های شفاف بازبینی کد، و خطاهای ترکیبی صفر در نقاط عطف، عامل پیاده‌سازی باید پروتکل 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" - Human Gatekeeper Diff Review:
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
Primary Architecture Dependency Graph
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}نقطه عطف ۱: داربست پروژه، انواع هسته، و لایه پایگاه داده
هدف: ایجاد کردن پایه مخزن، قراردادهای دامنه TypeScript سخت‌گیرانه، اتصالات کیت توسعه نرم‌افزار Firebase، و کاشتن دانشنامه تمرین ایستا.
- تکلیف ۱.۰: مقداردهی اولیه شاخه Git — ایجاد و رفتن به
feat/m1-scaffolding-types. - Task 1.1: Project Scaffolding & Toolchain Setup — Initialize Next.js 19 (App Router) with TypeScript strict mode, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDKs, Google generative AI SDK, Recharts, and PWA baseline.
- تکلیف ۱.۲: تعاریف نوع دامنه TypeScript متعارف — ماژول
src/types/(exercise.ts،plan.ts،session.ts،profile.ts،chat.ts،pr.ts) را دقیقاً مطابق با مشخصات معماری داده ایجاد کنید. - تکلیف ۱.۳: راه‌اندازی کیت توسعه نرم‌افزار Firebase Client و Firebase Admin —
src/lib/firebase/client.tsوsrc/lib/firebase/admin.tsرا پیاده‌سازی کنید. - تکلیف ۱.۴: اسکریپت بذرپاشی دایره‌المعارف تمرین —
scripts/seed-exercises.tsرا برای بذرپاشی/exercisesبا فراداده و نامک‌های متعارف ایجاد کنید. - تکلیف ۱.۵: قوانین و نمایه‌های Firestore —
firestore.rulesوfirestore.indexes.jsonرا مستقر کنید.
درستی‌سنجی لایه ۱ و لایه ۲ (دروازه ۱): npx tsc --noEmit، npm run lint، و npx ts-node scripts/seed-exercises.ts را اجرا کنید؛ git diff main..HEAD را بازرسی کنید و اسناد Firestore بذرپاشی‌شده را قبل‌از برچسب‌گذاری gate-1-approved درستی‌سنجی کنید.
نقطه عطف ۲: گرداننده‌های مسیر میانای برنامه‌سازی کاربردی باطن و خط لوله موتور هوش مصنوعی
هدف: پیاده‌سازی گرداننده‌های مسیر سرور برای ثبت تمرین و خط لوله مربیگری هوش مصنوعی Gemini با ذخیره‌سازی موقت بافت، مدیریت تغییر حافظه، و پیشنهادهای مرحله‌ای.
- تکلیف ۲.۰: مقداردهی اولیه شاخه Git —
feat/m2-backend-apisرا ازmainایجاد کنید و به آن بروید. - تکلیف ۲.۱: کمک‌کننده میان‌افزار اصالت‌سنجی —
src/lib/auth/server-auth.tsدرستی‌سنجی کردن توکن‌های شناسه Firebase را پیاده‌سازی کنید. - تکلیف ۲.۲: نقطه پایانی ثبت تمرین (
POST /api/workouts/log) — محاسبه حجم جلسه، اعمال فرمول Brzycki 1RM، به‌روزرسانی/درج رکوردهای شخصی، حفظ گزارش تغییرناپذیر، و علامت‌گذاری روز زمان‌بندی‌شده به‌عنوانcompleted. - تکلیف ۲.۳: حافظه نهان بافت Gemini و مونتاژ پیام‌واره پویا —
cachedContents.createرا با «دستورالعمل‌های سیستم اصلی» و مونتاژ بافت زمان اجرای پویا راه‌اندازی کنید. - Task 2.4: Unified Chat Endpoint (
POST /api/coach/chat) — Enforce structured JSON schema output, dual-write toweekly_chats, and enforce Staged Mutation Isolation. - تکلیف ۲.۵: پردازنده جهش حافظه خودکار — اعمال
memory_mutations(CREATE،UPDATE،DELETE) به/users/{userId}/profile/main. - تکلیف ۲.۶: ابزارهای پُرسمان تحلیلی فقط خواندنی —
get_historical_exercise_logs،get_volume_trends، وget_pr_recordsرا پیاده‌سازی کنید.
درستی‌سنجی لایه ۱ و لایه ۲ (دروازه ۲): npx ts-node scripts/test-api-routes.ts را اجرا کنید، جداسازی جهش مرحله‌ای را درستی‌سنجی کنید، تأخیر ذخیره‌شده در حافظه نهان را بررسی کنید (کمتر از ۲٫۵ ثانیه)، و gate-2-approved را برچسب‌گذاری کنید.
نقطه عطف ۳: زیرساخت وضعیت کارخواه و ردیاب اصلی Gym-Floor
هدف: ساختن پوسته برنامه، جایگاه ثابت پایین، معماری حالت Zustand محلی و TanStack Query، و نمای اجرای پرخطر /workout/active در کف سالن ورزشی.
- تکلیف ۳.۰: مقداردهی اولیه شاخه Git —
feat/m3-client-state-trackerرا ازmainایجاد کنید و به آن بروید. - تکلیف ۳.۱: پوسته برنامه و پیمایش دائمی —
<AppContainer />و<BottomNavigationBar />را با ۵ هدف ضربه ۴۸dp لمسی و دکمه مرکزی پویا پیاده‌سازی کنید. - تکلیف ۳.۲: مدیریت وضعیت مشتری و مسطح‌کننده نمودار مرحله‌ای —
useActiveSessionStore(Zustand +localStorage) و الگوریتم مسطح‌کننده نمودار مرحله‌ای را پیاده‌سازی کنید. - تکلیف ۳.۳: کاتالوگ مؤلفه بلوک تمرین قابل‌استفاده مجدد —
<WorkoutHeader />،<WorkoutExerciseSummary />،<WorkoutBlock />،<ExerciseCard />،<EmptyDayPlaceholder />، و<ModifyWithCoachCard />را پیاده‌سازی کنید. - تکلیف ۳.۴: نماهای پیش‌نمایش تمرین روزانه —
DailyWorkoutViewرا برای/todayو/workouts/:dayپیاده‌سازی کنید. - تکلیف ۳.۵: صفحه اجرای تمرین فعال (
/workout/active) — پیاده‌سازی سرصفحه زمان‌سنج،<CurrentSetTargetCard />(واسط کاربر خوش‌بینانه کمتر از ۱۶ میلی‌ثانیه)،<ActiveRestTimerDock />،<ExerciseSetsTable />،<SwapExerciseModal />، و<FinishConfirmationModal />. - تکلیف ۳.۶: نمای دایره‌المعارف جزئیات تمرین (
/exercises/:exerciseId) — پیاده‌سازی حلقه خودکار بی‌صدا<ExerciseVideoPlayer />، عضلات هدف، مراحل، و نکات فرم.
درستی‌سنجی لایه ۱ و لایه ۲ (دروازه ۳): مجموعه‌های ۱، ۲، ۵، و ۶ را در نمای دستگاه همراه Chrome DevTools (۳۹۰×۸۴۴) اجرا کنید، بازیابی بار کردن مجدد localStorage را درستی‌سنجی کنید، و gate-3-approved را برچسب‌گذاری کنید.
نقطه عطف ۴: مرکز مکالمه مربی هوش مصنوعی و میانای پیشنهاد مرحله‌ای
هدف: پیاده‌سازی میانای مربیگری مکالمه‌ای (/coach) با دیکته گفتار به نوشتار، توصیه‌های تراشه پیام‌واره، پیوست‌های برنمای بافت، و کارت‌های پیشنهاد مرحله‌ای تعاملی.
- تکلیف ۴.۰: مقداردهی اولیه شاخه Git —
feat/m4-coach-chatرا ازmainایجاد کنید و به آن بروید. - تکلیف ۴.۱: وضعیت گپ و همگام‌سازی هم‌زمان —
useCoachChatStoreرا با اشتراک FirestoreonSnapshotپیاده‌سازی کنید. - تکلیف ۴.۲: چیدمان نمای گپ Coach و جریان پیام —
<CoachHeader />،<ChatMessageList />،<ChatBubble />، و Coach Thinking Spinner را پیاده‌سازی کنید. - تکلیف ۴.۳: پیوست کردن بافت و تراشه‌های پیام‌واره —
<ContextBanner />،<ContextualPromptsBar />،<ChatInputBar />، و<SpeechToTextButton />را پیاده‌سازی کنید. - تکلیف ۴.۴: پیاده‌سازی کارت پیشنهاد مرحله‌ای —
<StagedProposalCard />را برای تفاوت‌هایUPDATE_DAYوUPDATE_WEEKپیاده‌سازی کنید. - تکلیف ۴.۵: تعهد پیشنهاد مشارکت انسانی در حلقه —
proposal.dataرا فقط وقتی[Accept Plan]تک‌ضرب زده شد به Firestoreweekly_plansمتعهد کنید.
درستی‌سنجی لایه ۱ و لایه ۲ (دروازه ۴): Suite 4 را در Chrome DevTools اجرا کنید، جداسازی جهش مرحله‌ای و [Accept Plan] commit را درستی‌سنجی کنید، و gate-4-approved را برچسب‌گذاری کنید.
نقطه عطف ۵: بازنگری زمان‌بندی، تجزیه‌وتحلیل پیشرفت، و تنظیمات نمایه
هدف: تکمیل نماهای باقی‌مانده برنامه: «برنامه هفتگی» (/week)، «پیشرفت و تجزیه‌وتحلیل» (/progress)، و «نمایه/تنظیمات» (/settings) با مدیریت حافظه ۳ سطحی.
- تکلیف ۵.۰: مقداردهی اولیه شاخه Git —
feat/m5-schedule-progress-settingsرا ازmainایجاد کنید و به آن بروید. - تکلیف ۵.۱: نمای زمان‌بندی هفته (
/week) —<WeekHeader />،<WeeklyStatsSummary />،<DayScheduleCard variant="normal" />، و<ModifyWeekWithCoachCard />را پیاده‌سازی کنید. - تکلیف ۵.۲: نمای پیشرفت و Analytics (
/progress) —<PRShowcaseBanner />، Recharts<VolumeProgressChartCard /> (4W | 3M | 1Y)،<AllTimeStatsGrid />، و<WorkoutHistorySection />را پیاده‌سازی کنید. - تکلیف ۵.۳: نمایه، تنظیمات، و نمای حافظه هوش مصنوعی (
/settings) —<UserProfileCard />،<EquipmentSelectorCard />،<PreferencesGroup />، و<MemoryTierViewerCard />را با حذف[🗑]پیاده‌سازی کنید.
تأیید لایه ۱ و لایه ۲ (دروازه ۵): مجموعه‌های ۳، ۷، و ۸ را در Chrome DevTools اجرا کنید، کلیدهای نمودار و حذف حافظه را تأیید کنید، و gate-5-approved را برچسب‌گذاری کنید.
نقطه عطف ۶: تقویت تولید، میان‌گیر آفلاین PWA، و تأیید نهایی ماتریس کامل
هدف: تقویت برنامه برای محیط‌های واقعی باشگاه: پیکربندی ذخیره موقت دارایی PWA آفلاین، پیاده‌سازی همگام‌سازی گزارش تمرین آفلاین، و اجرای ماتریس درستی‌سنجی کامل ۴۲ آزمایشی به زبان انگلیسی ساده.
- تکلیف ۶.۰: مقداردهی اولیه شاخه Git —
feat/m6-pwa-productionرا ازmainایجاد کنید و به آن بروید. - تکلیف ۶.۱: عامل خدماتی PWA و ذخیره دارایی در حافظه نهان — نهایی کردن عامل خدماتی Serwist / next-pwa و مانیفست PWA مستقل.
- تکلیف ۶.۲: میان‌گیر همگام‌سازی آفلاین Basement Gym — پیاده‌سازی صف آفلاین در IndexedDB/localStorage برای
POST /api/workouts/logبا پاک‌سازی خودکار اتصال مجدد. - تکلیف ۶.۳: مرزهای خطا و نماهای بازگشتی — بازگشت ۴۰۴، بازگشت روز نامعتبر، و بازگشت تمرین نامعتبر را درستی‌سنجی کنید.
- تکلیف ۶.۴: اجرای ماتریس کامل و ممیزی عملکرد — اجرای هر ۴۲ مورد آزمایشی به زبان انگلیسی ساده در مجموعه‌های ۱ تا ۸ و اجرای ممیزی Lighthouse (عملکرد >۹۰، LCP <۲.۵ ثانیه، اهداف لمسی ≥۴۸dp).
درستی‌سنجی لایه ۱ و لایه ۲ (دروازه ۶): npm run build را اجرا کنید، حالت شبکه آفلاین را در Chrome DevTools شبیه‌سازی کنید، درستی‌سنجی کنید که مجموعه آزمون ۴۲/۴۲ کامل قبول شده است، و v1.0.0 را برچسب‌گذاری کنید.
خلاصه دروازه‌های درستی‌سنجی برای دروازه‌بان انسانی
| گیت | ناحیه تمرکز | شاخه Git و برچسب انتشار | تحویلی عامل کلیدی | زمان موردانتظار برای درستی‌سنجی انسانی |
|---|---|---|---|---|
| گیت ۱ | انواع، طرح‌واره پایگاه داده، و مقدار اولیه | feat/m1-scaffolding-typesبرچسب: gate-1-approved |
src/types/، اسکریپت بذر اجرا شد، ترجمه تمیز |
~۲ دقیقه (بازرسی تفاوت و پایگاه داده بذرپاشی‌شده) |
| گیت ۲ | میاناهای برنامه‌سازی کاربردی پسین و خط لوله Gemini | feat/m2-backend-apisبرچسب: gate-2-approved |
/api/workouts/log، /api/coach/chat، آزمایش‌های ادغام |
~۳ دقیقه (اجرای اسکریپت آزمایش API و بررسی طرح‌واره) |
| گیت ۳ | ردیاب فعال و وضعیت کارخواه | feat/m3-client-state-trackerبرچسب: gate-3-approved |
Shell، /today، /workout/active، آزمایش مرورگر با موفقیت انجام شد |
~۳ دقیقه (روی کنترل‌های تمرین و وقت‌نگهدار آزمون ضربه بزنید) |
| گیت ۴ | گپ مربی و پیشنهادهای مرحله‌ای | feat/m4-coach-chatبرچسب: gate-4-approved |
/coach، <StagedProposalCard />، پیشنهاد نهایی شد |
~۳ دقیقه (گپ با مربی، آزمایش [Accept Plan]) |
| گیت ۵ | زمان‌بندی، Analytics، و تنظیمات | feat/m5-schedule-progress-settingsبرچسب: gate-5-approved |
/week، /progress، /settings، مدیر حافظه |
~۳ دقیقه (مرور نمودارها و حذف حافظه آزمایشی) |
| گیت ۶ | همگام‌سازی آفلاین برنامه وب پیش‌رو و انتشار کامل | feat/m6-pwa-productionبرچسب: v1.0.0 |
ساخت تولید، حافظه نهان برنامه وب پیش‌رو، ۴۲/۴۲ آزمایش موفق بود | ~۵ دقیقه (مرور گزارش نهایی و بررسی سلامت تلفن همراه) |