BOXCYCLE

문서 작성은 document/260509-BOXCYCLE-문서-생성-및-수정-지침.md를 따른다. 분류별 전체 목록은 document/README.md를 본다.

현재 단계·범위·스택·1차 마일스톤(멀티 유저 검증) 의 단일 진실은 document/archive/260509-BOXCYCLE-현재단계-범위-스택-및-1차마일스톤.md를 본다.

서비스 비전·UGC 정책·저장 전략(장기) 의 단일 진실은 document/reference/product/260511-RTW-마스터-비전-및-종합계획.md를 본다.

월드 맵 activity presence(publication dot·heartbeat 분리) 의 단일 진실은 document/reference/architecture/260523-World-Activity-Presence-설계.md를 본다.

Mapbox 기반 실내 사이클 서비스입니다. Mapbox 시뮬 검증은 완료되었으며, 본 개발 앱은 apps/web (Vite + TypeScript + React + Firebase Auth) 에서 진행한다.

본 개발 웹 앱 (apps/web)

웹 UI·지도·인증·로비는 apps/web 패키지(boxcycle-web, Vite + TypeScript + React + Firebase) 한 곳에서만 개발한다. Node 의존성은 npm workspaces 기준으로 저장소 루트에서 한 번만 설치한다(package-lock.json도 루트 하나). 루트 npm run dev / npm run build는 워크스페이스 boxcycle-web으로 위임된다.

• 인증: Firebase(Google·게스트 등 콘솔 설정에 따름).
• 경로 계산: Callable getMapboxDirections. 지도 타일은 클라이언트 VITE_MAPBOX_ACCESS_TOKEN(pk.).

1. Node.js LTS 설치
2. PowerShell(권장: 저장소 루트에서 설치·실행):

cd C:\20.HDev\boxcycle
npm install
git config core.hooksPath githooks   # 커밋/푸시 품질 게이트 활성화 (clone 후 1회)
Copy-Item apps\web\.env.example apps\web\.env
# apps\web\.env 에 Firebase 웹 앱 설정값 + VITE_MAPBOX_ACCESS_TOKEN(pk.) 입력 후 저장
npm run dev

apps/web만 열어 두었다면, 위와 동일하게 먼저 루트에서 npm install 한 뒤 apps/web에서 npm run dev를 써도 같은 워크스페이스를 가리킨다. apps/web에 별도 package-lock.json은 두지 않는다.

품질 게이트: git config core.hooksPath githooks를 1회 실행하면 githooks/pre-commit(변경 파일 eslint)·githooks/pre-push(변경 워크스페이스 typecheck)가 켜진다. 브랜치·커밋·푸시 운영 규칙은 document/260719-개발-워크플로-브랜치-커밋-게이트.

Firebase CLI: 프로젝트 연결은 저장소 루트의 .firebaserc(기본 프로젝트 ID)와 firebase.json을 쓴다. 명령은 루트에서 실행한다.

Firestore(프로필/Trailhead·Trail/라이드/코스 동기화): Firebase Console에서 Firestore Database 를 생성한다. 로그인 시 users/{uid} 문서에 표시 이름·이메일 등을 merge 저장한다. Trail presence는 trails/{trailId}/members/{uid}, Trail 주행 진행률은 trails/{trailId}/liveCourseRides/{uid}, 주행 요약은 rides, 코스는 courses, 입문 허브 동행은 coursePresence/{courseId}/members/{uid} 를 사용한다. rooms/ 레거시 데이터는 npm run admin:migrate-rooms-to-trails 로 이전한다(용어·배포 순서: document/reference/product/260517-제품-용어-Trailhead-Trail.md §8). 저장소 루트의 firestore.rules, firestore.indexes.json을 기준으로 적용한다.

Hosting: firebase.json 이 apps/web/dist 를 SPA(rewrites → index.html)로 배포하도록 설정되어 있다. 배포 전에 웹 앱을 빌드해야 한다.

cd C:\20.HDev\boxcycle
# Firestore 규칙·인덱스만
firebase deploy --only firestore
# 웹 빌드 + Hosting (또는 npm run deploy:hosting)
npm run build
firebase deploy --only hosting

Cloud Functions(Mapbox Directions 프록시): functions/ 에 Callable getMapboxDirections 가 있다. Mapbox secret 을 쓰므로 프로젝트가 Blaze(종량제) 여야 하는 경우가 많다.

cd C:\20.HDev\boxcycle
# 최초 1회: Secret Manager (저장소 루트에서 실행)
firebase functions:secrets:set MAPBOX_ACCESS_TOKEN
# 구독 Functions 배포·전체 deploy 시 필수 (Stripe 테스트/라이브 키 — 빈 Enter 금지)
firebase functions:secrets:set STRIPE_SECRET_KEY
firebase functions:secrets:set STRIPE_PRICE_ID
firebase functions:secrets:set STRIPE_WEBHOOK_SECRET

cd functions
npm install
npm run build
cd ..
firebase deploy --only functions

단일 함수만 배포해도(--only functions:courseActivityOnLiveCourseRideWritten 등) CLI는 전체 functions/src 를 분석하므로, 위 Stripe 시크릿에 ENABLED 버전이 없으면 배포 중 Secret Payload cannot be empty 가 날 수 있다. firebase functions:secrets:describe STRIPE_PRICE_ID 로 버전 표가 비어 있지 않은지 확인한다.

배포 후 웹 앱은 기본 리전 asia-northeast3 으로 Callable 을 호출한다. Functions 를 다른 리전에 두었다면 apps/web/.env 에 VITE_FUNCTIONS_REGION 을 맞춘다.

개발용 규칙 예시는 아래와 같다(운영 전 반드시 재검토).

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read: if request.auth != null;
      allow create, update: if request.auth != null && request.auth.uid == userId;
      allow delete: if false;
    }
    match /trails/{trailId}/members/{userId} {
      allow read: if request.auth != null;
      allow create, update: if request.auth != null && request.auth.uid == userId;
      allow delete: if request.auth != null && request.auth.uid == userId;
    }
  }
}

3. 브라우저에서 터미널에 표시된 주소로 접속한다.
   • 이 PC만: 개발 서버가 출력하는 localhost / 127.0.0.1 주소(기본 포트는 apps/web의 Vite 설정을 따름).
   • 같은 Wi-Fi의 다른 기기: 터미널에 출력되는 Network — http://192.168.x.x:… 형태의 주소를 사용한다. (apps/web 의 Vite 설정이 LAN 바인딩을 켜 두었다.)

LAN 접속이 안 될 때: Windows 방화벽에서 Node.js(또는 해당 포트) 허용 여부를 확인한다. 이 PC의 IP는 PowerShell에서 ipconfig → 무선 LAN 어댑터 Wi-Fi 의 IPv4 주소를 본다.

Firebase Google 로그인을 폰에서도 쓸 때: Firebase Console → Authentication → 설정 → 승인된 도메인에 192.168.x.x 같은 호스트만 추가할 수 없고, 정확한 호스트 문자열이 필요하다. IP가 바뀔 때마다 추가하거나, ngrok·Cloudflare Tunnel 등으로 고정 HTTPS 도메인을 쓰는 편이 낫다. (지도·로비만 테스트하고 로그인은 PC만 할 경우는 생략 가능.)

Mapbox 토큰 URL 제한을 쓰는 경우: 개발에 쓰는 http://localhost:… / http://127.0.0.1:… / LAN http://192.168.… 를 허용 목록에 넣는다.

LAN에 열지 않고 이 PC만: 루트에서 npm run dev:localhost (또는 cd apps/web 후 동일 스크립트)

Trail: 기본 Trail ID는 default 이다. 다른 Trail은 http://<호스트>:<포트>/?trail=my-ride (또는 ?room= 호환) 또는 MENU Trail 이동으로 전환한다. Firestore 경로는 trails/{trailId}/members/{uid} 이다.

Google 로그인 테스트는 Cursor 간이 브라우저(리디렉션 탭) 대신 Chrome / Edge 같은 일반 브라우저를 권장한다. 임베디드 탭에서 firebaseapp.com/__/auth/handler 가 흰 화면으로 멈추는 경우가 있다(팝업·쿠키·리디렉션 제한).

Firebase Console에서 Authentication → Google 사용 설정 및 Authentication → 설정 → 승인된 도메인을 확인한다.

• localhost와 127.0.0.1은 서로 다른 출처입니다. 브라우저에서 http://127.0.0.1:… 으로 열면 콘솔에 App domain is unauthorized 가 날 수 있다. 해결은 둘 중 하나다.
  1. 승인된 도메인에 127.0.0.1 을 추가하거나
  2. 항상 http://localhost:… 으로만 접속한다.
• .env를 저장한 직후에는 개발 서버를 한 번 재시작해야 Vite가 환경 변수를 반영한다.

빌드 확인: 루트에서 npm run build → 산출물은 apps/web/dist/ .

과거 정적 POC: Mapbox 검증용 HTML+단일 app.js 구현은 260508 개발 중간 보고에 기록되어 있다. 저장소 루트의 해당 파일은 제거하였다.

실행이 안 될 때 체크

• 개발자도구(Console)에 CORS, blocked, Access token 관련 에러가 있는지 확인
• Mapbox 토큰이 pk.로 시작하는 공개 토큰인지 확인
• Mapbox 토큰 URL 제한을 걸어둔 경우, 실제로 접속하는 호스트·포트를 허용 목록에 넣었는지 확인

본 개발 방향 (요약)

• 클라이언트: Vite + TypeScript + React → 최종 안드로이드는 웹 래핑(Capacitor 등) 우선
• 초기 데이터·백엔드: Firebase 로 서비스 동작·멀티 유저 검증 후 분리
• 인증(1차): Google(Gmail) 로 빠른 검증

상세는 위 현재 단계 문서 링크를 본다.