GhiVideo_v4/docs/history/2026-06-30_1610_KMZ필수화-CSV폴백제거-누락경고.md

KMZ 필수화 — building POI/구조물 CSV 폴백 제거 + 누락 경고

배경 / 결정

• 정책: KMZ는 항상 필수. 없으면 "데이터 누락"으로 보고 재구축해서 KMZ를 전달받음.
• 기존 코드는 KMZ 없으면 조용히 building CSV로 폴백 → 불완전 데이터가 에러 없이 통과(정책과 상충).
• 사용자 선택: "경고만 표시" (앱은 계속 동작, CSV POI/구조물 폴백 제거, 측점은 유지).

변경 내용

1. geoData.ts — 죽은 파서 제거 + KMZ 단일 소스화

• 삭제: parsePois, parseStructures, parseHistoricStations, parseAccessDoors + 전용 헬퍼 rowProps, cleanHeader
• loadFolderGeoData:
  • Promise.all에서 위 4개 파서 호출 제거(헛수고 파싱 제거)
  • useKmz 분기 → kmzMissing 판정으로 교체: !kmz || (pois==0 && structures==0)
  • KMZ 누락 시 console.warn, 정상 시 console.log
  • pois = kmz?.pois ?? [], baseStructures = kmz?.structures ?? []
  • structures에서 historicStations concat 제거 → 역사 중복 위험 제거(역사는 KMZ KAKAO_RAIL에서만 생성)
  • 반환값에 kmzMissing 추가
• 유지: parseStations(측점), parseDroneFrames, parseKmz, mergeStructures, parseRouteMeta, parsePoiOverrides, buildCenterlineFromStations 및 공용 헬퍼(makeFieldIndexer/cell/readCsv/findBuildingFile/mmssToSeconds 등)

2. 타입/스토어 (kmzMissing 전파)

• types/geo.ts: FolderGeoData.kmzMissing: boolean 추가
• store/geoStore.ts: GeoStore.kmzMissing + EMPTY 기본값 + loadFromFolder에서 set

3. UI 경고

• VideoPlayer.tsx handleSelectFolder: 로드 후 kmzMissing && (stations||frames 존재) 면 alert로 "KMZ 누락 → 재구축 필요(측점·드론은 정상)" 안내

4. 문서 갱신

• docs/구현상세_GhiVideo_기술-소스코드매칭.md: 데이터 흐름도 + 소스 우선순위 콜아웃 + 파서 표를 KMZ 필수 정책으로 갱신(폴백 제거 명시)

검증

• tsc --noEmit (node v20.20.2): 통과 (시스템 기본 node v12라 nvm node20 사용)
• npm run build (tsc && vite build): 성공 (219 modules, 빌드 1.49s)

비고

• 측점.csv(루트)는 KMZ에 없어 그대로 필수 — 빠지면 스테이션바/체이니지/중심선 동작 불가.
• 빌드 산출물 반영됨 → 55000 PM2 서빙 시 재시작/재배포 필요할 수 있음.

---

소요 시간: 25분 Context 사용량: input 175k / output 22k tokens