여행 일기 (Travel Diary)
여행의 원자료를 스크롤텔링 웹사이트로 변환합니다: 고정된 위성 지도 위에 하루별 카드, 이동 구간(캠핑카, 자동차, 자전거, 도보, 페리, 하우스보트)이 지도에 그려지고, 사진과 동영상이 해당 위치에 고정되며, Wikimedia Commons 이미지가 포함된 정보 지점("Unterwegs" / "길 위에서")이 표시됩니다. 또한 하루별 리플레이 기능으로 3D 경로 비행과 함께 통계, 고도 프로필 및 촬영 위치에서 팝업으로 나타나는 사진을 제공합니다.
template/의 템플릿은 Vite + TypeScript + MapLibre 프로젝트(프레임워크 없음, API 키 없음)입니다.
사용자는 코드를 전혀 건드릴 필요가 없습니다. 로컬 셋업 웹 앱이 언어, 여행 데이터, 일별 텍스트 및 파일을 드래그 앤 드롭으로 수집하고, 나머지 작업은 빌드 스크립트가 처리합니다.
어떤 모드?
| 사용자 말 | 모드 | 이동 위치 |
|---|---|---|
| "새 여행 일기", "여행 사이트 설정", 아직 프로젝트 없음 | init | §1 |
| "새 사진 / GPX / 타임라인 / 일기 텍스트", "N일차 추가", 프로젝트 존재 | day | §2 |
| "배포", "게시", "단일 파일 만들기", "온라인에 올리기" | deploy | §3 |
data/trip.json과 scripts/build-timeline.mjs 파일이 있으면 traveldiary 프로젝트입니다.
1. init – 새 프로젝트 스캐폴드
- 메시지에서 두 가지만 묻습니다: 대상 폴더와 사용자가 설정 질문에 답변하는 방식을 브라우저 앱(기본, 더 친숙함)에서 할지 채팅에서 할지 결정합니다. 나머지는 앱이 질문합니다.
- 스캐폴드 실행:
node <skill-dir>/scripts/init.mjs <대상-폴더>.template/을 복사하고npm install을 실행한 후 다음 명령어를 출력합니다. - 설정 앱 시작: 프로젝트 내에서
npm run setup(포트 5180) 실행하고 사용자에게 http://localhost:5180을 열라고 알립니다. 브라우저 창을 사용할 수 있으면preview_start와 함께 해당 URL을 사용합니다. 앱이 다음 과정을 안내합니다: 언어 (de/en) → 제목, 부제목, 날짜, 시간대, 이동 수단, 출력 유형, 강조 색상 → 하루별 항목 (날짜, 제목, Markdown 일기 텍스트) → 사진, 동영상, GPX, Google 타임라인 드롭 영역.data/trip.json,content/tagebuch.md및raw/폴더를 작성합니다. 사용자는 언제든지 다시 열 수 있습니다. - 사용자가 "완료", "fertig"라고 말하거나 자료를 붙여넣으면 day 모드로 계속 진행합니다.
사용자가 채팅에서 답변하는 경우, data/trip.json을 직접 작성하고 (스키마는 references/data-formats.md 참조) 일기는 content/tagebuch.md에 작성합니다 (## Tag N – <요일, 날짜> – <제목> / ## Day N – …).
2. day – 새 자료 처리
세션에서 첫 실행 전에 references/day-workflow.md를 읽으십시오. 정확한 순서, 규칙 및 주의 사항이 있습니다. 간략 버전:
- 인벤토리:
raw/아래에 새로 추가된 항목 (find raw -newer public/data/photos.json)과 일기에 새 날짜가 있는지 확인합니다. Claude Docs 커넥터와 문서 링크를 사용할 수 있으면 문서를 Markdown으로 내보내content/tagebuch.md에 저장합니다. 그렇지 않으면 설정 앱이나 사용자가 해당 파일을 관리합니다. - 구조화:
data/trip.json에서 하루별days[]항목 (n,date,title, GPX용tracks[], 플라이오버 클립용video, 타임라인이 없을 때legs[])을 만듭니다. GPX 파일 이름을YYYY-MM-DD_slug.gpx로 변경합니다. - 타임라인 레이블:
npm run data:timeline실행 후 콘솔의 구간 목록을 읽고 각 구간에 사람이 읽을 수 있는 레이블을trip.json → timeline.labels에 추가합니다 (키 = 로컬 시작 시간YYYY-MM-DDTHH:MM). 잘못 감지된 종류를timeline.kinds에서 수정합니다 (스키를 e-bike 위에서 탄 경우ebike, 친구 차면car). 정류장 장소를places에 추가하여 정지 시 "Pause" 대신 이름이 표시되도록 합니다. - 빌드:
npm run data(콘텐츠 → 트랙 → 타임라인 → POI → 사진). 공용 라우팅/고도/Commons 서버는 속도 제한이 있으므로 스크립트가 일시 중지 및 캐싱하며 반복하지 않습니다. - 사진 확인: 새 사진의 연락처 시트를 빌드하고 (참조 문서의 스크립트 사용) 읽은 후 각 사진에 대해 한 문장씩
data/captions.json에 작성합니다. 사진 위치(각 사진 옆에 인쇄됨)로 식별 가능한 장소와 산 이름을 명시하고, 정확하지 않은 봉우리 추측보다는 "Ortler 그룹"과 같이 말합니다. 흐릿하거나 우발적인 사진은data/exclude.json에 넣습니다. - 관심 지점: 사용자가 좋은 사진 없이 지나친 주목할 만한 장소(터널, 유명한 호수, 성)에 대해
data/pois.json에 2~3개의 사실적인 문장과 Commons 검색어를 추가합니다.npm run data:pois가 자유 라이선스 이미지와 저작자 표시를 가져옵니다. 연락처 시트에서 선택된 이미지를 확인하고 첫 번째 결과가 좋지 않으면(판화, 지도 등) 더 나은file을 지정합니다. - 확인:
npm run dev로 새 날짜를 열고 선, 핀, 캡션을 확인하고 리플레이를 한 번 재생합니다. - 배포 (§3)하고 프로젝트가 git 저장소이면 커밋합니다.
프로젝트의 CLAUDE.md를 최신 상태로 유지하십시오 (다음 세션을 위한 핸드오프 문서).
3. deploy
trip.json → output은 사용자가 선택한 것을 나타냅니다. 자세한 내용과 정확한 명령어는 references/hosting.md에 있습니다.
- single:
npm run build:single→ 프로젝트 옆에 데이터, 사진 및 동영상이 포함된 단일 HTML 파일 (큰 동영상은 제외되며 안내 메시지가 표시됨). 사용자 참고: 일부 휴대폰에서 파일 시스템에서 열린 파일은 지도의 웹 워커를 차단합니다. 호스팅이 더 안정적입니다. - web:
npm run deploy:web→ 빌드,.htaccess+.htpasswd(Basic Auth) 생성 후 변경된 파일을 SSH로 업로드 (tar 파이프, 해시 매니페스트로 증분)..env.web필요 (호스트, 사용자, 디렉토리, 로그인). - nas:
npm run deploy→ Synology nginx 컨테이너로 tar 파이프. 설정은nas/default.conf.
알아두면 좋은 점
- 사진에는 EXIF 시간 + GPS가 필요합니다 (스마트폰은 둘 다 제공). 동영상은 파일 이름(
PXL_YYYYMMDD_HHMMSS)에서 시간을 얻고 타임라인, GPX, 정류장 또는 가장 가까운 사진에서 위치를 얻습니다. - GPX가 타임라인보다 우선합니다: GPX 트랙과 겹치는 타임라인 활동은 삭제됩니다.
- Google 타임라인이 없으면
days[].legs를 통해 명명된 장소 사이를 라우팅합니다. - 하우스보트 여행: 종류
boat는 OSM 강/운하를 따라 경로를 지정하며 (scripts/waterway.mjs, 선택적timeline.waterways화이트리스트) 사진 EXIF 위치를 웨이포인트로 사용합니다 –references/day-workflow.md참조. - 데스크탑 (≥ 900 px): 지도 왼쪽 50 %, 스토리 오른쪽 50 %에 큰 사진 그리드; 리플레이는 오른쪽에 사진 카드를 표시하고 15분 이내에 촬영된 사진(최대 6장)을 하나의 카드로 그룹화합니다 (모바일은 변경 없음).
- 고속도로 터널 위의 고도 프로필은 지형 위를 보여줍니다. 따라서 고도 상승은 자전거/도보에 대해서만 계산됩니다.
- 모든 UI 텍스트는
src/i18n.ts에 있습니다 (de, en). 언어 추가는 하나의 딕셔너리만 추가하면 됩니다.