일기 (timeline-diary)

그날 남기고 싶은 것만 골라서 적는 일기장입니다. 식사·복약·몸 상태처럼 날마다 챙기는 것을 고르면 그 칸이 날짜마다 올라오고, 그 아래에 짧은 일기를 남길 수 있습니다. 구글 타임라인을 올리면 그날 다닌 길도 지도로 펼쳐집니다 — 그것도 고를 수 있는 기록 중 하나입니다.

• 하루 경로를 한눈에 보기(SVG)와 지도에서 재생(애니메이션) 두 가지로
• 트랙 — 사람마다 남기고 싶은 게 다르니, 그날 무엇을 기록할지 고를 수 있습니다 (복약 · 식사 · 변, 그리고 직접 추가한 약)
• 구글 로그인 → 기기 간 동기화
• 로그인 없이도 사용 (이 기기에만 저장). 나중에 로그인하면 쌓인 기록이 그대로 계정으로 합류합니다.
• 업로드한 파일은 브라우저 밖으로 나가지 않습니다. 날짜별로 정리한 경로만 저장됩니다.

빌드 도구는 Vite. 런타임 의존성은 지도용 Leaflet 하나뿐이고, API 키가 필요 없습니다. 배경지도는 OpenStreetMap을 씁니다.

---

1. Vercel 배포

1. vercel.com/new → Import Git Repository → TRASH-TRACO/timeline-diary 선택
2. 설정은 건드릴 필요 없습니다. Vercel이 자동으로 잡습니다.
   • Framework Preset: Vite
   • Build Command: npm run build
   • Output Directory: dist
3. Deploy → 끝. https://timeline-diary.vercel.app 같은 주소가 나옵니다.

이후 main에 push하면 자동으로 재배포됩니다.

이 단계까지만 하면 로그인 없이 사용하기는 바로 됩니다. 구글 로그인은 아래 2번을 해야 동작합니다.

2. Firebase 설정 (구글 로그인용)

이 앱 전용 Firebase 프로젝트 timeline-diary-99be8 를 씁니다. 설정값은 src/firebase-config.js에 들어 있으니 두 가지만 해주세요.

2-1. 승인된 도메인 추가

Firebase 콘솔 → Authentication → 설정 → 승인된 도메인 → 도메인 추가

1번에서 받은 Vercel 주소를 넣습니다. 예: timeline-diary.vercel.app

여기에 없는 도메인에서 로그인하면 auth/unauthorized-domain 오류가 납니다. 앱이 그 오류를 만나면 해결 방법을 화면에 띄워주니, 안내대로 하시면 됩니다.

2-2. Storage 켜기 (사진용)

Firebase 콘솔 → Storage → 시작하기 → 위치는 Firestore와 같은 곳으로.

만들어지면 Rules 탭에 이 저장소의 storage.rules 내용을 붙여넣고 게시합니다.

사진 없이 쓰실 거면 건너뛰어도 됩니다. Storage가 없으면 사진은 이 기기에만 남고 다른 기기로 넘어가지 않습니다(앱은 그대로 동작합니다).

2-3. Firestore 규칙 게시

Firebase 콘솔 → Firestore Database → 규칙 탭에 이 저장소의 firestore.rules 내용을 붙여넣고 게시를 누릅니다.

로그인한 사람이 자기 UID 아래 문서만 읽고 쓸 수 있게 하는 규칙 하나가 전부입니다. 하위 컬렉션은 상위 문서의 규칙을 물려받지 않으므로 users/{uid}/diary/{monthKey} 경로를 직접 적어주어야 합니다.

이 세 가지가 끝나면 구글 로그인과 기기 간 동기화가 동작합니다.

---

3. 선택 — 다른 Firebase 프로젝트로 옮기기

프로젝트를 갈아타고 싶으면 Vercel 프로젝트의 Settings → Environment Variables에 아래를 넣고 재배포하세요. 코드를 고칠 필요는 없습니다.

변수	예시
VITE_FB_API_KEY	AIzaSy...
VITE_FB_AUTH_DOMAIN	my-diary.firebaseapp.com
VITE_FB_PROJECT_ID	my-diary
VITE_FB_STORAGE	my-diary.firebasestorage.app
VITE_FB_SENDER_ID	1234567890
VITE_FB_APP_ID	1:1234567890:web:abcdef

값은 Firebase 콘솔 → 프로젝트 설정 → 내 앱 → 웹 앱의 SDK 설정에 있습니다. vercel.json의 리라이트 주소도 같이 바꿔주세요(4번 참고).

Firebase 웹 설정값은 비밀이 아닙니다. 브라우저에 그대로 실려 나가는 값이고, 실제 접근 통제는 보안 규칙과 승인된 도메인이 합니다. 그래서 기본값을 src/firebase-config.js에 그냥 적어 두었습니다.

4. 선택 — 로그인 팝업에 내 도메인 보이게 하기

기본 설정에서는 구글 로그인 팝업 주소창에 timeline-diary-99be8.firebaseapp.com이 잠깐 보입니다. 내 도메인으로 바꾸고 싶다면:

1. VITE_FB_AUTH_DOMAIN을 내 도메인으로 설정 (예: timeline-diary.vercel.app)
2. vercel.json의 /__/auth 리라이트가 그 요청을 실제 Firebase 인증 핸들러로 넘겨줍니다. 이미 timeline-diary-99be8를 가리키게 들어 있으니 그대로 두면 됩니다. (3번으로 프로젝트를 옮겼다면 destination도 바꿔주세요)

이 리라이트는 기본 설정에서는 쓰이지 않으니, 신경 안 쓰셔도 아무 문제 없습니다.

---

지도 바꾸기

기본은 Leaflet + OpenStreetMap입니다. 키도 결제 계정도 필요 없어 설정 없이 돌아갑니다.

지도를 다루는 코드는 src/map/ 아래 어댑터로 분리돼 있습니다. 재생 타임라인과 자동 카메라 — 이 앱에서 정작 까다로운 부분 — 는 지도와 무관하므로, 배경지도를 갈아끼워도 그쪽은 그대로입니다.

src/map/geo.js       배율 계산 (웹 메르카토르 — 지도 라이브러리와 무관, 브라우저 없이 검증 가능)
src/map/leaflet.js   Leaflet + XYZ 타일  ← 기본
src/map/kakao.js     카카오맵 SDK
src/map/index.js     어느 쪽을 쓸지 고르고, 실패하면 되돌린다

① 타일만 바꾸기 (가장 쉬움)

VWorld(국토지리정보원)처럼 일반 XYZ 타일을 주는 곳이면 환경 변수만 넣으면 됩니다. 한글 지명·건물 디테일이 OSM보다 낫고, Leaflet을 그대로 쓰므로 아무것도 깨지지 않습니다.

변수	예시
VITE_TILE_URL	https://api.vworld.kr/req/wmts/1.0.0/{키}/Base/{z}/{y}/{x}.png
VITE_TILE_ATTR	© VWorld
VITE_TILE_MAXZOOM	18

② 카카오맵으로 바꾸기

변수	값
VITE_MAP_PROVIDER	kakao
VITE_KAKAO_KEY	카카오 개발자 사이트의 JavaScript 키

developers.kakao.com → 내 애플리케이션 → 앱 설정 → 플랫폼 → Web에 배포 도메인을 등록해야 SDK가 동작합니다.

⚠️ 카카오 어댑터는 검증되지 않았습니다. 개발 환경에서 카카오 도메인이 막혀 있어 SDK를 불러올 수도, 자동 테스트를 돌릴 수도 없었습니다. 그래서 실패하면 조용히 OpenStreetMap으로 되돌아가도록 해 두었습니다(이 되돌림 경로는 테스트했습니다). 지도가 아예 안 뜨는 일은 없지만, 카카오 쪽은 직접 보시면서 고쳐야 할 수 있습니다. 특히 이런 것들이 어긋날 수 있습니다.

• 레벨 ↔ 배율 대응 — 카카오는 레벨(1~14, 작을수록 확대), Leaflet은 배율(클수록 확대)을 씁니다. src/map/kakao.js의 LEVEL_BASE가 근사값이라, 확대 정도가 어색하면 이 숫자만 고치면 됩니다.
• 어두운 화면 — 카카오는 자체 지도 스타일을 쓰므로 OSM처럼 타일을 반전시키지 않습니다. 다크 모드에서도 지도는 밝게 나옵니다.
• 부드러움 — 카카오에는 flyTo가 없어 중심 이동과 레벨 변경을 따로 겁니다.

참고: 끊김의 원인은 지도 라이브러리가 아니라 카메라 로직이었습니다(계측상 Leaflet에서 60fps·드롭 0). 지도를 바꾼다고 부드러워지지는 않습니다. 바꿀 이유는 한국 지도 디테일입니다.

OSM 타일은 이용 정책상 대규모 트래픽에는 쓸 수 없습니다. 개인용·소규모라면 문제없지만, 사용자가 늘면 위 ①이나 ②로 옮기는 게 맞습니다.

로컬에서 돌려보기

npm install
npm run dev      # http://localhost:5173
npm run build    # dist/ 생성
npm run preview  # 빌드 결과 확인

localhost는 Firebase 승인된 도메인에 기본으로 들어 있어 로그인도 됩니다.

타임라인 데이터 받는 법

앱 안의 도움말 버튼에도 같은 내용이 있습니다.

• 안드로이드 — 설정 → 위치 → 위치 서비스 → 타임라인 → 타임라인 데이터 내보내기 → Timeline.json
• 아이폰 — Google 지도 → 프로필 → 타임라인 → ⋯ → 위치 및 개인 정보 설정 → 타임라인 데이터 내보내기 → location-history.json
• Takeout — takeout.google.com → 위치 기록(타임라인) 만 선택, JSON → 받은 .zip을 압축 풀지 말고 그대로 올리기

지원하는 형식

형식	파일	최상위 키
안드로이드 기기 반출 (2024~)	Timeline.json	semanticSegments, rawSignals
iOS 기기 반출 (2024~)	location-history.json	(배열)
예전 Takeout 시맨틱 기록	2021_JANUARY.json 등	timelineObjects
예전 Takeout 원시 기록	Records.json	locations

좌표 표기(geo:37.5,127.0 / 37.5665°, 126.9780° / latitudeE7 / latE7 / {lat,lng})도 전부 받습니다. 날짜 분류는 기록에 박힌 UTC 오프셋을 우선 쓰고, 없으면 브라우저 시간대로 환산합니다 — 그래야 자정 근처 기록이 엉뚱한 날로 밀리지 않습니다.

아주 큰 Records.json(원시 위치 로그, 수백 MB)은 브라우저가 감당하기 어려워 건너뜁니다. 기기에서 내보낸 Timeline.json이나 Semantic Location History 폴더의 월별 파일을 쓰면 훨씬 빠르고 결과도 깔끔합니다.

---

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗