# 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에서 아래 명령을 **한 줄씩** 실행합니다.

```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을 설치합니다. 의존성은 소스 폴더에서 다시 설치합니다.

```powershell
cd D:\Capstone_projects\Tranimal_Run\main
npm ci
```

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

### 3-2. 매 작업 시작 전

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

```powershell
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. 작업 완료 후

```powershell
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. 시스템 구조

```text
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의 전체 작업 이유와 파일 변경은 아래로 확인합니다.

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

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

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

```powershell
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` 폴더로 열고 다음처럼 요청합니다.

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

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

## 10. 배포 전 최소 점검

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