HANDOFF.md

Tranimal Run 인수인계서

마지막 갱신: 2026-08-26
이 문서는 다른 컴퓨터·다른 Codex 작업에서 같은 프로젝트를 안전하게 이어가기 위한 기준 문서입니다. 비밀번호, 토큰, DB 접속 문자열, 서명 키 파일은 절대 이 문서나 Git에 기록하지 않습니다.

1. 공유 원칙

Git은 소스 코드, DB 마이그레이션, 설정 템플릿, 배포 정의, 작업 이력을 공유합니다. 다른 기기에서는 해당 저장소를 내려받으면 같은 코드 기준점에서 작업할 수 있습니다.

단, 다음은 Git으로 이동하지 않으며 별도로 안전하게 전달해야 합니다.

Git으로 공유되지 않는 항목	이유	전달 방법
.env와 API 토큰	비밀 정보	비밀번호 관리자 또는 암호화된 개인 저장소
Hugging Face Space의 Secrets/Variables	배포 플랫폼 설정	새 기기에서 Space 설정 화면으로 확인·수정
EC2 PostgreSQL DB와 접속 정보	원격 운영 데이터	기존 DB를 그대로 사용하고 접속 문자열만 비공개 전달
Android signing.keystore·키 비밀번호	앱 서명 비밀	암호화된 USB/비밀번호 관리자로만 전달
node_modules, .next, Gradle 빌드 결과	재생성되는 대용량 파일	새 기기에서 의존성 설치·빌드
ADB 무선 디버깅 페어링	기기별·일회성 정보	새 PC에서 다시 페어링

권장 방식: 전체 D:\Capstone_projects 폴더를 클라우드 드라이브로 복사하지 말고, 소스는 Git으로 공유하고 비밀값·서명키만 별도로 전달합니다. 빌드 캐시나 DB 덤프까지 섞여 용량과 보안 문제가 생기는 것을 방지합니다.

2. 프로젝트별 기준 저장소

영역	로컬 위치	Git 기준	역할	현재 주의점
메인 서비스	D:\Capstone_projects\Tranimal_Run	https://github.com/hwangtutu/Tranimal_Run.git / DemoService	웹, API, AI, DB 마이그레이션, Hugging Face 배포	이 브랜치 푸시가 배포 기준
워치·휴대폰 동반 앱	D:\Capstone_projects\capstonWearOS	같은 저장소 / WearOS	Galaxy Watch 센서 수집, 휴대폰 중계, Data Layer	이 문서 작성 시점에 미커밋 변경이 존재함. 기기 이동 전 반드시 별도 커밋 필요
Android TWA 패키지	D:\Capstone_projects\frontend_demo\TranimalTwa	현재 독립 Git 저장소가 아님	배포 웹을 감싸는 실제 휴대폰 앱	별도 비공개 저장소를 만들어 관리해야 함. signing.keystore는 절대 커밋하지 않음

메인 서비스 배포는 GitHub의 DemoService 브랜치와 Hugging Face Space tkadkghdlf/CD가 연결된 방식입니다. .github/workflows/sync-huggingface-space.yml가 GitHub Secret HUGGINGFACE_TOKEN을 사용해 동기화합니다.

3. 새 컴퓨터에서 메인 서비스를 이어가는 방법

3-1. 처음 한 번만

PowerShell에서 아래 명령을 한 줄씩 실행합니다.

git clone --branch DemoService https://github.com/hwangtutu/Tranimal_Run.git D:\Capstone_projects\Tranimal_Run
cd D:\Capstone_projects\Tranimal_Run
git status

그 뒤 새 PC에 Node.js, Docker Desktop(로컬 실행이 필요할 때), Android Studio/SDK(앱 작업이 필요할 때), Git을 설치합니다. 의존성은 소스 폴더에서 다시 설치합니다.

cd D:\Capstone_projects\Tranimal_Run\main
npm ci

로컬 API·AI 서비스를 실행해야 할 때만 루트 폴더의 Docker 구성과 .env를 준비합니다. 운영 DB 접속 문자열을 임의로 바꾸거나 새 DB를 만들지 않습니다.

3-2. 매 작업 시작 전

작업 폴더에서 아래 명령을 순서대로 실행합니다.

cd D:\Capstone_projects\Tranimal_Run
git status
git fetch origin
git switch DemoService
git pull --rebase origin DemoService

git status에 변경이 보이면 먼저 그 변경을 커밋하거나 별도 백업한 뒤 내려받습니다. 변경된 파일이 있는 상태에서 무리하게 pull하거나 reset하지 않습니다.

3-3. 작업 완료 후

cd D:\Capstone_projects\Tranimal_Run
git add -A
git commit -m "작업 내용을 설명하는 메시지"
git push origin DemoService

배포 대상은 DemoService이므로, 실제 서비스에 반영해도 되는 검증된 변경만 이 브랜치에 푸시합니다. 규모가 큰 작업은 별도 작업 브랜치에서 만든 뒤 검토 후 DemoService에 반영합니다.

4. 비밀 설정과 운영 DB

절대 Git에 넣지 않을 것

• .env, .env.local, DB URL, 비밀번호, JWT/SMTP/OAuth 토큰
• Hugging Face 액세스 토큰
• Android signing.keystore, 키스토어·키 별칭 비밀번호
• 로그인 정보 파일과 개인 인증서

.gitignore에 이미 포함돼 있더라도, git status로 매번 확인합니다. 채팅·스크린샷·커밋 메시지에도 비밀값 전체를 넣지 않습니다.

배포 설정 확인 위치

Hugging Face Space tkadkghdlf/CD의 Settings → Secrets/Variables에서 기존 값을 유지합니다. 특히 아래 이름의 값은 누락되면 로그인·DB·배포 기능이 동작하지 않을 수 있습니다.

• AUTH_DATABASE_URL — EC2 PostgreSQL의 운영 접속 문자열
• JWT_SECRET_KEY
• PROTOTYPE_PGVECTOR_URL, TEXT_PROTOTYPE_PGVECTOR_URL — 사용하는 경우
• NEXT_PUBLIC_API_BASE_URL, NEXT_INTERNAL_API_PROXY_TARGET, CORS_ORIGINS 등 배포 환경 변수
• 선택 기능의 Google/SMTP 관련 값

운영 DB는 EC2 PostgreSQL로 이전되어 있습니다. 새 컴퓨터에서 소스를 내려받아도 DB 데이터는 자동으로 복제되지 않습니다. 같은 운영 DB의 비공개 접속 설정을 사용하면 기존 사용자·러닝·경로 데이터가 그대로 보입니다. DB를 초기화하거나 마이그레이션 이력을 임의로 삭제하지 않습니다.

5. 시스템 구조

Galaxy Watch 센서
  → Wear OS 러닝 세션 / Data Layer
  → Android 휴대폰 동반 앱
  → 인증 서비스 API / EC2 PostgreSQL
  → 웹 서비스(Next.js) 및 결과·통계 화면

웹 브라우저는 워치와 Bluetooth로 직접 통신하지 않습니다.

워치는 네트워크 연결을 전제로 하지 않고 휴대폰과 직접 데이터를 교환합니다. 휴대폰이 서버로 정리된 러닝 데이터를 전송하고, 웹은 저장된 데이터를 조회합니다.

6. 유지해야 하는 핵심 규칙

1. 워치 자동 회전·화면 조작 정책을 바꾸지 않는다. 앱 실행·백그라운드 전환 중에도 워치 기본 터치와 버튼 조작이 가능해야 합니다.
2. 음성 안내는 운영체제 기본 TTS가 아니라 MeloTTS 한국어 모델의 WAV 음성을 사용합니다.
3. 센서가 제공하지 않은 심박·자세·경로 값을 임의로 만들지 않습니다. 데이터가 없으면 없는 상태로 표시합니다.
4. 실제 완주 경로는 선택한 경로와 구분해 저장·표시합니다. 캘린더와 게시글 지도는 가능하면 실제 이동 경로를 사용하고, 과거 데이터에 실제 경로가 없을 때만 선택 경로를 보조적으로 사용합니다.
5. Alembic 마이그레이션 revision ID는 DB 컬럼 길이 제한을 넘지 않게 짧게 유지합니다. 실제 경로 저장 마이그레이션의 ID는 0010_actual_routes입니다.
6. 웹 배포 후 예전 화면이 남지 않도록 PWA/캐시 변경을 함께 점검합니다. 완료 캘린더 데이터는 최신 정보를 읽도록 캐시 정책을 유지합니다.
7. DB 스키마·운영 데이터를 바꾸기 전에는 백업·복구 가능 여부와 배포 순서를 먼저 확인합니다.

7. 최근 배포 기준 작업

커밋	내용
8ea72e02	러닝 결과 화면에서 뒤로가기를 누르면 이전 러닝 세션으로 돌아가지 않고 로비로 이동하도록 수정
ceb3a6e4	로그인 후 로비에서 뒤로가기를 해도 로그인 페이지로 되돌아가지 않도록 수정
c0e912b7	완료 캘린더의 오래된 캐시를 방지해 최신 완주 기록을 반영
a8822eb1	경로·러닝 경험 UI 개선
3aeadf31	캘린더에서 실제 러닝 경로 지도를 더 크게 표시
271453dd	완료한 실제 경로를 캘린더 지도에 표시
4ff536d0	캘린더 완주 날짜를 파란 점으로 표시
97aace4c	커뮤니티 목록·내 게시글 통합, 업로드 중복 방지·대기 처리, 실제 경로 지도 등 개선

Git의 전체 작업 이유와 파일 변경은 아래로 확인합니다.

cd D:\Capstone_projects\Tranimal_Run
git log --oneline --decorate -30
git show <커밋ID>

8. 워치·실제 앱 인수인계

capstonWearOS는 메인 서비스와 별도 체크아웃입니다. 현재 수정·새 파일이 남아 있으므로, 다른 PC로 이동하기 전에 현재 PC에서 다음을 확인하고 의미 있는 단위로 커밋합니다.

cd D:\Capstone_projects\capstonWearOS
git status
git add -A
git commit -m "Wear OS 변경 내용"
git push origin WearOS

커밋 전에는 signing.properties, 키스토어, 로컬 SDK 경로, 기기 연결 설정이 포함되지 않았는지 반드시 확인합니다. 새 PC에서는 WearOS 브랜치를 별도 폴더로 내려받고, 워치와 휴대폰을 새로 페어링합니다.

TWA 폴더는 아직 Git 저장소가 아니므로 다른 PC에 안전하게 이어서 작업하려면 다음 중 하나를 먼저 결정해야 합니다.

• 권장: TranimalTwa 전용 비공개 GitHub 저장소를 생성해 소스만 관리
• 대안: Tranimal_Run에 명시적으로 통합하되 Android 전용 .gitignore와 CI 정책을 먼저 정비

어느 경우든 signing.keystore, *.jks, *.keystore, local.properties, build/, .gradle/, 배포 APK/AAB는 커밋하지 않습니다.

9. 다음 Codex에게 전달할 시작 문구

새 컴퓨터에서 Codex를 D:\Capstone_projects\Tranimal_Run 폴더로 열고 다음처럼 요청합니다.

이 저장소의 HANDOFF.md와 README.md를 먼저 끝까지 읽고, DemoService 브랜치에서 작업을 이어가줘.
비밀값·DB 접속 문자열·서명키는 출력하거나 커밋하지 마. 변경 전 git status를 확인하고,
완료한 변경은 빌드/검증 후 DemoService에만 반영해줘. 워치 자동회전은 절대 활성화하거나 바꾸지 마.

Codex의 이전 채팅 내용은 다른 기기로 자동 이전되지 않으므로, 이 문서와 Git 커밋 이력이 작업 맥락의 기준입니다.

10. 배포 전 최소 점검

• git status가 의도한 파일만 포함하는지 확인
• 메인 웹 빌드와 타입·린트 오류 확인
• DB 마이그레이션이 필요한 변경인지 확인
• DemoService 푸시 후 GitHub Actions 성공 여부 확인
• Hugging Face Space 재기동 뒤 로그인, 러닝 시작/종료, 결과, 캘린더, 커뮤니티의 핵심 흐름 확인
• 실제 워치·휴대폰 기능을 변경했다면 Data Layer 동기화와 백그라운드 조작 가능 여부를 확인