补充技能说明

2026-05-20 14:59:18 +08:00
parent 96d894d1e0
commit bd04444d9d
38 changed files with 618 additions and 83 deletions
@@ -7,44 +7,101 @@ version: 3.0.0
 # scada Action Skill

 ## 简介
-负责 `analytics/scada-operations` 场景下 `scada` 的具体接口调用。
+负责 `analytics/scada-operations` 场景下 `scada` 的具体接口调用，分为**设备配置（静态元数据）**、**时序监测数据（TimescaleDB）**、**实时模拟数据**、**方案数据**和**复合查询**五类。

 ## 子模块索引 (渐进式引导)
 - 当前为叶子节点，直接使用下方接口目录。

 ## 接口目录
+
+### SCADA 设备配置（静态元数据）
 | Method | Path | Summary | Required Params | Optional Params |
 |---|---|---|---|---|
-| POST | `/api/v1/addscadadevice/` | 添加SCADA设备 | network (query) | - |
-| POST | `/api/v1/addscadadevicedata/` | 添加SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/addscadaelement/` | 添加SCADA元素映射 | network (query) | - |
-| POST | `/api/v1/cleanscadadevice/` | 清空SCADA设备表 | network (query) | - |
-| POST | `/api/v1/cleanscadadevicedata/` | 清空SCADA设备数据表 | network (query) | - |
-| POST | `/api/v1/cleanscadaelement/` | 清空SCADA元素映射表 | network (query) | - |
-| POST | `/api/v1/deletescadadevice/` | 删除SCADA设备 | network (query) | - |
-| POST | `/api/v1/deletescadadevicedata/` | 删除SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/deletescadaelement/` | 删除SCADA元素映射 | network (query) | - |
+| GET | `/api/v1/getscadadeviceschema/` | 获取SCADA设备架构 | network (query) | - |
+| GET | `/api/v1/getscadadevice/` | 获取SCADA设备 | network (query), id (query) | - |
 | GET | `/api/v1/getallscadadeviceids/` | 获取所有SCADA设备ID | network (query) | - |
 | GET | `/api/v1/getallscadadevices/` | 获取所有SCADA设备 | network (query) | - |
-| GET | `/api/v1/getallscadainfo/` | 获取所有SCADA信息 | network (query) | - |
-| GET | `/api/v1/getallscadaproperties/` | 获取所有SCADA属性 | network (query) | - |
-| GET | `/api/v1/getscadadevice/` | 获取SCADA设备 | network (query), id (query) | - |
-| GET | `/api/v1/getscadadevicedata/` | 获取SCADA设备数据 | network (query), device_id (query) | - |
+| POST | `/api/v1/addscadadevice/` | 添加SCADA设备 | network (query) | - |
+| POST | `/api/v1/setscadadevice/` | 更新SCADA设备 | network (query) | - |
+| POST | `/api/v1/deletescadadevice/` | 删除SCADA设备 | network (query) | - |
+| POST | `/api/v1/cleanscadadevice/` | 清空SCADA设备表 | network (query) | - |
 | GET | `/api/v1/getscadadevicedataschema/` | 获取SCADA设备数据架构 | network (query) | - |
-| GET | `/api/v1/getscadadeviceschema/` | 获取SCADA设备架构 | network (query) | - |
+| GET | `/api/v1/getscadadevicedata/` | 获取SCADA设备数据 | network (query), device_id (query) | - |
+| POST | `/api/v1/addscadadevicedata/` | 添加SCADA设备数据 | network (query) | - |
+| POST | `/api/v1/setscadadevicedata/` | 更新SCADA设备数据 | network (query) | - |
+| POST | `/api/v1/deletescadadevicedata/` | 删除SCADA设备数据 | network (query) | - |
+| POST | `/api/v1/cleanscadadevicedata/` | 清空SCADA设备数据表 | network (query) | - |
+| GET | `/api/v1/getscadaelementschema/` | 获取SCADA元素架构 | network (query) | - |
 | GET | `/api/v1/getscadaelement/` | 获取单个SCADA元素映射 | network (query), id (query) | - |
 | GET | `/api/v1/getscadaelements/` | 获取所有SCADA元素映射 | network (query) | - |
-| GET | `/api/v1/getscadaelementschema/` | 获取SCADA元素架构 | network (query) | - |
-| GET | `/api/v1/getscadainfo/` | 获取SCADA信息 | network (query), id (query) | - |
-| GET | `/api/v1/getscadainfoschema/` | 获取SCADA信息架构 | network (query) | - |
-| GET | `/api/v1/getscadaproperties/` | 获取SCADA属性 | network (query), scada (query) | - |
-| POST | `/api/v1/scada/batch` | 批量插入SCADA监测数据 | data (body) | - |
-| DELETE | `/api/v1/scada/by-id-time-range` | 按设备ID和时间范围删除SCADA数据 | device_id (query), start_time (query), end_time (query) | - |
-| GET | `/api/v1/scada/by-ids-field-time-range` | 按设备ID、字段和时间范围查询SCADA数据 | start_time (query), end_time (query), field (query), device_ids (query) | - |
-| GET | `/api/v1/scada/by-ids-time-range` | 按设备ID和时间范围查询SCADA数据 | start_time (query), end_time (query), device_ids (query) | - |
-| PATCH | `/api/v1/scada/{device_id}/field` | 更新SCADA设备字段 | device_id (path), time (query), field (query), value (query) | - |
-| POST | `/api/v1/setscadadevice/` | 更新SCADA设备 | network (query) | - |
-| POST | `/api/v1/setscadadevicedata/` | 更新SCADA设备数据 | network (query) | - |
+| POST | `/api/v1/addscadaelement/` | 添加SCADA元素映射 | network (query) | - |
 | POST | `/api/v1/setscadaelement/` | 更新SCADA元素映射 | network (query) | - |
+| POST | `/api/v1/deletescadaelement/` | 删除SCADA元素映射 | network (query) | - |
+| POST | `/api/v1/cleanscadaelement/` | 清空SCADA元素映射表 | network (query) | - |
+| GET | `/api/v1/getscadainfoschema/` | 获取SCADA信息架构 | network (query) | - |
+| GET | `/api/v1/getscadainfo/` | 获取SCADA信息 | network (query), id (query) | - |
+| GET | `/api/v1/getallscadainfo/` | 获取所有SCADA信息 | network (query) | - |
+| GET | `/api/v1/getscadaproperties/` | 获取SCADA属性 | network (query), scada (query) | - |
+| GET | `/api/v1/getallscadaproperties/` | 获取所有SCADA属性 | network (query) | - |
+
+### SCADA 时序监测数据（TimescaleDB）
+| Method | Path | Summary | Required Params | Optional Params |
+|---|---|---|---|---|
+| POST | `/api/v1/scada/batch` | 批量插入SCADA监测数据 | data (body) | - |
+| GET | `/api/v1/scada/by-ids-time-range` | 按设备ID和时间范围查询SCADA数据 | start_time (query), end_time (query), device_ids (query) | - |
+| GET | `/api/v1/scada/by-ids-field-time-range` | 按设备ID、字段和时间范围查询SCADA数据 | start_time (query), end_time (query), field (query), device_ids (query) | - |
+| PATCH | `/api/v1/scada/{device_id}/field` | 更新SCADA设备字段 | device_id (path), time (query), field (query), value (query) | - |
+| DELETE | `/api/v1/scada/by-id-time-range` | 按设备ID和时间范围删除SCADA数据 | device_id (query), start_time (query), end_time (query) | - |
+
+### 实时模拟数据（TimescaleDB - Realtime）
+| Method | Path | Summary | Required Params | Optional Params |
+|---|---|---|---|---|
+| POST | `/api/v1/realtime/links/batch` | 批量插入实时管道数据 | data (body) | - |
+| GET | `/api/v1/realtime/links` | 查询实时管道数据 | start_time (query), end_time (query) | link_ids (query) |
+| DELETE | `/api/v1/realtime/links` | 删除实时管道数据 | start_time (query), end_time (query) | - |
+| PATCH | `/api/v1/realtime/links/{link_id}/field` | 更新实时管道字段 | link_id (path), time (query), field (query), value (query) | - |
+| POST | `/api/v1/realtime/nodes/batch` | 批量插入实时节点数据 | data (body) | - |
+| GET | `/api/v1/realtime/nodes` | 查询实时节点数据 | start_time (query), end_time (query) | node_ids (query) |
+| DELETE | `/api/v1/realtime/nodes` | 删除实时节点数据 | start_time (query), end_time (query) | - |
+| POST | `/api/v1/realtime/simulation/store` | 存储实时模拟结果 | data (body) | - |
+| GET | `/api/v1/realtime/query/by-time-property` | 按时间和属性查询实时数据 | time (query), property (query) | - |
+| GET | `/api/v1/realtime/query/by-id-time` | 按ID和时间查询实时模拟数据 | element_id (query), time (query) | - |
+
+### 方案模拟数据（TimescaleDB - Scheme）
+| Method | Path | Summary | Required Params | Optional Params |
+|---|---|---|---|---|
+| POST | `/api/v1/scheme/links/batch` | 批量插入方案管道数据 | data (body) | - |
+| GET | `/api/v1/scheme/links` | 查询方案管道数据 | scheme_type (query) | link_ids (query) |
+| GET | `/api/v1/scheme/links/{link_id}/field` | 查询方案管道字段数据 | link_id (path), scheme_type (query), field (query) | - |
+| PATCH | `/api/v1/scheme/links/{link_id}/field` | 更新方案管道字段 | link_id (path), scheme_type (query), field (query), value (query) | - |
+| DELETE | `/api/v1/scheme/links` | 删除方案管道数据 | scheme_type (query) | - |
+| POST | `/api/v1/scheme/nodes/batch` | 批量插入方案节点数据 | data (body) | - |
+| GET | `/api/v1/scheme/nodes/{node_id}/field` | 查询方案节点字段数据 | node_id (path), scheme_type (query), field (query) | - |
+| PATCH | `/api/v1/scheme/nodes/{node_id}/field` | 更新方案节点字段 | node_id (path), scheme_type (query), field (query), value (query) | - |
+| DELETE | `/api/v1/scheme/nodes` | 删除方案节点数据 | scheme_type (query) | - |
+| POST | `/api/v1/scheme/simulation/store` | 存储方案模拟结果 | scheme_type (query), data (body) | - |
+| GET | `/api/v1/scheme/query/by-id-time` | 按ID和时间查询方案模拟数据 | element_id (query), scheme_type (query), time (query) | - |
+
+### 复合查询（TimescaleDB - Composite）
+| Method | Path | Summary | Required Params | Optional Params |
+|---|---|---|---|---|
+| GET | `/api/v1/composite/scada-simulation` | 获取SCADA关联的模拟数据 | network (query), start_time (query) | end_time (query) |
+| GET | `/api/v1/composite/element-simulation` | 获取管网元素的模拟数据 | network (query), element_id (query), start_time (query) | end_time (query) |
+| GET | `/api/v1/composite/element-scada` | 获取管网元素关联的SCADA监测数据 | element_id (query), start_time (query) | end_time (query) |
+| POST | `/api/v1/composite/clean-scada` | 清洗SCADA监测数据 | data (body) | - |
+| GET | `/api/v1/composite/pipeline-health-prediction` | 预测管道健康状况 | network (query), time (query) | - |

 - 覆盖方法：`DELETE, GET, PATCH, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /scada/by-ids-time-range` | 查询多个设备在指定时间范围内的所有监测字段数据，device_ids 为逗号分隔的ID字符串 |
+| `GET /scada/by-ids-field-time-range` | 查询多个设备在指定时间范围内的特定字段数据（如只查压力或只查流量） |
+| `POST /realtime/simulation/store` | 将水力模拟结果以实时数据形式存入TimescaleDB，供前端实时展示 |
+| `GET /realtime/query/by-time-property` | 按特定时间点和属性名查询管网实时模拟结果 |
+| `GET /composite/scada-simulation` | 同时返回指定管网的SCADA监测数据和对应的水力模拟数据，便于对比分析 |
+| `GET /composite/element-scada` | 查询特定管网元素（管道或节点）关联的SCADA监测时序数据 |
+| `GET /composite/pipeline-health-prediction` | 基于历史SCADA数据和模型预测管道健康状态 |
+| `POST /composite/clean-scada` | 对指定设备的SCADA原始数据进行清洗处理（去异常值等），支持传 'all' 清洗所有设备 |
@@ -20,3 +20,24 @@ version: 3.0.0
 | GET | `/api/v1/burst-detection/schemes/{scheme_name}` | 获取爆管检测方案详情 | network (query), scheme_name (path) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `POST /detect/` | 基于压力观测数据执行爆管检测分析。使用异常检测算法（隔离森林 IsolationForest）识别压力时间序列中的异常，判定为潜在爆管事件。请求体支持列式字典、逐时刻对象数组、二维数组三种格式的压力数据，可指定数据来源（monitoring 监测 / simulation 模拟）。 |
+| `GET /schemes/` | 获取指定管网的所有爆管检测方案列表，可通过 query_date 按日期筛选。 |
+| `GET /schemes/{scheme_name}` | 获取指定名称的爆管检测方案详细配置信息，包含传感器节点、算法参数等。 |
+
+## 请求体关键字段（POST /detect/）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `network` | str | 管网名称（数据库名） |
+| `observed_pressure_data` | dict/list/null | 压力观测数据，支持列式字典 `{sensor_id: [values]}` 或逐行数组 |
+| `points_per_day` | int | 每天数据点数，默认1440 |
+| `mu` | int | 异常值检测参数，默认100 |
+| `iforest_params` | dict/null | 隔离森林算法参数，可选 |
+| `scada_start` / `scada_end` | datetime/null | 从SCADA数据库查询的时间范围 |
+| `sensor_nodes` | list/null | 指定传感器节点，null为全部 |
+| `data_source` | str | 数据来源：`monitoring`（监测）或 `simulation`（模拟），默认monitoring |
@@ -20,3 +20,28 @@ version: 3.0.0
 | GET | `/api/v1/burst-location/schemes/{scheme_name}` | 获取爆管定位方案详情 | network (query), scheme_name (path) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `POST /locate/` | 基于压力和流量SCADA数据定位管网中的爆管位置。通过对比爆管时与正常状态下的压力/流量差异，计算最可能的爆管节点。 |
+| `GET /schemes/` | 获取指定管网的所有爆管定位方案列表，可通过 query_date 按日期筛选。 |
+| `GET /schemes/{scheme_name}` | 获取指定名称的爆管定位方案详细配置，包含传感器布置、阈值参数等。 |
+
+## 请求体关键字段（POST /locate/）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `network` | str | 管网名称（数据库名） |
+| `data_source` | str | 数据来源：`monitoring`（监测）或 `simulation`（模拟），默认monitoring |
+| `pressure_scada_ids` | list/null | 压力SCADA传感器ID列表 |
+| `burst_pressure` | dict/list/null | 爆管时的压力数据 |
+| `normal_pressure` | dict/list/null | 正常时的压力数据 |
+| `burst_leakage` | float | 爆管时的漏水量（必填） |
+| `flow_scada_ids` | list/null | 流量SCADA传感器ID列表 |
+| `burst_flow` / `normal_flow` | dict/list/null | 爆管/正常时的流量数据 |
+| `min_dpressure` | float | 最小压力差（bar），默认2.0 |
+| `basic_pressure` | float | 基准压力（bar），默认10.0 |
+| `scada_burst_start` / `scada_burst_end` | datetime/null | 从SCADA数据库查询的爆管时间范围 |
+| `use_scada_flow` | bool | 是否使用SCADA流量数据，默认false |
@@ -20,3 +20,27 @@ version: 3.0.0
 | GET | `/api/v1/leakage/schemes/{scheme_name}` | 获取漏损识别方案详情 | network (query), scheme_name (path) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `POST /identify/` | 基于压力观测数据和遗传算法识别管网中的漏损位置和大小。通过对比模型计算与实测压力数据，迭代优化找到最匹配的漏损节点和漏水量。 |
+| `GET /schemes/` | 获取指定管网的所有漏损识别方案列表，可通过 query_date 按日期筛选。 |
+| `GET /schemes/{scheme_name}` | 获取指定名称的漏损识别方案详细配置，包含传感器节点、算法参数等。 |
+
+## 请求体关键字段（POST /identify/）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `network` | str | 管网名称（数据库名） |
+| `observed_pressure_data` | str/dict/list/null | 观测压力数据 |
+| `start_time` | float | 起始时间（小时），默认0 |
+| `duration` | float | 持续时间（小时），默认24 |
+| `timestep` | float | 时间步长（分钟），默认5 |
+| `q_sum` | float | 总流量（m³/s），默认0.2 |
+| `pop_size` | int | 遗传算法种群大小，默认50 |
+| `max_gen` | int | 遗传算法最大代数，默认100 |
+| `n_workers` | int | 并行工作线程数，默认CPU数-1（最大4） |
+| `scada_start` / `scada_end` | datetime/null | 从SCADA数据库查询的时间范围 |
+| `sensor_nodes` | list/null | 传感器节点列表，null为全部 |
@@ -15,10 +15,20 @@ version: 3.0.0
 ## 接口目录
 | Method | Path | Summary | Required Params | Optional Params |
 |---|---|---|---|---|
-| GET | `/api/v1/getnetworkpiperiskprobabilitynow/` | 获取整个网络的管道风险概率 | network (query) | - |
-| GET | `/api/v1/getpiperiskprobability/` | 获取管道风险概率历史 | network (query), pipe_id (query) | - |
-| GET | `/api/v1/getpiperiskprobabilitygeometries/` | 获取管道风险几何信息 | network (query) | - |
 | GET | `/api/v1/getpiperiskprobabilitynow/` | 获取管道当前风险概率 | network (query), pipe_id (query) | - |
+| GET | `/api/v1/getpiperiskprobability/` | 获取管道风险概率历史 | network (query), pipe_id (query) | - |
 | GET | `/api/v1/getpipesriskprobability/` | 批量获取多条管道风险概率 | network (query), pipe_ids (query) | - |
+| GET | `/api/v1/getnetworkpiperiskprobabilitynow/` | 获取整个网络的管道风险概率 | network (query) | - |
+| GET | `/api/v1/getpiperiskprobabilitygeometries/` | 获取管道风险几何信息 | network (query) | - |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getpiperiskprobabilitynow/` | 查询指定管道在当前时刻的风险概率值 |
+| `GET /getpiperiskprobability/` | 查询指定管道的历史风险概率时间序列数据 |
+| `GET /getpipesriskprobability/` | 批量查询多条管道的风险概率，pipe_ids为逗号分隔的ID字符串（如 `pipe1,pipe2,pipe3`） |
+| `GET /getnetworkpiperiskprobabilitynow/` | 查询整个管网中所有管道的当前风险概率，返回列表 |
+| `GET /getpiperiskprobabilitygeometries/` | 查询管网中管道的地理位置和风险相关几何数据，适合地图可视化 |
@@ -15,34 +15,60 @@ version: 3.0.0
 ## 接口目录
 | Method | Path | Summary | Required Params | Optional Params |
 |---|---|---|---|---|
-| GET | `/api/v1/age_analysis/` | 水龄分析（高级） | network (query), start_time (query), end_time (query), duration (query) | - |
-| GET | `/api/v1/ageanalysis/` | 水龄分析（基础） | network (query) | - |
-| GET | `/api/v1/burst_analysis/` | 爆管分析（高级） | network (query), modify_pattern_start_time (query), burst_ID (query), burst_size (query), modify_total_duration (query), scheme_name (query) | - |
-| GET | `/api/v1/burstanalysis/` | 爆管分析（基础） | network (query), pipe_id (query), start_time (query), end_time (query), burst_flow (query) | - |
-| GET | `/api/v1/contaminant_simulation/` | 污染物模拟 | network (query), start_time (query), source (query), concentration (query), duration (query) | scheme_name (query), pattern (query) |
-| POST | `/api/v1/daily_scheduling_analysis/` | 日排程分析 | data (body) | - |
-| GET | `/api/v1/dumpoutput/` | 导出模拟输出 | output (query) | - |
-| GET | `/api/v1/flushing_analysis/` | 冲洗分析（高级） | network (query), start_time (query), valves (query), valves_k (query), drainage_node_ID (query) | flush_flow (query), duration (query), scheme_name (query) |
-| GET | `/api/v1/flushinganalysis/` | 冲洗分析（基础） | network (query), pipe_id (query), start_time (query), duration (query), flow (query) | - |
-| POST | `/api/v1/network_project/` | 导入网络项目 | file (file) | - |
-| POST | `/api/v1/network_update/` | 管网更新（高级） | file (file) | - |
-| GET | `/api/v1/networkupdate/` | 管网更新（基础） | network (query) | - |
-| POST | `/api/v1/pressure_regulation/` | 压力调节（高级） | data (body) | - |
-| POST | `/api/v1/pressure_sensor_placement_kmeans/` | 压力传感器放置-KMeans聚类分析（高级） | data (body) | - |
-| POST | `/api/v1/pressure_sensor_placement_sensitivity/` | 压力传感器放置-灵敏度分析（高级） | data (body) | - |
-| GET | `/api/v1/pressureregulation/` | 压力调节（基础） | network (query), target_node (query), target_pressure (query) | - |
-| GET | `/api/v1/pressuresensorplacementkmeans/` | 压力传感器放置-KMeans聚类分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
-| GET | `/api/v1/pressuresensorplacementsensitivity/` | 压力传感器放置-灵敏度分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
-| POST | `/api/v1/project_management/` | 项目管理（高级） | data (body) | - |
-| GET | `/api/v1/projectmanagement/` | 项目管理（基础） | network (query) | - |
-| POST | `/api/v1/pump_failure/` | 泵故障管理 | data (body) | - |
-| GET | `/api/v1/runinp/` | 运行INP文件 | network (query) | - |
 | GET | `/api/v1/runproject/` | 运行项目模拟 | network (query) | - |
 | GET | `/api/v1/runprojectreturndict/` | 运行项目模拟（返回字典） | network (query) | - |
-| POST | `/api/v1/runsimulationmanuallybydate/` | 手动运行日期指定模拟 | data (body) | - |
-| POST | `/api/v1/scheduling_analysis/` | 排程分析 | data (body) | - |
-| POST | `/api/v1/sensorplacementscheme/create` | 传感器放置方案创建 | network (query), scheme_name (query), sensor_type (query), method (query), sensor_count (query), user_name (query) | min_diameter (query) |
+| GET | `/api/v1/runinp/` | 运行INP文件 | network (query) | - |
+| GET | `/api/v1/dumpoutput/` | 导出模拟输出 | output (query) | - |
+| GET | `/api/v1/burstanalysis/` | 爆管分析（基础） | network (query), pipe_id (query), start_time (query), end_time (query), burst_flow (query) | - |
+| GET | `/api/v1/burst_analysis/` | 爆管分析（高级） | network (query), modify_pattern_start_time (query), burst_ID (query), burst_size (query), modify_total_duration (query), scheme_name (query) | - |
+| GET | `/api/v1/valvecloseanalysis/` | 阀门关闭分析（基础） | network (query), valve_id (query), start_time (query), end_time (query) | - |
 | GET | `/api/v1/valve_close_analysis/` | 阀门关闭分析（高级） | network (query), start_time (query), valves (query) | duration (query) |
 | GET | `/api/v1/valve_isolation_analysis/` | 阀门隔离分析 | network (query), accident_element (query) | disabled_valves (query) |
-| GET | `/api/v1/valvecloseanalysis/` | 阀门关闭分析（基础） | network (query), valve_id (query), start_time (query), end_time (query) | - |
+| GET | `/api/v1/flushinganalysis/` | 冲洗分析（基础） | network (query), pipe_id (query), start_time (query), duration (query), flow (query) | - |
+| GET | `/api/v1/flushing_analysis/` | 冲洗分析（高级） | network (query), start_time (query), valves (query), valves_k (query), drainage_node_ID (query) | flush_flow (query), duration (query), scheme_name (query) |
+| GET | `/api/v1/contaminant_simulation/` | 污染物模拟 | network (query), start_time (query), source (query), concentration (query), duration (query) | scheme_name (query), pattern (query) |
+| GET | `/api/v1/ageanalysis/` | 水龄分析（基础） | network (query) | - |
+| GET | `/api/v1/age_analysis/` | 水龄分析（高级） | network (query), start_time (query), end_time (query), duration (query) | - |
+| GET | `/api/v1/pressureregulation/` | 压力调节（基础） | network (query), target_node (query), target_pressure (query) | - |
+| POST | `/api/v1/pressure_regulation/` | 压力调节（高级） | data (body) | - |
+| GET | `/api/v1/projectmanagement/` | 项目管理（基础） | network (query) | - |
+| POST | `/api/v1/project_management/` | 项目管理（高级） | data (body) | - |
+| POST | `/api/v1/scheduling_analysis/` | 排程分析 | data (body) | - |
+| POST | `/api/v1/daily_scheduling_analysis/` | 日排程分析 | data (body) | - |
+| POST | `/api/v1/network_project/` | 导入网络项目 | file (file) | - |
+| GET | `/api/v1/networkupdate/` | 管网更新（基础） | network (query) | - |
+| POST | `/api/v1/network_update/` | 管网更新（高级） | file (file) | - |
+| POST | `/api/v1/pump_failure/` | 泵故障管理 | data (body) | - |
+| GET | `/api/v1/pressuresensorplacementsensitivity/` | 压力传感器放置-灵敏度分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
+| POST | `/api/v1/pressure_sensor_placement_sensitivity/` | 压力传感器放置-灵敏度分析（高级） | data (body) | - |
+| GET | `/api/v1/pressuresensorplacementkmeans/` | 压力传感器放置-KMeans聚类分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
+| POST | `/api/v1/pressure_sensor_placement_kmeans/` | 压力传感器放置-KMeans聚类分析（高级） | data (body) | - |
+| POST | `/api/v1/sensorplacementscheme/create` | 传感器放置方案创建 | network (query), scheme_name (query), sensor_type (query), method (query), sensor_count (query), user_name (query) | min_diameter (query) |
+| POST | `/api/v1/runsimulationmanuallybydate/` | 手动运行日期指定模拟 | data (body) | - |

+- 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /runproject/` | 运行标准水力模拟，返回纯文本格式的模拟报告 |
+| `GET /runprojectreturndict/` | 运行标准水力模拟，返回JSON字典（含节点/管段结果数据），适合程序处理；结果可达30MB+ |
+| `GET /runinp/` | 运行指定INP文件（文件放在inp文件夹中，参数为不含扩展名的文件名）进行水力模拟 |
+| `GET /dumpoutput/` | 导出指定绝对路径的模拟输出文件内容 |
+| `GET /burstanalysis/` | 基础爆管分析：对指定管道指定时间范围内的爆管事件进行分析，评估对压力/流量的影响 |
+| `GET /burst_analysis/` | 高级爆管分析：支持在指定时间点修改泵控制模式和阀门开度，分析干预措施对爆管影响的作用；支持固定泵和变速泵独立控制 |
+| `GET /valve_close_analysis/` | 高级阀门关闭分析：支持同时关闭多个阀门，指定持续时间，返回纯文本格式结果 |
+| `GET /valve_isolation_analysis/` | 阀门隔离分析：分析突发事件时通过关闭指定阀门进行隔离，确定必须关闭阀门、可选关闭阀门及隔离可行性 |
+| `GET /flushing_analysis/` | 高级冲洗分析：支持同时开启多个阀门冲洗，指定排污节点，设置固定冲洗流量，返回纯文本结果 |
+| `GET /contaminant_simulation/` | 污染物模拟：评估污染源对管网的影响范围和浓度分布，支持指定污染位置、浓度和扩散模式 |
+| `GET /age_analysis/` | 高级水龄分析：在指定时间点分析水体停留时间，支持自定义模拟持续时间，返回纯文本结果 |
+| `POST /pressure_regulation/` | 高级压力调节：通过JSON体提供详细控制参数（固定泵/变速泵独立控制、水箱初始水位等）进行压力优化 |
+| `POST /project_management/` | 高级项目管理：通过JSON体提供详细参数（泵控制策略、水箱水位、区域需水量控制）进行管网管理 |
+| `POST /scheduling_analysis/` | 排程分析：优化泵运行时间和出水流量，平衡水厂出水、水箱进出水，满足用户需求 |
+| `POST /daily_scheduling_analysis/` | 日排程分析：优化水库、水厂、水箱和用户需求协调，制定合理的每日排程方案 |
+| `POST /pump_failure/` | 泵故障管理：记录故障发生时间和受影响的泵列表，更新泵状态日志 |
+| `POST /pressure_sensor_placement_sensitivity/` | 高级传感器放置（灵敏度法）：通过JSON体提供详细参数，基于灵敏度矩阵确定最优放置位置 |
+| `POST /pressure_sensor_placement_kmeans/` | 高级传感器放置（KMeans法）：通过JSON体提供详细参数，基于聚类算法确定最优放置位置 |
+| `POST /sensorplacementscheme/create` | 创建传感器放置方案：支持 sensitivity 和 kmeans 两种算法，自动计算最优传感器位置并存储方案 |
+| `POST /runsimulationmanuallybydate/` | 按日期手动运行模拟：根据指定日期、开始时间和持续时间查询管网参数并执行水力模拟 |
@@ -23,3 +23,14 @@ version: 3.0.0
 | POST | `/api/v1/setruleproperties/` | 设置规则属性 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getcontrolschema/` | 返回简单控制（Control）数据模型的字段定义 |
+| `GET /getcontrolproperties/` | 获取管网中所有简单控制规则的属性列表 |
+| `GET /getruleschema/` | 返回规则控制（Rule）数据模型的字段定义 |
+| `GET /getruleproperties/` | 获取管网中所有基于规则的复杂控制条件列表 |
+| `POST /setcontrolproperties/` | 设置/更新简单控制规则的属性 |
+| `POST /setruleproperties/` | 设置/更新规则控制的属性 |
@@ -24,3 +24,14 @@ version: 3.0.0
 | POST | `/api/v1/setcurveproperties/` | 设置曲线属性 | network (query), curve (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getcurveschema` | 返回曲线（Curve）数据模型的字段定义（水泵特性曲线、效率曲线等） |
+| `GET /getcurves/` | 获取管网中所有曲线的ID列表 |
+| `GET /getcurveproperties/` | 查询指定曲线的详细属性（类型、控制点数据等） |
+| `POST /addcurve/` | 向管网添加一条新曲线 |
+| `POST /deletecurve/` | 从管网删除指定曲线 |
+| `POST /setcurveproperties/` | 设置/更新曲线的属性（控制点坐标等） |
@@ -29,3 +29,15 @@ version: 3.0.0
 | POST | `/api/v1/settimeproperties/` | 设置时间选项属性 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getoptionschema/` | 返回模拟选项（Options）数据模型的字段定义 |
+| `GET /getoptionproperties/` | 获取管网模拟参数设置（时步、精度、单位系统等） |
+| `GET /getenergyschema/` | 返回能耗选项（Energy）数据模型的字段定义 |
+| `GET /getenergyproperties/` | 获取全局能耗设置（电价、效率等） |
+| `GET /getpumpenergyproperties/` | 获取单台水泵的能耗参数 |
+| `POST /setoptionproperties/` | 设置管网模拟参数 |
+| `POST /setenergyproperties/` | 设置全局能耗参数 |
@@ -24,3 +24,14 @@ version: 3.0.0
 | POST | `/api/v1/setpatternproperties/` | 设置模式属性 | network (query), pattern (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getpatternschema` | 返回模式（Pattern）数据模型的字段定义 |
+| `GET /getpatterns/` | 获取管网中所有时间模式的ID列表 |
+| `GET /getpatternproperties/` | 查询指定模式的属性（时间序列乘数值等） |
+| `POST /addpattern/` | 向管网添加一个新时间模式 |
+| `POST /deletepattern/` | 从管网删除指定时间模式 |
+| `POST /setpatternproperties/` | 设置/更新时间模式的属性（乘数序列） |
@@ -42,3 +42,18 @@ version: 3.0.0
 | POST | `/api/v1/settankreaction/` | 设置水池反应属性 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getemitterproperties/` | 查询节点处发射器（用于模拟管漏）的属性 |
+| `GET /getmixingproperties/` | 查询水箱水质混合模型属性 |
+| `GET /getsourceproperties/` | 查询水质污染源的属性（位置、类型、浓度等） |
+| `GET /getreactionproperties/` | 获取全局水质反应参数（管网反应系数等） |
+| `GET /getwaterqualityresult/` | 查询水质模拟结果 |
+| `POST /addsource/` | 向管网添加一个水质污染源 |
+| `POST /deletesource/` | 删除指定水质污染源 |
+| `POST /addmixing/` | 为水箱添加水质混合模型 |
+| `POST /deletemixing/` | 删除水箱水质混合模型 |
+| `POST /setemitter*/` | 设置发射器属性（流量系数等） |
@@ -32,3 +32,14 @@ version: 3.0.0
 | POST | `/api/v1/setvertexproperties/` | 设置图形元素属性 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getallvertexlinks/` | 获取所有管线的折点列表（用于地图还原管线真实走向） |
+| `GET /getvertexlink/` | 获取单条管线的折点坐标序列 |
+| `POST /addvertex/` | 为管线添加一个折点（改变管线显示路径） |
+| `POST /deletevertex/` | 删除管线上的指定折点 |
+| `POST /addlabel/` | 在地图上添加文字标注 |
+| `POST /deletelabel/` | 删除地图文字标注 |
@@ -15,10 +15,18 @@ version: 3.0.0
 ## 接口目录
 | Method | Path | Summary | Required Params | Optional Params |
 |---|---|---|---|---|
-| POST | `/api/v1/auth/login` | login | form_data (body) | - |
-| POST | `/api/v1/auth/login/simple` | login_simple | username (query), password (query) | - |
-| GET | `/api/v1/auth/me` | get_current_user_info | - | - |
-| POST | `/api/v1/auth/refresh` | refresh_token | refresh_token (query) | - |
-| POST | `/api/v1/auth/register` | register | user_data (body) | - |
+| POST | `/api/v1/auth/login` | 用户登录 | form_data (body) | - |
+| POST | `/api/v1/auth/login/simple` | 简化版登录 | username (query), password (query) | - |
+| GET | `/api/v1/auth/me` | 获取当前用户信息 | - | - |
+| POST | `/api/v1/auth/refresh` | 刷新AccessToken | refresh_token (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `POST /login` | OAuth2标准格式登录，提交form-data（username+password），返回JWT Access Token和Refresh Token |
+| `POST /login/simple` | 简化版登录，直接通过query参数传递username和password，保持向后兼容 |
+| `GET /me` | 返回当前已登录用户的详细信息（需携带Access Token） |
+| `POST /refresh` | 使用Refresh Token换取新的Access Token，延续会话 |
@@ -23,3 +23,14 @@ version: 3.0.0
 | POST | `/api/v1/users/{user_id}/deactivate` | 停用用户 | user_id (path) | - |

 - 覆盖方法：`DELETE, GET, POST, PUT`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /users/` | 列出系统中所有用户（管理员权限），支持分页（skip/limit） |
+| `GET /users/{user_id}` | 按用户ID查询单个用户的详细信息 |
+| `PUT /users/{user_id}` | 更新指定用户的信息（邮箱、角色、密码等），请求体为 user_update 对象 |
+| `DELETE /users/{user_id}` | 删除指定用户（软删除或硬删除） |
+| `POST /users/{user_id}/activate` | 激活指定用户账号（管理员操作） |
+| `POST /users/{user_id}/deactivate` | 停用指定用户账号（禁止登录，管理员操作） |
@@ -20,3 +20,11 @@ version: 3.0.0
 | GET | `/api/v1/getuserschema/` | 获取用户模式 | network (query) | - |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getallusers/` | 获取指定管网下的所有用户列表（旧版接口，返回管网级别用户信息） |
+| `GET /getuser/` | 按用户名查询指定管网下的单个用户信息 |
+| `GET /getuserschema/` | 获取用户数据模型的字段定义（Schema） |
@@ -23,3 +23,14 @@ version: 3.0.0
 | POST | `/api/v1/setdemandproperties/` | 设置需水量属性 | network (query), junction (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getdemandschema` | 返回需水量（Demand）数据模型的字段定义 |
+| `GET /getdemandproperties/` | 查询指定节点的需水量属性（基础需水量、模式等） |
+| `POST /setdemandproperties/` | 设置节点的需水量属性 |
+| `POST /calculatedemandtonodes/` | 将指定总需水量计算分配到各节点 |
+| `POST /calculatedemandtoregion/` | 将指定总需水量计算分配到指定区域内的节点 |
+| `POST /calculatedemandtonetwork/` | 将指定总需水量按比例分配到整个管网的所有节点 |
@@ -46,3 +46,17 @@ version: 3.0.0
 | GET | `/api/v1/settitle/` | 设置水网标题属性 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getelementtype/` | 查询指定ID元素的类型（Junction/Pipe/Pump/Tank/Valve/Reservoir） |
+| `GET /getelementtypevalue/` | 查询指定ID元素的类型编码值 |
+| `GET /getelementproperties/` | 查询指定ID元素的所有属性（自动识别类型） |
+| `GET /getelementpropertieswithtype/` | 查询指定类型和ID的元素属性 |
+| `GET /getlinkproperties/` | 查询管线（Pipe/Pump/Valve）的属性 |
+| `GET /getnodeproperties/` | 查询节点（Junction/Tank/Reservoir）的属性 |
+| `GET /settitle/` | 设置管网标题属性 |
+| `POST /deletelink/` | 删除管线（管道/水泵/阀门） |
+| `POST /deletenode/` | 删除节点（节点/水箱/水库） |
@@ -23,3 +23,14 @@ version: 3.0.0
 | GET | `/api/v1/getnodecoord/` | 获取节点坐标 | network (query), node (query) | - |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getnodecoord/` | 查询单个节点（任意类型）的坐标（x, y） |
+| `GET /getmajornodecoords/` | 获取管网主要节点（干管节点）的坐标列表，用于快速渲染 |
+| `GET /getmajorpipenodes/` | 获取主要管道的起终节点列表 |
+| `GET /getnetworklinknodes/` | 获取管网中所有管线的起终节点信息 |
+| `GET /getnetworkgeometries/` | 获取整个管网的完整几何信息（节点坐标 + 管线折点），适合地图绘制 |
+| `GET /getnetworkinextent/` | 查询指定地理范围（bbox）内的管网节点和管线 |
@@ -35,3 +35,18 @@ version: 3.0.0
 | POST | `/api/v1/setjunctiony/` | 设置节点 Y 坐标 | network (query), junction (query), y (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getjunctionschema` | 返回节点（Junction）数据模型的所有字段定义 |
+| `GET /getjunctionproperties/` | 查询单个节点的所有属性（标高、需水量、坐标等） |
+| `GET /getalljunctionproperties/` | 批量获取管网中所有节点的属性列表 |
+| `GET /getjunctioncoord/` | 查询单个节点的坐标（x, y） |
+| `GET /getjunctionelevation/` | 查询节点标高值 |
+| `GET /getjunctiondemand/` | 查询节点基础需水量 |
+| `GET /getjunctionpattern/` | 查询节点关联的需水时间模式名称 |
+| `POST /addjunction/` | 向管网添加一个新节点，需提供ID、坐标和标高 |
+| `POST /deletejunction/` | 从管网删除指定节点 |
+| `POST /setjunction*/` | 设置节点某个具体属性（坐标、标高、需水量等） |
@@ -37,3 +37,18 @@ version: 3.0.0
 | POST | `/api/v1/setpipestatus/` | 设置管道状态 | network (query), pipe (query), status (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getpipeschema` | 返回管道（Pipe）数据模型的所有字段定义 |
+| `GET /getpipeproperties/` | 查询单条管道的所有属性（管径、长度、起终节点等） |
+| `GET /getallpipeproperties/` | 批量获取管网中所有管道的属性列表 |
+| `GET /getpipelength/` | 查询管道长度 |
+| `GET /getpipediameter/` | 查询管道管径 |
+| `GET /getpipestatus/` | 查询管道当前状态（开/关/CV） |
+| `GET /getpiperoughness/` | 查询管道粗糙系数 |
+| `POST /addpipe/` | 向管网添加一条新管道，需提供ID、起终节点、长度和管径 |
+| `POST /deletepipe/` | 从管网删除指定管道 |
+| `POST /setpipe*/` | 设置管道某个具体属性（管径、长度、状态等） |
@@ -27,3 +27,16 @@ version: 3.0.0
 | POST | `/api/v1/setpumpproperties/` | 设置水泵属性 | network (query), pump (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getpumpschema` | 返回水泵（Pump）数据模型的所有字段定义 |
+| `GET /getpumpproperties/` | 查询单台水泵的所有属性（曲线名称、起终节点等） |
+| `GET /getallpumpproperties/` | 批量获取管网中所有水泵的属性列表 |
+| `POST /addpump/` | 向管网添加一台新水泵，需提供ID和起终节点 |
+| `POST /deletepump/` | 从管网删除指定水泵 |
+| `POST /setpumpproperties/` | 批量设置水泵属性（曲线、初始状态、效率等） |
+| `POST /setpumpnode1/` | 设置水泵起始节点 |
+| `POST /setpumpnode2/` | 设置水泵终止节点 |
@@ -54,3 +54,20 @@ version: 3.0.0
 | POST | `/api/v1/setvirtualdistrict/` | 设置虚拟分区属性 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getregionschema` | 返回区域（Region）数据模型的字段定义 |
+| `GET /getregion/` | 查询单个区域的属性 |
+| `GET /getallregions/` | 获取管网中所有区域列表 |
+| `GET /getalldistrictmeteringareas/` | 获取所有 DMA（独立计量区）列表 |
+| `GET /getallserviceareas/` | 获取所有服务区列表 |
+| `POST /addregion/` | 新增区域（需提供名称和节点/管道列表） |
+| `POST /adddistrictmeteringarea/` | 新增 DMA 分区 |
+| `POST /addvirtualdistrict/` | 新增虚拟分区 |
+| `POST /addservicearea/` | 新增服务区 |
+| `POST /calculatedistrictmeteringarea/` | 为指定节点集合计算其所属 DMA |
+| `POST /calculatedistrictmeteringareaforregion/` | 为指定区域内的所有节点计算 DMA 归属 |
+| `POST /calculatedistrictmeteringareafornetwork/` | 为整个管网的所有节点计算 DMA 归属 |
@@ -33,3 +33,16 @@ version: 3.0.0
 | POST | `/api/v1/setreservoiry/` | 设置水库Y坐标 | network (query), reservoir (query), y (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getreservoirschema` | 返回水库（Reservoir）数据模型的所有字段定义 |
+| `GET /getreservoirproperties/` | 查询单个水库的所有属性（水头、模式、坐标等） |
+| `GET /getallreservoirproperties/` | 批量获取管网中所有水库的属性列表 |
+| `GET /getreservoirhead/` | 查询水库水头（即水库水位高度） |
+| `GET /getreservoirpattern/` | 查询水库关联的时间模式名称 |
+| `POST /addreservoir/` | 向管网添加一个新水库，需提供ID、坐标和水头 |
+| `POST /deletereservoir/` | 从管网删除指定水库 |
+| `POST /setreservoir*/` | 设置水库某个具体属性（水头、模式、坐标等） |
@@ -21,3 +21,12 @@ version: 3.0.0
 | POST | `/api/v1/settag/` | 设置标签 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /gettagschema/` | 返回标签（Tag）数据模型的字段定义 |
+| `GET /gettag/` | 查询单个元素绑定的标签信息 |
+| `GET /gettags/` | 获取管网中所有标签列表 |
+| `POST /settag/` | 为管网元素设置/更新标签（支持自定义键值对属性） |
@@ -45,3 +45,17 @@ version: 3.0.0
 | POST | `/api/v1/settanky/` | 设置水箱Y坐标 | network (query), tank (query), y (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /gettankschema` | 返回水箱（Tank）数据模型的所有字段定义 |
+| `GET /gettankproperties/` | 查询单个水箱的所有属性（标高、直径、初始/最大/最小水位等） |
+| `GET /getalltankproperties/` | 批量获取管网中所有水箱的属性列表 |
+| `GET /gettankelevation/` | 查询水箱底部标高 |
+| `GET /gettankdiameter/` | 查询水箱直径 |
+| `GET /gettankinitlevel/` | 查询水箱初始水位 |
+| `POST /addtank/` | 向管网添加一个新水箱，需提供ID、坐标、标高和水位参数 |
+| `POST /deletetank/` | 从管网删除指定水箱 |
+| `POST /settank*/` | 设置水箱某个具体属性（坐标、标高、直径、水位等） |
@@ -34,3 +34,17 @@ version: 3.0.0
 | POST | `/api/v1/setvalvetype/` | 设置阀门类型 | network (query), valve (query), type (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getvalveschema` | 返回阀门（Valve）数据模型的所有字段定义 |
+| `GET /getvalveproperties/` | 查询单个阀门的所有属性（管径、类型、设定值等） |
+| `GET /getallvalveproperties/` | 批量获取管网中所有阀门的属性列表 |
+| `GET /getvalvediameter/` | 查询阀门管径 |
+| `GET /getvalvetype/` | 查询阀门类型（PRV/PSV/TCV/FCV/PBV/GPV） |
+| `GET /getvalvesetting/` | 查询阀门设定值（压力设定或流量设定） |
+| `POST /addvalve/` | 向管网添加一个新阀门，需提供ID、起终节点、管径和类型 |
+| `POST /deletevalve/` | 从管网删除指定阀门 |
+| `POST /setvalve*/` | 设置阀门某个具体属性（类型、设定值、管径等） |
@@ -21,3 +21,12 @@ version: 3.0.0
 | POST | `/api/v1/setextensiondata/` | 设置扩展数据 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getallextensiondatakeys/` | 获取当前管网中所有已存储的自定义扩展数据的键名列表 |
+| `GET /getallextensiondata/` | 获取当前管网所有自定义扩展数据（键值对集合） |
+| `GET /getextensiondata/` | 按 key 查询指定的自定义扩展数据值 |
+| `POST /setextensiondata/` | 设置或更新一个自定义扩展数据键值对（可用于存储任意业务自定义信息） |
@@ -23,3 +23,14 @@ version: 3.0.0
 | POST | `/api/v1/test_dict/` | 测试字典处理 | data (body) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getallburstlocateresults/` | 获取当前管网所有历史爆管定位分析结果（旧版接口） |
+| `GET /getallsensorplacements/` | 获取当前管网所有传感器布置方案的结果列表 |
+| `GET /getsimulationresult/` | 获取最近一次水力模拟结果（旧版接口） |
+| `GET /getrealtimedata/` | 获取管网实时监测数据（旧版接口） |
+| `GET /getjson/` | 返回示例 JSON 数据结构，用于开发调试 |
+| `POST /test_dict/` | 测试字典类型请求体的接口，用于开发调试 |
@@ -21,3 +21,12 @@ version: 3.0.0
 | GET | `/api/v1/scheme-list` | 获取方案列表 | - | - |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /burst-locate-result` | 获取所有爆管定位事件的历史结果列表（新版REST接口） |
+| `GET /burst-locate-result/{burst_incident}` | 查询指定爆管事件（burst_incident ID）的详细定位结果 |
+| `GET /scada-info` | 获取当前项目关联的 SCADA 设备和监测点信息汇总 |
+| `GET /scheme-list` | 获取当前项目中所有可用的水力计算方案列表 |
@@ -15,34 +15,41 @@ version: 3.0.0
 ## 接口目录
 | Method | Path | Summary | Required Params | Optional Params |
 |---|---|---|---|---|
-| POST | `/api/v1/closeproject/` | 关闭项目 | network (query) | - |
-| GET | `/api/v1/convertv3tov2/` | 转换 INP V3 为 V2 | - | - |
-| GET | `/api/v1/convertv3tov2/` | 转换 INP V3 为 V2 | - | - |
-| POST | `/api/v1/copyproject/` | 复制项目 | source (query), target (query) | - |
+| GET | `/api/v1/listprojects/` | 获取项目列表 | - | - |
+| GET | `/api/v1/project_info/` | 获取项目信息 | network (query) | - |
+| GET | `/api/v1/haveproject/` | 检查项目是否存在 | network (query) | - |
 | POST | `/api/v1/createproject/` | 创建新项目 | network (query) | - |
 | POST | `/api/v1/deleteproject/` | 删除项目 | network (query) | - |
-| GET | `/api/v1/downloadinp/` | 下载 INP 文件 | name (query) | - |
-| GET | `/api/v1/downloadinp/` | 下载 INP 文件 | name (query) | - |
-| GET | `/api/v1/dumpinp/` | 导出项目到 INP 文件 | network (query), inp (query) | - |
-| GET | `/api/v1/dumpinp/` | 导出项目到 INP 文件 | network (query), inp (query) | - |
-| GET | `/api/v1/exportinp/` | 导出项目为 ChangeSet | network (query), version (query) | - |
-| GET | `/api/v1/haveproject/` | 检查项目是否存在 | network (query) | - |
-| POST | `/api/v1/importinp/` | 导入 INP 文件内容 | network (query) | - |
-| GET | `/api/v1/isprojectlocked/` | 检查项目是否被锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlocked/` | 检查项目是否被锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlockedbyme/` | 检查项目是否被当前用户锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlockedbyme/` | 检查项目是否被当前用户锁定 | network (query) | - |
+| POST | `/api/v1/copyproject/` | 复制项目 | source (query), target (query) | - |
 | GET | `/api/v1/isprojectopen/` | 检查项目是否已打开 | network (query) | - |
-| GET | `/api/v1/listprojects/` | 获取项目列表 | - | - |
-| POST | `/api/v1/lockproject/` | 锁定项目 | network (query) | - |
-| POST | `/api/v1/lockproject/` | 锁定项目 | network (query) | - |
 | POST | `/api/v1/openproject/` | 打开项目 | network (query) | - |
-| GET | `/api/v1/project_info/` | 获取项目信息 | network (query) | - |
-| POST | `/api/v1/readinp/` | 读取 INP 文件到项目 | network (query), inp (query) | - |
-| POST | `/api/v1/readinp/` | 读取 INP 文件到项目 | network (query), inp (query) | - |
-| POST | `/api/v1/unlockproject/` | 解锁项目 | network (query) | - |
+| POST | `/api/v1/closeproject/` | 关闭项目 | network (query) | - |
+| GET | `/api/v1/isprojectlocked/` | 检查项目是否被锁定 | network (query) | - |
+| GET | `/api/v1/isprojectlockedbyme/` | 检查项目是否被当前用户锁定 | network (query) | - |
+| POST | `/api/v1/lockproject/` | 锁定项目 | network (query) | - |
 | POST | `/api/v1/unlockproject/` | 解锁项目 | network (query) | - |
+| POST | `/api/v1/importinp/` | 导入 INP 文件内容 | network (query) | - |
+| GET | `/api/v1/exportinp/` | 导出项目为 ChangeSet | network (query), version (query) | - |
+| POST | `/api/v1/readinp/` | 读取 INP 文件到项目 | network (query), inp (query) | - |
+| GET | `/api/v1/dumpinp/` | 导出项目到 INP 文件 | network (query), inp (query) | - |
 | POST | `/api/v1/uploadinp/` | 上传 INP 文件 | afile (body), name (query) | - |
-| POST | `/api/v1/uploadinp/` | 上传 INP 文件 | afile (body), name (query) | - |
+| GET | `/api/v1/downloadinp/` | 下载 INP 文件 | name (query) | - |
+| GET | `/api/v1/convertv3tov2/` | 转换 INP V3 为 V2 | - | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /listprojects/` | 获取服务器上所有可用的供水管网项目名称列表 |
+| `GET /project_info/` | 从数据库获取项目的详细信息，包括地图范围等配置 |
+| `POST /createproject/` | 创建一个新的供水管网项目；若已存在可能覆盖或报错 |
+| `POST /deleteproject/` | 永久删除指定项目，此操作不可恢复 |
+| `POST /openproject/` | 将指定项目加载到内存并初始化数据库连接池 |
+| `POST /closeproject/` | 将指定项目从内存中卸载，释放相关资源 |
+| `POST /lockproject/` | 锁定项目以防止并发修改 |
+| `POST /unlockproject/` | 释放对项目的锁定 |
+| `POST /importinp/` | 将 INP 格式文本内容导入到指定项目 |
+| `GET /exportinp/` | 导出项目变更集（ChangeSet），含顶点、SCADA元素、DMA、SA、VD等 |
+| `GET /convertv3tov2/` | 将 EPANET 3.0 格式的 INP 内容转换为 2.x 格式 |
@@ -20,3 +20,11 @@ version: 3.0.0
 | GET | `/api/v1/getschemeschema/` | 获取方案模式 | network (query) | - |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getschemeschema/` | 返回方案（Scheme）数据模型的字段定义 |
+| `GET /getallschemes/` | 获取当前管网下所有已保存方案的列表 |
+| `GET /getscheme/` | 查询指定方案名称（schema_name）的详细属性和配置 |
@@ -35,3 +35,20 @@ version: 3.0.0
 | POST | `/api/v1/undo/` | 撤销操作 | network (query) | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /getsnapshots/` | 列出当前管网所有已保存的快照标签（tag）列表 |
+| `GET /havesnapshot/` | 检查指定 tag 的快照是否存在 |
+| `POST /takesnapshot/` | 保存当前管网状态为一个快照，tag 为快照名称 |
+| `POST /picksnapshot/` | 将管网状态回滚到指定快照，discard=true 时丢弃当前未保存修改 |
+| `GET /getcurrentoperationid/` | 获取当前管网的操作ID（用于追踪操作历史） |
+| `POST /undo/` | 撤销对管网的最近一次操作 |
+| `POST /redo/` | 重做上一次被撤销的操作 |
+| `POST /batch/` | 批量执行多个管网操作命令（原子事务） |
+| `POST /compressedbatch/` | 执行压缩格式的批量命令（减少网络传输量） |
+| `GET /syncwithserver/` | 将客户端的操作与服务端管网状态同步 |
+| `POST /pickoperation/` | 切换到指定 operation ID 的历史操作状态 |
+| `POST /takesnapshotforcurrentoperation` | 为当前 operation 创建快照（保存当前操作节点状态） |
@@ -22,3 +22,13 @@ version: 3.0.0
 | GET | `/api/v1/composite/scada-simulation` | 获取SCADA关联的模拟数据 | start_time (query), end_time (query), device_ids (query) | scheme_type (query), scheme_name (query) |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /composite/scada-simulation` | 将 SCADA 设备历史监测数据与水力模拟结果对齐返回，便于压差分析 |
+| `GET /composite/element-simulation` | 按管网元素ID和属性类型查询该元素在某方案下的模拟时序数据 |
+| `GET /composite/element-scada` | 查询某管网元素关联的 SCADA 设备的历史监测时序数据，支持使用清洗后数据（use_cleaned） |
+| `POST /composite/clean-scada` | 对指定设备在指定时间段的 SCADA 数据进行清洗处理（去噪、异常值替换） |
+| `GET /composite/pipeline-health-prediction` | 在指定时刻对整个管网的管道健康状态进行预测，返回各管道健康评分 |
@@ -27,3 +27,18 @@ version: 3.0.0
 | POST | `/api/v1/realtime/simulation/store` | 存储实时模拟结果 | node_result_list (body), link_result_list (body), result_start_time (query) | - |

 - 覆盖方法：`DELETE, GET, PATCH, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `POST /realtime/links/batch` | 批量将管道（link）模拟结果写入实时数据表（TimescaleDB） |
+| `GET /realtime/links` | 查询指定时间范围内的实时管道模拟数据 |
+| `DELETE /realtime/links` | 删除指定时间范围内的实时管道数据 |
+| `PATCH /realtime/links/{link_id}/field` | 修改某条管道在特定时刻的某个字段值 |
+| `POST /realtime/nodes/batch` | 批量将节点模拟结果写入实时数据表 |
+| `GET /realtime/nodes` | 查询指定时间范围内的实时节点模拟数据 |
+| `DELETE /realtime/nodes` | 删除指定时间范围内的实时节点数据 |
+| `POST /realtime/simulation/store` | 一次性存储一次完整模拟运行的节点和管道结果（含起始时间） |
+| `GET /realtime/query/by-time-property` | 按查询时间点和属性名（如 pressure/flow）查询全网实时模拟值 |
+| `GET /realtime/query/by-id-time` | 按单个元素ID、类型和时间点查询其实时模拟值 |
@@ -29,3 +29,20 @@ version: 3.0.0
 | POST | `/api/v1/scheme/simulation/store` | 存储方案模拟结果 | scheme_type (query), scheme_name (query), node_result_list (body), link_result_list (body), result_start_time (query) | - |

 - 覆盖方法：`DELETE, GET, PATCH, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `POST /scheme/links/batch` | 批量将管道模拟结果写入指定方案（scheme_type + scheme_name）的数据表 |
+| `GET /scheme/links` | 查询指定方案和时间范围内的所有管道模拟数据 |
+| `DELETE /scheme/links` | 删除指定方案和时间范围内的管道模拟数据 |
+| `GET /scheme/links/{link_id}/field` | 查询特定管道在指定方案和时间范围内某字段的时序数据 |
+| `PATCH /scheme/links/{link_id}/field` | 修改特定管道在指定方案某时刻的某个字段值 |
+| `POST /scheme/nodes/batch` | 批量将节点模拟结果写入指定方案的数据表 |
+| `GET /scheme/nodes/{node_id}/field` | 查询特定节点在指定方案和时间范围内某字段的时序数据 |
+| `PATCH /scheme/nodes/{node_id}/field` | 修改特定节点在指定方案某时刻的某个字段值 |
+| `DELETE /scheme/nodes` | 删除指定方案和时间范围内的节点模拟数据 |
+| `POST /scheme/simulation/store` | 一次性存储完整方案模拟结果（节点 + 管道），需提供 scheme_type 和 scheme_name |
+| `GET /scheme/query/by-id-time` | 按元素ID、类型和时间点查询该元素在指定方案下的模拟值 |
+| `GET /scheme/query/by-scheme-time-property` | 按方案、时间点和属性名查询全网在指定方案下的模拟值 |
@@ -20,3 +20,11 @@ version: 3.0.0
 | GET | `/api/v1/audit/logs/my` | 查询我的审计日志 | - | action (query), start_time (query), end_time (query), skip (query), limit (query) |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /audit/logs` | 查询系统审计日志（仅管理员），支持按用户ID、项目ID、操作类型、资源类型、时间范围过滤；支持分页（skip/limit） |
+| `GET /audit/logs/count` | 获取满足过滤条件的审计日志总条数，用于分页显示 |
+| `GET /audit/logs/my` | 查询当前登录用户自己的操作日志，支持按操作类型和时间范围过滤 |
@@ -21,3 +21,12 @@ version: 3.0.0
 | GET | `/api/v1/queryredis/` | 查询缓存键列表 | - | - |

 - 覆盖方法：`GET, POST`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /queryredis/` | 查询当前 Redis 中所有缓存键列表，用于检查缓存状态 |
+| `POST /clearrediskey/` | 删除指定单个键的缓存（精确匹配） |
+| `POST /clearrediskeys/` | 批量删除多个匹配的缓存键（支持模式匹配） |
+| `POST /clearallredis/` | 清除 Redis 中所有缓存数据（慎用，会影响所有会话） |
@@ -20,3 +20,11 @@ version: 3.0.0
 | GET | `/api/v1/meta/projects` | 列出用户项目 | - | - |

 - 覆盖方法：`GET`
+
+## 接口说明
+
+| 接口 | 说明 |
+|---|---|
+| `GET /meta/db/health` | 检查数据库（PostgreSQL/TimescaleDB）连接健康状态，返回 ok/error |
+| `GET /meta/project` | 获取当前用户当前项目的元数据（名称、创建时间、所有者等） |
+| `GET /meta/projects` | 列出当前登录用户有权限访问的所有项目信息 |