Gemini 4 Argon is now available for Google AI Pro and Ultra subscribers and via Gemini API paid tier. Learn more.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

스마트 피트니스 앱: 단계별 구현 계획 및 검증 로드맵

아티팩트

이것은 에피소드 4: 노 코드 앱 구현 계획에서 사용되는 아티팩트입니다. 이 로드맵을 사용하여 이중 레이어 검증 및 Git 브랜치/태그 게이트를 통해 마일스톤 기반 개발을 조정할 수 있습니다.

다루는 내용: 에피소드 4: 노 코드 앱 구현 계획

상태: 승인됨 및 실행 준비 완료
타겟층: 자율 AI 개발자 에이전트 및 인간 프로젝트 리드
관련 문서: 데이터 아키텍처 사양, 클라이언트 아키텍처 사양, AI 트레이너 에이전트 사양

핵심 요약 및 실행 전략

이 구현 계획은 기본 스키마부터 프로덕션 준비 상태에 이르기까지 스마트 피트니스 애플리케이션의 전체 빌드를 조정합니다.

실행 패러다임: 이중 레이어 검증을 통한 마일스톤 기반

이 계획은 에이전트의 빠른 속도와 아키텍처의 정확성 간의 균형을 맞추기 위해 단계별 마일스톤 프레임워크를 따릅니다.

마일스톤 내 자율 실행: 구현 에이전트는 인간의 세세한 관리 없이 각 마일스톤의 단계를 지속적으로 진행하며 코드를 작성하고, 빌드를 실행하고, 컴파일러 오류를 수정하고, 문제를 자가 복구합니다.
레이어 1 검증 — 자율 에이전트 사전 게이트 장벽: 에이전트는 사람의 승인을 요청하기 전에 컴파일러 검사를 실행하고, 백엔드 테스트 스크립트를 실행하고, Google Antigravity Autonomous Browser Verification (Chrome DevTools 사용)을 실행하여 실제 모바일 사용자 상호작용을 시뮬레이션하고, 일반 영어 테스트 사례를 실행하고, DOM 상태를 검사하고, 스크린샷을 캡처해야 합니다.
레이어 2 검증 — 인간 게이트키퍼 체크포인트: 에이전트의 자동 검사가 통과되면 인간 게이트키퍼가 구체적인 2분 체크리스트를 검토하여 UX 느낌, 비즈니스 정렬, 데이터 무결성을 확인한 후 다음 마일스톤으로 진행할 수 있는 권한을 부여합니다.

버전 제어 및 Git 태그 지정 프로토콜

재해 복구, 투명한 코드 검토 차이, 마일스톤 전반에 걸친 오류 누적 방지를 위해 구현 에이전트는 다음 Git 프로토콜을 엄격하게 준수해야 합니다.

브랜치 전략:
- main: 보호된 브랜치입니다. 사람이 승인한 마일스톤 출시만 여기에 병합됩니다.
- 주요 단계 기능 브랜치: 주요 단계별 전용 브랜치 (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: 프로젝트 스캐폴딩 및 도구 모음 설정 — TypeScript 엄격 모드, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDK, Google 생성형 AI SDK, Recharts, PWA 기준을 사용하여 Next.js 19 (App Router)를 초기화합니다.
작업 1.2: 표준 TypeScript 도메인 유형 정의 — 데이터 아키텍처 사양과 정확히 일치하는 src/types/ 모듈 (exercise.ts, plan.ts, session.ts, profile.ts, chat.ts, pr.ts)을 만듭니다.
작업 1.3: Firebase 클라이언트 및 Admin SDK 설정 — 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를 검사하고 gate-1-approved에 태그를 지정하기 전에 시드된 Firestore 문서를 확인합니다.

핵심 목표 2: 백엔드 API 경로 핸들러 및 AI 엔진 파이프라인

목표: 컨텍스트 캐싱, 메모리 변형 처리, 단계적 제안을 사용하여 운동 로깅 및 Gemini AI 코칭 파이프라인의 서버 경로 핸들러를 구현합니다.

작업 2.0: Git 브랜치 초기화 — main에서 feat/m2-backend-apis를 만들고 전환합니다.
작업 2.1: 인증 미들웨어 도우미 — Firebase ID 토큰을 확인하는 src/lib/auth/server-auth.ts를 구현합니다.
작업 2.2: 운동 로깅 엔드포인트 (POST /api/workouts/log) — 세션 볼륨을 계산하고, Brzycki 1RM 수식을 적용하고, PR을 삽입/업데이트하고, 변경 불가능한 로그를 저장하고, 예약된 날짜를 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: 클라이언트 상태 인프라 및 핵심 Gym-Floor 추적기

목표: 앱 셸, 영구 하단 도크, 로컬 Zustand 및 TanStack Query 상태 아키텍처, 중요한 /workout/active 체육관 바닥 실행 뷰를 빌드합니다.

작업 3.0: Git 브랜치 초기화 — main에서 feat/m3-client-state-tracker를 만들고 전환합니다.
작업 3.1: 앱 셸 및 영구 탐색 — 5개의 촉각 48dp 탭 타겟과 동적 중앙 버튼을 사용하여 <AppContainer /> 및 <BottomNavigationBar />를 구현합니다.
작업 3.2: 클라이언트 상태 관리 및 단계 그래프 평탄화 도구 — useActiveSessionStore (Zustand + localStorage) 및 단계 그래프 평탄화 도구 알고리즘을 구현합니다.
작업 3.3: 재사용 가능한 운동 블록 구성요소 카탈로그 — <WorkoutHeader />, <WorkoutExerciseSummary />, <WorkoutBlock />, <ExerciseCard />, <EmptyDayPlaceholder />, <ModifyWithCoachCard />를 구현합니다.
작업 3.4: 일일 운동 미리보기 뷰 — /today 및 /workouts/:day에 DailyWorkoutView를 구현합니다.
작업 3.5: 활성 운동 실행 화면 (/workout/active) — 스톱워치 헤더, <CurrentSetTargetCard />(16ms 미만 낙관적 UI), <ActiveRestTimerDock />, <ExerciseSetsTable />, <SwapExerciseModal />, <FinishConfirmationModal />를 구현합니다.
작업 3.6: 운동 세부정보 백과사전 뷰 (/exercises/:exerciseId) — 자동 반복 음소거 <ExerciseVideoPlayer />, 타겟 근육, 단계, 자세 팁을 구현합니다.

레이어 1 및 레이어 2 확인 (게이트 3): Chrome DevTools 모바일 표시 영역 (390x844)에서 모음 1, 2, 5, 6을 실행하고 localStorage 새로고침 복구를 확인하고 gate-3-approved 태그를 지정합니다.

마일스톤 4: AI 코치 대화 허브 및 단계별 제안 인터페이스

목표: 음성 텍스트 변환 받아쓰기, 프롬프트 칩 추천, 컨텍스트 배너 첨부파일, 대화형 단계별 제안 카드를 사용하여 대화형 코칭 인터페이스 (/coach)를 구현합니다.

작업 4.0: Git 브랜치 초기화 — main에서 feat/m4-coach-chat를 만들고 전환합니다.
작업 4.1: 채팅 상태 및 실시간 동기화 — Firestore onSnapshot 구독을 사용하여 useCoachChatStore를 구현합니다.
작업 4.2: 코치 채팅 뷰 레이아웃 및 메시지 스트림 — <CoachHeader />, <ChatMessageList />, <ChatBubble />, 코치 생각 중 스피너를 구현합니다.
작업 4.3: 컨텍스트 첨부파일 및 프롬프트 칩 — <ContextBanner />, <ContextualPromptsBar />, <ChatInputBar />, <SpeechToTextButton />를 구현합니다.
작업 4.4: 단계적 제안 카드 구현 — UPDATE_DAY 및 UPDATE_WEEK 차이에 대해 <StagedProposalCard />를 구현합니다.
태스크 4.5: 휴먼인더루프 제안서 커밋 — [Accept Plan]를 탭한 경우에만 proposal.data를 Firestore weekly_plans에 커밋합니다.

레이어 1 및 레이어 2 확인 (게이트 4): Chrome DevTools에서 Suite 4를 실행하고, 스테이징된 변형 격리 및 [Accept Plan] 커밋을 확인하고, gate-4-approved에 태그를 지정합니다.

마일스톤 5: 일정 점검, 진행 상황 분석, 프로필 설정

목표: 3계층 메모리 관리를 사용하여 나머지 애플리케이션 뷰인 주간 일정 (/week), 진행 상황 및 분석 (/progress), 프로필/설정 (/settings)을 완료합니다.

작업 5.0: Git 브랜치 초기화 — main에서 feat/m5-schedule-progress-settings를 만들고 전환합니다.
작업 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): Chrome DevTools에서 제품군 3, 7, 8을 실행하고 차트 전환 및 메모리 삭제를 확인하고 gate-5-approved를 태그합니다.

마일스톤 6: 프로덕션 강화, PWA 오프라인 버퍼, 전체 매트릭스 승인

목표: 실제 체육관 환경에 맞게 애플리케이션을 강화합니다. 오프라인 PWA 애셋 캐싱을 구성하고, 오프라인 운동 기록 동기화를 구현하고, 42개의 테스트로 구성된 일반 영어 검증 매트릭스를 실행합니다.

작업 6.0: Git 브랜치 초기화 — main에서 feat/m6-pwa-production를 만들고 전환합니다.
작업 6.1: PWA 서비스 워커 및 애셋 캐싱 — Serwist/next-pwa 서비스 워커 및 독립형 PWA 매니페스트를 마무리합니다.
작업 6.2: Basement Gym 오프라인 동기화 버퍼 — 자동 재연결 플러시를 사용하여 POST /api/workouts/log의 IndexedDB/localStorage에 오프라인 대기열을 구현합니다.
작업 6.3: 오류 경계 및 대체 뷰 — 404 대체, 잘못된 날짜 대체, 잘못된 운동 대체를 확인합니다.
작업 6.4: 전체 매트릭스 실행 및 성능 감사 — 모음 1~8에 걸쳐 42개의 일반 영어 테스트 사례를 모두 실행하고 Lighthouse 감사 (성능 >90, LCP <2.5초, 터치 영역 ≥48dp)를 실행합니다.

레이어 1 및 레이어 2 인증 (게이트 6): npm run build를 실행하고 Chrome DevTools에서 오프라인 네트워크 모드를 시뮬레이션하고 전체 42/42 테스트 모음 통과를 확인하고 v1.0.0를 태그합니다.

인간 게이트키퍼를 위한 검증 게이트 요약

게이트	중점 분야	Git 브랜치 및 출시 태그	상담사 주요 결과물	예상 사람 인증 시간
게이트 1	유형, DB 스키마, 시드	`feat/m1-scaffolding-types` 태그: `gate-1-approved`	`src/types/`, 시드 스크립트 실행됨, 클린 컴파일	약 2분 (차이점 및 시드 DB 검사)
게이트 2	백엔드 API 및 Gemini 파이프라인	`feat/m2-backend-apis` 태그: `gate-2-approved`	`/api/workouts/log`, `/api/coach/chat`, 통합 테스트	약 3분 (API 테스트 스크립트 실행 및 스키마 확인)
Gate 3	고객 상태 및 활성 추적기	`feat/m3-client-state-tracker` 태그: `gate-3-approved`	셸, `/today`, `/workout/active`, 브라우저 테스트 통과	약 3분 (운동 제어 탭 및 스톱워치 테스트)
Gate 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분 (최종 보고서 검토 및 모바일 온전성 검사)

스마트 피트니스 앱: 단계별 구현 계획 및 검증 로드맵

개발자 프로필 필요

개발자 프로필 만들기

Builder Central에 가입하여 활용하기

핵심 요약 및 실행 전략

실행 패러다임: 이중 레이어 검증을 통한 마일스톤 기반

버전 제어 및 Git 태그 지정 프로토콜

기본 아키텍처 종속 항목 그래프

마일스톤 1: 프로젝트 스캐폴딩, 핵심 유형, 데이터베이스 레이어

핵심 목표 2: 백엔드 API 경로 핸들러 및 AI 엔진 파이프라인

목표 3: 클라이언트 상태 인프라 및 핵심 Gym-Floor 추적기

마일스톤 4: AI 코치 대화 허브 및 단계별 제안 인터페이스

마일스톤 5: 일정 점검, 진행 상황 분석, 프로필 설정

마일스톤 6: 프로덕션 강화, PWA 오프라인 버퍼, 전체 매트릭스 승인

인간 게이트키퍼를 위한 검증 게이트 요약

스마트 피트니스 앱: 단계별 구현 계획 및 검증 로드맵

이 아티팩트에 액세스하려면 로그인하세요.

개발자 프로필 필요

개발자 프로필 만들기

Builder Central에 가입하여 활용하기

핵심 요약 및 실행 전략

실행 패러다임: 이중 레이어 검증을 통한 마일스톤 기반

버전 제어 및 Git 태그 지정 프로토콜

기본 아키텍처 종속 항목 그래프

마일스톤 1: 프로젝트 스캐폴딩, 핵심 유형, 데이터베이스 레이어

핵심 목표 2: 백엔드 API 경로 핸들러 및 AI 엔진 파이프라인

목표 3: 클라이언트 상태 인프라 및 핵심 Gym-Floor 추적기

마일스톤 4: AI 코치 대화 허브 및 단계별 제안 인터페이스

마일스톤 5: 일정 점검, 진행 상황 분석, 프로필 설정

마일스톤 6: 프로덕션 강화, PWA 오프라인 버퍼, 전체 매트릭스 승인

인간 게이트키퍼를 위한 검증 게이트 요약