feat(B04): 상세 배수유역 계산 — 관 매설 지점 편집 + 세부유역 분할

관 매설 지점을 기준으로 세부 배수유역을 나누는 기능을 B04 2D 지도에 추가한다.
경계는 B04 전처리 격자(03_road_routing.npz)의 road_slot — 1m 셀마다 물이 도달하는
도로 셀 — 을 담당 관으로 라벨링해 그 경계로 잡는다. 종단 Z는 경계를 긋지 않고
"도로 셀이 어느 관으로 흐르는가"만 정한다.

공용 승격 (B04 관리자 화면과 B05 사용자 화면이 같은 결과를 내야 함)
- common_util_drainage_detail.py: 관 보충(9)·세부유역 분할(10) 알고리즘
- common_util_drainage_context.py: 노선·종단 Z·좌표계 입력 준비
- common_util_drainage_pipes.py: 관 지점 정본 저장소(edits/pipe_points.json)
- common_util_route_profile.py: 종단 Z 해석기(계획고 > 경로 정점 > 지표면 > CSV)
- common_util_surface_sampler.py: B05 종횡단 sampler 이동
- B05 _prepare()의 노선 소스를 원청 계획노선 CSV로 정정(B04 격자와 누가거리 정합)

B04 신규 API
- GET  /{project_id}/drainage/pipe-points   저장분 조회(없으면 자동 생성)
- POST /{project_id}/drainage/detail-basins 편집 중 목록으로 재분할(저장 안 함)
- PUT  /{project_id}/drainage/pipe-points   모델 확정 시 관 지점·세부유역 커밋

B04 화면
- 관 마커 기본/자동/수동 색 구분, 계획선 스냅 드래그 이동
- 계획선 우클릭 "관 매설 추가" / 마커 우클릭 "관 매설 삭제"
- 표시 토글 2그룹(관 매설 / 세부 유역)을 유입 집중점과 분리
- "상세유역 분석" 버튼을 눌렀을 때만 재계산

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

common_util/common_util_drainage_context.py

@@ -0,0 +1,131 @@
+"""배수유역 세부 설계 입력 준비 (B04 관리자 화면 · B05 사용자 화면 공용).
+
+두 화면이 같은 관 목록과 같은 세부유역을 보여 주려면 **입력이 한 글자도 달라선 안 된다**
+(2026-08-01 사용자 지시). 그래서 노선·종단 Z·좌표계를 여기 한 곳에서 만들어 양쪽에 넘긴다.
+
+노선 기준선은 B05가 푼 최적 경로가 아니라 **B03이 업로드한 원청 계획노선 CSV**다. B04 격자
+해석이 그 노선으로 도로 셀을 구웠으므로, 다른 노선의 누가거리를 쓰면 도로 셀과 관 위치가
+어긋난다. 종단 Z만 상황에 따라 갈아 끼운다 → [[common_util_route_profile]].
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from pyproj import Transformer
+
+from B03_FileInput.B03_FileInput_Repository import get_project_storage_relative_path
+from B05_wf2_Route.B05_wf2_Route_Repository import (
+    get_latest_route,
+    get_route_points,
+    get_surface_crs_epsg,
+)
+from B06_wf3_ProfileCross.B06_wf3_ProfileCross_Repository import get_longitudinal_section
+from common_util.common_util_route_geometry import (
+    RouteVertex,
+    build_route_vertices,
+    find_planned_route_file,
+    read_planned_route_csv,
+)
+from common_util.common_util_route_profile import Z_SOURCE_CSV, resolve_route_profile
+from common_util.common_util_storage import resolve_stored_project_path
+from common_util.common_util_surface_confirmation import get_surface_confirmation_params
+from common_util.common_util_surface_sampler import build_surface_sampler
+from config.config_db import get_db_pool
+
+logger = logging.getLogger(__name__)
+
+_INPUT_SUBDIR = Path("B03_FileInput") / "input"
+_MODELS_SUBDIR = Path("B04_wf1_Surface") / "models"
+
+
+@dataclass
+class DrainageContext:
+    """세부 설계 한 번에 필요한 입력 묶음."""
+
+    stored_path: str
+    project_root: Path
+    vertices: list[RouteVertex] = field(default_factory=list)
+    z_source: str = Z_SOURCE_CSV
+    epsg: int = 5186
+    route_id: int | None = None
+    to_lonlat: Callable[[float, float], tuple[float, float]] = lambda x, y: (x, y)
+
+
+async def load_drainage_context(project_id: UUID) -> tuple[DrainageContext | None, str]:
+    """노선·종단 Z·좌표계를 준비한다. 실패하면 (None, 사용자에게 보일 사유).
+
+    B05 확정 경로는 **있으면 쓰고 없으면 넘어간다** — B04는 WF1 화면이라 아직 경로가 없다.
+    """
+    pool = get_db_pool()
+    async with pool.acquire() as connection:
+        stored_path = await get_project_storage_relative_path(connection, project_id)
+        if not stored_path:
+            return None, "프로젝트 저장 경로가 없습니다."
+        route = await get_latest_route(connection, project_id)
+        route_points: list[dict[str, Any]] = []
+        longitudinal: dict[str, Any] | None = None
+        if route:
+            route_points = await get_route_points(connection, int(route["id"]))
+            section = await get_longitudinal_section(connection, project_id, int(route["id"]))
+            longitudinal = (section or {}).get("data")
+        surface_model_id = (route or {}).get("surface_model_id")
+        db_epsg = await get_surface_crs_epsg(
+            connection, project_id, int(surface_model_id) if surface_model_id else 0
+        )
+        surface_params = await get_surface_confirmation_params(connection, str(project_id))
+
+    project_root = Path(resolve_stored_project_path(stored_path))
+    planned = await asyncio.to_thread(_read_planned_route, project_root)
+    if planned is None or len(planned.vertices) < 2:
+        return None, "원청 계획노선 CSV를 읽지 못했습니다. B03에서 노선 파일을 확인하세요."
+
+    sampler = await asyncio.to_thread(_open_sampler, project_root, surface_params)
+    vertices, z_source = await asyncio.to_thread(
+        resolve_route_profile,
+        planned.vertices,
+        route_vertices=build_route_vertices(route_points) if route_points else None,
+        longitudinal=longitudinal,
+        sampler=sampler,
+    )
+
+    epsg = int(planned.epsg or db_epsg or 5186)
+    transformer = Transformer.from_crs(f"EPSG:{epsg}", "EPSG:4326", always_xy=True)
+    return (
+        DrainageContext(
+            stored_path=stored_path,
+            project_root=project_root,
+            vertices=vertices,
+            z_source=z_source,
+            epsg=epsg,
+            route_id=int(route["id"]) if route else None,
+            to_lonlat=lambda x, y: transformer.transform(x, y),
+        ),
+        "",
+    )
+
+
+def _read_planned_route(project_root: Path):
+    """원청 계획노선 CSV를 찾아 읽는다(파일 접근이라 스레드에서 돈다)."""
+    path = find_planned_route_file(project_root / _INPUT_SUBDIR)
+    return read_planned_route_csv(path) if path else None
+
+
+def _open_sampler(project_root: Path, surface_params: dict[str, Any]):
+    """확정 지표면 표고 sampler를 연다. 모델이 없으면 None(종단 Z가 다른 경로로 폴백)."""
+    try:
+        return build_surface_sampler(
+            project_root / _MODELS_SUBDIR,
+            str(surface_params["source_filter"]),
+            str(surface_params["method"]),
+            bool(surface_params["smooth"]),
+        )
+    except (FileNotFoundError, ValueError, OSError) as exc:
+        logger.warning("배수유역: 확정 지표면 sampler를 열지 못했습니다 — %s", exc)
+        return None