diff --git a/docs/05_submission/data_spec.md b/docs/05_submission/data_spec.md new file mode 100644 index 0000000..72ef59b --- /dev/null +++ b/docs/05_submission/data_spec.md @@ -0,0 +1,258 @@ +# 말따라 제주 — 데이터 활용 명세 + +- 작성: 2026-11-19 (A 트랙) +- 수치 근거: 동봉 DB `data/db/malttara.sqlite`(`meta.data_version = 2026-11-19`, 2026-11-19 14:44 빌드)의 `places`·`emd_stats`·`sight_visits`·`data_sources`·`meta.build_stats`를 직접 조회한 값. 원본 확인 내용은 `data/cards/{ID}_*.md`의 '분석 결과'. + - 카드의 '분석 결과' 일부 매칭 수(예: 장소 4024곳, 811 24곳)는 **11/17 첫 빌드** 기준이다. 그 뒤 정제 규칙이 강화되어(같은 이름 병합 2km, 분류 없는 1349 기록 추천 제외 등, `docs/01_planning/decisions.md`) 현재 DB 값과 다르다. **이 문서는 현재 DB 값을 따른다.** + - 데이터를 다시 빌드하면 수치가 바뀔 수 있다. 제출 직전 빌드로 다시 확인한다(9장 쿼리). +- 원칙 (기획문서_v0 1.3): 수치는 Tool(코드)이 DB에서 계산한 값만 쓴다. **지역 단위 통계(563)는 읍면동 지표로만 표시하고 개별 장소의 속성으로 표시하지 않는다.** 직선거리를 이동시간으로 표현하지 않는다. + +--- + +## 1. 사용 데이터 한눈에 보기 + +| 구분 | 허브 ID | 데이터명 | 실제 사용 기간 | 원본 규모 | 에이전트에서의 쓰임 | +|---|---|---|---|---|---| +| 필수(허브) | 1349 | 제주관광공사 제주관광정보시스템(VISIT JEJU) 여행장소 | 기간 컬럼 없음(스냅샷) | 5,669행 | 장소 후보(이름·좌표), 인지도 항(같은 이름 기록 수) | +| 필수(허브) | 563 | 내국인 유동인구 구성비율 | 2018-01 ~ 2022-09 | 35,733,343행 | 분산 항(spread): 읍면동 방문/거주 비율 — **읍면동 지표** | +| 필수(허브) | 1208 | 월별 렌터카 체류 거점 위치 정보(2021년 하반기) | 2021-07 ~ 2021-12 (토요일) | 186,606점 | 한적 항(quiet): 장소 반경 1km 체류 거점 수 — **장소 반경 지표** | +| 필수(허브) | 189 | 제주특별자치도 내국인 관광지 입장객 수 추이 | 2009-01 ~ 2024-12 | 6,640행 | 장소 카드의 입장객 추이 차트·근거 (점수에는 미사용) | +| 필수(허브) | 190 | 제주특별자치도 외국인 관광지 입장객 수 추이 | 2009-01 ~ 2024-12 | 6,226행 | 189와 함께 추이 차트 | +| 보조(허브) | 811 | 오름 위치 정보 (Open API) | 기간 개념 없음(위치) | 372건 | 장소 분류 참조('오름') | +| 보조(허브) | 812 | 박물관 및 미술관 위치 정보 (Open API) | 기간 개념 없음(위치) | 129건 | 장소 분류 참조(박물관·미술관) | +| 보조(허브) | 784 | 제주특별자치도 해수욕장 정보 | 2016 ~ 2023 | 88행(해변 11곳) | 장소 분류 참조('해수욕장') | +| 보조(허브) | 858 | 무장애 여행지 정보(통합) | 기간 컬럼 없음(기준일 2021-09-30) | 120행 | 이름·좌표 검증, 일부 분류 참조 | +| 보조(허브) | 912 | 제주 관광상품 [관광지] 선호 및 구매 데이터 | 구매 2020-12-01 ~ 2021-09-30 | 5,936행(구매 파일) | 권역 구분 4개의 근거 (DB 미적재) | +| 외부 | — | 한국관광공사 국문 관광정보 서비스_GW (TourAPI KorService2) | 2026-11-19 수신 스냅샷 | 1,875건 | 장소 분류·개요, 음식점·카페 후보 추가 | +| 외부 | — | 행정동 경계 vuski/admdongkor ver20261001 (원자료 통계청 SGIS) | 2026-10-01 기준 경계 | 제주 행정동 43개 | 좌표 → 읍면동·권역 판정, 화면 SVG 지도 | + +- 실행 중에는 어떤 외부 데이터 API도 호출하지 않는다. 모든 데이터는 개발 PC에서 ETL(`src/malttara/etl/build_db.py`)로 가공해 `data/db/malttara.sqlite`, `data/db/map.json`으로 동봉한다(설계 결정 D18). 데이터 API 키는 제출물에 없다. +- 센터 데이터는 사용하지 않는다(허브 데이터만 사용). + +--- + +## 2. 데이터별 상세 + +### 2.1 1349 VISIT JEJU 여행장소 (필수 · 장소 후보) + +| 항목 | 내용 | +|---|---| +| 제공 | 제주데이터허브 (원 제공처 표기: 공공데이터포털, 제주관광공사) — https://jejudatahub.net/data/view/data/1349 | +| 형태 | 파일 CSV `제주관광공사_제주관광정보시스템(VISIT JEJU)_여행장소.csv`, UTF-8(BOM) | +| 이용조건 | 제주데이터허브 공개 데이터, 허브 이용약관 적용. 게시판 답변(11/16): 허브 공개 데이터의 전처리 파일·DB를 결과물 ZIP에 포함 가능, 공공데이터법에 맞춰 활용. 데이터별 공공누리 유형 표기는 **미확인** | +| 실제 기간 | 기간 컬럼 없음. `수정일시`가 일괄 갱신 시점(2025-09-18)이라 방문 시점으로 쓰지 않음 → `period_actual` 비움 | +| 행 수 | 5,669행, 좌표 결측 0 | +| 사용 컬럼 | `장소명`, `위도`, `경도`, `지번주소`(경계 밖 좌표의 읍면동 보조 판정) | +| 쓰임 | ① 장소 후보 목록(`places`, source=`1349`) ② **인지도 항**: 정제 전 원본에서 같은 정규화 이름으로 남은 기록 수(`places.popularity`) → 점수 4항 중 하나, 하루 대표지 1곳 선정 | +| Tool | `search_places`·`score_places`(`tools/places.py`), `create_itinerary`(`tools/itinerary.py`) | + +### 2.2 563 내국인 유동인구 구성비율 (필수 · 읍면동 지표) + +| 항목 | 내용 | +|---|---| +| 제공 | 제주데이터허브 — https://jejudatahub.net/data/view/data/563 | +| 형태 | 파일 CSV `내국인 유동인구 구성비율.csv`, CP949, 약 2.4GB | +| 이용조건 | 1349와 같음(허브 공개 데이터). 공공누리 유형 **미확인** | +| 실제 기간 | **2018-01 ~ 2022-09** (57개월, 원본 `base_year_month` 확인) | +| 행 수 | 35,733,343행 | +| 사용 컬럼 | `base_year_month`, `emd_name`, `visit_population_count`, `residence_population_count` | +| 적재 | `emd_stats` 533행 = 본섬 **41개 읍면동**(우도면·추자면 제외) × (월 1~12 + 전체 평균 month=0). `visit_ratio = 방문인구 합 ÷ 거주인구 합` | +| 값 범위(전체 평균) | 최저 제주시 삼양동 0.225 ~ 최고 제주시 도두동 2.660, 결측 0 | +| 쓰임 | **분산 항(spread) = 1 − (장소가 속한 읍면동 visit_ratio의 백분위)**. 여행 월을 입력하면 그 달 값, 없으면 전체 평균. 01 화면 지도의 '붐비는 정도'(읍면동 색) | +| 표시 원칙 | 응답의 `indicators.region`(읍면동 지표)로만 내보내고, 화면은 "{읍면동} 지표(읍면동 단위)"로 장소 반경 지표와 **다른 제목 아래** 표시. 인쇄물에도 "지역 지표는 읍면동 단위 통계이며 개별 장소의 속성이 아닙니다" 문구 | +| Tool | `score_places`, `get_region_data`(`tools/places.py`), `GET /api/stats/emd` | + +### 2.3 1208 월별 렌터카 체류 거점 위치 정보(2021년 하반기) (필수 · 장소 반경 지표) + +| 항목 | 내용 | +|---|---| +| 제공 | 제주데이터허브 (제공기관: 제주특별자치도 미래성장과) — https://jejudatahub.net/data/view/data/1208 | +| 형태 | 파일 CSV 6개 `체류거점_2021_07.csv` ~ `체류거점_2021_12.csv`, UTF-8(BOM) | +| 이용조건 | 허브 공개 데이터. 공공누리 유형 **미확인** | +| 실제 기간 | **2021-07 ~ 2021-12**, 원문 설명상 각 월의 **토요일** 렌터카 체류 거점(전후 로그 시각 차 20분 이상인 위치) | +| 행 수 | 186,606점 (07 31,286 · 08 29,433 · 09 29,590 · 10 41,679 · 11 31,838 · 12 22,780) | +| 사용 컬럼 | `latitude`, `longitude`, `collection_dt`(기간 확인) | +| 적재 | 장소마다 반경 1.0km(`config/settings.json`의 `quiet_radius_km`) 안 체류 거점 수 → `places.quiet_count` (격자 색인으로 계산) | +| 쓰임 | **한적 항(quiet) = 1 − (quiet_count 백분위)**. 체류 거점 0건은 '한적'이 아니라 '지표 없음'(중립 0.5)으로 처리 | +| 현재 값 | 추천 대상 1,383곳 모두 값 있음, 그중 0건 15곳(지표 없음 처리). 중앙값 1,082, 최댓값 12,052 | +| 표시 원칙 | `indicators.nearby`(장소 반경 지표)로 내보내고 "장소 반경 1km · 2021-07~12 토요일 렌터카" 기준을 함께 표시 | + +### 2.4 189·190 내·외국인 관광지 입장객 수 추이 (필수 · 추이 근거) + +| 항목 | 내용 | +|---|---| +| 제공 | 제주데이터허브 (원 제공처 표기: 관광지식정보시스템) — https://jejudatahub.net/data/view/data/189 , https://jejudatahub.net/data/view/data/190 | +| 형태 | 파일 CSV, CP949 | +| 이용조건 | 허브 공개 데이터. 공공누리 유형 **미확인** | +| 실제 기간 | **2009-01 ~ 2024-12** (192개월) | +| 행 수 | 189: 6,640행, 190: 6,226행 (관광지 50곳, 같은 목록) | +| 사용 컬럼 | `날짜`(YYYY.MM), `관광지명`, `관광객수` | +| 매칭 | 관광지 50곳 중 **29곳**을 장소와 연결(수작업 대응표 `data/mapping/sights_to_places.csv` 20곳 포함, 나머지는 정규화 이름 완전 일치). 같은 이름이 여러 좌표에 있으면 자동 매칭하지 않음 | +| 적재 | `sight_visits` 4,255행(장소 29곳, 29곳 모두 추천 대상). 외국인 값 없는 월 85행은 null(차트 선 끊김) | +| 쓰임 | 장소 카드·최종 계획의 월별 입장객 추이 차트(`GET /api/places/{id}/trend`), 작업 계획의 `analyze_tourism` Tool. **점수에는 넣지 않는다**(매칭 29곳뿐이라 다른 장소와 비교 불가) | + +### 2.5 811·812·784·858 (보조 · 장소 분류 참조) + +1349에는 분류 컬럼이 없어, 아래 데이터와 TourAPI를 참조 세트로 써서 장소 분류를 붙인다(`etl/categorize.py`). 매칭 기준: 같은 정규화 이름이 300m 이내, 또는 100m 이내에서 이름 유사도 0.6 이상(`config/etl.json`의 `match`). + +| ID | 제공·URL | 형태·규모 | 사용 항목 | 결과(현재 DB) | +|---|---|---|---|---| +| 811 오름 위치 정보 | 허브 Open API (원 제공처 표기: 카카오위치서비스) — https://jejudatahub.net/data/view/data/811 | JSON 스냅샷 `hub_811.json` 372건 | `placeName`, `category`, `latitude`, `longitude` | 분류 매칭 5곳(빌드 로그). 이후 같은 이름 병합을 거쳐 DB에 `hub_811` 4곳 | +| 812 박물관 및 미술관 위치 정보 | 허브 Open API (카카오위치서비스) — https://jejudatahub.net/data/view/data/812 | JSON 스냅샷 `hub_812.json` 129건 | 위와 같음 | 분류 매칭 2곳, DB `hub_812` 2곳 | +| 784 해수욕장 정보 | 허브 파일 — https://jejudatahub.net/data/view/data/784 | CSV 88행(해변 11곳 × 2016~2023), 좌표 없음 | `해변명`, `기준일(년)` | 해변명+'해수욕장'/'해변' 이름이 같은 장소에 '해수욕장' 분류 4곳 | +| 858 무장애 여행지 정보(통합) | 허브 파일 (제주특별자치도) — https://jejudatahub.net/data/view/data/858 | CSV 120행 | `장소명`, `위도`, `경도` | 정제 장소와 이름·좌표 일치 39곳(검증용), 그중 이름 키워드로 분류가 정해지는 8곳만 분류로 사용 | + +- 811·812·858의 정확한 이용조건(카카오위치서비스 원자료 표기 등)은 **미확인**. 허브 공개 데이터로 활용했다. + +### 2.6 912 관광상품 선호·구매 데이터 (보조 · 권역 근거) + +- 제공: 제주데이터허브 (제공기관: 넥스트이지) — https://jejudatahub.net/data/view/data/912 +- 사용: 구매 파일 `TRRSRT_AREA_NM` 값(서부권 2,330 · 동부권 1,816 · 중문/서귀포 1,237 · 제주시내권 553행)을 근거로 권역 4개(제주시내권·서부권·동부권·중문·서귀포권, `config/regions.json`)를 정했다. **DB에는 적재하지 않는다.** + +### 2.7 외부 데이터 + +| 데이터 | 제공·URL | 이용조건 | 사용 | +|---|---|---|---| +| 한국관광공사 국문 관광정보 서비스_GW (TourAPI KorService2) | 공공데이터포털 https://www.data.go.kr/data/15101578/openapi.do | 공공데이터포털 이용허락 조건 적용. 공공누리 유형 **미확인**(`docs/05_submission/README.md`에도 '확인 필요') | 제주(법정동 시도코드 50) 관광지·문화시설·레포츠·쇼핑·음식점 1,875건 스냅샷(`areaBasedList2`, 개요 `detailCommon2`). ① 1349 장소 분류 참조(신분류 `lclsSystm3` 이름) ② 음식점·카페 512곳을 장소로 추가(1349에 같은 이름 장소가 있으면 제외) ③ 개요(overview) | +| 행정동 경계 vuski/admdongkor ver20261001 | https://github.com/vuski/admdongkor (원자료: 통계청 SGIS 행정구역 경계) | **CC BY 4.0** (원자료 공공누리 1유형). 화면·출처 표에 "SGIS 행정동 경계(가공: vuski/admdongkor)" 표기 | 제주 행정동 43개 → 좌표의 읍면동 판정(점-다각형), 화면 지도 `map.json`(단순화) | + +- 화면 3D 지형(Copernicus DEM GLO-30), 글꼴·아이콘·라이브러리는 B 트랙이 `docs/05_submission/README.md` 명시 사항 표에 기록했다. + +--- + +## 3. 전처리·매칭 흐름 (ETL, `python -m malttara.etl.build_db`) + +``` +원본(data/raw/) + 0) 경계: admdongkor GeoJSON → 제주 행정동 43개 다각형 + 1) 1349 정제: 본섬 범위(bbox)·부속섬(주소·이름·좌표 원) 제외, 비장소 키워드(숙소·렌터카·식사 등)·무의미 이름·행정구역명 제외, + 같은 정규화 이름 2km 안 병합 → 2,284곳 + 읍면동 = 좌표가 들어간 행정동 다각형. 경계 밖(해안) 좌표는 1.5km 안 가장 가까운 행정동(58곳), 그래도 없으면 지번주소(3곳) + 부속섬 읍면동으로 판정된 좌표 1곳 제외 + 2) 좌표 오류 보정: 참조 데이터(TourAPI·811·812·784·858)와 이름은 같은데 모든 참조 좌표에서 2km 넘게 떨어진 1349 기록 + → 참조가 한 곳이면 그 좌표로 이동(88곳), 여러 곳이면 제외(16곳) → 2,268곳 + 3) 분류 매칭: TourAPI → 811/812/784 → 858 → 이름 키워드 순 (빌드 로그: TourAPI 390 · 811 5 · 812 2 · 784 4 · 858 8 · 키워드 529 · 없음 1,330) + 4) TourAPI 음식점·카페 512곳 추가(같은 정제 규칙, 1349와 같은 이름·2km 안이면 제외) + 5) 같은 권역·같은 정규화 이름 중복 108곳 제외(참조 매칭 > 키워드 > 분류 없음 순으로 남김) → 2,672곳 + 6) 563 집계: 2.4GB를 한 줄씩 읽어 읍면동 × 월 합계 → 41개 읍면동 × 13 = 533행 + 7) 1208 집계: 186,606점 → 장소마다 반경 1km 점 수(quiet_count) + 8) 189/190: 관광지 50곳 → 장소 29곳 매칭, 월별 4,255행 + 9) 인지도: 1349 원본에서 같은 정규화 이름 기록 수 → popularity (1349 장소 2,160곳에 값) +10) 분류 표시명 정리, 추천 범위(in_scope) 판정: 권역이 없거나, 분류가 없는 1349 기록은 in_scope=0(DB에는 남김) +11) SQLite 쓰기(data_sources·meta.build_stats 포함), map.json 생성 +``` + +- 수작업 대응표: `data/mapping/emd_alias.csv`(읍면동 이름 별칭), `data/mapping/sights_to_places.csv`(입장객 관광지 → 장소). +- 563의 `emd_name` 43개는 행정동 경계 키와 모두 일치했다(별칭 불필요, 카드 확인). +- `data_sources.notes`의 1349 설명 문구 "50m 내 같은 이름 중복 제거"는 코드의 옛 문구다. 실제 병합 거리는 `config/etl.json`의 `dedup_max_m = 2000`(2km). + +--- + +## 4. 현재 DB의 장소·매칭 현황 (2026-11-19 빌드) + +### 장소 수 + +| 구분 | 전체 | 추천·목록 대상(in_scope=1) | +|---|---|---| +| 1349 출처 | 2,160 | 871 | +| TourAPI 출처(음식점·카페) | 512 | 512 | +| **합계** | **2,672** | **1,383** | + +| 권역 | 추천 대상 | 제외(in_scope=0) | +|---|---|---| +| 제주시내권 (city) | 297 | 239 | +| 서부권 (west) | 400 | 396 | +| 동부권 (east) | 399 | 412 | +| 중문·서귀포권 (south) | 287 | 240 | +| 권역 없음 | 0 | 2 | + +- 제외 1,289곳은 분류가 없는 1349 기록(이용자 메모형 기록 포함)과 권역 없는 장소 2곳이다. 추천과 '직접 고르기' 목록에서 빠지고 DB에는 남는다. + +### 분류 출처 (추천 대상 1,383곳) + +| category_source | 곳 | 비율 | +|---|---|---| +| tourapi | 859 | 62.1% | +| keyword (이름 키워드) | 506 | 36.6% | +| hub_858 | 8 | 0.6% | +| hub_784 | 4 | 0.3% | +| hub_811 | 4 | 0.3% | +| hub_812 | 2 | 0.1% | + +(추천 대상은 정의상 모두 분류가 있다. 전체 2,672곳 중 분류 없음은 1,287곳) + +### 지표 연결률 (추천 대상 1,383곳) + +| 지표 | 연결 | 비고 | +|---|---|---| +| 563 읍면동 지표 | 1,383곳(100%) | 전체 2,672곳 기준 2,670곳 | +| 1208 반경 지표 | 1,368곳(98.9%) | 0건 15곳은 '지표 없음'(중립) | +| 189·190 입장객 추이 | 29곳(2.1%) | 관광지 50곳 중 29곳 매칭 | +| 개요(overview) | 371곳(26.8%) | 1349 출처 214/871, TourAPI 출처 157/512 | +| 인지도(1349 기록 수) | 871곳 | 1349 출처 추천 대상 전부. 최대 57건 | + +--- + +## 5. 에이전트에서의 사용 (점수·Tool) + +``` +점수 = w1 × 관심사 + w2 × 분산(563) + w3 × 한적(1208) + w4 × 인지도(1349 기록 수) +현재 가중치(config/settings.json, 2026-11-19): 기본 (0.5, 0.15, 0.15, 0.2) · 한적함 요청 시 (0.4, 0.25, 0.25, 0.1) +``` + +| 항 | 데이터 | 계산 | +|---|---|---| +| 관심사 | 분류(TourAPI·811·812·784·858·키워드) | 장소 분류가 관심사 분류 목록(`config/interests.json`)에 있으면 1, 아니면 0. 관심사 미입력이면 분류 있는 장소 1 | +| 분산 | 563 | 1 − 읍면동 visit_ratio 백분위. 지표 없으면 0.5 | +| 한적 | 1208 | 1 − quiet_count 백분위. 0건·없음이면 0.5 | +| 인지도 | 1349 | 같은 이름 기록 수의 백분위. 하루마다 관심사 일치 + 기록 최다 장소 1곳을 대표지로 넣음 | + +| Tool (`src/malttara/tools/`) | 쓰는 데이터 | +|---|---| +| `search_places`, `score_places` | places(1349·TourAPI), emd_stats(563), quiet_count(1208), popularity(1349) | +| `get_region_data` | emd_stats(563) | +| `analyze_tourism` | sight_visits(189·190) | +| `check_data_quality` | 분류·지표 결측 수 집계 → 실행 로그와 결과 `quality` | +| `create_itinerary`, `calculate_route`, `validate_itinerary` | 장소 좌표(하버사인 직선거리), 권역 | +| `explain_decisions`, `export_travel_plan` | 각 지표의 source_id·기간(`data_sources.period_actual`)을 근거 문장·인쇄물 출처 표에 표시 | + +- 한적함 요청("조용한·한적한·덜 붐비는")은 가중치를 바꿔 563·1208 지표가 순위를 더 크게 움직이게 한다. +- 지표가 없으면 값을 지어내지 않고 `missing: true`, 값 `null`로 내보낸다(인수 테스트 5·9). + +--- + +## 6. 재현성 + +- 같은 DB(`data_version`) + 같은 설정(`config/`) + 같은 조건 → 같은 순위·같은 일정(동점은 `place_id` 순). 인수 테스트 2(`tests/test_acceptance.py`). +- 데이터 지표가 바뀌면 순위가 바뀐다(인수 테스트 4: 한 장소의 반경 체류 수를 최댓값보다 크게 → 한적함 요청 순위 하락). +- 출처·기준 시점은 모든 장소 지표(`source_id`, `period`)와 인쇄물 출처 표에 나온다(인수 테스트 9). + +--- + +## 7. 한계 + +- **1349는 이용자가 여행 일정에 입력한 장소 기록**이다. 같은 장소가 여러 좌표로 반복되고(카드 점검 시 '성산일출봉'만 43건), 좌표·지번주소 오류, 숙소·식사 같은 비장소 이름이 섞여 있다. 정제(같은 이름 2km 병합, 좌표 오류 이동 88곳·제외 16곳, 같은 권역 중복 108곳 제외, 분류 없는 기록 추천 제외)로 줄였지만 완전히 없앨 수는 없다. 인지도 항도 "여행자 기록 수"이지 실제 방문객 수가 아니다. +- **1208은 2021년 7~12월 토요일 렌터카 표본**이다. 평일·대중교통·도보 여행자·현재 상황을 반영하지 않는다. "현재 혼잡도"로 표현하지 않는다. +- **563은 2022-09에서 끝나는 내국인 유동인구**다. 외국인·2022-10 이후는 반영되지 않는다. 읍면동 단위 통계이므로 장소의 속성으로 쓰지 않는다. +- 189·190은 관광지 50곳 중 29곳만 장소와 연결되어 점수에 넣지 않고 근거 차트로만 쓴다. +- 개요(overview)는 추천 대상의 26.8%(371곳)에만 있다. 개요가 없으면 화면에 비워 둔다. +- 허브 보조 데이터(811·812·784·858)의 분류 매칭은 수 곳에 그친다. 분류 대부분은 TourAPI와 이름 키워드에서 왔고, 키워드 분류는 이름만 보고 붙이므로 틀릴 수 있다. +- 부속섬(우도·추자 등)은 배 이동을 직선거리로 검증할 수 없어 제외했다. +- 거리는 직선이며 도로·대중교통·이동시간을 반영하지 않는다. +- 데이터별 공공누리 유형 등 세부 이용조건은 일부 **미확인**이다(2장 표의 '미확인' 항목). + +--- + +## 8. 데이터 API 키 + +- 제주데이터허브 프로젝트키(811·812 Open API), 공공데이터포털 서비스키(TourAPI)는 **제출물에 포함하지 않았다**. 발급·설정 방법: `docs/05_submission/manual_run.md` 9장. +- 실행 중에는 데이터 API를 호출하지 않으므로 평가 실행에 키가 필요 없다. + +--- + +## 9. 수치 다시 확인하는 법 + +``` +py -3 -c "import sqlite3; c=sqlite3.connect('data/db/malttara.sqlite'); print(c.execute('select source, in_scope, count(*) from places group by 1,2').fetchall()); print(c.execute('select value from meta where key=?', ('build_stats',)).fetchone()[0])" +``` +- `data_sources` 표: 데이터별 원본 행 수·실제 기간·수신일·매칭 메모. +- `meta.build_stats`: ETL 단계별 건수(이 문서 3장 숫자의 출처). diff --git a/docs/05_submission/manual_run.md b/docs/05_submission/manual_run.md new file mode 100644 index 0000000..169cc0e --- /dev/null +++ b/docs/05_submission/manual_run.md @@ -0,0 +1,251 @@ +# 말따라 제주 — 실행환경·설치·실행 매뉴얼 + +- 대상: 개발 경험이 없는 평가자·센터 운영자. 순서대로 따라 하면 실행된다. +- 작성: 2026-11-19 (A 트랙). 근거: `run.bat`, `run.py`, `src/malttara/server/app.py`, `src/malttara/agent/llm.py`, `src/malttara/etl/build_db.py`, `.env.example`, `config/settings.json` +- 한 줄 요약: **Python 3.11 이상만 설치하고 `run.bat`을 더블클릭한다.** 추가 패키지 설치는 없다. + +--- + +## 1. 실행 환경 + +| 항목 | 내용 | +|---|---| +| 운영체제 | Windows 10/11 64비트 (센터 PC: Windows 11, i7-8700, GTX 1060, RAM 32GB에서 실행하는 것을 전제로 만들었다) | +| Python | **3.11 이상** (python.org 공식 설치본 권장. 개발은 3.14, 코드는 3.11 문법만 사용) | +| 추가 Python 패키지 | **없음.** 실행 중 코드는 Python 표준 라이브러리만 쓴다(`requirements.txt`는 비어 있다). `pip install` 단계가 없다 | +| Node.js·빌드 도구 | 필요 없음. 화면(`web/dist`)은 이미 만들어진 파일로 동봉한다 | +| GPU·VRAM | 사용하지 않음. 로컬 AI 모델을 돌리지 않는다 | +| 브라우저 | Chrome 또는 Edge 최신판 (Windows 기본 브라우저가 자동으로 열린다) | +| 인터넷 | 없어도 전 기능이 돈다(규칙 기반 모드). 있고 AI 키가 있으면 외부 AI(Upstage Solar Pro 4)를 쓴다 | +| 디스크 | 압축 해제 후 수십 MB 수준. 압축을 푼 폴더에 **쓰기 권한**이 있어야 한다(실행 기록을 DB에 저장) | +| 서명 없는 확장 모듈(.pyd/.dll) | 쓰지 않음. 외부 패키지를 설치하지 않으므로 센터 보안 정책의 확장 모듈 실행 제한에 걸리지 않는다 | + +자동 검사: `tests/test_acceptance.py`의 `test_11_runtime_imports_stdlib_only`가 실행 중 코드(`src/malttara/` 중 ETL 제외, `run.py`)에 표준 라이브러리 밖 import가 없는지 확인한다. + +--- + +## 2. 폴더 구성 (압축을 푼 뒤) + +``` +malttara-jeju/ +├─ run.bat ← 더블클릭해서 실행 (Windows) +├─ run.py ← 실제 실행 파일 (run.bat이 호출) +├─ .env.example ← 환경변수 예시 (키 칸이 비어 있음) +├─ .env ← 평가용 AI 키 파일 (제출본에만, 4장 참고. 없으면 규칙 기반으로 동작) +├─ requirements.txt ← 비어 있음 (실행에 필요한 패키지 없음) +├─ requirements-etl.txt ← 데이터 다시 만들기(ETL)용, 평가 실행에는 불필요 +├─ config/ ← 가중치·권역·관심사 설정(JSON) +├─ src/malttara/ ← 에이전트·Tool·서버 코드, 프롬프트(agent/prompts.py) +├─ data/db/malttara.sqlite ← 가공 데이터베이스 (제주데이터허브 데이터 가공본, 동봉) +├─ data/db/map.json ← 화면 지도용 읍면동 경계 (동봉) +├─ web/dist/ ← 화면 파일 (index.html, js, css, fonts 등, 동봉) +├─ tests/ ← 자동 테스트 +└─ docs/05_submission/ ← 이 매뉴얼, 데이터 활용 명세 +``` + +| 파일 | 없으면 | +|---|---| +| `data/db/malttara.sqlite` | 실행 직후 "데이터 파일이 없습니다" 안내 후 종료 (7장) | +| `data/db/map.json` | 화면 지도만 비어 보인다(경로 생성은 동작) | +| `web/dist/` | 브라우저에 "프론트 빌드(web/dist)가 없습니다" 안내 문구만 보인다 | +| `.env` | AI 키 없음 → 규칙 기반 모드로 전 기능 동작 | + +--- + +## 3. 설치 순서 (최초 1회) + +### 3-1. Python 설치 +1. https://www.python.org/downloads/ 에서 **Python 3.11 이상**의 Windows installer (64-bit)를 받는다. +2. 설치 첫 화면 아래쪽 **"Add python.exe to PATH"를 체크**한다. ("Use admin privileges when installing py.exe"는 기본값 그대로 둔다.) +3. **Install Now**를 누르고 끝날 때까지 기다린다. +4. 확인: 시작 메뉴에서 "명령 프롬프트"를 열고 아래를 입력한다. `Python 3.11.x` 이상이 나오면 된다. + ``` + py --version + ``` + (`py`가 없다고 나오면 `python --version`) + +> 관리자 권한은 Python 설치에만 필요할 수 있다. 프로그램 실행에는 필요 없다. + +### 3-2. 결과물 압축 풀기 +1. 제출 ZIP을 **쓰기 가능한 폴더**(예: `C:\malttara-jeju` 또는 바탕화면)에 **압축 풀기**한다. +2. ZIP 미리보기 창 안에서 바로 실행하지 않는다(쓰기 불가 → 실행 기록 저장 실패). `C:\Program Files` 아래도 피한다. +3. 경로 문제를 피하려면 영문 경로(`C:\malttara-jeju`)를 권장한다. + +### 3-3. (선택) AI 키 확인 +- 제출본에는 평가용 `.env`가 들어 있다(4장). 따로 할 일은 없다. + +추가 설치(`pip install`)는 **하지 않는다.** + +--- + +## 4. 환경변수(.env)와 AI 키 + +### 4-1. 위치와 읽는 방식 +- 파일 위치: **`run.py`와 같은 폴더의 `.env`** (`malttara-jeju\.env`). +- `run.py`가 시작할 때 이 파일을 한 번 읽는다(`src/malttara/config.py`의 `load_env`). `KEY=VALUE` 형식의 줄만 읽고, `#`으로 시작하는 줄은 무시한다. +- 같은 이름의 Windows 환경변수가 있으면 그 값이 우선한다. +- 키 값은 화면·콘솔·로그·DB 어디에도 기록하지 않는다(`agent/llm.py`). +- 키가 비어 있거나 파일이 없으면 **규칙 기반 모드**로 동작한다. 콘솔에 `AI 키 없음 → 규칙 기반으로 동작`이 표시된다. + +### 4-2. AI 관련 항목 (`.env.example`과 같은 이름) + +| 이름 | 뜻 | 평가용 값(예시 형식, 실제 키는 제출본 `.env`에만) | +|---|---|---| +| `LLM_API_KEY` | 외부 AI API 키 | Upstage 콘솔에서 발급한 키 (이 문서에는 적지 않는다) | +| `LLM_BASE_URL` | API 주소 | `https://api.upstage.ai/v1` | +| `LLM_MODEL` | 모델 이름 | `solar-pro4` | +| `LLM_JSON_MODE` | JSON 응답 방식 | `schema` | +| `LLM_EXTRA_BODY` | 추가 요청 값(JSON) | 비워 둔다 | + +- 세 값(`LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL`)이 모두 있어야 AI를 쓴다. 하나라도 비면 규칙 기반이다. +- AI 호출 1회 제한 시간은 20초(`config/settings.json`의 `llm.timeout_s`). 실패·시간 초과·형식 오류면 그 판단만 규칙으로 바꿔 계속 진행한다. +- 평가용 키는 **사용 한도를 설정**했고 **평가 종료 후 폐기**한다(대회 규칙의 AI API 키 예외 조항). +- 평가용 키를 직접 넣어야 하는 경우: `.env.example`을 복사해 이름을 `.env`로 바꾸고, 위 표의 값을 채운 뒤 저장한다(메모장 사용 가능, 인코딩 UTF-8). + +### 4-3. 데이터 API 키 (평가 실행에는 필요 없음) +- 제주데이터허브 프로젝트키(`HUB_PROJECT_KEY`), 공공데이터포털 서비스키(`DATA_GO_KR_KEY`)는 **제출물에 넣지 않았다**(대회 규칙). +- 이 키들은 **데이터를 처음부터 다시 만들 때(9장)만** 필요하다. 실행 중에는 외부 데이터 API를 호출하지 않는다. 모든 데이터는 `data/db/malttara.sqlite`에 가공해 동봉했다. + +--- + +## 5. 최초 실행 + +1. 압축을 푼 폴더에서 **`run.bat`을 더블클릭**한다. +2. 검은 콘솔 창이 열리고 아래와 비슷한 줄이 나온다. + ``` + 말따라 제주 실행 중: http://127.0.0.1:8765/ (AI 연결됨) + 끝내려면 이 창에서 Ctrl+C를 누르세요. + ``` + - `(AI 연결됨)`: `.env`에 AI 설정 세 값이 있음 (실제 연결 여부는 첫 AI 호출 때 확인되며, 실패하면 규칙으로 넘어간다) + - `(AI 키 없음 → 규칙 기반으로 동작)`: 키 없이 동작 +3. 기본 브라우저가 자동으로 `http://127.0.0.1:8765/`를 연다. 안 열리면 브라우저 주소창에 직접 입력한다. +4. 화면 흐름: **01 여행 설명·조건 확인 → 02 경로 만들기 → 03 미리보기(말 타이핑 게임 또는 목록) → 04 다시 짜기·최종 계획**. 화면의 "사용 가이드" 버튼(30초 사용 가이드)을 누르면 단계별 안내가 나온다. +5. **끝내기**: 콘솔 창에서 `Ctrl+C`를 누른 뒤 아무 키나 눌러 창을 닫는다(또는 창의 X). + +`run.bat`이 하는 일: 콘솔을 UTF-8로 바꾸고(`chcp 65001`, `PYTHONUTF8=1`) → `py -3 run.py`를 실행, `py`가 없으면 `python run.py` → 둘 다 없으면 Python 설치 안내를 출력하고 멈춘다. + +### 명령 프롬프트에서 실행하기 (선택) +``` +cd C:\malttara-jeju +py -3 run.py 실제 데이터로 실행 (기본 포트 8765) +py -3 run.py --port 9000 다른 포트로 실행 +py -3 run.py --no-browser 브라우저를 자동으로 열지 않음 +py -3 run.py --mock 모의 데이터로 실행 (DB 없이 화면 확인용, 실제 장소 아님) +``` +(`py`가 없으면 `python`으로 바꿔 입력) + +### 키오스크 운영 팁 +- 브라우저에서 `F11`로 전체 화면. +- 서버는 이 PC 안(`127.0.0.1`)에서만 접속되며 외부에 열리지 않는다. 그래서 보통 Windows 방화벽 허용 창이 뜨지 않는다. 뜨면 "취소"해도 동작한다. + +--- + +## 6. 동작 확인 (설치 직후 1분 점검) + +| 확인 | 방법 | 기대 결과 | +|---|---|---| +| 서버 상태 | 브라우저에서 `http://127.0.0.1:8765/api/health` | `{"ok": true, "llm_available": true 또는 false, "data_version": "2026-11-19"}` 형태 | +| 경로 생성 | 01 화면에 "2박 3일 바다 보고 싶어요, 여유롭게" 입력 → 02 진행 | 실행 로그가 한 줄씩 나오고 3일 일정 생성 | +| AI 없이 동작 | `.env`의 `LLM_API_KEY=` 값을 지우고 재실행 | 콘솔에 `AI 키 없음 → 규칙 기반으로 동작`, 같은 흐름 완주 | +| 자동 테스트(선택) | 명령 프롬프트에서 아래 명령 | 마지막 줄 `OK` | + +``` +cd C:\malttara-jeju +set PYTHONPATH=src +py -3 -m unittest discover -s tests -v +``` +(인수 테스트 11종만: `py -3 -m unittest tests.test_acceptance -v`) + +--- + +## 7. 오류와 조치 + +| 증상 | 원인 | 조치 | +|---|---|---| +| `Python 3.11 이상이 필요합니다...` 출력 후 멈춤 | Python 미설치 또는 PATH 미등록 | 3-1을 다시 하되 "Add python.exe to PATH" 체크. 설치 후 `run.bat`을 다시 더블클릭 | +| `python`을 입력하면 Microsoft Store가 열림 | Windows 앱 실행 별칭 | `run.bat`은 `py`를 먼저 쓰므로 보통 문제없다. 계속되면 설정 → 앱 → 고급 앱 설정 → 앱 실행 별칭에서 python.exe·python3.exe 끄기 | +| `포트 8765를 쓸 수 없습니다(이미 실행 중일 수 있습니다)` | 이미 켜진 서버 창이 있거나 다른 프로그램이 포트 사용 | 먼저 열린 말따라 제주 콘솔 창을 닫는다. 그래도 안 되면 명령 프롬프트에서 `py -3 run.py --port 9000` 후 `http://127.0.0.1:9000/` 접속 | +| `데이터 파일이 없습니다: data/db/malttara.sqlite` | 압축이 덜 풀렸거나 DB 파일이 빠짐 | ZIP을 다시 "모두 압축 풀기". `data\db\malttara.sqlite`가 있는지 확인. 화면만 볼 때는 `py -3 run.py --mock` | +| 브라우저가 자동으로 안 열림 | 기본 브라우저 미설정 등 | 콘솔에 나온 주소 `http://127.0.0.1:8765/`를 Chrome·Edge 주소창에 직접 입력 | +| 화면에 "프론트 빌드(web/dist)가 없습니다" | `web/dist` 폴더 누락 | ZIP을 다시 압축 풀기. (개발 저장소라면 `py -3 web/build.py` 실행) | +| 화면이 하얗게 비어 있음 | 브라우저 캐시·구버전 브라우저 | `Ctrl+F5` 새로고침, Chrome/Edge 최신판 사용 | +| 콘솔에 `AI 키 없음 → 규칙 기반으로 동작` | `.env` 없음 또는 키 칸 비어 있음 | 정상 동작(규칙 기반). AI를 쓰려면 4-2대로 `.env` 작성 후 재실행 | +| AI 키가 있는데 각 단계가 오래 걸림(수십 초) | 인터넷 차단·API 장애로 AI 호출이 제한 시간(20초)까지 기다린 뒤 규칙으로 넘어감 | 결과는 정상이다. 오프라인 환경이면 `.env`의 `LLM_API_KEY=`를 비워 처음부터 규칙 기반으로 실행 | +| 경로를 만들 때 "여행 기간이 없습니다" | 입력에 기간이 없음 | "2박 3일", "당일치기"처럼 기간을 넣는다(1~7일) | +| `database is locked` 또는 저장 실패 | 쓰기 불가 폴더(ZIP 내부·Program Files) 또는 서버 두 개 동시 실행 | 쓰기 가능한 폴더로 옮기고 서버 창을 하나만 띄운다 | +| 콘솔 한글이 깨짐 | 콘솔 코드페이지 | `run.bat`으로 실행하면 UTF-8로 맞춘다. 직접 실행할 때는 `chcp 65001` 후 실행 | + +--- + +## 8. 제약사항 + +- 거리는 장소 사이 **직선거리**다. 도로망 데이터가 없어 이동 시간·도로 거리를 표시하지 않는다. +- 지역 지표(563)는 2018-01~2022-09 내국인 유동인구, 장소 주변 지표(1208)는 2021년 7~12월 토요일 렌터카 표본이다. "현재 혼잡도"가 아니다. +- 부속섬(우도·추자 등)은 추천 범위에서 뺀다. +- 한 번에 한 명의 키오스크 사용자를 가정한다. +- 자세한 데이터 한계는 `docs/05_submission/data_spec.md` 7장. + +--- + +## 9. (개발자용) 데이터 다시 만들기 — 평가 실행에는 필요 없음 + +제출본에는 가공 DB(`data/db/malttara.sqlite`, `map.json`)가 들어 있어 이 단계가 필요 없다. 원본부터 다시 만들 때만 한다(개발 PC 기준, 563 원본이 약 2.4GB라 수 분 걸린다). + +### 9-1. 키 발급 (제출물에 키 없음) +| 키 | 발급 방법 | 용도 | +|---|---|---| +| `HUB_PROJECT_KEY` | 제주데이터허브(https://jejudatahub.net) 회원가입·로그인 → 데이터 상세에서 "프로젝트 담기" → 마이페이지 → 프로젝트 관리 → 프로젝트 상세에서 프로젝트키 확인 | 허브 Open API 811·812 스냅샷 | +| `DATA_GO_KR_KEY` | 공공데이터포털(https://www.data.go.kr) 로그인 → "한국관광공사_국문 관광정보 서비스_GW"(https://www.data.go.kr/data/15101578/openapi.do) 활용신청 → 마이페이지에서 일반 인증키 확인 | TourAPI 분류·개요·음식점 스냅샷 | + +받은 키는 `.env`의 같은 이름 칸에만 적는다. 코드·문서에 적지 않는다. + +### 9-2. 원본 파일 배치 (`data/raw/`) +허브 파일형 데이터는 허브에 로그인 → 데이터 상세 페이지(`https://jejudatahub.net/data/view/data/{ID}`) → 프로젝트 담기 → 첨부파일 다운로드. 상세: `data/guides/how-to-collect.md`. + +| 위치 | 파일 | 받는 곳 | +|---|---|---| +| `data/raw/1349/` | `제주관광공사_제주관광정보시스템(VISIT JEJU)_여행장소.csv` | 허브 1349 | +| `data/raw/563/` | `내국인 유동인구 구성비율.csv` (약 2.4GB) | 허브 563 | +| `data/raw/1208/` | `체류거점_2021_07.csv` ~ `체류거점_2021_12.csv` (6개) | 허브 1208 | +| `data/raw/189/` | `제주특별자치도_내국인관광지입장객수추이.csv` | 허브 189 | +| `data/raw/190/` | `제주특별자치도_외국인관광지입장객수추이.csv` | 허브 190 | +| `data/raw/784/` | `제주특별자치도해수욕장정보.csv` | 허브 784 | +| `data/raw/858/` | `무장애여행정보.csv` | 허브 858 | +| `data/raw/hub_811.json`, `hub_812.json` | 허브 Open API 스냅샷 | 아래 `fetch_hub` 명령으로 생성 | +| `data/raw/tourapi_jeju.json` | TourAPI 스냅샷 | 아래 `fetch_tourapi` 명령으로 생성 | +| `data/raw/boundary/HangJeongDong_ver20261001.geojson` | 행정동 경계 | https://github.com/vuski/admdongkor (ver20261001, CC BY 4.0) | + +(912 파일은 권역 이름 확인에만 썼고 DB 빌드에는 쓰지 않는다.) + +### 9-3. 명령 (프로젝트 폴더에서) +``` +py -3 -m pip install -r requirements-etl.txt +set PYTHONPATH=src +py -3 -m malttara.etl.fetch_hub 811 +py -3 -m malttara.etl.fetch_hub 812 +py -3 -m malttara.etl.fetch_tourapi +py -3 -m malttara.etl.build_db +``` +- `build_db` 기본 경로: 입력 `data/raw`, 출력 `data/db/malttara.sqlite`, `data/db/map.json` (`--raw`, `--db`, `--map`으로 바꿀 수 있음). +- 없는 원본은 그 단계만 건너뛰고 `[건너뜀]` 로그를 남긴다. 끝나면 단계별 건수를 출력하고, 같은 값이 DB `meta.build_stats`에 저장된다. +- 참고: 현재 ETL 코드도 표준 라이브러리만 import한다. `requirements-etl.txt`(pyshp, pyproj)는 경계 파일 형식이 바뀔 때를 대비한 예비 목록이다. +- 데이터 흐름·매칭 결과: `docs/05_submission/data_spec.md`. + +--- + +## 10. 검증 기록 (클린 PC 설치 확인 — 사람이 채운다) + +Python 공식 설치본만 있는 Windows(가능하면 다른 PC 또는 새 사용자 계정)에서 ZIP을 풀고 `run.bat` 더블클릭 → 01→04 완주. + +| 날짜 | 확인자 | PC·OS | Python 버전 | AI 키 | 결과(01→04 완주) | 걸린 시간 | 문제·조치 | +|---|---|---|---|---|---|---|---| +| | | | | 없음(규칙 기반) | | | | +| | | | | 있음(Solar Pro 4) | | | | +| | | | | 있음 + 인터넷 차단 | | | | + +자동 테스트 결과: + +| 날짜 | 명령 | 결과 | +|---|---|---| +| 2026-11-19 | `PYTHONPATH=src python -m unittest tests.test_acceptance -v` (개발 PC, Python 3.14, 모의 DB) | 11개 OK | +| | `py -3 -m unittest discover -s tests -v` (클린 PC) | | diff --git a/requirements-etl.txt b/requirements-etl.txt index 69c46bd..b77dde8 100644 --- a/requirements-etl.txt +++ b/requirements-etl.txt @@ -1,2 +1,3 @@ -pyshp==2.3.1 -pyproj==3.7.1 +# ETL도 표준 라이브러리만 쓴다(경계 GeoJSON이 WGS84라 변환 불필요). +# 좌표계가 다른 경계 파일을 쓸 때만 아래를 설치한다. +# pyproj==3.7.1 diff --git a/src/malttara/etl/build_db.py b/src/malttara/etl/build_db.py index b79fbe5..17533bd 100644 --- a/src/malttara/etl/build_db.py +++ b/src/malttara/etl/build_db.py @@ -237,7 +237,7 @@ def skip(name, why): stats["places_1349"] = len(places) log(f"[1349] 원본 {len(rows)}행 → 정제 후 {len(places)}곳") src("1349", rows=len(rows), fetched_at=_mtime_date(_csvs(raw_dir, "1349")[0]) if rows else None, - notes=f"정제 후 {len(places)}곳(본섬 범위·부속섬·비장소 제외, 50m 내 같은 이름 중복 제거)") + notes=f"정제 후 {len(places)}곳(본섬 범위·부속섬·비장소 제외, 같은 이름 2km 안 병합·좌표 오류 보정)") # 2) 분류 참조 세트 ref_sets = [] diff --git a/tests/test_acceptance.py b/tests/test_acceptance.py new file mode 100644 index 0000000..7b9e16e --- /dev/null +++ b/tests/test_acceptance.py @@ -0,0 +1,230 @@ +"""인수 테스트 10종(기획문서_v0 6.1) + 실행 중 코드 표준 라이브러리 검사. + +모의 DB(tests/helpers.py)로 돌린다. 점수 공식은 바뀔 수 있으므로 정확한 점수·장소 ID 대신 동작을 검사한다. +실행: PYTHONPATH=src python -m unittest tests.test_acceptance -v +""" +import ast +import os +import pathlib +import sys +import unittest +from datetime import datetime + +sys.path.insert(0, os.path.dirname(__file__)) +from helpers import I, R, S, goal, mock_conn +from malttara.agent.batch_a import run_batch_a +from malttara.agent.batch_b import run_batch_b +from malttara.agent.llm import LLMClient, client_from_env +from malttara.agent.state import BatchState +from malttara.db import data_sources +from malttara.tools.explain import export_travel_plan +from malttara.tools.feedback import analyze_feedback, load_events, record_event +from malttara.tools.goal import merge_goal, parse_goal_rules +from malttara.tools.places import score_places +from malttara.tools.quests import generate_quests + +ROOT = pathlib.Path(__file__).resolve().parent.parent +NO_LLM = LLMClient(None, None, None, 5) + + +def day_ids(res, day_index=None): + days = res["itinerary"]["days"] + if day_index is not None: + return list(days[day_index]["place_ids"]) + return [pid for d in days for pid in d["place_ids"]] + + +class Acceptance(unittest.TestCase): + def setUp(self): + self.conn, _ = mock_conn() + self._sec = 0 + + def tearDown(self): + self.conn.close() + + def _state(self, kind, prev=None): + self._sec += 1 # 배치마다 다른 시각 → 다른 batch_id + return BatchState(kind, datetime(2026, 11, 19, 10, 0, self._sec), prev_batch_id=prev) + + def run_a(self, g, inject=False, llm=NO_LLM): + st = self._state("A") + res = run_batch_a(self.conn, g, inject, llm, S, I, R, st) + return res, st + + def run_b(self, prev, llm=NO_LLM): + st = self._state("B", prev) + res = run_batch_b(self.conn, prev, llm, S, I, R, st) + return res, st + + # 1. 취향이 바뀌면 추천 결과가 바뀌는가 + def test_01_preference_changes_result(self): + sea, _ = self.run_a(goal(days=2, pace="여유롭게", interests=["바다"])) + forest, _ = self.run_a(goal(days=2, pace="여유롭게", interests=["숲"])) + self.assertNotEqual(set(day_ids(sea, 0)), set(day_ids(forest, 0))) # 1일차 장소 집합이 다르다 + sea_cats = set(I["interests"]["바다"]["categories"]) + forest_cats = set(I["interests"]["숲"]["categories"]) + self.assertIn(sea["places"][day_ids(sea, 0)[0]]["category"], sea_cats) + self.assertIn(forest["places"][day_ids(forest, 0)[0]]["category"], forest_cats) + + # 2. 같은 조건에서 같은 결과가 나오는가 + def test_02_same_input_same_result(self): + g = goal(days=3, pace="여유롭게", interests=["바다", "음식"]) + a1, _ = self.run_a(dict(g)) + a2, _ = self.run_a(dict(g)) + self.assertNotEqual(a1["batch_id"], a2["batch_id"]) + self.assertEqual(a1["itinerary"], a2["itinerary"]) + self.assertEqual(a1["routes"], a2["routes"]) + self.assertEqual(a1["alternatives"], a2["alternatives"]) + r1 = [p["place_id"] for p in score_places(self.conn, g, S, I)] + r2 = [p["place_id"] for p in score_places(self.conn, g, S, I)] + self.assertEqual(r1, r2) + + # 3. 추천을 거부하면 적절한 대안을 주는가 + def test_03_rejection_gives_alternative(self): + a, _ = self.run_a(goal(days=2)) + target = day_ids(a, 0)[0] + region = a["places"][target]["region_id"] + self.assertTrue(a["alternatives"].get(target)) # 거부 전에도 대안이 보인다 + self.assertTrue(all(a["places"][x]["region_id"] == region for x in a["alternatives"][target])) + record_event(self.conn, a["batch_id"], target, "feedback", "dislike") + b, st = self.run_b(a["batch_id"]) + self.assertIsNotNone(b, st.error) + self.assertNotIn(target, day_ids(b)) + ch = {x["place_id"]: x for x in b["diff"]} + self.assertEqual(ch[target]["change"], "replace") + new = ch[target]["replaced_by"] + self.assertIn(new, b["places"]) + self.assertNotEqual(new, target) + self.assertEqual(b["places"][new]["region_id"], region) # 같은 권역 대안 + self.assertEqual(len(day_ids(b)), len(day_ids(a))) # 하루 장소 수 유지 + + # 4. 데이터셋 지표가 바뀌면 추천에 반영되는가 + def test_04_indicator_change_changes_rank(self): + g = goal(interests=["바다"], quiet_pref=True) + before = score_places(self.conn, g, S, I) + max_q = max(p["quiet_count"] for p in before if p["quiet_count"] is not None) + target = next(p for p in before if p["quiet_count"] is not None and p["quiet_count"] < max_q) + rank_before = [p["place_id"] for p in before].index(target["place_id"]) + self.conn.execute("UPDATE places SET quiet_count = ? WHERE place_id = ?", (max_q + 1000, target["place_id"])) + self.conn.commit() + after = score_places(self.conn, g, S, I) + rank_after = [p["place_id"] for p in after].index(target["place_id"]) + moved = next(p for p in after if p["place_id"] == target["place_id"]) + self.assertLess(moved["quiet"], target["quiet"]) + self.assertEqual(moved["indicators"]["nearby"]["quiet_count"], max_q + 1000) + self.assertGreater(rank_after, rank_before) # 체류 거점이 많아지면 순위 하락 + + # 5. 필수 데이터가 빠졌을 때 안전하게 처리하는가 + def test_05_missing_data_safe(self): + self.conn.execute("DELETE FROM emd_stats") + self.conn.commit() + res, st = self.run_a(goal(days=2, quiet_pref=True)) + self.assertIsNotNone(res, st.error) + self.assertTrue(st.done) + self.assertTrue(all(d["place_ids"] for d in res["itinerary"]["days"])) + self.assertGreater(res["quality"]["no_region_indicator"], 0) + for pid in day_ids(res): + reg = res["places"][pid]["indicators"]["region"] + self.assertTrue(reg["missing"]) + self.assertIsNone(reg["visit_ratio"]) # 없는 값을 지어내지 않는다 + + # 6. LLM 실행에 실패해도 핵심 서비스가 동작하는가 + def test_06_llm_failure_still_works(self): + def boom(*a): + raise OSError("LLM 서버 응답 없음") + broken = LLMClient("test-key", "http://llm.invalid", "m", 1, transport=boom) + self.assertTrue(broken.available) + self.assertIsNone(broken.chat_json("s", "u", {"type": "object"})) + res, st = self.run_a(goal(days=2, interests=["바다"]), inject=True, llm=broken) + self.assertIsNotNone(res, st.error) + actors = {e["actor"] for e in st.events_after(0)} + self.assertNotIn("llm", actors) + self.assertIn("rule", actors) + self.assertTrue(day_ids(res)) + self.assertTrue(res["summary"]) + record_event(self.conn, res["batch_id"], day_ids(res)[0], "feedback", "dislike") + b, st_b = self.run_b(res["batch_id"], llm=broken) + self.assertIsNotNone(b, st_b.error) + self.assertNotIn("llm", {e["actor"] for e in st_b.events_after(0)}) + + # 7. 인터넷을 끊어도 필수 기능이 동작하는가(규칙 기반 모드) + def test_07_offline_rule_mode(self): + llm = client_from_env({}, S) # .env에 AI 키 없음 + self.assertFalse(llm.available) + text = "2박 3일 바다 보러 여유롭게" + rule = parse_goal_rules(text, I) + g, used = merge_goal(None, rule, text, I) + self.assertFalse(used) + self.assertEqual(g["days"], 3) + self.assertIn("바다", g["interests"]) + res, st = self.run_a(g, llm=llm) + self.assertIsNotNone(res, st.error) + self.assertEqual(len(res["itinerary"]["days"]), 3) + self.assertNotIn("llm", {e["actor"] for e in st.events_after(0)}) + b, st_b = self.run_b(res["batch_id"], llm=llm) + self.assertIsNotNone(b, st_b.error) + + # 8. 게임과 대시보드(목록)에서 같은 분석 결과가 나오는가 + def test_08_game_and_list_same_analysis(self): + res, _ = self.run_a(goal(days=3, interests=["바다", "음식"])) + self.assertEqual(len(res["quests"]), len(res["itinerary"]["days"])) + for q, d in zip(res["quests"], res["itinerary"]["days"]): + self.assertEqual(q["day"], d["day"]) + self.assertEqual([i["place_id"] for i in q["items"]], d["place_ids"]) + self.assertEqual(generate_quests(res["itinerary"], res["places"]), res["quests"]) + + # 9. 데이터 출처와 기준 시점을 확인할 수 있는가 + def test_09_sources_and_period_visible(self): + res, _ = self.run_a(goal(days=2, quiet_pref=True)) + for pid, p in res["places"].items(): + reg, near = p["indicators"]["region"], p["indicators"]["nearby"] + self.assertEqual(reg["source_id"], "563") + self.assertEqual(near["source_id"], "1208") + for ind in (reg, near): + self.assertTrue(ind["period"] or ind["missing"], pid) + html = export_travel_plan(res, data_sources(self.conn)) + self.assertIn("563", html) + self.assertIn("1208", html) + self.assertIn("2018-01~2022-09", html) # 기준 시점(모의 DB 값) + self.assertIn("개별 장소의 속성이 아닙니다", html) + + # 10. 가상 탐험 기록과 실제 방문 기록을 구분하는가 + def test_10_virtual_vs_visited_separate(self): + res, _ = self.run_a(goal(days=2)) + ids = day_ids(res) + bid = res["batch_id"] + record_event(self.conn, bid, ids[0], "virtual_arrival", None) + record_event(self.conn, bid, ids[1], "visited", None) + + def by_type(t): + return [r["place_id"] for r in self.conn.execute( + "SELECT place_id FROM user_interactions WHERE batch_id = ? AND type = ?", (bid, t))] + self.assertEqual(by_type("virtual_arrival"), [ids[0]]) + self.assertEqual(by_type("visited"), [ids[1]]) + fb = analyze_feedback(load_events(self.conn, bid), res["places"]) + self.assertEqual((fb["pinned"], fb["disliked"], fb["liked_categories"]), (set(), set(), {})) + self.assertEqual(fb["arrived"], {ids[0]}) # 실제 방문은 가상 도착에 섞이지 않는다 + b, _ = self.run_b(bid) + self.assertTrue(all(x["change"] == "keep" for x in b["diff"])) # 선호 집계·경로에 미반영 + + # 11. 실행 중 코드는 표준 라이브러리만 import한다(D17) + def test_11_runtime_imports_stdlib_only(self): + src = ROOT / "src" / "malttara" + files = [f for f in src.rglob("*.py") if "etl" not in f.parts or f.name in ("mock_data.py", "__init__.py")] + files.append(ROOT / "run.py") + bad = set() + for f in files: + for node in ast.walk(ast.parse(f.read_text(encoding="utf-8"))): + if isinstance(node, ast.Import): + names = [a.name for a in node.names] + elif isinstance(node, ast.ImportFrom) and node.level == 0: + names = [node.module or ""] + else: + names = [] + bad |= {n.split(".")[0] for n in names + if n and n.split(".")[0] not in sys.stdlib_module_names and n.split(".")[0] != "malttara"} + self.assertEqual(bad, set()) + + +if __name__ == "__main__": + unittest.main()