Aislo/docs/raw/verification/2026-07-17_verify_b04_defects.md

검증 보고서: B04 지표면 분석 결함 수정 및 확정 흐름 보완

• 검증 일자: 2026-07-17
• 검증 대상: B04_wf1_Surface 모듈 백엔드 및 프론트엔드
• 상태: PASS (결함 조치 완료)

---

1. 검증 대상 파일 목록

• 백엔드 (Python):
  • [B04_wf1_Surface_Engine.py](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Engine.py)
  • [B04_wf1_Surface_Router.py](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Router.py) (643줄)
  • [main.py](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/main.py)
• 프론트엔드 (TypeScript/CSS):
  • [B04_wf1_Surface_Api_Fetch.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Api_Fetch.ts)
  • [B04_wf1_Surface_UI_Camera.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Camera.ts) (신설)
  • [B04_wf1_Surface_UI_Page.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Page.ts)
  • [B04_wf1_Surface_UI_Viewer.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Viewer.ts)
  • [B04_wf1_Surface_UI_TerrainViewer.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_TerrainViewer.ts)
  • [B04_wf1_Surface_UI_MapViewer.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_MapViewer.ts)
  • [B04_wf1_Surface_UI_Style.css](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Style.css)

---

2. 발견된 중대 결함 및 미결 사항 (조치 완료)

✓ GIS 라우터 유실로 인한 백엔드 실행 오류 (ImportError)

• 결과: PASS
• 조치 내용: 이전 정상 커밋(f63e44f)으로부터 유실되었던 [B04_wf1_Surface_Router_GIS.py](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Router_GIS.py) 파일을 정상 복구하였습니다. 이로 인해 main.py의 ImportError가 완치되었으며 서버 기동이 정상적으로 수행됩니다.

✓ 단일 소스파일 700줄 한계 규정 위반

• 결과: PASS
• 조치 내용: GIS 라우터가 [B04_wf1_Surface_Router_GIS.py](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Router_GIS.py)로 분리 복구됨에 따라, [B04_wf1_Surface_Router.py](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Router.py)는 643줄, B04_wf1_Surface_Router_GIS.py는 175줄로 각각 700줄 제한을 완벽히 만족합니다.

---

3. 계획서 구현 검증 상세 결과

A. 지면 필터 미리보기 원본 데이터 표시 수정

• 결과: PASS
  • 분석 시 필터별 지면 마스크를 50만 상한으로 샘플링한 ground_points_{filter}.npz 캐시 파일이 정상 생성되도록 Engine.py에 적용되었습니다.
  • Router.py에서 point-cloud 엔드포인트가 filter 파라미터를 받아 캐싱 데이터 제공 및 미존재 시 백필 처리를 수행합니다.
  • Api_Fetch.ts 및 UI_Page.ts에서 필터 드롭다운 선택 변경 시 filter 쿼리를 넘겨 재조회 렌더하도록 연동되었습니다.

B. 등고선 간격 옵션 미작동 수정

• 결과: PASS
  • Router.py의 get_surface_model_contour가 요청받은 간격의 등고선 파일이 없으면 extract_contours를 사용해 온디맨드 등고선 데이터 생성 및 캐싱하도록 보완되었습니다.
  • 무음 폴백 glob 처리가 완전히 걷혀 다른 간격 요청 시 조용히 무시되는 현상이 완치되었습니다.

C. 스무딩 옵션 동작 명확화

• 결과: PASS
  • UI_TerrainViewer.ts에서 메쉬법이 tin/dtm이 아닐 경우 syncSmoothingSupport를 기동하여 스무딩 토글 체크박스를 비활성화(disabled)하고 레이블에 .is-disabled를 씌워 visual 피드백을 전달합니다.

D. 2D 지도 이미지 왜곡 해결 (UI/CSS)

• 결과: PASS
  • .b04-map__image에 object-fit: contain을 지정하여 강제 가로 늘어남을 방지했습니다.
  • UI_MapViewer.ts에서 VWorld 종횡비를 정밀 계산하는 getMapRect를 도입하여, 캔버스 영역 내 실제 이미지 투영 비율에 맞게 GeoJSON 벡터 좌표 오버레이가 한 치의 뒤틀림 없이 매핑되도록 정합했습니다.

F. 두 3D 뷰어 카메라 동기화의 스케일 일치

• 결과: PASS
  • 카메라 동기화 공식을 모아둔 [B04_wf1_Surface_UI_Camera.ts](file:///D:/02_Software_Prog/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Camera.ts)를 신설했습니다.
  • 3D 뷰어(포인트클라우드)와 지형 메시 뷰어가 카메라 교환 시 real-world 좌표(m) 및 오프셋 단위로 변환해 emit/apply 하므로, 시점과 축척바의 배율이 일치합니다.

G. 지표면 표현 뷰어가 컨테이너 전체를 사용하지 못함 수정

• 결과: PASS
  • UI_TerrainViewer.ts에서 height: 520px 고정 코드를 삭제하고, UI_Style.css에 2열 배치 그리드를 설정하여 두 뷰어가 동일 높이로 넓게 본문을 활용하고 크기 변화에 추종합니다.

E. 확정 흐름 주의점 보완

• 결과: PASS
  • enableRouteStep에서 DOM [2] 하드코딩을 제거하고 라우트명(B05_wf2_Route) 기준 동적 탐색 버튼 활성화로 개선했습니다.
  • 확정 완료 토스트의 {smoothing} 변수에 실제 스무딩 체크 상태("ON" 또는 "OFF")를 동적으로 바인딩했습니다.
  • SOURCE_FILTERS 드롭다운에서 불필요한 ransac 필터를 정상적으로 지웠습니다.
  • 사용자가 모델을 확정 성공하면 곧바로 다음 단계인 B05로 자동 이동(goToWorkflowStage)되도록 제어 흐름이 완료되었습니다.