Just Judo
배포 대상: Vercel (GitHub 저장소 연동).
화면 주소
메인 주소는 https://justjudo.app/입니다. 하위 화면은 직접 접속·새로고침·브라우저 뒤로/앞으로 가기를 지원합니다.
| 화면 | 주소 경로 |
|---|
| 기초 / 띠 매는 법 | /basics / /basics/belt |
| 굳히기본 분류 | /katame-waza |
| 조르기 | /katame-waza/shime-waza |
| 꺾기 (레슨 준비 중) | /katame-waza/kansetsu-waza |
| 누르기 (레슨 준비 중) | /katame-waza/osaekomi-waza |
| 십자조르기 | /katame-waza/shime-waza/nami-juji-jime |
| 역십자 조르기 | /katame-waza/shime-waza/gyaku-juji-jime |
| 외십자 조르기 | /katame-waza/shime-waza/kata-juji-jime |
| 메치기본 (레슨 준비 중) | /throws |
기술과 굳히기 분류의 경로는 일본어 로마자 표기를 사용합니다. 화면의 한글 명칭은 유지하며, ?lang=en은 이동·새로고침 시 보존합니다. 화면의 메뉴 복귀 버튼은 해당 화면의 상위 분류로 이동합니다.
src/routes.js는 화면·상위 분류를 정의하고, vercel.json은 해당 경로만 앱 진입점으로 연결합니다. 없는 페이지와 정적 파일은 404를 반환합니다. 로컬 npm start는 동일한 경로를 지원하며, 빌드 검증용 /dist/ 아래에서도 동작합니다.
설치 없이 PC/노트북 웹브라우저에서 이용하는 유도 학습 도장입니다. Yuji Boku 붓글씨 서체의 柔道·基本·固技·投技, 종이 질감, 먹선, 붉은 낙관을 사용한 두루마리 도장 UI입니다. 상품 카드 대신 과정 칸과 기술 목록을 사용합니다. 특정 단체의 공식 서비스는 아닙니다.
메뉴와 현재 범위
첫 화면은 기초 → 굳히기본 → 메치기본 순서입니다.
- 기초: 띠 매는 법 시연·카메라 가이드를 이용할 수 있으며, 낙법은 준비 중입니다.
- 굳히기본: 조르기·꺾기·누르기로 나뉩니다. 조르기에서 십자조르기, 역십자 조르기, 외십자 조르기를 선택할 수 있으며, 꺾기와 누르기 레슨은 준비 중입니다.
- 메치기본: 다음 레슨을 위한 메뉴이며 아직 실행되지 않습니다.
조르기 기술마다 그립 개념 설명, 손바닥 방향 개념도, IJF 공식 설명·시범 링크, 연습 화면 옆 기술 설명, 웹캠 손 위치 예비 연습이 있습니다. 이전의 일반 팔 벌리기·V자·파워 포즈 동작은 제거했습니다.
미션과 기록
- 수련하기를 누르면 고정된 도복 상대 위에서 반투명 흰색 손이 준비 → 왼손 교차 → 오른손 교차 → 유지 → 풀기를 12초 주기로 시연합니다. 카메라는 아직 켜지지 않습니다.
- 내 동작 연습을 눌러 카메라를 연결하세요. 처음에는 카메라 권한을 허용합니다. 연결되면 3초 준비 후 연습이 시작됩니다. 기술 설명과 그립 방향은 오른쪽 패널에서 봅니다.
- 손가락을 굽힌 준비 자세로 손목을 교차해 각각 반대편 깃에 접근합니다. 카메라를 향하는 면은 십자조르기에서 양 손바닥, 역십자조르기에서 양 손등입니다. 반쯤 쥔 손도 100ms 이상 접촉하면 잡히며, 손목을 특정 대각선 각도로 기울이거나 손을 완전히 폈다가 쥘 필요는 없습니다. 깃 밖, 같은 쪽 깃, 반대 면, 앞뒤를 구분하기 어려운 손날 자세는 잡기로 인정하지 않습니다.
- 깃·앞섶·주름은 이완/주름 모임/중간 당김/팽팽함 네 단계의 벡터 그림으로 다시 그립니다. 좌우 앞섶의 그림은 손 위치와 팔꿈치 동작에 따른 작은 주름 모임으로 전환하며, 단계 사이에서는 선의 제어점만 보간합니다. 이미지 픽셀이나 텍스처 메시를 늘리지 않습니다. 목선과 허리띠는 고정됩니다. 목 가까운 위쪽 깃을 잡고 손 위치를 유지하면서 양 팔꿈치를 올린 상태를 1.2초 유지하면 가상 상대가 탭합니다. 손을 멀리 벌리는 동작은 점수를 주지 않습니다. TAP 안내 뒤 20 XP와 완료 도장이 기록됩니다. 네 손가락을 확실히 편 상태가 200ms 유지되면 깃을 놓습니다. 짧은 가림은 800ms 동안 그립을 보존하고 탭 진행을 멈춥니다. 인식이 돌아오면 같은 위치에서 이어가며, 800ms 이상 인식이 끊기면 놓습니다.
- 기술별 XP는 최초 1회 지급하며 다시 연습해도 중복되지 않습니다. 현재 연습 보상은 3종 합계 60 XP이며, 이전 퀴즈에서 받은 XP는 유지합니다.
진행도는 브라우저 localStorage의 just-judo-progress-v1에 저장합니다. 저장이 차단되면 현재 방문 동안만 동작하며 이를 화면에 표시합니다. 강도관 공식 영상 버튼은 선택한 기술의 YouTube 영상을 엽니다. 영상 창을 열면 연습은 정지되며, 닫으면 플레이어가 해제됩니다. 메뉴로 나갈 때 카메라와 추론 Worker를 종료합니다.
웹캠 판정의 범위
웹캠은 손의 21개 관절을 이용해 열린 손/주먹과 가상 깃의 접촉을 판정합니다. 실제 압박이나 실제 유도 기술의 효과를 측정하지 않습니다. 기술별 손바닥 방향은 설명 그림과 공식 영상을 함께 참고합니다.
- MediaPipe Pose Landmarker와 Hand Landmarker의 기존 모델과 설정을 유지합니다. 추론은 Worker에서 실행합니다.
- 어깨 너비를 기준으로 손을 고정된 상대 좌표에 투영합니다. 상대의 몸·머리 위치는 사용자 움직임을 따라가지 않습니다. 완료 시 상대의 한쪽 팔만 탭 동작을 합니다.
- 흰 장갑이 실제 손가락의 펴기·부분 쥐기·주먹·교차를 따라갑니다. 표시 좌표에는 적응형 필터와 보간을 적용합니다.
src/collar-interaction.js의 동일한 깃 곡선을 그리기와 잡기 충돌 검사에 사용합니다. 준비된 손의 반대편 깃 접촉과 카메라를 향한 손바닥/손등을 검사합니다. 중력 방향을 섞지 않은 카메라 깊이축 법선을 사용하므로 손목의 화면 내 회전은 앞뒤 판정에 영향을 주지 않습니다. 접촉 허용 반경은 어깨 폭의 13%입니다. 잡힌 지점은 손 중심에 붙으며 src/cloth-renderer.js의 네 단계 그림이 깃 경계를 공유하는 앞섶·주름·일정한 크기의 바늘땀을 직접 그립니다. 목선과 허리는 고정됩니다.- 잡은 깃 하나당 25점, 위쪽 깃과 손 방향을 유지한 양 팔꿈치 상승으로 최대 50점을 더합니다. 양쪽 깃을 잡았을 때 팔꿈치와 같은 쪽 어깨·손목의 높이 차이를 기록하고, 두 기준에서 줄어든 높이 차이 중 작은 값을 사용합니다. 어깨 너비의 15% 상승에서 100%이며, 양쪽 모두 70% 이상을 1.2초 유지하면 완료합니다. 실제 기술의 의학적·역학적 임계값이 아닌 화면 미션의 허용 범위입니다. 한쪽 팔꿈치만 올리기, 몸 전체 이동, 어깨만 들기, 손과 팔꿈치를 같이 들어 올리기로는 완료되지 않습니다.
- 화면의 팔꿈치 비율은 관찰 가능한 상승 동작만 나타냅니다. 뒷목 안쪽 그립의 실제 깊이·힘·압박은 측정하지 않습니다. 위쪽 깃의 화면 위치는 깊은 그립을 설명하기 위한 대리 지표입니다.
- 확실한 놓기, 몸까지 사라진 상태의 800ms 이상 인식 끊김, 거울 전환, 재시작 시 잡기 상태를 해제합니다. 양손으로 이미 잡았고 몸이 보이면 손 가림이 길어져도 그립을 보존하며 채점만 멈춥니다. 한 손만 잡은 상태의 인식 끊김에는 기존 800ms 해제를 적용합니다. 잡힌 깃은 급격히 바뀐 손 위치를 반복 검출해도 따라가지 않습니다. 마지막 정상 위치에서 이어지는 작은 이동만 반영하며, 횡방향 손 이동은 완료 점수를 주지 않습니다. 놓은 깃은 이완 그림으로 돌아옵니다.
- 신체/손이 인식되지 않으면 점수 대신 대시를 표시합니다. 팔 위치만 맞추거나 손을 펴고 대기하는 것으로는 완료되지 않습니다.
- 카메라 영상은 저장하지 않습니다. 추적 오류가 나도 영상과 재연결 버튼을 유지합니다.
영상을 서버로 전송하거나 저장하지 않습니다. 최초 카메라 연결 시 jsDelivr의 고정 버전 @mediapipe/[email protected]와 Google Storage의 모델 파일을 다운로드합니다. 글꼴은 Google Fonts를 사용하며 실패하면 시스템 글꼴로 표시됩니다. 웹캠에는 HTTPS 또는 localhost가 필요합니다.
기술 참고
명칭과 그립 구분은 다음 IJF 자료를 참고했습니다. 자체 제작한 손 위치 예비 연습은 공식 지도 과정이나 기술 인증이 아닙니다.
개발과 배포
Node.js 20 이상, 별도 앱 의존성 설치 없이 실행합니다.
npm start
# http://localhost:5173
npm test
Vercel에서 Ocean-Eyes/VibeCoding_V2 저장소를 Import하세요. Root Directory는 저장소 루트(.)이며, vercel.json이 Build Command npm run build, Output Directory dist, Framework Other를 설정합니다. 별도 환경 변수는 필요 없습니다. GitHub Pages 자동 배포는 중단했고 기존 워크플로는 수동 실행만 가능합니다.
빌드는 HTML·CSS·모든 로컬 JS 모듈 및 Worker URL에 동일한 콘텐츠 버전을 붙여 이전 캐시와 새 파일이 섞이는 것을 방지합니다. Vercel 응답은 캐시 재검증을 사용합니다.
Playwright 패키지가 있는 환경에서:
node scripts/browser-dojo.cjs <Playwright 패키지 경로>
node scripts/browser-regressions.cjs <Playwright 패키지 경로>
npm run build
node scripts/browser-entry.cjs <Playwright 패키지 경로>
node scripts/browser-demonstration.cjs <Playwright 패키지 경로>
SITE_URL 환경 변수로 배포 사이트를 검사할 수 있습니다. 도장 검사에는 메뉴·즉시 연습 진입·기술별 설명·저장·중복 XP 방지·강도관 영상 연결·기본 관절 숨김·가상 상대 탭·가상 카메라의 실제 모델 초기화·메뉴 복귀 시 카메라 해제·반응형 레이아웃이 포함됩니다. 미션 완료 흐름은 합성 관절을 주입하여 검증합니다. 회귀 검사는 공개 인물 사진을 영상 입력으로 사용하며 오류도 강제로 주입합니다. 이 검사는 실제 사용자가 유도 동작을 하는 웹캠 환경의 인식률 검증을 대신하지 않습니다.
강도관 영상 링크는 강도관 공식 기술 목록에서 확인했습니다. 영상 임베드가 제한되면 플레이어 아래 YouTube 링크를 이용합니다. 가상 상대의 탭은 깃 위치와 양 팔꿈치 상승 유지로 발생하는 게임 이벤트이며 실제 압박의 시뮬레이션이 아닙니다.
진입 회귀 검사(browser-entry.cjs)는 빌드 산출물에서 구형 Canvas 환경, 이전 무버전 모듈 캐시, 연습 모듈 로드 실패, 로딩 중 메뉴 복귀를 확인합니다. 연습 모듈 초기화는 메뉴에서 분리되어 실패해도 기술 설명과 메뉴 복귀는 사용할 수 있습니다.
Portrait image
assets/jigoro-kano.jpg: the user-selected portrait of Kano Jigoro (378 x 469).
Source: Wikimedia Commons, Kano Jigoro.jpg, listed as public domain (PD-Japan-oldphoto / PD-1996).
The original photograph is included unchanged; the frame is drawn with CSS.
교차 그립 도식의 기준
강도관 기술 정의와 IJF의
십자조르기,
역십자조르기를 기준으로 구분합니다.
십자는 양 엄지가 안쪽·손바닥 아래·양손 밀기, 역십자는 양손의 네 손가락이 안쪽·손바닥 위·양팔 조이기입니다.
외십자는 왼손 네 손가락 안쪽·당기기와 오른손 엄지 안쪽·밀기의 조합입니다.
설명 그림과 시연은 동일한 V자 깃과 교차 손목 배치를 사용합니다. 손등을 보는 닫힌 그립에서는 접힌 손끝과 손톱을 그리지 않습니다.
시연의 팔 움직임은 작용 방향을 표현하는 2D 도식입니다. 점수는 가상 깃 위치와 팔꿈치 상승만 평가하며 실제 깃 안팎이나 압박은 판정하지 않습니다.
참고 자료 기반 손 모델
사용자가 제공한 references/ms_arm_and_hand의 AAH 모델에서 손목 이하 28개 body의 관절 위치·축·범위와 말단 골격 STL의 손끝 위치를 추출했습니다. references/hands.md의 MediaPipe 순서대로 21개 관절점을 구성합니다. 좌우 손은 해부학적 속성이며, 화면 좌우 위치나 카메라 반전으로 바꾸지 않습니다. 손바닥 전환은 깊이축까지 회전시킵니다.
src/hand-rig-data.js는 원본 XML의 SHA256을 기록합니다. src/hand-rig.js가 범위 내 관절 회전과 뼈 길이를 유지합니다. 피부·흰 장갑 표면은 이 골격을 감싸도록 별도로 만든 부드러운 표면이며, 원본 자료에 피부 메시가 포함되어 있다는 의미는 아닙니다. 압박·깃 마찰을 계산하는 생체역학 시뮬레이터도 아닙니다.
실행 시 GPU에 의존하지 않도록 관절 모델의 좌우·앞뒤·재질 렌더와 엄지가 완전히 가려진 네 가지 그립 변형을 assets/hands-aah-v1/에 저장합니다. 실패한 AI 생성 사진은 앱에 사용하지 않습니다. 원본 모델의 MIT 고지는 assets/AAH-LICENSE.txt에 포함했습니다. 큰 원본 참고 폴더는 배포물에 포함하지 않습니다.
재생성 (저장소 루트에서 로컬 서버 실행 후):
python scripts/extract-hand-rig.py
node scripts/render-hand-assets.cjs <Playwright 패키지 경로>
node scripts/browser-hand-rig.cjs <Playwright 패키지 경로>
실시간 흰 장갑
자동 시연에서는 AAH 참고 모델의 고정 그립을 사용합니다. 카메라 연습에서는 기존 MediaPipe HandLandmarker가 반환한 21개 관절을 매 프레임 흰 장갑 표면으로 그립니다. 손가락마다 굽힘을 반영하며, 두 손의 검출 순서가 바뀌어도 몸의 좌우 손목과 직전 위치를 이용해 동일한 손에 연결합니다. 상대 캐릭터는 고정됩니다.
src/live-hands.js의 적응형 필터와 프레임 사이 보간은 표시 좌표에만 적용합니다. 원래 인식 모델과 신뢰도 설정을 유지합니다. 채점은 가상 깃 위치와 팔꿈치 상승을 사용합니다. 손 가림 중에는 마지막 장갑을 최대 350ms 흐리게 유지하고 채점 관측에서는 제외합니다. 위치가 다시 확인되면 150ms 동안 이어 그리며 이 보간 중에도 채점을 멈춥니다. 현실의 깃 접촉이나 압박의 적절성은 채점하지 않습니다.
src/live-glove.js는 관절 구체나 손톱 없이 손바닥과 다섯 손가락의 윤곽을 한 표면으로 합성합니다. 접힌 손가락은 둥근 끝을 가진 구간들의 합집합으로 채워 윤곽선 역전이나 구멍을 방지합니다. 자동 시연용 흰 장갑 PNG도 같은 렌더러로 생성합니다. 손바닥은 넓은 음영과 얕은 주름으로 구분하고 팔목은 팔꿈치 방향으로 흐려집니다. GPU 렌더러 없이 Canvas 2D에서 동작합니다. 그립 설명과 자동 시연에서는 이어진 도복 깃을 엄지/손끝 앞에 겹쳐 깃 안쪽으로 들어가는 부분을 표현합니다.
node --test tests/*.test.mjs
node scripts/browser-live-hands.cjs <Playwright 패키지 경로>
실시간 장갑 검사는 합성 관절로 펴기·부분 쥐기·주먹·교차, 검출 순서 반전, 거울 모드, 추적 끊김·복구, 모바일 화면과 카메라 해제를 검증합니다. 실제 웹캠의 손가락 인식 정확도는 조명과 손 가림에 영향을 받으며 이 검사의 측정 범위에 포함되지 않습니다.
깃 위치·팔꿈치 통합 검사
node scripts/browser-collar-grip.cjs <Playwright 패키지 경로>
합성 카메라 관절을 실제 연습 화면에 주입하여 깃 위에서 펴기→쥐기, 구부린 손으로 교차 접근할 때 잡기 허용, 두 깃의 부착·변형, 양옆으로 크게 당기기와 한쪽 팔꿈치만 올리기에서 완료 거부, 손을 유지한 양 팔꿈치 상승 후 탭·XP, 놓은 뒤 복원, 추적 끊김, 모바일을 검사합니다. tests/collar-interaction.test.mjs는 잡힌 깃 좌표가 손 중심과 일치하고 연결된 앞섶이 함께 움직이며 목선과 허리가 고정되는지, 기술별 손바닥 방향과 교차 자세도 검사합니다. 실제 사용자 웹캠의 인식률을 측정한 결과는 아닙니다.
캐릭터는 이전 대비 약 25% 확대해 표시하며, 실시간 깃 안내는 양손 높이를 조금 달리합니다. 확대는 화면 표시의 변화이며 웹캠에서 겹쳐 가려진 관절을 복원하지는 않습니다. 인식 모델과 필터는 변경하지 않았습니다.
node scripts/browser-cloth-states.cjs <playwright-package-path>는 이완·잡기·주름 모임·중간 당김·양손 당김·왼손만 당김·오른손만 당김·복원의 비교 그림을 .test-output/cloth-drawing-states.png에 저장합니다. 옷 렌더링의 비트맵 그리기 호출을 금지한 상태로 각 그림의 깃/앞섶 연결, 고정된 머리와 놓기 후 복원을 검사합니다. 그립 검사는 짧게 손·팔꿈치가 가려져도 깃은 유지하고 점수 진행은 멈추는 경로를 포함합니다. 팔꿈치 가림이 800ms를 넘으면 유지 시간을 초기화하지만 손이 보이면 깃을 놓지는 않습니다.
그립을 잡은 동안에는 잡기 직전의 어깨 너비와 축을 유지하고, 몸 전체 이동은 어깨 중심으로 보정합니다. 팔꿈치는 같은 쪽 어깨와 손목을 기준으로 비교하므로 몸 이동이나 어깨 들기를 상승 동작으로 계산하지 않습니다. 좌우 팔꿈치 진행률을 화면에 표시합니다.
교차 가림과 손 위치 튐
HandIdentityTracker는 좌우 손 이력과 이동 예측을 보존하며, 겹치는 구간에서는 몸 모델의 손목이 뒤바뀌어도 그 위치를 그대로 따라 손을 교환하지 않습니다. 거의 같은 곳에 중복 검출되거나 한 손의 소속을 구분하기 어려우면 관측을 보류합니다. HandStream은 순간 위치 점프와 비정상적으로 늘어난 손가락을 걸러냅니다. 정상적인 15fps 손 이동을 허용하면서 큰 위치 점프를 거부합니다. 마지막 정상 위치 근처로 돌아오면 추적을 이어갑니다. 잡힌 깃이 없는 상태에서 마지막 정상 관측이 900ms 이상 지났고 새 위치가 200ms 이상 안정되면 새 추적을 시작합니다. 새 손은 200ms 동안 서서히 나타나며 이 동안 채점하지 않습니다. 실제 손 관측이 600ms 이상 끊긴 후 재등장하는 경우에도 새 위치에서 시작할 수 있습니다. 겹침의 중복 검출 범위는 손 전체 길이가 아닌 손바닥 폭으로 정합니다. 350ms 표시 보존과 150ms 복귀 보간은 화면 표시용이며, 보존·보간 좌표는 점수에 사용하지 않습니다. MediaPipe 모델 파일과 추론 설정은 그대로입니다.
단위 검사는 검출 순서 반전·교차 중 몸 모델 손목 교환·모호한 중복 손·한 프레임 위치 점프·가림 복귀·빠른 정상 이동·손가락 이상치를 재현합니다. 실제 사용자 웹캠에서의 가림 복원 정확도를 측정한 것은 아닙니다.
깃 접촉 허용 범위와 옷 변형은 분리합니다. 처음 잡을 때 손과 깃 사이의 거리는 접촉 오프셋으로 보존하고, 잡기 이후의 손 이동만 반영합니다. 목선 인근의 변형 가중치와 합산 변위를 제한해 작은 움직임이 옷 전체에서 증폭되지 않도록 했습니다. 앞섶의 이완 윤곽도 잡은 높이에 따라 갑자기 바뀌지 않습니다.
안정성 회귀 검사는 tests/cloth-stability.test.mjs와 scripts/browser-cloth-stability.cjs에 있습니다. 4,032가지 한 손·양손 접촉 위치·손 방향·거울 설정에서 최초 잡기 전후 캔버스 픽셀이 동일한지 비교하고, 128개 난수 시드의 23,040프레임에서 잡음·반복 급변·복귀를 검사합니다. 목선과 허리 고정, 변위 증폭 제한, 한쪽을 먼저 잡은 뒤 반대쪽 잡기도 검사합니다. 브라우저 입력은 합성 손 좌표이며 실제 웹캠에서의 인식 정확도를 검증한 결과는 아닙니다.
src/cloth-motion.js는 손 인식 필터와 별개로 화면에 그리는 깃 변형을 제한합니다. 최대 변위는 상대 어깨 너비의 24%, 이동 속도는 초당 35%이며 한 프레임의 적분 시간은 50ms 이하입니다. 충돌 판정과 옷 그림에 같은 좌표를 사용합니다. 따라서 손 추적을 정상화하더라도 옷이 한 프레임 만에 화면 밖으로 늘어나지 않습니다.
node scripts/browser-single-grip.cjs <playwright-package-path>는 보고된 목선 위 한 손 잡기를 앱의 카메라 입력부터 렌더링까지 검사합니다. 좌우 손·십자/역십자·거울 설정·PC/모바일 16가지 조합에서 잡기 전후 옷 픽셀과 캔버스 크기를 비교합니다. SITE_URL을 배포 주소로 지정하면 같은 검사를 실제 배포된 모듈에 실행합니다. npm test에도 옷 안정성 검사를 포함합니다.
양손으로 깃을 잡은 뒤 팔꿈치를 돌려 손이 반대 손목·팔뚝에 가려질 때, CollarInteraction은 손 미검출과 불확실한 손가락 모양을 놓기로 처리하지 않습니다. 손바닥이 반대 손목·팔뚝과 겹치면 놓기와 채점을 보류합니다. 가림 뒤 손을 편 상태로 나타나면 300ms 동안 관측이 이어진 후 기존 200ms 놓기 판정을 적용합니다. 닫힌 손이 정상 위치로 돌아오면 다시 잡을 필요 없이 기존 깃을 이어갑니다. 가림 중에는 완료 시간이 늘어나지 않으며, 800ms를 넘으면 완료 유지 시간만 초기화합니다. 몸이 보이는 동안 양손 모두 미검출되어도 잡기를 보존하므로 손을 보이게 펴거나 연습 초기화 버튼으로 해제할 수 있습니다.
방문자 통계 (Vercel Visitors)
왼쪽 숫자는 별도 Redis 브라우저 카운터가 아니라 Vercel Web Analytics의 누적 data.visitors를 읽습니다. /v1/query/web-analytics/visits/count를 기간 제한 없이 호출하므로 production의 수집 시작부터 누적값입니다. 조회수(pageviews)나 국가별 합계를 대신 표시하지 않습니다. 국가별 숫자는 숨깁니다.
Vercel 프로젝트의 Settings → Environment Variables → Production에 다음 값을 설정하고 재배포하세요. 토큰은 서버에서만 사용하며 저장소·브라우저·채팅에 넣지 않습니다.
VERCEL_ANALYTICS_TOKEN: 이 프로젝트의 Web Analytics를 읽을 권한이 있는 Vercel access token.VERCEL_ANALYTICS_PROJECT_ID: 대상 프로젝트 ID (prj_...). 없으면 시스템의 VERCEL_PROJECT_ID 사용.VERCEL_ANALYTICS_TEAM_ID: 팀 소유 프로젝트의 팀 ID (team_...). 개인 프로젝트는 생략.
API 권한/환경변수 설정 전에는 —와 연결 안내를 표시합니다. 기존 자체 카운터 5명이나 0명으로 대체하지 않습니다. 성공 응답은 5분 캐시하고 재검증 동안 1분까지 이전 값을 제공할 수 있습니다. Vercel 대시보드도 동일한 누적 기간·production·전체 프로젝트 기준으로 비교해야 합니다. 공식 문서: https://vercel.com/docs/analytics/web-analytics-api
기존 ?exclude_visits=1은 Vercel beforeSend를 통해 해당 브라우저의 향후 이벤트를 제외합니다. ?exclude_visits=0으로 해제합니다. 이미 Vercel에 저장된 방문 기록을 소급 삭제하지 않습니다. Redis의 예전 방문자 자료는 수정/삭제하지 않으며 배밀기 랭킹의 Redis 연결도 그대로 유지합니다.
검증: npm run test:visitors, node scripts/browser-visitors.cjs <Playwright 경로>. API 테스트는 공식 응답 스키마의 모의 응답을 사용합니다. 실제 Vercel 수치와의 일치는 환경변수 설정 후 확인해야 합니다.
