ZIP 하나로 시작하는
TripWeave v4
작성일: 2026-09-30 · 국내 여행용 초기 버전 · 원본 v3 데모를 실제 조회 구조로 전환했습니다.
1. 처음 배포하기
- Cloudflare 로그인 → Workers & Pages → Create application으로 이동합니다.
- Pages의 Direct Upload / Upload assets / Drag and drop your files를 찾습니다. UI 언어에 따라 이름이 다를 수 있습니다. 일반 Worker 코드 편집기에 ZIP을 넣는 방식이 아닙니다.
- 프로젝트 이름(예: tripweave)을 정하고 TripWeave_v4.0.0_PAGES_UPLOAD.zip을 압축 해제 없이 업로드합니다.
- 업로드된 최상위에 index.html, _worker.js, _routes.json이 있는지 확인하고 Deploy site를 누릅니다.
- 생성된 pages.dev 주소를 엽니다. 키가 없으면 연결 안내가 나오는 것이 정상입니다.
- 프로젝트 Settings → Variables and Secrets에서 아래 키를 Production 환경의 Secret으로 등록합니다.
- 동일 ZIP으로 Create a new deployment → Production 배포를 합니다. 설정 후 기존 배포가 자동 변경됐다고 가정하지 말고 새 배포를 만드세요.
- 앱의 연결·안내에서 상태를 확인하고 출발지를 입력해 여행을 만듭니다. Preview 배포를 사용할 경우 해당 환경에도 별도로 키를 등록해야 합니다.
| 이름 | 필수 여부 / 값 |
|---|---|
| KAKAO_REST_API_KEY | 기본 여행 생성 필수. 카카오 개발자 앱의 REST API 키. JavaScript 키가 아닙니다. 필요한 카카오맵/로컬 사용 설정·권한은 개발자 콘솔에서 확인하세요. |
| TOUR_API_KEY | 사진·관광 상세·행사 달력 권장. 공공데이터포털의 한국관광공사 국문 관광정보 서비스_GW 활용승인 후 발급된 키. 인코딩·디코딩 키를 한 번만 인코딩하도록 처리합니다. |
| APP_PASSWORD | 선택. 개인 앱으로 쓸 때 지정하는 별도의 충분히 긴 이용 비밀번호. 서비스 API 키와 다른 값을 쓰세요. 앱 화면에서 입력한 비밀번호는 탭 메모리에서만 사용합니다. |
무료 범위 내 사용을 목표로 했지만 Cloudflare와 외부 API의 실제 요금·한도는 계정 및 서비스 정책을 따릅니다. OpenAI API, DB, KV, 빌드 서버, npm 설치는 이 배포에 필요 없습니다.
2. 실제로 구현한 기능
- 1~7일 날짜별 일정 생성. 출발지·목적지 주소 검색. 동명 검색 결과가 여러 개면 사용자가 선택합니다.
- 목적지를 비우면 국내 도시 중심 좌표 목록에서 거리 조건으로 인근 3개 도시를 비교해 첫 후보를 조회합니다. 전국 실시간 최적화·전체 도시 전수조사가 아닙니다.
- 카카오 장소 검색과 TourAPI의 관광지·음식점·숙박 후보를 통합합니다. 장소 ID와 이름·인접 좌표로 중복을 줄입니다.
- 관광공사에 제공된 장소 대표사진을 표시합니다. 없는 사진은 합성·다른 업체 사진으로 채우지 않습니다.
- TourAPI 콘텐츠는 메뉴명·운영 안내·휴일·요금 안내·체크인 정보가 제공될 때 상세 조회합니다. 메뉴별 현재 가격은 자동 생성하지 않습니다.
- 여행 날짜와 겹치고 목적지에서 25km 이내인 조회 행사 중 가까운 1건을 일정 후보로 자동 배치합니다. 운영 시간은 자동 확정하지 않고 확인 안내를 표시합니다. 인접 행정구역의 행사까지 전수 조회하지 않습니다.
- 월간 행사 달력, 날짜 선택, 기간형 행사 표시, 기존 여행 날짜를 선택한 행사 추가, 중복 추가 방지.
- 인원·숙박 객실 수·식사 횟수·관광 배정액·교통 배정액·예비비 합산. 예산 초과를 0원으로 숨기지 않습니다.
- 일정 고정, 사용하지 않은 다른 장소로 교체, 제외, 더 여유롭게. 변경 후 시간과 배정 예산 재계산.
- 브라우저에 최대 10개 여행 저장, JSON 내보내기·가져오기, 전체 날짜 인쇄. 서버에 여행·현재 위치를 저장하지 않습니다.
- 네트워크 지연·키 미설정·인증·한도·JSON 파싱 오류·일부 공급자 실패·결과 없음 구분. 데모 데이터로 자동 대체하지 않습니다.
3. v3를 세밀하게 검토한 결과
| 문제 | v4 조치 |
|---|---|
| 부산 3일 고정 데이터 | 입력과 실제 장소 후보로 동적 생성 |
| 4일 선택 가능하지만 3일만 존재 | 기간에 맞는 날짜·탭 생성 및 날짜 경계 계산 |
| 인원 변경이 식비에 반영되지 않음 | 계획 단가 × 인원 × 횟수 계산 |
| 비용 세부내역·총액 불일치 | 단일 계산 결과에서 상세·총액·잔액 표시 |
| 비용 초과가 0원으로 숨겨짐 | 초과액과 경고 표시 |
| 검증 완료·준비도 82 고정 표시 | 삭제. 실제 확인 범위와 미검증 사항 표시 |
| 일정 고정·완화가 문구만 변경 | 일정 데이터 변경·재계산·저장 연결 |
| 캐시 우선이라 업데이트 지연 가능 | v3 전용 캐시 정리·이전 서비스워커 해제·JS 재검증 헤더 |
| 소스 ZIP을 그대로 올리면 배포 루트 혼동 | index.html과 _worker.js를 ZIP 루트에 포함 |
4. 정보의 의미를 구분합니다
조회된 장소는 공급자 데이터에 있다는 뜻입니다. 폐업하지 않았음·오늘 영업함·예약 가능함을 증명하지는 않습니다. 조회 시각과 현장 검증 시각도 다릅니다.
배정 예산은 사용자 입력 단가로 여행에 돈을 나눈 값입니다. 음식점 판매가나 호텔 견적이 아닙니다. 호텔은 2인당 1객실을 가정하며 인원·객실 정책·추가 요금은 확인해야 합니다.
이동시간은 직선거리 × 1.35를 자가용 38km/h·대중교통 23km/h의 계획용 속도로 나누고 이동 준비 여유(10분/20분)를 더한 추정입니다. 이는 지도 경로·실시간 교통·대중교통 시간표가 아닙니다. 도서·산악·장거리 구간에서는 큰 오차가 날 수 있습니다. 식사·관광·행사 방문 시간과 운영시간을 자동 대조하지 않습니다.
행사기간은 TourAPI 제공 값입니다. 일정에 배치된 시각은 실제 공연 시작시각이 아닙니다. 대표사진도 실제 선택한 음식·객실을 의미하지 않습니다.
5. 행사 수집 범위와 비용 관리
지역·월별 조회는 전년도 1월 이후 시작한 행사부터 조회해 월과 기간이 겹치는 것을 골라냅니다. 한 번에 최대 3페이지·300건까지 확인하며 상한에 도달하면 일부 결과임을 표시합니다. 전국 조회는 쉽게 상한에 도달하므로 지역을 선택하는 편이 낫습니다. 전년도 이전에 시작한 상설 행사, 미등록 행사, 행사 시간·취소 변경은 놓칠 수 있습니다.
TourAPI 정상 응답만 Cloudflare Cache API에 최대 1시간 캐시합니다. 반환한 조회 시각은 캐시의 실제 수집 시각을 유지합니다. 오류는 캐시에 넣지 않습니다. 카카오 응답은 서버에 별도 캐시하지 않습니다. 공급자의 보관·이미지·표시 조건은 운영 전에 확인하세요.
한 API 요청의 외부 호출은 10초 제한, 클라이언트는 40초 제한을 둡니다. 무한 재시도나 페이지를 끝없이 넘기는 수집은 없습니다. IP별 1분 30회 제한은 Worker 인스턴스 내 최선 노력 방식이며 분산된 전체 요청의 엄격한 한도를 보장하지 않습니다. 개인 사용은 비밀번호를 권장하며, 불특정 다수 공개 시 Cloudflare Access·전역 한도 제어 등 별도 운영 설정이 필요합니다.
6. 다음 버전에서 우선할 개선
- 실제 경로: 자동차 길찾기 공급자 연결, 대중교통 시간표·환승·막차·도보를 별도 구현. 일정 전체 구간의 이동 가능성을 확인한 후에만 ‘이동 가능’ 표시.
- 운영시간: 휴무·브레이크타임·마지막 주문·체크인·공연 시작시간을 구조화. 확인되지 않은 시간은 자동 확정하지 않기.
- 음식: 식당·지점·메뉴 ID를 연결하고 메뉴명·가격·주문 수량·사진의 출처를 개별 관리. 메뉴판 OCR은 인식 결과를 검증하고 반영.
- 숙소: 숙박 공급자 계약/제휴 API로 날짜·인원·객실·세금·취소 조건을 포함한 견적과 재고를 조회. 호텔 외관과 실제 객실 이미지를 구분.
- 추천 품질: 현재 거리 기반 인근 도시 선택을 예산·행사·취향·날씨·데이터 충실도를 고려한 후보 비교로 확장. 계절 행사 하나 때문에 과도한 우회를 만들지 않기.
- 여행 운영: 날씨 대체 코스, 일정 지연 재계산, 예약 정보 연결. 휴대폰 화면이 꺼져도 알림이 된다고 가정하지 않고 서버 Push 설계 후 별도 기기 검증.
- 저장·동기화: 필요할 때만 D1·로그인을 도입하고 현재 JSON 여행 데이터를 이관. 현 초기판에는 상시 수집·스케줄러가 없음.
7. 오류별 확인 방법
| 화면 | 확인할 내용 |
|---|---|
| 서버 API 인식 실패 | Pages 직접 업로드인지, ZIP 루트에 _worker.js가 있는지 확인 |
| 키 미설정 | 변수명·Production 환경·새 배포 확인 |
| 401/403 또는 인증 오류 | REST API 키 종류·카카오 사용 설정·공공데이터 활용승인 확인 |
| 앱 비밀번호 요구 | APP_PASSWORD로 설정한 이용 비밀번호를 연결·안내에 입력 |
| 429 | 요청을 줄이고 한도 확인. 앱 제한이면 1분 후 재시도 |
| 조회 결과 없음 | 시·군·구를 포함하거나 다른 중심 장소 선택. API 실패와 다른 상태 |
| 업데이트 후 옛 화면 | 올바른 Production 주소 확인 후 강력 새로고침. 저장 여행 JSON을 보관한 뒤 사이트 데이터 정리를 고려 |
8. 검증 결과와 한계
Node 자동 시험 24개 통과: 기간·날짜 경계·중복 관광지·인원 계산·예산 초과·고정·교체·완화·저장 복원·빈 후보·기간형 행사·키 미설정·인증·쿼터·파싱·통신 오류·부분 실패·API 파라미터·행사 페이지 제한·요청 제한을 확인했습니다. 외부 API는 모의 응답으로 시험했습니다.
Chromium 브라우저 흐름 15개 항목 통과: 키 미설정 안내·가짜 계획 방지, 4일 일정·행사 자동 반영, 날짜별 탭, 고정, 메뉴 상세, 새로고침 복원, 기간형 행사 달력, 지역 변경 후 이전 결과 제거, 390px·320px 화면 가로 넘침, JSON 내보내기·가져오기, 조회 실패 시 기존 계획 보존을 확인했습니다. 1440px 데스크톱과 390px 모바일 화면 이미지를 점검했습니다. 외부 데이터는 테스트용 모의 응답입니다.
실제 사용자 API 키로 인증된 조회, Cloudflare 계정에 직접 업로드한 배포, Android 실기기 확인은 수행하지 않았습니다. 따라서 전체 서비스 연동 완료나 모든 지역 검색 성공을 보장하지 않습니다. 본 초기판은 연결 가능한 앱과 검증된 내부 동작을 제공하는 범위입니다.
공식 근거
- Cloudflare Pages Direct Upload: ZIP 업로드 및 _worker.js 지원
- Pages Advanced mode
- Pages 변수·비밀값
- 카카오 로컬 API 규격
- 국문 관광정보 KorService2
Cloudflare는 일반 신규 개발에 Workers Static Assets를 권장하지만, 이번에는 사용자의 ‘ZIP 하나 직접 업로드’ 조건을 우선하여 공식적으로 지원되는 Pages Advanced mode를 선택했습니다.