Akıllı Fitness Uygulaması: Aşamalı Uygulama Planı ve Doğrulama Yol Haritası
ÖğeBu, 4. Bölüm: Kodsuz Uygulama Uygulama Planı'nda kullanılan öğedir. Bu yol haritasını kullanarak çift katmanlı doğrulama ve Git dalı/etiket kapılarıyla aşama odaklı geliştirme sürecini yönetebilirsiniz.
Bu öğeye erişmek için oturum açın
Build It! serisinde kullanılan yapının tamamını görüntülemek ve kopyalamak için Google Geliştirici Profilinizle oturum açın.
Geliştirici Profili Gerekli
Geliştirici profili için uygun değilsiniz. Bu özelliği etkinleştirmek için Workspace yöneticinizle iletişime geçin.
Geliştirici Profili oluşturun
Tüm Build It! istemlerinin ve yapılarının kilidini açmak için ücretsiz bir Google Geliştirici Profili oluşturun.
Builder Central'a katılarak erişim elde edin
Tüm Build It! istemlerine ve yapılarına erişmek için ücretsiz Builder üye rozetinizi tek tıklamayla alın.
Durum: Onaylandı ve Uygulamaya Hazır
Hedef Kitle: Otonom Yapay Zeka Geliştirici Temsilcisi ve İnsan Proje Lideri
Eşlik Eden Belgeler: Veri Mimarisi Spesifikasyonu, İstemci Mimarisi Spesifikasyonu, Yapay Zeka Eğitmeni Temsilci Spesifikasyonu
Yönetici Özeti ve Uygulama Stratejisi
Bu uygulama planı, temel şemalardan üretime hazırlık aşamasına kadar Smart Fitness uygulamasının tüm derleme sürecini yönetir.
Yürütme Paradigması: Çift Katmanlı Doğrulama ile Aşama Odaklı
Bu plan, yüksek temsilci hızı ile mimari hassasiyet arasında denge kurmak için Aşama Kapılı Ara Hedef Çerçevesi'ni kullanır:
- Ara hedeflerde otonom yürütme: Uygulama temsilcisi, her ara hedefin adımları üzerinde sürekli çalışır. Kod yazar, derlemeleri yürütür, derleyici hatalarını düzeltir ve insan müdahalesi olmadan sorunları kendi kendine çözer.
- 1. Katman Doğrulama - Otonom Temsilci Ön Kapı Bariyeri: Temsilci, insan onayı istemeden önce derleyici kontrollerini çalıştırmalı, arka uç test komut dosyalarını yürütmeli ve gerçek mobil kullanıcı etkileşimlerini simüle etmek, basit İngilizce test senaryolarını yürütmek, DOM durumunu incelemek ve ekran görüntüleri yakalamak için Google Antigravity Otonom Tarayıcı Doğrulaması'nı (Chrome Geliştirici Araçları'nı kullanarak) başlatmalıdır.
- 2. Katman Doğrulama - İnsan Gözetmen Kontrol Noktası: Temsilcinin otomatik kontrolleri tamamlandıktan sonra insan gözetmen, bir sonraki aşamaya geçiş izni vermeden önce kullanıcı deneyimi hissini, iş uyumunu ve veri bütünlüğünü doğrulamak için 2 dakikalık somut bir kontrol listesini inceler.
Sürüm Denetimi ve Git Etiketleme Protokolü
Uygulama temsilcisi, olağanüstü durum kurtarma, şeffaf kod incelemesi farkları ve aşamalar arasında sıfır bileşik hata sağlamak için aşağıdaki Git protokolüne kesinlikle uymalıdır:
- Dallanma Stratejisi:
main: Korunan dal. Burada yalnızca gerçek kişiler tarafından onaylanan ara sürümler birleştirilir.- Aşama Özellik Dalları: Her aşama için özel dal (
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" - Human Gatekeeper Diff Review:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Aşama Onayı ve Ara Hedef Etiketleme:
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" - Geri alma ve olağanüstü durum kurtarma:
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
Birincil Mimari Bağımlılık Grafiği
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. Aşama: Proje İskeleti, Temel Türler ve Veritabanı Katmanı
Hedef: Depo temelini, katı TypeScript alan adı sözleşmelerini ve Firebase SDK'sı bağlantılarını oluşturun ve statik egzersiz ansiklopedisini doldurun.
- Görev 1.0: Git dalı başlatma:
feat/m1-scaffolding-typesdalını oluşturun ve bu dala geçin. - Görev 1.1: Proje İskeleti ve Araç Zinciri Kurulumu: Next.js 19'u (App Router) TypeScript yüksek düzey modu, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDK'ları, Google üretken yapay zeka SDK'sı, Recharts ve PWA temeli ile başlatın.
- Görev 1.2: Standart TypeScript Alan Adı Türü Tanımları: Veri Mimarisi Spesifikasyonu ile tam olarak eşleşen
src/types/modülünü (exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) oluşturun. - Görev 1.3: Firebase İstemci ve Yönetici SDK'sı Kurulumu:
src/lib/firebase/client.tsvesrc/lib/firebase/admin.ts'yı uygulayın. - Görev 1.4: Egzersiz Ansiklopedisi Başlangıç Komut Dosyası: Standart kısa adlar ve meta verilerle
/exercisesveritabanını doldurmak içinscripts/seed-exercises.tsoluşturun. - Görev 1.5: Firestore Kuralları ve Dizinleri:
firestore.rulesvefirestore.indexes.jsondosyalarını dağıtın.
1. ve 2. Katman Doğrulaması (1. Aşama): npx tsc --noEmit, npm run lint ve npx ts-node scripts/seed-exercises.ts komutlarını çalıştırın; git diff main..HEAD komutunu inceleyin ve gate-1-approved etiketini eklemeden önce temel Firestore dokümanlarını doğrulayın.
Ara Hedef 2: Arka Uç API Rota İşleyicileri ve Yapay Zeka Motoru Ardışık Düzeni
Hedef: Antrenman günlük kaydı ve Gemini AI yapay zeka koçluğu ardışık düzeni için sunucu rota işleyicilerini bağlam önbelleğe alma, bellek mutasyonu işleme ve aşamalı önerilerle uygulayın.
- Görev 2.0: Git dalı başlatma:
feat/m2-backend-apisdalını oluşturun vemaindalından bu dala geçin. - Görev 2.1: Kimlik Doğrulama Ara Katman Yazılımı Yardımcısı: Firebase kimlik jetonlarını doğrulayan
src/lib/auth/server-auth.tsişlevini uygulayın. - Görev 2.2: Antrenman Günlüğü Uç Noktası (
POST /api/workouts/log): Antrenman hacmini hesaplayın, Brzycki 1RM formülünü uygulayın, kişisel rekorları güncelleyin, sabit günlüğü kaydedin ve planlanan günücompletedolarak işaretleyin. - Görev 2.3: Gemini bağlam önbelleğe alma ve dinamik istem birleştirme: Birincil sistem talimatları ve dinamik çalışma zamanı bağlam birleştirme ile
cachedContents.createoluşturun. - Görev 2.4: Birleştirilmiş Sohbet Uç Noktası (
POST /api/coach/chat): Yapılandırılmış JSON şeması çıkışını zorunlu kılın,weekly_chats'e ikili yazma işlemi gerçekleştirin ve Aşamalı Mutasyon İzolasyonu'nu zorunlu kılın. - Görev 2.5: Otonom Bellek Mutasyon İşlemcisi —
memory_mutations(CREATE,UPDATE,DELETE) işlemini/users/{userId}/profile/mainiçin uygulayın. - Görev 2.6: Salt Okunur Analitik Sorgu Araçları:
get_historical_exercise_logs,get_volume_trendsveget_pr_recordsaraçlarını uygulayın.
1. ve 2. Katman Doğrulaması (2. Aşama): npx ts-node scripts/test-api-routes.ts komutunu çalıştırın, aşamalı mutasyon izolasyonunu doğrulayın, önbelleğe alınmış gecikmeyi (<2,5 sn.) kontrol edin ve gate-2-approved etiketini ekleyin.
3. Ara Hedef: İstemci Durumu Altyapısı ve Temel Spor Salonu Takipçisi
Hedef: Uygulama kabuğunu, kalıcı alt paneli, yerel Zustand ve TanStack Query durum mimarisini ve yüksek riskli /workout/active spor salonu zemininde uygulama görünümünü oluşturun.
- Görev 3.0: Git dalı başlatma:
maindalındanfeat/m3-client-state-trackerdalını oluşturun ve bu dala geçin. - Görev 3.1: Uygulama Kabuğu ve Kalıcı Gezinme: 5 dokunsal 48 dp dokunma hedefi ve dinamik orta düğme ile
<AppContainer />ve<BottomNavigationBar />'yi uygulayın. - Görev 3.2: İstemci Durumu Yönetimi ve Adım Grafiği Düzleştirici:
useActiveSessionStore(Zustand +localStorage) ve adım grafiği düzleştirici algoritmasını uygulayın. - Görev 3.3: Yeniden Kullanılabilir Antrenman Bloğu Bileşen Kataloğu:
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />ve<ModifyWithCoachCard />bileşenlerini uygulayın. - Görev 3.4: Günlük antrenman önizleme görünümleri:
/todayve/workouts/:dayiçinDailyWorkoutViewuygulayın. - Görev 3.5: Aktif Antrenman Uygulama Ekranı (
/workout/active): Kronometre başlığını,<CurrentSetTargetCard />(<16 ms iyimser kullanıcı arayüzü),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />ve<FinishConfirmationModal />öğelerini uygulayın. - Görev 3.6: Egzersiz Ayrıntıları Ansiklopedi Görünümü (
/exercises/:exerciseId): Otomatik olarak döngüye giren sessiz<ExerciseVideoPlayer />, hedef kaslar, adımlar ve form ipuçları ekleyin.
1. ve 2. Katman Doğrulaması (3. Aşama): Chrome Geliştirici Araçları mobil görüntü alanında (390x844) 1, 2, 5 ve 6 numaralı paketleri çalıştırın, localStorage yeniden yükleme kurtarmayı ve gate-3-approved etiketini doğrulayın.
4. Aşama: Yapay Zeka Koç Etkileşimli Merkezi ve Aşamalı Teklif Arayüzü
Hedef: Konuşmayı metne dönüştürme diktesi, istem çipi önerileri, bağlam banner'ı ekleri ve etkileşimli aşamalı teklif kartları içeren etkileşimli koçluk arayüzünü (/coach) uygulama.
- Görev 4.0: Git dalı başlatma:
maindalındanfeat/m4-coach-chatdalını oluşturun ve bu dala geçin. - Görev 4.1: Sohbet Durumu ve Anlık Senkronizasyon: Firestore
onSnapshotaboneliğiyleuseCoachChatStoreuygulayın. - Görev 4.2: Coach Chat View Layout & Mesaj Akışı —
<CoachHeader />,<ChatMessageList />,<ChatBubble />ve Coach Thinking Spinner'ı uygulayın. - 4.3 Görevi: Bağlam Eki ve İstem Çipleri:
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />ve<SpeechToTextButton />'yi uygulayın. - Görev 4.4: Aşamalı Teklif Kartı Uygulaması:
UPDATE_DAYveUPDATE_WEEKfarkları için<StagedProposalCard />uygulayın. - Görev 4.5: İnsan Müdahalesi Gerektiren Teklif Taahhüdü:
proposal.datadeğerini yalnızca[Accept Plan]öğesine dokunulduğunda Firestoreweekly_plansveritabanına kaydedin.
1. ve 2. Katman Doğrulaması (4. Aşama): Chrome Geliştirici Araçları'nda 4. Paketi çalıştırın, aşamalı mutasyon izolasyonunu ve [Accept Plan] commit, and tag gate-4-approved'i doğrulayın.
5. Aşama: Program Yenileme, İlerleme Analizleri ve Profil Ayarları
Hedef: Kalan uygulama görünümlerini tamamlayın: Haftalık Program (/week), İlerleme Durumu ve Analizler (/progress) ve Profil/Ayarlar (/settings) (3 katmanlı bellek yönetimiyle).
- Görev 5.0: Git dalı başlatma:
maindalındanfeat/m5-schedule-progress-settingsdalını oluşturun ve bu dala geçin. - Görev 5.1: Haftalık Program Görünümü (
/week):<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />ve<ModifyWeekWithCoachCard />öğelerini uygulayın. - 5.2 Görevi: İlerleme Durumu ve Analizler Görünümü (
/progress):<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />ve<WorkoutHistorySection />bileşenlerini uygulayın. - 5.3 numaralı görev: Profil, Ayarlar ve Yapay Zeka Hafızası Görünümü (
/settings):[🗑]silme işlemiyle<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />ve<MemoryTierViewerCard />öğelerini uygulayın.
1. ve 2. Katman Doğrulaması (5. Aşama): Chrome Geliştirici Araçları'nda 3, 7 ve 8. paketleri çalıştırın, grafik açma/kapatma düğmelerini ve bellek silme işlemini doğrulayın ve gate-5-approved etiketini ekleyin.
6. Hedef: Üretim Güçlendirme, PWA Çevrimdışı Arabelleği ve Tam Matris Onayı
Hedef: Uygulamayı gerçek spor salonu ortamları için güçlendirin: Çevrimdışı PWA öğe önbelleğe almayı yapılandırın, çevrimdışı antrenman günlüğü senkronizasyonunu uygulayın ve 42 testten oluşan tam doğrulama matrisini çalıştırın.
- Görev 6.0: Git Dalı Başlatma:
maindalındanfeat/m6-pwa-productiondalını oluşturun ve bu dala geçin. - Görev 6.1: PWA Hizmet Çalışanı ve Öğe Önbelleğe Alma: Serwist/next-pwa hizmet çalışanını ve bağımsız PWA manifestini tamamlayın.
- Görev 6.2: Basement Gym Çevrimdışı Senkronizasyon Arabelleği:
POST /api/workouts/logiçin IndexedDB/localStorage'da otomatik yeniden bağlanma temizleme özelliğiyle çevrimdışı sırayı uygulayın. - Görev 6.3: Hata Sınırları ve Yedek Görünümler: 404 yedek, geçersiz gün yedek ve geçersiz egzersiz yedek görünümlerini doğrulayın.
- Görev 6.4: Tam Matris Yürütme ve Performans Denetimi: 1-8.Paketler'deki 42 düz İngilizce test durumunun tamamını yürütün ve Lighthouse denetimini çalıştırın (Performans > 90, LCP < 2,5 sn, dokunma hedefleri ≥ 48 dp).
1. ve 2. Katman Doğrulaması (6. Aşama): npm run build komutunu çalıştırın, Chrome Geliştirici Araçları'nda çevrimdışı ağ modunu simüle edin, 42/42 test paketinin tamamının geçtiğini doğrulayın ve v1.0.0 etiketini ekleyin.
Gerçek Kişi Doğrulayıcı İçin Doğrulama Kapılarının Özeti
| Kapı | Odak Bölgesi | Git dalı ve sürüm etiketi | Temsilcinin Temel Çıktısı | Beklenen Gerçek Kişiler Tarafından Doğrulama Süresi |
|---|---|---|---|---|
| 1. kapı | Türler, Veritabanı Şeması ve Başlangıç Noktası | feat/m1-scaffolding-typesEtiket: gate-1-approved |
src/types/, temel komut dosyası yürütüldü, temiz derleme |
Yaklaşık 2 dakika (farkı ve temel DB'yi inceleme) |
| 2. kapı | Arka uç API'leri ve Gemini ardışık düzeni | feat/m2-backend-apisEtiket: gate-2-approved |
/api/workouts/log, /api/coach/chat, entegrasyon testleri |
Yaklaşık 3 dakika (API test komut dosyasını çalıştırma ve şemayı kontrol etme) |
| 3. kapı | İstemci Durumu ve Aktivite İzleyici | feat/m3-client-state-trackerEtiket: gate-3-approved |
Shell, /today, /workout/active, tarayıcı testi başarılı |
Yaklaşık 3 dakika (antrenman kontrollerine dokunma ve kronometreyi test etme) |
| 4. kapı | Coach Chat ve Aşamalı Teklifler | feat/m4-coach-chatEtiket: gate-4-approved |
/coach, <StagedProposalCard />, teklif taahhüdü |
Yaklaşık 3 dakika (koçla sohbet, [Accept Plan] testi) |
| Gate 5 | Planlama, Analytics ve Ayarlar | feat/m5-schedule-progress-settingsEtiket: gate-5-approved |
/week, /progress, /settings, bellek yöneticisi |
~3 dakika (grafikleri inceleme ve test hafızasını silme) |
| 6. kapı | PWA Çevrimdışı Senkronizasyon ve Tam Sürüm | feat/m6-pwa-productionEtiket: v1.0.0 |
Üretim derlemesi, PWA önbelleği, 42/42 test başarılı | ~5 dakika (nihai raporu inceleme ve mobil cihazda doğruluk kontrolü) |