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,43 @@
+---
+status: stable
+page_id: B04_wf1_Surface
+related_pages: ["[[B04_wf1_Surface/B04_backend]]", "[[B04_wf1_Surface/B04_frontend]]", "[[B04_wf1_Surface/B04_db]]", "[[B04_wf1_Surface/B04_dependencies]]"]
+last_updated: 2026-07-12
+---
+
+# B04_wf1_Surface — API
+
+실제 라우터 prefix: `/api/projects` (`B04_wf1_Surface_Router.py:41`). 총 12개 엔드포인트.
+
+> ⚠️ 이전 계획서 기반 api.md에는 "추정 경로 surface/analyze·models 2개"로만 기재됐으나,
+> 실 코드는 아래 12개(분석·모델·미리보기·등고선·VWorld·GeoJSON 포함). 실 코드 채택(규칙6).
+
+## 엔드포인트
+
+| 엔드포인트 | 위치 | 역할 |
+|---|---|---|
+| `POST /{project_id}/surface/analyze` | `B04_wf1_Surface_Router.py:147` | LAS 구조화+지면필터+모델생성 실행, DB 기록, WF1 stage 전이 |
+| `GET /{project_id}/surface/models` | `B04_wf1_Surface_Router.py:241` | 생성된 지표면 모델 목록 |
+| `GET /{project_id}/surface/input-files` | `B04_wf1_Surface_Router.py:260` | 분석 대상 LAS/LAZ 입력파일 목록 |
+| `GET /{project_id}/surface/point-cloud` | `B04_wf1_Surface_Router.py:279` | 3D 미리보기용 포인트클라우드 샘플 |
+| `GET /{project_id}/surface/ground-stats` | `B04_wf1_Surface_Router.py:341` | 필터별 지면 포인트 통계 |
+| `GET /{project_id}/surface/status` | `B04_wf1_Surface_Router.py:372` | WF1 분석 상태 조회 (workflow_state 우선, 레거시 폴백) |
+| `GET /{project_id}/surface/models/{model_id}/preview` | `B04_wf1_Surface_Router.py:484` | 모델 미리보기 |
+| `GET /{project_id}/surface/models/{model_id}/contour` | `B04_wf1_Surface_Router.py:557` | 등고선 생성/조회 |
+| `GET /{project_id}/vworld-meta` | `B04_wf1_Surface_Router.py:643` | VWorld 배경지도 메타 |
+| `GET /{project_id}/vworld-map` | `B04_wf1_Surface_Router.py:676` | VWorld 배경지도 타일 |
+| `GET /{project_id}/geojson` | `B04_wf1_Surface_Router.py:712` | GIS 벡터 GeoJSON |
+
+## 요청/응답 스키마 (Pydantic)
+
+| 모델 | 위치 | 역할 |
+|---|---|---|
+| `SurfaceAnalyzeRequest` | `B04_wf1_Surface_Schema.py:16` | input_file_id, source_filters?, methods?, force. resolved_filters/methods로 화이트리스트 검증 |
+| `SurfaceAnalyzeResponse` | `B04_wf1_Surface_Schema.py:97` | ground_summary, manifest_status, surface_model_ids |
+| `SurfaceModelSummary` / `SurfaceModelListResponse` | `B04_wf1_Surface_Schema.py:45,107` | 모델 요약/목록 |
+| `SurfaceInputFileSummary` / `...ListResponse` | `B04_wf1_Surface_Schema.py:56,69` | 입력파일 요약/목록 |
+| `SurfacePointCloudSampleResponse` | `B04_wf1_Surface_Schema.py:77` | 포인트클라우드 샘플(bounds/points/rgb) |
+| `SurfaceGroundStatsResponse` | `B04_wf1_Surface_Schema.py:89` | 필터별 통계 |
+
+- 공통 오류 포맷 `{"status":"error","message":...}` → [[schema_common]]
+- 분석 파라미터 화이트리스트: `SURFACE_MODEL_SOURCE_FILTERS`+`ransac`, `SURFACE_MODEL_PRECOMPUTE` (config_system)