Aislo/docs/backup/wiki/pages/B04_PreProcess/B04_api.md

status, page_id, related_pages, last_updated

status	page_id	related_pages	last_updated
draft	B04_PreProcess	B04_PreProcess/B04_backend B04_PreProcess/B04_frontend B04_PreProcess/B04_db B04_PreProcess/B04_dependencies architecture/project_map architecture/workflow_data_flow	2026-08-02

B04_PreProcess — API

이 API는 B04_PreProcess/B04_frontend의 분석·확정 요청을 B04_PreProcess/B04_backend에 연결하고 workflow_state stage 1을 변경한다.

실제 라우터 prefix: /api/projects (B04_PreProcess_Router.py, B04_PreProcess_Router_GIS.py, B04_PreProcess_Router_Contour.py, B04_PreProcess_Router_Basins.py). 총 17개 엔드포인트.

엔드포인트

엔드포인트	위치	역할
POST /{project_id}/surface/analyze	B04_PreProcess_Router.py	LAS 구조화+지면필터+모델생성 실행, DB 기록, WF1 stage 전이
GET /{project_id}/surface/models	B04_PreProcess_Router.py	생성된 지표면 모델 목록
POST /{project_id}/surface/confirm	B04_PreProcess_Router.py	사용자가 선택한 지표면 모델을 확정하고 WF1을 완료 처리
GET /{project_id}/surface/input-files	B04_PreProcess_Router.py	분석 대상 LAS/LAZ 입력파일 목록
GET /{project_id}/surface/point-cloud	B04_PreProcess_Router.py	3D 미리보기용 포인트클라우드 샘플 (지면 필터 filter 파라미터 적용)
GET /{project_id}/surface/ground-stats	B04_PreProcess_Router.py	필터별 지면 포인트 통계
GET /{project_id}/surface/status	B04_PreProcess_Router.py	WF1 분석 상태 조회 (workflow_state 우선, 레거시 폴백)
GET /{project_id}/surface/models/{model_id}/preview	B04_PreProcess_Router.py	모델 미리보기
GET /{project_id}/surface/models/{model_id}/contour	B04_PreProcess_Router_Contour.py	등고선 생성/조회 (요청 간격 파일 부재 시 온디맨드 생성)
GET /{project_id}/vworld-meta	B04_PreProcess_Router_GIS.py	VWorld 배경지도 매핑 좌표 메타데이터
GET /{project_id}/vworld-map	B04_PreProcess_Router_GIS.py	배경 지도 레이어 PNG 이미지
GET /{project_id}/geojson	B04_PreProcess_Router_GIS.py	저장된 프로젝트의 특정 GeoJSON 레이어 데이터
GET /tiles/{project_id}/{layer}/{z}/{x}/{y}.pbf	B04_PreProcess_Router_GIS.py	프로젝트의 특정 레이어에 대한 정밀 벡터 타일(MVT) 조각
GET /{project_id}/drainage/primary-region	B04_PreProcess_Router_Watershed.py	배수유역 1차 해석 단계별 영구저장 및 응답 캐시
GET /{project_id}/drainage/road-inflow	B04_PreProcess_Router_Inflow.py	도로 유입 흐름 강도 1m 해상도 노출 및 기여 셀 외곽선 폴리곤 조회
GET /{project_id}/drainage/pipe-points	B04_PreProcess_Router_Basins.py	저장된 관 지점 및 세부유역 데이터 조회 (B04/B05 공용)
POST /{project_id}/drainage/detail-basins	B04_PreProcess_Router_Basins.py	임시 관 매설 및 실시간 세부유역 분할 계산 (B04/B05 공용, 저장 안 함)
PUT /{project_id}/drainage/pipe-points	B04_PreProcess_Router_Basins.py	관 매설 위치 확정 및 세부유역 구조 최종 영구 보존 (B04/B05 공용)
DELETE /{project_id}/drainage/pipe-points	B04_PreProcess_Router_Basins.py	관 매설 저장분 및 세부유역 GeoJSON 물리적 디스크 삭제 및 자동배치 갱신 (B04/B05 공용)

요청/응답 스키마 (Pydantic)

모델	위치	역할
SurfaceAnalyzeRequest	B04_PreProcess_Schema.py:16	input_file_id, source_filters?, methods?, force. resolved_filters/methods로 화이트리스트 검증
SurfaceAnalyzeResponse	B04_PreProcess_Schema.py:97	ground_summary, manifest_status, surface_model_ids
SurfaceConfirmRequest	B04_PreProcess_Schema.py:45	확정할 surface_models.id
SurfaceConfirmResponse	B04_PreProcess_Schema.py:52	지표면 모델 확정 결과 (status: success, confirmed: true)
SurfaceModelSummary / SurfaceModelListResponse	B04_PreProcess_Schema.py:45,107	모델 요약/목록
SurfaceInputFileSummary / ...ListResponse	B04_PreProcess_Schema.py:56,69	입력파일 요약/목록
SurfacePointCloudSampleResponse	B04_PreProcess_Schema.py:77	포인트클라우드 샘플(bounds/points/rgb)
SurfaceGroundStatsResponse	B04_PreProcess_Schema.py:89	필터별 통계

• 공통 오류 포맷 {"status":"error","message":...} → schema_common
• 분석 파라미터 화이트리스트: SURFACE_MODEL_SOURCE_FILTERS+ransac, SURFACE_MODEL_PRECOMPUTE (config_system)