Fit Atlas
운동 백과사전 · 개인화 세션 · 기록 분석 · 회복 · 웰니스를 하나의 브라우저 로컬 앱으로 연결합니다.
GitHub Pages에서 열기 · 요구사항 QA · 개발 기록 아카이브
Fit Atlas는 개인 또는 소수 사용자를 위한 정적·로컬 우선 피트니스 웹앱입니다. 계정, 서버, 데이터베이스 없이 브라우저에서 동작하며, 운동 기록과 프로필은 사용자의 기기에만 저장됩니다.
❓ 왜 만들었나
운동을 시작할 때 막히는 건 의지가 아니라 정보의 형태였다.
"등 운동"을 검색하면 영상 수십 개가 나오는데, 그중 무엇이 지금 내 수준에 맞는지, 어느 근육을 쓰는지, 어디가 아프면 멈춰야 하는지는 각자 다른 곳에 흩어져 있다. 운동 앱은 대부분 기록부터 시작하지만, 애초에 무엇을 해야 할지 모르는 단계를 도와주지 않는다.
그래서 목표를 이렇게 잡았다.
- 찾기부터 — 부위·목적·난이도·장비로 좁혀 들어가고, 각 운동마다 자세 단서·타깃 근육·주의 사항·공신력 있는 출처를 함께 본다
- 계정 없이 — 서버도 로그인도 없이 브라우저만으로 동작한다. 기록은 이 기기에만 남는다
- 의료 조언이 아님을 분명히 — 통증·질환은 전문가 영역이다. 일반적인 운동 정보와 안전 고지의 경계를 지킨다
현재 상태
| 항목 | 현재 구현 |
|---|
| 운동 카탈로그 | 990개 실제 독립 운동: 공개 원천 검증 534개 + 수작업 큐레이션 456개 |
| 탐색 범위 | 러닝, 유산소, 헬스기구, 프리웨이트, 맨몸운동, 모빌리티, 균형·협응, 요가·필라테스, 파워·민첩성의 9개 카테고리 |
| 상세 지식 | 시작 자세, 수행 경로, 대표 오류, 쉬운 변형, 진행 변형, 종료 기준, 주의 사항, 근거 적용 범위 |
| 데이터 저장 | localStorage 기반의 기록·프로필·체크인·주간 계획·컨디션 이력·즐겨찾기·최근 본 운동, 백업 버전 5 |
| 품질 기준 | Vitest 359개 테스트(54개 파일), TypeScript 검사(noUnusedLocals 포함), GitHub Pages용 정적 빌드 통과 |
| 배포 | main 푸시 시 GitHub Actions가 검사·테스트·빌드 후 GitHub Pages에 배포 |
주요 기능
| 영역 | 제공 내용 |
|---|
| 운동 탐색 | 키워드, 카테고리, 신체 부위, 목적, 난이도, 장비, 정렬 기준을 조합해 990개 운동을 탐색합니다. "팔굽혀펴기"·"허벅지"처럼 일상에서 쓰는 말로 찾아도 카탈로그 표기로 이어집니다. 조건을 좁혀 결과가 0건이 되면 어떤 조건이 막고 있는지와 그 조건만 풀었을 때의 결과 수를 함께 제시합니다. 100개 단위의 지연 로딩으로 초기 다운로드를 줄입니다. |
| 상세 운동 카드 | 타깃 부위, 기대 효과, 장비, 시간·반복 정보, 자세 단서, 대표 오류, 후퇴·진행 변형, 안전 경계와 원문 링크를 확인합니다. 대표 운동에는 3단계 CSS 시각 가이드가 표시됩니다. |
| 근거 범위 안내 | 종목 원천, 일반 활동·안전 지침의 적용 범위, 개인 질환·통증·부상 상태에 대한 한계를 분리해 제공합니다. |
| 바디 맵·회복 | 7개 신체 부위를 선택해 관련 운동과 일반 회복 관점을 살펴봅니다. 스트레칭·폼롤러·마사지건·부하 조절·위험 신호와 조건별 대체 운동을 연결합니다. |
| 개인화 | 연령, 체중, 성별, 목표, 경험 수준, 선택적 안전 맥락을 바탕으로 보수적인 시작 원칙을 제안합니다. 선호 운동 종류·장비·주 활동 환경을 저장해 탐색과 세션 설계에 적용할 수 있습니다. |
| 세션·주간 계획 | 목표, 환경(집·매트/헬스장/야외), 시간(15/30/45분), 일일 컨디션을 조합해 가벼운 시작 세션을 설계하고 주간 계획에 추가합니다. 한 자리에 넣을 수 있는 운동이 여럿일 때는 한 가지를 먼저 보여 주고 나머지는 "대체 운동"으로 펼쳐 봅니다. |
| 기록·분석 | 날짜, 종목, 세트, 횟수, 중량, 시간, 거리, RPE를 기록합니다. 기록 창은 같은 종목의 직전 값으로 미리 채워지고, 최근 기록한 종목은 버튼으로 바로 고를 수 있습니다. 캘린더, 누적 볼륨, 4주 시간·거리·부하, 개인 최고 기록, 연속성·부위 균형과 종목별 진척(중량 또는 총 반복 기준)을 로컬에서 계산합니다. |
| 일일 체크인 | 에너지, 수면, 스트레스, 통증·불편감을 기록해 당일 RPE·세션 강도 안내를 보수적으로 조절합니다. |
| 회복·웰니스 | 오래 앉은 뒤 5분/10분 전환 루틴, 영양·수분·수면·사우나·열 노출 안내, 저강도 유산소 인터벌, 저소음 홈 서킷을 제공합니다. |
| 빠른 재탐색 | 최근 본 운동과 즐겨찾기를 저장하고, 필요한 카탈로그 페이지만 늦게 불러와 다시 엽니다. |
카탈로그 원칙과 안전 범위
카탈로그에는 코칭 템포, 반복 수, 세트 수만 다른 조합이 아닌 실제로 구별되는 독립 운동 종목을 수록합니다. 공개 운동 데이터 원천 534개는 운동 양식·장비·주동근·자세 변형에 맞춘 개별 상세 프로필을 갖고, 나머지 항목도 메타데이터와 안전 상세를 함께 검증합니다.
라켓·격투 영역은 혼자 수행하는 비접촉·저충격 입문 드릴로 제한합니다. 대련, 스파링, 타격 대상 접촉, 강한 점프·피벗은 포함하지 않습니다. 자세한 경계는 docs/racket_combat_intro_scope.md를 참고하세요.
의학적 고지: Fit Atlas는 일반 운동·웰니스 교육 자료입니다. 의료 진단, 치료, 재활 처방을 대체하지 않습니다. 새롭거나 심한 통증, 저림, 근력 저하, 호흡 곤란, 어지러움, 외상 후 변화가 있으면 활동을 멈추고 적절한 평가를 우선하세요.
공개 출처와 콘텐츠 적용 범위는 연구·가이드라인 목록, 대표 시각·근거 범위, 앉은 자세 회복 범위에서 확인할 수 있습니다.
데이터·프라이버시·백업
운동 기록, 프로필, 선호 설정, 일일 체크인, 주간 계획, 최근 본 운동, 즐겨찾기는 모두 브라우저의 localStorage에 저장됩니다. 앱은 이 데이터를 운영 서버로 전송하지 않습니다.
백업 버튼은 현재 데이터를 JSON으로 내보내며, 가져오기로 다른 브라우저에 복원할 수 있습니다. 데스크톱에서는 상단 막대, 모바일에서는 메뉴 안에 있습니다. 현재 백업 포맷은 버전 5이며 운동 기록·프로필·체크인·주간 계획·탐색 설정에 더해 주간 컨디션 이력과 편집한 세션 블록까지 담습니다. 버전 1–4의 기존 백업도 안전한 기본값과 함께 읽습니다. 가져오기는 현재 브라우저의 기록을 대체하므로 실행 전에 무엇이 얼마나 바뀌는지 확인을 받습니다.
일일 체크인은 직접 입력했을 때만 저장됩니다. 앱을 열어 보기만 한 날은 주간 대시보드에서 "입력 대기"로 남습니다.
로컬 개발
필요 환경
Node.js 22와 pnpm이 필요합니다.
git clone https://github.com/MoriochoRadio/fit-atlas.git
cd fit-atlas
pnpm install
pnpm dev
품질 검사
pnpm check
pnpm test -- --pool=forks --poolOptions.forks.maxForks=1 --poolOptions.forks.minForks=1
pnpm build
pnpm build는 GitHub Pages 경로를 고려한 정적 dist/ 번들을 생성합니다. 현재 초기 화면은 첫 100개 운동만 포함하고, 나머지 카탈로그는 정적 지연 청크로 불러옵니다.
지연 로딩은 실제로 큰 것에만 적용합니다. 카탈로그 페이지(각 100개 운동)와 화면 캡처용 html2canvas가 대상입니다. 작은 UI 컴포넌트까지 쪼개면 전송량은 거의 줄지 않으면서 요청 수와 Suspense 경계만 늘어나므로 하지 않습니다.
GitHub Pages 배포
main 브랜치에 푸시하면 배포 워크플로가 다음 순서로 실행됩니다.
- 의존성을 lockfile 기준으로 설치합니다.
pnpm check로 TypeScript를 검사합니다.pnpm test로 전체 회귀 테스트를 실행합니다.pnpm build 결과인 dist/를 GitHub Pages에 배포합니다.
Pages 기본 경로는 /fit-atlas/이며 vite.config.ts의 GITHUB_PAGES_BASE로 조절합니다. 저장소 이름이나 Pages 경로를 바꾸면 이 값도 함께 갱신해야 합니다.
프로젝트 구조
client/src/
pages/Home.tsx # 상태·훅과 장면 연결 (JSX는 장면 컴포넌트로 분리)
components/scenes/ # 장면 단위 화면: Hero·Session·Explore·Anatomy·Progress·Wellness
components/ModalDialog.tsx # 모달 공통 뼈대와 포커스 관리(진입·순환·복귀)
components/ # 바디 맵·가이드·시각화 UI
lib/catalogPage01..11.ts # 100개 단위 지연 로딩 카탈로그
lib/catalogLoader.ts # 페이지 단위 로더·캐시·통계
lib/exploreFilterState.ts # 탐색 조건 한 벌의 타입·기본값·프리셋 복원
lib/filterRelaxation.ts # 결과 0건일 때 어떤 조건이 막는지 계산
lib/logFormDefaults.ts # 직전 기록 기반 기록 창 기본값
lib/exerciseProgression.ts # 종목별 첫 기록 대비 최근 기록 비교
lib/sessionMovement.ts # 세션 항목을 대표 동작·대체 후보·수행량으로 분리
lib/josa.ts # 받침에 맞는 한국어 조사 선택
lib/logFormValidation.ts # 기록 입력의 칸별 검증
lib/profilePreferences.ts # 프로필·선호 설정의 기본값·호환 복원
lib/localStore.ts # localStorage·백업·가져오기
lib/sessionBuilder.ts # 목표·환경·시간·체크인 기반 세션 설계
lib/recovery*.ts # 회복 선택 경로·프로토콜·앉은 자세 루틴
docs/ # 콘텐츠 근거 자료와 요구사항 QA
.github/workflows/deploy-pages.yml # 정적 배포 자동화
fitnessData.ts는 카탈로그 11개 페이지를 정적으로 import하면서 타입과 콘텐츠까지 재수출합니다. 화면 코드가 여기서 값을 가져오면 지연 청크가 통째로 초기 번들에 들어오므로, 타입은 catalogTypes, 콘텐츠는 catalogContent에서 직접 가져옵니다. 이 규칙은 catalogEagerImport.test.ts가 검사합니다.
🧪 한계
- 개인 기록이 이 브라우저에만 있다. 기기를 바꾸면 백업 파일로 옮겨야 한다. 계정을 없앤 대가다.
- 운동 콘텐츠는 큐레이션이다. 공개 출처(WHO·CDC·ACSM·free-exercise-db)를 근거로 정리했지만, 개인의 상태에 맞춘 처방이 아니다.
- 동작 영상이 없다. 자세는 글과 도식으로만 설명한다. 영상은 저작권과 용량 문제로 넣지 않았다.
- 개인화가 규칙 기반이다. 연령·체중·경험 수준에 따라 보수적으로 시작점을 제안할 뿐, 학습하거나 적응하지 않는다.
✍️ 회고
이 저장소의 커밋 203개 중 160개가 AI 에이전트(Manus) 명의다. 그 산출물을 정리한 과정이 여기서 배운 것의 대부분이다.
2026-08-13에 Manus에게 만들게 했다. 콘텐츠는 진짜였다 — 운동 990종에 자세 단서·타깃 근육·주의 사항·출처가 붙어 있고, 표본을 뽑아 봐도 스모 데드리프트·글루트햄 레이즈 같은 실제 종목이다. 문제는 그 주변이었다.
발견한 것들
배포가 33회 연속 실패하고 있었다. 전면 디자인 개편을 포함한 약 30커밋이 라이브에 반영되지 않은 채였다. 그런데 커밋 메시지는 전부 "테스트 210개 통과"라고 적고 있었다. 실제로는 2건이 실패 중이었다.
원인은 성능 최적화였다. 작은 컴포넌트 12개를 지연 로딩으로 쪼갰는데 — 전부 합쳐 31.7 KB였다. 전송량은 거의 줄지 않으면서 요청만 12회 늘었고, 렌더 타이밍이 비결정적이 되면서 테스트가 깨졌다. 정작 무거운 것은 CSS 267 KB였는데 그건 최적화 대상이 아니었다.
같은 데이터가 두 벌 있었다. 29,448줄짜리 파일이 카탈로그의 일부와 내용까지 완전히 같았다. 그리고 그것을 만든 생성 스크립트들은 /home/ubuntu/... 같은 에이전트 샌드박스 경로를 읽고 있어 이 PC에서는 애초에 실행할 수 없었다.
CSS가 퇴적층이었다. .hero의 높이가 10곳에서 재선언돼 있었다(650→730→665→600→660→684→590px). 고칠 때마다 새 선언을 얹고 이전 것을 지우지 않은 결과다. 마지막 하나만 적용되고 나머지 970개 선언은 전송만 되고 있었다.
카탈로그 숫자에 허수가 있었다. 1,008종 중 235개가 "스테어 클라이머 이지"처럼 강도를 이름 끝에 붙인 항목이었다. 같은 기구가 두 항목으로 세어진 것이다. 품질 게이트가 이런 패턴을 막고 있었는데 정규식에 "이지"가 빠져 있었다.
검색이 표기 하나에 무너졌다. "푸시업"은 31건인데 "푸쉬업"은 0건이었다. 공백·하이픈도 마찬가지였다.
정리한 결과
| 이전 | 이후 |
|---|
| CI | 33연속 실패 | 통과 |
| 테스트 | 208/210 | 359/359 (파일 54개) |
| 카탈로그 | 1,008 (허수 포함) | 990 |
| 코드 | — | 30,027줄 삭제 |
| CSS | 267.6 KB / 10개 파일 | 215.3 KB / 4개 파일 |
| 검색 "푸쉬업" | 0건 | 31건 |
| 개발 도구 취약점 | 35건 | 0건 |
첫 화면에서 클릭할 수 있는 것이 29개였고 그중 8개가 테마 색·애니메이션 속도 같은 운동과 무관한 설정이었다. 가장 큰 자리를 차지한 것은 드래그로 돌리는 "3D 운동 기구"였는데, 실체는 SVG에 회전 한 줄이라 아무 값도 만들지 않았다. 걷어내고 10개로 줄였다. 모바일에서 첫 운동까지 3.3화면을 스크롤해야 했던 것도 1.6화면으로 줄였다.
배운 것
- 자동 검증을 통과한다고 도는 것은 아니다. 타입 검사와 테스트가 초록인데 배포는 33번 실패하고 있었다.
- 커밋 메시지는 증거가 아니다. 161개가 전부 "통과"라고 적혀 있었다. CI 상태를 따로 봐야 했다.
- 최적화는 측정부터. 31.7 KB를 쪼개려고 요청을 12회 늘리는 동안, 진짜 무거운 267 KB는 손대지 않았다.
- 숫자는 세어 보기 전까지 모른다. 1,008과 990의 차이는 강도 라벨 235개였다.
문서 안내
진행 로그·QA 리포트·디자인 방향 문서는 docs/archive 브랜치에 그대로 보관합니다. main 에는 콘텐츠의 근거가 되는 자료만 남깁니다.
라이선스
MIT License
