Bullpen Log

투수를 위한 훈련·기록 웹앱. 던진 양을 기록하면 부하를 계산해 오늘 얼마나 던져도 되는지 알려주고, 몸상태에 맞는 운동을 골라주고, 투구 영상에서 폼을 측정한다.

설계 원칙 하나만 기억하면 된다 — 숫자와 판정은 전부 코드가 낸다. AI 는 쓰지 않는다(2026-10-07 뺐다, docs/ai-usage.md). 통증이 잡히면 병원 안내로 보낸다.

---

처음 실행하기

맥과 윈도우 양쪽에서 개발한다. 명령이 다른 곳은 그때그때 적어둔다. 윈도우는 PowerShell 기준이며, 예전 명령 프롬프트(cmd)가 아니다.

1. 필요한 것

• Node.js 22 이상 (개발은 24에서 하고 있다) — nodejs.org 의 LTS
• Git — 맥은 거의 깔려 있고, 윈도우는 따로 받아야 한다 (git-scm.com)
• Supabase 계정 — Postgres와 영상 저장소로 쓴다

2. 받아서 설치

git clone https://github.com/Bullpen-Log/bullpen-log.git
cd bullpen-log
npm install

3. 환경변수

.env.example을 .env로 복사하고 값을 채운다.

# 맥
cp .env.example .env
open -e .env

# 윈도우 (PowerShell)
Copy-Item .env.example .env
notepad .env

⚠️ 윈도우에서 파일 탐색기로 .env 를 새로 만들지 말 것. 확장자를 숨기는 설정 때문에 .env.txt 가 만들어지는데, 겉보기엔 똑같아서 왜 안 되는지 한참 헤매게 된다. 위처럼 복사한 뒤 열어서 고치면 그럴 일이 없다.

변수	어디서 얻나
DATABASE_URL	Supabase → Project Settings → Database → Connection string. 포트 6543(풀러)
DIRECT_URL	같은 화면의 포트 5432. 마이그레이션 전용 — 6543으로는 멈춘다
SESSION_SECRET	openssl rand -base64 32 로 직접 만든다
SUPABASE_URL	Supabase → Project Settings → API
SUPABASE_SERVICE_ROLE_KEY	같은 화면. 비밀키다. 절대 커밋하지 않는다
ADMIN_EMAIL	본인 이메일. 이 이메일로 가입할 때 관리자 권한이 붙는다

.env는 .gitignore에 막혀 있어 깃에 올라가지 않는다. 그래서 새로 받은 사람은 이 파일을 직접 만들어야 한다.

4. DB 준비

여기서 두 갈래로 나뉜다. 자기가 어느 쪽인지 먼저 확인할 것.

(가) 이미 돌아가는 Supabase에 합류하는 경우 — 팀원이라면 보통 이쪽

같이 쓰는 DB에는 표가 이미 다 만들어져 있다. 만들 게 없고, 코드가 DB를 읽을 수 있게 클라이언트만 생성하면 된다.

npx prisma generate --schema=prisma/schema.prisma

⚠️ prisma migrate dev 를 실행하지 말 것. 남과 같이 쓰는 DB에서 이 명령을 쓰면, 상황에 따라 표를 전부 지우고 다시 만들겠느냐고 물어온다. 무심코 넘기면 다른 사람 기록까지 사라진다. 표 구조를 바꿔야 할 일이 생기면 혼자 하지 말고 팀에 먼저 말할 것.

5번은 건너뛴다. 저장소는 이미 만들어져 있다.

(나) 내 Supabase를 새로 만든 경우

npx prisma migrate dev --schema=prisma/schema.prisma

--schema 플래그를 빼면 "Specify a schema" 오류가 난다. 이 프로젝트는 prisma.config.ts를 쓰기 때문에 명시해줘야 한다. 매번 붙인다고 생각하면 편하다.

5. Supabase Storage 버킷 — (나)인 경우에만

영상 업로드에 비공개 버킷 pitch-videos가 필요하다. Supabase → Storage에서 만든다. 공개로 만들면 안 된다 — 남의 투구 영상이 URL만 알면 다 보인다. 앱은 서명된 임시 URL로만 재생한다.

6. 실행

npm run dev

http://localhost:3000

---

자주 쓰는 명령

npm run dev      # 개발 서버
npm run build    # prisma generate + migrate deploy + next build
npm run lint     # eslint
npx tsc --noEmit # 타입 검사 — 커밋 전에 한 번 돌리면 좋다
npm run backup   # DB 전체를 ~/bullpen-log-backups 에 JSON 으로 받아둔다

여럿이 같은 DB를 보고 개발하면 누군가 실수로 지우는 일이 언젠가 생긴다. 표 구조를 바꾸거나 데이터를 손대기 전에 npm run backup 을 한 번 돌려두면 마음이 편하다.

---

코드가 어디 있나

경로	무엇
app/(app)/	로그인한 사람이 보는 화면들 (홈, 투구기록, 트레이닝, 분석 · 그래프…)
app/(session)/	운동하는 동안만 쓰는 전용 화면 (워밍업 · 실시간 운동). 메뉴·탭바 없이 화면을 꽉 채운다
app/actions/	서버 액션 — 폼 제출을 받아 DB에 쓴다
lib/report/	부하 계산, 투구 계획, 운동 처방. 앱의 두뇌. 숫자는 전부 여기서 나온다
lib/pose/	영상 → 관절 추출(extract) → 구간 감지(detect) → 지표 측정(measure)
lib/workout/	운동 한 판(세션) — 시작할 때 목록 얼려 두기, 세트 요약, 워밍업 루틴 고르기
prisma/schema.prisma	DB 구조

값을 바꿀 때 한 곳만 고치면 나머지가 따라오게 만들어 둔 배열들이 있다. 이런 건 그 배열만 고치면 된다.

• lib/checkin.ts의 CHECKIN_PARTS — 체크인 부위
• lib/session-type.ts의 SESSION_TYPES — 투구 종류
• lib/nav.ts의 NAV_GROUPS / MOBILE_TABS — 메뉴

---

같이 작업할 때

지금은 둘 다 main에 바로 올린다. 아직 실제 사용자가 없어서 브랜치와 Pull Request 를 거치지 않고 간단하게 간다. 나누는 기준은 영역이다 — 트레이닝 / 투구일지·기록·인터페이스.

main에 올리면 곧바로 실제 사이트(bullpen-log.vercel.app)에 배포된다. 그래서

• 시작하기 전에 항상 최신을 받는다. 상대가 올린 것 위에서 시작해야 부딪히는 일이 적다.
• 올리기 전에 npm run lint 와 npx tsc --noEmit 을 돌린다. 빌드가 깨진 채로 올라가면 그 뒤로 상대가 올리는 것까지 배포가 멈춘다.
• 작게, 자주 올린다. 이미 있는 화면을 깨뜨린 채로 올리지는 않는다.
• DB 를 건드릴 때는 AGENTS.md 의 규칙을 따른다. prisma migrate dev 금지, 구조 변경은 한 명씩 · 미리 말하고 · 백업부터.

# 시작할 때
git pull

# 끝날 때
git add -A
git commit -m "무엇을 왜 바꿨는지"
git pull     # 그사이 상대가 올린 것을 먼저 받는다
git push

git pull 에서 충돌(conflict)이 나면, 둘이 같은 파일의 같은 곳을 고친 것이다. 억지로 덮어쓰지 말고 상대와 먼저 이야기한다.

커밋 메시지

무엇을 바꿨는지보다 왜 바꿨는지를 적는다. 코드를 보면 무엇인지는 알 수 있지만 왜인지는 알 수 없다.

윈도우에서 자주 걸리는 것

npm 을 쳤는데 "이 시스템에서 스크립트를 실행할 수 없으므로" 라는 오류가 날 때

PowerShell 이 기본으로 스크립트 실행을 막아둔 탓이다. PowerShell 에서 한 번만 실행하면 된다.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

관리자 권한도 필요 없고, 내 계정에만 적용된다.

줄바꿈 경고(LF will be replaced by CRLF)가 뜰 때

무시해도 된다. .gitattributes 가 저장소 안에는 항상 LF 로 담기도록 잡아두고 있어서, 맥과 윈도우가 서로 다른 줄바꿈을 커밋하는 일은 생기지 않는다.

손대기 전에 알아둘 것

• 부하 계산식(투구수 × 강도)과 안전 규칙은 함부로 완화하지 않는다. 후보 운동이 부족하다고 통증 차단이나 강도 제한을 푸는 방향은 안 된다. 부족하면 부족하다고 말하는 편이 맞다.
• AGENTS.md에 적힌 대로, 이 Next.js는 버전이 앞서 있어 익숙한 API와 다를 수 있다. 헷갈리면 node_modules/next/dist/docs/를 본다.
• 맥에서 iCloud 동기화 때문에 .next 안에 파일 2.js 같은 중복이 생겨 타입 검사가 깨질 때가 있다. 그럴 땐 find .next -name "* 2.*" -delete. 윈도우 데스크탑에서도 작업합니다.