---
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)