260715_0

2026-07-15 18:33:33 +09:00
parent 6b1583103f
commit f533082537
201 changed files with 19776 additions and 563 deletions
@@ -0,0 +1,66 @@
+---
+status: stable
+page_id: B04_wf1_Surface
+related_pages: ["[[B04_wf1_Surface/B04_backend]]", "[[B04_wf1_Surface/B04_api]]", "[[B04_wf1_Surface/B04_dependencies]]", "[[ui_templates]]"]
+last_updated: 2026-07-12
+---
+
+# B04_wf1_Surface — Frontend
+
+WF1 지표면 분석 화면. 워크플로우 레이아웃(필터/표현 폼 + 모델 목록) + **three.js 기반 3D 뷰어**(포인트클라우드/지형).
+
+## 파일 구조
+
+| 파일 | 위치 | 역할 |
+|---|---|---|
+| `B04_wf1_Surface_UI_Page.ts` | `B04_wf1_Surface_UI_Page.ts:1-377` | 페이지 조립 + 분석 실행/폴링/뷰어 렌더 |
+| `B04_wf1_Surface_UI_Viewer.ts` | `B04_wf1_Surface_UI_Viewer.ts:1-567` | 포인트클라우드 3D 뷰어(three.js) |
+| `B04_wf1_Surface_UI_TerrainViewer.ts` | `B04_wf1_Surface_UI_TerrainViewer.ts:1-637` | 지형 메시 3D 뷰어(three.js) |
+| `B04_wf1_Surface_Api_Fetch.ts` | `B04_wf1_Surface_Api_Fetch.ts:1-174` | surface API 클라이언트 |
+| `B04_wf1_Surface_UI_Style.css` | `B04_wf1_Surface_UI_Style.css` | 폼 그룹/모델 카드/뷰어 스타일 |
+
+## ⚠️ 계획서와 실 코드 불일치 (3D 뷰어)
+
+이전 wiki(계획서 기반)는 **"WebCAD 3D 뷰어 미구현"**으로 기재했으나,
+실 코드에는 three.js(WebGL) 기반 뷰어가 **구현되어 있음**:
+- `createSurfacePointCloudViewer` (`B04_wf1_Surface_UI_Viewer.ts:187` WebGLRenderer, OrbitControls, THREE.Points)
+- `createSurfaceTerrainViewer` (`B04_wf1_Surface_UI_TerrainViewer.ts`)
+- UI_Page에서 import·인스턴스화(`B04_wf1_Surface_UI_Page.ts:37,38,110,356`)
+
+→ 규칙6, 실 코드 채택. dependencies도 three.js 반영 → [[B04_wf1_Surface/B04_dependencies]]
+
+## 컴포넌트 / 함수
+
+| 함수 | 위치 | 역할 |
+|---|---|---|
+| `renderB04Surface(root)` | `B04_wf1_Surface_UI_Page.ts:95` | 워크플로우 레이아웃+뷰어 조립(async) |
+| `createSurfacePointCloudViewer()` | `B04_wf1_Surface_UI_Viewer.ts:187` | 포인트클라우드 뷰어 핸들 생성 |
+| `createSurfaceTerrainViewer()` | `B04_wf1_Surface_UI_TerrainViewer.ts` | 지형 메시 뷰어 핸들 생성 |
+
+## API 클라이언트 함수
+
+| 함수 | 위치 | 대응 API |
+|---|---|---|
+| `analyzeSurface()` | `B04_wf1_Surface_Api_Fetch.ts:117` | `POST .../surface/analyze` |
+| `listSurfaceModels()` | `B04_wf1_Surface_Api_Fetch.ts:128` | `GET .../surface/models` |
+| `listSurfaceInputFiles()` | `B04_wf1_Surface_Api_Fetch.ts:134` | `GET .../surface/input-files` |
+| `fetchSurfacePointCloud()` | `B04_wf1_Surface_Api_Fetch.ts:142` | `GET .../surface/point-cloud` |
+| `fetchSurfaceGroundStats()` | `B04_wf1_Surface_Api_Fetch.ts:153` | `GET .../surface/ground-stats` |
+| `fetchSurfaceStatus()` | `B04_wf1_Surface_Api_Fetch.ts:161` | `GET .../surface/status` |
+| `getVWorldMapUrl()` / `fetchVWorldMeta()` | `B04_wf1_Surface_Api_Fetch.ts:182,186` | VWorld 배경지도 |
+| `fetchGisGeoJson()` | `B04_wf1_Surface_Api_Fetch.ts:192` | `GET .../geojson` |
+
+## 처리 흐름
+
+1. 워크플로우 레이아웃(`createWorkflowLayout`) + 스텝(`workflowSteps`) 조립
+2. 입력파일/모델 목록 로드 → 필터·표현 폼 구성
+3. 분석 실행(`analyzeSurface`) → 상태 폴링(`fetchSurfaceStatus`)
+4. 완료 시 포인트클라우드(`fetchSurfacePointCloud`) → `viewer.render()` (`B04_wf1_Surface_UI_Page.ts:356`)
+
+## 의존성
+
+- [[a00_app_shell_framework]] — `navigateTo`, `workflowSteps`(b_page_scaffold)
+- `config_frontend.ts` — `API_BASE_URL`, `CURRENT_PROJECT_ID_KEY`, `ROUTES`, `RENDER_OPTIONS`, `API_TIMEOUT_MS`
+- [[ui_templates]] — `createWorkflowLayout`(ui_template_workflow_layout) 등
+- **three.js** (WebGL 3D 뷰어) → [[B04_wf1_Surface/B04_dependencies]]
+- 백엔드 API → [[B04_wf1_Surface/B04_api]]