OrgTJWater/TJWaterServerBinary
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化API文档，添加参数描述和示例

Browse Source
This commit is contained in:
Jiang
2026-03-13 15:17:06 +08:00
parent 9a8d851275
commit b513d05611
38 changed files with 5846 additions and 1224 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/api/v1/endpoints/timeseries/composite.py
+100 -37
View File
@@ -8,21 +8,37 @@ from .dependencies import get_timescale_connection, get_postgres_connection
router = APIRouter()
@router.get("/composite/scada-simulation")
@router.get("/composite/scada-simulation", summary="获取SCADA关联的模拟数据",
tags=["复合查询"])
async def get_scada_associated_simulation_data(
start_time: datetime,
end_time: datetime,
device_ids: str,
scheme_type: str = Query(None, description="指定方案名称，若为空则查询实时数据"),
scheme_name: str = Query(None, description="指定方案名称，若为空则查询实时数据"),
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
device_ids: str = Query(..., description="SCADA设备ID列表，逗号分隔"),
scheme_type: str = Query(None, description="方案类型，若为空则查询实时数据"),
scheme_name: str = Query(None, description="方案名称，若为空则查询实时数据"),
timescale_conn: AsyncConnection = Depends(get_timescale_connection),
postgres_conn: AsyncConnection = Depends(get_postgres_connection),
):
"""
获取 SCADA 关联的 link/node 模拟值
获取SCADA关联的link/node模拟值
根据传入的SCADA device_ids，找到关联的link/node，
并根据对应的type，查询对应的模拟数据。支持查询实时或方案数据。
根据传入的 SCADA device_ids，找到关联的 link/node，
并根据对应的 type，查询对应的模拟数据
Args:
start_time: 查询开始时间
end_time: 查询结束时间
device_ids: SCADA设备ID列表，用逗号分隔
scheme_type: 方案类型，若为空则查询实时数据
scheme_name: 方案名称，若为空则查询实时数据
timescale_conn: TimescaleDB连接
postgres_conn: PostgreSQL连接
Returns:
SCADA关联的模拟数据
Raises:
HTTPException: 当查询参数无效时返回400错误，未找到数据时返回404错误
"""
try:
device_ids_list = (
@@ -58,26 +74,38 @@ async def get_scada_associated_simulation_data(
raise HTTPException(status_code=400, detail=str(e))
@router.get("/composite/element-simulation")
@router.get("/composite/element-simulation", summary="获取管网元素的模拟数据",
tags=["复合查询"])
async def get_feature_simulation_data(
start_time: datetime,
end_time: datetime,
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
feature_infos: str = Query(
..., description="特征信息，格式: id1:type1,id2:type2，type为pipe或junction"
..., description="特征信息，格式: id1:type1,id2:type2，type为pipe（管道）或junction（节点）"
),
scheme_type: str = Query(None, description="指定方案类型，若为空则查询实时数据"),
scheme_name: str = Query(None, description="指定方案名称，若为空则查询实时数据"),
scheme_type: str = Query(None, description="方案类型，若为空则查询实时数据"),
scheme_name: str = Query(None, description="方案名称，若为空则查询实时数据"),
timescale_conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
获取 link/node 模拟值
根据传入的 featureInfos，找到关联的 link/node，
并根据对应的 type，查询对应的模拟数据
获取link/node模拟值
根据传入的featureInfos，找到关联的link/node，
并根据对应的type，查询对应的模拟数据。支持查询实时或方案数据。
Args:
start_time: 查询开始时间
end_time: 查询结束时间
feature_infos: 格式为 "element_id1:type1,element_id2:type2"
例如: "P1:pipe,J1:junction"
scheme_type: 方案类型，若为空则查询实时数据
scheme_name: 方案名称，若为空则查询实时数据
timescale_conn: TimescaleDB连接
Returns:
管网元素的模拟数据
Raises:
HTTPException: 当feature_infos为空返回400错误，未找到数据返回404错误，其他错误返回400错误
"""
try:
feature_infos_list = []
@@ -117,20 +145,35 @@ async def get_feature_simulation_data(
raise HTTPException(status_code=400, detail=str(e))
@router.get("/composite/element-scada")
@router.get("/composite/element-scada", summary="获取管网元素关联的SCADA监测数据",
tags=["复合查询"])
async def get_element_associated_scada_data(
element_id: str,
start_time: datetime,
end_time: datetime,
element_id: str = Query(..., description="管网元素ID（管道或节点）"),
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
use_cleaned: bool = Query(False, description="是否使用清洗后的数据"),
timescale_conn: AsyncConnection = Depends(get_timescale_connection),
postgres_conn: AsyncConnection = Depends(get_postgres_connection),
):
"""
获取 link/node 关联的 SCADA 监测值
获取link/node关联的SCADA监测值
根据传入的link/node id，匹配SCADA信息，
如果存在关联的SCADA device_id，获取实际的监测数据。
根据传入的 link/node id，匹配 SCADA 信息，
如果存在关联的 SCADA device_id，获取实际的监测数据
Args:
element_id: 管网元素ID
start_time: 查询开始时间
end_time: 查询结束时间
use_cleaned: 是否使用清洗后的数据，默认为False使用原始数据
timescale_conn: TimescaleDB连接
postgres_conn: PostgreSQL连接
Returns:
管网元素关联的SCADA监测数据
Raises:
HTTPException: 当查询参数无效时返回400错误，未找到关联数据返回404错误
"""
try:
result = await CompositeQueries.get_element_associated_scada_data(
@@ -145,18 +188,33 @@ async def get_element_associated_scada_data(
raise HTTPException(status_code=400, detail=str(e))
@router.post("/composite/clean-scada")
@router.post("/composite/clean-scada", summary="清洗SCADA监测数据",
tags=["复合查询"])
async def clean_scada_data(
device_ids: str,
start_time: datetime = Query(...),
end_time: datetime = Query(...),
device_ids: str = Query(..., description="设备ID列表或 'all' 表示清洗所有设备"),
start_time: datetime = Query(..., description="清洗数据的开始时间"),
end_time: datetime = Query(..., description="清洗数据的结束时间"),
timescale_conn: AsyncConnection = Depends(get_timescale_connection),
postgres_conn: AsyncConnection = Depends(get_postgres_connection),
):
"""
清洗 SCADA 数据
清洗SCADA监测数据
根据device_ids查询monitored_value，清洗后更新cleaned_value。
支持清洗指定设备或所有设备的数据。
根据 device_ids 查询 monitored_value，清洗后更新 cleaned_value
Args:
device_ids: 设备ID列表，用逗号分隔，或 'all' 表示清洗所有设备
start_time: 清洗数据的开始时间
end_time: 清洗数据的结束时间
timescale_conn: TimescaleDB连接
postgres_conn: PostgreSQL连接
Returns:
清洗结果信息
Raises:
HTTPException: 当清洗过程出现错误时返回400错误
"""
try:
if device_ids == "all":
@@ -174,24 +232,29 @@ async def clean_scada_data(
raise HTTPException(status_code=400, detail=str(e))
@router.get("/composite/pipeline-health-prediction")
@router.get("/composite/pipeline-health-prediction", summary="预测管道健康状况",
tags=["复合查询"])
async def predict_pipeline_health(
query_time: datetime = Query(..., description="查询时间"),
network_name: str = Query(..., description="管网数据库名称"),
network_name: str = Query(..., description="管网名称（或数据库名称）"),
timescale_conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
预测管道健康状况
根据管网名称和当前时间，查询管道信息和实时数据，
使用随机生存森林模型预测管道的生存概率
使用随机生存森林模型预测管道的生存概率。
Args:
query_time: 查询时间
db_name: 管网数据库名称
network_name: 管网名称（或数据库名称）
timescale_conn: TimescaleDB连接
Returns:
预测结果列表，每个元素包含 link_id 和对应的生存函数
Raises:
HTTPException: 当模型文件不存在返回404错误，其他错误返回400或500错误
"""
try:
return await CompositeQueries.predict_pipeline_health(
app/api/v1/endpoints/timeseries/realtime.py
+176 -37
View File
@@ -1,4 +1,4 @@
from fastapi import APIRouter, Depends, HTTPException
from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
from typing import List
from datetime import datetime
from psycopg import AsyncConnection
@@ -9,41 +9,96 @@ from .dependencies import get_timescale_connection
router = APIRouter()
@router.post("/realtime/links/batch", status_code=201)
@router.post("/realtime/links/batch", status_code=201, summary="批量插入实时管道数据",
tags=["时间序列-实时数据"])
async def insert_realtime_links(
data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
data: List[dict] = Body(..., description="管道数据列表，每项包含管道ID、时间戳等信息"),
conn: AsyncConnection = Depends(get_timescale_connection)
):
"""
批量插入实时管道数据
将管道的实时监测数据批量插入时间序列数据库。
Args:
data: 管道数据列表
Returns:
插入成功的记录数
"""
await RealtimeRepository.insert_links_batch(conn, data)
return {"message": f"Inserted {len(data)} records"}
@router.get("/realtime/links")
@router.get("/realtime/links", summary="查询实时管道数据", tags=["时间序列-实时数据"])
async def get_realtime_links(
start_time: datetime,
end_time: datetime,
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
查询指定时间范围内的实时管道数据
根据时间范围查询所有实时管道的监测值。
Args:
start_time: 查询开始时间
end_time: 查询结束时间
Returns:
实时管道数据列表
"""
return await RealtimeRepository.get_links_by_time_range(conn, start_time, end_time)
@router.delete("/realtime/links")
@router.delete("/realtime/links", summary="删除实时管道数据", tags=["时间序列-实时数据"])
async def delete_realtime_links(
start_time: datetime,
end_time: datetime,
start_time: datetime = Query(..., description="删除开始时间"),
end_time: datetime = Query(..., description="删除结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
删除指定时间范围内的实时管道数据
删除在指定时间范围内的所有实时管道监测数据。
Args:
start_time: 删除开始时间
end_time: 删除结束时间
Returns:
删除结果信息
"""
await RealtimeRepository.delete_links_by_time_range(conn, start_time, end_time)
return {"message": "Deleted successfully"}
@router.patch("/realtime/links/{link_id}/field")
@router.patch("/realtime/links/{link_id}/field", summary="更新实时管道字段",
tags=["时间序列-实时数据"])
async def update_realtime_link_field(
link_id: str,
time: datetime,
field: str,
value: float,
link_id: str = Path(..., description="管道ID"),
time: datetime = Query(..., description="更新数据的时间戳"),
field: str = Query(..., description="要更新的字段名称"),
value: float = Query(..., description="更新的字段值"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
更新指定管道的字段值
更新实时管道在特定时间的某个字段数据。
Args:
link_id: 管道ID
time: 数据时间戳
field: 字段名称
value: 字段新值
Returns:
更新结果信息
Raises:
HTTPException: 当字段不存在或更新失败时返回400错误
"""
try:
await RealtimeRepository.update_link_field(conn, time, link_id, field, value)
return {"message": "Updated successfully"}
@@ -51,55 +106,123 @@ async def update_realtime_link_field(
raise HTTPException(status_code=400, detail=str(e))
@router.post("/realtime/nodes/batch", status_code=201)
@router.post("/realtime/nodes/batch", status_code=201, summary="批量插入实时节点数据",
tags=["时间序列-实时数据"])
async def insert_realtime_nodes(
data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
data: List[dict] = Body(..., description="节点数据列表，每项包含节点ID、时间戳等信息"),
conn: AsyncConnection = Depends(get_timescale_connection)
):
"""
批量插入实时节点数据
将节点的实时监测数据批量插入时间序列数据库。
Args:
data: 节点数据列表
Returns:
插入成功的记录数
"""
await RealtimeRepository.insert_nodes_batch(conn, data)
return {"message": f"Inserted {len(data)} records"}
@router.get("/realtime/nodes")
@router.get("/realtime/nodes", summary="查询实时节点数据", tags=["时间序列-实时数据"])
async def get_realtime_nodes(
start_time: datetime,
end_time: datetime,
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
查询指定时间范围内的实时节点数据
根据时间范围查询所有实时节点的监测值。
Args:
start_time: 查询开始时间
end_time: 查询结束时间
Returns:
实时节点数据列表
"""
return await RealtimeRepository.get_nodes_by_time_range(conn, start_time, end_time)
@router.delete("/realtime/nodes")
@router.delete("/realtime/nodes", summary="删除实时节点数据", tags=["时间序列-实时数据"])
async def delete_realtime_nodes(
start_time: datetime,
end_time: datetime,
start_time: datetime = Query(..., description="删除开始时间"),
end_time: datetime = Query(..., description="删除结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
删除指定时间范围内的实时节点数据
删除在指定时间范围内的所有实时节点监测数据。
Args:
start_time: 删除开始时间
end_time: 删除结束时间
Returns:
删除结果信息
"""
await RealtimeRepository.delete_nodes_by_time_range(conn, start_time, end_time)
return {"message": "Deleted successfully"}
@router.post("/realtime/simulation/store", status_code=201)
@router.post("/realtime/simulation/store", status_code=201, summary="存储实时模拟结果",
tags=["时间序列-实时数据"])
async def store_realtime_simulation_result(
node_result_list: List[dict],
link_result_list: List[dict],
result_start_time: str,
node_result_list: List[dict] = Body(..., description="节点模拟结果列表"),
link_result_list: List[dict] = Body(..., description="管道模拟结果列表"),
result_start_time: str = Query(..., description="模拟结果开始时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""Store realtime simulation results to TimescaleDB"""
"""
存储实时模拟结果到时间序列数据库
将节点和管道的实时模拟计算结果批量存储到TimescaleDB数据库。
Args:
node_result_list: 节点模拟结果列表
link_result_list: 管道模拟结果列表
result_start_time: 模拟结果对应的起始时间
Returns:
存储结果信息
"""
await RealtimeRepository.store_realtime_simulation_result(
conn, node_result_list, link_result_list, result_start_time
)
return {"message": "Simulation results stored successfully"}
@router.get("/realtime/query/by-time-property")
@router.get("/realtime/query/by-time-property", summary="按时间和属性查询实时数据",
tags=["时间序列-实时数据"])
async def query_realtime_records_by_time_property(
query_time: str,
type: str,
property: str,
query_time: str = Query(..., description="查询时间"),
type: str = Query(..., description="数据类型，pipe（管道）或 junction（节点）"),
property: str = Query(..., description="要查询的属性名称"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""Query all realtime records by time and property"""
"""
按指定时间和属性查询所有实时监测数据
查询在特定时间点，所有指定类型元素的特定属性值。
Args:
query_time: 查询时间
type: 元素类型（pipe或junction）
property: 属性名称
Returns:
查询结果列表
Raises:
HTTPException: 当查询参数无效时返回400错误
"""
try:
results = await RealtimeRepository.query_all_record_by_time_property(
conn, query_time, type, property
@@ -109,14 +232,30 @@ async def query_realtime_records_by_time_property(
raise HTTPException(status_code=400, detail=str(e))
@router.get("/realtime/query/by-id-time")
@router.get("/realtime/query/by-id-time", summary="按ID和时间查询实时模拟数据",
tags=["时间序列-实时数据"])
async def query_realtime_simulation_by_id_time(
id: str,
type: str,
query_time: str,
id: str = Query(..., description="元素ID（管道ID或节点ID）"),
type: str = Query(..., description="元素类型，pipe（管道）或 junction（节点）"),
query_time: str = Query(..., description="查询时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""Query realtime simulation results by id and time"""
"""
按指定ID和时间查询实时模拟结果
查询特定元素在某一时间点的实时模拟数据。
Args:
id: 元素ID
type: 元素类型（pipe或junction）
query_time: 查询时间
Returns:
模拟结果数据
Raises:
HTTPException: 当查询参数无效时返回400错误
"""
try:
results = await RealtimeRepository.query_simulation_result_by_id_time(
conn, id, type, query_time
app/api/v1/endpoints/timeseries/scada.py
+98 -21
View File
@@ -1,4 +1,4 @@
from fastapi import APIRouter, Depends, HTTPException
from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
from typing import List
from datetime import datetime
from psycopg import AsyncConnection
@@ -9,21 +9,48 @@ from .dependencies import get_timescale_connection
router = APIRouter()
@router.post("/scada/batch", status_code=201)
@router.post("/scada/batch", status_code=201, summary="批量插入SCADA监测数据",
tags=["时间序列-监测数据"])
async def insert_scada_data(
data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
data: List[dict] = Body(..., description="SCADA设备监测数据列表"),
conn: AsyncConnection = Depends(get_timescale_connection)
):
"""
批量插入SCADA监测数据
将多个设备的实时监测数据批量插入时间序列数据库。
Args:
data: SCADA设备监测数据列表，每项包含device_id、时间戳和监测值等信息
Returns:
插入成功的记录数
"""
await ScadaRepository.insert_scada_batch(conn, data)
return {"message": f"Inserted {len(data)} records"}
@router.get("/scada/by-ids-time-range")
@router.get("/scada/by-ids-time-range", summary="按设备ID和时间范围查询SCADA数据",
tags=["时间序列-监测数据"])
async def get_scada_by_ids_time_range(
start_time: datetime,
end_time: datetime,
device_ids: str,
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
device_ids: str = Query(..., description="设备ID列���，逗号分隔，如 'device1,device2,device3'"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
按设备ID和时间范围查询SCADA监测数据
查询多个设备在指定时间范围内的所有监测数据。
Args:
start_time: 查询开始时间
end_time: 查询结束时间
device_ids: 设备ID列表，用逗号分隔
Returns:
SCADA监测数据列表
"""
device_ids_list = (
[id.strip() for id in device_ids.split(",") if id.strip()] if device_ids else []
)
@@ -32,14 +59,32 @@ async def get_scada_by_ids_time_range(
)
@router.get("/scada/by-ids-field-time-range")
@router.get("/scada/by-ids-field-time-range", summary="按设备ID、字段和时间范围查询SCADA数据",
tags=["时间序列-监测数据"])
async def get_scada_field_by_ids_time_range(
start_time: datetime,
end_time: datetime,
field: str,
device_ids: str,
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
field: str = Query(..., description="要查询的字段名称"),
device_ids: str = Query(..., description="设备ID列表，逗号分隔，如 'device1,device2,device3'"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
按设备ID、字段和时间范围查询特定SCADA数据
查询多个设备在指定时间范围内的特定字段监测数据。
Args:
start_time: 查询开始时间
end_time: 查询结束时间
field: 字段名称
device_ids: 设备ID列表，用逗号分隔
Returns:
SCADA字段数据列表
Raises:
HTTPException: 当字段不存在或查询参数无效时返回400错误
"""
try:
device_ids_list = (
[id.strip() for id in device_ids.split(",") if id.strip()]
@@ -53,14 +98,32 @@ async def get_scada_field_by_ids_time_range(
raise HTTPException(status_code=400, detail=str(e))
@router.patch("/scada/{device_id}/field")
@router.patch("/scada/{device_id}/field", summary="更新SCADA设备字段",
tags=["时间序列-监测数据"])
async def update_scada_field(
device_id: str,
time: datetime,
field: str,
value: float,
device_id: str = Path(..., description="设备ID"),
time: datetime = Query(..., description="更新数据的时间戳"),
field: str = Query(..., description="要更新的字段名称"),
value: float = Query(..., description="更新的字段值"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
更新指定设备的字段值
更新SCADA设备在特定时间的某个字段监测数据。
Args:
device_id: 设备ID
time: 数据时间戳
field: 字段名称
value: 字段新值
Returns:
更新结果信息
Raises:
HTTPException: 当字段不存在或更新失败时返回400错误
"""
try:
await ScadaRepository.update_scada_field(conn, time, device_id, field, value)
return {"message": "Updated successfully"}
@@ -68,13 +131,27 @@ async def update_scada_field(
raise HTTPException(status_code=400, detail=str(e))
@router.delete("/scada/by-id-time-range")
@router.delete("/scada/by-id-time-range", summary="按设备ID和时间范围删除SCADA数据",
tags=["时间序列-监测数据"])
async def delete_scada_data(
device_id: str,
start_time: datetime,
end_time: datetime,
device_id: str = Query(..., description="设备ID"),
start_time: datetime = Query(..., description="删除开始时间"),
end_time: datetime = Query(..., description="删除结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
删除指定设备和时间范围内的SCADA数据
删除在指定时间范围内的特定设备监测数据。
Args:
device_id: 设备ID
start_time: 删除开始时间
end_time: 删除结束时间
Returns:
删除结果信息
"""
await ScadaRepository.delete_scada_by_id_time_range(
conn, device_id, start_time, end_time
)
app/api/v1/endpoints/timeseries/scheme.py
+268 -69
View File
@@ -1,4 +1,4 @@
from fastapi import APIRouter, Depends, HTTPException
from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
from typing import List
from datetime import datetime
from psycopg import AsyncConnection
@@ -9,37 +9,84 @@ from .dependencies import get_timescale_connection
router = APIRouter()
@router.post("/scheme/links/batch", status_code=201)
@router.post("/scheme/links/batch", status_code=201, summary="批量插入方案管道数据",
tags=["时间序列-方案数据"])
async def insert_scheme_links(
data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
data: List[dict] = Body(..., description="方案管道数据列表"),
conn: AsyncConnection = Depends(get_timescale_connection)
):
"""
批量插入方案管道数据
将特定方案的管道模拟数据批量插入时间序列数据库。
Args:
data: 方案管道数据列表
Returns:
插入成功的记录数
"""
await SchemeRepository.insert_links_batch(conn, data)
return {"message": f"Inserted {len(data)} records"}
@router.get("/scheme/links")
@router.get("/scheme/links", summary="查询方案管道数据", tags=["时间序列-方案数据"])
async def get_scheme_links(
scheme_type: str,
scheme_name: str,
start_time: datetime,
end_time: datetime,
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
查询指定方案和时间范围内的管道数据
根据方案和时间范围查询管道的模拟值。
Args:
scheme_type: 方案类型
scheme_name: 方案名称
start_time: 查询开始时间
end_time: 查询结束时间
Returns:
方案管道数据列表
"""
return await SchemeRepository.get_links_by_scheme_and_time_range(
conn, scheme_type, scheme_name, start_time, end_time
)
@router.get("/scheme/links/{link_id}/field")
@router.get("/scheme/links/{link_id}/field", summary="查询方案管道字段数据",
tags=["时间序列-方案数据"])
async def get_scheme_link_field(
scheme_type: str,
scheme_name: str,
link_id: str,
start_time: datetime,
end_time: datetime,
field: str,
link_id: str = Path(..., description="管道ID"),
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
field: str = Query(..., description="要查询的字段名称"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
查询指定方案管道的特定字段数据
查询特定方案中指定管道在时间范围内的特定字段值。
Args:
link_id: 管道ID
scheme_type: 方案类型
scheme_name: 方案名称
start_time: 查询开始时间
end_time: 查询结束时间
field: 字段名称
Returns:
字段数据列表
Raises:
HTTPException: 当查询参数无效时返回400错误
"""
try:
return await SchemeRepository.get_link_field_by_scheme_and_time_range(
conn, scheme_type, scheme_name, start_time, end_time, link_id, field
@@ -48,16 +95,36 @@ async def get_scheme_link_field(
raise HTTPException(status_code=400, detail=str(e))
@router.patch("/scheme/links/{link_id}/field")
@router.patch("/scheme/links/{link_id}/field", summary="更新方案管道字段",
tags=["时间序列-方案数据"])
async def update_scheme_link_field(
scheme_type: str,
scheme_name: str,
link_id: str,
time: datetime,
field: str,
value: float,
link_id: str = Path(..., description="管道ID"),
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
time: datetime = Query(..., description="更新数据的时间戳"),
field: str = Query(..., description="要更新的字段名称"),
value: float = Query(..., description="更新的字段值"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
更新指定方案管道的字段值
更新特定方案中指定管道在某个时间的字段数据。
Args:
link_id: 管道ID
scheme_type: 方案类型
scheme_name: 方案名称
time: 数据时间戳
field: 字段名称
value: 字段新值
Returns:
更新结果信息
Raises:
HTTPException: 当字段不存在或更新失败时返回400错误
"""
try:
await SchemeRepository.update_link_field(
conn, time, scheme_type, scheme_name, link_id, field, value
@@ -67,38 +134,85 @@ async def update_scheme_link_field(
raise HTTPException(status_code=400, detail=str(e))
@router.delete("/scheme/links")
@router.delete("/scheme/links", summary="删除方案管道数据", tags=["时间序列-方案数据"])
async def delete_scheme_links(
scheme_type: str,
scheme_name: str,
start_time: datetime,
end_time: datetime,
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
start_time: datetime = Query(..., description="删除开始时间"),
end_time: datetime = Query(..., description="删除结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
删除指定方案和时间范围内的管道数据
删除在指定方案和时间范围内的所有管道模拟数据。
Args:
scheme_type: 方案类型
scheme_name: 方案名称
start_time: 删除开始时间
end_time: 删除结束时间
Returns:
删除结果信息
"""
await SchemeRepository.delete_links_by_scheme_and_time_range(
conn, scheme_type, scheme_name, start_time, end_time
)
return {"message": "Deleted successfully"}
@router.post("/scheme/nodes/batch", status_code=201)
@router.post("/scheme/nodes/batch", status_code=201, summary="批量插入方案节点数据",
tags=["时间序列-方案数据"])
async def insert_scheme_nodes(
data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
data: List[dict] = Body(..., description="方案节点数据列表"),
conn: AsyncConnection = Depends(get_timescale_connection)
):
"""
批量插入方案节点数据
将特定方案的节点模拟数据批量插入时间序列数据库。
Args:
data: 方案节点数据列表
Returns:
插入成功的记录数
"""
await SchemeRepository.insert_nodes_batch(conn, data)
return {"message": f"Inserted {len(data)} records"}
@router.get("/scheme/nodes/{node_id}/field")
@router.get("/scheme/nodes/{node_id}/field", summary="查询方案节点字段数据",
tags=["时间序列-方案数据"])
async def get_scheme_node_field(
scheme_type: str,
scheme_name: str,
node_id: str,
start_time: datetime,
end_time: datetime,
field: str,
node_id: str = Path(..., description="节点ID"),
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
start_time: datetime = Query(..., description="查询开始时间"),
end_time: datetime = Query(..., description="查询结束时间"),
field: str = Query(..., description="要查询的字段名称"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
查询指定方案节点的特定字段数据
查询特定方案中指定节点在时间范围内的特定字段值。
Args:
node_id: 节点ID
scheme_type: 方案类型
scheme_name: 方案名称
start_time: 查询开始时间
end_time: 查询结束时间
field: 字段名称
Returns:
字段数据列表
Raises:
HTTPException: 当查询参数无效时返回400错误
"""
try:
return await SchemeRepository.get_node_field_by_scheme_and_time_range(
conn, scheme_type, scheme_name, start_time, end_time, node_id, field
@@ -107,16 +221,36 @@ async def get_scheme_node_field(
raise HTTPException(status_code=400, detail=str(e))
@router.patch("/scheme/nodes/{node_id}/field")
@router.patch("/scheme/nodes/{node_id}/field", summary="更新方案节点字段",
tags=["时间序列-方案数据"])
async def update_scheme_node_field(
scheme_type: str,
scheme_name: str,
node_id: str,
time: datetime,
field: str,
value: float,
node_id: str = Path(..., description="节点ID"),
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
time: datetime = Query(..., description="更新数据的时间戳"),
field: str = Query(..., description="要更新的字段名称"),
value: float = Query(..., description="更新的字段值"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
更新指定方案节点的字段值
更新特定方案中指定节点在某个时间的字段数据。
Args:
node_id: 节点ID
scheme_type: 方案类型
scheme_name: 方案名称
time: 数据时间戳
field: 字段名称
value: 字段新值
Returns:
更新结果信息
Raises:
HTTPException: 当字段不存在或更新失败时返回400错误
"""
try:
await SchemeRepository.update_node_field(
conn, time, scheme_type, scheme_name, node_id, field, value
@@ -126,30 +260,59 @@ async def update_scheme_node_field(
raise HTTPException(status_code=400, detail=str(e))
@router.delete("/scheme/nodes")
@router.delete("/scheme/nodes", summary="删除方案节点数据", tags=["时间序列-方案数据"])
async def delete_scheme_nodes(
scheme_type: str,
scheme_name: str,
start_time: datetime,
end_time: datetime,
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
start_time: datetime = Query(..., description="删除开始时间"),
end_time: datetime = Query(..., description="删除结束时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""
删除指定方案和时间范围内的节点数据
删除在指定方案和时间范围内的所有节点模拟数据。
Args:
scheme_type: 方案类型
scheme_name: 方案名称
start_time: 删除开始时间
end_time: 删除结束时间
Returns:
删除结果信息
"""
await SchemeRepository.delete_nodes_by_scheme_and_time_range(
conn, scheme_type, scheme_name, start_time, end_time
)
return {"message": "Deleted successfully"}
@router.post("/scheme/simulation/store", status_code=201)
@router.post("/scheme/simulation/store", status_code=201, summary="存储方案模拟结果",
tags=["时间序列-方案数据"])
async def store_scheme_simulation_result(
scheme_type: str,
scheme_name: str,
node_result_list: List[dict],
link_result_list: List[dict],
result_start_time: str,
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
node_result_list: List[dict] = Body(..., description="节点模拟结果列表"),
link_result_list: List[dict] = Body(..., description="管道模拟结果列表"),
result_start_time: str = Query(..., description="模拟结果开始时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""Store scheme simulation results to TimescaleDB"""
"""
存储方案模拟结果到时间序列数据库
将特定方案的节点和管道模拟计算结果批量存储到TimescaleDB数据库。
Args:
scheme_type: 方案类型
scheme_name: 方案名称
node_result_list: 节点模拟结果列表
link_result_list: 管道模拟结果列表
result_start_time: 模拟结果对应的起始时间
Returns:
存储结果信息
"""
await SchemeRepository.store_scheme_simulation_result(
conn,
scheme_type,
@@ -161,16 +324,34 @@ async def store_scheme_simulation_result(
return {"message": "Scheme simulation results stored successfully"}
@router.get("/scheme/query/by-scheme-time-property")
@router.get("/scheme/query/by-scheme-time-property", summary="按方案、时间和属性查询数据",
tags=["时间序列-方案数据"])
async def query_scheme_records_by_scheme_time_property(
scheme_type: str,
scheme_name: str,
query_time: str,
type: str,
property: str,
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
query_time: str = Query(..., description="查询时间"),
type: str = Query(..., description="元素类型，pipe（管道）或 junction（节点）"),
property: str = Query(..., description="要查询的属性名称"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""Query all scheme records by scheme, time and property"""
"""
按指定方案、时间和属性查询所有方案数据
查询在特定方案和时间点，所有指定类型元素的特定属性值。
Args:
scheme_type: 方案类型
scheme_name: 方案名称
query_time: 查询时间
type: 元素类型（pipe或junction）
property: 属性名称
Returns:
查询结果列表
Raises:
HTTPException: 当查询参数无效时返回400错误
"""
try:
results = await SchemeRepository.query_all_record_by_scheme_time_property(
conn, scheme_type, scheme_name, query_time, type, property
@@ -180,16 +361,34 @@ async def query_scheme_records_by_scheme_time_property(
raise HTTPException(status_code=400, detail=str(e))
@router.get("/scheme/query/by-id-time")
@router.get("/scheme/query/by-id-time", summary="按ID和时间查询方案模拟数据",
tags=["时间序列-方案数据"])
async def query_scheme_simulation_by_id_time(
scheme_type: str,
scheme_name: str,
id: str,
type: str,
query_time: str,
scheme_type: str = Query(..., description="方案类型"),
scheme_name: str = Query(..., description="方案名称"),
id: str = Query(..., description="元素ID（管道ID或节点ID）"),
type: str = Query(..., description="元素类型，pipe（管道）或 junction（节点）"),
query_time: str = Query(..., description="查询时间"),
conn: AsyncConnection = Depends(get_timescale_connection),
):
"""Query scheme simulation results by id and time"""
"""
按指定ID和时间查询方案模拟结果
查询特定方案中的元素在某一时间点的模拟数据。
Args:
scheme_type: 方案类型
scheme_name: 方案名称
id: 元素ID
type: 元素类型（pipe或junction）
query_time: 查询时间
Returns:
模拟结果数据
Raises:
HTTPException: 当查询参数无效时返回400错误
"""
try:
result = await SchemeRepository.query_scheme_simulation_result_by_id_time(
conn, scheme_type, scheme_name, id, type, query_time