重构爆管定位相关功能，优化输入验证与API接口

app/algorithms/burst_location/burst_location.py

@@ -1,9 +1,7 @@
-"""爆管定位部署入口（基于外部 SCADA 实测数据）。"""
-
 import argparse
 import json
 from pathlib import Path
-from typing import Iterable
+from typing import Any, Iterable
 
 import pandas as pd
 
@@ -69,23 +67,11 @@ def _align_scada_series(
     return aligned
 
 
-def run_burst_location(
-    wn_inp_path,
-    pressure_scada_ids,
-    burst_pressure,
-    normal_pressure,
-    burst_leakage,
-    flow_scada_ids=None,
-    burst_flow=None,
-    normal_flow=None,
-    min_dpressure=2.0,
-    basic_pressure=10.0,
-):
-    if pressure_scada_ids is None or len(pressure_scada_ids) == 0:
-        raise ValueError("pressure_scada_ids cannot be empty.")
-    if burst_pressure is None or normal_pressure is None:
-        raise ValueError("burst_pressure and normal_pressure are required.")
-
+def _validate_flow_inputs(
+    flow_scada_ids: list[str] | None,
+    burst_flow: pd.Series | None,
+    normal_flow: pd.Series | None,
+) -> tuple[bool, list[str]]:
     has_any_flow = any(
         value is not None for value in [flow_scada_ids, burst_flow, normal_flow]
     )
@@ -97,6 +83,46 @@ def run_burst_location(
             "flow_scada_ids, burst_flow, and normal_flow must be provided together."
         )
 
+    if not has_all_flow:
+        return False, []
+
+    flow_ids = [str(item) for item in (flow_scada_ids or [])]
+    if len(flow_ids) == 0:
+        raise ValueError("flow_scada_ids cannot be empty when flow data is provided.")
+    return True, flow_ids
+
+
+def _build_top_candidates(similarity_series: pd.Series) -> list[dict[str, Any]]:
+    top_series = similarity_series.iloc[:10]
+    return [
+        {"pipe_id": str(pipe_id), "similarity": float(score)}
+        for pipe_id, score in top_series.items()
+    ]
+
+
+def run_burst_location(
+    wn_inp_path: str,
+    pressure_scada_ids: list[str],
+    burst_pressure: pd.Series,
+    normal_pressure: pd.Series,
+    burst_leakage: float,
+    flow_scada_ids: list[str] | None = None,
+    burst_flow: pd.Series | None = None,
+    normal_flow: pd.Series | None = None,
+    min_dpressure: float = 2.0,
+    basic_pressure: float = 10.0,
+) -> dict[str, Any]:
+    if pressure_scada_ids is None or len(pressure_scada_ids) == 0:
+        raise ValueError("pressure_scada_ids cannot be empty.")
+    if burst_pressure is None or normal_pressure is None:
+        raise ValueError("burst_pressure and normal_pressure are required.")
+
+    has_all_flow, flow_ids = _validate_flow_inputs(
+        flow_scada_ids=flow_scada_ids,
+        burst_flow=burst_flow,
+        normal_flow=normal_flow,
+    )
+
     inp_path = Path(wn_inp_path)
     wn = load_inp(
         inp_name=inp_path.name,
@@ -131,11 +157,6 @@ def run_burst_location(
     timestep_list = list(pressure_normal.index)
 
     if has_all_flow:
-        flow_ids = [str(item) for item in flow_scada_ids]
-        if len(flow_ids) == 0:
-            raise ValueError(
-                "flow_scada_ids cannot be empty when flow data is provided."
-            )
         normal_flow_aligned = _align_scada_series(normal_flow, flow_ids, "normal_flow")
         burst_flow_aligned = _align_scada_series(burst_flow, flow_ids, "burst_flow")
         flow_normal = normal_flow_aligned.to_frame().T
@@ -190,7 +211,7 @@ def run_burst_location(
         "burst_leakage": float(burst_leakage),
         "elapsed_seconds": elapsed_seconds,
         "simulation_times": int(simulation_times),
-        "top_candidates": list(similarity_series.index[:10]),
+        "top_candidates": _build_top_candidates(similarity_series),
         "similarity_mode": similarity_mode,
     }