Pier_v1/랜딩페이지/SAMPLE_EXPLORER.md

# 샘플 교량 탐색 개선 결과 — 2026-11-04

## 범위
현재 경로에 Test랜딩페이지 폴더가 없어 기존 랜딩페이지에서 개선했다. 화이트 테마와 지도/목록/상세 3단 구조를 유지했다. 폴더 외 변경은 이번에 사용자가 허용한 src/core/rebar/column.ts의 1줄뿐이다. 샘플 JSON 원본과 프로젝트 Store는 변경하지 않았다.

## 실제 불러오기 오류 원인과 수정
수정 전 9개는 기존 파일 로더로 열렸고 대호지교·승천천교·감북교는 메타데이터 blockReason 때문에 로더 호출 전에 차단됐다. 세 파일을 원래 #project-file로 직접 열어 확인했다.

- 대호지교·감북교: 현장타설말뚝 모델에 확대기초가 없는데 columnInputFor가 model.footings[0].top을 읽어 Cannot read properties of undefined (reading 'top')가 발생했다.
- 사용자 허용 후 model.footings[0]?.top ?? col.bottom으로 변경했다. 확대기초가 있으면 기존 값을 유지하며, 없을 때 실제 모델 기둥 하단을 사용한다. 현장타설말뚝 철근 상세 설계까지 검증한 변경은 아니다.
- 승천천교: 원본에 교각 데이터가 0기지만 기존 로더는 파일을 정상적으로 열 수 있었다. 임의 교각을 생성하지 않고 지반·지도 자료로 구분한다.
- 기존 UI의 지도 레이어가 정확히 2개가 아니면 전체 프로젝트를 거부하던 조건도 제거했다. 교량명/교각수는 원본과 검증하고 지도·지형 누락은 상태로 표시한다.

## 기존 로더 재사용과 선택 일치
sampleProjects의 ID/파일명/URL → sampleResource의 실제 파일 확인 → 기존 #project-file change → 기존 openProjectFile → 기존 openProjectText 경로를 유지했다. 별도 Store나 가상 프로젝트를 만들지 않았다.

미리보기와 로드는 같은 URL의 리소스를 공유한다. 선택 ID 하나로 지도·목록·미리보기·위치정보·불러오기 대상을 갱신한다. 불러오는 동안 선택을 잠그고 기존 로더의 새 성공/실패 메시지로 완료를 판단한다. 실패는 교량명과 실제 오류로 표시하며 재시도가 가능하다. 이전 미리보기의 비동기 결과가 현재 선택을 덮어쓰지 않는다.

## 실제 지도·지형·교각 미리보기
PNG 썸네일 대신 실시간 Three.js 미리보기로 변경했다. 기존 buildPier, buildAllPiers, terrainGeometry, buildTerrainMapGroup를 재사용하고 저장 mapLayers.image/survey_corners를 같은 pivot과 DTM 격자로 매핑한다.

- 저장 위성/2D 지도 전환, 드래그 회전, 휠 확대/축소, 큰 화면, 맞춤/전체 보기 제공.
- 처음 두 교각 주변을 대표 구간으로 맞추되 전체 교각을 장면에 유지하며 전체 버튼으로 전체 배치를 확인.
- 기초·말뚝은 실제 모델의 부재를 사용하고 지반 투명 버튼으로 지하 부재 확인.
- 승천천교는 실제 저장 지도·지반과 교각 0기를 명시.
- 지형/지도 미연결과 이미지 오류를 표시. 교량 변경 시 렌더러·텍스처·컨트롤 해제.

## 지도 확대와 클러스터
sample-map-model.ts의 SAMPLE_MAP_CONFIG에서 확대/중심/상한을 관리한다. 초기 확대 7.3, 일반지도 상한 19, 위성지도 상한 23이다. 지역별 실제 고배율 영상 제공 여부는 다르며 실패 시 타일 표시 불가 안내를 표시한다. 상한 이상의 저해상도 타일을 영구 확대하지 않는다.

선택 시 부드럽게 이동하며 휠·더블클릭·버튼·드래그를 지원한다. 애니메이션 도중에는 기존 타일을 이동하고 도착 후 필요한 타일을 요청한다. 현재 화면에서 32px 이내로 겹치는 마커를 연결 성분으로 묶어 개수와 교량 선택 목록을 표시한다. 확대 시 다시 계산하고 완전히 같은 좌표는 최대 확대에서도 선택 목록으로 유지한다. 원본 좌표를 이동하지 않는다.

서비스 확인 자료:
- https://operations.osmfoundation.org/policies/tiles/
- https://operations.osmfoundation.org/files/OWG_Summary_2013-07-01.pdf
- https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer?f=pjson

## 위치정보
대표점은 각 파일의 첫 교각 IP1/IP3 중점이다. 교각이 없는 승천천교만 저장 지도 영역 중심을 사용하며 이를 명시한다. Excel X=N/Y=E → 프로그램 x=E/y=N → 지반 X=N/Y=E 규칙을 확인했다. 프로그램에 이미 교환되어 저장된 좌표를 다시 교환하지 않는다.

하단에 교량명·주소 확인 상태·적용 EPSG·조사 X(N)/Y(E)·WGS84 위도/경도·대표점 기준을 표시한다. 위치 버튼은 같은 선택 ID로 상단 지도를 확대한다. sample-locations.ts는 각 파일 EPSG에서 대표점을 WGS84로 변환한 결과다.

원본 CRS 추정 상태를 유지하고 원본 CRS 미확정을 표시한다. EPSG를 측량 원자료로 확정한 것은 아니다. 확인된 행정주소가 원자료에 없어 주소 확인 불가로 표시한다. 역지오코딩 API를 임의 연결하거나 주소를 추정하지 않았다.

## 검증 결과
- 샘플 12개 모두 패널 버튼으로 실제 파일 열기 성공, 각 프로젝트명과 교각수 일치. 대호지교 12기, 감북교 2기, 승천천교 0기.
- 12개 미리보기에서 저장 지도 2종·지반 연결 확인. 교각 수는 원본과 동일.
- 클러스터 개별 선택·확대 시 분리·동일 좌표 유지, 목록/버튼/위치정보 동기화 검증.
- 휠/더블클릭, 상한 19/23, HTTP 503 오류 표시와 재시도, 불러오기 중 선택 잠금, 실제 3D 드래그 회전 검증.
- 1366×768 가로 넘침 없음. 불러오기 하단 약 738px로 화면 안에 표시. 1920×1080 확인. 브라우저 페이지 오류 0건.
- 신규 회귀 검사 5개 통과: 클러스터, 실제 대표좌표, 전체 63개 모델의 기둥 배근 높이 및 입력 불변성 포함.
- 타입 검사·프로덕션 빌드 통과. 기존 대형 번들 경고 유지.
- 전체 543개 중 539개 통과. 기존 axis.test.ts, bearing-coordinate-frame.test.ts, integrated-block.test.ts, validate-and-foundation.test.ts 실패 4건 유지. 커밋하지 않았다.

승천천교는 원본 교각이 없어 메인 형상 화면에 교각 3D를 복원할 수 없다. 통합 미리보기에서 실제 지도·지반을 확인하며, 교각 복원에는 원본 방위각/교각 자료가 필요하다.

## 변경 파일
sample-loader.ts, sample-resource.ts: 기존 파일 로더 연결·완료/실패 처리·리소스 공유.
sample-preview.ts: 지도·지형·교각의 실시간 통합 미리보기.
sample-map.ts, sample-map-model.ts: 확대·이동·타일 상한·클러스터 선택.
sample-explorer.ts/css, sample-locations.ts: 단일 선택 상태·위치정보·상세 레이아웃.
landing-page.ts, landing-guide.ts: 시작 화면 연결·안내 갱신.
sample-explorer.test.ts: 실제 데이터와 클러스터 회귀 검사.
사용자 허용 외부 변경: src/core/rebar/column.ts 1줄.

검증 기록과 스크린샷은 이 폴더 .cache/에 보존한다. 원본 JSON·도면·교각 속성은 수정하지 않았다.


## 추가 변경: 기설계 교량 / 간단한 지역명
패널 제목·위치/목록 제목·불러오기 이름을 기설계 교량으로 바꿨다. 사용자 명시 허용 후 대표 좌표 12개를 ArcGIS reverseGeocode에 조회해 시·도와 시·군만 저장했다. 상세주소는 저장하지 않는다. 예: 산외교 경상남도 밀양시, 계문철교·기양천교 전북특별자치도 익산시. 원본 CRS 미확정 상태는 유지하며 좌표 기준 지역명이다. 이 추가 변경은 위의 초기 주소 확인 불가 상태를 대체한다.

교량 선택 시 현재 고배율을 그대로 유지하지 않고, 대표 좌표에서 70km 이내 교량들을 함께 담는 범위를 다시 계산한다. 근접 그룹 선택은 유지한다. 브라우저 검사에서 계문철교 선택 시 인근 기양천교 등 주변 교량 마커 동시 표시와 익산시 지역명을 확인했다. 제목/지역명/주변 마커 동기화 검사와 기존 회귀 검사 5개, 타입 검사가 통과했다.

지역명 출처: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer (조회 2026-11-04). 조회 결과의 Region/City 등 시군 단위 필드만 사용했다. 실제 좌표는 기존 대표점이며 새 좌표를 추정하거나 원본 측량 위치를 보정하지 않았다.


## 최신 목록/마커 변경
교량 목록은 3열×3행(행 높이 46px, 표시 높이 150px)이며 12개 중 나머지는 목록 안에서 스크롤한다. 목록 클릭 시 선택한 실제 교량 좌표로 14단계 확대한다. 지도 클러스터 및 그룹 선택 팝업은 제거하고 교량마다 개별 번호 마커를 생성한다. 겹치는 번호만 지시선으로 분산해 각 교량을 구분하며 원본 좌표는 변경하지 않는다. 화면 밖 마커는 지도 이동/확대로 확인한다.

1366×768에서 3열, 표시 높이 150px/스크롤 높이 202px, 개별 마커 12개/클러스터 0개, 클릭 확대 14단계를 확인했다. 불러오기 버튼 하단 약 738px로 화면 안에 유지된다. 클러스터 관련 미사용 코드와 검사는 제거했다. 최신 회귀 검사는 좌표·확대 설정·실제 63개 모델의 3개 검사다.