DSN 复用已有连接池

.github/workflows/build-package.yml

@@ -0,0 +1,128 @@
+name: Build And Package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-package:
+    runs-on: ${{ matrix.os }}
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install system build tools
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential
+
+      - name: Install compile dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install cython setuptools wheel
+
+      - name: Run Cython compile
+        run: |
+          python scripts/compile.py
+
+      - name: Prepare package and archive
+        run: |
+          python - <<'PY'
+          import os
+          import shutil
+          import tarfile
+          import zipfile
+          import sys
+          from pathlib import Path
+
+          root = Path.cwd()
+          package_dir = root / "package"
+          dist_dir = root / "dist"
+
+          for d in [package_dir, dist_dir]:
+            if d.exists():
+              shutil.rmtree(d)
+            d.mkdir(parents=True, exist_ok=True)
+
+          # Define directories with compiled artifacts
+          compile_dirs = ["app/services", "app/native/wndb", "app/algorithms"]
+          # Global ignore list
+          ignore_names = {
+            ".git",
+            ".github",
+            "__pycache__",
+            ".pytest_cache",
+            ".mypy_cache",
+            ".venv",
+            "venv",
+            "temp",
+            "tests",
+            "package",
+            "dist",
+          }
+
+          def ignore_func(directory, names):
+            rel_dir = os.path.relpath(directory, root).replace("\\", "/")
+            is_in_compile_path = any(rel_dir.startswith(d) for d in compile_dirs)
+            
+            ignored = []
+            for name in names:
+              if name in ignore_names or name.endswith(".pyc"):
+                ignored.append(name)
+              # Exclude source .py files only in compiled directories
+              elif is_in_compile_path and name.endswith(".py"):
+                ignored.append(name)
+            return ignored
+
+          for item in root.iterdir():
+            if item.name in ignore_names:
+              continue
+            target = package_dir / item.name
+            if item.is_dir():
+              shutil.copytree(item, target, ignore=ignore_func)
+            else:
+              shutil.copy2(item, target)
+
+          # Safety guard: ensure no .github directory remains
+          github_paths = [p for p in package_dir.rglob(".github") if p.is_dir()]
+          for p in github_paths:
+            shutil.rmtree(p, ignore_errors=True)
+
+          sha = os.environ["GITHUB_SHA"]
+          run_os = os.environ["RUNNER_OS"].lower()
+
+          if run_os == "windows":
+            archive_path = dist_dir / f"tjwater-server-{run_os}-{sha}.zip"
+            with zipfile.ZipFile(archive_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+              for f in package_dir.rglob("*"):
+                if f.is_file():
+                  zf.write(f, f.relative_to(package_dir))
+          else:
+            archive_path = dist_dir / f"tjwater-server-{run_os}-{sha}.tar.gz"
+            with tarfile.open(archive_path, "w:gz") as tf:
+              tf.add(package_dir, arcname=".")
+
+          print(f"Archive created: {archive_path}")
+          PY
+        shell: bash
+
+      - name: Upload package artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: tjwater-server-package-${{ runner.os }}
+          path: dist/*
+          retention-days: 14

Dockerfile

@@ -8,7 +8,7 @@ RUN conda install -y -c conda-forge python=3.12 pymetis && \
 
 COPY requirements.txt .
 RUN pip install uv
-RUN uv pip install --no-cache-dir -r requirements.txt
+RUN uv pip install --system --no-cache-dir -r requirements.txt
 
 # 将代码放入子目录 'app'，将数据放入子目录 'db_inp'
 # 这样临时文件默认会生成在 /app 下，而代码在 /app/app 下，实现了分离

app/algorithms/simulation/scenarios.py

@@ -9,7 +9,6 @@ from app.algorithms.simulation.runner import (
     run_simulation_ex,
     from_clock_to_seconds_2,
 )
-from app.infra.epanet.epanet import Output
 from app.services.scheme_management import store_scheme_info
 from app.services.tjnetwork import (
     ChangeSet,
@@ -666,21 +665,21 @@ def age_analysis(
         modify_total_duration,
         downloading_prohibition=True,
     )
+    simulation_result = json.loads(result)
+    output_data = simulation_result.get("output")
+    if not isinstance(output_data, dict):
+        raise RuntimeError("run_simulation_ex did not return JSON output content")
     # step 2. restore the base model status
     # execute_undo(name) #有疑惑
     if is_project_open(new_name):
         close_project(new_name)
     delete_project(new_name)
-    output = Output("./temp/{}.db.out".format(new_name))
-    # element_name = output.element_name()
-    # node_name = element_name['nodes']
-    # link_name = element_name['links']
     nodes_age = []
-    node_result = output.node_results()
+    node_result = output_data.get("node_results") or []
     for node in node_result:
         nodes_age.append(node["result"][-1]["quality"])
     links_age = []
-    link_result = output.link_results()
+    link_result = output_data.get("link_results") or []
     for link in link_result:
         links_age.append(link["result"][-1]["quality"])
     age_result = {"nodes": nodes_age, "links": links_age}

app/api/v1/endpoints/audit.py

@@ -3,28 +3,36 @@
 
 仅管理员可访问
 """
+
 from typing import List, Optional
 from uuid import UUID
 from datetime import datetime
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, Query, Path
 from app.domain.schemas.audit import AuditLogResponse
-from app.infra.repositories.audit_repository import AuditRepository
+from app.infra.db.metadb.repositories.audit_repository import AuditRepository
 from app.auth.metadata_dependencies import (
     get_current_metadata_admin,
     get_current_metadata_user,
 )
-from app.infra.db.metadata.database import get_metadata_session
+from app.infra.db.metadb.database import get_metadata_session
 from sqlalchemy.ext.asyncio import AsyncSession
 
 router = APIRouter()
 
+
 async def get_audit_repository(
     session: AsyncSession = Depends(get_metadata_session),
 ) -> AuditRepository:
     """获取审计日志仓储"""
     return AuditRepository(session)
 
-@router.get("/logs", response_model=List[AuditLogResponse])
+
+@router.get(
+    "/logs",
+    summary="查询审计日志",
+    description="查询审计日志（仅管理员）",
+    response_model=List[AuditLogResponse],
+)
 async def get_audit_logs(
     user_id: Optional[UUID] = Query(None, description="按用户ID过滤"),
     project_id: Optional[UUID] = Query(None, description="按项目ID过滤"),
@@ -38,9 +46,9 @@ async def get_audit_logs(
     audit_repo: AuditRepository = Depends(get_audit_repository),
 ) -> List[AuditLogResponse]:
     """
-    查询审计日志（仅管理员）
-    
-    支持按用户、时间、操作类型等条件过滤
+    查询审计日志
+
+    支持按用户、时间、操作类型等条件过滤，仅管理员可访问
     """
     logs = await audit_repo.get_logs(
         user_id=user_id,
@@ -50,11 +58,16 @@ async def get_audit_logs(
         start_time=start_time,
         end_time=end_time,
         skip=skip,
-        limit=limit
+        limit=limit,
     )
     return logs
 
-@router.get("/logs/count")
+
+@router.get(
+    "/logs/count",
+    summary="获取审计日志总数",
+    description="获取审计日志总数（仅管理员）",
+)
 async def get_audit_logs_count(
     user_id: Optional[UUID] = Query(None, description="按用户ID过滤"),
     project_id: Optional[UUID] = Query(None, description="按项目ID过滤"),
@@ -66,7 +79,9 @@ async def get_audit_logs_count(
     audit_repo: AuditRepository = Depends(get_audit_repository),
 ) -> dict:
     """
-    获取审计日志总数（仅管理员）
+    获取审计日志总数
+
+    获取符合条件的审计日志的总数，仅管理员可访问
     """
     count = await audit_repo.get_log_count(
         user_id=user_id,
@@ -74,23 +89,29 @@ async def get_audit_logs_count(
         action=action,
         resource_type=resource_type,
         start_time=start_time,
-        end_time=end_time
+        end_time=end_time,
     )
     return {"count": count}
 
-@router.get("/logs/my", response_model=List[AuditLogResponse])
+
+@router.get(
+    "/logs/my",
+    summary="查询我的审计日志",
+    description="查询当前用户的审计日志",
+    response_model=List[AuditLogResponse],
+)
 async def get_my_audit_logs(
     action: Optional[str] = Query(None, description="按操作类型过滤"),
     start_time: Optional[datetime] = Query(None, description="开始时间"),
     end_time: Optional[datetime] = Query(None, description="结束时间"),
-    skip: int = Query(0, ge=0),
-    limit: int = Query(100, ge=1, le=1000),
+    skip: int = Query(0, ge=0, description="跳过记录数"),
+    limit: int = Query(100, ge=1, le=1000, description="限制记录数"),
     current_user=Depends(get_current_metadata_user),
     audit_repo: AuditRepository = Depends(get_audit_repository),
 ) -> List[AuditLogResponse]:
     """
     查询当前用户的审计日志
-    
+
     普通用户只能查看自己的操作记录
     """
     logs = await audit_repo.get_logs(
@@ -99,6 +120,6 @@ async def get_my_audit_logs(
         start_time=start_time,
         end_time=end_time,
         skip=skip,
-        limit=limit
+        limit=limit,
     )
     return logs

app/api/v1/endpoints/auth.py

@@ -5,7 +5,7 @@ from fastapi.security import OAuth2PasswordRequestForm
 from app.core.config import settings
 from app.core.security import create_access_token, create_refresh_token, verify_password
 from app.domain.schemas.user import UserCreate, UserResponse, UserLogin, Token
-from app.infra.repositories.user_repository import UserRepository
+from app.infra.db.metadb.repositories.user_repository import UserRepository
 from app.auth.dependencies import get_user_repository, get_current_active_user
 from app.domain.schemas.user import UserInDB
 import logging
@@ -14,53 +14,55 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter()
 
-@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+
+@router.post(
+    "/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED
+)
 async def register(
-    user_data: UserCreate,
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_data: UserCreate, user_repo: UserRepository = Depends(get_user_repository)
 ) -> UserResponse:
     """
     用户注册
-    
+
     创建新用户账号
     """
     # 检查用户名和邮箱是否已存在
     if await user_repo.user_exists(username=user_data.username):
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Username already registered"
+            detail="Username already registered",
         )
-    
+
     if await user_repo.user_exists(email=user_data.email):
         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Email already registered"
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Email already registered"
         )
-    
+
     # 创建用户
     try:
         user = await user_repo.create_user(user_data)
         if not user:
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                detail="Failed to create user"
+                detail="Failed to create user",
             )
         return UserResponse.model_validate(user)
     except Exception as e:
         logger.error(f"Error during user registration: {e}")
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="Registration failed"
+            detail="Registration failed",
         )
 
+
 @router.post("/login", response_model=Token)
 async def login(
     form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> Token:
     """
     用户登录（OAuth2 标准格式）
-    
+
     返回 JWT Access Token 和 Refresh Token
     """
     # 验证用户（支持用户名或邮箱登录）
@@ -68,119 +70,121 @@ async def login(
     if not user:
         # 尝试用邮箱登录
         user = await user_repo.get_user_by_email(form_data.username)
-    
+
     if not user or not verify_password(form_data.password, user.hashed_password):
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Incorrect username or password",
             headers={"WWW-Authenticate": "Bearer"},
         )
-    
+
     if not user.is_active:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Inactive user account"
+            status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user account"
         )
-    
+
     # 生成 Token
     access_token = create_access_token(subject=user.username)
     refresh_token = create_refresh_token(subject=user.username)
-    
+
     return Token(
         access_token=access_token,
         refresh_token=refresh_token,
         token_type="bearer",
-        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
+        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
     )
 
+
 @router.post("/login/simple", response_model=Token)
 async def login_simple(
     username: str,
     password: str,
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> Token:
     """
     简化版登录接口（保持向后兼容）
-    
+
     直接使用 username 和 password 参数
     """
     # 验证用户
     user = await user_repo.get_user_by_username(username)
     if not user:
         user = await user_repo.get_user_by_email(username)
-    
+
     if not user or not verify_password(password, user.hashed_password):
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Incorrect username or password"
+            detail="Incorrect username or password",
         )
-    
+
     if not user.is_active:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Inactive user account"
+            status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user account"
         )
-    
+
     # 生成 Token
     access_token = create_access_token(subject=user.username)
     refresh_token = create_refresh_token(subject=user.username)
-    
+
     return Token(
         access_token=access_token,
         refresh_token=refresh_token,
         token_type="bearer",
-        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
+        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
     )
 
+
 @router.get("/me", response_model=UserResponse)
 async def get_current_user_info(
-    current_user: UserInDB = Depends(get_current_active_user)
+    current_user: UserInDB = Depends(get_current_active_user),
 ) -> UserResponse:
     """
     获取当前登录用户信息
     """
     return UserResponse.model_validate(current_user)
 
+
 @router.post("/refresh", response_model=Token)
 async def refresh_token(
-    refresh_token: str,
-    user_repo: UserRepository = Depends(get_user_repository)
+    refresh_token: str, user_repo: UserRepository = Depends(get_user_repository)
 ) -> Token:
     """
     刷新 Access Token
-    
+
     使用 Refresh Token 获取新的 Access Token
     """
     from jose import jwt, JWTError
-    
+
     credentials_exception = HTTPException(
         status_code=status.HTTP_401_UNAUTHORIZED,
         detail="Could not validate refresh token",
         headers={"WWW-Authenticate": "Bearer"},
     )
-    
+
     try:
-        payload = jwt.decode(refresh_token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+        payload = jwt.decode(
+            refresh_token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM]
+        )
         username: str = payload.get("sub")
         token_type: str = payload.get("type")
-        
+
         if username is None or token_type != "refresh":
             raise credentials_exception
-        
+
     except JWTError:
         raise credentials_exception
-    
+
     # 验证用户仍然存在且激活
     user = await user_repo.get_user_by_username(username)
     if not user or not user.is_active:
         raise credentials_exception
-    
+
     # 生成新的 Access Token
     new_access_token = create_access_token(subject=user.username)
-    
+
     return Token(
         access_token=new_access_token,
         refresh_token=refresh_token,  # 保持原 refresh token
         token_type="bearer",
-        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
+        expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
     )

app/api/v1/endpoints/burst_detection.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
 from pydantic import BaseModel, Field
 
 from app.auth.keycloak_dependencies import get_current_keycloak_username
@@ -15,7 +15,8 @@ router = APIRouter()
 
 
 class BurstDetectionRequest(BaseModel):
-    network: str
+    """爆管检测请求模型"""
+    network: str = Field(..., description="管网名称（或数据库名称）")
     observed_pressure_data: (
         dict[str, list[Any]] | list[dict[str, Any]] | list[list[Any]] | None
     ) = Field(
@@ -26,45 +27,104 @@ class BurstDetectionRequest(BaseModel):
             "或二维数组 [[t1_s1, t1_s2], [t2_s1, t2_s2], ...]。"
         ),
     )
-    points_per_day: int = 1440
-    mu: int = 100
-    iforest_params: dict[str, Any] | None = None
-    scada_start: datetime | None = None
-    scada_end: datetime | None = None
-    sensor_nodes: list[str] | None = None
-    scheme_name: str | None = None
-    data_source: str = "monitoring"
-    simulation_scheme_name: str | None = None
-    simulation_scheme_type: str | None = None
+    points_per_day: int = Field(1440, description="每天的数据点数")
+    mu: int = Field(100, description="异常值检测的参数")
+    iforest_params: dict[str, Any] | None = Field(None, description="隔离森林算法参数")
+    scada_start: datetime | None = Field(None, description="SCADA数据起始时间")
+    scada_end: datetime | None = Field(None, description="SCADA数据结束时间")
+    sensor_nodes: list[str] | None = Field(None, description="传感器节点列表")
+    scheme_name: str | None = Field(None, description="方案名称")
+    data_source: str = Field("monitoring", description="数据来源：monitoring（监测）或simulation（模拟）")
+    simulation_scheme_name: str | None = Field(None, description="模拟方案名称")
+    simulation_scheme_type: str | None = Field(None, description="模拟方案类型")
 
 
-@router.post("/detect/")
+@router.post(
+    "/detect/",
+    summary="执行爆管检测",
+    description="基于压力观测数据和其他参数执行爆管检测分析"
+)
 async def detect_burst(
-    data: BurstDetectionRequest,
+    data: BurstDetectionRequest = Body(..., description="爆管检测请求数据"),
     username: str = Depends(get_current_keycloak_username),
 ) -> dict[str, Any]:
+    """
+    执行爆管检测分析。
+    
+    使用异常检测算法（隔离森林）识别压力时间序列中的异常，
+    将其作为潜在的爆管事件。
+    
+    Args:
+        data: 包含管网名称（或数据库名称）、压力数据及相关参数的请求体
+        username: 当前认证用户名
+        
+    Returns:
+        包含检测结果的字典
+        
+    Raises:
+        HTTPException: 当处理过程中发生错误时
+    """
     try:
         return run_burst_detection(**data.model_dump(), username=username)
     except Exception as exc:
         raise HTTPException(status_code=400, detail=str(exc))
 
 
-@router.get("/schemes/")
+@router.get(
+    "/schemes/",
+    summary="查询爆管检测方案列表",
+    description="获取指定网络的所有爆管检测方案"
+)
 async def query_burst_detection_schemes(
-    network: str,
-    query_date: datetime | None = None,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    query_date: datetime | None = Query(None, description="查询日期（可选）"),
 ) -> list[dict[str, Any]]:
+    """
+    获取爆管检测方案列表。
+    
+    查询指定网络的所有已配置的爆管检测方案，
+    可按日期进行筛选。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        query_date: 查询日期（可选）
+        
+    Returns:
+        爆管检测方案列表
+        
+    Raises:
+        HTTPException: 当查询失败时
+    """
     try:
         return list_burst_detection_schemes(network=network, query_date=query_date)
     except Exception as exc:
         raise HTTPException(status_code=400, detail=str(exc))
 
 
-@router.get("/schemes/{scheme_name}")
+@router.get(
+    "/schemes/{scheme_name}",
+    summary="获取爆管检测方案详情",
+    description="获取指定爆管检测方案的详细信息"
+)
 async def query_burst_detection_scheme_detail(
-    network: str,
-    scheme_name: str,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    scheme_name: str = Path(..., description="爆管检测方案名称"),
 ) -> dict[str, Any]:
+    """
+    获取爆管检测方案详情。
+    
+    查询指定爆管检测方案的完整配置和参数信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        scheme_name: 爆管检测方案名称
+        
+    Returns:
+        包含方案详情的字典
+        
+    Raises:
+        HTTPException: 当查询失败时
+    """
     try:
         return get_burst_detection_scheme_detail(network=network, scheme_name=scheme_name)
     except Exception as exc:

app/api/v1/endpoints/burst_location.py

@@ -3,8 +3,8 @@ from datetime import datetime
 
 from typing import Literal
 
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
+from pydantic import BaseModel, Field
 
 from app.auth.keycloak_dependencies import get_current_keycloak_username
 from app.services.burst_location import (
@@ -17,48 +17,112 @@ router = APIRouter()
 
 
 class BurstLocationRequest(BaseModel):
-    network: str
-    data_source: Literal["monitoring", "simulation"] = "monitoring"
-    pressure_scada_ids: list[str] | None = None
-    burst_pressure: dict[str, float] | list[dict[str, Any]] | None = None
-    normal_pressure: dict[str, float] | list[dict[str, Any]] | None = None
-    burst_leakage: float
-    flow_scada_ids: list[str] | None = None
-    burst_flow: dict[str, float] | list[dict[str, Any]] | None = None
-    normal_flow: dict[str, float] | list[dict[str, Any]] | None = None
-    min_dpressure: float = 2.0
-    basic_pressure: float = 10.0
-    scada_burst_start: datetime | None = None
-    scada_burst_end: datetime | None = None
-    use_scada_flow: bool = False
-    scheme_name: str | None = None
-    simulation_scheme_name: str | None = None
-    simulation_scheme_type: str | None = None
+    """爆管定位请求模型"""
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    data_source: Literal["monitoring", "simulation"] = Field("monitoring", description="数据来源：monitoring（监测）或simulation（模拟）")
+    pressure_scada_ids: list[str] | None = Field(None, description="压力SCADA传感器ID列表")
+    burst_pressure: dict[str, float] | list[dict[str, Any]] | None = Field(None, description="爆管时的压力数据")
+    normal_pressure: dict[str, float] | list[dict[str, Any]] | None = Field(None, description="正常时的压力数据")
+    burst_leakage: float = Field(..., description="爆管时的漏水量")
+    flow_scada_ids: list[str] | None = Field(None, description="流量SCADA传感器ID列表")
+    burst_flow: dict[str, float] | list[dict[str, Any]] | None = Field(None, description="爆管时的流量数据")
+    normal_flow: dict[str, float] | list[dict[str, Any]] | None = Field(None, description="正常时的流量数据")
+    min_dpressure: float = Field(2.0, description="最小压力差（bar）")
+    basic_pressure: float = Field(10.0, description="基准压力（bar）")
+    scada_burst_start: datetime | None = Field(None, description="SCADA爆管开始时间")
+    scada_burst_end: datetime | None = Field(None, description="SCADA爆管结束时间")
+    use_scada_flow: bool = Field(False, description="是否使用SCADA流量数据")
+    scheme_name: str | None = Field(None, description="方案名称")
+    simulation_scheme_name: str | None = Field(None, description="模拟方案名称")
+    simulation_scheme_type: str | None = Field(None, description="模拟方案类型")
 
 
-@router.post("/locate/")
+@router.post(
+    "/locate/",
+    summary="执行爆管定位",
+    description="基于压力和流量数据定位管网中的爆管位置"
+)
 async def locate_burst(
-    data: BurstLocationRequest,
+    data: BurstLocationRequest = Body(..., description="爆管定位请求数据"),
     username: str = Depends(get_current_keycloak_username),
 ) -> dict[str, Any]:
+    """
+    执行爆管定位分析。
+    
+    使用压力和流量SCADA数据，通过对比爆管和正常状态下的数据差异，
+    定位管网中的爆管位置。
+    
+    Args:
+        data: 包含管网名称（或数据库名称）、压力、流量数据及相关参数的请求体
+        username: 当前认证用户名
+        
+    Returns:
+        包含定位结果的字典
+        
+    Raises:
+        HTTPException: 当数据类型或值不正确时
+    """
     try:
         return run_burst_location_by_network(**data.model_dump(), username=username)
     except (TypeError, ValueError) as exc:
         raise HTTPException(status_code=400, detail=str(exc))
 
 
-@router.get("/schemes/")
+@router.get(
+    "/schemes/",
+    summary="查询爆管定位方案列表",
+    description="获取指定网络的所有爆管定位方案"
+)
 async def query_burst_schemes(
-    network: str, query_date: datetime | None = None
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    query_date: datetime | None = Query(None, description="查询日期（可选）")
 ) -> list[dict[str, Any]]:
+    """
+    获取爆管定位方案列表。
+    
+    查询指定网络的所有已配置的爆管定位方案，
+    可按日期进行筛选。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        query_date: 查询日期（可选）
+        
+    Returns:
+        爆管定位方案列表
+        
+    Raises:
+        HTTPException: 当查询失败时
+    """
     try:
         return list_burst_location_schemes(network=network, query_date=query_date)
     except Exception as exc:
         raise HTTPException(status_code=400, detail=str(exc))
 
 
-@router.get("/schemes/{scheme_name}")
-async def query_burst_scheme_detail(network: str, scheme_name: str) -> dict[str, Any]:
+@router.get(
+    "/schemes/{scheme_name}",
+    summary="获取爆管定位方案详情",
+    description="获取指定爆管定位方案的详细信息"
+)
+async def query_burst_scheme_detail(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    scheme_name: str = Path(..., description="爆管定位方案名称")
+) -> dict[str, Any]:
+    """
+    获取爆管定位方案详情。
+    
+    查询指定爆管定位方案的完整配置和参数信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        scheme_name: 爆管定位方案名称
+        
+    Returns:
+        包含方案详情的字典
+        
+    Raises:
+        HTTPException: 当查询失败时
+    """
     try:
         return get_burst_location_scheme_detail(network=network, scheme_name=scheme_name)
     except Exception as exc:

app/api/v1/endpoints/cache.py

@@ -1,16 +1,26 @@
-from fastapi import APIRouter
+from fastapi import APIRouter, Query
 from app.infra.cache.redis_client import redis_client
 
 router = APIRouter()
 
-@router.post("/clearrediskey/")
-async def fastapi_clear_redis_key(key: str):
+@router.post("/clearrediskey/", summary="清除单个缓存键", description="根据键名清除单个Redis缓存")
+async def fastapi_clear_redis_key(key: str = Query(..., description="缓存键名")):
+    """
+    清除单个缓存键
+    
+    根据指定的键名删除Redis中对应的缓存
+    """
     redis_client.delete(key)
     return True
 
 
-@router.post("/clearrediskeys/")
-async def fastapi_clear_redis_keys(keys: str):
+@router.post("/clearrediskeys/", summary="清除匹配的缓存键", description="根据模式清除匹配的Redis缓存键")
+async def fastapi_clear_redis_keys(keys: str = Query(..., description="缓存键模式（支持通配符）")):
+    """
+    清除匹配的缓存键
+    
+    根据指定的模式删除Redis中所有匹配的缓存键
+    """
     # delete keys contains the key
     matched_keys = redis_client.keys(f"*{keys}*")
     if matched_keys:
@@ -19,14 +29,24 @@ async def fastapi_clear_redis_keys(keys: str):
     return True
 
 
-@router.post("/clearallredis/")
+@router.post("/clearallredis/", summary="清除所有缓存", description="清空整个Redis数据库的所有缓存")
 async def fastapi_clear_all_redis():
+    """
+    清除所有缓存
+    
+    清空Redis数据库中的所有缓存键值对
+    """
     redis_client.flushdb()
     return True
 
 
-@router.get("/queryredis/")
+@router.get("/queryredis/", summary="查询缓存键列表", description="获取Redis中所有的缓存键")
 async def fastapi_query_redis():
+    """
+    查询缓存键列表
+    
+    获取Redis数据库中所有的缓存键列表
+    """
     # Helper to decode bytes to str for JSON response if needed, 
     # but original just returned keys (which might be bytes in redis-py unless decode_responses=True)
     # create_redis_client usually sets decode_responses=False by default.

app/api/v1/endpoints/components/controls.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -13,28 +13,58 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getcontrolschema/")
-async def fastapi_get_control_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getcontrolschema/", summary="获取控制架构", description="获取网络中控制对象的架构定义")
+async def fastapi_get_control_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取控制架构。
+    
+    返回指定网络中控制对象的属性架构定义。
+    """
     return get_control_schema(network)
 
-@router.get("/getcontrolproperties/")
-async def fastapi_get_control_properties(network: str) -> dict[str, Any]:
+@router.get("/getcontrolproperties/", summary="获取控制属性", description="获取指定网络中的控制属性信息")
+async def fastapi_get_control_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取控制属性。
+    
+    返回指定网络中的控制对象属性信息。
+    """
     return get_control(network)
 
-@router.post("/setcontrolproperties/", response_model=None)
-async def fastapi_set_control_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setcontrolproperties/", response_model=None, summary="设置控制属性", description="更新指定网络中的控制属性")
+async def fastapi_set_control_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置控制属性。
+    
+    更新指定网络中的控制属性值。
+    """
     props = await req.json()
     return set_control(network, ChangeSet(props))
 
-@router.get("/getruleschema/")
-async def fastapi_get_rule_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getruleschema/", summary="获取规则架构", description="获取网络中规则对象的架构定义")
+async def fastapi_get_rule_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取规则架构。
+    
+    返回指定网络中规则对象的属性架构定义。
+    """
     return get_rule_schema(network)
 
-@router.get("/getruleproperties/")
-async def fastapi_get_rule_properties(network: str) -> dict[str, Any]:
+@router.get("/getruleproperties/", summary="获取规则属性", description="获取指定网络中的规则属性信息")
+async def fastapi_get_rule_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取规则属性。
+    
+    返回指定网络中的规则对象属性信息。
+    """
     return get_rule(network)
 
-@router.post("/setruleproperties/", response_model=None)
-async def fastapi_set_rule_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setruleproperties/", response_model=None, summary="设置规则属性", description="更新指定网络中的规则属性")
+async def fastapi_set_rule_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置规则属性。
+    
+    更新指定网络中的规则属性值。
+    """
     props = await req.json()
     return set_rule(network, ChangeSet(props))

app/api/v1/endpoints/components/curves.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -14,39 +14,82 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getcurveschema")
-async def fastapi_get_curve_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getcurveschema", summary="获取曲线架构", description="获取网络中曲线对象的架构定义")
+async def fastapi_get_curve_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取曲线架构。
+    
+    返回指定网络中曲线对象的属性架构定义。
+    """
     return get_curve_schema(network)
 
-@router.post("/addcurve/", response_model=None)
-async def fastapi_add_curve(network: str, curve: str, req: Request) -> ChangeSet:
+@router.post("/addcurve/", response_model=None, summary="添加曲线", description="在网络中添加一条新的曲线")
+async def fastapi_add_curve(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    curve: str = Query(..., description="曲线ID"),
+    req: Request = None
+) -> ChangeSet:
+    """添加曲线。
+    
+    在指定网络中创建一条新的曲线，并设置其初始属性。
+    """
     props = await req.json()
     ps = {
         "id": curve,
     } | props
     return add_curve(network, ChangeSet(ps))
 
-@router.post("/deletecurve/", response_model=None)
-async def fastapi_delete_curve(network: str, curve: str) -> ChangeSet:
+@router.post("/deletecurve/", response_model=None, summary="删除曲线", description="从网络中删除指定的曲线")
+async def fastapi_delete_curve(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    curve: str = Query(..., description="曲线ID")
+) -> ChangeSet:
+    """删除曲线。
+    
+    从指定网络中删除指定的曲线及其相关数据。
+    """
     ps = {"id": curve}
     return delete_curve(network, ChangeSet(ps))
 
-@router.get("/getcurveproperties/")
-async def fastapi_get_curve_properties(network: str, curve: str) -> dict[str, Any]:
+@router.get("/getcurveproperties/", summary="获取曲线属性", description="获取指定曲线的属性信息")
+async def fastapi_get_curve_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    curve: str = Query(..., description="曲线ID")
+) -> dict[str, Any]:
+    """获取曲线属性。
+    
+    返回指定曲线的所有属性信息。
+    """
     return get_curve(network, curve)
 
-@router.post("/setcurveproperties/", response_model=None)
+@router.post("/setcurveproperties/", response_model=None, summary="设置曲线属性", description="更新指定曲线的属性")
 async def fastapi_set_curve_properties(
-    network: str, curve: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    curve: str = Query(..., description="曲线ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """设置曲线属性。
+    
+    更新指定曲线的属性值。
+    """
     props = await req.json()
     ps = {"id": curve} | props
     return set_curve(network, ChangeSet(ps))
 
-@router.get("/getcurves/")
-async def fastapi_get_curves(network: str) -> list[str]:
+@router.get("/getcurves/", summary="获取所有曲线", description="获取网络中的所有曲线列表")
+async def fastapi_get_curves(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[str]:
+    """获取所有曲线。
+    
+    返回指定网络中的所有曲线ID列表。
+    """
     return get_curves(network)
 
-@router.get("/iscurve/")
-async def fastapi_is_curve(network: str, curve: str) -> bool:
+@router.get("/iscurve/", summary="检查曲线存在性", description="检查指定的曲线是否存在")
+async def fastapi_is_curve(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    curve: str = Query(..., description="曲线ID")
+) -> bool:
+    """检查曲线是否存在。
+    
+    判断指定的曲线是否在网络中存在。
+    """
     return is_curve(network, curve)

app/api/v1/endpoints/components/options.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -19,57 +19,119 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/gettimeschema")
-async def fastapi_get_time_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/gettimeschema", summary="获取时间选项架构", description="获取网络中时间选项的架构定义")
+async def fastapi_get_time_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取时间选项架构。
+    
+    返回指定网络中时间相关选项的属性架构定义。
+    """
     return get_time_schema(network)
 
-@router.get("/gettimeproperties/")
-async def fastapi_get_time_properties(network: str) -> dict[str, Any]:
+@router.get("/gettimeproperties/", summary="获取时间选项属性", description="获取指定网络中的时间选项属性信息")
+async def fastapi_get_time_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取时间选项属性。
+    
+    返回指定网络中的时间相关选项属性。
+    """
     return get_time(network)
 
-@router.post("/settimeproperties/", response_model=None)
-async def fastapi_set_time_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/settimeproperties/", response_model=None, summary="设置时间选项属性", description="更新指定网络中的时间选项属性")
+async def fastapi_set_time_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置时间选项属性。
+    
+    更新指定网络中的时间相关选项属性值。
+    """
     props = await req.json()
     return set_time(network, ChangeSet(props))
 
-@router.get("/getenergyschema/")
-async def fastapi_get_energy_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getenergyschema/", summary="获取能耗选项架构", description="获取网络中能耗选项的架构定义")
+async def fastapi_get_energy_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取能耗选项架构。
+    
+    返回指定网络中能耗相关选项的属性架构定义。
+    """
     return get_energy_schema(network)
 
-@router.get("/getenergyproperties/")
-async def fastapi_get_energy_properties(network: str) -> dict[str, Any]:
+@router.get("/getenergyproperties/", summary="获取能耗选项属性", description="获取指定网络中的能耗选项属性信息")
+async def fastapi_get_energy_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取能耗选项属性。
+    
+    返回指定网络中的能耗相关选项属性。
+    """
     return get_energy(network)
 
-@router.post("/setenergyproperties/", response_model=None)
-async def fastapi_set_energy_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setenergyproperties/", response_model=None, summary="设置能耗选项属性", description="更新指定网络中的能耗选项属性")
+async def fastapi_set_energy_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置能耗选项属性。
+    
+    更新指定网络中的能耗相关选项属性值。
+    """
     props = await req.json()
     return set_energy(network, ChangeSet(props))
 
-@router.get("/getpumpenergyschema/")
-async def fastapi_get_pump_energy_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getpumpenergyschema/", summary="获取泵能耗选项架构", description="获取网络中泵能耗选项的架构定义")
+async def fastapi_get_pump_energy_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取泵能耗选项架构。
+    
+    返回指定网络中泵能耗相关选项的属性架构定义。
+    """
     return get_pump_energy_schema(network)
 
-@router.get("/getpumpenergyproperties//")
-async def fastapi_get_pump_energy_proeprties(network: str, pump: str) -> dict[str, Any]:
+@router.get("/getpumpenergyproperties//", summary="获取泵能耗属性", description="获取指定泵的能耗属性信息")
+async def fastapi_get_pump_energy_proeprties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="泵ID")
+) -> dict[str, Any]:
+    """获取泵能耗属性。
+    
+    返回指定泵的能耗相关属性。
+    """
     return get_pump_energy(network, pump)
 
-@router.get("/setpumpenergyproperties//", response_model=None)
+@router.get("/setpumpenergyproperties//", response_model=None, summary="设置泵能耗属性", description="更新指定泵的能耗属性")
 async def fastapi_set_pump_energy_properties(
-    network: str, pump: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="泵ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """设置泵能耗属性。
+    
+    更新指定泵的能耗相关属性值。
+    """
     props = await req.json()
     ps = {"id": pump} | props
     return set_pump_energy(network, ChangeSet(ps))
 
-@router.get("/getoptionschema/")
-async def fastapi_get_option_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getoptionschema/", summary="获取选项架构", description="获取网络中选项对象的架构定义")
+async def fastapi_get_option_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取选项架构。
+    
+    返回指定网络中选项对象的属性架构定义。
+    """
     return get_option_v3_schema(network)
 
-@router.get("/getoptionproperties/")
-async def fastapi_get_option_properties(network: str) -> dict[str, Any]:
+@router.get("/getoptionproperties/", summary="获取选项属性", description="获取指定网络中的选项属性信息")
+async def fastapi_get_option_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取选项属性。
+    
+    返回指定网络中的选项对象属性信息。
+    """
     return get_option_v3(network)
 
-@router.post("/setoptionproperties/", response_model=None)
-async def fastapi_set_option_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setoptionproperties/", response_model=None, summary="设置选项属性", description="更新指定网络中的选项属性")
+async def fastapi_set_option_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置选项属性。
+    
+    更新指定网络中的选项属性值。
+    """
     props = await req.json()
     return set_option_v3(network, ChangeSet(props))

app/api/v1/endpoints/components/patterns.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -14,39 +14,82 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getpatternschema")
-async def fastapi_get_pattern_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getpatternschema", summary="获取模式架构", description="获取网络中模式对象的架构定义")
+async def fastapi_get_pattern_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取模式架构。
+    
+    返回指定网络中模式对象的属性架构定义。
+    """
     return get_pattern_schema(network)
 
-@router.post("/addpattern/", response_model=None)
-async def fastapi_add_pattern(network: str, pattern: str, req: Request) -> ChangeSet:
+@router.post("/addpattern/", response_model=None, summary="添加模式", description="在网络中添加一个新的模式")
+async def fastapi_add_pattern(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pattern: str = Query(..., description="模式ID"),
+    req: Request = None
+) -> ChangeSet:
+    """添加模式。
+    
+    在指定网络中创建一个新的模式，并设置其初始属性。
+    """
     props = await req.json()
     ps = {
         "id": pattern,
     } | props
     return add_pattern(network, ChangeSet(ps))
 
-@router.post("/deletepattern/", response_model=None)
-async def fastapi_delete_pattern(network: str, pattern: str) -> ChangeSet:
+@router.post("/deletepattern/", response_model=None, summary="删除模式", description="从网络中删除指定的模式")
+async def fastapi_delete_pattern(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pattern: str = Query(..., description="模式ID")
+) -> ChangeSet:
+    """删除模式。
+    
+    从指定网络中删除指定的模式及其相关数据。
+    """
     ps = {"id": pattern}
     return delete_pattern(network, ChangeSet(ps))
 
-@router.get("/getpatternproperties/")
-async def fastapi_get_pattern_properties(network: str, pattern: str) -> dict[str, Any]:
+@router.get("/getpatternproperties/", summary="获取模式属性", description="获取指定模式的属性信息")
+async def fastapi_get_pattern_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pattern: str = Query(..., description="模式ID")
+) -> dict[str, Any]:
+    """获取模式属性。
+    
+    返回指定模式的所有属性信息。
+    """
     return get_pattern(network, pattern)
 
-@router.post("/setpatternproperties/", response_model=None)
+@router.post("/setpatternproperties/", response_model=None, summary="设置模式属性", description="更新指定模式的属性")
 async def fastapi_set_pattern_properties(
-    network: str, pattern: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pattern: str = Query(..., description="模式ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """设置模式属性。
+    
+    更新指定模式的属性值。
+    """
     props = await req.json()
     ps = {"id": pattern} | props
     return set_pattern(network, ChangeSet(ps))
 
-@router.get("/ispattern/")
-async def fastapi_is_pattern(network: str, pattern: str) -> bool:
+@router.get("/ispattern/", summary="检查模式存在性", description="检查指定的模式是否存在")
+async def fastapi_is_pattern(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pattern: str = Query(..., description="模式ID")
+) -> bool:
+    """检查模式是否存在。
+    
+    判断指定的模式是否在网络中存在。
+    """
     return is_pattern(network, pattern)
 
-@router.get("/getpatterns/")
-async def fastapi_get_patterns(network: str) -> list[str]:
+@router.get("/getpatterns/", summary="获取所有模式", description="获取网络中的所有模式列表")
+async def fastapi_get_patterns(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[str]:
+    """获取所有模式。
+    
+    返回指定网络中的所有模式ID列表。
+    """
     return get_patterns(network)

app/api/v1/endpoints/components/quality.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -32,116 +32,266 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getqualityschema/")
-async def fastapi_get_quality_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getqualityschema/", summary="获取水质架构", description="获取网络中水质对象的架构定义")
+async def fastapi_get_quality_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取水质架构。
+    
+    返回指定网络中水质对象的属性架构定义。
+    """
     return get_quality_schema(network)
 
-@router.get("/getqualityproperties/")
-async def fastapi_get_quality_properties(network: str, node: str) -> dict[str, Any]:
+@router.get("/getqualityproperties/", summary="获取水质属性", description="获取指定节点的水质属性信息")
+async def fastapi_get_quality_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> dict[str, Any]:
+    """获取水质属性。
+    
+    返回指定节点的水质属性信息。
+    """
     return get_quality(network, node)
 
-@router.post("/setqualityproperties/", response_model=None)
-async def fastapi_set_quality_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setqualityproperties/", response_model=None, summary="设置水质属性", description="更新指定节点的水质属性")
+async def fastapi_set_quality_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置水质属性。
+    
+    更新指定节点的水质属性值。
+    """
     props = await req.json()
     return set_quality(network, ChangeSet(props))
 
-@router.get("/getemitterschema")
-async def fastapi_get_emitter_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getemitterschema", summary="获取发射器架构", description="获取网络中发射器对象的架构定义")
+async def fastapi_get_emitter_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取发射器架构。
+    
+    返回指定网络中发射器对象的属性架构定义。
+    """
     return get_emitter_schema(network)
 
-@router.get("/getemitterproperties/")
-async def fastapi_get_emitter_properties(network: str, junction: str) -> dict[str, Any]:
+@router.get("/getemitterproperties/", summary="获取发射器属性", description="获取指定连接点的发射器属性信息")
+async def fastapi_get_emitter_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="连接点ID")
+) -> dict[str, Any]:
+    """获取发射器属性。
+    
+    返回指定连接点的发射器属性信息。
+    """
     return get_emitter(network, junction)
 
-@router.post("/setemitterproperties/", response_model=None)
+@router.post("/setemitterproperties/", response_model=None, summary="设置发射器属性", description="更新指定连接点的发射器属性")
 async def fastapi_set_emitter_properties(
-    network: str, junction: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="连接点ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """设置发射器属性。
+    
+    更新指定连接点的发射器属性值。
+    """
     props = await req.json()
     ps = {"junction": junction} | props
     return set_emitter(network, ChangeSet(ps))
 
-@router.get("/getsourcechema/")
-async def fastapi_get_source_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getsourcechema/", summary="获取水源架构", description="获取网络中水源对象的架构定义")
+async def fastapi_get_source_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取水源架构。
+    
+    返回指定网络中水源对象的属性架构定义。
+    """
     return get_source_schema(network)
 
-@router.get("/getsource/")
-async def fastapi_get_source(network: str, node: str) -> dict[str, Any]:
+@router.get("/getsource/", summary="获取水源属性", description="获取指定节点的水源属性信息")
+async def fastapi_get_source(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> dict[str, Any]:
+    """获取水源属性。
+    
+    返回指定节点的水源属性信息。
+    """
     return get_source(network, node)
 
-@router.post("/setsource/", response_model=None)
-async def fastapi_set_source(network: str, req: Request) -> ChangeSet:
+@router.post("/setsource/", response_model=None, summary="设置水源属性", description="更新指定节点的水源属性")
+async def fastapi_set_source(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置水源属性。
+    
+    更新指定节点的水源属性值。
+    """
     props = await req.json()
     return set_source(network, ChangeSet(props))
 
-@router.post("/addsource/", response_model=None)
-async def fastapi_add_source(network: str, req: Request) -> ChangeSet:
+@router.post("/addsource/", response_model=None, summary="添加水源", description="在网络中添加一个新的水源")
+async def fastapi_add_source(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加水源。
+    
+    在指定网络中创建一个新的水源，并设置其初始属性。
+    """
     props = await req.json()
     return add_source(network, ChangeSet(props))
 
-@router.post("/deletesource/", response_model=None)
-async def fastapi_delete_source(network: str, node: str) -> ChangeSet:
+@router.post("/deletesource/", response_model=None, summary="删除水源", description="从网络中删除指定节点的水源")
+async def fastapi_delete_source(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> ChangeSet:
+    """删除水源。
+    
+    从指定网络中删除指定节点的水源。
+    """
     props = {"node": node}
     return delete_source(network, ChangeSet(props))
 
-@router.get("/getreactionschema/")
-async def fastapi_get_reaction_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getreactionschema/", summary="获取反应架构", description="获取网络中反应对象的架构定义")
+async def fastapi_get_reaction_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取反应架构。
+    
+    返回指定网络中反应对象的属性架构定义。
+    """
     return get_reaction_schema(network)
 
-@router.get("/getreaction/")
-async def fastapi_get_reaction(network: str) -> dict[str, Any]:
+@router.get("/getreaction/", summary="获取反应属性", description="获取指定网络中的反应属性信息")
+async def fastapi_get_reaction(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取反应属性。
+    
+    返回指定网络中的反应属性信息。
+    """
     return get_reaction(network)
 
-@router.post("/setreaction/", response_model=None)
-async def fastapi_set_reaction(network: str, req: Request) -> ChangeSet:
+@router.post("/setreaction/", response_model=None, summary="设置反应属性", description="更新指定网络中的反应属性")
+async def fastapi_set_reaction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置反应属性。
+    
+    更新指定网络中的反应属性值。
+    """
     props = await req.json()
     return set_reaction(network, ChangeSet(props))
 
-@router.get("/getpipereactionschema/")
-async def fastapi_get_pipe_reaction_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getpipereactionschema/", summary="获取管道反应架构", description="获取网络中管道反应对象的架构定义")
+async def fastapi_get_pipe_reaction_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取管道反应架构。
+    
+    返回指定网络中管道反应对象的属性架构定义。
+    """
     return get_pipe_reaction_schema(network)
 
-@router.get("/getpipereaction/")
-async def fastapi_get_pipe_reaction(network: str, pipe: str) -> dict[str, Any]:
+@router.get("/getpipereaction/", summary="获取管道反应属性", description="获取指定管道的反应属性信息")
+async def fastapi_get_pipe_reaction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> dict[str, Any]:
+    """获取管道反应属性。
+    
+    返回指定管道的反应属性信息。
+    """
     return get_pipe_reaction(network, pipe)
 
-@router.post("/setpipereaction/", response_model=None)
-async def fastapi_set_pipe_reaction(network: str, req: Request) -> ChangeSet:
+@router.post("/setpipereaction/", response_model=None, summary="设置管道反应属性", description="更新指定管道的反应属性")
+async def fastapi_set_pipe_reaction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置管道反应属性。
+    
+    更新指定管道的反应属性值。
+    """
     props = await req.json()
     return set_pipe_reaction(network, ChangeSet(props))
 
-@router.get("/gettankreactionschema/")
-async def fastapi_get_tank_reaction_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/gettankreactionschema/", summary="获取水池反应架构", description="获取网络中水池反应对象的架构定义")
+async def fastapi_get_tank_reaction_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取水池反应架构。
+    
+    返回指定网络中水池反应对象的属性架构定义。
+    """
     return get_tank_reaction_schema(network)
 
-@router.get("/gettankreaction/")
-async def fastapi_get_tank_reaction(network: str, tank: str) -> dict[str, Any]:
+@router.get("/gettankreaction/", summary="获取水池反应属性", description="获取指定水池的反应属性信息")
+async def fastapi_get_tank_reaction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水池ID")
+) -> dict[str, Any]:
+    """获取水池反应属性。
+    
+    返回指定水池的反应属性信息。
+    """
     return get_tank_reaction(network, tank)
 
-@router.post("/settankreaction/", response_model=None)
-async def fastapi_set_tank_reaction(network: str, req: Request) -> ChangeSet:
+@router.post("/settankreaction/", response_model=None, summary="设置水池反应属性", description="更新指定水池的反应属性")
+async def fastapi_set_tank_reaction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置水池反应属性。
+    
+    更新指定水池的反应属性值。
+    """
     props = await req.json()
     return set_tank_reaction(network, ChangeSet(props))
 
-@router.get("/getmixingschema/")
-async def fastapi_get_mixing_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getmixingschema/", summary="获取混合架构", description="获取网络中混合对象的架构定义")
+async def fastapi_get_mixing_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取混合架构。
+    
+    返回指定网络中混合对象的属性架构定义。
+    """
     return get_mixing_schema(network)
 
-@router.get("/getmixing/")
-async def fastapi_get_mixing(network: str, tank: str) -> dict[str, Any]:
+@router.get("/getmixing/", summary="获取混合属性", description="获取指定水池的混合属性信息")
+async def fastapi_get_mixing(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水池ID")
+) -> dict[str, Any]:
+    """获取混合属性。
+    
+    返回指定水池的混合属性信息。
+    """
     return get_mixing(network, tank)
 
-@router.post("/setmixing/", response_model=None)
-async def fastapi_set_mixing(network: str, req: Request) -> ChangeSet:
+@router.post("/setmixing/", response_model=None, summary="设置混合属性", description="更新指定水池的混合属性")
+async def fastapi_set_mixing(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置混合属性。
+    
+    更新指定水池的混合属性值。
+    """
     props = await req.json()
     return api.set_mixing(network, ChangeSet(props))
 
-@router.post("/addmixing/", response_model=None)
-async def fastapi_add_mixing(network: str, req: Request) -> ChangeSet:
+@router.post("/addmixing/", response_model=None, summary="添加混合", description="在网络中添加一个新的混合")
+async def fastapi_add_mixing(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加混合。
+    
+    在指定网络中创建一个新的混合，并设置其初始属性。
+    """
     props = await req.json()
     return add_mixing(network, ChangeSet(props))
 
-@router.post("/deletemixing/", response_model=None)
-async def fastapi_delete_mixing(network: str, req: Request) -> ChangeSet:
+@router.post("/deletemixing/", response_model=None, summary="删除混合", description="从网络中删除指定的混合")
+async def fastapi_delete_mixing(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """删除混合。
+    
+    从指定网络中删除指定的混合及其相关数据。
+    """
     props = await req.json()
     return delete_mixing(network, ChangeSet(props))

app/api/v1/endpoints/components/visuals.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request, Response
+from fastapi import APIRouter, Request, Query, Path, Body, Response
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -24,71 +24,157 @@ import json
 
 router = APIRouter()
 
-@router.get("/getvertexschema/")
-async def fastapi_get_vertex_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getvertexschema/", summary="获取图形元素架构", description="获取网络中图形元素对象的架构定义")
+async def fastapi_get_vertex_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取图形元素架构。
+    
+    返回指定网络中图形元素对象的属性架构定义。
+    """
     return get_vertex_schema(network)
 
-@router.get("/getvertexproperties/")
-async def fastapi_get_vertex_properties(network: str, link: str) -> dict[str, Any]:
+@router.get("/getvertexproperties/", summary="获取图形元素属性", description="获取指定图形元素的属性信息")
+async def fastapi_get_vertex_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="图形元素链接")
+) -> dict[str, Any]:
+    """获取图形元素属性。
+    
+    返回指定图形元素的所有属性信息。
+    """
     return get_vertex(network, link)
 
-@router.post("/setvertexproperties/", response_model=None)
-async def fastapi_set_vertex_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setvertexproperties/", response_model=None, summary="设置图形元素属性", description="更新指定图形元素的属性")
+async def fastapi_set_vertex_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置图形元素属性。
+    
+    更新指定图形元素的属性值。
+    """
     props = await req.json()
     return set_vertex(network, ChangeSet(props))
 
-@router.post("/addvertex/", response_model=None)
-async def fastapi_add_vertex(network: str, req: Request) -> ChangeSet:
+@router.post("/addvertex/", response_model=None, summary="添加图形元素", description="在网络中添加一个新的图形元素")
+async def fastapi_add_vertex(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加图形元素。
+    
+    在指定网络中创建一个新的图形元素，并设置其初始属性。
+    """
     props = await req.json()
     return add_vertex(network, ChangeSet(props))
 
-@router.post("/deletevertex/", response_model=None)
-async def fastapi_delete_vertex(network: str, req: Request) -> ChangeSet:
+@router.post("/deletevertex/", response_model=None, summary="删除图形元素", description="从网络中删除指定的图形元素")
+async def fastapi_delete_vertex(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """删除图形元素。
+    
+    从指定网络中删除指定的图形元素及其相关数据。
+    """
     props = await req.json()
     return delete_vertex(network, ChangeSet(props))
 
-@router.get("/getallvertexlinks/", response_class=PlainTextResponse)
-async def fastapi_get_all_vertex_links(network: str) -> list[str]:
+@router.get("/getallvertexlinks/", response_class=PlainTextResponse, summary="获取所有图形元素链接", description="获取网络中的所有图形元素链接列表")
+async def fastapi_get_all_vertex_links(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[str]:
+    """获取所有图形元素链接。
+    
+    返回指定网络中的所有图形元素链接列表。
+    """
     return json.dumps(get_all_vertex_links(network))
 
-@router.get("/getallvertices/", response_class=PlainTextResponse)
-async def fastapi_get_all_vertices(network: str) -> list[dict[str, Any]]:
+@router.get("/getallvertices/", response_class=PlainTextResponse, summary="获取所有图形元素", description="获取网络中的所有图形元素详细信息")
+async def fastapi_get_all_vertices(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[dict[str, Any]]:
+    """获取所有图形元素。
+    
+    返回指定网络中的所有图形元素详细信息。
+    """
     return json.dumps(get_all_vertices(network))
 
-@router.get("/getlabelschema/")
-async def fastapi_get_label_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getlabelschema/", summary="获取标签架构", description="获取网络中标签对象的架构定义")
+async def fastapi_get_label_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取标签架构。
+    
+    返回指定网络中标签对象的属性架构定义。
+    """
     return get_label_schema(network)
 
-@router.get("/getlabelproperties/")
+@router.get("/getlabelproperties/", summary="获取标签属性", description="获取指定坐标处的标签属性信息")
 async def fastapi_get_label_properties(
-    network: str, x: float, y: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    x: float = Query(..., description="X坐标"),
+    y: float = Query(..., description="Y坐标")
 ) -> dict[str, Any]:
+    """获取标签属性。
+    
+    返回指定坐标处的标签属性信息。
+    """
     return get_label(network, x, y)
 
-@router.post("/setlabelproperties/", response_model=None)
-async def fastapi_set_label_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setlabelproperties/", response_model=None, summary="设置标签属性", description="更新指定标签的属性")
+async def fastapi_set_label_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置标签属性。
+    
+    更新指定标签的属性值。
+    """
     props = await req.json()
     return set_label(network, ChangeSet(props))
 
-@router.post("/addlabel/", response_model=None)
-async def fastapi_add_label(network: str, req: Request) -> ChangeSet:
+@router.post("/addlabel/", response_model=None, summary="添加标签", description="在网络中添加一个新的标签")
+async def fastapi_add_label(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加标签。
+    
+    在指定网络中创建一个新的标签，并设置其初始属性。
+    """
     props = await req.json()
     return add_label(network, ChangeSet(props))
 
-@router.post("/deletelabel/", response_model=None)
-async def fastapi_delete_label(network: str, req: Request) -> ChangeSet:
+@router.post("/deletelabel/", response_model=None, summary="删除标签", description="从网络中删除指定的标签")
+async def fastapi_delete_label(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """删除标签。
+    
+    从指定网络中删除指定的标签及其相关数据。
+    """
     props = await req.json()
     return delete_label(network, ChangeSet(props))
 
-@router.get("/getbackdropschema/")
-async def fastapi_get_backdrop_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getbackdropschema/", summary="获取背景架构", description="获取网络中背景对象的架构定义")
+async def fastapi_get_backdrop_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取背景架构。
+    
+    返回指定网络中背景对象的属性架构定义。
+    """
     return get_backdrop_schema(network)
 
-@router.get("/getbackdropproperties/")
-async def fastapi_get_backdrop_properties(network: str) -> dict[str, Any]:
+@router.get("/getbackdropproperties/", summary="获取背景属性", description="获取指定网络的背景属性信息")
+async def fastapi_get_backdrop_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取背景属性。
+    
+    返回指定网络的背景属性信息。
+    """
     return get_backdrop(network)
 
-@router.post("/setbackdropproperties/", response_model=None)
-async def fastapi_set_backdrop_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setbackdropproperties/", response_model=None, summary="设置背景属性", description="更新指定网络的背景属性")
+async def fastapi_set_backdrop_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置背景属性。
+    
+    更新指定网络的背景属性值。
+    """
     props = await req.json()
     return set_backdrop(network, ChangeSet(props))

app/api/v1/endpoints/extension.py

@@ -1,5 +1,5 @@
 from typing import List, Any
-from fastapi import APIRouter, Request, HTTPException
+from fastapi import APIRouter, Request, HTTPException, Query, Body
 from app.services.tjnetwork import (
     ChangeSet,
     get_all_extension_data_keys,
@@ -10,20 +10,93 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getallextensiondatakeys/")
-async def get_all_extension_data_keys_endpoint(network: str) -> list[str]:
+@router.get(
+    "/getallextensiondatakeys/",
+    summary="获取所有扩展数据键",
+    description="获取指定网络的所有扩展数据的键列表"
+)
+async def get_all_extension_data_keys_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[str]:
+    """
+    获取所有扩展数据键。
+    
+    返回指定网络中所有可用的扩展数据键。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        扩展数据键列表
+    """
     return get_all_extension_data_keys(network)
 
-@router.get("/getallextensiondata/")
-async def get_all_extension_data_endpoint(network: str) -> dict[str, Any]:
+@router.get(
+    "/getallextensiondata/",
+    summary="获取所有扩展数据",
+    description="获取指定网络的所有扩展数据"
+)
+async def get_all_extension_data_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, Any]:
+    """
+    获取所有扩展数据。
+    
+    返回指定网络的所有扩展数据及其值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        扩展数据字典
+    """
     return get_all_extension_data(network)
 
-@router.get("/getextensiondata/")
-async def get_extension_data_endpoint(network: str, key: str) -> str | None:
+@router.get(
+    "/getextensiondata/",
+    summary="获取指定扩展数据",
+    description="获取指定网络中指定键的扩展数据值"
+)
+async def get_extension_data_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    key: str = Query(..., description="扩展数据键")
+) -> str | None:
+    """
+    获取指定扩展数据。
+    
+    返回指定网络中指定键对应的扩展数据值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        key: 扩展数据键
+        
+    Returns:
+        扩展数据值，如果不存在返回None
+    """
     return get_extension_data(network, key)
 
-@router.post("/setextensiondata/", response_model=None)
-async def set_extension_data_endpoint(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/setextensiondata/",
+    response_model=None,
+    summary="设置扩展数据",
+    description="设置指定网络中的扩展数据"
+)
+async def set_extension_data_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    设置扩展数据。
+    
+    在指定网络中设置扩展数据，并返回变更集信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 包含扩展数据的请求体
+        
+    Returns:
+        变更集信息
+    """
     props = await req.json()
     print(props)
     cs = set_extension_data(network, ChangeSet(props))

app/api/v1/endpoints/leakage.py

@@ -2,8 +2,8 @@ import os
 from typing import Any
 from datetime import datetime
 
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
+from pydantic import BaseModel, Field
 
 from app.auth.keycloak_dependencies import get_current_keycloak_username
 from app.services.leakage_identifier import (
@@ -17,50 +17,114 @@ DEFAULT_N_WORKERS = max(1, min((os.cpu_count() or 1) - 1, 4))
 
 
 class LeakageIdentifyRequest(BaseModel):
-    network: str
-    observed_pressure_data: str | dict[str, list[Any]] | list[dict[str, Any]] | None = (
-        None
+    """漏损识别请求模型"""
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    observed_pressure_data: str | dict[str, list[Any]] | list[dict[str, Any]] | None = Field(
+        None, description="观测的压力数据"
     )
-    start_time: float = 0
-    duration: float = 24
-    timestep: float = 5
-    q_sum: float = 0.2
-    q_sum_unit: str = "m3/s"
-    output_dir: str = "db_inp"
-    pop_size: int = 50
-    max_gen: int = 100
-    n_workers: int = DEFAULT_N_WORKERS
-    output_flow_unit: str = "m3/s"
-    dma_count: int | None = None
-    scada_start: datetime | None = None
-    scada_end: datetime | None = None
-    sensor_nodes: list[str] | None = None
-    scheme_name: str | None = None
+    start_time: float = Field(0, description="起始时间（小时）")
+    duration: float = Field(24, description="持续时间（小时）")
+    timestep: float = Field(5, description="时间步长（分钟）")
+    q_sum: float = Field(0.2, description="总流量（m3/s）")
+    q_sum_unit: str = Field("m3/s", description="流量单位")
+    output_dir: str = Field("db_inp", description="输出目录")
+    pop_size: int = Field(50, description="种群大小")
+    max_gen: int = Field(100, description="最大代数")
+    n_workers: int = Field(DEFAULT_N_WORKERS, description="工作线程数")
+    output_flow_unit: str = Field("m3/s", description="输出流量单位")
+    dma_count: int | None = Field(None, description="DMA区域数量")
+    scada_start: datetime | None = Field(None, description="SCADA数据起始时间")
+    scada_end: datetime | None = Field(None, description="SCADA数据结束时间")
+    sensor_nodes: list[str] | None = Field(None, description="传感器节点列表")
+    scheme_name: str | None = Field(None, description="方案名称")
 
 
-@router.post("/identify/")
+@router.post(
+    "/identify/",
+    summary="执行漏损识别",
+    description="基于压力观测数据和遗传算法识别管网中的漏损位置和大小"
+)
 async def identify_leakage(
-    data: LeakageIdentifyRequest,
+    data: LeakageIdentifyRequest = Body(..., description="漏损识别请求数据"),
     username: str = Depends(get_current_keycloak_username),
 ) -> dict[str, Any]:
+    """
+    执行漏损识别分析。
+    
+    使用遗传算法对比模型计算和实测压力数据，
+    识别管网中的漏损节点和漏水量。
+    
+    Args:
+        data: 包含管网名称（或数据库名称）、压力数据及优化参数的请求体
+        username: 当前认证用户名
+        
+    Returns:
+        包含识别结果的字典
+        
+    Raises:
+        HTTPException: 当处理过程中发生错误时
+    """
     try:
         return run_leakage_identification(**data.model_dump(), username=username)
     except Exception as exc:
         raise HTTPException(status_code=400, detail=str(exc))
 
 
-@router.get("/schemes/")
+@router.get(
+    "/schemes/",
+    summary="查询漏损识别方案列表",
+    description="获取指定网络的所有漏损识别方案"
+)
 async def query_leakage_schemes(
-    network: str, query_date: datetime | None = None
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    query_date: datetime | None = Query(None, description="查询日期（可选）")
 ) -> list[dict[str, Any]]:
+    """
+    获取漏损识别方案列表。
+    
+    查询指定网络的所有已配置的漏损识别方案，
+    可按日期进行筛选。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        query_date: 查询日期（可选）
+        
+    Returns:
+        漏损识别方案列表
+        
+    Raises:
+        HTTPException: 当查询失败时
+    """
     try:
         return list_leakage_identify_schemes(network=network, query_date=query_date)
     except Exception as exc:
         raise HTTPException(status_code=400, detail=str(exc))
 
 
-@router.get("/schemes/{scheme_name}")
-async def query_leakage_scheme_detail(network: str, scheme_name: str) -> dict[str, Any]:
+@router.get(
+    "/schemes/{scheme_name}",
+    summary="获取漏损识别方案详情",
+    description="获取指定漏损识别方案的详细信息"
+)
+async def query_leakage_scheme_detail(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    scheme_name: str = Path(..., description="漏损识别方案名称")
+) -> dict[str, Any]:
+    """
+    获取漏损识别方案详情。
+    
+    查询指定漏损识别方案的完整配置和参数信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        scheme_name: 漏损识别方案名称
+        
+    Returns:
+        包含方案详情的字典
+        
+    Raises:
+        HTTPException: 当查询失败时
+    """
     try:
         return get_leakage_identify_scheme_detail(
             network=network, scheme_name=scheme_name

app/api/v1/endpoints/meta.py

@@ -1,5 +1,5 @@
 import logging
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Path
 from psycopg import AsyncConnection
 from sqlalchemy import text
 from sqlalchemy.exc import SQLAlchemyError
@@ -19,17 +19,22 @@ from app.domain.schemas.metadata import (
     ProjectMetaResponse,
     ProjectSummaryResponse,
 )
-from app.infra.repositories.metadata_repository import MetadataRepository
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
 
 router = APIRouter()
 logger = logging.getLogger(__name__)
 
 
-@router.get("/meta/project", response_model=ProjectMetaResponse)
+@router.get("/meta/project", summary="获取项目元数据", description="获取当前项目的元数据和配置信息", response_model=ProjectMetaResponse)
 async def get_project_metadata(
     ctx: ProjectContext = Depends(get_project_context),
     metadata_repo: MetadataRepository = Depends(get_metadata_repository),
 ):
+    """
+    获取项目元数据
+    
+    返回当前项目的完整元数据，包括项目基本信息和GeoServer配置
+    """
     project = await metadata_repo.get_project_by_id(ctx.project_id)
     if not project:
         raise HTTPException(
@@ -59,11 +64,16 @@ async def get_project_metadata(
     )
 
 
-@router.get("/meta/projects", response_model=list[ProjectSummaryResponse])
+@router.get("/meta/projects", summary="列出用户项目", description="获取当前用户有权限的所有项目列表", response_model=list[ProjectSummaryResponse])
 async def list_user_projects(
     current_user=Depends(get_current_metadata_user),
     metadata_repo: MetadataRepository = Depends(get_metadata_repository),
 ):
+    """
+    列出用户的所有项目
+    
+    返回当前用户有权限访问的项目摘要列表
+    """
     try:
         projects = await metadata_repo.list_projects_for_user(current_user.id)
     except SQLAlchemyError as exc:
@@ -90,11 +100,16 @@ async def list_user_projects(
     ]
 
 
-@router.get("/meta/db/health")
+@router.get("/meta/db/health", summary="检查数据库健康状态", description="检查项目数据库连接的健康状况")
 async def project_db_health(
     pg_session: AsyncSession = Depends(get_project_pg_session),
     ts_conn: AsyncConnection = Depends(get_project_timescale_connection),
 ):
+    """
+    检查数据库健康状态
+    
+    检查PostgreSQL和TimescaleDB数据库的连接状态
+    """
     await pg_session.execute(text("SELECT 1"))
     async with ts_conn.cursor() as cur:
         await cur.execute("SELECT 1")

app/api/v1/endpoints/misc.py

@@ -1,6 +1,6 @@
 from typing import Any
 import random
-from fastapi import APIRouter
+from fastapi import APIRouter, Query
 from fastapi.responses import JSONResponse
 from fastapi import status
 from pydantic import BaseModel
@@ -12,8 +12,13 @@ from app.services.tjnetwork import (
 router = APIRouter()
 
 
-@router.get("/getjson/")
+@router.get("/getjson/", summary="获取JSON示例", description="获取JSON格式响应示例")
 async def fastapi_get_json():
+    """
+    获取JSON示例
+    
+    返回示例JSON格式的响应
+    """
     return JSONResponse(
         status_code=status.HTTP_400_BAD_REQUEST,
         content={
@@ -24,32 +29,58 @@ async def fastapi_get_json():
     )
 
 
-@router.get("/getallsensorplacements/")
-async def fastapi_get_all_sensor_placements(network: str) -> list[dict[Any, Any]]:
+@router.get("/getallsensorplacements/", summary="获取所有传感器位置", description="获取网络中所有传感器的放置位置信息")
+async def fastapi_get_all_sensor_placements(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[dict[Any, Any]]:
+    """
+    获取所有传感器位置
+    
+    返回网络中所有传感器的放置位置及其配置信息
+    """
     return get_all_sensor_placements(network)
 
 
-@router.get("/getallburstlocateresults/")
-async def fastapi_get_all_burst_locate_results(network: str) -> list[dict[Any, Any]]:
+@router.get("/getallburstlocateresults/", summary="获取所有爆管定位结果", description="获取网络中所有爆管定位的分析结果")
+async def fastapi_get_all_burst_locate_results(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[dict[Any, Any]]:
+    """
+    获取所有爆管定位结果
+    
+    返回网络中所有的爆管定位分析结果
+    """
     return get_all_burst_locate_results(network)
 
 
 class Item(BaseModel):
+    """测试数据模型"""
     str_info: str
 
 
-@router.post("/test_dict/")
+@router.post("/test_dict/", summary="测试字典处理", description="测试处理字典类型数据")
 async def fastapi_test_dict(data: Item) -> dict[str, str]:
+    """
+    测试字典处理
+    
+    接收Item模型，返回其字典格式
+    """
     item = data.dict()
     return item
 
-@router.get("/getrealtimedata/")
+@router.get("/getrealtimedata/", summary="获取实时数据", description="获取实时监测数据")
 async def fastapi_get_realtimedata():
+    """
+    获取实时数据
+    
+    返回随机生成的实时监测数据示例
+    """
     data = [random.randint(0, 100) for _ in range(100)]
     return data
 
 
-@router.get("/getsimulationresult/")
+@router.get("/getsimulationresult/", summary="获取模拟结果", description="获取仿真计算结果")
 async def fastapi_get_simulationresult():
+    """
+    获取仿真结果
+    
+    返回随机生成的仿真计算结果示例
+    """
     data = [random.randint(0, 100) for _ in range(100)]
     return data

app/api/v1/endpoints/network/demands.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -17,21 +17,54 @@ router = APIRouter()
 # demand 9.[DEMANDS]
 ############################################################
 
-@router.get("/getdemandschema")
-async def fastapi_get_demand_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/getdemandschema",
+    summary="获取需水量属性架构",
+    description="获取指定水网中需水量(Demand)的属性架构定义"
+)
+async def fastapi_get_demand_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """
+    获取需水量属性架构。
+    
+    返回指定水网的需水量属性架构，包括所有可配置的属性及其类型定义。
+    """
     return get_demand_schema(network)
 
 
-@router.get("/getdemandproperties/")
-async def fastapi_get_demand_properties(network: str, junction: str) -> dict[str, Any]:
+@router.get(
+    "/getdemandproperties/",
+    summary="获取需水量属性",
+    description="获取指定水网中节点的需水量属性信息"
+)
+async def fastapi_get_demand_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点ID")
+) -> dict[str, Any]:
+    """
+    获取节点的需水量属性。
+    
+    返回指定节点的所有需水量信息，包括需水量值、水压等级等。
+    """
     return get_demand(network, junction)
 
 
 # example: set_demand(p, ChangeSet({'junction': 'j1', 'demands': [{'demand': 10.0, 'pattern': None, 'category': 'x'}, {'demand': 20.0, 'pattern': None, 'category': None}]}))
-@router.post("/setdemandproperties/", response_model=None)
+@router.post(
+    "/setdemandproperties/",
+    response_model=None,
+    summary="设置需水量属性",
+    description="设置指定水网中节点的需水量属性信息"
+)
 async def fastapi_set_demand_properties(
-    network: str, junction: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """
+    设置节点的需水量属性。
+    
+    修改指定节点的需水量信息。请求体应包含需水量值、水压等级等属性。
+    """
     props = await req.json()
     ps = {"junction": junction} | props
     return set_demand(network, ChangeSet(ps))
@@ -39,26 +72,68 @@ async def fastapi_set_demand_properties(
 ############################################################
 # water distribution 36.[Water Distribution]
 ############################################################
-@router.get("/calculatedemandtonodes/")
+@router.get(
+    "/calculatedemandtonodes/",
+    summary="计算需水量到节点分配",
+    description="将总需水量按指定方式分配到多个节点"
+)
 async def fastapi_calculate_demand_to_nodes(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> dict[str, float]:
+    """
+    计算需水量到节点分配。
+    
+    将指定的总需水量均匀或按比例分配到指定的节点列表中。
+    
+    请求体格式:
+    {
+        "demand": 需水量值(float),
+        "nodes": 节点ID列表(list[str])
+    }
+    """
     props = await req.json()
     demand = props["demand"]
     nodes = props["nodes"]
     return calculate_demand_to_nodes(network, demand, nodes)
 
-@router.get("/calculatedemandtoregion/")
+@router.get(
+    "/calculatedemandtoregion/",
+    summary="计算需水量到区域分配",
+    description="将总需水量按区域特征分配到该区域内的节点"
+)
 async def fastapi_calculate_demand_to_region(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> dict[str, float]:
+    """
+    计算需水量到区域分配。
+    
+    根据区域内节点的特征(如面积、人口等)将总需水量分配到该区域的各个节点。
+    
+    请求体格式:
+    {
+        "demand": 需水量值(float),
+        "region": 区域ID(str)
+    }
+    """
     props = await req.json()
     demand = props["demand"]
     region = props["region"]
     return calculate_demand_to_region(network, demand, region)
 
-@router.get("/calculatedemandtonetwork/")
+@router.get(
+    "/calculatedemandtonetwork/",
+    summary="计算需水量到整网分配",
+    description="将需水量均匀分配到整个水网的所有需水节点"
+)
 async def fastapi_calculate_demand_to_network(
-    network: str, demand: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    demand: float = Query(..., description="总需水量(m³/h)", gt=0)
 ) -> dict[str, float]:
+    """
+    计算需水量到整网分配。
+    
+    将指定的需水量均匀分配到整个水网的所有需水节点。
+    """
     return calculate_demand_to_network(network, demand)

app/api/v1/endpoints/network/general.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -44,110 +44,291 @@ router = APIRouter()
 # type
 ############################################################
 
-@router.get("/isnode/")
-async def fastapi_is_node(network: str, node: str) -> bool:
+@router.get(
+    "/isnode/",
+    summary="检查节点有效性",
+    description="检查指定ID是否为水网中的有效节点"
+)
+async def fastapi_is_node(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> bool:
+    """检查指定ID是否为节点。"""
     return is_node(network, node)
 
-@router.get("/isjunction/")
-async def fastapi_is_junction(network: str, node: str) -> bool:
+@router.get(
+    "/isjunction/",
+    summary="检查是否为接点",
+    description="检查指定ID是否为水网中的接点(需求点)"
+)
+async def fastapi_is_junction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> bool:
+    """检查指定ID是否为接点。"""
     return is_junction(network, node)
 
-@router.get("/isreservoir/")
-async def fastapi_is_reservoir(network: str, node: str) -> bool:
+@router.get(
+    "/isreservoir/",
+    summary="检查是否为水源",
+    description="检查指定ID是否为水网中的水源(水库/河流)"
+)
+async def fastapi_is_reservoir(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> bool:
+    """检查指定ID是否为水源。"""
     return is_reservoir(network, node)
 
-@router.get("/istank/")
-async def fastapi_is_tank(network: str, node: str) -> bool:
+@router.get(
+    "/istank/",
+    summary="检查是否为蓄水池",
+    description="检查指定ID是否为水网中的蓄水池"
+)
+async def fastapi_is_tank(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> bool:
+    """检查指定ID是否为蓄水池。"""
     return is_tank(network, node)
 
-@router.get("/islink/")
-async def fastapi_is_link(network: str, link: str) -> bool:
+@router.get(
+    "/islink/",
+    summary="检查管线有效性",
+    description="检查指定ID是否为水网中的有效管线"
+)
+async def fastapi_is_link(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> bool:
+    """检查指定ID是否为管线。"""
     return is_link(network, link)
 
-@router.get("/ispipe/")
-async def fastapi_is_pipe(network: str, link: str) -> bool:
+@router.get(
+    "/ispipe/",
+    summary="检查是否为管道",
+    description="检查指定ID是否为水网中的管道"
+)
+async def fastapi_is_pipe(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> bool:
+    """检查指定ID是否为管道。"""
     return is_pipe(network, link)
 
-@router.get("/ispump/")
-async def fastapi_is_pump(network: str, link: str) -> bool:
+@router.get(
+    "/ispump/",
+    summary="检查是否为泵",
+    description="检查指定ID是否为水网中的泵"
+)
+async def fastapi_is_pump(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> bool:
+    """检查指定ID是否为泵。"""
     return is_pump(network, link)
 
-@router.get("/isvalve/")
-async def fastapi_is_valve(network: str, link: str) -> bool:
+@router.get(
+    "/isvalve/",
+    summary="检查是否为阀门",
+    description="检查指定ID是否为水网中的阀门"
+)
+async def fastapi_is_valve(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> bool:
+    """检查指定ID是否为阀门。"""
     return is_valve(network, link)
 
-@router.get("/getnodetype/")
-async def fastapi_get_node_type(network: str, node: str) -> str:
+@router.get(
+    "/getnodetype/",
+    summary="获取节点类型",
+    description="获取指定节点的类型(接点/水源/蓄水池)"
+)
+async def fastapi_get_node_type(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> str:
+    """获取节点的类型标识。"""
     return get_node_type(network, node)
 
-@router.get("/getlinktype/")
-async def fastapi_get_link_type(network: str, link: str) -> str:
+@router.get(
+    "/getlinktype/",
+    summary="获取管线类型",
+    description="获取指定管线的类型(管道/泵/阀门)"
+)
+async def fastapi_get_link_type(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> str:
+    """获取管线的类型标识。"""
     return get_link_type(network, link)
 
-@router.get("/getelementtype/")
-async def fastapi_get_element_type(network: str, element: str) -> str:
+@router.get(
+    "/getelementtype/",
+    summary="获取元素类型",
+    description="获取指定元素的类型(节点或管线)"
+)
+async def fastapi_get_element_type(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    element: str = Query(..., description="元素ID")
+) -> str:
+    """获取元素的类型标识。"""
     return get_element_type(network, element)
 
-@router.get("/getelementtypevalue/")
-async def fastapi_get_element_type_value(network: str, element: str) -> int:
+@router.get(
+    "/getelementtypevalue/",
+    summary="获取元素类型值",
+    description="获取指定元素的类型数值标识"
+)
+async def fastapi_get_element_type_value(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    element: str = Query(..., description="元素ID")
+) -> int:
+    """获取元素的类型数值。"""
     return get_element_type_value(network, element)
 
-@router.get("/getnodes/")
-async def fastapi_get_nodes(network: str) -> list[str]:
+@router.get(
+    "/getnodes/",
+    summary="获取所有节点",
+    description="获取指定水网中的所有节点ID列表"
+)
+async def fastapi_get_nodes(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[str]:
+    """获取水网中所有节点的ID列表。"""
     return get_nodes(network)
 
-@router.get("/getlinks/")
-async def fastapi_get_links(network: str) -> list[str]:
+@router.get(
+    "/getlinks/",
+    summary="获取所有管线",
+    description="获取指定水网中的所有管线ID列表"
+)
+async def fastapi_get_links(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[str]:
+    """获取水网中所有管线的ID列表。"""
     return get_links(network)
 
-@router.get("/getnodelinks/")
-def get_node_links_endpoint(network: str, node: str) -> list[str]:
+@router.get(
+    "/getnodelinks/",
+    summary="获取节点的关联管线",
+    description="获取指定节点连接的所有管线ID列表"
+)
+def get_node_links_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> list[str]:
+    """获取节点关联的所有管线。"""
     return get_node_links(network, node)
 
 ############################################################
 # Node & Link properties
 ############################################################
 
-@router.get("/getnodeproperties/")
-async def fast_get_node_properties(network: str, node: str) -> dict[str, Any]:
+@router.get(
+    "/getnodeproperties/",
+    summary="获取节点属性",
+    description="获取指定节点的所有属性信息"
+)
+async def fast_get_node_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> dict[str, Any]:
+    """获取节点的完整属性信息。"""
     return get_node_properties(network, node)
 
-@router.get("/getlinkproperties/")
-async def fast_get_link_properties(network: str, link: str) -> dict[str, Any]:
+@router.get(
+    "/getlinkproperties/",
+    summary="获取管线属性",
+    description="获取指定管线的所有属性信息"
+)
+async def fast_get_link_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> dict[str, Any]:
+    """获取管线的完整属性信息。"""
     return get_link_properties(network, link)
 
-@router.get("/getscadaproperties/")
-async def fast_get_scada_properties(network: str, scada: str) -> dict[str, Any]:
+@router.get(
+    "/getscadaproperties/",
+    summary="获取SCADA点属性",
+    description="获取指定SCADA点的属性信息"
+)
+async def fast_get_scada_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    scada: str = Query(..., description="SCADA点ID")
+) -> dict[str, Any]:
+    """获取SCADA点的属性信息。"""
     return get_scada_info(network, scada)
 
-@router.get("/getallscadaproperties/")
-async def fast_get_all_scada_properties(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/getallscadaproperties/",
+    summary="获取所有SCADA点属性",
+    description="获取指定水网中所有SCADA点的属性信息"
+)
+async def fast_get_all_scada_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """获取水网中所有SCADA点的属性列表。"""
     return get_all_scada_info(network)
 
-@router.get("/getelementpropertieswithtype/")
+@router.get(
+    "/getelementpropertieswithtype/",
+    summary="获取指定类型元素属性",
+    description="获取指定类型的元素属性信息"
+)
 async def fast_get_element_properties_with_type(
-    network: str, elementtype: str, element: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    elementtype: str = Query(..., description="元素类型"),
+    element: str = Query(..., description="元素ID")
 ) -> dict[str, Any]:
+    """获取指定类型元素的属性。"""
     return get_element_properties_with_type(network, elementtype, element)
 
-@router.get("/getelementproperties/")
-async def fast_get_element_properties(network: str, element: str) -> dict[str, Any]:
+@router.get(
+    "/getelementproperties/",
+    summary="获取元素属性",
+    description="获取指定元素的属性信息"
+)
+async def fast_get_element_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    element: str = Query(..., description="元素ID")
+) -> dict[str, Any]:
+    """获取元素的完整属性信息。"""
     return get_element_properties(network, element)
 
 ############################################################
 # title 1.[TITLE]
 ############################################################
 
-@router.get("/gettitleschema/")
-async def fast_get_title_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/gettitleschema/",
+    summary="获取标题属性架构",
+    description="获取指定水网的标题(标题)属性架构定义"
+)
+async def fast_get_title_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """获取水网标题的属性架构。"""
     return get_title_schema(network)
 
-@router.get("/gettitle/")
-async def fast_get_title(network: str) -> dict[str, Any]:
+@router.get(
+    "/gettitle/",
+    summary="获取水网标题属性",
+    description="获取指定水网的标题(Title)信息"
+)
+async def fast_get_title(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取水网的标题属性。"""
     return get_title(network)
 
-@router.get("/settitle/", response_model=None)
-async def fastapi_set_title(network: str, req: Request) -> ChangeSet:
+@router.get(
+    "/settitle/",
+    response_model=None,
+    summary="设置水网标题属性",
+    description="设置指定水网的标题(Title)信息"
+)
+async def fastapi_set_title(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置水网的标题属性。"""
     props = await req.json()
     return set_title(network, ChangeSet(props))
 
@@ -155,18 +336,41 @@ async def fastapi_set_title(network: str, req: Request) -> ChangeSet:
 # status 10.[STATUS]
 ############################################################
 
-@router.get("/getstatusschema")
-async def fastapi_get_status_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/getstatusschema",
+    summary="获取状态属性架构",
+    description="获取指定水网的状态(Status)属性架构定义"
+)
+async def fastapi_get_status_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """获取水网状态的属性架构。"""
     return get_status_schema(network)
 
-@router.get("/getstatus/")
-async def fastapi_get_status(network: str, link: str) -> dict[str, Any]:
+@router.get(
+    "/getstatus/",
+    summary="获取管线状态",
+    description="获取指定管线的状态信息"
+)
+async def fastapi_get_status(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> dict[str, Any]:
+    """获取管线的状态属性。"""
     return get_status(network, link)
 
-@router.post("/setstatus/", response_model=None)
+@router.post(
+    "/setstatus/",
+    response_model=None,
+    summary="设置管线状态",
+    description="设置指定管线的状态信息"
+)
 async def fastapi_set_status_properties(
-    network: str, link: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """设置管线的状态属性。"""
     props = await req.json()
     ps = {"link": link} | props
     return set_status(network, ChangeSet(ps))
@@ -175,8 +379,17 @@ async def fastapi_set_status_properties(
 # General Deletion
 ############################################################
 
-@router.post("/deletenode/", response_model=None)
-async def fastapi_delete_node(network: str, node: str) -> ChangeSet:
+@router.post(
+    "/deletenode/",
+    response_model=None,
+    summary="删除节点",
+    description="删除指定的节点(接点/水源/蓄水池)"
+)
+async def fastapi_delete_node(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> ChangeSet:
+    """删除指定的节点。自动识别节点类型并调用相应的删除操作。"""
     ps = {"id": node}
     if is_junction(network, node):
         return delete_junction(network, ChangeSet(ps))
@@ -186,8 +399,17 @@ async def fastapi_delete_node(network: str, node: str) -> ChangeSet:
         return delete_tank(network, ChangeSet(ps))
     return ChangeSet() # Should probably raise error or return empty
 
-@router.post("/deletelink/", response_model=None)
-async def fastapi_delete_link(network: str, link: str) -> ChangeSet:
+@router.post(
+    "/deletelink/",
+    response_model=None,
+    summary="删除管线",
+    description="删除指定的管线(管道/泵/阀门)"
+)
+async def fastapi_delete_link(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    link: str = Query(..., description="管线ID")
+) -> ChangeSet:
+    """删除指定的管线。自动识别管线类型并调用相应的删除操作。"""
     ps = {"id": link}
     if is_pipe(network, link):
         return delete_pipe(network, ChangeSet(ps))

app/api/v1/endpoints/network/geometry.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request, Depends
+from fastapi import APIRouter, Request, Depends, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -34,19 +34,44 @@ router = APIRouter()
 #     props = await req.json()
 #     return set_coord(network, ChangeSet(props))
 
-@router.get("/getnodecoord/")
-async def fastapi_get_node_coord(network: str, node: str) -> dict[str, float] | None:
+@router.get(
+    "/getnodecoord/",
+    summary="获取节点坐标",
+    description="获取指定节点的地理坐标(X, Y)"
+)
+async def fastapi_get_node_coord(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    node: str = Query(..., description="节点ID")
+) -> dict[str, float] | None:
+    """获取节点的地理坐标信息。"""
     return get_node_coord(network, node)
 
 # Additional geometry queries found in main.py logic (implicit or explicit)
-@router.get("/getnetworkinextent/")
+@router.get(
+    "/getnetworkinextent/",
+    summary="获取范围内的网络元素",
+    description="获取指定地理范围内的网络节点和管线"
+)
 async def fastapi_get_network_in_extent(
-    network: str, x1: float, y1: float, x2: float, y2: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    x1: float = Query(..., description="范围左下角X坐标", alias="x1"),
+    y1: float = Query(..., description="范围左下角Y坐标", alias="y1"),
+    x2: float = Query(..., description="范围右上角X坐标", alias="x2"),
+    y2: float = Query(..., description="范围右上角Y坐标", alias="y2")
 ) -> dict[str, Any]:
+    """获取地理范围内的网络几何信息。"""
     return get_network_in_extent(network, x1, y1, x2, y2)
 
-@router.get("/getnetworkgeometries/", dependencies=[Depends(verify_token)])
-async def fastapi_get_network_geometries(network: str) -> dict[str, Any] | None:
+@router.get(
+    "/getnetworkgeometries/",
+    dependencies=[Depends(verify_token)],
+    summary="获取完整网络几何信息",
+    description="获取整个水网的所有节点、管线和SCADA点的几何信息(需要身份验证)"
+)
+async def fastapi_get_network_geometries(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, Any] | None:
+    """获取完整的网络几何信息，包括所有节点、管线和SCADA点。结果从缓存返回。"""
     cache_key = f"getnetworkgeometries_{network}"
     data = redis_client.get(cache_key)
     if data:
@@ -64,18 +89,39 @@ async def fastapi_get_network_geometries(network: str) -> dict[str, Any] | None:
     redis_client.set(cache_key, msgpack.packb(results, default=encode_datetime))
     return results
 
-@router.get("/getmajornodecoords/")
+@router.get(
+    "/getmajornodecoords/",
+    summary="获取主要节点坐标",
+    description="获取直径大于等于指定值的节点坐标"
+)
 async def fastapi_get_majornode_coords(
-    network: str, diameter: int
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    diameter: int = Query(..., description="最小直径(mm)", gt=0)
 ) -> dict[str, dict[str, float]]:
+    """获取主要节点的坐标。只返回直径大于等于指定值的节点。"""
     return get_major_node_coords(network, diameter)
 
-@router.get("/getmajorpipenodes/")
-async def fastapi_get_major_pipe_nodes(network: str, diameter: int) -> list[str] | None:
+@router.get(
+    "/getmajorpipenodes/",
+    summary="获取主要管道节点",
+    description="获取直径大于等于指定值的管道的节点ID"
+)
+async def fastapi_get_major_pipe_nodes(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    diameter: int = Query(..., description="最小直径(mm)", gt=0)
+) -> list[str] | None:
+    """获取主要管道节点。只返回直径大于等于指定值的管道。"""
     return get_major_pipe_nodes(network, diameter)
 
-@router.get("/getnetworklinknodes/")
-async def fastapi_get_network_link_nodes(network: str) -> list[str] | None:
+@router.get(
+    "/getnetworklinknodes/",
+    summary="获取网络管线节点",
+    description="获取指定水网所有管线的起点和终点节点"
+)
+async def fastapi_get_network_link_nodes(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[str] | None:
+    """获取网络中所有管线的连接节点。"""
     return get_network_link_nodes(network)
 
 # @router.get("/getallcoords/")

app/api/v1/endpoints/network/junctions.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -13,108 +13,349 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getjunctionschema")
-async def fast_get_junction_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getjunctionschema", summary="获取节点架构", description="获取指定项目的节点属性架构和数据类型定义。")
+async def fast_get_junction_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取节点架构信息。
+    
+    返回指定项目的节点属性架构，包括所有属性的类型和约束信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+    """
     return get_junction_schema(network)
 
-@router.post("/addjunction/", response_model=None)
+@router.post("/addjunction/", response_model=None, summary="添加节点", description="在供水网络中添加新的节点，指定节点ID和空间坐标。")
 async def fastapi_add_junction(
-    network: str, junction: str, x: float, y: float, z: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    x: float = Query(..., description="X 坐标"),
+    y: float = Query(..., description="Y 坐标"),
+    z: float = Query(..., description="标高（海拔高度）")
 ) -> ChangeSet:
+    """
+    添加新节点到供水网络。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        x: X 坐标值
+        y: Y 坐标值
+        z: 标高（海拔高度）
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "x": x, "y": y, "elevation": z}
     return add_junction(network, ChangeSet(ps))
 
-@router.post("/deletejunction/", response_model=None)
-async def fastapi_delete_junction(network: str, junction: str) -> ChangeSet:
+@router.post("/deletejunction/", response_model=None, summary="删除节点", description="从供水网络中删除指定的节点。")
+async def fastapi_delete_junction(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> ChangeSet:
+    """
+    删除指定的节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction}
     return delete_junction(network, ChangeSet(ps))
 
-@router.get("/getjunctionelevation/")
-async def fastapi_get_junction_elevation(network: str, junction: str) -> float:
+@router.get("/getjunctionelevation/", summary="获取节点标高", description="获取指定节点的标高（海拔高度）。")
+async def fastapi_get_junction_elevation(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> float:
+    """
+    获取节点的标高值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        float: 节点标高值
+    """
     ps = get_junction(network, junction)
     return ps["elevation"]
 
-@router.get("/getjunctionx/")
-async def fastapi_get_junction_x(network: str, junction: str) -> float:
+@router.get("/getjunctionx/", summary="获取节点 X 坐标", description="获取指定节点的 X 坐标值。")
+async def fastapi_get_junction_x(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> float:
+    """
+    获取节点的 X 坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        float: 节点 X 坐标值
+    """
     ps = get_junction(network, junction)
     return ps["x"]
 
-@router.get("/getjunctiony/")
-async def fastapi_get_junction_y(network: str, junction: str) -> float:
+@router.get("/getjunctiony/", summary="获取节点 Y 坐标", description="获取指定节点的 Y 坐标值。")
+async def fastapi_get_junction_y(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> float:
+    """
+    获取节点的 Y 坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        float: 节点 Y 坐标值
+    """
     ps = get_junction(network, junction)
     return ps["y"]
 
-@router.get("/getjunctioncoord/")
-async def fastapi_get_junction_coord(network: str, junction: str) -> dict[str, float]:
+@router.get("/getjunctioncoord/", summary="获取节点坐标", description="获取指定节点的 X 和 Y 坐标。")
+async def fastapi_get_junction_coord(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> dict[str, float]:
+    """
+    获取节点的坐标信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        dict: 包含 x 和 y 坐标的字典
+    """
     ps = get_junction(network, junction)
     coord = {"x": ps["x"], "y": ps["y"]}
     return coord
 
-@router.get("/getjunctiondemand/")
-async def fastapi_get_junction_demand(network: str, junction: str) -> float:
+@router.get("/getjunctiondemand/", summary="获取节点需水量", description="获取指定节点的需水量。")
+async def fastapi_get_junction_demand(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> float:
+    """
+    获取节点的需水量。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        float: 节点的需水量值
+    """
     ps = get_junction(network, junction)
     return ps["demand"]
 
-@router.get("/getjunctionpattern/")
-async def fastapi_get_junction_pattern(network: str, junction: str) -> str:
+@router.get("/getjunctionpattern/", summary="获取节点需水模式", description="获取指定节点的需水模式标识。")
+async def fastapi_get_junction_pattern(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
+) -> str:
+    """
+    获取节点的需水模式。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        str: 节点的需水模式标识
+    """
     ps = get_junction(network, junction)
     return ps["pattern"]
 
-@router.post("/setjunctionelevation/", response_model=None)
+@router.post("/setjunctionelevation/", response_model=None, summary="设置节点标高", description="设置指定节点的标高值。")
 async def fastapi_set_junction_elevation(
-    network: str, junction: str, elevation: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    elevation: float = Query(..., description="标高（海拔高度）")
 ) -> ChangeSet:
+    """
+    设置节点的标高。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        elevation: 标高值
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "elevation": elevation}
     return set_junction(network, ChangeSet(ps))
 
-@router.post("/setjunctionx/", response_model=None)
-async def fastapi_set_junction_x(network: str, junction: str, x: float) -> ChangeSet:
+@router.post("/setjunctionx/", response_model=None, summary="设置节点 X 坐标", description="设置指定节点的 X 坐标值。")
+async def fastapi_set_junction_x(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    x: float = Query(..., description="X 坐标值")
+) -> ChangeSet:
+    """
+    设置节点的 X 坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        x: X 坐标值
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "x": x}
     return set_junction(network, ChangeSet(ps))
 
-@router.post("/setjunctiony/", response_model=None)
-async def fastapi_set_junction_y(network: str, junction: str, y: float) -> ChangeSet:
+@router.post("/setjunctiony/", response_model=None, summary="设置节点 Y 坐标", description="设置指定节点的 Y 坐标值。")
+async def fastapi_set_junction_y(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    y: float = Query(..., description="Y 坐标值")
+) -> ChangeSet:
+    """
+    设置节点的 Y 坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        y: Y 坐标值
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "y": y}
     return set_junction(network, ChangeSet(ps))
 
-@router.post("/setjunctioncoord/", response_model=None)
+@router.post("/setjunctioncoord/", response_model=None, summary="设置节点坐标", description="设置指定节点的 X 和 Y 坐标。")
 async def fastapi_set_junction_coord(
-    network: str, junction: str, x: float, y: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    x: float = Query(..., description="X 坐标值"),
+    y: float = Query(..., description="Y 坐标值")
 ) -> ChangeSet:
+    """
+    设置节点的坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        x: X 坐标值
+        y: Y 坐标值
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "x": x, "y": y}
     return set_junction(network, ChangeSet(ps))
 
-@router.post("/setjunctiondemand/", response_model=None)
+@router.post("/setjunctiondemand/", response_model=None, summary="设置节点需水量", description="设置指定节点的需水量。")
 async def fastapi_set_junction_demand(
-    network: str, junction: str, demand: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    demand: float = Query(..., description="需水量值")
 ) -> ChangeSet:
+    """
+    设置节点的需水量。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        demand: 需水量值
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "demand": demand}
     return set_junction(network, ChangeSet(ps))
 
-@router.post("/setjunctionpattern/", response_model=None)
+@router.post("/setjunctionpattern/", response_model=None, summary="设置节点需水模式", description="设置指定节点的需水模式标识。")
 async def fastapi_set_junction_pattern(
-    network: str, junction: str, pattern: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    pattern: str = Query(..., description="需水模式标识")
 ) -> ChangeSet:
+    """
+    设置节点的需水模式。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        pattern: 需水模式标识
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     ps = {"id": junction, "pattern": pattern}
     return set_junction(network, ChangeSet(ps))
 
-@router.get("/getjunctionproperties/")
+@router.get("/getjunctionproperties/", summary="获取节点属性", description="获取指定节点的所有属性信息。")
 async def fastapi_get_junction_properties(
-    network: str, junction: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID")
 ) -> dict[str, Any]:
+    """
+    获取节点的完整属性信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        
+    Returns:
+        dict: 包含节点所有属性的字典
+    """
     return get_junction(network, junction)
 
-@router.get("/getalljunctionproperties/")
-async def fastapi_get_all_junction_properties(network: str) -> list[dict[str, Any]]:
+@router.get("/getalljunctionproperties/", summary="获取所有节点属性", description="获取指定项目中所有节点的属性信息。")
+async def fastapi_get_all_junction_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取所有节点的属性信息列表。
+    
+    此端点返回指定项目中所有节点的详细属性。缓存查询结果以提高性能。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        list: 包含所有节点属性的列表
+    """
     # 缓存查询结果提高性能
     # global redis_client # Redis logic removed for clean split, can be re-added if needed or imported
     results = get_all_junctions(network)
     return results
 
-@router.post("/setjunctionproperties/", response_model=None)
+@router.post("/setjunctionproperties/", response_model=None, summary="批量设置节点属性", description="批量设置指定节点的多个属性。")
 async def fastapi_set_junction_properties(
-    network: str, junction: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    junction: str = Query(..., description="节点 ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """
+    批量设置节点属性。
+    
+    允许一次性设置节点的多个属性，如坐标、标高、需水量等。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        junction: 节点 ID
+        req: 包含属性和值的 JSON 请求体
+        
+    Returns:
+        ChangeSet: 包含变更信息的结果
+    """
     props = await req.json()
     ps = {"id": junction} | props
     return set_junction(network, ChangeSet(ps))

app/api/v1/endpoints/network/pipes.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -14,22 +14,50 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getpipeschema")
-async def fastapi_get_pipe_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getpipeschema", summary="获取管道模式", description="获取管道对象的模式定义，包含所有可用字段及其类型")
+async def fastapi_get_pipe_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取管道数据模式定义。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含管道模式信息的字典
+    """
     return get_pipe_schema(network)
 
-@router.post("/addpipe/", response_model=None)
+@router.post("/addpipe/", response_model=None, summary="添加管道", description="向网络中添加新的管道，需要提供管道的基本参数如长度、管径、粗糙度等")
 async def fastapi_add_pipe(
-    network: str,
-    pipe: str,
-    node1: str,
-    node2: str,
-    length: float = 0,
-    diameter: float = 0,
-    roughness: float = 0,
-    minor_loss: float = 0,
-    status: str = PIPE_STATUS_OPEN,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道标识符"),
+    node1: str = Query(..., description="管道起始节点ID"),
+    node2: str = Query(..., description="管道终止节点ID"),
+    length: float = Query(0, description="管道长度（单位：米）"),
+    diameter: float = Query(0, description="管道管径（单位：毫米）"),
+    roughness: float = Query(0, description="管道粗糙度"),
+    minor_loss: float = Query(0, description="管道局部阻力系数"),
+    status: str = Query(PIPE_STATUS_OPEN, description="管道状态（开启/关闭）"),
 ) -> ChangeSet:
+    """
+    添加新管道到网络。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        node1: 起始节点ID
+        node2: 终止节点ID
+        length: 管道长度
+        diameter: 管道管径
+        roughness: 管道粗糙度
+        minor_loss: 局部阻力系数
+        status: 管道状态
+        
+    Returns:
+        ChangeSet对象，包含本次操作的变更信息
+    """
     ps = {
         "id": pipe,
         "node1": node1,
@@ -42,102 +70,342 @@ async def fastapi_add_pipe(
     }
     return add_pipe(network, ChangeSet(ps))
 
-@router.post("/deletepipe/", response_model=None)
-async def fastapi_delete_pipe(network: str, pipe: str) -> ChangeSet:
+@router.post("/deletepipe/", response_model=None, summary="删除管道", description="从网络中删除指定的管道")
+async def fastapi_delete_pipe(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="要删除的管道ID")
+) -> ChangeSet:
+    """
+    删除管道。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        ChangeSet对象，包含本次删除操作的变更信息
+    """
     ps = {"id": pipe}
     return delete_pipe(network, ChangeSet(ps))
 
-@router.get("/getpipenode1/")
-async def fastapi_get_pipe_node1(network: str, pipe: str) -> str | None:
+@router.get("/getpipenode1/", summary="获取管道起始节点", description="获取指定管道的起始节点ID")
+async def fastapi_get_pipe_node1(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> str | None:
+    """
+    获取管道的起始节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        起始节点ID，如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["node1"]
 
-@router.get("/getpipenode2/")
-async def fastapi_get_pipe_node2(network: str, pipe: str) -> str | None:
+@router.get("/getpipenode2/", summary="获取管道终止节点", description="获取指定管道的终止节点ID")
+async def fastapi_get_pipe_node2(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> str | None:
+    """
+    获取管道的终止节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        终止节点ID，如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["node2"]
 
-@router.get("/getpipelength/")
-async def fastapi_get_pipe_length(network: str, pipe: str) -> float | None:
+@router.get("/getpipelength/", summary="获取管道长度", description="获取指定管道的长度")
+async def fastapi_get_pipe_length(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> float | None:
+    """
+    获取管道长度。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        管道长度（单位：米），如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["length"]
 
-@router.get("/getpipediameter/")
-async def fastapi_get_pipe_diameter(network: str, pipe: str) -> float | None:
+@router.get("/getpipediameter/", summary="获取管道管径", description="获取指定管道的管径")
+async def fastapi_get_pipe_diameter(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> float | None:
+    """
+    获取管道管径。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        管道管径（单位：毫米），如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["diameter"]
 
-@router.get("/getpiperoughness/")
-async def fastapi_get_pipe_roughness(network: str, pipe: str) -> float | None:
+@router.get("/getpiperoughness/", summary="获取管道粗糙度", description="获取指定管道的粗糙度")
+async def fastapi_get_pipe_roughness(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> float | None:
+    """
+    获取管道粗糙度。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        管道粗糙度值，如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["roughness"]
 
-@router.get("/getpipeminorloss/")
-async def fastapi_get_pipe_minor_loss(network: str, pipe: str) -> float | None:
+@router.get("/getpipeminorloss/", summary="获取管道局部阻力系数", description="获取指定管道的局部阻力系数")
+async def fastapi_get_pipe_minor_loss(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> float | None:
+    """
+    获取管道局部阻力系数。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        局部阻力系数，如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["minor_loss"]
 
-@router.get("/getpipestatus/")
-async def fastapi_get_pipe_status(network: str, pipe: str) -> str | None:
+@router.get("/getpipestatus/", summary="获取管道状态", description="获取指定管道的状态（开启或关闭）")
+async def fastapi_get_pipe_status(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> str | None:
+    """
+    获取管道状态。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        管道状态（开启/关闭），如果不存在则返回None
+    """
     ps = get_pipe(network, pipe)
     return ps["status"]
 
-@router.post("/setpipenode1/", response_model=None)
-async def fastapi_set_pipe_node1(network: str, pipe: str, node1: str) -> ChangeSet:
+@router.post("/setpipenode1/", response_model=None, summary="设置管道起始节点", description="设置指定管道的起始节点")
+async def fastapi_set_pipe_node1(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    node1: str = Query(..., description="新的起始节点ID")
+) -> ChangeSet:
+    """
+    设置管道起始节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        node1: 新的起始节点ID
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "node1": node1}
     return set_pipe(network, ChangeSet(ps))
 
-@router.post("/setpipenode2/", response_model=None)
-async def fastapi_set_pipe_node2(network: str, pipe: str, node2: str) -> ChangeSet:
+@router.post("/setpipenode2/", response_model=None, summary="设置管道终止节点", description="设置指定管道的终止节点")
+async def fastapi_set_pipe_node2(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    node2: str = Query(..., description="新的终止节点ID")
+) -> ChangeSet:
+    """
+    设置管道终止节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        node2: 新的终止节点ID
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "node2": node2}
     return set_pipe(network, ChangeSet(ps))
 
-@router.post("/setpipelength/", response_model=None)
-async def fastapi_set_pipe_length(network: str, pipe: str, length: float) -> ChangeSet:
+@router.post("/setpipelength/", response_model=None, summary="设置管道长度", description="设置指定管道的长度")
+async def fastapi_set_pipe_length(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    length: float = Query(..., description="新的管道长度（单位：米）")
+) -> ChangeSet:
+    """
+    设置管道长度。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        length: 新的管道长度
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "length": length}
     return set_pipe(network, ChangeSet(ps))
 
-@router.post("/setpipediameter/", response_model=None)
+@router.post("/setpipediameter/", response_model=None, summary="设置管道管径", description="设置指定管道的管径")
 async def fastapi_set_pipe_diameter(
-    network: str, pipe: str, diameter: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    diameter: float = Query(..., description="新的管道管径（单位：毫米）")
 ) -> ChangeSet:
+    """
+    设置管道管径。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        diameter: 新的管道管径
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "diameter": diameter}
     return set_pipe(network, ChangeSet(ps))
 
-@router.post("/setpiperoughness/", response_model=None)
+@router.post("/setpiperoughness/", response_model=None, summary="设置管道粗糙度", description="设置指定管道的粗糙度")
 async def fastapi_set_pipe_roughness(
-    network: str, pipe: str, roughness: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    roughness: float = Query(..., description="新的管道粗糙度值")
 ) -> ChangeSet:
+    """
+    设置管道粗糙度。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        roughness: 新的管道粗糙度
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "roughness": roughness}
     return set_pipe(network, ChangeSet(ps))
 
-@router.post("/setpipeminorloss/", response_model=None)
+@router.post("/setpipeminorloss/", response_model=None, summary="设置管道局部阻力系数", description="设置指定管道的局部阻力系数")
 async def fastapi_set_pipe_minor_loss(
-    network: str, pipe: str, minor_loss: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    minor_loss: float = Query(..., description="新的局部阻力系数值")
 ) -> ChangeSet:
+    """
+    设置管道局部阻力系数。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        minor_loss: 新的局部阻力系数
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "minor_loss": minor_loss}
     return set_pipe(network, ChangeSet(ps))
 
-@router.post("/setpipestatus/", response_model=None)
-async def fastapi_set_pipe_status(network: str, pipe: str, status: str) -> ChangeSet:
+@router.post("/setpipestatus/", response_model=None, summary="设置管道状态", description="设置指定管道的状态（开启或关闭）")
+async def fastapi_set_pipe_status(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    status: str = Query(..., description="新的管道状态（开启/关闭）")
+) -> ChangeSet:
+    """
+    设置管道状态。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        status: 新的管道状态
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pipe, "status": status}
     return set_pipe(network, ChangeSet(ps))
 
-@router.get("/getpipeproperties/")
-async def fastapi_get_pipe_properties(network: str, pipe: str) -> dict[str, Any]:
+@router.get("/getpipeproperties/", summary="获取管道属性", description="获取指定管道的所有属性信息")
+async def fastapi_get_pipe_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID")
+) -> dict[str, Any]:
+    """
+    获取管道的所有属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        
+    Returns:
+        包含管道所有属性的字典
+    """
     return get_pipe(network, pipe)
 
-@router.get("/getallpipeproperties/")
-async def fastapi_get_all_pipe_properties(network: str) -> list[dict[str, Any]]:
+@router.get("/getallpipeproperties/", summary="获取所有管道属性", description="获取网络中所有管道的属性信息列表")
+async def fastapi_get_all_pipe_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取网络中所有管道的属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含所有管道属性的字典列表
+    """
     # 缓存查询结果提高性能
     # global redis_client
     results = get_all_pipes(network)
     return results
 
-@router.post("/setpipeproperties/", response_model=None)
+@router.post("/setpipeproperties/", response_model=None, summary="设置管道属性", description="批量设置指定管道的多个属性")
 async def fastapi_set_pipe_properties(
-    network: str, pipe: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe: str = Query(..., description="管道ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """
+    批量设置管道属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe: 管道ID
+        req: 请求体，包含要设置的属性及其值
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     props = await req.json()
     ps = {"id": pipe} | props
     return set_pipe(network, ChangeSet(ps))

app/api/v1/endpoints/network/pumps.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -13,57 +13,191 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getpumpschema")
-async def fastapi_get_pump_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getpumpschema", summary="获取水泵模式", description="获取水泵对象的模式定义，包含所有可用字段及其类型")
+async def fastapi_get_pump_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取水泵数据模式定义。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含水泵模式信息的字典
+    """
     return get_pump_schema(network)
 
-@router.post("/addpump/", response_model=None)
+@router.post("/addpump/", response_model=None, summary="添加水泵", description="向网络中添加新的水泵，需要提供水泵的基本参数如功率等")
 async def fastapi_add_pump(
-    network: str, pump: str, node1: str, node2: str, power: float = 0.0
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵标识符"),
+    node1: str = Query(..., description="水泵起始节点ID"),
+    node2: str = Query(..., description="水泵终止节点ID"),
+    power: float = Query(0.0, description="水泵功率（单位：千瓦）")
 ) -> ChangeSet:
+    """
+    添加新水泵到网络。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        node1: 起始节点ID
+        node2: 终止节点ID
+        power: 水泵功率
+        
+    Returns:
+        ChangeSet对象，包含本次操作的变更信息
+    """
     ps = {"id": pump, "node1": node1, "node2": node2, "power": power}
     return add_pump(network, ChangeSet(ps))
 
-@router.post("/deletepump/", response_model=None)
-async def fastapi_delete_pump(network: str, pump: str) -> ChangeSet:
+@router.post("/deletepump/", response_model=None, summary="删除水泵", description="从网络中删除指定的水泵")
+async def fastapi_delete_pump(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="要删除的水泵ID")
+) -> ChangeSet:
+    """
+    删除水泵。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        
+    Returns:
+        ChangeSet对象，包含本次删除操作的变更信息
+    """
     ps = {"id": pump}
     return delete_pump(network, ChangeSet(ps))
 
-@router.get("/getpumpnode1/")
-async def fastapi_get_pump_node1(network: str, pump: str) -> str | None:
+@router.get("/getpumpnode1/", summary="获取水泵起始节点", description="获取指定水泵的起始节点ID")
+async def fastapi_get_pump_node1(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵ID")
+) -> str | None:
+    """
+    获取水泵的起始节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        
+    Returns:
+        起始节点ID，如果不存在则返回None
+    """
     ps = get_pump(network, pump)
     return ps["node1"]
 
-@router.get("/getpumpnode2/")
-async def fastapi_get_pump_node2(network: str, pump: str) -> str | None:
+@router.get("/getpumpnode2/", summary="获取水泵终止节点", description="获取指定水泵的终止节点ID")
+async def fastapi_get_pump_node2(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵ID")
+) -> str | None:
+    """
+    获取水泵的终止节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        
+    Returns:
+        终止节点ID，如果不存在则返回None
+    """
     ps = get_pump(network, pump)
     return ps["node2"]
 
-@router.post("/setpumpnode1/", response_model=None)
-async def fastapi_set_pump_node1(network: str, pump: str, node1: str) -> ChangeSet:
+@router.post("/setpumpnode1/", response_model=None, summary="设置水泵起始节点", description="设置指定水泵的起始节点")
+async def fastapi_set_pump_node1(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵ID"),
+    node1: str = Query(..., description="新的起始节点ID")
+) -> ChangeSet:
+    """
+    设置水泵起始节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        node1: 新的起始节点ID
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pump, "node1": node1}
     return set_pump(network, ChangeSet(ps))
 
-@router.post("/setpumpnode2/", response_model=None)
-async def fastapi_set_pump_node2(network: str, pump: str, node2: str) -> ChangeSet:
+@router.post("/setpumpnode2/", response_model=None, summary="设置水泵终止节点", description="设置指定水泵的终止节点")
+async def fastapi_set_pump_node2(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵ID"),
+    node2: str = Query(..., description="新的终止节点ID")
+) -> ChangeSet:
+    """
+    设置水泵终止节点。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        node2: 新的终止节点ID
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     ps = {"id": pump, "node2": node2}
     return set_pump(network, ChangeSet(ps))
 
-@router.get("/getpumpproperties/")
-async def fastapi_get_pump_properties(network: str, pump: str) -> dict[str, Any]:
+@router.get("/getpumpproperties/", summary="获取水泵属性", description="获取指定水泵的所有属性信息")
+async def fastapi_get_pump_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵ID")
+) -> dict[str, Any]:
+    """
+    获取水泵的所有属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        
+    Returns:
+        包含水泵所有属性的字典
+    """
     return get_pump(network, pump)
 
-@router.get("/getallpumpproperties/")
-async def fastapi_get_all_pump_properties(network: str) -> list[dict[str, Any]]:
+@router.get("/getallpumpproperties/", summary="获取所有水泵属性", description="获取网络中所有水泵的属性信息列表")
+async def fastapi_get_all_pump_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取网络中所有水泵的属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含所有水泵属性的字典列表
+    """
     # 缓存查询结果提高性能
     # global redis_client
     results = get_all_pumps(network)
     return results
 
-@router.post("/setpumpproperties/", response_model=None)
+@router.post("/setpumpproperties/", response_model=None, summary="设置水泵属性", description="批量设置指定水泵的多个属性")
 async def fastapi_set_pump_properties(
-    network: str, pump: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="水泵ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """
+    批量设置水泵属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pump: 水泵ID
+        req: 请求体，包含要设置的属性及其值
+        
+    Returns:
+        ChangeSet对象，包含本次修改的变更信息
+    """
     props = await req.json()
     ps = {"id": pump} | props
     return set_pump(network, ChangeSet(ps))

app/api/v1/endpoints/network/regions.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -7,9 +7,11 @@ from app.services.tjnetwork import (
     add_region,
     add_service_area,
     add_virtual_district,
+    # calculate_district_metering_area,
     calculate_district_metering_area_for_network,
     calculate_district_metering_area_for_nodes,
     calculate_district_metering_area_for_region,
+    # calculate_region,
     calculate_service_area,
     calculate_virtual_district,
     delete_district_metering_area,
@@ -17,11 +19,13 @@ from app.services.tjnetwork import (
     delete_service_area,
     delete_virtual_district,
     generate_district_metering_area,
+    # generate_region,
     generate_service_area,
     generate_sub_district_metering_area,
     generate_virtual_district,
     get_all_district_metering_area_ids,
     get_all_district_metering_areas,
+    # get_all_regions,
     get_all_service_areas,
     get_all_virtual_districts,
     get_district_metering_area,
@@ -44,41 +48,105 @@ router = APIRouter()
 # region 32
 ############################################################
 
-@router.get("/calculateregion/")
-async def fastapi_calculate_region(network: str, time_index: int) -> dict[str, Any]:
+@router.get(
+    "/calculateregion/",
+    summary="计算区域",
+    description="计算指定水网在指定时间步长的区域分区"
+)
+async def fastapi_calculate_region(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    time_index: int = Query(..., description="时间步长索引", ge=0)
+) -> dict[str, Any]:
+    """计算区域分区。"""
     return calculate_region(network, time_index)
 
-@router.get("/getregionschema/")
-async def fastapi_get_region_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/getregionschema/",
+    summary="获取区域属性架构",
+    description="获取指定水网的区域属性架构定义"
+)
+async def fastapi_get_region_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """获取区域的属性架构。"""
     return get_region_schema(network)
 
-@router.get("/getregion/")
-async def fastapi_get_region(network: str, id: str) -> dict[str, Any]:
+@router.get(
+    "/getregion/",
+    summary="获取区域信息",
+    description="获取指定ID的区域详细信息"
+)
+async def fastapi_get_region(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="区域ID")
+) -> dict[str, Any]:
+    """获取区域的详细信息。"""
     return get_region(network, id)
 
-@router.post("/setregion/", response_model=None)
-async def fastapi_set_region(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/setregion/",
+    response_model=None,
+    summary="设置区域属性",
+    description="修改指定区域的属性信息"
+)
+async def fastapi_set_region(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置区域属性。"""
     props = await req.json()
     return set_region(network, ChangeSet(props))
 
-@router.post("/addregion/", response_model=None)
-async def fastapi_add_region(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/addregion/",
+    response_model=None,
+    summary="添加新区域",
+    description="向水网添加一个新的区域"
+)
+async def fastapi_add_region(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加新的区域。"""
     props = await req.json()
     return add_region(network, ChangeSet(props))
 
-@router.post("/deleteregion/", response_model=None)
-async def fastapi_delete_region(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/deleteregion/",
+    response_model=None,
+    summary="删除区域",
+    description="删除指定的区域"
+)
+async def fastapi_delete_region(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """删除区域。"""
     props = await req.json()
     return delete_region(network, ChangeSet(props))
 
-@router.get("/getallregions/")
-async def fastapi_get_all_regions(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/getallregions/",
+    summary="获取所有区域",
+    description="获取指定水网中的所有区域信息"
+)
+async def fastapi_get_all_regions(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """获取所有区域的信息列表。"""
     return get_all_regions(network)
 
-@router.post("/generateregion/", response_model=None)
+@router.post(
+    "/generateregion/",
+    response_model=None,
+    summary="生成区域分区",
+    description="根据参数自动生成水网的区域分区"
+)
 async def fastapi_generate_region(
-    network: str, inflate_delta: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inflate_delta: float = Query(..., description="膨胀参数")
 ) -> ChangeSet:
+    """生成区域分区。"""
     return generate_region(network, inflate_delta)
 
 
@@ -86,10 +154,25 @@ async def fastapi_generate_region(
 # district_metering_area 33
 ############################################################
 
-@router.get("/calculatedistrictmeteringarea/")
+@router.get(
+    "/calculatedistrictmeteringarea/",
+    summary="计算DMA分区",
+    description="计算指定节点集的区域计量(DMA)分区方案"
+)
 async def fastapi_calculate_district_metering_area(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> list[list[str]]:
+    """
+    计算DMA分区。
+    
+    请求体格式:
+    {
+        "nodes": 节点ID列表(list[str]),
+        "part_count": 分区数量(int),
+        "part_type": 分区类型(int)
+    }
+    """
     props = await req.json()
     nodes = props["nodes"]
     part_count = props["part_count"]
@@ -98,10 +181,25 @@ async def fastapi_calculate_district_metering_area(
         network, nodes, part_count, part_type
     )
 
-@router.get("/calculatedistrictmeteringareaforregion/")
+@router.get(
+    "/calculatedistrictmeteringareaforregion/",
+    summary="计算区域内DMA分区",
+    description="为指定区域计算区域计量(DMA)分区方案"
+)
 async def fastapi_calculate_district_metering_area_for_region(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> list[list[str]]:
+    """
+    计算区域内DMA分区。
+    
+    请求体格式:
+    {
+        "region": 区域ID(str),
+        "part_count": 分区数量(int),
+        "part_type": 分区类型(int)
+    }
+    """
     props = await req.json()
     region = props["region"]
     part_count = props["part_count"]
@@ -110,32 +208,77 @@ async def fastapi_calculate_district_metering_area_for_region(
         network, region, part_count, part_type
     )
 
-@router.get("/calculatedistrictmeteringareafornetwork/")
+@router.get(
+    "/calculatedistrictmeteringareafornetwork/",
+    summary="计算整网DMA分区",
+    description="为整个水网计算区域计量(DMA)分区方案"
+)
 async def fastapi_calculate_district_metering_area_for_network(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> list[list[str]]:
+    """
+    计算整网DMA分区。
+    
+    请求体格式:
+    {
+        "part_count": 分区数量(int),
+        "part_type": 分区类型(int)
+    }
+    """
     props = await req.json()
     part_count = props["part_count"]
     part_type = props["part_type"]
     return calculate_district_metering_area_for_network(network, part_count, part_type)
 
-@router.get("/getdistrictmeteringareaschema/")
+@router.get(
+    "/getdistrictmeteringareaschema/",
+    summary="获取DMA属性架构",
+    description="获取指定水网的区域计量(DMA)属性架构定义"
+)
 async def fastapi_get_district_metering_area_schema(
-    network: str,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
 ) -> dict[str, dict[str, Any]]:
+    """获取DMA的属性架构。"""
     return get_district_metering_area_schema(network)
 
-@router.get("/getdistrictmeteringarea/")
-async def fastapi_get_district_metering_area(network: str, id: str) -> dict[str, Any]:
+@router.get(
+    "/getdistrictmeteringarea/",
+    summary="获取DMA信息",
+    description="获取指定ID的区域计量(DMA)详细信息"
+)
+async def fastapi_get_district_metering_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="DMA ID")
+) -> dict[str, Any]:
+    """获取DMA的详细信息。"""
     return get_district_metering_area(network, id)
 
-@router.post("/setdistrictmeteringarea/", response_model=None)
-async def fastapi_set_district_metering_area(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/setdistrictmeteringarea/",
+    response_model=None,
+    summary="设置DMA属性",
+    description="修改指定DMA的属性信息"
+)
+async def fastapi_set_district_metering_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置DMA属性。"""
     props = await req.json()
     return set_district_metering_area(network, ChangeSet(props))
 
-@router.post("/adddistrictmeteringarea/", response_model=None)
-async def fastapi_add_district_metering_area(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/adddistrictmeteringarea/",
+    response_model=None,
+    summary="添加新DMA",
+    description="向水网添加一个新的区域计量(DMA)"
+)
+async def fastapi_add_district_metering_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加新的DMA。"""
     props = await req.json()
     # boundary should be [(x,y), (x,y)]
     boundary = props.get("boundary", [])
@@ -146,33 +289,73 @@ async def fastapi_add_district_metering_area(network: str, req: Request) -> Chan
     props["boundary"] = newBoundary
     return add_district_metering_area(network, ChangeSet(props))
 
-@router.post("/deletedistrictmeteringarea/", response_model=None)
+@router.post(
+    "/deletedistrictmeteringarea/",
+    response_model=None,
+    summary="删除DMA",
+    description="删除指定的区域计量(DMA)"
+)
 async def fastapi_delete_district_metering_area(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> ChangeSet:
+    """删除DMA。"""
     props = await req.json()
     return delete_district_metering_area(network, ChangeSet(props))
 
-@router.get("/getalldistrictmeteringareaids/")
-async def fastapi_get_all_district_metering_area_ids(network: str) -> list[str]:
+@router.get(
+    "/getalldistrictmeteringareaids/",
+    summary="获取所有DMA ID",
+    description="获取指定水网中所有DMA的ID列表"
+)
+async def fastapi_get_all_district_metering_area_ids(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[str]:
+    """获取所有DMA的ID列表。"""
     return get_all_district_metering_area_ids(network)
 
-@router.get("/getalldistrictmeteringareas/")
-async def getalldistrictmeteringareas(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/getalldistrictmeteringareas/",
+    summary="获取所有DMA",
+    description="获取指定水网中所有DMA的详细信息"
+)
+async def getalldistrictmeteringareas(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """获取所有DMA的详细信息列表。"""
     return get_all_district_metering_areas(network)
 
-@router.post("/generatedistrictmeteringarea/", response_model=None)
+@router.post(
+    "/generatedistrictmeteringarea/",
+    response_model=None,
+    summary="生成DMA分区",
+    description="根据参数自动生成水网的DMA分区方案"
+)
 async def fastapi_generate_district_metering_area(
-    network: str, part_count: int, part_type: int, inflate_delta: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    part_count: int = Query(..., description="分区数量", gt=0),
+    part_type: int = Query(..., description="分区类型"),
+    inflate_delta: float = Query(..., description="膨胀参数")
 ) -> ChangeSet:
+    """生成DMA分区。"""
     return generate_district_metering_area(
         network, part_count, part_type, inflate_delta
     )
 
-@router.post("/generatesubdistrictmeteringarea/", response_model=None)
+@router.post(
+    "/generatesubdistrictmeteringarea/",
+    response_model=None,
+    summary="生成DMA子分区",
+    description="为指定DMA生成子DMA分区"
+)
 async def fastapi_generate_sub_district_metering_area(
-    network: str, dma: str, part_count: int, part_type: int, inflate_delta: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    dma: str = Query(..., description="DMA ID"),
+    part_count: int = Query(..., description="分区数量", gt=0),
+    part_type: int = Query(..., description="分区类型"),
+    inflate_delta: float = Query(..., description="膨胀参数")
 ) -> ChangeSet:
+    """生成DMA子分区。"""
     return generate_sub_district_metering_area(
         network, dma, part_count, part_type, inflate_delta
     )
@@ -182,43 +365,105 @@ async def fastapi_generate_sub_district_metering_area(
 # service_area 34
 ############################################################
 
-@router.get("/calculateservicearea/")
+@router.get(
+    "/calculateservicearea/",
+    summary="计算服务区",
+    description="计算指定水网在指定时间步长的服务区分区"
+)
 async def fastapi_calculate_service_area(
-    network: str, time_index: int
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    time_index: int = Query(..., description="时间步长索引", ge=0)
 ) -> dict[str, Any]:
+    """计算服务区分区。"""
     return calculate_service_area(network, time_index)
 
-@router.get("/getserviceareaschema/")
-async def fastapi_get_service_area_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/getserviceareaschema/",
+    summary="获取服务区属性架构",
+    description="获取指定水网的服务区属性架构定义"
+)
+async def fastapi_get_service_area_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """获取服务区的属性架构。"""
     return get_service_area_schema(network)
 
-@router.get("/getservicearea/")
-async def fastapi_get_service_area(network: str, id: str) -> dict[str, Any]:
+@router.get(
+    "/getservicearea/",
+    summary="获取服务区信息",
+    description="获取指定ID的服务区详细信息"
+)
+async def fastapi_get_service_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="服务区ID")
+) -> dict[str, Any]:
+    """获取服务区的详细信息。"""
     return get_service_area(network, id)
 
-@router.post("/setservicearea/", response_model=None)
-async def fastapi_set_service_area(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/setservicearea/",
+    response_model=None,
+    summary="设置服务区属性",
+    description="修改指定服务区的属性信息"
+)
+async def fastapi_set_service_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置服务区属性。"""
     props = await req.json()
     return set_service_area(network, ChangeSet(props))
 
-@router.post("/addservicearea/", response_model=None)
-async def fastapi_add_service_area(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/addservicearea/",
+    response_model=None,
+    summary="添加新服务区",
+    description="向水网添加一个新的服务区"
+)
+async def fastapi_add_service_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加新的服务区。"""
     props = await req.json()
     return add_service_area(network, ChangeSet(props))
 
-@router.post("/deleteservicearea/", response_model=None)
-async def fastapi_delete_service_area(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/deleteservicearea/",
+    response_model=None,
+    summary="删除服务区",
+    description="删除指定的服务区"
+)
+async def fastapi_delete_service_area(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """删除服务区。"""
     props = await req.json()
     return delete_service_area(network, ChangeSet(props))
 
-@router.get("/getallserviceareas/")
-async def fastapi_get_all_service_areas(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/getallserviceareas/",
+    summary="获取所有服务区",
+    description="获取指定水网中的所有服务区信息"
+)
+async def fastapi_get_all_service_areas(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """获取所有服务区的信息列表。"""
     return get_all_service_areas(network)
 
-@router.post("/generateservicearea/", response_model=None)
+@router.post(
+    "/generateservicearea/",
+    response_model=None,
+    summary="生成服务区分区",
+    description="根据参数自动生成水网的服务区分区"
+)
 async def fastapi_generate_service_area(
-    network: str, inflate_delta: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inflate_delta: float = Query(..., description="膨胀参数")
 ) -> ChangeSet:
+    """生成服务区分区。"""
     return generate_service_area(network, inflate_delta)
 
 
@@ -226,52 +471,128 @@ async def fastapi_generate_service_area(
 # virtual_district 35
 ############################################################
 
-@router.get("/calculatevirtualdistrict/")
+@router.get(
+    "/calculatevirtualdistrict/",
+    summary="计算虚拟分区",
+    description="根据指定的中心节点计算虚拟分区方案"
+)
 async def fastapi_calculate_virtual_district(
-    network: str, centers: list[str]
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    centers: list[str] = Query(..., description="中心节点ID列表")
 ) -> dict[str, list[Any]]:
+    """计算虚拟分区。"""
     return calculate_virtual_district(network, centers)
 
-@router.get("/getvirtualdistrictschema/")
+@router.get(
+    "/getvirtualdistrictschema/",
+    summary="获取虚拟分区属性架构",
+    description="获取指定水网的虚拟分区属性架构定义"
+)
 async def fastapi_get_virtual_district_schema(
-    network: str,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
 ) -> dict[str, dict[str, Any]]:
+    """获取虚拟分区的属性架构。"""
     return get_virtual_district_schema(network)
 
-@router.get("/getvirtualdistrict/")
-async def fastapi_get_virtual_district(network: str, id: str) -> dict[str, Any]:
+@router.get(
+    "/getvirtualdistrict/",
+    summary="获取虚拟分区信息",
+    description="获取指定ID的虚拟分区详细信息"
+)
+async def fastapi_get_virtual_district(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="虚拟分区ID")
+) -> dict[str, Any]:
+    """获取虚拟分区的详细信息。"""
     return get_virtual_district(network, id)
 
-@router.post("/setvirtualdistrict/", response_model=None)
-async def fastapi_set_virtual_district(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/setvirtualdistrict/",
+    response_model=None,
+    summary="设置虚拟分区属性",
+    description="修改指定虚拟分区的属性信息"
+)
+async def fastapi_set_virtual_district(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置虚拟分区属性。"""
     props = await req.json()
     return set_virtual_district(network, ChangeSet(props))
 
-@router.post("/addvirtualdistrict/", response_model=None)
-async def fastapi_add_virtual_district(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/addvirtualdistrict/",
+    response_model=None,
+    summary="添加新虚拟分区",
+    description="向水网添加一个新的虚拟分区"
+)
+async def fastapi_add_virtual_district(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """添加新的虚拟分区。"""
     props = await req.json()
     return add_virtual_district(network, ChangeSet(props))
 
-@router.post("/deletevirtualdistrict/", response_model=None)
-async def fastapi_delete_virtual_district(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/deletevirtualdistrict/",
+    response_model=None,
+    summary="删除虚拟分区",
+    description="删除指定的虚拟分区"
+)
+async def fastapi_delete_virtual_district(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """删除虚拟分区。"""
     props = await req.json()
     return delete_virtual_district(network, ChangeSet(props))
 
-@router.get("/getallvirtualdistrict/")
-async def fastapi_get_all_virtual_district(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/getallvirtualdistrict/",
+    summary="获取所有虚拟分区",
+    description="获取指定水网中的所有虚拟分区信息"
+)
+async def fastapi_get_all_virtual_district(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """获取所有虚拟分区的信息列表。"""
     return get_all_virtual_districts(network)
 
-@router.post("/generatevirtualdistrict/", response_model=None)
+@router.post(
+    "/generatevirtualdistrict/",
+    response_model=None,
+    summary="生成虚拟分区",
+    description="根据参数自动生成虚拟分区方案"
+)
 async def fastapi_generate_virtual_district(
-    network: str, inflate_delta: float, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inflate_delta: float = Query(..., description="膨胀参数"),
+    req: Request = None
 ) -> ChangeSet:
+    """生成虚拟分区。"""
     props = await req.json()
     return generate_virtual_district(network, props["centers"], inflate_delta)
 
-@router.get("/calculatedistrictmeteringareafornodes/")
+@router.get(
+    "/calculatedistrictmeteringareafornodes/",
+    summary="计算节点DMA分区",
+    description="为指定节点集计算区域计量(DMA)分区方案"
+)
 async def fastapi_calculate_district_metering_area_for_nodes(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
 ) -> list[list[str]]:
+    """
+    计算节点DMA分区。
+    
+    请求体格式:
+    {
+        "nodes": 节点ID列表(list[str]),
+        "part_count": 分区数量(int),
+        "part_type": 分区类型(int)
+    }
+    """
     props = await req.json()
     nodes = props["nodes"]
     part_count = props["part_count"]

app/api/v1/endpoints/network/reservoirs.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -13,102 +13,410 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getreservoirschema")
-async def fast_get_reservoir_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/getreservoirschema",
+    summary="获取水库模式",
+    description="获取指定供水网络中所有水库的模式/属性字段定义"
+)
+async def fast_get_reservoir_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取水库模式定义。
+    
+    该端点返回指定网络中水库对象的模式定义，包括所有可用的属性字段。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        水库属性的模式定义字典
+    """
     return get_reservoir_schema(network)
 
-@router.post("/addreservoir/", response_model=None)
+@router.post(
+    "/addreservoir/",
+    response_model=None,
+    summary="添加水库",
+    description="在指定供水网络中添加新的水库/水源节点"
+)
 async def fastapi_add_reservoir(
-    network: str, reservoir: str, x: float, y: float, head: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    x: float = Query(..., description="水库的X坐标"),
+    y: float = Query(..., description="水库的Y坐标"),
+    head: float = Query(..., description="水库的水头/总水头（米）")
 ) -> ChangeSet:
+    """
+    添加新的水库/水源节点。
+    
+    在指定的供水网络中创建一个新的水库，并设置其坐标和水头参数。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        x: 水库的X坐标位置
+        y: 水库的Y坐标位置
+        head: 水库的供水水头（以米为单位）
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir, "x": x, "y": y, "head": head}
     return add_reservoir(network, ChangeSet(ps))
 
-@router.post("/deletereservoir/", response_model=None)
-async def fastapi_delete_reservoir(network: str, reservoir: str) -> ChangeSet:
+@router.post(
+    "/deletereservoir/",
+    response_model=None,
+    summary="删除水库",
+    description="从指定供水网络中删除指定的水库/水源节点"
+)
+async def fastapi_delete_reservoir(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="要删除的水库的唯一标识符")
+) -> ChangeSet:
+    """
+    删除指定的水库节点。
+    
+    从指定的供水网络中删除一个水库及其相关的所有连接关系。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir}
     return delete_reservoir(network, ChangeSet(ps))
 
-@router.get("/getreservoirhead/")
-async def fastapi_get_reservoir_head(network: str, reservoir: str) -> float | None:
+@router.get(
+    "/getreservoirhead/",
+    summary="获取水库水头",
+    description="获取指定水库的供水水头/总水头值"
+)
+async def fastapi_get_reservoir_head(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符")
+) -> float | None:
+    """
+    获取水库的水头参数。
+    
+    返回指定水库的供水水头（总水头），单位为米。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        水库的水头值（米），如果水库不存在则返回None
+    """
     ps = get_reservoir(network, reservoir)
     return ps["head"]
 
-@router.get("/getreservoirpattern/")
-async def fastapi_get_reservoir_pattern(network: str, reservoir: str) -> str | None:
+@router.get(
+    "/getreservoirpattern/",
+    summary="获取水库模式",
+    description="获取指定水库的运行模式/供水模式"
+)
+async def fastapi_get_reservoir_pattern(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符")
+) -> str | None:
+    """
+    获取水库的运行模式。
+    
+    返回指定水库的供水模式，如固定水头模式、时间序列模式等。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        水库的运行模式字符串，如果水库不存在则返回None
+    """
     ps = get_reservoir(network, reservoir)
     return ps["pattern"]
 
-@router.get("/getreservoirx/")
+@router.get(
+    "/getreservoirx/",
+    summary="获取水库X坐标",
+    description="获取指定水库的X坐标位置"
+)
 async def fastapi_get_reservoir_x(
-    network: str, reservoir: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符")
 ) -> dict[str, float] | None:
+    """
+    获取水库的X坐标。
+    
+    返回指定水库的X轴坐标值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        水库的X坐标值，如果水库不存在则返回None
+    """
     ps = get_reservoir(network, reservoir)
     return ps["x"]
 
-@router.get("/getreservoiry/")
+@router.get(
+    "/getreservoiry/",
+    summary="获取水库Y坐标",
+    description="获取指定水库的Y坐标位置"
+)
 async def fastapi_get_reservoir_y(
-    network: str, reservoir: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符")
 ) -> dict[str, float] | None:
+    """
+    获取水库的Y坐标。
+    
+    返回指定水库的Y轴坐标值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        水库的Y坐标值，如果水库不存在则返回None
+    """
     ps = get_reservoir(network, reservoir)
     return ps["y"]
 
-@router.get("/getreservoircoord/")
+@router.get(
+    "/getreservoircoord/",
+    summary="获取水库坐标",
+    description="获取指定水库的平面坐标（X和Y坐标）"
+)
 async def fastapi_get_reservoir_coord(
-    network: str, reservoir: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符")
 ) -> dict[str, float] | None:
+    """
+    获取水库的坐标。
+    
+    返回指定水库的平面坐标，包含水库ID、X坐标和Y坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        包含water库ID和X、Y坐标的字典，如果水库不存在则返回None
+    """
     ps = get_reservoir(network, reservoir)
     coord = {"id": reservoir, "x": ps["x"], "y": ps["y"]}
     return coord
 
-@router.post("/setreservoirhead/", response_model=None)
+@router.post(
+    "/setreservoirhead/",
+    response_model=None,
+    summary="设置水库水头",
+    description="更新指定水库的供水水头/总水头值"
+)
 async def fastapi_set_reservoir_head(
-    network: str, reservoir: str, head: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    head: float = Query(..., description="新的水头值（米）")
 ) -> ChangeSet:
+    """
+    设置水库的水头参数。
+    
+    更新指定水库的供水水头（总水头）值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        head: 新的水头值（以米为单位）
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir, "head": head}
     return set_reservoir(network, ChangeSet(ps))
 
-@router.post("/setreservoirpattern/", response_model=None)
+@router.post(
+    "/setreservoirpattern/",
+    response_model=None,
+    summary="设置水库模式",
+    description="更新指定水库的运行模式/供水模式"
+)
 async def fastapi_set_reservoir_pattern(
-    network: str, reservoir: str, pattern: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    pattern: str = Query(..., description="新的运行模式")
 ) -> ChangeSet:
+    """
+    设置水库的运行模式。
+    
+    更新指定水库的供水模式，如固定水头模式、时间序列模式等。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        pattern: 新的运行模式字符串
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir, "pattern": pattern}
     return set_reservoir(network, ChangeSet(ps))
 
-@router.post("/setreservoirx/", response_model=None)
-async def fastapi_set_reservoir_x(network: str, reservoir: str, x: float) -> ChangeSet:
+@router.post(
+    "/setreservoirx/",
+    response_model=None,
+    summary="设置水库X坐标",
+    description="更新指定水库的X坐标位置"
+)
+async def fastapi_set_reservoir_x(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    x: float = Query(..., description="新的X坐标值")
+) -> ChangeSet:
+    """
+    设置水库的X坐标。
+    
+    更新指定水库的X轴坐标值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        x: 新的X坐标值
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir, "x": x}
     return set_reservoir(network, ChangeSet(ps))
 
-@router.post("/setreservoiry/", response_model=None)
-async def fastapi_set_reservoir_y(network: str, reservoir: str, y: float) -> ChangeSet:
+@router.post(
+    "/setreservoiry/",
+    response_model=None,
+    summary="设置水库Y坐标",
+    description="更新指定水库的Y坐标位置"
+)
+async def fastapi_set_reservoir_y(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    y: float = Query(..., description="新的Y坐标值")
+) -> ChangeSet:
+    """
+    设置水库的Y坐标。
+    
+    更新指定水库的Y轴坐标值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        y: 新的Y坐标值
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir, "y": y}
     return set_reservoir(network, ChangeSet(ps))
 
-@router.post("/setreservoircoord/", response_model=None)
+@router.post(
+    "/setreservoircoord/",
+    response_model=None,
+    summary="设置水库坐标",
+    description="更新指定水库的平面坐标（X和Y坐标）"
+)
 async def fastapi_set_reservoir_coord(
-    network: str, reservoir: str, x: float, y: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    x: float = Query(..., description="新的X坐标值"),
+    y: float = Query(..., description="新的Y坐标值")
 ) -> ChangeSet:
+    """
+    设置水库的坐标。
+    
+    更新指定水库的平面坐标，包括X和Y坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        x: 新的X坐标值
+        y: 新的Y坐标值
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     ps = {"id": reservoir, "x": x, "y": y}
     return set_reservoir(network, ChangeSet(ps))
 
-@router.get("/getreservoirproperties/")
+@router.get(
+    "/getreservoirproperties/",
+    summary="获取水库属性",
+    description="获取指定水库的所有属性"
+)
 async def fastapi_get_reservoir_properties(
-    network: str, reservoir: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符")
 ) -> dict[str, Any]:
+    """
+    获取水库的所有属性。
+    
+    返回指定水库的完整属性信息，包括ID、坐标、水头、模式等所有属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        
+    Returns:
+        包含水库所有属性的字典
+    """
     return get_reservoir(network, reservoir)
 
-@router.get("/getallreservoirproperties/")
-async def fastapi_get_all_reservoir_properties(network: str) -> list[dict[str, Any]]:
-    # 缓存查询结果提高性能
-    # global redis_client
+@router.get(
+    "/getallreservoirproperties/",
+    summary="获取所有水库属性",
+    description="获取指定供水网络中所有水库的属性"
+)
+async def fastapi_get_all_reservoir_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取所有水库的属性。
+    
+    返回指定供水网络中所有水库的完整属性信息列表。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含所有水库属性的字典列表
+    """
     results = get_all_reservoirs(network)
     return results
 
-@router.post("/setreservoirproperties/", response_model=None)
+@router.post(
+    "/setreservoirproperties/",
+    response_model=None,
+    summary="设置水库属性",
+    description="批量更新指定水库的多个属性"
+)
 async def fastapi_set_reservoir_properties(
-    network: str, reservoir: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    reservoir: str = Query(..., description="水库的唯一标识符"),
+    req: Request = None
 ) -> ChangeSet:
+    """
+    设置水库的多个属性。
+    
+    批量更新指定水库的属性。属性通过JSON请求体传递。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        reservoir: 水库的唯一标识符
+        req: HTTP请求对象，包含JSON格式的属性数据
+        
+    Returns:
+        包含操作变更集的ChangeSet对象
+    """
     props = await req.json()
     ps = {"id": reservoir} | props
     return set_reservoir(network, ChangeSet(ps))

app/api/v1/endpoints/network/tags.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -15,20 +15,52 @@ router = APIRouter()
 # tag 8.[TAGS]
 ############################################################
 
-@router.get("/gettagschema/")
-async def fastapi_get_tag_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/gettagschema/",
+    summary="获取标签属性架构",
+    description="获取指定水网的标签(Tag)属性架构定义"
+)
+async def fastapi_get_tag_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """获取标签的属性架构。"""
     return get_tag_schema(network)
 
-@router.get("/gettag/")
-async def fastapi_get_tag(network: str, t_type: str, id: str) -> dict[str, Any]:
+@router.get(
+    "/gettag/",
+    summary="获取标签信息",
+    description="获取指定类型和ID的标签信息"
+)
+async def fastapi_get_tag(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    t_type: str = Query(..., description="标签类型"),
+    id: str = Query(..., description="元素ID")
+) -> dict[str, Any]:
+    """获取标签信息。"""
     return get_tag(network, t_type, id)
 
-@router.get("/gettags/")
-async def fastapi_get_tags(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/gettags/",
+    summary="获取所有标签",
+    description="获取指定水网中的所有标签信息"
+)
+async def fastapi_get_tags(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """获取水网中所有标签的列表。"""
     tags = get_tags(network)
     return tags
 
-@router.post("/settag/", response_model=None)
-async def fastapi_set_tag(network: str, req: Request) -> ChangeSet:
+@router.post(
+    "/settag/",
+    response_model=None,
+    summary="设置标签",
+    description="为指定元素设置或修改标签信息"
+)
+async def fastapi_set_tag(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """设置标签信息。"""
     props = await req.json()
     return set_tag(network, ChangeSet(props))

app/api/v1/endpoints/network/tanks.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -13,23 +13,50 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/gettankschema")
-async def fast_get_tank_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/gettankschema", summary="获取水箱模式", description="获取指定网络的水箱数据结构模式定义")
+async def fast_get_tank_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """
+    获取水箱的数据结构模式。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含水箱属性的模式定义字典
+    """
     return get_tank_schema(network)
 
-@router.post("/addtank/", response_model=None)
+@router.post("/addtank/", summary="新增水箱", description="向指定网络中新增一个水箱", response_model=None)
 async def fastapi_add_tank(
-    network: str,
-    tank: str,
-    x: float,
-    y: float,
-    elevation: float,
-    init_level: float = 0,
-    min_level: float = 0,
-    max_level: float = 0,
-    diameter: float = 0,
-    min_vol: float = 0,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    x: float = Query(..., description="X坐标"),
+    y: float = Query(..., description="Y坐标"),
+    elevation: float = Query(..., description="标高"),
+    init_level: float = Query(0, description="初始水位"),
+    min_level: float = Query(0, description="最小水位"),
+    max_level: float = Query(0, description="最大水位"),
+    diameter: float = Query(0, description="直径"),
+    min_vol: float = Query(0, description="最小体积"),
 ) -> ChangeSet:
+    """
+    创建新水箱。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        x: X坐标
+        y: Y坐标
+        elevation: 水箱标高
+        init_level: 初始水位，默认为0
+        min_level: 最小水位，默认为0
+        max_level: 最大水位，默认为0
+        diameter: 水箱直径，默认为0
+        min_vol: 最小体积，默认为0
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {
         "id": tank,
         "x": x,
@@ -43,155 +70,497 @@ async def fastapi_add_tank(
     }
     return add_tank(network, ChangeSet(ps))
 
-@router.post("/deletetank/", response_model=None)
-async def fastapi_delete_tank(network: str, tank: str) -> ChangeSet:
+@router.post("/deletetank/", summary="删除水箱", description="删除指定网络中的水箱", response_model=None)
+async def fastapi_delete_tank(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> ChangeSet:
+    """
+    删除指定的水箱。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank}
     return delete_tank(network, ChangeSet(ps))
 
-@router.get("/gettankelevation/")
-async def fastapi_get_tank_elevation(network: str, tank: str) -> float | None:
+@router.get("/gettankelevation/", summary="获取水箱标高", description="获取指定水箱的标高值")
+async def fastapi_get_tank_elevation(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float | None:
+    """
+    获取水箱的标高。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱标高值，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["elevation"]
 
-@router.get("/gettankinitlevel/")
-async def fastapi_get_tank_init_level(network: str, tank: str) -> float | None:
+@router.get("/gettankinitlevel/", summary="获取水箱初始水位", description="获取指定水箱的初始水位值")
+async def fastapi_get_tank_init_level(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float | None:
+    """
+    获取水箱的初始水位。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱初始水位值，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["init_level"]
 
-@router.get("/gettankminlevel/")
-async def fastapi_get_tank_min_level(network: str, tank: str) -> float | None:
+@router.get("/gettankminlevel/", summary="获取水箱最小水位", description="获取指定水箱的最小水位值")
+async def fastapi_get_tank_min_level(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float | None:
+    """
+    获取水箱的最小水位。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱最小水位值，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["min_level"]
 
-@router.get("/gettankmaxlevel/")
-async def fastapi_get_tank_max_level(network: str, tank: str) -> float | None:
+@router.get("/gettankmaxlevel/", summary="获取水箱最大水位", description="获取指定水箱的最大水位值")
+async def fastapi_get_tank_max_level(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float | None:
+    """
+    获取水箱的最大水位。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱最大水位值，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["max_level"]
 
-@router.get("/gettankdiameter/")
-async def fastapi_get_tank_diameter(network: str, tank: str) -> float | None:
+@router.get("/gettankdiameter/", summary="获取水箱直径", description="获取指定水箱的直径值")
+async def fastapi_get_tank_diameter(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float | None:
+    """
+    获取水箱的直径。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱直径值，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["diameter"]
 
-@router.get("/gettankminvol/")
-async def fastapi_get_tank_min_vol(network: str, tank: str) -> float | None:
+@router.get("/gettankminvol/", summary="获取水箱最小体积", description="获取指定水箱的最小体积值")
+async def fastapi_get_tank_min_vol(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float | None:
+    """
+    获取水箱的最小体积。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱最小体积值，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["min_vol"]
 
-@router.get("/gettankvolcurve/")
-async def fastapi_get_tank_vol_curve(network: str, tank: str) -> str | None:
+@router.get("/gettankvolcurve/", summary="获取水箱容积曲线", description="获取指定水箱的容积曲线标识")
+async def fastapi_get_tank_vol_curve(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> str | None:
+    """
+    获取水箱的容积曲线。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱容积曲线标识，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["vol_curve"]
 
-@router.get("/gettankoverflow/")
-async def fastapi_get_tank_overflow(network: str, tank: str) -> str | None:
+@router.get("/gettankoverflow/", summary="获取水箱溢流口", description="获取指定水箱的溢流口配置")
+async def fastapi_get_tank_overflow(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> str | None:
+    """
+    获取水箱的溢流口配置。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱溢流口配置，如果不存在则返回None
+    """
     ps = get_tank(network, tank)
     return ps["overflow"]
 
-@router.get("/gettankx/")
-async def fastapi_get_tank_x(network: str, tank: str) -> float:
+@router.get("/gettankx/", summary="获取水箱X坐标", description="获取指定水箱的X坐标值")
+async def fastapi_get_tank_x(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float:
+    """
+    获取水箱的X坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱X坐标值
+    """
     ps = get_tank(network, tank)
     return ps["x"]
 
-@router.get("/gettanky/")
-async def fastapi_get_tank_y(network: str, tank: str) -> float:
+@router.get("/gettanky/", summary="获取水箱Y坐标", description="获取指定水箱的Y坐标值")
+async def fastapi_get_tank_y(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> float:
+    """
+    获取水箱的Y坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        水箱Y坐标值
+    """
     ps = get_tank(network, tank)
     return ps["y"]
 
-@router.get("/gettankcoord/")
-async def fastapi_get_tank_coord(network: str, tank: str) -> dict[str, float]:
+@router.get("/gettankcoord/", summary="获取水箱坐标", description="获取指定水箱的X和Y坐标")
+async def fastapi_get_tank_coord(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> dict[str, float]:
+    """
+    获取水箱的坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        包含x和y坐标的字典
+    """
     ps = get_tank(network, tank)
     coord = {"x": ps["x"], "y": ps["y"]}
     return coord
 
-@router.post("/settankelevation/", response_model=None)
+@router.post("/settankelevation/", summary="设置水箱标高", description="设置指定水箱的标高值", response_model=None)
 async def fastapi_set_tank_elevation(
-    network: str, tank: str, elevation: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    elevation: float = Query(..., description="新的标高值")
 ) -> ChangeSet:
+    """
+    设置水箱的标高。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        elevation: 新的标高值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "elevation": elevation}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankinitlevel/", response_model=None)
+@router.post("/settankinitlevel/", summary="设置水箱初始水位", description="设置指定水箱的初始水位值", response_model=None)
 async def fastapi_set_tank_init_level(
-    network: str, tank: str, init_level: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    init_level: float = Query(..., description="新的初始水位值")
 ) -> ChangeSet:
+    """
+    设置水箱的初始水位。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        init_level: 新的初始水位值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "init_level": init_level}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankminlevel/", response_model=None)
+@router.post("/settankminlevel/", summary="设置水箱最小水位", description="设置指定水箱的最小水位值", response_model=None)
 async def fastapi_set_tank_min_level(
-    network: str, tank: str, min_level: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    min_level: float = Query(..., description="新的最小水位值")
 ) -> ChangeSet:
+    """
+    设置水箱的最小水位。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        min_level: 新的最小水位值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "min_level": min_level}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankmaxlevel/", response_model=None)
+@router.post("/settankmaxlevel/", summary="设置水箱最大水位", description="设置指定水箱的最大水位值", response_model=None)
 async def fastapi_set_tank_max_level(
-    network: str, tank: str, max_level: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    max_level: float = Query(..., description="新的最大水位值")
 ) -> ChangeSet:
+    """
+    设置水箱的最大水位。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        max_level: 新的最大水位值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "max_level": max_level}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("settankdiameter//", response_model=None)
+@router.post("/settankdiameter/", summary="设置水箱直径", description="设置指定水箱的直径值", response_model=None)
 async def fastapi_set_tank_diameter(
-    network: str, tank: str, diameter: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    diameter: float = Query(..., description="新的直径值")
 ) -> ChangeSet:
+    """
+    设置水箱的直径。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        diameter: 新的直径值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "diameter": diameter}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankminvol/", response_model=None)
+@router.post("/settankminvol/", summary="设置水箱最小体积", description="设置指定水箱的最小体积值", response_model=None)
 async def fastapi_set_tank_min_vol(
-    network: str, tank: str, min_vol: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    min_vol: float = Query(..., description="新的最小体积值")
 ) -> ChangeSet:
+    """
+    设置水箱的最小体积。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        min_vol: 新的最小体积值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "min_vol": min_vol}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankvolcurve/", response_model=None)
+@router.post("/settankvolcurve/", summary="设置水箱容积曲线", description="设置指定水箱的容积曲线标识", response_model=None)
 async def fastapi_set_tank_vol_curve(
-    network: str, tank: str, vol_curve: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    vol_curve: str = Query(..., description="新的容积曲线标识")
 ) -> ChangeSet:
+    """
+    设置水箱的容积曲线。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        vol_curve: 新的容积曲线标识
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "vol_curve": vol_curve}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankoverflow/", response_model=None)
+@router.post("/settankoverflow/", summary="设置水箱溢流口", description="设置指定水箱的溢流口配置", response_model=None)
 async def fastapi_set_tank_overflow(
-    network: str, tank: str, overflow: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    overflow: str = Query(..., description="新的溢流口配置")
 ) -> ChangeSet:
+    """
+    设置水箱的溢流口配置。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        overflow: 新的溢流口配置
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "overflow": overflow}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankx/", response_model=None)
-async def fastapi_set_tank_x(network: str, tank: str, x: float) -> ChangeSet:
+@router.post("/settankx/", summary="设置水箱X坐标", description="设置指定水箱的X坐标值", response_model=None)
+async def fastapi_set_tank_x(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    x: float = Query(..., description="新的X坐标值")
+) -> ChangeSet:
+    """
+    设置水箱的X坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        x: 新的X坐标值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "x": x}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settanky/", response_model=None)
-async def fastapi_set_tank_y(network: str, tank: str, y: float) -> ChangeSet:
+@router.post("/settanky/", summary="设置水箱Y坐标", description="设置指定水箱的Y坐标值", response_model=None)
+async def fastapi_set_tank_y(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    y: float = Query(..., description="新的Y坐标值")
+) -> ChangeSet:
+    """
+    设置水箱的Y坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        y: 新的Y坐标值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "y": y}
     return set_tank(network, ChangeSet(ps))
 
-@router.post("/settankcoord/", response_model=None)
+@router.post("/settankcoord/", summary="设置水箱坐标", description="设置指定水箱的X和Y坐标", response_model=None)
 async def fastapi_set_tank_coord(
-    network: str, tank: str, x: float, y: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    x: float = Query(..., description="新的X坐标值"),
+    y: float = Query(..., description="新的Y坐标值")
 ) -> ChangeSet:
+    """
+    设置水箱的坐标。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        x: 新的X坐标值
+        y: 新的Y坐标值
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     ps = {"id": tank, "x": x, "y": y}
     return set_tank(network, ChangeSet(ps))
 
-@router.get("/gettankproperties/")
-async def fastapi_get_tank_properties(network: str, tank: str) -> dict[str, Any]:
+@router.get("/gettankproperties/", summary="获取水箱属性", description="获取指定水箱的所有属性")
+async def fastapi_get_tank_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID")
+) -> dict[str, Any]:
+    """
+    获取水箱的所有属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        
+    Returns:
+        包含水箱所有属性的字典
+    """
     return get_tank(network, tank)
 
-@router.get("/getalltankproperties/")
-async def fastapi_get_all_tank_properties(network: str) -> list[dict[str, Any]]:
+@router.get("/getalltankproperties/", summary="获取所有水箱属性", description="获取指定网络中所有水箱的属性")
+async def fastapi_get_all_tank_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取网络中所有水箱的属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含所有水箱属性的字典列表
+    """
     # 缓存查询结果提高性能
     # global redis_client
     results = get_all_tanks(network)
     return results
 
-@router.post("/settankproperties/", response_model=None)
+@router.post("/settankproperties/", summary="设置水箱属性", description="批量设置指定水箱的多个属性", response_model=None)
 async def fastapi_set_tank_properties(
-    network: str, tank: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    tank: str = Query(..., description="水箱ID"),
+    req: Request = None
 ) -> ChangeSet:
+    """
+    批量设置水箱的属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        tank: 水箱ID
+        req: 包含水箱属性的请求体（JSON格式）
+        
+    Returns:
+        包含变更信息的ChangeSet对象
+    """
     props = await req.json()
     ps = {"id": tank} | props
     return set_tank(network, ChangeSet(ps))

app/api/v1/endpoints/network/valves.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -14,21 +14,42 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getvalveschema")
-async def fastapi_get_valve_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get(
+    "/getvalveschema",
+    summary="获取阀门架构",
+    description="获取指定水网中所有阀门的架构和字段定义",
+)
+async def fastapi_get_valve_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取阀门架构。
+    
+    返回指定水网中所有阀门类型的完整架构定义，包括字段名称、类型和默认值。
+    """
     return get_valve_schema(network)
 
-@router.post("/addvalve/", response_model=None)
+@router.post(
+    "/addvalve/",
+    response_model=None,
+    summary="添加阀门",
+    description="在指定的水网中添加新的阀门",
+)
 async def fastapi_add_valve(
-    network: str,
-    valve: str,
-    node1: str,
-    node2: str,
-    diameter: float = 0,
-    v_type: str = VALVES_TYPE_PRV,
-    setting: float = 0,
-    minor_loss: float = 0,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    node1: str = Query(..., description="起点节点ID"),
+    node2: str = Query(..., description="终点节点ID"),
+    diameter: float = Query(0, description="阀门直径（mm）"),
+    v_type: str = Query(VALVES_TYPE_PRV, description="阀门类型"),
+    setting: float = Query(0, description="阀门开度/设置值"),
+    minor_loss: float = Query(0, description="损失系数"),
 ) -> ChangeSet:
+    """
+    添加新的阀门。
+    
+    在指定的水网中创建一个新的阀门，设置其连接的两个节点、直径、类型、开度和损失系数。
+    """
     ps = {
         "id": valve,
         "node1": node1,
@@ -41,85 +62,271 @@ async def fastapi_add_valve(
 
     return add_valve(network, ChangeSet(ps))
 
-@router.post("/deletevalve/", response_model=None)
-async def fastapi_delete_valve(network: str, valve: str) -> ChangeSet:
+@router.post(
+    "/deletevalve/",
+    response_model=None,
+    summary="删除阀门",
+    description="从指定的水网中删除指定的阀门",
+)
+async def fastapi_delete_valve(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> ChangeSet:
+    """
+    删除阀门。
+    
+    从指定的水网中删除指定ID的阀门。
+    """
     ps = {"id": valve}
     return delete_valve(network, ChangeSet(ps))
 
-@router.get("/getvalvenode1/")
-async def fastapi_get_valve_node1(network: str, valve: str) -> str | None:
+@router.get(
+    "/getvalvenode1/",
+    summary="获取阀门起点节点",
+    description="获取指定阀门连接的起点节点ID",
+)
+async def fastapi_get_valve_node1(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> str | None:
+    """
+    获取阀门的起点节点。
+    
+    返回指定阀门连接的起点（第一个）节点的ID。
+    """
     ps = get_valve(network, valve)
     return ps["node1"]
 
-@router.get("/getvalvenode2/")
-async def fastapi_get_valve_node2(network: str, valve: str) -> str | None:
+@router.get(
+    "/getvalvenode2/",
+    summary="获取阀门终点节点",
+    description="获取指定阀门连接的终点节点ID",
+)
+async def fastapi_get_valve_node2(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> str | None:
+    """
+    获取阀门的终点节点。
+    
+    返回指定阀门连接的终点（第二个）节点的ID。
+    """
     ps = get_valve(network, valve)
     return ps["node2"]
 
-@router.get("/getvalvediameter/")
-async def fastapi_get_valve_diameter(network: str, valve: str) -> float | None:
+@router.get(
+    "/getvalvediameter/",
+    summary="获取阀门直径",
+    description="获取指定阀门的直径",
+)
+async def fastapi_get_valve_diameter(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> float | None:
+    """
+    获取阀门的直径。
+    
+    返回指定阀门的直径值（单位：mm）。
+    """
     ps = get_valve(network, valve)
     return ps["diameter"]
 
-@router.get("/getvalvetype/")
-async def fastapi_get_valve_type(network: str, valve: str) -> str | None:
+@router.get(
+    "/getvalvetype/",
+    summary="获取阀门类型",
+    description="获取指定阀门的类型",
+)
+async def fastapi_get_valve_type(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> str | None:
+    """
+    获取阀门的类型。
+    
+    返回指定阀门的类型（例如：减压阀、调节阀等）。
+    """
     ps = get_valve(network, valve)
     return ps["type"]
 
-@router.get("/getvalvesetting/")
-async def fastapi_get_valve_setting(network: str, valve: str) -> float | None:
+@router.get(
+    "/getvalvesetting/",
+    summary="获取阀门开度",
+    description="获取指定阀门的开度/设置值",
+)
+async def fastapi_get_valve_setting(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> float | None:
+    """
+    获取阀门的开度。
+    
+    返回指定阀门的开度/设置值。
+    """
     ps = get_valve(network, valve)
     return ps["setting"]
 
-@router.get("/getvalveminorloss/")
-async def fastapi_get_valve_minor_loss(network: str, valve: str) -> float | None:
+@router.get(
+    "/getvalveminorloss/",
+    summary="获取阀门损失系数",
+    description="获取指定阀门的损失系数",
+)
+async def fastapi_get_valve_minor_loss(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> float | None:
+    """
+    获取阀门的损失系数。
+    
+    返回指定阀门的损失系数值，用于计算流体通过阀门的压力损失。
+    """
     ps = get_valve(network, valve)
     return ps["minor_loss"]
 
-@router.post("/setvalvenode1/", response_model=None)
-async def fastapi_set_valve_node1(network: str, valve: str, node1: str) -> ChangeSet:
+@router.post(
+    "/setvalvenode1/",
+    response_model=None,
+    summary="设置阀门起点节点",
+    description="设置指定阀门的起点节点",
+)
+async def fastapi_set_valve_node1(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    node1: str = Query(..., description="新的起点节点ID"),
+) -> ChangeSet:
+    """
+    设置阀门的起点节点。
+    
+    更新指定阀门的起点节点连接。
+    """
     ps = {"id": valve, "node1": node1}
     return set_valve(network, ChangeSet(ps))
 
-@router.post("/setvalvenode2/", response_model=None)
-async def fastapi_set_valve_node2(network: str, valve: str, node2: str) -> ChangeSet:
+@router.post(
+    "/setvalvenode2/",
+    response_model=None,
+    summary="设置阀门终点节点",
+    description="设置指定阀门的终点节点",
+)
+async def fastapi_set_valve_node2(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    node2: str = Query(..., description="新的终点节点ID"),
+) -> ChangeSet:
+    """
+    设置阀门的终点节点。
+    
+    更新指定阀门的终点节点连接。
+    """
     ps = {"id": valve, "node2": node2}
     return set_valve(network, ChangeSet(ps))
 
-@router.post("/setvalvenodediameter/", response_model=None)
+@router.post(
+    "/setvalvenodediameter/",
+    response_model=None,
+    summary="设置阀门直径",
+    description="设置指定阀门的直径",
+)
 async def fastapi_set_valve_diameter(
-    network: str, valve: str, diameter: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    diameter: float = Query(..., description="新的直径值（mm）"),
 ) -> ChangeSet:
+    """
+    设置阀门的直径。
+    
+    更新指定阀门的直径值。
+    """
     ps = {"id": valve, "diameter": diameter}
     return set_valve(network, ChangeSet(ps))
 
-@router.post("/setvalvetype/", response_model=None)
-async def fastapi_set_valve_type(network: str, valve: str, type: str) -> ChangeSet:
+@router.post(
+    "/setvalvetype/",
+    response_model=None,
+    summary="设置阀门类型",
+    description="设置指定阀门的类型",
+)
+async def fastapi_set_valve_type(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    type: str = Query(..., description="新的阀门类型"),
+) -> ChangeSet:
+    """
+    设置阀门的类型。
+    
+    更新指定阀门的类型（例如：减压阀、调节阀等）。
+    """
     ps = {"id": valve, "type": type}
     return set_valve(network, ChangeSet(ps))
 
-@router.post("/setvalvesetting/", response_model=None)
+@router.post(
+    "/setvalvesetting/",
+    response_model=None,
+    summary="设置阀门开度",
+    description="设置指定阀门的开度/设置值",
+)
 async def fastapi_set_valve_setting(
-    network: str, valve: str, setting: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    setting: float = Query(..., description="新的开度值"),
 ) -> ChangeSet:
+    """
+    设置阀门的开度。
+    
+    更新指定阀门的开度/设置值。
+    """
     ps = {"id": valve, "setting": setting}
     return set_valve(network, ChangeSet(ps))
 
-@router.get("/getvalveproperties/")
-async def fastapi_get_valve_properties(network: str, valve: str) -> dict[str, Any]:
+@router.get(
+    "/getvalveproperties/",
+    summary="获取阀门所有属性",
+    description="获取指定阀门的所有属性",
+)
+async def fastapi_get_valve_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+) -> dict[str, Any]:
+    """
+    获取阀门的所有属性。
+    
+    返回指定阀门的完整属性集合，包括ID、节点、直径、类型、开度和损失系数。
+    """
     return get_valve(network, valve)
 
-@router.get("/getallvalveproperties/")
-async def fastapi_get_all_valve_properties(network: str) -> list[dict[str, Any]]:
+@router.get(
+    "/getallvalveproperties/",
+    summary="获取所有阀门属性",
+    description="获取指定水网中所有阀门的属性",
+)
+async def fastapi_get_all_valve_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取所有阀门的属性。
+    
+    返回指定水网中所有阀门的完整属性列表。
+    """
     # 缓存查询结果提高性能
     # global redis_client
     results = get_all_valves(network)
     return results
 
-@router.post("/setvalveproperties/", response_model=None)
+@router.post(
+    "/setvalveproperties/",
+    response_model=None,
+    summary="批量设置阀门属性",
+    description="批量设置指定阀门的多个属性",
+)
 async def fastapi_set_valve_properties(
-    network: str, valve: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve: str = Query(..., description="阀门ID"),
+    req: Request = None,
 ) -> ChangeSet:
+    """
+    批量设置阀门的属性。
+    
+    更新指定阀门的一个或多个属性，通过JSON请求体传递要更新的属性。
+    """
     props = await req.json()
     ps = {"id": valve} | props
     return set_valve(network, ChangeSet(ps))

app/api/v1/endpoints/project.py

@@ -1,7 +1,10 @@
 import json
-from fastapi import APIRouter, Request, HTTPException
+from fastapi import APIRouter, Request, HTTPException, Query, Path, Body, Depends
 from fastapi.responses import PlainTextResponse
-from typing import Any, Dict
+from typing import Any, Dict, List
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
+from app.auth.project_dependencies import get_metadata_repository
+from app.domain.schemas.metadata import ProjectMetaResponse, GeoServerConfigResponse
 import app.services.project_info as project_info
 from app.infra.db.postgresql.database import get_database_instance as get_pg_db
 from app.infra.db.timescaledb.database import get_database_instance as get_ts_db
@@ -39,30 +42,106 @@ inpDir = "data/" # Assuming data directory exists or is defined somewhere.
 router = APIRouter()
 lockedPrjs: Dict[str, str] = {}
 
-@router.get("/listprojects/")
+@router.get("/project_info/", summary="获取项目信息", description="从数据库获取项目的详细信息，包括地图范围等。", response_model=ProjectMetaResponse)
+async def get_project_info_endpoint(
+    network: str = Query(..., description="管网名称（或项目代码）"),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+):
+    """
+    获取项目信息
+    
+    - **network**: 管网名称（或项目代码）
+    """
+    project_detail = await metadata_repo.get_project_detail_by_code(network)
+    if not project_detail:
+        raise HTTPException(status_code=404, detail=f"Project {network} not found")
+        
+    geoserver_payload = None
+    if project_detail.geoserver:
+         geoserver_payload = GeoServerConfigResponse(
+            gs_base_url=project_detail.geoserver.gs_base_url,
+            gs_admin_user=project_detail.geoserver.gs_admin_user,
+            gs_datastore_name=project_detail.geoserver.gs_datastore_name,
+            default_extent=project_detail.geoserver.default_extent,
+            srid=project_detail.geoserver.srid,
+        )
+
+    return ProjectMetaResponse(
+        project_id=project_detail.project_id,
+        name=project_detail.name,
+        code=project_detail.code,
+        description=project_detail.description,
+        gs_workspace=project_detail.gs_workspace,
+        map_extent=project_detail.map_extent,
+        status=project_detail.status,
+        project_role="viewer", # Default role for public access
+        geoserver=geoserver_payload
+    )
+
+@router.get("/listprojects/", summary="获取项目列表", description="获取服务器上所有可用的供水管网项目名称列表。")
 async def list_projects_endpoint() -> list[str]:
+    """
+    获取项目列表
+
+    返回所有已创建项目的名称列表。
+    """
     return list_project()
 
-@router.get("/haveproject/")
-async def have_project_endpoint(network: str):
+@router.get("/haveproject/", summary="检查项目是否存在", description="检查指定名称的项目是否存在。")
+async def have_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    检查项目是否存在
+
+    - **network**: 管网名称（或数据库名称）
+    """
     return have_project(network)
 
-@router.post("/createproject/")
-async def create_project_endpoint(network: str):
+@router.post("/createproject/", summary="创建新项目", description="创建一个新的供水管网项目。如果项目已存在，可能会覆盖或报错（取决于底层实现）。")
+async def create_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    创建新项目
+
+    - **network**: 管网名称（或数据库名称）
+    """
     create_project(network)
     return network
 
-@router.post("/deleteproject/")
-async def delete_project_endpoint(network: str):
+@router.post("/deleteproject/", summary="删除项目", description="永久删除指定的供水管网项目。此操作不可恢复。")
+async def delete_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    删除项目
+
+    - **network**: 管网名称（或数据库名称）
+    """
     delete_project(network)
     return True
 
-@router.get("/isprojectopen/")
-async def is_project_open_endpoint(network: str):
+@router.get("/isprojectopen/", summary="检查项目是否已打开", description="检查指定项目是否已被加载到内存中。")
+async def is_project_open_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    检查项目是否已打开
+
+    - **network**: 管网名称（或数据库名称）
+    """
     return is_project_open(network)
 
-@router.post("/openproject/")
-async def open_project_endpoint(network: str):
+@router.post("/openproject/", summary="打开项目", description="将指定项目加载到内存中，并初始化数据库连接池。")
+async def open_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    打开项目
+
+    - **network**: 管网名称（或数据库名称）
+    """
     open_project(network)
     
     # 尝试连接指定数据库
@@ -88,18 +167,43 @@ async def open_project_endpoint(network: str):
 
     return network
 
-@router.post("/closeproject/")
-async def close_project_endpoint(network: str):
+@router.post("/closeproject/", summary="关闭项目", description="将指定项目从内存中卸载，释放资源。")
+async def close_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    关闭项目
+
+    - **network**: 管网名称（或数据库名称）
+    """
     close_project(network)
     return True
 
-@router.post("/copyproject/")
-async def copy_project_endpoint(source: str, target: str):
+@router.post("/copyproject/", summary="复制项目", description="将现有项目复制为新项目。")
+async def copy_project_endpoint(
+    source: str = Query(..., description="管网名称（或数据库名称）"),
+    target: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    复制项目
+
+    - **source**: 管网名称（或数据库名称）
+    - **target**: 管网名称（或数据库名称）
+    """
     copy_project(source, target)
     return True
 
-@router.post("/importinp/")
-async def import_inp_endpoint(network: str, req: Request):
+@router.post("/importinp/", summary="导入 INP 文件内容", description="将 INP 格式的文本内容导入到指定项目中。")
+async def import_inp_endpoint(
+    req: Request,
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    导入 INP 文件内容
+
+    - **network**: 管网名称（或数据库名称）
+    - **req**: 请求体，需包含 `{"inp": "..."}` 结构
+    """
     jo_root = await req.json()
     inp_text = jo_root["inp"]
     ps = {"inp": inp_text}
@@ -107,8 +211,17 @@ async def import_inp_endpoint(network: str, req: Request):
     print(ret)
     return ret
 
-@router.get("/exportinp/", response_model=None)
-async def export_inp_endpoint(network: str, version: str) -> ChangeSet:
+@router.get("/exportinp/", response_model=None, summary="导出项目为 ChangeSet", description="导出项目的变更集 (ChangeSet)，包含顶点、SCADA 元素、DMA、SA、VD 等信息。")
+async def export_inp_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    version: str = Query(..., description="版本号 (通常用于增量更新)")
+) -> ChangeSet:
+    """
+    导出项目为 ChangeSet
+
+    - **network**: 管网名称（或数据库名称）
+    - **version**: 版本号
+    """
     cs = export_inp(network, version)
     op = cs.operations[0]
     open_project(network)
@@ -131,30 +244,75 @@ async def export_inp_endpoint(network: str, version: str) -> ChangeSet:
 
     return cs
 
-@router.post("/readinp/")
-async def read_inp_endpoint(network: str, inp: str) -> bool:
+@router.post("/readinp/", summary="读取 INP 文件到项目", description="从服务器文件系统中读取指定的 INP 文件并加载到项目中。")
+async def read_inp_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inp: str = Query(..., description="INP 文件名 (不包含路径)")
+) -> bool:
+    """
+    读取 INP 文件到项目
+
+    - **network**: 管网名称（或数据库名称）
+    - **inp**: INP 文件名
+    """
     read_inp(network, inp)
     return True
 
-@router.get("/dumpinp/")
-async def dump_inp_endpoint(network: str, inp: str) -> bool:
+@router.get("/dumpinp/", summary="导出项目到 INP 文件", description="将项目当前状态保存为 INP 文件到服务器文件系统。")
+async def dump_inp_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inp: str = Query(..., description="目标文件名")
+) -> bool:
+    """
+    导出项目到 INP 文件
+
+    - **network**: 管网名称（或数据库名称）
+    - **inp**: 目标文件名
+    """
     dump_inp(network, inp)
     return True
 
-@router.get("/isprojectlocked/")
-async def is_project_locked_endpoint(network: str, req: Request):
+@router.get("/isprojectlocked/", summary="检查项目是否被锁定", description="检查指定项目是否处于锁定状态。")
+async def is_project_locked_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    检查项目是否被锁定
+
+    - **network**: 管网名称（或数据库名称）
+    """
     return network in lockedPrjs.keys()
 
-@router.get("/isprojectlockedbyme/")
-async def is_project_locked_by_me_endpoint(network: str, req: Request):
+@router.get("/isprojectlockedbyme/", summary="检查项目是否被当前用户锁定", description="检查指定项目是否被当前客户端 (IP) 锁定。")
+async def is_project_locked_by_me_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    检查项目是否被当前用户锁定
+
+    - **network**: 管网名称（或数据库名称）
+    """
     client_host = req.client.host
     return lockedPrjs.get(network) == client_host
 
 # 0 successfully locked
 # 1 already locked by you
 # 2 locked by others
-@router.post("/lockproject/")
-async def lock_project_endpoint(network: str, req: Request):
+@router.post("/lockproject/", summary="锁定项目", description="锁定指定项目以防止并发修改。")
+async def lock_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    锁定项目
+
+    返回值:
+    - **0**: 锁定成功
+    - **1**: 已被当前用户锁定
+    - **2**: 已被其他用户锁定
+    """
     client_host = req.client.host
     if not network in lockedPrjs.keys():
         lockedPrjs[network] = client_host
@@ -165,8 +323,16 @@ async def lock_project_endpoint(network: str, req: Request):
         else:
             return 2
 
-@router.post("/unlockproject/")
-def unlock_project_endpoint(network: str, req: Request):
+@router.post("/unlockproject/", summary="解锁项目", description="释放对项目的锁定。")
+def unlock_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    解锁项目
+
+    只有锁定者才能解锁。
+    """
     client_host = req.client.host
     if lockedPrjs.get(network) == client_host:
         print("delete key")
@@ -176,8 +342,17 @@ def unlock_project_endpoint(network: str, req: Request):
     return False
 
 # inp file operations
-@router.post("/uploadinp/", status_code=status.HTTP_200_OK)
-async def fastapi_upload_inp(afile: bytes, name: str):
+@router.post("/uploadinp/", status_code=status.HTTP_200_OK, summary="上传 INP 文件", description="上传 INP 文件到服务器数据目录。")
+async def fastapi_upload_inp(
+    afile: bytes = Body(..., description="文件二进制内容"),
+    name: str = Query(..., description="保存的文件名")
+):
+    """
+    上传 INP 文件
+
+    - **afile**: 文件内容
+    - **name**: 文件名
+    """
     if not os.path.exists(inpDir):
         os.makedirs(inpDir, exist_ok=True)
         
@@ -186,8 +361,16 @@ async def fastapi_upload_inp(afile: bytes, name: str):
         f.write(afile)
     return True
 
-@router.get("/downloadinp/", status_code=status.HTTP_200_OK)
-async def fastapi_download_inp(name: str, response: Response):
+@router.get("/downloadinp/", status_code=status.HTTP_200_OK, summary="下载 INP 文件", description="从服务器数据目录下载指定的 INP 文件。")
+async def fastapi_download_inp(
+    name: str = Query(..., description="文件名"),
+    response: Response = None
+):
+    """
+    下载 INP 文件
+
+    - **name**: 文件名
+    """
     filePath = inpDir + name
     if os.path.exists(filePath):
         return FileResponse(
@@ -198,8 +381,186 @@ async def fastapi_download_inp(name: str, response: Response):
         return True
 
 # DingZQ, 2024-12-28, convert v3 to v2
-@router.get("/convertv3tov2/", response_model=None)
-async def fastapi_convert_v3_to_v2(req: Request) -> ChangeSet:
+@router.get("/convertv3tov2/", response_model=None, summary="转换 INP V3 为 V2", description="将 EPANET 3.0 格式的 INP 内容转换为 2.x 格式。")
+async def fastapi_convert_v3_to_v2(
+    req: Request
+) -> ChangeSet:
+    """
+    转换 INP V3 为 V2
+
+    - **req**: 请求体，需包含 `{"inp": "..."}` 结构
+    """
+    network = "v3Tov2"
+    jo_root = await req.json()
+    inp = jo_root["inp"]
+    cs = convert_inp_v3_to_v2(inp)
+    op = cs.operations[0]
+    open_project(network)
+    op["vertex"] = json.dumps(get_all_vertices(network))
+    op["scada"] = json.dumps(get_all_scada_elements(network))
+    op["dma"] = json.dumps(get_all_district_metering_areas(network))
+    op["sa"] = json.dumps(get_all_service_areas(network))
+    op["vd"] = json.dumps(get_all_virtual_districts(network))
+    op["legend"] = get_extension_data(network, "legend")
+
+    db = get_extension_data(network, "scada_db")
+    print(db)
+    scada_db = ""
+    if db:
+        scada_db = db
+    print(scada_db)
+    op["scada_db"] = scada_db
+
+    close_project(network)
+
+    return cs
+
+@router.post("/readinp/", summary="读取 INP 文件到项目", description="从服务器文件系统中读取指定的 INP 文件并加载到项目中。")
+async def read_inp_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inp: str = Query(..., description="INP 文件名 (不包含路径)")
+) -> bool:
+    """
+    读取 INP 文件到项目
+
+    - **network**: 管网名称（或数据库名称）
+    - **inp**: INP 文件名
+    """
+    read_inp(network, inp)
+    return True
+
+@router.get("/dumpinp/", summary="导出项目到 INP 文件", description="将项目当前状态保存为 INP 文件到服务器文件系统。")
+async def dump_inp_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    inp: str = Query(..., description="目标文件名")
+) -> bool:
+    """
+    导出项目到 INP 文件
+
+    - **network**: 管网名称（或数据库名称）
+    - **inp**: 目标文件名
+    """
+    dump_inp(network, inp)
+    return True
+
+@router.get("/isprojectlocked/", summary="检查项目是否被锁定", description="检查指定项目是否处于锁定状态。")
+async def is_project_locked_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    检查项目是否被锁定
+
+    - **network**: 管网名称（或数据库名称）
+    """
+    return network in lockedPrjs.keys()
+
+@router.get("/isprojectlockedbyme/", summary="检查项目是否被当前用户锁定", description="检查指定项目是否被当前客户端 (IP) 锁定。")
+async def is_project_locked_by_me_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    检查项目是否被当前用户锁定
+
+    - **network**: 管网名称（或数据库名称）
+    """
+    client_host = req.client.host
+    return lockedPrjs.get(network) == client_host
+
+# 0 successfully locked
+# 1 already locked by you
+# 2 locked by others
+@router.post("/lockproject/", summary="锁定项目", description="锁定指定项目以防止并发修改。")
+async def lock_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    锁定项目
+
+    返回值:
+    - **0**: 锁定成功
+    - **1**: 已被当前用户锁定
+    - **2**: 已被其他用户锁定
+    """
+    client_host = req.client.host
+    if not network in lockedPrjs.keys():
+        lockedPrjs[network] = client_host
+        return 0
+    else:
+        if lockedPrjs.get(network) == client_host:
+            return 1
+        else:
+            return 2
+
+@router.post("/unlockproject/", summary="解锁项目", description="释放对项目的锁定。")
+def unlock_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+):
+    """
+    解锁项目
+
+    只有锁定者才能解锁。
+    """
+    client_host = req.client.host
+    if lockedPrjs.get(network) == client_host:
+        print("delete key")
+        del lockedPrjs[network]
+        return True
+
+    return False
+
+# inp file operations
+@router.post("/uploadinp/", status_code=status.HTTP_200_OK, summary="上传 INP 文件", description="上传 INP 文件到服务器数据目录。")
+async def fastapi_upload_inp(
+    afile: bytes = Body(..., description="文件二进制内容"),
+    name: str = Query(..., description="保存的文件名")
+):
+    """
+    上传 INP 文件
+
+    - **afile**: 文件内容
+    - **name**: 文件名
+    """
+    if not os.path.exists(inpDir):
+        os.makedirs(inpDir, exist_ok=True)
+        
+    filePath = inpDir + str(name)
+    with open(filePath, "wb") as f:
+        f.write(afile)
+    return True
+
+@router.get("/downloadinp/", status_code=status.HTTP_200_OK, summary="下载 INP 文件", description="从服务器数据目录下载指定的 INP 文件。")
+async def fastapi_download_inp(
+    name: str = Query(..., description="文件名"),
+    response: Response = None
+):
+    """
+    下载 INP 文件
+
+    - **name**: 文件名
+    """
+    filePath = inpDir + name
+    if os.path.exists(filePath):
+        return FileResponse(
+            filePath, media_type="application/octet-stream", filename="inp.inp"
+        )
+    else:
+        response.status_code = status.HTTP_400_BAD_REQUEST
+        return True
+
+# DingZQ, 2024-12-28, convert v3 to v2
+@router.get("/convertv3tov2/", response_model=None, summary="转换 INP V3 为 V2", description="将 EPANET 3.0 格式的 INP 内容转换为 2.x 格式。")
+async def fastapi_convert_v3_to_v2(
+    req: Request
+) -> ChangeSet:
+    """
+    转换 INP V3 为 V2
+
+    - **req**: 请求体，需包含 `{"inp": "..."}` 结构
+    """
     network = "v3Tov2"
     jo_root = await req.json()
     inp = jo_root["inp"]

app/api/v1/endpoints/project_data.py

@@ -1,9 +1,10 @@
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
 from psycopg import AsyncConnection
 
-from app.infra.db.postgresql.scada_info import ScadaRepository
+import app.native.wndb as wndb
 from app.infra.db.postgresql.scheme import SchemeRepository
 from app.auth.project_dependencies import get_project_pg_connection
+from app.services import project_info
 
 router = APIRouter()
 
@@ -11,18 +12,23 @@ router = APIRouter()
 async def get_database_connection(
     conn: AsyncConnection = Depends(get_project_pg_connection),
 ):
+    """获取数据库连接"""
     yield conn
 
 
-@router.get("/scada-info")
+@router.get("/scada-info", summary="获取SCADA信息", description="使用连接池查询所有SCADA信息")
 async def get_scada_info_with_connection(
     conn: AsyncConnection = Depends(get_database_connection),
 ):
     """
-    使用连接池查询所有SCADA信息
+    获取所有SCADA信息
+    
+    返回项目中所有的SCADA设备信息
     """
     try:
-        scada_data = await ScadaRepository.get_scadas(conn)
+        _ = conn
+        network_name = project_info.name
+        scada_data = wndb.get_all_scada_info(network_name) if network_name else []
         return {"success": True, "data": scada_data, "count": len(scada_data)}
     except Exception as e:
         raise HTTPException(
@@ -30,12 +36,14 @@ async def get_scada_info_with_connection(
         )
 
 
-@router.get("/scheme-list")
+@router.get("/scheme-list", summary="获取方案列表", description="使用连接池查询所有方案信息")
 async def get_scheme_list_with_connection(
     conn: AsyncConnection = Depends(get_database_connection),
 ):
     """
-    使用连接池查询所有方案信息
+    获取所有方案信息
+    
+    返回项目中所有方案的详细信息
     """
     try:
         scheme_data = await SchemeRepository.get_schemes(conn)
@@ -44,12 +52,14 @@ async def get_scheme_list_with_connection(
         raise HTTPException(status_code=500, detail=f"查询方案信息时发生错误: {str(e)}")
 
 
-@router.get("/burst-locate-result")
+@router.get("/burst-locate-result", summary="获取爆管定位结果", description="使用连接池查询所有爆管定位结果")
 async def get_burst_locate_result_with_connection(
     conn: AsyncConnection = Depends(get_database_connection),
 ):
     """
-    使用连接池查询所有爆管定位结果
+    获取所有爆管定位结果
+    
+    返回项目中所有的爆管定位分析结果
     """
     try:
         burst_data = await SchemeRepository.get_burst_locate_results(conn)
@@ -60,13 +70,16 @@ async def get_burst_locate_result_with_connection(
         )
 
 
-@router.get("/burst-locate-result/{burst_incident}")
+@router.get("/burst-locate-result/{burst_incident}", summary="按事件查询爆管定位结果", description="根据爆管事件ID查询对应的爆管定位结果")
 async def get_burst_locate_result_by_incident(
-    burst_incident: str,
+    burst_incident: str = Path(..., description="爆管事件ID"),
     conn: AsyncConnection = Depends(get_database_connection),
 ):
     """
-    根据 burst_incident 查询爆管定位结果
+    根据爆管事件ID查询爆管定位结果
+    
+    参数:
+        burst_incident: 爆管事件的唯一标识符
     """
     try:
         return await SchemeRepository.get_burst_locate_result_by_incident(

app/api/v1/endpoints/risk.py

@@ -1,5 +1,5 @@
 from typing import Any, List, Dict
-from fastapi import APIRouter
+from fastapi import APIRouter, Query, Path
 from app.services.tjnetwork import (
     get_pipe_risk_probability_now,
     get_pipe_risk_probability,
@@ -10,35 +10,118 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getpiperiskprobabilitynow/")
+@router.get(
+    "/getpiperiskprobabilitynow/",
+    summary="获取管道当前风险概率",
+    description="获取指定管道当前时刻的风险概率值"
+)
 async def fastapi_get_pipe_risk_probability_now(
-    network: str, pipe_id: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe_id: str = Query(..., description="管道ID")
 ) -> dict[str, Any]:
+    """
+    获取管道当前风险概率。
+    
+    查询指定管道在当前时刻的风险概率值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe_id: 管道ID
+        
+    Returns:
+        包含风险概率信息的字典
+    """
     return get_pipe_risk_probability_now(network, pipe_id)
 
 
-@router.get("/getpiperiskprobability/")
+@router.get(
+    "/getpiperiskprobability/",
+    summary="获取管道风险概率历史",
+    description="获取指定管道的风险概率历史数据"
+)
 async def fastapi_get_pipe_risk_probability(
-    network: str, pipe_id: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe_id: str = Query(..., description="管道ID")
 ) -> dict[str, Any]:
+    """
+    获取管道风险概率历史。
+    
+    查询指定管道的历史风险概率数据。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe_id: 管道ID
+        
+    Returns:
+        包含风险概率历史的字典
+    """
     return get_pipe_risk_probability(network, pipe_id)
 
 
-@router.get("/getpipesriskprobability/")
+@router.get(
+    "/getpipesriskprobability/",
+    summary="批量获取多条管道风险概率",
+    description="批量获取多条管道的风险概率值"
+)
 async def fastapi_get_pipes_risk_probability(
-    network: str, pipe_ids: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe_ids: str = Query(..., description="逗号分隔的管道ID列表")
 ) -> list[dict[str, Any]]:
+    """
+    批量获取多条管道风险概率。
+    
+    查询多条指定管道的风险概率值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        pipe_ids: 逗号分隔的管道ID列表（例如：pipe1,pipe2,pipe3）
+        
+    Returns:
+        包含多条管道风险概率的列表
+    """
     pipeids = pipe_ids.split(",")
     return get_pipes_risk_probability(network, pipeids)
 
 
-@router.get("/getnetworkpiperiskprobabilitynow/")
+@router.get(
+    "/getnetworkpiperiskprobabilitynow/",
+    summary="获取整个网络的管道风险概率",
+    description="获取指定网络中所有管道的当前风险概率值"
+)
 async def fastapi_get_network_pipe_risk_probability_now(
-    network: str,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
 ) -> list[dict[str, Any]]:
+    """
+    获取整个网络的管道风险概率。
+    
+    查询指定网络中所有管道在当前时刻的风险概率值。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含网络内所有管道风险概率的列表
+    """
     return get_network_pipe_risk_probability_now(network)
 
 
-@router.get("/getpiperiskprobabilitygeometries/")
-async def fastapi_get_pipe_risk_probability_geometries(network: str) -> dict[str, Any]:
+@router.get(
+    "/getpiperiskprobabilitygeometries/",
+    summary="获取管道风险几何信息",
+    description="获取指定网络中管道的风险相关几何数据"
+)
+async def fastapi_get_pipe_risk_probability_geometries(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, Any]:
+    """
+    获取管道风险几何信息。
+    
+    查询指定网络中管道的地理和风险相关的几何数据。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        包含几何信息和风险数据的字典
+    """
     return get_pipe_risk_probability_geometries(network)

app/api/v1/endpoints/scada.py

@@ -1,5 +1,5 @@
 from typing import Any
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query
 from app.services.tjnetwork import (
     ChangeSet,
     get_scada_info,
@@ -31,139 +31,497 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getscadaproperties/")
-async def fast_get_scada_properties(network: str, scada: str) -> dict[str, Any]:
+@router.get("/getscadaproperties/", summary="获取SCADA属性", tags=["SCADA基础"])
+async def fast_get_scada_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    scada: str = Query(..., description="SCADA设备ID")
+) -> dict[str, Any]:
+    """
+    获取单个SCADA设备的属性信息
+    
+    根据管网名称和SCADA设备ID获取该设备的完整属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        scada: SCADA设备ID
+        
+    Returns:
+        SCADA设备的属性字典
+    """
     return get_scada_info(network, scada)
 
-@router.get("/getallscadaproperties/")
-async def fast_get_all_scada_properties(network: str) -> list[dict[str, Any]]:
+@router.get("/getallscadaproperties/", summary="获取所有SCADA属性", tags=["SCADA基础"])
+async def fast_get_all_scada_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取指定管网所有SCADA设备的属性信息
+    
+    查询该管网下所有已配置的SCADA设备的属性列表。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA设备属性列表
+    """
     return get_all_scada_info(network)
 
 
 ############################################################
-# scada_device 29
+# scada_device 设备管理
 ############################################################
 
-@router.get("/getscadadeviceschema/")
-async def fastapi_get_scada_device_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getscadadeviceschema/", summary="获取SCADA设备架构", tags=["SCADA设备"])
+async def fastapi_get_scada_device_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取SCADA设备的数据架构
+    
+    返回SCADA设备表的字段定义和类型信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA设备的字段架构信息
+    """
     return get_scada_device_schema(network)
 
-@router.get("/getscadadevice/")
-async def fastapi_get_scada_device(network: str, id: str) -> dict[str, Any]:
+@router.get("/getscadadevice/", summary="获取SCADA设备", tags=["SCADA设备"])
+async def fastapi_get_scada_device(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="SCADA设备ID")
+) -> dict[str, Any]:
+    """
+    获取单个SCADA设备的信息
+    
+    根据设备ID查询该设备的详细信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        id: SCADA设备ID
+        
+    Returns:
+        SCADA设备信息
+    """
     return get_scada_device(network, id)
 
-@router.post("/setscadadevice/", response_model=None)
-async def fastapi_set_scada_device(network: str, req: Request) -> ChangeSet:
+@router.post("/setscadadevice/", response_model=None, summary="更新SCADA设备", tags=["SCADA设备"])
+async def fastapi_set_scada_device(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    更新SCADA设备信息
+    
+    修改指定SCADA设备的属性。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含要更新的设备属性
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return set_scada_device(network, ChangeSet(props))
 
-@router.post("/addscadadevice/", response_model=None)
-async def fastapi_add_scada_device(network: str, req: Request) -> ChangeSet:
+@router.post("/addscadadevice/", response_model=None, summary="添加SCADA设备", tags=["SCADA设备"])
+async def fastapi_add_scada_device(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    添加新的SCADA设备
+    
+    在指定管网中添加一个新的SCADA设备。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含新设备的属性
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return add_scada_device(network, ChangeSet(props))
 
-@router.post("/deletescadadevice/", response_model=None)
-async def fastapi_delete_scada_device(network: str, req: Request) -> ChangeSet:
+@router.post("/deletescadadevice/", response_model=None, summary="删除SCADA设备", tags=["SCADA设备"])
+async def fastapi_delete_scada_device(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    删除SCADA设备
+    
+    从指定管网中删除一个SCADA设备。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含要删除的设备ID
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return delete_scada_device(network, ChangeSet(props))
 
-@router.post("/cleanscadadevice/", response_model=None)
-async def fastapi_clean_scada_device(network: str) -> ChangeSet:
+@router.post("/cleanscadadevice/", response_model=None, summary="清空SCADA设备表", tags=["SCADA设备"])
+async def fastapi_clean_scada_device(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> ChangeSet:
+    """
+    清空SCADA设备表
+    
+    删除指定管网中所有的SCADA设备。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        变更集合信息
+    """
     return clean_scada_device(network)
 
-@router.get("/getallscadadeviceids/")
-async def fastapi_get_all_scada_device_ids(network: str) -> list[str]:
+@router.get("/getallscadadeviceids/", summary="获取所有SCADA设备ID", tags=["SCADA设备"])
+async def fastapi_get_all_scada_device_ids(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[str]:
+    """
+    获取指定管网所有SCADA设备的ID列表
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA设备ID列表
+    """
     return get_all_scada_device_ids(network)
 
-@router.get("/getallscadadevices/")
-async def fastapi_get_all_scada_devices(network: str) -> list[dict[str, Any]]:
+@router.get("/getallscadadevices/", summary="获取所有SCADA设备", tags=["SCADA设备"])
+async def fastapi_get_all_scada_devices(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取指定管网所有SCADA设备的完整信息
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA设备信息列表
+    """
     return get_all_scada_devices(network)
 
 
 ############################################################
-# scada_device_data 30
+# scada_device_data 设备数据管理
 ############################################################
 
-@router.get("/getscadadevicedataschema/")
+@router.get("/getscadadevicedataschema/", summary="获取SCADA设备数据架构", tags=["SCADA设备数据"])
 async def fastapi_get_scada_device_data_schema(
-    network: str,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
 ) -> dict[str, dict[str, Any]]:
+    """
+    获取SCADA设备数据的表结构
+    
+    返回SCADA设备数据表的字段定义和类型信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA设备数据的字段架构信息
+    """
     return get_scada_device_data_schema(network)
 
-@router.get("/getscadadevicedata/")
-async def fastapi_get_scada_device_data(network: str, device_id: str) -> dict[str, Any]:
+@router.get("/getscadadevicedata/", summary="获取SCADA设备数据", tags=["SCADA设备数据"])
+async def fastapi_get_scada_device_data(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    device_id: str = Query(..., description="SCADA设备ID")
+) -> dict[str, Any]:
+    """
+    获取单个SCADA设备的数据
+    
+    查询指定设备的监测数据或配置数据。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        device_id: SCADA设备ID
+        
+    Returns:
+        SCADA设备数据
+    """
     return get_scada_device_data(network, device_id)
 
-@router.post("/setscadadevicedata/", response_model=None)
-async def fastapi_set_scada_device_data(network: str, req: Request) -> ChangeSet:
+@router.post("/setscadadevicedata/", response_model=None, summary="更新SCADA设备数据", tags=["SCADA设备数据"])
+async def fastapi_set_scada_device_data(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    更新SCADA设备数据
+    
+    修改指定SCADA设备的数据。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含要更新的数据
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return set_scada_device_data(network, ChangeSet(props))
 
-@router.post("/addscadadevicedata/", response_model=None)
-async def fastapi_add_scada_device_data(network: str, req: Request) -> ChangeSet:
+@router.post("/addscadadevicedata/", response_model=None, summary="添加SCADA设备数据", tags=["SCADA设备数据"])
+async def fastapi_add_scada_device_data(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    添加新的SCADA设备数据
+    
+    为指定SCADA设备添加新的数据记录。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含新数据的内容
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return add_scada_device_data(network, ChangeSet(props))
 
-@router.post("/deletescadadevicedata/", response_model=None)
-async def fastapi_delete_scada_device_data(network: str, req: Request) -> ChangeSet:
+@router.post("/deletescadadevicedata/", response_model=None, summary="删除SCADA设备数据", tags=["SCADA设备数据"])
+async def fastapi_delete_scada_device_data(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    删除SCADA设备数据
+    
+    删除指定SCADA设备的数据记录。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含要删除的数据ID
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return delete_scada_device_data(network, ChangeSet(props))
 
-@router.post("/cleanscadadevicedata/", response_model=None)
-async def fastapi_clean_scada_device_data(network: str) -> ChangeSet:
+@router.post("/cleanscadadevicedata/", response_model=None, summary="清空SCADA设备数据表", tags=["SCADA设备数据"])
+async def fastapi_clean_scada_device_data(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> ChangeSet:
+    """
+    清空SCADA设备数据表
+    
+    删除指定管网中所有SCADA设备的数据。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        变更集合信息
+    """
     return clean_scada_device_data(network)
 
 
 ############################################################
-# scada_element 31
+# scada_element SCADA元素映射
 ############################################################
 
-@router.get("/getscadaelementschema/")
+@router.get("/getscadaelementschema/", summary="获取SCADA元素架构", tags=["SCADA元素映射"])
 async def fastapi_get_scada_element_schema(
-    network: str,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
 ) -> dict[str, dict[str, Any]]:
+    """
+    获取SCADA元素映射的表结构
+    
+    返回SCADA元素映射表的字段定义和类型信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA元素映射的字段架构信息
+    """
     return get_scada_element_schema(network)
 
-@router.get("/getscadaelements/")
-async def fastapi_get_scada_elements(network: str) -> list[dict[str, Any]]:
+@router.get("/getscadaelements/", summary="获取所有SCADA元素映射", tags=["SCADA元素映射"])
+async def fastapi_get_scada_elements(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取指定管网所有SCADA元素映射
+    
+    查询所有SCADA设备与管网元素（节点/管道）的映射关系。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA元素映射列表
+    """
     return get_all_scada_elements(network)
 
-@router.get("/getscadaelement/")
-async def fastapi_get_scada_element(network: str, id: str) -> dict[str, Any]:
+@router.get("/getscadaelement/", summary="获取单个SCADA元素映射", tags=["SCADA元素映射"])
+async def fastapi_get_scada_element(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="SCADA元素映射ID")
+) -> dict[str, Any]:
+    """
+    获取单个SCADA元素映射的信息
+    
+    根据ID查询特定的SCADA设备与管网元素的映射关系。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        id: SCADA元素映射ID
+        
+    Returns:
+        SCADA元素映射信息
+    """
     return get_scada_element(network, id)
 
-@router.post("/setscadaelement/", response_model=None)
-async def fastapi_set_scada_element(network: str, req: Request) -> ChangeSet:
+@router.post("/setscadaelement/", response_model=None, summary="更新SCADA元素映射", tags=["SCADA元素映射"])
+async def fastapi_set_scada_element(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    更新SCADA元素映射
+    
+    修改SCADA设备与管网元素的映射关系。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含要更新的映射信息
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return set_scada_element(network, ChangeSet(props))
 
-@router.post("/addscadaelement/", response_model=None)
-async def fastapi_add_scada_element(network: str, req: Request) -> ChangeSet:
+@router.post("/addscadaelement/", response_model=None, summary="添加SCADA元素映射", tags=["SCADA元素映射"])
+async def fastapi_add_scada_element(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    添加新的SCADA元素映射
+    
+    创建SCADA设备与管网元素的新映射关系。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含新映射的信息
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return add_scada_element(network, ChangeSet(props))
 
-@router.post("/deletescadaelement/", response_model=None)
-async def fastapi_delete_scada_element(network: str, req: Request) -> ChangeSet:
+@router.post("/deletescadaelement/", response_model=None, summary="删除SCADA元素映射", tags=["SCADA元素映射"])
+async def fastapi_delete_scada_element(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = None
+) -> ChangeSet:
+    """
+    删除SCADA元素映射
+    
+    移除SCADA设备与管网元素的映射关系。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        req: 请求体，包含要删除的映射ID
+        
+    Returns:
+        变更集合信息
+    """
     props = await req.json()
     return delete_scada_element(network, ChangeSet(props))
 
-@router.post("/cleanscadaelement/", response_model=None)
-async def fastapi_clean_scada_element(network: str) -> ChangeSet:
+@router.post("/cleanscadaelement/", response_model=None, summary="清空SCADA元素映射表", tags=["SCADA元素映射"])
+async def fastapi_clean_scada_element(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> ChangeSet:
+    """
+    清空SCADA元素映射表
+    
+    删除指定管网中所有的SCADA元素映射。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        变更集合信息
+    """
     return clean_scada_element(network)
 
 
 ############################################################
-# scada_info 38
+# scada_info SCADA信息
 ############################################################
 
-@router.get("/getscadainfoschema/")
-async def fastapi_get_scada_info_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getscadainfoschema/", summary="获取SCADA信息架构", tags=["SCADA信息"])
+async def fastapi_get_scada_info_schema(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> dict[str, dict[str, Any]]:
+    """
+    获取SCADA信息表的结构
+    
+    返回SCADA信息表的字段定义和类型信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA信息的字段架构信息
+    """
     return get_scada_info_schema(network)
 
-@router.get("/getscadainfo/")
-async def fastapi_get_scada_info(network: str, id: str) -> dict[str, Any]:
+@router.get("/getscadainfo/", summary="获取SCADA信息", tags=["SCADA信息"])
+async def fastapi_get_scada_info(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    id: str = Query(..., description="SCADA信息ID")
+) -> dict[str, Any]:
+    """
+    获取单个SCADA信息
+    
+    根据ID查询SCADA的详细配置信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        id: SCADA信息ID
+        
+    Returns:
+        SCADA信息详情
+    """
     return get_scada_info(network, id)
 
-@router.get("/getallscadainfo/")
-async def fastapi_get_all_scada_info(network: str) -> list[dict[str, Any]]:
+@router.get("/getallscadainfo/", summary="获取所有SCADA信息", tags=["SCADA信息"])
+async def fastapi_get_all_scada_info(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+) -> list[dict[str, Any]]:
+    """
+    获取指定管网所有SCADA的信息
+    
+    查询该管网下所有已配置的SCADA的完整信息。
+    
+    Args:
+        network: 管网名称（或数据库名称）
+        
+    Returns:
+        SCADA信息列表
+    """
     return get_all_scada_info(network)

app/api/v1/endpoints/schemes.py

@@ -1,17 +1,32 @@
-from fastapi import APIRouter
+from fastapi import APIRouter, Query
 from typing import Any, List, Dict
 from app.services.tjnetwork import get_scheme_schema, get_scheme, get_all_schemes
 
 router = APIRouter()
 
-@router.get("/getschemeschema/")
-async def fastapi_get_scheme_schema(network: str) -> dict[str, dict[Any, Any]]:
+@router.get("/getschemeschema/", summary="获取方案模式", description="获取指定网络的方案模式定义")
+async def fastapi_get_scheme_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[Any, Any]]:
+    """
+    获取方案模式定义
+    
+    返回指定网络的方案模式结构定义
+    """
     return get_scheme_schema(network)
 
-@router.get("/getscheme/")
-async def fastapi_get_scheme(network: str, schema_name: str) -> dict[Any, Any]:
+@router.get("/getscheme/", summary="获取单个方案", description="根据名称获取指定的方案信息")
+async def fastapi_get_scheme(network: str = Query(..., description="管网名称（或数据库名称）"), schema_name: str = Query(..., description="方案名称")) -> dict[Any, Any]:
+    """
+    获取单个方案详情
+    
+    返回指定网络中指定名称的方案详细信息
+    """
     return get_scheme(network, schema_name)
 
-@router.get("/getallschemes/")
-async def fastapi_get_all_schemes(network: str) -> list[dict[Any, Any]]:
+@router.get("/getallschemes/", summary="获取所有方案", description="获取指定网络的所有方案信息")
+async def fastapi_get_all_schemes(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[dict[Any, Any]]:
+    """
+    获取所有方案列表
+    
+    返回指定网络中所有可用的方案
+    """
     return get_all_schemes(network)

app/api/v1/endpoints/simulation.py

@@ -4,13 +4,11 @@ import json
 import os
 import shutil
 import threading
-import pandas as pd
-from fastapi import APIRouter, HTTPException, File, UploadFile, Query
+from fastapi import APIRouter, HTTPException, File, UploadFile, Query, Path, Body
 from fastapi.responses import PlainTextResponse
 import app.infra.db.influxdb.api as influxdb_api
 import app.services.simulation as simulation
 import app.services.globals as globals
-from app.infra.cache.redis_client import redis_client
 from app.services.tjnetwork import (
     run_project,
     run_project_return_dict,
@@ -39,77 +37,77 @@ from app.services.simulation_ops import (
     daily_scheduling_simulation,
 )
 from app.services.valve_isolation import analyze_valve_isolation
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 router = APIRouter()
 
 
 class RunSimulationManuallyByDate(BaseModel):
-    name: str
-    simulation_date: str
-    start_time: str
-    duration: int
+    name: str = Field(..., description="管网名称（或数据库名称）")
+    simulation_date: str = Field(..., description="模拟基准日期 (YYYY-MM-DD)")
+    start_time: str = Field(..., description="开始时间 (HH:MM 或 HH:MM:SS)")
+    duration: int = Field(..., description="持续时间 (分钟)")
 
 
 class BurstAnalysis(BaseModel):
-    name: str
-    modify_pattern_start_time: str
-    burst_ID: List[str] | str | None = None
-    burst_size: List[float] | float | int | None = None
-    modify_total_duration: int = 900
-    modify_fixed_pump_pattern: Optional[dict[str, list]] = None
-    modify_variable_pump_pattern: Optional[dict[str, list]] = None
-    modify_valve_opening: Optional[dict[str, float]] = None
-    scheme_name: Optional[str] = None
+    name: str = Field(..., description="管网名称（或数据库名称）")
+    modify_pattern_start_time: str = Field(..., description="模式修改开始时间 (ISO 8601)")
+    burst_ID: List[str] | str | None = Field(None, description="爆管节点/管段ID列表")
+    burst_size: List[float] | float | int | None = Field(None, description="爆管流量大小")
+    modify_total_duration: int = Field(900, description="模拟总时长 (秒)")
+    modify_fixed_pump_pattern: Optional[dict[str, list]] = Field(None, description="定速泵模式修改")
+    modify_variable_pump_pattern: Optional[dict[str, list]] = Field(None, description="变速泵模式修改")
+    modify_valve_opening: Optional[dict[str, float]] = Field(None, description="阀门开度修改")
+    scheme_name: Optional[str] = Field(None, description="方案名称")
 
 
 class SchedulingAnalysis(BaseModel):
-    network: str
-    start_time: str
-    pump_control: dict
-    tank_id: str
-    water_plant_output_id: str
-    time_delta: Optional[int] = 300
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    start_time: str = Field(..., description="开始时间")
+    pump_control: dict = Field(..., description="泵控制策略")
+    tank_id: str = Field(..., description="水箱ID")
+    water_plant_output_id: str = Field(..., description="水厂出水ID")
+    time_delta: Optional[int] = Field(300, description="时间步长 (秒)")
 
 
 class PressureRegulation(BaseModel):
-    network: str
-    start_time: str
-    pump_control: dict
-    tank_init_level: Optional[dict] = None
-    duration: Optional[int] = 900
-    scheme_name: Optional[str] = None
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    start_time: str = Field(..., description="开始时间")
+    pump_control: dict = Field(..., description="泵控制策略")
+    tank_init_level: Optional[dict] = Field(None, description="水箱初始水位")
+    duration: Optional[int] = Field(900, description="持续时间 (秒)")
+    scheme_name: Optional[str] = Field(None, description="方案名称")
 
 
 class ProjectManagement(BaseModel):
-    network: str
-    start_time: str
-    pump_control: dict
-    tank_init_level: Optional[dict] = None
-    region_demand: Optional[dict] = None
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    start_time: str = Field(..., description="开始时间")
+    pump_control: dict = Field(..., description="泵控制策略")
+    tank_init_level: Optional[dict] = Field(None, description="水箱初始水位")
+    region_demand: Optional[dict] = Field(None, description="区域需水量控制")
 
 
 class DailySchedulingAnalysis(BaseModel):
-    network: str
-    start_time: str
-    pump_control: dict
-    reservoir_id: str
-    tank_id: str
-    water_plant_output_id: str
-    time_delta: Optional[int] = 300
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    start_time: str = Field(..., description="开始时间")
+    pump_control: dict = Field(..., description="泵控制策略")
+    reservoir_id: str = Field(..., description="水库ID")
+    tank_id: str = Field(..., description="水箱ID")
+    water_plant_output_id: str = Field(..., description="水厂出水ID")
+    time_delta: Optional[int] = Field(300, description="时间步长 (秒)")
 
 
 class PumpFailureState(BaseModel):
-    time: str
-    pump_status: dict
+    time: str = Field(..., description="故障发生时间")
+    pump_status: dict = Field(..., description="泵状态字典")
 
 
 class PressureSensorPlacement(BaseModel):
-    name: str
-    scheme_name: str
-    sensor_number: int
-    min_diameter: int = 0
-    username: str
+    name: str = Field(..., description="管网名称（或数据库名称）")
+    scheme_name: str = Field(..., description="方案名称")
+    sensor_number: int = Field(..., description="传感器数量")
+    min_diameter: int = Field(0, description="最小管径限制")
+    username: str = Field(..., description="用户名")
 
 
 def run_simulation_manually_by_date(
@@ -140,75 +138,106 @@ def run_simulation_manually_by_date(
 
 
 # 必须用这个PlainTextResponse，不然每个key都有引号
-@router.get("/runproject/", response_class=PlainTextResponse)
-async def run_project_endpoint(network: str) -> str:
-    lock_key = "exclusive_api_lock"
-    timeout = 120  # 锁自动过期时间（秒）
-
-    # 尝试获取锁（NX=True: 不存在时设置，EX=timeout: 过期时间）
-    acquired = redis_client.set(lock_key, "locked", nx=True, ex=timeout)
-
-    if not acquired:
-        raise HTTPException(status_code=409, detail="is in simulation")
-    else:
-        try:
-            return run_project(network)
-        finally:
-            # 手动释放锁（可选，依赖过期时间自动释放更安全）
-            redis_client.delete(lock_key)
+@router.get("/runproject/", response_class=PlainTextResponse, summary="运行项目模拟", description="基于指定的管网项目运行标准水力模拟，返回纯文本格式的模拟报告。")
+async def run_project_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")) -> str:
+    """
+    运行项目模拟
+    
+    - **network**: 管网名称（或数据库名称）
+    
+    运行指定管网项目的标准水力模拟并返回文本报告。
+    """
+    return run_project(network)
 
 
 # DingZQ, 2025-02-04, 返回dict[str, Any]
 # output 和 report
 # output 是 json
 # report 是 text
-@router.get("/runprojectreturndict/")
-async def run_project_return_dict_endpoint(network: str) -> dict[str, Any]:
-    lock_key = "exclusive_api_lock"
-    timeout = 120  # 锁自动过期时间（秒）
-
-    # 尝试获取锁（NX=True: 不存在时设置，EX=timeout: 过期时间）
-    acquired = redis_client.set(lock_key, "locked", nx=True, ex=timeout)
-
-    if not acquired:
-        raise HTTPException(status_code=409, detail="is in simulation")
-    else:
-        try:
-            return run_project_return_dict(network)
-        finally:
-            # 手动释放锁（可选，依赖过期时间自动释放更安全）
-            redis_client.delete(lock_key)
+@router.get("/runprojectreturndict/", summary="运行项目模拟（返回字典）", description="基于指定的管网项目运行标准水力模拟，返回JSON格式的字典，包含输出数据和报告文本。")
+async def run_project_return_dict_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """
+    运行项目模拟（返回字典）
+    
+    - **network**: 管网名称（或数据库名称）
+    
+    返回字典包含：
+    - output: JSON格式的模拟输出数据
+    - report: 文本格式的模拟报告
+    
+    运行指定管网项目的标准水力模拟并返回字典结果。
+    """
+    return run_project_return_dict(network)
 
 
 # put in inp folder, name without extension
-@router.get("/runinp/")
-async def run_inp_endpoint(network: str) -> str:
+@router.get("/runinp/", summary="运行INP文件", description="运行指定INP文件格式的管网模型进行水力模拟。INP文件应该放在inp文件夹中，参数为文件名不含扩展名。")
+async def run_inp_endpoint(network: str = Query(..., description="inp文件名（不含扩展名）")) -> str:
+    """
+    运行INP文件
+    
+    - **network**: inp文件名（不含扩展名）
+    
+    从inp文件夹中读取指定的INP文件并运行模拟。
+    """
     return run_inp(network)
 
 
 # path is absolute path
-@router.get("/dumpoutput/")
-async def dump_output_endpoint(output: str) -> str:
+@router.get("/dumpoutput/", summary="导出模拟输出", description="导出指定路径的模拟输出文件内容。参数应为绝对路径。")
+async def dump_output_endpoint(output: str = Query(..., description="模拟输出文件的绝对路径")) -> str:
+    """
+    导出模拟输出
+    
+    - **output**: 模拟输出文件的绝对路径
+    
+    读取并返回指定路径的模拟输出内容。
+    """
     return dump_output(output)
 
 
 # Analysis Endpoints
-@router.get("/burstanalysis/")
+@router.get("/burstanalysis/", summary="爆管分析（基础）", description="对管网中的爆管事件进行分析，包括爆管对管网压力和流量的影响。此为基础版本，接收简化的查询参数。")
 async def burst_analysis_endpoint(
-    network: str, pipe_id: str, start_time: str, end_time: str, burst_flow: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe_id: str = Query(..., description="管段ID"),
+    start_time: str = Query(..., description="分析开始时间（ISO 8601格式）"),
+    end_time: str = Query(..., description="分析结束时间（ISO 8601格式）"),
+    burst_flow: float = Query(..., description="爆管流量大小（L/s）"),
 ):
+    """
+    爆管分析（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **pipe_id**: 管段ID
+    - **start_time**: 分析开始时间
+    - **end_time**: 分析结束时间
+    - **burst_flow**: 爆管流量大小
+    """
     return burst_analysis(network, pipe_id, start_time, end_time, burst_flow)
 
 
-@router.get("/burst_analysis/")
+@router.get("/burst_analysis/", summary="爆管分析（高级）", description="高级版本的爆管分析，支持在指定时间点修改泵控制模式和阀门开度，以分析这些改变对爆管影响的作用。支持固定泵和变速泵的独立控制。")
 async def fastapi_burst_analysis(
-    network: str = Query(...),
-    modify_pattern_start_time: str = Query(...),
-    burst_ID: list[str] = Query(...),
-    burst_size: list[float] = Query(...),
-    modify_total_duration: int = Query(...),
-    scheme_name: str = Query(...),
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    modify_pattern_start_time: str = Query(..., description="模式修改开始时间（ISO 8601格式）"),
+    burst_ID: list[str] = Query(..., description="爆管节点/管段ID列表"),
+    burst_size: list[float] = Query(..., description="对应各爆管点的爆管流量大小列表（L/s）"),
+    modify_total_duration: int = Query(..., description="模拟总时长（秒）"),
+    scheme_name: str = Query(..., description="分析方案名称"),
 ) -> str:
+    """
+    爆管分析（高级版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **modify_pattern_start_time**: 模式修改开始时间
+    - **burst_ID**: 爆管节点/管段ID列表
+    - **burst_size**: 爆管流量大小列表（与burst_ID对应）
+    - **modify_total_duration**: 模拟总时长（秒）
+    - **scheme_name**: 分析方案名称
+    
+    支持在指定时间修改泵控制模式和阀门开度。
+    """
     burst_analysis(
         name=network,
         modify_pattern_start_time=modify_pattern_start_time,
@@ -220,20 +249,41 @@ async def fastapi_burst_analysis(
     return "success"
 
 
-@router.get("/valvecloseanalysis/")
+@router.get("/valvecloseanalysis/", summary="阀门关闭分析（基础）", description="对管网中的阀门关闭事件进行分析，评估关闭阀门对管网的影响。此为基础版本。")
 async def valve_close_analysis_endpoint(
-    network: str, valve_id: str, start_time: str, end_time: str
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    valve_id: str = Query(..., description="阀门ID"),
+    start_time: str = Query(..., description="分析开始时间（ISO 8601格式）"),
+    end_time: str = Query(..., description="分析结束时间（ISO 8601格式）"),
 ):
+    """
+    阀门关闭分析（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **valve_id**: 阀门ID
+    - **start_time**: 分析开始时间
+    - **end_time**: 分析结束时间
+    """
     return valve_close_analysis(network, valve_id, start_time, end_time)
 
 
-@router.get("/valve_close_analysis/", response_class=PlainTextResponse)
+@router.get("/valve_close_analysis/", response_class=PlainTextResponse, summary="阀门关闭分析（高级）", description="高级版本的阀门关闭分析，支持同时关闭多个阀门，并在指定持续时间内进行模拟。返回纯文本格式的分析结果。")
 async def fastapi_valve_close_analysis(
-    network: str,
-    start_time: str,
-    valves: List[str] = Query(...),
-    duration: int | None = None,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    start_time: str = Query(..., description="阀门关闭开始时间（ISO 8601格式）"),
+    valves: List[str] = Query(..., description="要关闭的阀门ID列表"),
+    duration: int | None = Query(None, description="模拟持续时间（秒），默认900秒"),
 ) -> str:
+    """
+    阀门关闭分析（高级版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 阀门关闭开始时间
+    - **valves**: 要关闭的阀门ID列表
+    - **duration**: 模拟持续时间（秒，可选，默认900）
+    
+    支持同时关闭多个阀门进行分析。
+    """
     result = valve_close_analysis(
         name=network,
         modify_pattern_start_time=start_time,
@@ -243,12 +293,25 @@ async def fastapi_valve_close_analysis(
     return result or "success"
 
 
-@router.get("/valve_isolation_analysis/")
+@router.get("/valve_isolation_analysis/", summary="阀门隔离分析", description="分析当发生突发事件时，通过关闭指定阀门进行隔离，确定哪些阀门必须关闭、哪些可选关闭，以及隔离的可行性。")
 async def valve_isolation_endpoint(
-    network: str,
-    accident_element: List[str] = Query(...),
-    disabled_valves: List[str] = Query(None),
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    accident_element: List[str] = Query(..., description="发生事故的管段/节点ID列表"),
+    disabled_valves: List[str] = Query(None, description="已故障的阀门ID列表（可选）"),
 ):
+    """
+    阀门隔离分析
+    
+    - **network**: 管网名称（或数据库名称）
+    - **accident_element**: 发生事故的管段/节点ID列表
+    - **disabled_valves**: 已故障的阀门ID列表（可选）
+    
+    返回隔离方案，包括：
+    - must_close_valves: 必须关闭的阀门列表
+    - optional_valves: 可选关闭的阀门列表
+    - affected_nodes: 受影响的节点列表
+    - isolatable: 是否可以有效隔离
+    """
     result = {
         "accident_element": "P461309",
         "accident_elements": ["P461309"],
@@ -270,24 +333,51 @@ async def valve_isolation_endpoint(
     return result
 
 
-@router.get("/flushinganalysis/")
+@router.get("/flushinganalysis/", summary="冲洗分析（基础）", description="对管网的冲洗操作进行分析，评估冲洗流量和持续时间对管网的影响。此为基础版本。")
 async def flushing_analysis_endpoint(
-    network: str, pipe_id: str, start_time: str, duration: float, flow: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pipe_id: str = Query(..., description="要冲洗的管段ID"),
+    start_time: str = Query(..., description="冲洗开始时间（ISO 8601格式）"),
+    duration: float = Query(..., description="冲洗持续时间（分钟）"),
+    flow: float = Query(..., description="冲洗流量（L/s）"),
 ):
+    """
+    冲洗分析（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **pipe_id**: 要冲洗的管段ID
+    - **start_time**: 冲洗开始时间
+    - **duration**: 冲洗持续时间（分钟）
+    - **flow**: 冲洗流量（L/s）
+    """
     return flushing_analysis(network, pipe_id, start_time, duration, flow)
 
 
-@router.get("/flushing_analysis/", response_class=PlainTextResponse)
+@router.get("/flushing_analysis/", response_class=PlainTextResponse, summary="冲洗分析（高级）", description="高级版本的冲洗分析，支持同时开启多个阀门进行冲洗，指定排污节点，并设置固定的冲洗流量。返回纯文本格式的分析结果。")
 async def fastapi_flushing_analysis(
-    network: str,
-    start_time: str,
-    valves: List[str] = Query(...),
-    valves_k: List[float] = Query(...),
-    drainage_node_ID: str = Query(...),
-    flush_flow: float = 0,
-    duration: int | None = None,
-    scheme_name: str | None = None,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    start_time: str = Query(..., description="冲洗开始时间（ISO 8601格式）"),
+    valves: List[str] = Query(..., description="要开启的阀门ID列表"),
+    valves_k: List[float] = Query(..., description="对应各阀门的开度列表（0-1）"),
+    drainage_node_ID: str = Query(..., description="排污节点ID"),
+    flush_flow: float = Query(0, description="冲洗流量（L/s），0表示自动计算"),
+    duration: int | None = Query(None, description="模拟持续时间（秒），默认900秒"),
+    scheme_name: str | None = Query(None, description="冲洗方案名称（可选）"),
 ) -> str:
+    """
+    冲洗分析（高级版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 冲洗开始时间
+    - **valves**: 要开启的阀门ID列表
+    - **valves_k**: 各阀门的开度列表（0-1，与valves对应）
+    - **drainage_node_ID**: 排污节点ID
+    - **flush_flow**: 冲洗流量（L/s）
+    - **duration**: 模拟持续时间（秒，可选，默认900）
+    - **scheme_name**: 冲洗方案名称（可选）
+    
+    支持多阀联合冲洗操作。
+    """
     valve_opening = {
         valve_id: float(valves_k[idx]) for idx, valve_id in enumerate(valves)
     }
@@ -303,16 +393,29 @@ async def fastapi_flushing_analysis(
     return result or "success"
 
 
-@router.get("/contaminant_simulation/", response_class=PlainTextResponse)
+@router.get("/contaminant_simulation/", response_class=PlainTextResponse, summary="污染物模拟", description="对管网中的污染物扩散进行模拟，评估污染源对管网的影响范围和浓度分布。支持指定污染源位置、污染浓度和扩散模式。")
 async def fastapi_contaminant_simulation(
-    network: str,
-    start_time: str,
-    source: str,
-    concentration: float,
-    duration: int,
-    scheme_name: str | None = None,
-    pattern: str | None = None,
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    start_time: str = Query(..., description="污染开始时间（ISO 8601格式）"),
+    source: str = Query(..., description="污染源节点ID"),
+    concentration: float = Query(..., description="污染浓度（mg/L）"),
+    duration: int = Query(..., description="模拟持续时间（秒）"),
+    scheme_name: str | None = Query(None, description="模拟方案名称（可选）"),
+    pattern: str | None = Query(None, description="污染源模式ID（可选）"),
 ) -> str:
+    """
+    污染物模拟
+    
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 污染开始时间
+    - **source**: 污染源节点ID
+    - **concentration**: 污染浓度（mg/L）
+    - **duration**: 模拟持续时间（秒）
+    - **scheme_name**: 模拟方案名称（可选）
+    - **pattern**: 污染源模式ID（可选）
+    
+    用于评估管网中污染物的传播和影响范围。
+    """
     result = contaminant_simulation(
         name=network,
         modify_pattern_start_time=start_time,
@@ -325,15 +428,35 @@ async def fastapi_contaminant_simulation(
     return result or "success"
 
 
-@router.get("/ageanalysis/")
-async def age_analysis_endpoint(network: str):
+@router.get("/ageanalysis/", summary="水龄分析（基础）", description="对管网中的水体停留时间（水龄）进行分析。此为基础版本。")
+async def age_analysis_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")):
+    """
+    水龄分析（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    
+    分析管网中各节点的水体停留时间。
+    """
     return age_analysis(network)
 
 
-@router.get("/age_analysis/", response_class=PlainTextResponse)
+@router.get("/age_analysis/", response_class=PlainTextResponse, summary="水龄分析（高级）", description="高级版本的水龄分析，在指定时间点进行分析，支持自定义模拟持续时间。返回纯文本格式的分析结果。")
 async def fastapi_age_analysis(
-    network: str, start_time: str, end_time: str, duration: int
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    start_time: str = Query(..., description="分析开始时间（ISO 8601格式）"),
+    end_time: str = Query(..., description="分析结束时间（ISO 8601格式）"),
+    duration: int = Query(..., description="模拟持续时间（秒）"),
 ) -> str:
+    """
+    水龄分析（高级版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 分析开始时间
+    - **end_time**: 分析结束时间（可选）
+    - **duration**: 模拟持续时间（秒）
+    
+    分析指定时间段内管网中各节点的水体停留时间。
+    """
     result = age_analysis(network, start_time, duration)
     return result or "success"
 
@@ -343,15 +466,39 @@ async def fastapi_age_analysis(
 #     return scheduling_analysis(network)
 
 
-@router.get("/pressureregulation/")
+@router.get("/pressureregulation/", summary="压力调节（基础）", description="对管网的压力进行调节分析，通过控制泵的运行来维持目标节点的目标压力。此为基础版本。")
 async def pressure_regulation_endpoint(
-    network: str, target_node: str, target_pressure: float
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    target_node: str = Query(..., description="目标节点ID"),
+    target_pressure: float = Query(..., description="目标压力值（kPa）"),
 ):
+    """
+    压力调节（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **target_node**: 目标节点ID
+    - **target_pressure**: 目标压力值（kPa）
+    
+    通过泵控制维持目标节点的压力。
+    """
     return pressure_regulation(network, target_node, target_pressure)
 
 
-@router.post("/pressure_regulation/")
-async def fastapi_pressure_regulation(data: PressureRegulation) -> str:
+@router.post("/pressure_regulation/", summary="压力调节（高级）", description="高级版本的压力调节分析，通过JSON请求体提供详细的控制参数，包括固定泵和变速泵的独立控制、水箱初始水位等。")
+async def fastapi_pressure_regulation(data: PressureRegulation = Body(..., description="压力调节控制参数")) -> str:
+    """
+    压力调节（高级版本）
+    
+    请求体参数：
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 控制开始时间
+    - **pump_control**: 泵控制策略字典
+    - **tank_init_level**: 水箱初始水位字典（可选）
+    - **duration**: 模拟持续时间（秒，可选，默认900）
+    - **scheme_name**: 控制方案名称（可选）
+    
+    支持固定泵和变速泵的独立控制。
+    """
     item = data.dict()
     simulation.query_corresponding_element_id_and_query_id(item["network"])
     fixed_pumps = set(globals.fixed_pumps_id.keys())
@@ -375,13 +522,32 @@ async def fastapi_pressure_regulation(data: PressureRegulation) -> str:
     return "success"
 
 
-@router.get("/projectmanagement/")
-async def project_management_endpoint(network: str):
+@router.get("/projectmanagement/", summary="项目管理（基础）", description="对管网项目进行基础的管理操作。此为基础版本。")
+async def project_management_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")):
+    """
+    项目管理（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    
+    进行基础的项目管理操作。
+    """
     return project_management(network)
 
 
-@router.post("/project_management/")
-async def fastapi_project_management(data: ProjectManagement) -> str:
+@router.post("/project_management/", summary="项目管理（高级）", description="高级版本的项目管理，通过JSON请求体提供详细的控制参数，包括泵控制策略、水箱初始水位和区域需水量控制。")
+async def fastapi_project_management(data: ProjectManagement = Body(..., description="项目管理控制参数")) -> str:
+    """
+    项目管理（高级版本）
+    
+    请求体参数：
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 管理开始时间
+    - **pump_control**: 泵控制策略字典
+    - **tank_init_level**: 水箱初始水位字典（可选）
+    - **region_demand**: 区域需水量控制字典（可选）
+    
+    支持多维度的项目管理。
+    """
     item = data.dict()
     return project_management(
         prj_name=item["network"],
@@ -397,8 +563,21 @@ async def fastapi_project_management(data: ProjectManagement) -> str:
 #     return daily_scheduling_analysis(network)
 
 
-@router.post("/scheduling_analysis/")
-async def fastapi_scheduling_analysis(data: SchedulingAnalysis) -> str:
+@router.post("/scheduling_analysis/", summary="排程分析", description="对管网的供水排程进行分析，优化泵的运行时间和出水流量，平衡水厂出水、水箱进出水，满足用户需求。")
+async def fastapi_scheduling_analysis(data: SchedulingAnalysis = Body(..., description="排程分析参数")) -> str:
+    """
+    排程分析
+    
+    请求体参数：
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 分析开始时间
+    - **pump_control**: 泵控制策略字典
+    - **tank_id**: 水箱ID
+    - **water_plant_output_id**: 水厂出水ID
+    - **time_delta**: 时间步长（秒，可选，默认300）
+    
+    用于优化供水排程。
+    """
     item = data.dict()
     return scheduling_simulation(
         item["network"],
@@ -410,8 +589,22 @@ async def fastapi_scheduling_analysis(data: SchedulingAnalysis) -> str:
     )
 
 
-@router.post("/daily_scheduling_analysis/")
-async def fastapi_daily_scheduling_analysis(data: DailySchedulingAnalysis) -> str:
+@router.post("/daily_scheduling_analysis/", summary="日排程分析", description="对管网的每日供水排程进行分析，优化水库、水厂、水箱和用户需求的协调，制定合理的每日排程方案。")
+async def fastapi_daily_scheduling_analysis(data: DailySchedulingAnalysis = Body(..., description="日排程分析参数")) -> str:
+    """
+    日排程分析
+    
+    请求体参数：
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 分析开始时间
+    - **pump_control**: 泵控制策略字典
+    - **reservoir_id**: 水库ID
+    - **tank_id**: 水箱ID
+    - **water_plant_output_id**: 水厂出水ID
+    - **time_delta**: 时间步长（秒，可选，默认300）
+    
+    用于制定每日供水排程方案。
+    """
     item = data.dict()
     return daily_scheduling_simulation(
         item["network"],
@@ -423,8 +616,15 @@ async def fastapi_daily_scheduling_analysis(data: DailySchedulingAnalysis) -> st
     )
 
 
-@router.post("/network_project/")
-async def fastapi_network_project(file: UploadFile = File()) -> str:
+@router.post("/network_project/", summary="导入网络项目", description="通过上传INP格式的管网文件导入新的网络项目。系统将自动处理文件并执行模拟。")
+async def fastapi_network_project(file: UploadFile = File(..., description="INP格式的管网文件")) -> str:
+    """
+    导入网络项目
+    
+    - **file**: 上传的INP格式管网文件
+    
+    系统将上传的文件保存到inp文件夹并执行模拟。
+    """
     temp_file_dir = "./inp/"
     if not os.path.exists(temp_file_dir):
         os.mkdir(temp_file_dir)
@@ -435,13 +635,27 @@ async def fastapi_network_project(file: UploadFile = File()) -> str:
     return run_inp(temp_file_name)
 
 
-@router.get("/networkupdate/")
-async def network_update_endpoint(network: str):
+@router.get("/networkupdate/", summary="管网更新（基础）", description="对指定管网项目进行基础的更新操作。此为基础版本。")
+async def network_update_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")):
+    """
+    管网更新（基础版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    
+    进行管网的基础更新操作。
+    """
     return network_update(network)
 
 
-@router.post("/network_update/")
-async def fastapi_network_update(file: UploadFile = File()) -> str:
+@router.post("/network_update/", summary="管网更新（高级）", description="通过上传更新文件对管网进行高级的更新操作。系统将处理更新文件并应用到数据库。")
+async def fastapi_network_update(file: UploadFile = File(..., description="包含管网更新信息的文件")) -> str:
+    """
+    管网更新（高级版本）
+    
+    - **file**: 包含管网更新信息的文件
+    
+    系统将处理上传的文件并应用管网更新。
+    """
     default_folder = "./"
     temp_file_name = f'network_update_{datetime.now().strftime("%Y%m%d")}'
     temp_file_path = os.path.join(default_folder, temp_file_name)
@@ -459,8 +673,17 @@ async def fastapi_network_update(file: UploadFile = File()) -> str:
 #     return pump_failure(network, pump_id, time)
 
 
-@router.post("/pump_failure/")
-async def fastapi_pump_failure(data: PumpFailureState) -> str:
+@router.post("/pump_failure/", summary="泵故障管理", description="记录和管理泵的故障状态，包括故障发生时间和受影响的泵列表。系统将记录故障日志并更新泵状态。")
+async def fastapi_pump_failure(data: PumpFailureState = Body(..., description="泵故障状态信息")) -> str:
+    """
+    泵故障管理
+    
+    请求体参数：
+    - **time**: 故障发生时间
+    - **pump_status**: 泵状态字典，包含第一阶段和第二阶段泵的故障状态
+    
+    系统将验证泵信息的有效性并更新故障状态文件。
+    """
     item = data.dict()
     with open("./pump_failure_message.txt", "a", encoding="utf-8-sig") as f1:
         f1.write("[{}] {}\n".format(datetime.now().strftime("%Y-%m-%d %H:%M:%S"), item))
@@ -494,19 +717,46 @@ async def fastapi_pump_failure(data: PumpFailureState) -> str:
     return json.dumps("SUCCESS")
 
 
-@router.get("/pressuresensorplacementsensitivity/")
+@router.get("/pressuresensorplacementsensitivity/", summary="压力传感器放置-灵敏度分析（基础）", description="基于灵敏度分析方法，为指定管网项目确定最优的压力传感器放置位置。此为基础版本。")
 async def pressure_sensor_placement_sensitivity_endpoint(
-    name: str, scheme_name: str, sensor_number: int, min_diameter: int, username: str
+    name: str = Query(..., description="管网名称（或数据库名称）"),
+    scheme_name: str = Query(..., description="放置方案名称"),
+    sensor_number: int = Query(..., description="传感器数量"),
+    min_diameter: int = Query(..., description="最小管径限制（毫米）"),
+    username: str = Query(..., description="用户名"),
 ):
+    """
+    压力传感器放置-灵敏度分析（基础版本）
+    
+    - **name**: 管网名称（或数据库名称）
+    - **scheme_name**: 放置方案名称
+    - **sensor_number**: 传感器数量
+    - **min_diameter**: 最小管径限制（毫米）
+    - **username**: 用户名
+    
+    基于灵敏度分析方法确定传感器放置位置。
+    """
     return pressure_sensor_placement_sensitivity(
         name, scheme_name, sensor_number, min_diameter, username
     )
 
 
-@router.post("/pressure_sensor_placement_sensitivity/")
+@router.post("/pressure_sensor_placement_sensitivity/", summary="压力传感器放置-灵敏度分析（高级）", description="高级版本的压力传感器放置分析，通过JSON请求体提供详细参数。基于灵敏度分析方法确定最优放置位置。")
 async def fastapi_pressure_sensor_placement_sensitivity(
-    data: PressureSensorPlacement,
+    data: PressureSensorPlacement = Body(..., description="传感器放置分析参数"),
 ) -> None:
+    """
+    压力传感器放置-灵敏度分析（高级版本）
+    
+    请求体参数：
+    - **name**: 管网名称（或数据库名称）
+    - **scheme_name**: 放置方案名称
+    - **sensor_number**: 传感器数量
+    - **min_diameter**: 最小管径限制（毫米）
+    - **username**: 用户名
+    
+    基于灵敏度分析方法确定压力传感器的最优放置位置。
+    """
     item = data.dict()
     pressure_sensor_placement_sensitivity(
         name=item["name"],
@@ -517,19 +767,46 @@ async def fastapi_pressure_sensor_placement_sensitivity(
     )
 
 
-@router.get("/pressuresensorplacementkmeans/")
+@router.get("/pressuresensorplacementkmeans/", summary="压力传感器放置-KMeans聚类分析（基础）", description="基于KMeans聚类算法，为指定管网项目确定压力传感器的最优放置位置。此为基础版本。")
 async def pressure_sensor_placement_kmeans_endpoint(
-    name: str, scheme_name: str, sensor_number: int, min_diameter: int, username: str
+    name: str = Query(..., description="管网名称（或数据库名称）"),
+    scheme_name: str = Query(..., description="放置方案名称"),
+    sensor_number: int = Query(..., description="传感器数量"),
+    min_diameter: int = Query(..., description="最小管径限制（毫米）"),
+    username: str = Query(..., description="用户名"),
 ):
+    """
+    压力传感器放置-KMeans聚类分析（基础版本）
+    
+    - **name**: 管网名称（或数据库名称）
+    - **scheme_name**: 放置方案名称
+    - **sensor_number**: 传感器数量
+    - **min_diameter**: 最小管径限制（毫米）
+    - **username**: 用户名
+    
+    基于KMeans聚类算法确定传感器放置位置。
+    """
     return pressure_sensor_placement_kmeans(
         name, scheme_name, sensor_number, min_diameter, username
     )
 
 
-@router.post("/pressure_sensor_placement_kmeans/")
+@router.post("/pressure_sensor_placement_kmeans/", summary="压力传感器放置-KMeans聚类分析（高级）", description="高级版本的压力传感器放置分析，通过JSON请求体提供详细参数。基于KMeans聚类算法确定最优放置位置。")
 async def fastapi_pressure_sensor_placement_kmeans(
-    data: PressureSensorPlacement,
+    data: PressureSensorPlacement = Body(..., description="传感器放置分析参数"),
 ) -> None:
+    """
+    压力传感器放置-KMeans聚类分析（高级版本）
+    
+    请求体参数：
+    - **name**: 管网名称（或数据库名称）
+    - **scheme_name**: 放置方案名称
+    - **sensor_number**: 传感器数量
+    - **min_diameter**: 最小管径限制（毫米）
+    - **username**: 用户名
+    
+    基于KMeans聚类算法确定压力传感器的最优放置位置。
+    """
     item = data.dict()
     pressure_sensor_placement_kmeans(
         name=item["name"],
@@ -540,16 +817,31 @@ async def fastapi_pressure_sensor_placement_kmeans(
     )
 
 
-@router.post("/sensorplacementscheme/create")
+@router.post("/sensorplacementscheme/create", summary="传感器放置方案创建", description="创建新的传感器放置方案，支持灵敏度分析和KMeans聚类两种方法。根据指定的方法自动计算最优的传感器放置位置。")
 async def fastapi_pressure_sensor_placement(
-    network: str = Query(...),
-    scheme_name: str = Query(...),
-    sensor_type: str = Query(...),
-    method: str = Query(...),
-    sensor_count: int = Query(...),
-    min_diameter: int = Query(0),
-    user_name: str = Query(...),
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    scheme_name: str = Query(..., description="放置方案名称"),
+    sensor_type: str = Query(..., description="传感器类型"),
+    method: str = Query(..., description="放置方法（'sensitivity'或'kmeans'）"),
+    sensor_count: int = Query(..., description="传感器数量"),
+    min_diameter: int = Query(0, description="最小管径限制（毫米），默认0"),
+    user_name: str = Query(..., description="用户名"),
 ) -> str:
+    """
+    传感器放置方案创建
+    
+    - **network**: 管网名称（或数据库名称）
+    - **scheme_name**: 放置方案名称
+    - **sensor_type**: 传感器类型
+    - **method**: 放置方法（'sensitivity'或'kmeans'）
+    - **sensor_count**: 传感器数量
+    - **min_diameter**: 最小管径限制（毫米，默认0）
+    - **user_name**: 用户名
+    
+    支持两种放置方法：
+    - sensitivity: 基于灵敏度分析
+    - kmeans: 基于KMeans聚类
+    """
     if method not in ["sensitivity", "kmeans"]:
         raise HTTPException(
             status_code=400, detail="Invalid method. Must be 'sensitivity' or 'kmeans'"
@@ -573,67 +865,22 @@ async def fastapi_pressure_sensor_placement(
     return "success"
 
 
-@router.post("/scadadevicedatacleaning/")
-async def fastapi_scada_device_data_cleaning(
-    network: str = Query(...),
-    ids_list: List[str] = Query(...),
-    start_time: str = Query(...),
-    end_time: str = Query(...),
-    user_name: str = Query(...),
-) -> str:
-    item = {
-        "network": network,
-        "ids": ids_list,
-        "start_time": start_time,
-        "end_time": end_time,
-        "user_name": user_name,
-    }
-    query_ids_list = item["ids"][0].split(",")
-    scada_data = influxdb_api.query_SCADA_data_by_device_ID_and_timerange(
-        query_ids_list=query_ids_list,
-        start_time=item["start_time"],
-        end_time=item["end_time"],
-    )
-    scada_device_info = influxdb_api.query_pg_scada_info(item["network"])
-    scada_device_info_dict = {info["id"]: info for info in scada_device_info}
-    type_groups: dict[str, list[str]] = {}
-    for device_id in query_ids_list:
-        device_info = scada_device_info_dict.get(device_id, {})
-        device_type = device_info.get("type", "unknown")
-        type_groups.setdefault(device_type, []).append(device_id)
-    for device_type, device_ids in type_groups.items():
-        if device_type not in ["pressure", "pipe_flow"]:
-            continue
-        type_scada_data = {
-            device_id: scada_data[device_id]
-            for device_id in device_ids
-            if device_id in scada_data
-        }
-        if not type_scada_data:
-            continue
-        time_list = [record["time"] for record in next(iter(type_scada_data.values()))]
-        df = pd.DataFrame({"time": time_list})
-        for device_id in device_ids:
-            if device_id in type_scada_data:
-                values = [record["value"] for record in type_scada_data[device_id]]
-                df[device_id] = values
-        if device_type == "pressure":
-            cleaned_value_df = pressure_data_clean.clean_pressure_data_df_km(df)
-        elif device_type == "pipe_flow":
-            cleaned_value_df = flow_data_clean.clean_flow_data_df_kf(df)
-        cleaned_value_df = pd.DataFrame(cleaned_value_df)
-        cleaned_df = pd.concat([df["time"], cleaned_value_df], axis=1)
-        influxdb_api.import_multicolumn_data_from_dict(
-            data_dict=cleaned_df.to_dict("list"),
-            raw=False,
-        )
-    return "success"
-
-
-@router.post("/runsimulationmanuallybydate/")
+@router.post("/runsimulationmanuallybydate/", summary="手动运行日期指定模拟", description="根据指定的日期、开始时间和持续时间，手动运行水力模拟。系统将自动查询管网参数并执行模拟。")
 async def fastapi_run_simulation_manually_by_date(
-    data: RunSimulationManuallyByDate,
+    data: RunSimulationManuallyByDate = Body(..., description="模拟运行参数"),
 ) -> dict[str, str]:
+    """
+    手动运行日期指定模拟
+    
+    请求体参数：
+    - **name**: 管网名称（或数据库名称）
+    - **simulation_date**: 模拟基准日期（YYYY-MM-DD格式）
+    - **start_time**: 开始时间（HH:MM或HH:MM:SS格式）
+    - **duration**: 模拟持续时间（分钟）
+    
+    系统将从指定日期和时间开始，按15分钟间隔多次运行模拟。
+    每次模拟间隔15分钟，直至达到指定的总持续时间。
+    """
     item = data.dict()
     try:
         simulation.query_corresponding_element_id_and_query_id(item["name"])

app/api/v1/endpoints/snapshots.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query
 from app.services.tjnetwork import (
     ChangeSet,
     get_current_operation,
@@ -22,90 +22,183 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/getcurrentoperationid/")
-async def get_current_operation_id_endpoint(network: str) -> int:
+@router.get("/getcurrentoperationid/", summary="获取当前操作ID", description="获取网络当前的操作ID")
+async def get_current_operation_id_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")) -> int:
+    """
+    获取当前操作ID
+    
+    返回网络当前正在执行的操作ID
+    """
     return get_current_operation(network)
 
-@router.post("/undo/")
-async def undo_endpoint(network: str):
+@router.post("/undo/", summary="撤销操作", description="撤销网络上最后的一个操作")
+async def undo_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")):
+    """
+    撤销操作
+    
+    撤销网络上最近执行的一个操作
+    """
     return execute_undo(network)
 
-@router.post("/redo/")
-async def redo_endpoint(network: str):
+@router.post("/redo/", summary="重做操作", description="重做网络上被撤销的操作")
+async def redo_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")):
+    """
+    重做操作
+    
+    重做网络上被撤销的操作
+    """
     return execute_redo(network)
 
-@router.get("/getsnapshots/")
-async def list_snapshot_endpoint(network: str) -> list[tuple[int, str]]:
+@router.get("/getsnapshots/", summary="获取快照列表", description="获取网络中的所有快照")
+async def list_snapshot_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[tuple[int, str]]:
+    """
+    获取快照列表
+    
+    返回网络中所有可用的快照及其信息
+    """
     return list_snapshot(network)
 
-@router.get("/havesnapshot/")
-async def have_snapshot_endpoint(network: str, tag: str) -> bool:
+@router.get("/havesnapshot/", summary="检查快照是否存在", description="检查指定标签的快照是否存在")
+async def have_snapshot_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), tag: str = Query(..., description="快照标签")) -> bool:
+    """
+    检查快照是否存在
+    
+    返回指定标签的快照是否存在
+    """
     return have_snapshot(network, tag)
 
-@router.get("/havesnapshotforoperation/")
-async def have_snapshot_for_operation_endpoint(network: str, operation: int) -> bool:
+@router.get("/havesnapshotforoperation/", summary="检查操作快照是否存在", description="检查指定操作ID的快照是否存在")
+async def have_snapshot_for_operation_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), operation: int = Query(..., description="操作ID")) -> bool:
+    """
+    检查操作快照是否存在
+    
+    返回指定操作ID的快照是否存在
+    """
     return have_snapshot_for_operation(network, operation)
 
-@router.get("/havesnapshotforcurrentoperation/")
-async def have_snapshot_for_current_operation_endpoint(network: str) -> bool:
+@router.get("/havesnapshotforcurrentoperation/", summary="检查当前操作快照是否存在", description="检查当前操作的快照是否存在")
+async def have_snapshot_for_current_operation_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")) -> bool:
+    """
+    检查当前操作快照是否存在
+    
+    返回当前操作的快照是否存在
+    """
     return have_snapshot_for_current_operation(network)
 
-@router.post("/takesnapshotforoperation/")
+@router.post("/takesnapshotforoperation/", summary="为操作创建快照", description="为指定的操作创建快照")
 async def take_snapshot_for_operation_endpoint(
-    network: str, operation: int, tag: str
+    network: str = Query(..., description="管网名称（或数据库名称）"), 
+    operation: int = Query(..., description="操作ID"), 
+    tag: str = Query(..., description="快照标签")
 ) -> None:
+    """
+    为操作创建快照
+    
+    为指定操作创建一个带标签的快照
+    """
     return take_snapshot_for_operation(network, operation, tag)
 
-@router.post("/takesnapshotforcurrentoperation")
-async def take_snapshot_for_current_operation_endpoint(network: str, tag: str) -> None:
+@router.post("/takesnapshotforcurrentoperation", summary="为当前操作创建快照", description="为当前操作创建快照")
+async def take_snapshot_for_current_operation_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), tag: str = Query(..., description="快照标签")) -> None:
+    """
+    为当前操作创建快照
+    
+    为网络当前操作创建一个快照
+    """
     return take_snapshot_for_current_operation(network, tag)
 
 # 兼容旧拼写: takenapshotforcurrentoperation
-@router.post("/takenapshotforcurrentoperation")
-async def take_snapshot_for_current_operation_legacy_endpoint(
-    network: str, tag: str
-) -> None:
+@router.post("/takenapshotforcurrentoperation", summary="为当前操作创建快照（兼容模式）", description="为当前操作创建快照（兼容旧的API路径）")
+async def take_snapshot_for_current_operation_legacy_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), tag: str = Query(..., description="快照标签")) -> None:
+    """
+    为当前操作创建快照（兼容模式）
+    
+    兼容旧的API路径，为网络当前操作创建一个快照
+    """
     return take_snapshot_for_current_operation(network, tag)
 
-@router.post("/takesnapshot/")
-async def take_snapshot_endpoint(network: str, tag: str) -> None:
+@router.post("/takesnapshot/", summary="创建快照", description="为网络创建一个快照")
+async def take_snapshot_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), tag: str = Query(..., description="快照标签")) -> None:
+    """
+    创建快照
+    
+    为网络创建一个带标签的快照
+    """
     return take_snapshot(network, tag)
 
-@router.post("/picksnapshot/", response_model=None)
-async def pick_snapshot_endpoint(network: str, tag: str, discard: bool = False) -> ChangeSet:
+@router.post("/picksnapshot/", summary="选择快照", description="选择并恢复到指定的快照", response_model=None)
+async def pick_snapshot_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), tag: str = Query(..., description="快照标签"), discard: bool = Query(False, description="是否丢弃当前更改")) -> ChangeSet:
+    """
+    选择快照
+    
+    选择并恢复到指定的快照
+    """
     return pick_snapshot(network, tag, discard)
 
-@router.post("/pickoperation/", response_model=None)
+@router.post("/pickoperation/", summary="选择操作", description="选择并恢复到指定的操作", response_model=None)
 async def pick_operation_endpoint(
-    network: str, operation: int, discard: bool = False
+    network: str = Query(..., description="管网名称（或数据库名称）"), 
+    operation: int = Query(..., description="操作ID"), 
+    discard: bool = Query(False, description="是否丢弃当前更改")
 ) -> ChangeSet:
+    """
+    选择操作
+    
+    选择并恢复到指定的操作
+    """
     return pick_operation(network, operation, discard)
 
-@router.get("/syncwithserver/", response_model=None)
-async def sync_with_server_endpoint(network: str, operation: int) -> ChangeSet:
+@router.get("/syncwithserver/", summary="与服务器同步", description="将网络与服务器同步到指定操作", response_model=None)
+async def sync_with_server_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), operation: int = Query(..., description="目标操作ID")) -> ChangeSet:
+    """
+    与服务器同步
+    
+    将网络与服务器同步到指定的操作
+    """
     return sync_with_server(network, operation)
 
-@router.post("/batch/", response_model=None)
-async def execute_batch_commands_endpoint(network: str, req: Request) -> ChangeSet:
+@router.post("/batch/", summary="执行批量命令", description="执行多个网络操作命令", response_model=None)
+async def execute_batch_commands_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), req: Request = None) -> ChangeSet:
+    """
+    执行批量命令
+    
+    在网络上执行多个操作命令
+    """
     jo_root = await req.json()
     cs: ChangeSet = ChangeSet()
     cs.operations = jo_root["operations"]
     rcs = execute_batch_commands(network, cs)
     return rcs
 
-@router.post("/compressedbatch/", response_model=None)
+@router.post("/compressedbatch/", summary="执行压缩批量命令", description="执行压缩的批量命令", response_model=None)
 async def execute_compressed_batch_commands_endpoint(
-    network: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"), 
+    req: Request = None
 ) -> ChangeSet:
+    """
+    执行压缩批量命令
+    
+    执行压缩格式的批量命令
+    """
     jo_root = await req.json()
     cs: ChangeSet = ChangeSet()
     cs.operations = jo_root["operations"]
     return execute_batch_command(network, cs)
 
-@router.get("/getrestoreoperation/")
-async def get_restore_operation_endpoint(network: str) -> int:
+@router.get("/getrestoreoperation/", summary="获取恢复操作ID", description="获取网络的恢复操作ID")
+async def get_restore_operation_endpoint(network: str = Query(..., description="管网名称（或数据库名称）")) -> int:
+    """
+    获取恢复操作ID
+    
+    返回网络的恢复操作ID
+    """
     return get_restore_operation(network)
 
-@router.post("/setrestoreoperation/")
-async def set_restore_operation_endpoint(network: str, operation: int) -> None:
+@router.post("/setrestoreoperation/", summary="设置恢复操作ID", description="设置网络的恢复操作ID")
+async def set_restore_operation_endpoint(network: str = Query(..., description="管网名称（或数据库名称）"), operation: int = Query(..., description="操作ID")) -> None:
+    """
+    设置恢复操作ID
+    
+    设置网络的恢复操作ID
+    """
     return set_restore_operation(network, operation)

app/api/v1/endpoints/timeseries/composite.py

@@ -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

@@ -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

@@ -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

@@ -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

app/api/v1/endpoints/user_management.py

@@ -3,178 +3,213 @@
 
 演示权限控制的使用
 """
+
 from typing import List
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Path, Query
 from app.domain.schemas.user import UserResponse, UserUpdate, UserCreate
 from app.domain.models.role import UserRole
 from app.domain.schemas.user import UserInDB
-from app.infra.repositories.user_repository import UserRepository
+from app.infra.db.metadb.repositories.user_repository import UserRepository
 from app.auth.dependencies import get_user_repository, get_current_active_user
 from app.auth.permissions import get_current_admin, require_role, check_resource_owner
 
 router = APIRouter()
 
-@router.get("/", response_model=List[UserResponse])
+
+@router.get(
+    "/",
+    summary="列出所有用户",
+    description="获取用户列表（仅管理员）",
+    response_model=List[UserResponse],
+)
 async def list_users(
-    skip: int = 0,
-    limit: int = 100,
+    skip: int = Query(0, ge=0, description="跳过的用户数"),
+    limit: int = Query(100, ge=1, le=1000, description="返回的最大用户数"),
     current_user: UserInDB = Depends(require_role(UserRole.ADMIN)),
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> List[UserResponse]:
     """
-    获取用户列表（仅管理员）
+    获取用户列表
+
+    获取系统中所有的用户信息（需要管理员权限）
     """
     users = await user_repo.get_all_users(skip=skip, limit=limit)
     return [UserResponse.model_validate(user) for user in users]
 
-@router.get("/{user_id}", response_model=UserResponse)
+
+@router.get(
+    "/{user_id}",
+    summary="获取用户详情",
+    description="获取指定用户的详细信息",
+    response_model=UserResponse,
+)
 async def get_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_active_user),
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> UserResponse:
     """
     获取用户详情
-    
+
     管理员可查看所有用户，普通用户只能查看自己
     """
     # 检查权限
     if not check_resource_owner(user_id, current_user):
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have permission to view this user"
+            detail="You don't have permission to view this user",
         )
-    
+
     user = await user_repo.get_user_by_id(user_id)
     if not user:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="User not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
         )
-    
+
     return UserResponse.model_validate(user)
 
-@router.put("/{user_id}", response_model=UserResponse)
+
+@router.put(
+    "/{user_id}",
+    summary="更新用户信息",
+    description="更新指定用户的信息",
+    response_model=UserResponse,
+)
 async def update_user(
-    user_id: int,
-    user_update: UserUpdate,
+    user_id: int = Path(..., gt=0, description="用户ID"),
+    user_update: UserUpdate = None,
     current_user: UserInDB = Depends(get_current_active_user),
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> UserResponse:
     """
     更新用户信息
-    
+
     管理员可更新所有用户，普通用户只能更新自己（且不能修改角色）
     """
     # 检查用户是否存在
     target_user = await user_repo.get_user_by_id(user_id)
     if not target_user:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="User not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
         )
-    
+
     # 权限检查
     is_owner = current_user.id == user_id
     is_admin = UserRole(current_user.role).has_permission(UserRole.ADMIN)
-    
+
     if not is_owner and not is_admin:
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have permission to update this user"
+            detail="You don't have permission to update this user",
         )
-    
+
     # 非管理员不能修改角色和激活状态
     if not is_admin:
         if user_update.role is not None:
             raise HTTPException(
                 status_code=status.HTTP_403_FORBIDDEN,
-                detail="Only admins can change user roles"
+                detail="Only admins can change user roles",
             )
         if user_update.is_active is not None:
             raise HTTPException(
                 status_code=status.HTTP_403_FORBIDDEN,
-                detail="Only admins can change user active status"
+                detail="Only admins can change user active status",
             )
-    
+
     # 更新用户
     updated_user = await user_repo.update_user(user_id, user_update)
     if not updated_user:
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="Failed to update user"
+            detail="Failed to update user",
         )
-    
+
     return UserResponse.model_validate(updated_user)
 
-@router.delete("/{user_id}")
+
+@router.delete("/{user_id}", summary="删除用户", description="删除指定用户（仅管理员）")
 async def delete_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_admin),
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> dict:
     """
-    删除用户（仅管理员）
+    删除用户
+
+    删除指定用户（需要管理员权限，不能删除自己）
     """
     # 不能删除自己
     if current_user.id == user_id:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail="You cannot delete your own account"
+            detail="You cannot delete your own account",
         )
-    
+
     success = await user_repo.delete_user(user_id)
     if not success:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="User not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
         )
-    
+
     return {"message": "User deleted successfully"}
 
-@router.post("/{user_id}/activate")
+
+@router.post(
+    "/{user_id}/activate",
+    summary="激活用户",
+    description="激活指定用户账户（仅管理员）",
+    response_model=UserResponse,
+)
 async def activate_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_admin),
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> UserResponse:
     """
-    激活用户（仅管理员）
+    激活用户
+
+    激活指定用户的账户（需要管理员权限）
     """
     user_update = UserUpdate(is_active=True)
     updated_user = await user_repo.update_user(user_id, user_update)
-    
+
     if not updated_user:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="User not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
         )
-    
+
     return UserResponse.model_validate(updated_user)
 
-@router.post("/{user_id}/deactivate")
+
+@router.post(
+    "/{user_id}/deactivate",
+    summary="停用用户",
+    description="停用指定用户账户（仅管理员）",
+    response_model=UserResponse,
+)
 async def deactivate_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_admin),
-    user_repo: UserRepository = Depends(get_user_repository)
+    user_repo: UserRepository = Depends(get_user_repository),
 ) -> UserResponse:
     """
-    停用用户（仅管理员）
+    停用用户
+
+    停用指定用户的账户（需要管理员权限，不能停用自己）
     """
     # 不能停用自己
     if current_user.id == user_id:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail="You cannot deactivate your own account"
+            detail="You cannot deactivate your own account",
         )
-    
+
     user_update = UserUpdate(is_active=False)
     updated_user = await user_repo.update_user(user_id, user_update)
-    
+
     if not updated_user:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="User not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
         )
-    
+
     return UserResponse.model_validate(updated_user)

app/api/v1/endpoints/users.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import Any, get_all_users, get_user, get_user_schema
 
@@ -8,14 +8,29 @@ router = APIRouter()
 # user 39
 ###########################################################
 
-@router.get("/getuserschema/")
-async def fastapi_get_user_schema(network: str) -> dict[str, dict[Any, Any]]:
+@router.get("/getuserschema/", summary="获取用户模式", description="获取指定网络的用户模式定义")
+async def fastapi_get_user_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[Any, Any]]:
+    """
+    获取用户模式定义
+    
+    返回指定网络的用户模式结构定义
+    """
     return get_user_schema(network)
 
-@router.get("/getuser/")
-async def fastapi_get_user(network: str, user_name: str) -> dict[Any, Any]:
+@router.get("/getuser/", summary="获取单个用户", description="获取指定网络中的单个用户信息")
+async def fastapi_get_user(network: str = Query(..., description="管网名称（或数据库名称）"), user_name: str = Query(..., description="用户名")) -> dict[Any, Any]:
+    """
+    获取用户信息
+    
+    返回指定网络中指定用户名的详细信息
+    """
     return get_user(network, user_name)
 
-@router.get("/getallusers/")
-async def fastapi_get_all_users(network: str) -> list[dict[Any, Any]]:
+@router.get("/getallusers/", summary="获取所有用户", description="获取指定网络的所有用户列表")
+async def fastapi_get_all_users(network: str = Query(..., description="管网名称（或数据库名称）")) -> list[dict[Any, Any]]:
+    """
+    获取所有用户列表
+    
+    返回指定网络中所有用户的信息
+    """
     return get_all_users(network)

app/auth/dependencies.py

@@ -4,7 +4,7 @@ from fastapi.security import OAuth2PasswordBearer
 from jose import jwt, JWTError
 from app.core.config import settings
 from app.domain.schemas.user import UserInDB, TokenPayload
-from app.infra.repositories.user_repository import UserRepository
+from app.infra.db.metadb.repositories.user_repository import UserRepository
 from app.infra.db.postgresql.database import Database
 
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.API_V1_STR}/auth/login")

app/auth/metadata_dependencies.py

@@ -8,8 +8,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.auth.keycloak_dependencies import get_current_keycloak_sub
 from app.core.config import settings
-from app.infra.db.metadata.database import get_metadata_session
-from app.infra.repositories.metadata_repository import MetadataRepository
+from app.infra.db.metadb.database import get_metadata_session
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
 
 logger = logging.getLogger(__name__)
 

app/auth/project_dependencies.py

@@ -11,8 +11,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.auth.keycloak_dependencies import get_current_keycloak_sub
 from app.core.config import settings
 from app.infra.db.dynamic_manager import project_connection_manager
-from app.infra.db.metadata.database import get_metadata_session
-from app.infra.repositories.metadata_repository import MetadataRepository
+from app.infra.db.metadb.database import get_metadata_session
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
 
 DB_ROLE_BIZ_DATA = "biz_data"
 DB_ROLE_IOT_DATA = "iot_data"

app/core/audit.py

@@ -66,8 +66,8 @@ async def log_audit_event(
         response_status: 响应状态码
         session: 元数据库会话（可选）
     """
-    from app.infra.db.metadata.database import SessionLocal
-    from app.infra.repositories.audit_repository import AuditRepository
+    from app.infra.db.metadb.database import SessionLocal
+    from app.infra.db.metadb.repositories.audit_repository import AuditRepository
 
     if request_data:
         request_data = sanitize_sensitive_data(request_data)

app/core/config.py

@@ -116,3 +116,37 @@ def get_pg_config() -> dict:
 def get_pg_password() -> str:
     """Return PostgreSQL password (use with care)."""
     return settings.DB_PASSWORD
+
+
+def get_timescaledb_pgconn_string(
+    db_name: Optional[str] = None,
+    db_host: Optional[str] = None,
+    db_port: Optional[str] = None,
+    db_user: Optional[str] = None,
+    db_password: Optional[str] = None,
+) -> str:
+    """Return TimescaleDB connection string in psycopg conninfo format."""
+    resolved_db_name = db_name or settings.TIMESCALEDB_DB_NAME
+    resolved_db_host = db_host or settings.TIMESCALEDB_DB_HOST
+    resolved_db_port = db_port or settings.TIMESCALEDB_DB_PORT
+    resolved_db_user = db_user or settings.TIMESCALEDB_DB_USER
+    resolved_db_password = db_password or settings.TIMESCALEDB_DB_PASSWORD
+    return (
+        f"dbname={resolved_db_name} host={resolved_db_host} port={resolved_db_port} "
+        f"user={resolved_db_user} password={resolved_db_password}"
+    )
+
+
+def get_timescaledb_pg_config() -> dict:
+    """Return TimescaleDB configuration except password."""
+    return {
+        "name": settings.TIMESCALEDB_DB_NAME,
+        "host": settings.TIMESCALEDB_DB_HOST,
+        "port": settings.TIMESCALEDB_DB_PORT,
+        "user": settings.TIMESCALEDB_DB_USER,
+    }
+
+
+def get_timescaledb_pg_password() -> str:
+    """Return TimescaleDB password (use with care)."""
+    return settings.TIMESCALEDB_DB_PASSWORD

app/domain/schemas/metadata.py

@@ -18,6 +18,7 @@ class ProjectMetaResponse(BaseModel):
     code: str
     description: Optional[str]
     gs_workspace: str
+    map_extent: Optional[dict]
     status: str
     project_role: str
     geoserver: Optional[GeoServerConfigResponse]

app/infra/audit/middleware.py

@@ -15,8 +15,8 @@ import logging
 from jose import JWTError, jwt
 
 from app.core.config import settings
-from app.infra.db.metadata.database import SessionLocal
-from app.infra.repositories.metadata_repository import MetadataRepository
+from app.infra.db.metadb.database import SessionLocal
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
 
 logger = logging.getLogger(__name__)
 

app/infra/db/dynamic_manager.py

@@ -24,6 +24,17 @@ logger = logging.getLogger(__name__)
 class PgEngineEntry:
     engine: AsyncEngine
     sessionmaker: async_sessionmaker[AsyncSession]
+    connection_url: str
+    pool_min_size: int
+    pool_max_size: int
+
+
+@dataclass(frozen=True)
+class PoolEntry:
+    pool: AsyncConnectionPool
+    connection_url: str
+    pool_min_size: int
+    pool_max_size: int
 
 
 @dataclass(frozen=True)
@@ -35,8 +46,8 @@ class CacheKey:
 class ProjectConnectionManager:
     def __init__(self) -> None:
         self._pg_cache: Dict[CacheKey, PgEngineEntry] = OrderedDict()
-        self._ts_cache: Dict[CacheKey, AsyncConnectionPool] = OrderedDict()
-        self._pg_raw_cache: Dict[CacheKey, AsyncConnectionPool] = OrderedDict()
+        self._ts_cache: Dict[CacheKey, PoolEntry] = OrderedDict()
+        self._pg_raw_cache: Dict[CacheKey, PoolEntry] = OrderedDict()
         self._pg_lock = asyncio.Lock()
         self._ts_lock = asyncio.Lock()
         self._pg_raw_lock = asyncio.Lock()
@@ -56,15 +67,29 @@ class ProjectConnectionManager:
         pool_max_size: int,
     ) -> async_sessionmaker[AsyncSession]:
         async with self._pg_lock:
-            key = CacheKey(project_id=project_id, db_role=db_role)
-            entry = self._pg_cache.get(key)
-            if entry:
-                self._pg_cache.move_to_end(key)
-                return entry.sessionmaker
-
             normalized_url = self._normalize_pg_url(connection_url)
             pool_min_size = max(1, pool_min_size)
             pool_max_size = max(pool_min_size, pool_max_size)
+
+            key = CacheKey(project_id=project_id, db_role=db_role)
+            entry = self._pg_cache.get(key)
+            if entry:
+                if (
+                    entry.connection_url == normalized_url
+                    and entry.pool_min_size == pool_min_size
+                    and entry.pool_max_size == pool_max_size
+                ):
+                    self._pg_cache.move_to_end(key)
+                    return entry.sessionmaker
+
+                await entry.engine.dispose()
+                logger.info(
+                    "Rebuilding PostgreSQL engine for project %s (%s) due to config change",
+                    project_id,
+                    db_role,
+                )
+                self._pg_cache.pop(key, None)
+
             engine = create_async_engine(
                 normalized_url,
                 pool_size=pool_min_size,
@@ -75,6 +100,9 @@ class ProjectConnectionManager:
             self._pg_cache[key] = PgEngineEntry(
                 engine=engine,
                 sessionmaker=sessionmaker,
+                connection_url=normalized_url,
+                pool_min_size=pool_min_size,
+                pool_max_size=pool_max_size,
             )
             await self._evict_pg_if_needed()
             logger.info(
@@ -91,14 +119,28 @@ class ProjectConnectionManager:
         pool_max_size: int,
     ) -> AsyncConnectionPool:
         async with self._ts_lock:
-            key = CacheKey(project_id=project_id, db_role=db_role)
-            pool = self._ts_cache.get(key)
-            if pool:
-                self._ts_cache.move_to_end(key)
-                return pool
-
             pool_min_size = max(1, pool_min_size)
             pool_max_size = max(pool_min_size, pool_max_size)
+
+            key = CacheKey(project_id=project_id, db_role=db_role)
+            entry = self._ts_cache.get(key)
+            if entry:
+                if (
+                    entry.connection_url == connection_url
+                    and entry.pool_min_size == pool_min_size
+                    and entry.pool_max_size == pool_max_size
+                ):
+                    self._ts_cache.move_to_end(key)
+                    return entry.pool
+
+                await entry.pool.close()
+                logger.info(
+                    "Rebuilding TimescaleDB pool for project %s (%s) due to config change",
+                    project_id,
+                    db_role,
+                )
+                self._ts_cache.pop(key, None)
+
             pool = AsyncConnectionPool(
                 conninfo=connection_url,
                 min_size=pool_min_size,
@@ -107,7 +149,12 @@ class ProjectConnectionManager:
                 kwargs={"row_factory": dict_row},
             )
             await pool.open()
-            self._ts_cache[key] = pool
+            self._ts_cache[key] = PoolEntry(
+                pool=pool,
+                connection_url=connection_url,
+                pool_min_size=pool_min_size,
+                pool_max_size=pool_max_size,
+            )
             await self._evict_ts_if_needed()
             logger.info(
                 "Created TimescaleDB pool for project %s (%s)", project_id, db_role
@@ -123,14 +170,28 @@ class ProjectConnectionManager:
         pool_max_size: int,
     ) -> AsyncConnectionPool:
         async with self._pg_raw_lock:
-            key = CacheKey(project_id=project_id, db_role=db_role)
-            pool = self._pg_raw_cache.get(key)
-            if pool:
-                self._pg_raw_cache.move_to_end(key)
-                return pool
-
             pool_min_size = max(1, pool_min_size)
             pool_max_size = max(pool_min_size, pool_max_size)
+
+            key = CacheKey(project_id=project_id, db_role=db_role)
+            entry = self._pg_raw_cache.get(key)
+            if entry:
+                if (
+                    entry.connection_url == connection_url
+                    and entry.pool_min_size == pool_min_size
+                    and entry.pool_max_size == pool_max_size
+                ):
+                    self._pg_raw_cache.move_to_end(key)
+                    return entry.pool
+
+                await entry.pool.close()
+                logger.info(
+                    "Rebuilding PostgreSQL pool for project %s (%s) due to config change",
+                    project_id,
+                    db_role,
+                )
+                self._pg_raw_cache.pop(key, None)
+
             pool = AsyncConnectionPool(
                 conninfo=connection_url,
                 min_size=pool_min_size,
@@ -139,7 +200,12 @@ class ProjectConnectionManager:
                 kwargs={"row_factory": dict_row},
             )
             await pool.open()
-            self._pg_raw_cache[key] = pool
+            self._pg_raw_cache[key] = PoolEntry(
+                pool=pool,
+                connection_url=connection_url,
+                pool_min_size=pool_min_size,
+                pool_max_size=pool_max_size,
+            )
             await self._evict_pg_raw_if_needed()
             logger.info(
                 "Created PostgreSQL pool for project %s (%s)", project_id, db_role
@@ -158,8 +224,8 @@ class ProjectConnectionManager:
 
     async def _evict_ts_if_needed(self) -> None:
         while len(self._ts_cache) > settings.PROJECT_TS_CACHE_SIZE:
-            key, pool = self._ts_cache.popitem(last=False)
-            await pool.close()
+            key, entry = self._ts_cache.popitem(last=False)
+            await entry.pool.close()
             logger.info(
                 "Evicted TimescaleDB pool for project %s (%s)",
                 key.project_id,
@@ -168,8 +234,8 @@ class ProjectConnectionManager:
 
     async def _evict_pg_raw_if_needed(self) -> None:
         while len(self._pg_raw_cache) > settings.PROJECT_PG_CACHE_SIZE:
-            key, pool = self._pg_raw_cache.popitem(last=False)
-            await pool.close()
+            key, entry = self._pg_raw_cache.popitem(last=False)
+            await entry.pool.close()
             logger.info(
                 "Evicted PostgreSQL pool for project %s (%s)",
                 key.project_id,
@@ -188,8 +254,8 @@ class ProjectConnectionManager:
             self._pg_cache.clear()
 
         async with self._ts_lock:
-            for key, pool in list(self._ts_cache.items()):
-                await pool.close()
+            for key, entry in list(self._ts_cache.items()):
+                await entry.pool.close()
                 logger.info(
                     "Closed TimescaleDB pool for project %s (%s)",
                     key.project_id,
@@ -198,8 +264,8 @@ class ProjectConnectionManager:
             self._ts_cache.clear()
 
         async with self._pg_raw_lock:
-            for key, pool in list(self._pg_raw_cache.items()):
-                await pool.close()
+            for key, entry in list(self._pg_raw_cache.items()):
+                await entry.pool.close()
                 logger.info(
                     "Closed PostgreSQL pool for project %s (%s)",
                     key.project_id,

app/infra/db/metadb/models.py

@@ -42,6 +42,7 @@ class Project(Base):
     code: Mapped[str] = mapped_column(String(50), unique=True)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     gs_workspace: Mapped[str] = mapped_column(String(100), unique=True)
+    map_extent: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
     status: Mapped[str] = mapped_column(String(20), default="active")
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=datetime.utcnow

app/infra/db/metadb/repositories/audit_repository.py

@@ -6,7 +6,7 @@ from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.domain.schemas.audit import AuditLogResponse
-from app.infra.db.metadata import models
+from app.infra.db.metadb import models
 
 
 class AuditRepository:

app/infra/db/metadb/repositories/metadata_repository.py

@@ -12,7 +12,7 @@ from app.core.encryption import (
     is_database_encryption_configured,
     is_encryption_configured,
 )
-from app.infra.db.metadata import models
+from app.infra.db.metadb import models
 
 
 def _normalize_postgres_dsn(dsn: str) -> str:
@@ -61,10 +61,23 @@ class ProjectSummary:
     code: str
     description: Optional[str]
     gs_workspace: str
+    map_extent: Optional[dict]
     status: str
     project_role: str
 
 
+@dataclass(frozen=True)
+class ProjectDetail:
+    project_id: UUID
+    name: str
+    code: str
+    description: Optional[str]
+    gs_workspace: str
+    map_extent: Optional[dict]
+    status: str
+    geoserver: Optional[ProjectGeoServerInfo]
+
+
 class MetadataRepository:
     """元数据访问层（system_hub）"""
 
@@ -89,6 +102,30 @@ class MetadataRepository:
         )
         return result.scalar_one_or_none()
 
+    async def get_project_by_code(self, code: str) -> Optional[models.Project]:
+        result = await self.session.execute(
+            select(models.Project).where(models.Project.code == code)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_project_detail_by_code(self, code: str) -> Optional[ProjectDetail]:
+        project = await self.get_project_by_code(code)
+        if not project:
+            return None
+        
+        geoserver = await self.get_geoserver_config(project.id)
+        
+        return ProjectDetail(
+            project_id=project.id,
+            name=project.name,
+            code=project.code,
+            description=project.description,
+            gs_workspace=project.gs_workspace,
+            map_extent=project.map_extent,
+            status=project.status,
+            geoserver=geoserver
+        )
+
     async def get_membership_role(
         self, project_id: UUID, user_id: UUID
     ) -> Optional[str]:
@@ -179,6 +216,7 @@ class MetadataRepository:
                 code=project.code,
                 description=project.description,
                 gs_workspace=project.gs_workspace,
+                map_extent=project.map_extent,
                 status=project.status,
                 project_role=role,
             )
@@ -196,6 +234,7 @@ class MetadataRepository:
                 code=project.code,
                 description=project.description,
                 gs_workspace=project.gs_workspace,
+                map_extent=project.map_extent,
                 status=project.status,
                 project_role="owner",
             )

app/infra/db/postgresql/internal_queries.py

@@ -1,83 +0,0 @@
-import time
-from typing import List, Optional
-
-from fastapi.logger import logger
-import app.core.config as postgresql_info
-import psycopg
-
-
-class InternalQueries:
-    @staticmethod
-    def get_links_by_property(
-        fields: Optional[List[str]] = None,
-        property_conditions: Optional[dict] = None,
-        db_name: str = None,
-        max_retries: int = 3,
-    ) -> List[dict]:
-        """
-        查询pg数据库中,pipes 的指定字段记录或根据属性筛选
-        :param fields: 要查询的字段列表，如 ["id", "diameter", "status"]，默认查询所有字段
-        :param property: 可选的筛选条件字典，如 {"status": "Open"} 或 {"diameter": 300}
-        :param db_name: 数据库名称
-        :param max_retries: 最大重试次数
-        :return: 包含所有记录的列表,每条记录为一个字典
-        """
-        # 如果未指定字段，查询所有字段
-        if not fields:
-            fields = [
-                "id",
-                "node1",
-                "node2",
-                "length",
-                "diameter",
-                "roughness",
-                "minor_loss",
-                "status",
-            ]
-
-        for attempt in range(max_retries):
-            try:
-                conn_string = (
-                    postgresql_info.get_pgconn_string(db_name=db_name)
-                    if db_name
-                    else postgresql_info.get_pgconn_string()
-                )
-                with psycopg.Connection.connect(conn_string) as conn:
-                    with conn.cursor() as cur:
-                        # 构建SELECT子句
-                        select_fields = ", ".join(fields)
-                        base_query = f"""
-                            SELECT {select_fields}
-                            FROM public.pipes
-                        """
-
-                        # 如果提供了筛选条件，构建WHERE子句
-                        if property_conditions:
-                            conditions = []
-                            params = []
-                            for key, value in property_conditions.items():
-                                conditions.append(f"{key} = %s")
-                                params.append(value)
-
-                            query = base_query + " WHERE " + " AND ".join(conditions)
-                            cur.execute(query, params)
-                        else:
-                            cur.execute(base_query)
-
-                        records = cur.fetchall()
-                        # 将查询结果转换为字典列表
-                        pipes = []
-                        for record in records:
-                            pipe_dict = {}
-                            for idx, field in enumerate(fields):
-                                pipe_dict[field] = record[idx]
-                            pipes.append(pipe_dict)
-
-                        return pipes
-                break  # 成功
-            except Exception as e:
-                logger.error(f"查询尝试 {attempt + 1} 失败: {e}")
-                if attempt < max_retries - 1:
-                    time.sleep(1)
-                else:
-                    raise

app/infra/db/postgresql/scada_info.py

@@ -1,36 +0,0 @@
-from typing import List, Optional, Any
-from psycopg import AsyncConnection
-
-
-class ScadaRepository:
-
-    @staticmethod
-    async def get_scadas(conn: AsyncConnection) -> List[dict]:
-        """
-        查询pg数据库中,scada_info 的所有记录
-        :param conn: 异步数据库连接
-        :return: 包含所有记录的列表,每条记录为一个字典
-        """
-        async with conn.cursor() as cur:
-            await cur.execute(
-                """
-                SELECT id, type, associated_element_id, transmission_mode, transmission_frequency, reliability
-                FROM public.scada_info
-                """
-            )
-            records = await cur.fetchall()
-            # 将查询结果转换为字典列表（假设 record 是字典）
-            scada_infos = []
-            for record in records:
-                scada_infos.append(
-                    {
-                        "id": record["id"],  # 使用字典键
-                        "type": record["type"],
-                        "associated_element_id": record["associated_element_id"],
-                        "transmission_mode": record["transmission_mode"],
-                        "transmission_frequency": record["transmission_frequency"],
-                        "reliability": record["reliability"],
-                    }
-                )
-
-            return scada_infos

app/infra/db/timescaledb/__init__.py

@@ -1,3 +1,2 @@
 from .database import *
-from .timescaledb_info import *
 from .composite_queries import CompositeQueries

app/infra/db/timescaledb/composite_queries.py

@@ -7,12 +7,12 @@ import numpy as np
 from app.algorithms.cleaning.flow import clean_flow_data_df_kf
 from app.algorithms.cleaning.pressure import clean_pressure_data_df_km
 from app.algorithms.health.analyzer import PipelineHealthAnalyzer
+import app.native.wndb as wndb
 
-from app.infra.db.postgresql.internal_queries import InternalQueries
-from app.infra.db.postgresql.scada_info import ScadaRepository as PostgreScadaRepository
 from app.infra.db.timescaledb.repositories.realtime import RealtimeRepository
 from app.infra.db.timescaledb.repositories.scheme import SchemeRepository
 from app.infra.db.timescaledb.repositories.scada import ScadaRepository
+from app.services import project_info
 
 
 class CompositeQueries:
@@ -49,7 +49,8 @@ class CompositeQueries:
         """
         result = {}
         # 1. 查询所有 SCADA 信息
-        scada_infos = await PostgreScadaRepository.get_scadas(postgres_conn)
+        network_name = project_info.name
+        scada_infos = wndb.get_all_scada_info(network_name) if network_name else []
 
         for device_id in device_ids:
             # 2. 根据 device_id 找到对应的 SCADA 信息
@@ -115,7 +116,8 @@ class CompositeQueries:
         """
         result = {}
         # 1. 查询所有 SCADA 信息
-        scada_infos = await PostgreScadaRepository.get_scadas(postgres_conn)
+        network_name = project_info.name
+        scada_infos = wndb.get_all_scada_info(network_name) if network_name else []
 
         for device_id in device_ids:
             # 2. 根据 device_id 找到对应的 SCADA 信息
@@ -300,7 +302,8 @@ class CompositeQueries:
         """
 
         # 1. 查询所有 SCADA 信息
-        scada_infos = await PostgreScadaRepository.get_scadas(postgres_conn)
+        network_name = project_info.name
+        scada_infos = wndb.get_all_scada_info(network_name) if network_name else []
 
         # 2. 根据 element_type 和 element_id 找到关联的 SCADA 设备
         associated_scada = None
@@ -352,7 +355,8 @@ class CompositeQueries:
         """
         try:
             # 获取所有 SCADA 信息
-            scada_infos = await PostgreScadaRepository.get_scadas(postgres_conn)
+            network_name = project_info.name
+            scada_infos = wndb.get_all_scada_info(network_name) if network_name else []
             # 将列表转换为字典，以 device_id 为键
             scada_device_info_dict = {info["id"]: info for info in scada_infos}
 
@@ -493,10 +497,7 @@ class CompositeQueries:
 
             # 批量查询这些管道的详细信息
             fields = ["id", "diameter", "node1", "node2"]
-            all_links = InternalQueries.get_links_by_property(
-                fields=fields,
-                db_name=network_name,
-            )
+            all_links = wndb.get_pipes_by_property(network_name, fields=fields)
 
             # 转换为字典以快速查找
             links_dict = {link["id"]: link for link in all_links}

app/infra/db/timescaledb/database.py

@@ -3,7 +3,7 @@ from contextlib import asynccontextmanager
 from typing import AsyncGenerator, Dict, Optional
 import psycopg_pool
 from psycopg.rows import dict_row
-import app.infra.db.timescaledb.timescaledb_info as timescaledb_info
+from app.core.config import get_timescaledb_pgconn_string
 
 # Configure logging
 logger = logging.getLogger(__name__)
@@ -21,9 +21,9 @@ class Database:
         
         # Get connection string, handling default case where target_db_name might be None
         if target_db_name:
-            conn_string = timescaledb_info.get_pgconn_string(db_name=target_db_name)
+            conn_string = get_timescaledb_pgconn_string(db_name=target_db_name)
         else:
-            conn_string = timescaledb_info.get_pgconn_string()
+            conn_string = get_timescaledb_pgconn_string()
 
         try:
             self.pool = psycopg_pool.AsyncConnectionPool(
@@ -54,8 +54,8 @@ class Database:
         """Get the TimescaleDB connection string."""
         target_db_name = db_name or self.db_name
         if target_db_name:
-            return timescaledb_info.get_pgconn_string(db_name=target_db_name)
-        return timescaledb_info.get_pgconn_string()
+            return get_timescaledb_pgconn_string(db_name=target_db_name)
+        return get_timescaledb_pgconn_string()
 
     @asynccontextmanager
     async def get_connection(self) -> AsyncGenerator:

app/infra/db/timescaledb/internal_queries.py

@@ -6,9 +6,9 @@ import psycopg
 from psycopg import sql
 from psycopg.rows import dict_row
 import time
+from app.core.config import get_timescaledb_pgconn_string
 from app.infra.db.timescaledb.repositories.scheme import SchemeRepository
 from app.infra.db.timescaledb.repositories.realtime import RealtimeRepository
-import app.infra.db.timescaledb.timescaledb_info as timescaledb_info
 from app.infra.db.timescaledb.repositories.scada import ScadaRepository
 
 
@@ -25,9 +25,9 @@ class InternalStorage:
         for attempt in range(max_retries):
             try:
                 conn_string = (
-                    timescaledb_info.get_pgconn_string(db_name=db_name)
+                    get_timescaledb_pgconn_string(db_name=db_name)
                     if db_name
-                    else timescaledb_info.get_pgconn_string()
+                    else get_timescaledb_pgconn_string()
                 )
                 with psycopg.Connection.connect(conn_string) as conn:
                     RealtimeRepository.store_realtime_simulation_result_sync(
@@ -56,9 +56,9 @@ class InternalStorage:
         for attempt in range(max_retries):
             try:
                 conn_string = (
-                    timescaledb_info.get_pgconn_string(db_name=db_name)
+                    get_timescaledb_pgconn_string(db_name=db_name)
                     if db_name
-                    else timescaledb_info.get_pgconn_string()
+                    else get_timescaledb_pgconn_string()
                 )
                 with psycopg.Connection.connect(conn_string) as conn:
                     SchemeRepository.store_scheme_simulation_result_sync(
@@ -97,9 +97,9 @@ class InternalQueries:
         for attempt in range(max_retries):
             try:
                 conn_string = (
-                    timescaledb_info.get_pgconn_string(db_name=db_name)
+                    get_timescaledb_pgconn_string(db_name=db_name)
                     if db_name
-                    else timescaledb_info.get_pgconn_string()
+                    else get_timescaledb_pgconn_string()
                 )
                 with psycopg.Connection.connect(conn_string) as conn:
                     rows = ScadaRepository.get_scada_by_ids_time_range_sync(
@@ -144,9 +144,9 @@ class InternalQueries:
         for attempt in range(max_retries):
             try:
                 conn_string = (
-                    timescaledb_info.get_pgconn_string(db_name=db_name)
+                    get_timescaledb_pgconn_string(db_name=db_name)
                     if db_name
-                    else timescaledb_info.get_pgconn_string()
+                    else get_timescaledb_pgconn_string()
                 )
                 with psycopg.Connection.connect(conn_string) as conn:
                     rows = ScadaRepository.get_scada_by_ids_time_range_sync(
@@ -257,9 +257,9 @@ class InternalQueries:
         for attempt in range(max_retries):
             try:
                 conn_string = (
-                    timescaledb_info.get_pgconn_string(db_name=db_name)
+                    get_timescaledb_pgconn_string(db_name=db_name)
                     if db_name
-                    else timescaledb_info.get_pgconn_string()
+                    else get_timescaledb_pgconn_string()
                 )
                 with psycopg.Connection.connect(conn_string) as conn:
                     with conn.cursor(row_factory=dict_row) as cur:

app/infra/db/timescaledb/timescaledb_info.py

@@ -1,36 +0,0 @@
-from dotenv import load_dotenv
-import os
-
-load_dotenv()
-
-pg_name = os.getenv("TIMESCALEDB_DB_NAME")
-pg_host = os.getenv("TIMESCALEDB_DB_HOST")
-pg_port = os.getenv("TIMESCALEDB_DB_PORT")
-pg_user = os.getenv("TIMESCALEDB_DB_USER")
-pg_password = os.getenv("TIMESCALEDB_DB_PASSWORD")
-
-
-def get_pgconn_string(
-    db_name=pg_name,
-    db_host=pg_host,
-    db_port=pg_port,
-    db_user=pg_user,
-    db_password=pg_password,
-):
-    """返回 PostgreSQL 连接字符串"""
-    return f"dbname={db_name} host={db_host} port={db_port} user={db_user} password={db_password}"
-
-
-def get_pg_config():
-    """返回 PostgreSQL 配置变量的字典"""
-    return {
-        "name": pg_name,
-        "host": pg_host,
-        "port": pg_port,
-        "user": pg_user,
-    }
-
-
-def get_pg_password():
-    """返回密码（谨慎使用）"""
-    return pg_password

app/infra/epanet/epanet.py

@@ -8,6 +8,7 @@ from datetime import datetime
 import subprocess
 import logging
 from typing import Any
+import uuid
 
 sys.path.append("..")
 from app.native.wndb import project
@@ -281,8 +282,6 @@ class Output:
 def _dump_output(path: str) -> dict[str, Any]:
     opt = Output(path)
     data = opt.dump()
-    with open(path + ".json", "w") as f:
-        json.dump(data, f)
     return data
 
 
@@ -302,25 +301,37 @@ def dump_output_binary(path: str) -> str:
         return str(bast64_data, "utf-8")
 
 
+def _safe_remove(path: str) -> None:
+    try:
+        if os.path.exists(path):
+            os.remove(path)
+    except Exception:
+        logging.warning("failed to remove temp file: %s", path)
+
+
+def _make_isolated_run_paths(base_name: str, cwd: str) -> tuple[str, str, str]:
+    # 进程号 + UUID 生成唯一后缀，避免并发进程互相覆盖临时文件。
+    token = f"{os.getpid()}_{uuid.uuid4().hex}"
+    inp = os.path.join(cwd, "db_inp", f"{base_name}.db.{token}.inp")
+    rpt = os.path.join(cwd, "temp", f"{base_name}.db.{token}.rpt")
+    opt = os.path.join(cwd, "temp", f"{base_name}.db.{token}.opt")
+    return inp, rpt, opt
+
+
 # DingZQ, 2025-02-04, 返回dict[str, Any]
-def run_project_return_dict(name: str, readable_output: bool = False) -> dict[str, Any]:
+def run_project_return_dict(name: str, readable_output: bool = True) -> dict[str, Any]:
     if not project.have_project(name):
         raise Exception(f"Not found project [{name}]")
 
-    dir = os.path.abspath(os.getcwd())
+    cwd = os.path.abspath(os.getcwd())
 
-    db_inp = os.path.join(os.path.join(dir, "db_inp"), name + ".db.inp")
-    inp_out.dump_inp(name, db_inp, "2")
+    inp, rpt, opt = _make_isolated_run_paths(name, cwd)
+    inp_out.dump_inp(name, inp, "2")
 
-    input = name + ".db"
     if platform.system() == "Windows":
         exe = os.path.join(os.path.dirname(__file__), "windows", "runepanet.exe")
     else:
         exe = os.path.join(os.path.dirname(__file__), "linux", "runepanet")
-    inp = os.path.join(os.path.join(dir, "db_inp"), input + ".inp")
-    rpt = os.path.join(os.path.join(dir, "temp"), input + ".rpt")
-    opt = os.path.join(os.path.join(dir, "temp"), input + ".opt")
-    command = f"{exe} {inp} {rpt} {opt}"
 
     if platform.system() != "Windows":
         if not os.access(exe, os.X_OK):
@@ -334,8 +345,7 @@ def run_project_return_dict(name: str, readable_output: bool = False) -> dict[st
         lib_dir = os.path.dirname(exe)
         env["LD_LIBRARY_PATH"] = f"{lib_dir}:{env.get('LD_LIBRARY_PATH', '')}"
 
-    # 使用 subprocess 替代 os.system 以传递 env
-    process = subprocess.run(command, shell=True, env=env)
+    process = subprocess.run([exe, inp, rpt, opt], env=env)
     result = process.returncode
 
     if result != 0:
@@ -347,33 +357,36 @@ def run_project_return_dict(name: str, readable_output: bool = False) -> dict[st
         else:
             data["output"] = dump_output_binary(opt)
 
+    data["input_file"] = inp
+    data["report_file"] = rpt
+    data["output_file"] = opt
     data["report"] = dump_report(rpt)
 
+    # 返回内容后删除仿真临时文件，避免临时文件堆积。
+    _safe_remove(inp)
+    _safe_remove(rpt)
+    _safe_remove(opt)
+
     return data
 
 
 # original code
-def run_project(name: str, readable_output: bool = False) -> str:
+def run_project(name: str, readable_output: bool = True) -> str:
     if not project.have_project(name):
         raise Exception(f"Not found project [{name}]")
 
-    dir = os.path.abspath(os.getcwd())
+    cwd = os.path.abspath(os.getcwd())
 
-    db_inp = os.path.join(os.path.join(dir, "db_inp"), name + ".db.inp")
-    inp_out.dump_inp(name, db_inp, "2")
+    inp, rpt, opt = _make_isolated_run_paths(name, cwd)
+    inp_out.dump_inp(name, inp, "2")
 
-    input = name + ".db"
     if platform.system() == "Windows":
         exe = os.path.join(os.path.dirname(__file__), "windows", "runepanet.exe")
     else:
         exe = os.path.join(os.path.dirname(__file__), "linux", "runepanet")
-    inp = os.path.join(os.path.join(dir, "db_inp"), input + ".inp")
-    rpt = os.path.join(os.path.join(dir, "temp"), input + ".rpt")
-    opt = os.path.join(os.path.join(dir, "temp"), input + ".opt")
 
-    command = f"{exe} {inp} {rpt} {opt}"
     logging.info(f"Run simulation at {datetime.now()}")
-    logging.info(command)
+    logging.info("%s %s %s %s", exe, inp, rpt, opt)
 
     if platform.system() != "Windows":
         if not os.access(exe, os.X_OK):
@@ -388,7 +401,7 @@ def run_project(name: str, readable_output: bool = False) -> str:
         env["LD_LIBRARY_PATH"] = f"{lib_dir}:{env.get('LD_LIBRARY_PATH', '')}"
 
     # DingZQ, 2025-06-02, 使用subprocess替代os.system
-    process = subprocess.run(command, shell=True, env=env)
+    process = subprocess.run([exe, inp, rpt, opt], env=env)
     result = process.returncode
     # logging.info(f"Simulation result: {result}")
 
@@ -402,27 +415,35 @@ def run_project(name: str, readable_output: bool = False) -> str:
         logging.info("simulation successful")
 
         if readable_output:
-            data |= _dump_output(opt)
+            data["output"] = _dump_output(opt)
         else:
             data["output"] = dump_output_binary(opt)
 
+    data["input_file"] = inp
+    data["report_file"] = rpt
+    data["output_file"] = opt
     data["report"] = dump_report(rpt)
+
+    # 返回内容后删除仿真临时文件，避免临时文件堆积。
+    _safe_remove(inp)
+    _safe_remove(rpt)
+    _safe_remove(opt)
     # logging.info(f"Report: {data['report']}")
 
     return json.dumps(data)
 
 
-def run_inp(name: str) -> str:
-    dir = os.path.abspath(os.getcwd())
+def run_inp(name: str, readable_output: bool = True) -> str:
+    cwd = os.path.abspath(os.getcwd())
 
     if platform.system() == "Windows":
         exe = os.path.join(os.path.dirname(__file__), "windows", "runepanet.exe")
     else:
         exe = os.path.join(os.path.dirname(__file__), "linux", "runepanet")
-    inp = os.path.join(os.path.join(dir, "inp"), name + ".inp")
-    rpt = os.path.join(os.path.join(dir, "temp"), name + ".rpt")
-    opt = os.path.join(os.path.join(dir, "temp"), name + ".opt")
-    command = f"{exe} {inp} {rpt} {opt}"
+    source_inp = os.path.join(cwd, "inp", name + ".inp")
+    token = f"{os.getpid()}_{uuid.uuid4().hex}"
+    rpt = os.path.join(cwd, "temp", f"{name}.{token}.rpt")
+    opt = os.path.join(cwd, "temp", f"{name}.{token}.opt")
 
     if platform.system() != "Windows":
         if not os.access(exe, os.X_OK):
@@ -436,16 +457,26 @@ def run_inp(name: str) -> str:
         lib_dir = os.path.dirname(exe)
         env["LD_LIBRARY_PATH"] = f"{lib_dir}:{env.get('LD_LIBRARY_PATH', '')}"
 
-    process = subprocess.run(command, shell=True, env=env)
+    process = subprocess.run([exe, source_inp, rpt, opt], env=env)
     result = process.returncode
 
     if result != 0:
         data["simulation_result"] = "failed"
     else:
         data["simulation_result"] = "successful"
-        # data |= _dump_output(opt)
-        data["output"] = dump_output_binary(opt)
+        if readable_output:
+            data["output"] = _dump_output(opt)
+        else:
+            data["output"] = dump_output_binary(opt)
 
+    data["input_file"] = source_inp
+    data["report_file"] = rpt
+    data["output_file"] = opt
     data["report"] = dump_report(rpt)
 
+    # 返回内容后删除仿真临时文件，避免临时文件堆积。
+    _safe_remove(source_inp)
+    _safe_remove(rpt)
+    _safe_remove(opt)
+
     return json.dumps(data)

app/main.py

@@ -10,7 +10,7 @@ from app.api.v1.router import api_router
 from app.infra.db.timescaledb.database import db as tsdb
 from app.infra.db.postgresql.database import db as pgdb
 from app.infra.db.dynamic_manager import project_connection_manager
-from app.infra.db.metadata.database import close_metadata_engine
+from app.infra.db.metadb.database import close_metadata_engine
 from app.services.tjnetwork import open_project
 from app.core.config import settings
 

app/native/wndb/__init__.py

@@ -130,7 +130,14 @@ from .s4_tanks import get_tank_schema, add_tank, get_tank, set_tank, get_all_tan
 from .batch_api import delete_tank_cascade
 
 from .s5_pipes import PIPE_STATUS_OPEN, PIPE_STATUS_CLOSED, PIPE_STATUS_CV
-from .s5_pipes import get_pipe_schema, add_pipe, get_pipe, set_pipe, get_all_pipes
+from .s5_pipes import (
+    get_pipe_schema,
+    add_pipe,
+    get_pipe,
+    set_pipe,
+    get_all_pipes,
+    get_pipes_by_property,
+)
 from .batch_api import delete_pipe_cascade
 
 from .s6_pumps import get_pump_schema, add_pump, get_pump, set_pump, get_all_pumps

app/native/wndb/inp_in.py

@@ -161,7 +161,7 @@ def _get_file_offset(inp: str) -> tuple[dict[str, list[int]], bool]:
     current = ""
     demand_outside = False
 
-    with open(inp) as f:
+    with open(inp, encoding="utf-8") as f:
         while True:
             line = f.readline()
             if not line:
@@ -210,7 +210,7 @@ def parse_file(project: str, inp: str, version: str = "3") -> None:
 
     sql_batch = SQLBatch(project)
     _print_time("Second scan...")
-    with open(inp) as f:
+    with open(inp, encoding="utf-8") as f:
         for s in levels:
             if s not in offset:
                 continue
@@ -421,7 +421,7 @@ def convert_inp_v3_to_v2(inp: str) -> ChangeSet:
     if os.path.exists(filename):
         os.remove(filename)
 
-    with open(filename, "w") as f:
+    with open(filename, "w", encoding="utf-8") as f:
         f.write(inp)
 
     parse_file(project, filename, "3")
@@ -448,7 +448,7 @@ def import_inp(project: str, cs: ChangeSet, version: str = "3") -> bool:
         os.remove(filename)
 
     _print_time(f'Start writing temp file "{filename}"...')
-    with open(filename, "w", encoding="GBK") as f:
+    with open(filename, "w", encoding="utf-8") as f:
         f.write(str(cs.operations[0]["inp"]))
     _print_time(f'End writing temp file "{filename}"...')
 

app/native/wndb/s38_scada_info.py

@@ -2,12 +2,17 @@ from .database import *
 
 
 def get_scada_info_schema(name: str) -> dict[str, dict[str, Any]]:
-    return { 'id'                    : {'type': 'str'      , 'optional': False , 'readonly': True },
-             'type'                  : {'type': 'str'      , 'optional': False , 'readonly': True },
-             'x'                     : {'type': 'float'    , 'optional': False , 'readonly': False},
-             'y'                     : {'type': 'float'    , 'optional': False , 'readonly': False},
-             'query_api_id'          : {'type': 'str'      , 'optional': False , 'readonly': False},
-             'associated_element_id' : {'type': 'str'      , 'optional': False , 'readonly': True } }
+    return {
+        "id": {"type": "str", "optional": False, "readonly": True},
+        "type": {"type": "str", "optional": False, "readonly": True},
+        "x": {"type": "float", "optional": False, "readonly": False},
+        "y": {"type": "float", "optional": False, "readonly": False},
+        "query_api_id": {"type": "str", "optional": False, "readonly": False},
+        "transmission_mode": {"type": "str", "optional": True, "readonly": True},
+        "transmission_frequency": {"type": "float", "optional": True, "readonly": True},
+        "reliability": {"type": "float", "optional": True, "readonly": True},
+        "associated_element_id": {"type": "str", "optional": False, "readonly": True},
+    }
 
 
 def get_scada_info(name: str, id: str) -> dict[str, Any]:
@@ -16,15 +21,19 @@ def get_scada_info(name: str, id: str) -> dict[str, Any]:
         return {}
 
     d = {}
-    d['id'] = si['id']
-    d['type'] = si['type']
-    d['x'] = float(si['x_coor'])
-    d['y'] = float(si['y_coor'])
-    d['api_query_id'] = si['api_query_id']
-    d['associated_element_id'] = si['associated_element_id']
+    d["id"] = si["id"]
+    d["type"] = si["type"]
+    d["x"] = float(si["x_coor"])
+    d["y"] = float(si["y_coor"])
+    d["api_query_id"] = si["api_query_id"]
+    d["transmission_mode"] = si.get("transmission_mode")
+    d["transmission_frequency"] = si.get("transmission_frequency")
+    d["reliability"] = si.get("reliability")
+    d["associated_element_id"] = si["associated_element_id"]
 
     return d
 
+
 def get_all_scada_info(name: str) -> list[dict[str, Any]]:
     sis = read_all(name, f"select * from scada_info")
     if sis is None:
@@ -32,11 +41,18 @@ def get_all_scada_info(name: str) -> list[dict[str, Any]]:
 
     d = []
     for si in sis:
-        d.append({ 'id': si['id'], 
-                   'type': si['type'], 
-                   'x': float(si['x_coor']), 
-                   'y': float(si['y_coor']), 
-                   'api_query_id': si['api_query_id'], 
-                   'associated_element_id': si['associated_element_id'] })
-        
-    return d
+        d.append(
+            {
+                "id": si["id"],
+                "type": si["type"],
+                "x": float(si["x_coor"]),
+                "y": float(si["y_coor"]),
+                "api_query_id": si["api_query_id"],
+                "transmission_mode": si.get("transmission_mode"),
+                "transmission_frequency": si.get("transmission_frequency"),
+                "reliability": si.get("reliability"),
+                "associated_element_id": si["associated_element_id"],
+            }
+        )
+
+    return d

app/native/wndb/s5_pipes.py

@@ -54,6 +54,52 @@ def get_all_pipes(name: str) -> list[dict[str, Any]]:
 
     return result
 
+
+def get_pipes_by_property(
+    name: str,
+    fields: list[str] | None = None,
+    property_conditions: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    if not fields:
+        fields = [
+            'id',
+            'node1',
+            'node2',
+            'length',
+            'diameter',
+            'roughness',
+            'minor_loss',
+            'status',
+        ]
+
+    rows = read_all(name, "select * from pipes")
+    if rows == None:
+        return []
+
+    result = []
+    for row in rows:
+        if property_conditions:
+            matched = True
+            for key, value in property_conditions.items():
+                if row[key] != value:
+                    matched = False
+                    break
+            if not matched:
+                continue
+
+        d = {}
+        for field in fields:
+            value = row[field]
+            if field in ('length', 'diameter', 'roughness', 'minor_loss') and value is not None:
+                d[field] = float(value)
+            elif field in ('id', 'node1', 'node2', 'status') and value is not None:
+                d[field] = str(value)
+            else:
+                d[field] = value
+        result.append(d)
+
+    return result
+
 class Pipe(object):
     def __init__(self, input: dict[str, Any]) -> None:
         self.type = 'pipe'

app/services/simulation.py

@@ -27,15 +27,12 @@ import json
 import pytz
 import requests
 import time
-import shutil
-from app.infra.epanet.epanet import Output
 from typing import Optional, Tuple
 import app.infra.db.influxdb.api as influxdb_api
 import typing
 import psycopg
 import logging
 import app.services.globals as globals
-import uuid
 import app.services.project_info as project_info
 from app.core.config import get_pgconn_string
 from app.infra.db.timescaledb.internal_queries import (
@@ -1219,7 +1216,7 @@ def run_simulation(
                 cs.append(valve_status)
                 set_status(name_c, cs)
     # 运行并返回结果
-    run_project(name_c)
+    result_data = json.loads(run_project(name_c))
     time_cost_end = time.perf_counter()
     print(
         "{} -- Hydraulic simulation finished, cost time: {:.2f} s.".format(
@@ -1227,23 +1224,22 @@ def run_simulation(
             time_cost_end - time_cost_start,
         )
     )
-    # DingZQ 下面这几句一定要这样，不然读取不了
-    # time.sleep(5)  # wait 5 seconds
-
-    # TODO: 2025/03/24
-    # DingZQ 这个名字要用随机数来处理
-    tmp_file = f"./temp/simulation_{uuid.uuid4()}.result.out"
-    shutil.copy(f"./temp/{name_c}.db.opt", tmp_file)
-
-    output = Output(tmp_file)
-    node_result = output.node_results()
-    link_result = output.link_results()
-
+    output_data = result_data.get("output")
+    if not isinstance(output_data, dict):
+        raise RuntimeError("run_project did not return JSON output content")
+    node_result = output_data.get("node_results")
+    link_result = output_data.get("link_results")
+    if node_result is None or link_result is None:
+        raise RuntimeError("run_project output missing node_results or link_results")
+ 
     # link_flow = []
     # for link in link_result:
     #     link_flow.append(link['result'][-1]['flow'])
     # print(link_flow)
-    num_periods_result = output.times()["num_periods"]
+    times_info = output_data.get("times") or {}
+    num_periods_result = times_info.get("num_periods")
+    if num_periods_result is None:
+        raise RuntimeError("run_project output missing times.num_periods")
     print("simulation_type", simulation_type)
     print("before store result")
     # print(num_periods_result)
@@ -1274,27 +1270,8 @@ def run_simulation(
     # 暂不需要再次存储 SCADA 模拟信息
     # TimescaleInternalQueries.fill_scheme_simulation_result_to_SCADA(scheme_type=scheme_type, scheme_name=scheme_name)
 
-    # if simulation_type.upper() == "REALTIME":
-    #     influxdb_api.store_realtime_simulation_result_to_influxdb(
-    #         node_result, link_result, modify_pattern_start_time
-    #     )
-    # elif simulation_type.upper() == "EXTENDED":
-    #     influxdb_api.store_scheme_simulation_result_to_influxdb(
-    #         node_result,
-    #         link_result,
-    #         modify_pattern_start_time,
-    #         num_periods_result,
-    #         scheme_type,
-    #         scheme_name,
-    #     )
-    # 暂不需要再次存储 SCADA 模拟信息
-    # influxdb_api.fill_scheme_simulation_result_to_SCADA(scheme_type=scheme_type, scheme_name=scheme_name)
-
     print("after store result")
 
-    del output
-    os.remove(tmp_file)
-
 
 if __name__ == "__main__":
     # 计算前，获取scada_info中的信息，按照设定的方法修改pg数据库

app/services/simulation_ops.py

@@ -5,7 +5,6 @@ from math import pi
 import pytz
 
 from app.algorithms.simulation.runner import run_simulation_ex
-from app.infra.epanet.epanet import Output
 from app.services.tjnetwork import (
     close_project,
     copy_project,
@@ -110,10 +109,16 @@ def scheduling_simulation(
         + " -- Database Loading OK."
     )
 
-    run_simulation_ex(
-        new_name, "realtime", start_time, duration=0, pump_control=pump_control
+    simulation_result = json.loads(
+        run_simulation_ex(
+            new_name, "realtime", start_time, duration=0, pump_control=pump_control
+        )
     )
 
+    output_data = simulation_result.get("output")
+    if not isinstance(output_data, dict):
+        raise RuntimeError("run_simulation_ex did not return JSON output content")
+
     if not is_project_open(new_name):
         open_project(new_name)
 
@@ -131,18 +136,14 @@ def scheduling_simulation(
         else:
             tank_pipe_flow_direction[pipe_id] = -1
 
-    output = Output("./temp/{}.db.out".format(new_name))
-
-    node_results = (
-        output.node_results()
-    )  # [{'node': str, 'result': [{'pressure': float}]}]
+    node_results = output_data.get("node_results") or []  # [{'node': str, 'result': [{'pressure': float}]}]
     water_plant_output_pressure = 0
     for node_result in node_results:
         if node_result["node"] == water_plant_output_id:  # 水厂出水压力(m)
             water_plant_output_pressure = node_result["result"][-1]["pressure"]
     water_plant_output_pressure /= 100  # 预计水厂出水压力(Mpa)
 
-    pipe_results = output.link_results()  # [{'link': str, 'result': [{'flow': float}]}]
+    pipe_results = output_data.get("link_results") or []  # [{'link': str, 'result': [{'flow': float}]}]
     tank_inflow = 0
     for pipe_result in pipe_results:
         for pipe_id in tank_pipes_id:  # 遍历与水塔相连的管道
@@ -200,18 +201,24 @@ def daily_scheduling_simulation(
         + " -- Database Loading OK."
     )
 
-    run_simulation_ex(
-        new_name, "realtime", start_time, duration=86400, pump_control=pump_control
+    simulation_result = json.loads(
+        run_simulation_ex(
+            new_name,
+            "realtime",
+            start_time,
+            duration=86400,
+            pump_control=pump_control,
+        )
     )
 
+    output_data = simulation_result.get("output")
+    if not isinstance(output_data, dict):
+        raise RuntimeError("run_simulation_ex did not return JSON output content")
+
     if not is_project_open(new_name):
         open_project(new_name)
 
-    output = Output("./temp/{}.db.out".format(new_name))
-
-    node_results = (
-        output.node_results()
-    )  # [{'node': str, 'result': [{'pressure': float, 'head': float}]}]
+    node_results = output_data.get("node_results") or []  # [{'node': str, 'result': [{'pressure': float, 'head': float}]}]
     water_plant_output_pressure = []
     reservoir_level = []
     tank_level = []

infra/docker/docker-compose.yml

@@ -39,23 +39,6 @@ services:
     volumes:
       - ./redis/data:/data
 
-  # --- InfluxDB ---
-  influxdb:
-    image: influxdb:2.7
-    container_name: influxdb
-    restart: always
-    environment:
-      DOCKER_INFLUXDB_INIT_MODE: setup
-      DOCKER_INFLUXDB_INIT_USERNAME: ${INFLUXDB_USER}
-      DOCKER_INFLUXDB_INIT_PASSWORD: ${INFLUXDB_PASSWORD}
-      DOCKER_INFLUXDB_INIT_ORG: ${INFLUXDB_ORG}
-      DOCKER_INFLUXDB_INIT_BUCKET: ${INFLUXDB_BUCKET}
-      DOCKER_INFLUXDB_INIT_ADMIN_TOKEN: ${INFLUXDB_ADMIN_TOKEN}
-    ports:
-      - "${INFLUXDB_PORT}:8086"
-    volumes:
-      - ./influxdb/data:/var/lib/influxdb2
-
   # --- Keycloak ---
   keycloakDB:
     image: postgis/postgis:14-3.5

scripts/clean_pycache.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+import os
+import shutil
+import sys
+
+def clean_pycache(root_dir):
+    """
+    Recursively deletes all __pycache__ directories and .pyc files.
+    """
+    print(f"Cleaning __pycache__ in: {root_dir}")
+    for root, dirs, files in os.walk(root_dir):
+        # Delete __pycache__ directories
+        if "__pycache__" in dirs:
+            pycache_path = os.path.join(root, "__pycache__")
+            print(f"Removing directory: {pycache_path}")
+            shutil.rmtree(pycache_path)
+            dirs.remove("__pycache__")  # Don't visit the deleted directory
+
+        # Delete orphan .pyc files
+        for file in files:
+            if file.endswith(".pyc"):
+                pyc_path = os.path.join(root, file)
+                print(f"Removing file: {pyc_path}")
+                os.remove(pyc_path)
+
+def clean_extensions(root_dir):
+    """
+    Recursively deletes all compiled .so and .pyd files.
+    """
+    print(f"Cleaning compiled extensions in: {root_dir}")
+    for root, dirs, files in os.walk(root_dir):
+        for file in files:
+            if file.endswith(".so") or file.endswith(".pyd"):
+                ext_path = os.path.join(root, file)
+                print(f"Removing extension: {ext_path}")
+                os.remove(ext_path)
+
+if __name__ == "__main__":
+    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+    
+    # Clean pycache
+    clean_pycache(project_root)
+    
+    # Optionally clean extensions if requested via argument
+    if len(sys.argv) > 1 and sys.argv[1] == "--all":
+        clean_extensions(project_root)
+    
+    print("Cleanup complete.")

scripts/compile.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python
+import os
+import sys
+import shutil
+from setuptools import setup, Extension
+from Cython.Build import cythonize
+
+
+def delete_source_files(target_dirs):
+    """
+    Deletes the original .py files in the target directories after successful compilation.
+    Caution: This will remove your source code!
+    """
+    if isinstance(target_dirs, str):
+        target_dirs = [target_dirs]
+
+    project_root = os.getcwd()
+    print(f"Deleting source .py files in: {target_dirs}")
+
+    for target_dir in target_dirs:
+        if not os.path.exists(target_dir):
+            continue
+
+        abs_target_path = os.path.abspath(target_dir)
+
+        if os.path.isfile(abs_target_path):
+            if abs_target_path.endswith(".py") and os.path.abspath(
+                abs_target_path
+            ) != os.path.abspath(__file__):
+                print(f"Deleting source: {abs_target_path}")
+                os.remove(abs_target_path)
+            continue
+
+        # If it's a directory, walk through it
+        for root, dirs, files in os.walk(abs_target_path):
+            for file in files:
+                if file.endswith(".py"):
+                    file_path = os.path.join(root, file)
+                    # Skip this script itself
+                    if os.path.abspath(file_path) == os.path.abspath(__file__):
+                        continue
+                    # Skip __init__.py if you want to keep package structure,
+                    # but usually Cython can handle them too.
+                    print(f"Deleting source: {file_path}")
+                    os.remove(file_path)
+
+
+def clean_extensions(target_dirs):
+    """
+    Deletes all compiled .so/.pyd files in the target directories.
+    """
+    if isinstance(target_dirs, str):
+        target_dirs = [target_dirs]
+
+    project_root = os.getcwd()
+    print(f"Cleaning compiled files in: {target_dirs}")
+
+    for target_dir in target_dirs:
+        if not os.path.exists(target_dir):
+            continue
+
+        abs_target_path = os.path.abspath(target_dir)
+
+        if os.path.isfile(abs_target_path):
+            # If it's a .py file, look for its .so/.pyd counterpart
+            dir_name = os.path.dirname(abs_target_path)
+            base_name = os.path.splitext(os.path.basename(abs_target_path))[0]
+            for file in os.listdir(dir_name):
+                if file.startswith(base_name) and (
+                    file.endswith(".so") or file.endswith(".pyd")
+                ):
+                    file_path = os.path.join(dir_name, file)
+                    print(f"Removing: {file_path}")
+                    os.remove(file_path)
+            continue
+
+        # If it's a directory, walk through it
+        for root, dirs, files in os.walk(abs_target_path):
+            for file in files:
+                if file.endswith(".so") or file.endswith(".pyd"):
+                    file_path = os.path.join(root, file)
+                    print(f"Removing: {file_path}")
+                    os.remove(file_path)
+
+
+def build_extensions(target_dirs):
+    """
+    Compiles all .py files in the target directories (recursively) into .so/.pyd extensions.
+    Args:
+        target_dirs (list or str): List of directories or single directory path to scan.
+    """
+    # Ensure input is a list
+    if isinstance(target_dirs, str):
+        target_dirs = [target_dirs]
+
+    extensions = []
+    project_root = os.getcwd()
+
+    print(f"Scanning directories: {target_dirs}")
+
+    for target_dir in target_dirs:
+        # Ensure target directory exists
+        if not os.path.exists(target_dir):
+            print(f"Warning: Path '{target_dir}' not found. Skipping.")
+            continue
+
+        # Get the absolute path of the target
+        abs_target_path = os.path.abspath(target_dir)
+
+        # Check if the target is a file or directory
+        if os.path.isfile(abs_target_path):
+            if abs_target_path.endswith(".py"):
+                file_path = abs_target_path
+                rel_path = os.path.relpath(file_path, project_root)
+                module_name = os.path.splitext(rel_path)[0].replace(os.sep, ".")
+                print(f"Found file: {rel_path} -> {module_name}")
+                extensions.append(Extension(module_name, [file_path]))
+            continue
+
+        print(f"Scanning {abs_target_path} for Python files...")
+
+        # Walk through the directory
+        for root, dirs, files in os.walk(abs_target_path):
+            for file in files:
+                if file.endswith(".py"):
+                    file_path = os.path.join(root, file)
+
+                    # Skip this script if it happens to be in the target dir
+                    if os.path.abspath(file_path) == os.path.abspath(__file__):
+                        continue
+
+                    # Skip setup.py if it exists
+                    if file == "setup.py":
+                        continue
+
+                    # Determine the module name based on path relative to project root
+                    # This ensures imports like 'from app.services import ...' work
+                    try:
+                        rel_path = os.path.relpath(file_path, project_root)
+                    except ValueError:
+                        # If file is not under project root, we can't easily determine module name
+                        # relative to project root. Skip or warn.
+                        print(
+                            f"Skipping {file_path}: cannot determine relative path to {project_root}"
+                        )
+                        continue
+
+                    # Convert file path to module name (e.g. app/services/foo.py -> app.services.foo)
+                    module_name = os.path.splitext(rel_path)[0].replace(os.sep, ".")
+
+                    print(f"Found: {rel_path} -> {module_name}")
+
+                    extensions.append(Extension(module_name, [file_path]))
+
+    if not extensions:
+        print("No Python files found to compile.")
+        return
+
+    print(f"\nCompiling {len(extensions)} modules...")
+
+    # Build options
+    # compiler_directives: language_level=3 for Python 3
+    # force=True: force recompilation even if timestamps are up to date
+    try:
+        setup(
+            ext_modules=cythonize(
+                extensions,
+                compiler_directives={"language_level": "3"},
+                build_dir="build",  # Put intermediate files in build/ directory
+                force=True,
+            ),
+            script_args=["build_ext", "--inplace"],
+        )
+        print("\nCompilation successful!")
+    except Exception as e:
+        print(f"\nCompilation failed: {e}")
+        sys.exit(1)
+    finally:
+        # Cleanup build directory (intermediate C files)
+        if os.path.exists("build"):
+            print("Cleaning up build artifacts...")
+            try:
+                shutil.rmtree("build")
+            except OSError as e:
+                print(f"Warning: Failed to clean up build directory: {e}")
+
+
+if __name__ == "__main__":
+    # Default directories to compile if none provided
+    DEFAULT_TARGETS = [
+        "app/services",
+        "app/native/wndb",
+        "app/algorithms",
+        "app/infra/epanet/epanet.py",
+    ]
+
+    # Check for help flag
+    if len(sys.argv) > 1 and sys.argv[1] in ["--help", "-h"]:
+        print(
+            "Usage: python scripts/build_extensions.py [--clean|--delete-source] [directory1] [directory2] ..."
+        )
+        print(
+            "Compiles all Python files in the given directories into C extensions (.so/.pyd)."
+        )
+        print("Use --clean to remove existing compiled extensions.")
+        print("Use --delete-source to remove source .py files after compilation.")
+        print(f"Default directories if none provided: {DEFAULT_TARGETS}")
+        sys.exit(0)
+
+    clean_mode = False
+    delete_source_mode = False
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--clean":
+            clean_mode = True
+            target_directories = sys.argv[2:]
+        elif sys.argv[1] == "--delete-source":
+            delete_source_mode = True
+            target_directories = sys.argv[2:]
+        else:
+            target_directories = sys.argv[1:]
+    else:
+        print(f"No directories specified. Using defaults: {DEFAULT_TARGETS}")
+        target_directories = DEFAULT_TARGETS
+
+    if clean_mode:
+        clean_extensions(target_directories)
+    elif delete_source_mode:
+        delete_source_files(target_directories)
+    else:
+        build_extensions(target_directories)

scripts/encrypt_string.py

@@ -17,6 +17,7 @@ def main() -> int:
         plaintext = sys.argv[1]
     if plaintext is None:
         try:
+            # 示例 postgresql://user:password@host:port/dbname
             plaintext = input("请输入要加密的文本: ")
         except EOFError:
             plaintext = ""

scripts/run_server.py

@@ -16,6 +16,6 @@ if __name__ == "__main__":
         "app.main:app",
         host="0.0.0.0",
         port=8000,
-        # workers=4,  # 这里可以设置多进程
+        # workers=2,  # 这里可以设置多进程
         loop="asyncio",
     )

scripts/setup_security.sh

@@ -1,122 +0,0 @@
-#!/bin/bash
-
-# TJWater Server 安全功能快速设置脚本
-
-set -e
-
-echo "=================================="
-echo "TJWater Server 安全功能设置"
-echo "=================================="
-echo ""
-
-# 颜色定义
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# 步骤 1: 检查依赖
-echo "📦 步骤 1/5: 检查 Python 依赖..."
-if ! python -c "import cryptography, passlib, jose" 2>/dev/null; then
-    echo -e "${YELLOW}缺少依赖，正在安装...${NC}"
-    pip install cryptography passlib python-jose bcrypt
-else
-    echo -e "${GREEN}✓ 依赖已安装${NC}"
-fi
-echo ""
-
-# 步骤 2: 生成密钥
-echo "🔑 步骤 2/5: 生成安全密钥..."
-
-if [ ! -f .env ]; then
-    echo "正在创建 .env 文件..."
-    cp .env.example .env
-    
-    # 生成 JWT 密钥
-    JWT_KEY=$(openssl rand -hex 32)
-    sed -i "s/SECRET_KEY=.*/SECRET_KEY=$JWT_KEY/" .env
-    echo -e "${GREEN}✓ JWT 密钥已生成${NC}"
-    
-    # 生成加密密钥
-    ENC_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
-    sed -i "s/ENCRYPTION_KEY=.*/ENCRYPTION_KEY=$ENC_KEY/" .env
-    echo -e "${GREEN}✓ 加密密钥已生成${NC}"
-else
-    echo -e "${YELLOW}⚠ .env 文件已存在，跳过生成${NC}"
-fi
-echo ""
-
-# 步骤 3: 数据库配置
-echo "💾 步骤 3/5: 数据库配置..."
-read -p "请输入数据库名称 [默认: tjwater]: " DB_NAME
-DB_NAME=${DB_NAME:-tjwater}
-
-read -p "请输入数据库用户 [默认: postgres]: " DB_USER
-DB_USER=${DB_USER:-postgres}
-
-read -sp "请输入数据库密码: " DB_PASS
-echo ""
-
-# 更新 .env
-sed -i "s/DB_NAME=.*/DB_NAME=$DB_NAME/" .env
-sed -i "s/DB_USER=.*/DB_USER=$DB_USER/" .env
-sed -i "s/DB_PASSWORD=.*/DB_PASSWORD=$DB_PASS/" .env
-
-echo -e "${GREEN}✓ 数据库配置已更新${NC}"
-echo ""
-
-# 步骤 4: 执行数据库迁移
-echo "🗄️  步骤 4/5: 执行数据库迁移..."
-read -p "是否立即执行数据库迁移？(y/n) [y]: " DO_MIGRATION
-DO_MIGRATION=${DO_MIGRATION:-y}
-
-if [ "$DO_MIGRATION" = "y" ]; then
-    echo "正在执行迁移脚本..."
-    
-    PGPASSWORD=$DB_PASS psql -U $DB_USER -d $DB_NAME -f resources/sql/001_create_users_table.sql 2>&1 | grep -v "NOTICE"
-    if [ $? -eq 0 ]; then
-        echo -e "${GREEN}✓ 用户表创建成功${NC}"
-    else
-        echo -e "${RED}✗ 用户表创建失败${NC}"
-    fi
-    
-    PGPASSWORD=$DB_PASS psql -U $DB_USER -d $DB_NAME -f resources/sql/002_create_audit_logs_table.sql 2>&1 | grep -v "NOTICE"
-    if [ $? -eq 0 ]; then
-        echo -e "${GREEN}✓ 审计日志表创建成功${NC}"
-    else
-        echo -e "${RED}✗ 审计日志表创建失败${NC}"
-    fi
-else
-    echo -e "${YELLOW}⚠ 跳过数据库迁移，请稍后手动执行：${NC}"
-    echo "  psql -U $DB_USER -d $DB_NAME -f resources/sql/001_create_users_table.sql"
-    echo "  psql -U $DB_USER -d $DB_NAME -f resources/sql/002_create_audit_logs_table.sql"
-fi
-echo ""
-
-# 步骤 5: 测试
-echo "🧪 步骤 5/5: 运行测试..."
-if python tests/test_encryption.py 2>&1; then
-    echo -e "${GREEN}✓ 加密功能测试通过${NC}"
-else
-    echo -e "${RED}✗ 加密功能测试失败${NC}"
-fi
-echo ""
-
-# 完成
-echo "=================================="
-echo -e "${GREEN}✅ 设置完成！${NC}"
-echo "=================================="
-echo ""
-echo "默认管理员账号："
-echo "  用户名: admin"
-echo "  密码: admin123"
-echo ""
-echo "  用户名: tjwater"
-echo "  密码: tjwater@123"
-echo ""
-echo "下一步："
-echo "  1. 查看文档: cat SECURITY_README.md"
-echo "  2. 查看部署指南: cat DEPLOYMENT.md"
-echo "  3. 启动服务器: uvicorn app.main:app --reload"
-echo "  4. 访问文档: http://localhost:8000/docs"
-echo ""

tests/api/test_api_integration.py

@@ -26,8 +26,8 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../.
         ("app.api.v1.endpoints.auth", "认证接口"),
         ("app.api.v1.endpoints.user_management", "用户管理接口"),
         ("app.api.v1.endpoints.audit", "审计日志接口"),
-        ("app.infra.repositories.user_repository", "用户仓储"),
-        ("app.infra.repositories.audit_repository", "审计仓储"),
+        ("app.infra.db.metadb.repositories.user_repository", "用户仓储"),
+        ("app.infra.db.metadb.repositories.audit_repository", "审计仓储"),
         ("app.infra.audit.middleware", "审计中间件"),
     ],
 )

tests/unit/test_metadata_repository_dsn_decrypt.py

@@ -6,7 +6,7 @@ from uuid import uuid4
 import pytest
 from cryptography.fernet import InvalidToken
 
-from app.infra.repositories.metadata_repository import MetadataRepository
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
 
 
 class _DummyResult:
@@ -51,11 +51,11 @@ def test_invalid_token_with_plaintext_dsn_value_raises_clear_error(monkeypatch):
     repo = MetadataRepository(session)
 
     monkeypatch.setattr(
-        "app.infra.repositories.metadata_repository.is_database_encryption_configured",
+        "app.infra.db.metadb.repositories.metadata_repository.is_database_encryption_configured",
         lambda: True,
     )
     monkeypatch.setattr(
-        "app.infra.repositories.metadata_repository.get_database_encryptor",
+        "app.infra.db.metadb.repositories.metadata_repository.get_database_encryptor",
         lambda: encryptor,
     )
 
@@ -78,11 +78,11 @@ def test_invalid_token_with_non_dsn_value_raises_clear_error(monkeypatch):
     repo = MetadataRepository(session)
 
     monkeypatch.setattr(
-        "app.infra.repositories.metadata_repository.is_database_encryption_configured",
+        "app.infra.db.metadb.repositories.metadata_repository.is_database_encryption_configured",
         lambda: True,
     )
     monkeypatch.setattr(
-        "app.infra.repositories.metadata_repository.get_database_encryptor",
+        "app.infra.db.metadb.repositories.metadata_repository.get_database_encryptor",
         lambda: _DummyEncryptor(raise_invalid_token=True),
     )
 
@@ -105,11 +105,11 @@ def test_encrypted_dsn_decrypts_without_migration(monkeypatch):
     repo = MetadataRepository(session)
 
     monkeypatch.setattr(
-        "app.infra.repositories.metadata_repository.is_database_encryption_configured",
+        "app.infra.db.metadb.repositories.metadata_repository.is_database_encryption_configured",
         lambda: True,
     )
     monkeypatch.setattr(
-        "app.infra.repositories.metadata_repository.get_database_encryptor",
+        "app.infra.db.metadb.repositories.metadata_repository.get_database_encryptor",
         lambda: _DummyEncryptor(decrypted="postgresql://u:p@ss@host/db"),
     )