docs: 编写客户版交付文档

Simulation mode reads scheme data for both burst and normal observations. Monitoring mode reuses the burst window when no normal window is provided.

.dockerignore

@@ -0,0 +1,19 @@
+.git
+.github
+.gitea
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.venv/
+venv/
+build/
+dist/
+package/
+temp/
+data/
+# db_inp/
+inp/
+.env
+*.pyc
+*.dump
+app/algorithms/health/model/my_survival_forest_model_quxi.joblib

.env.example

@@ -1,18 +1,16 @@
 # TJWater Server 环境变量配置模板
 # 复制此文件为 .env 并填写实际值
-NETWORK_NAME="szh"
+# CI/CD: 将生产 .env 的完整内容保存为 Gitea 仓库密钥 TJWATER_SERVER_ENV。
+ENVIRONMENT="production"
+NETWORK_NAME="tjwater"
 # ============================================
-# 安全配置 (必填)
+# 敏感配置加密 (必填)
 # ============================================
 
-# JWT 密钥 - 用于生成和验证 Token
-# 生成方式: openssl rand -hex 32
-SECRET_KEY=your-secret-key-here-change-in-production-use-openssl-rand-hex-32
-
-# 数据加密密钥 - 用于敏感数据加密
+# Fernet 格式，生产环境必须替换为独立密钥
 # 生成方式: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-ENCRYPTION_KEY=
-DATABASE_ENCRYPTION_KEY="rJC2VqLg4KrlSq+DGJcYm869q4v5KB2dFAeuQTe0I50="
+# 用于项目数据库 DSN、GeoServer 管理密码等敏感配置
+DATABASE_ENCRYPTION_KEY="replace-with-generated-fernet-key"
 
 # ============================================
 # 数据库配置 (PostgreSQL)
@@ -20,17 +18,17 @@ DATABASE_ENCRYPTION_KEY="rJC2VqLg4KrlSq+DGJcYm869q4v5KB2dFAeuQTe0I50="
 DB_NAME="tjwater"
 DB_HOST="localhost"
 DB_PORT="5432"
-DB_USER="postgres"
+DB_USER="tjwater"
 DB_PASSWORD="password"
 
 # ============================================
 # 数据库配置 (TimescaleDB)
 # ============================================
-TIMESCALEDB_DB_NAME="szh"
+TIMESCALEDB_DB_NAME="tjwater"
 TIMESCALEDB_DB_HOST="localhost"
 TIMESCALEDB_DB_PORT="5433"
 TIMESCALEDB_DB_USER="tjwater"
-TIMESCALEDB_DB_PASSWORD="Tjwater@123456"
+TIMESCALEDB_DB_PASSWORD="password"
 
 # ============================================
 # 元数据数据库配置 (Metadata DB)
@@ -41,39 +39,24 @@ METADATA_DB_PORT="5432"
 METADATA_DB_USER="tjwater"
 METADATA_DB_PASSWORD="password"
 
-# ============================================
-# 项目连接缓存与连接池配置
-# ============================================
-PROJECT_PG_CACHE_SIZE=50
-PROJECT_TS_CACHE_SIZE=50
-PROJECT_PG_POOL_SIZE=5
-PROJECT_PG_MAX_OVERFLOW=10
-PROJECT_TS_POOL_MIN_SIZE=1
-PROJECT_TS_POOL_MAX_SIZE=10
-
-# ============================================
-# InfluxDB 配置 (时序数据)
-# ============================================
-# INFLUXDB_URL=http://localhost:8086
-# INFLUXDB_TOKEN=your-influxdb-token
-# INFLUXDB_ORG=your-org
-# INFLUXDB_BUCKET=tjwater
-
-# ============================================
-# JWT 配置 (可选)
-# ============================================
-# ACCESS_TOKEN_EXPIRE_MINUTES=30
-# REFRESH_TOKEN_EXPIRE_DAYS=7
-# ALGORITHM=HS256
-
 # ============================================
 # Keycloak JWT (可选)
 # ============================================
-# KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
-# KEYCLOAK_ALGORITHM=RS256
+KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+KEYCLOAK_ALGORITHM=RS256
+KEYCLOAK_AUDIENCE="account"
+
 
 # ============================================
-# 其他配置
+# Bocha Web Search API
 # ============================================
-# PROJECT_NAME=TJWater Server
-# API_V1_STR=/api/v1
+BOCHA_API_KEY="sk-your-bocha-api-key"
+BOCHA_WEB_SEARCH_URL="https://api.bochaai.com/v1/web-search"
+BOCHA_WEB_SEARCH_TIMEOUT_SECONDS=30
+
+# ============================================
+# Tianditu Geocoding API
+# ============================================
+TIANDITU_GEOCODER_TOKEN="your-tianditu-geocoder-token"
+TIANDITU_GEOCODER_URL="https://api.tianditu.gov.cn/geocoder"
+TIANDITU_GEOCODER_TIMEOUT_SECONDS=30

.env.local

@@ -1,23 +0,0 @@
-NETWORK_NAME="tjwater"
-KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApBjdgjImuFfKsZ+FWFlsZSG0Kftduc2o0qA/warFezaYmi8+7fiuuhLErLUbjGPSEU3WpsVxPe5PIs+AJJn/z9uBXXXo/pYggHvp48hlwr6MIYX5xtby7MLM/bHL2ACN4m7FNs/Gilkkbt4515sMFUiwJzd6Wj6FvQdGDDGx/7bVGgiVQRJvrrMZN5zD4i8cFiTQIcGKbURJjre/zWWiA+7gEwArp9ujjBuaINooiQLQM39C9Z5QJcp5nhaztOBiJJgiJOHi5MLpIhI1p1ViVBXKXRMuPhtTXLAz+r/sC44XZS/6V8uUPuLNin9o0jHk/CqJ3GkK3xJBQoWgplkwuQIDAQAB\n-----END PUBLIC KEY-----"
-KEYCLOAK_ALGORITHM="RS256"
-KEYCLOAK_AUDIENCE="account"
-
-DB_NAME="tjwater"
-DB_HOST="192.168.1.114"
-DB_PORT="5432"
-DB_USER="tjwater"
-DB_PASSWORD="Tjwater@123456"
-
-TIMESCALEDB_DB_NAME="tjwater"
-TIMESCALEDB_DB_HOST="192.168.1.114"
-TIMESCALEDB_DB_PORT="5433"
-TIMESCALEDB_DB_USER="tjwater"
-TIMESCALEDB_DB_PASSWORD="Tjwater@123456"
-
-METADATA_DB_NAME="system_hub"
-METADATA_DB_HOST="192.168.1.114"
-METADATA_DB_PORT="5432"
-METADATA_DB_USER="tjwater"
-METADATA_DB_PASSWORD="Tjwater@123456"
-DATABASE_ENCRYPTION_KEY="rJC2VqLg4KrlSq+DGJcYm869q4v5KB2dFAeuQTe0I50="

.github/copilot-instructions.md

@@ -1,198 +0,0 @@
-# TJWater Server - Copilot Instructions
-
-This is a FastAPI-based water network management system (供水管网智能管理系统) that provides hydraulic simulation, SCADA data integration, network element management, and risk analysis capabilities.
-
-## Running the Server
-
-```bash
-# Install dependencies
-pip install -r requirements.txt
-
-# Start the server (default: http://0.0.0.0:8000 with 2 workers)
-python scripts/run_server.py
-
-# Note: On Windows, the script automatically sets WindowsSelectorEventLoopPolicy
-```
-
-## Running Tests
-
-```bash
-# Run all tests
-pytest
-
-# Run a specific test file with verbose output
-pytest tests/unit/test_pipeline_health_analyzer.py -v
-
-# Run from conftest helper
-python tests/conftest.py
-```
-
-## Architecture Overview
-
-### Core Components
-
-1. **Native Modules** (`app/native/`): Platform-specific compiled extensions (`.so` for Linux, `.pyd` for Windows) providing performance-critical functionality including:
-   - SCADA device integration
-   - Water distribution analysis (WDA)
-   - Pipe risk probability calculations
-   - Wrapped through `app.services.tjnetwork` interface
-
-2. **Services Layer** (`app/services/`):
-   - `tjnetwork.py`: Main network API wrapper around native modules
-   - `simulation.py`: Hydraulic simulation orchestration (EPANET integration)
-   - `project_info.py`: Project configuration management
-   - `epanet/`: EPANET hydraulic engine integration
-
-3. **API Layer** (`app/api/v1/`):
-   - **Network Elements**: Separate endpoint modules for junctions, reservoirs, tanks, pipes, pumps, valves
-   - **Components**: Curves, patterns, controls, options, quality, visuals
-   - **Network Features**: Tags, demands, geometry, regions/DMAs
-   - **Core Services**: Auth, project, simulation, SCADA, data query, snapshots
-
-4. **Database Infrastructure** (`app/infra/db/`):
-   - **PostgreSQL**: Primary relational database (users, audit logs, project metadata)
-   - **TimescaleDB**: Time-series extension for historical data
-   - **InfluxDB**: Optional time-series database for high-frequency SCADA data
-   - Connection pools initialized in `main.py` lifespan context
-   - Database instance stored in `app.state.db` for dependency injection
-
-5. **Domain Layer** (`app/domain/`):
-   - `models/`: Enums and domain objects (e.g., `UserRole`)
-   - `schemas/`: Pydantic models for request/response validation
-
-6. **Algorithms** (`app/algorithms/`):
-   - `api_ex/`: Analysis algorithms (k-means sensor placement, sensitivity analysis, pipeline health)
-   - `data_cleaning.py`: Data preprocessing utilities
-   - `simulations.py`: Simulation helpers
-
-### Security & Authentication
-
-- **Authentication**: JWT-based with access tokens (30 min) and refresh tokens (7 days)
-- **Authorization**: Role-based access control (RBAC) with 4 roles:
-  - `VIEWER`: Read-only access
-  - `USER`: Read-write access
-  - `OPERATOR`: Modify data
-  - `ADMIN`: Full permissions
-- **Audit Logging**: `AuditMiddleware` automatically logs POST/PUT/DELETE requests
-- **Encryption**: Fernet symmetric encryption for sensitive data (`app.core.encryption`)
-
-Default admin accounts:
-- `admin` / `admin123`
-- `tjwater` / `tjwater@123`
-
-### Key Files
-
-- `app/main.py`: FastAPI app initialization, lifespan (DB pools), CORS, middleware, router mounting
-- `app/api/v1/router.py`: Central router aggregating all endpoint modules
-- `app/core/config.py`: Settings management using `pydantic-settings`
-- `app/auth/dependencies.py`: Auth dependencies (`get_current_active_user`, `get_db`)
-- `app/auth/permissions.py`: Permission decorators (`require_role`, `get_current_admin`)
-- `.env`: Environment configuration (database credentials, JWT secret, encryption key)
-
-## Important Conventions
-
-### Database Connections
-
-- Database instances are initialized in `main.py` lifespan and stored in `app.state.db`
-- Access via dependency injection:
-  ```python
-  from app.auth.dependencies import get_db
-  
-  async def endpoint(db = Depends(get_db)):
-      # Use db connection
-  ```
-
-### Authentication in Endpoints
-
-Use dependency injection for auth requirements:
-
-```python
-from app.auth.dependencies import get_current_active_user
-from app.auth.permissions import require_role, get_current_admin
-from app.domain.models.role import UserRole
-
-# Require any authenticated user
-@router.get("/data")
-async def get_data(current_user = Depends(get_current_active_user)):
-    return data
-
-# Require specific role (USER or higher)
-@router.post("/data")
-async def create_data(current_user = Depends(require_role(UserRole.USER))):
-    return result
-
-# Admin-only access
-@router.delete("/data/{id}")
-async def delete_data(id: int, current_user = Depends(get_current_admin)):
-    return result
-```
-
-### API Routing Structure
-
-- All v1 APIs are mounted under `/api/v1` prefix via `api_router`
-- Legacy routes without version prefix are also mounted for backward compatibility
-- Group related endpoints in separate router modules under `app/api/v1/endpoints/`
-- Use descriptive tags in `router.py` for OpenAPI documentation grouping
-
-### Native Module Integration
-
-- Native modules are pre-compiled for specific platforms
-- Always import through `app.native.api` or `app.services.tjnetwork`
-- The `tjnetwork` service wraps native APIs with constants like:
-  - Element types: `JUNCTION`, `RESERVOIR`, `TANK`, `PIPE`, `PUMP`, `VALVE`
-  - Operations: `API_ADD`, `API_UPDATE`, `API_DELETE`
-  - `ChangeSet` for batch operations
-
-### Project Initialization
-
-- On startup, `main.py` automatically loads project from `project_info.name` if set
-- Projects are opened via `open_project(name)` from `tjnetwork` service
-
-### Audit Logging
-
-Manual audit logging for critical operations:
-
-```python
-from app.core.audit import log_audit_event, AuditAction
-
-await log_audit_event(
-    action=AuditAction.UPDATE,
-    user_id=current_user.id,
-    username=current_user.username,
-    resource_type="resource_name",
-    resource_id=str(resource_id),
-    ip_address=request.client.host,
-    request_data=data
-)
-```
-
-### Environment Configuration
-
-- Copy `.env.example` to `.env` before first run
-- Required environment variables:
-  - `SECRET_KEY`: JWT signing (generate with `openssl rand -hex 32`)
-  - `ENCRYPTION_KEY`: Data encryption (generate with Fernet)
-  - Database credentials for PostgreSQL, TimescaleDB, and optionally InfluxDB
-
-### Database Migrations
-
-SQL migration scripts are in `migrations/`:
-- `001_create_users_table.sql`: User authentication tables
-- `002_create_audit_logs_table.sql`: Audit logging tables
-
-Apply with:
-```bash
-psql -U postgres -d tjwater -f migrations/001_create_users_table.sql
-```
-
-## API Documentation
-
-- Swagger UI: http://localhost:8000/docs
-- ReDoc: http://localhost:8000/redoc
-- OpenAPI schema: http://localhost:8000/openapi.json
-
-## Additional Resources
-
-- `SECURITY_README.md`: Comprehensive security feature documentation
-- `DEPLOYMENT.md`: Integration guide for security features
-- `readme.md`: Project overview and directory structure (in Chinese)

.gitignore

@@ -5,5 +5,5 @@ build/
 *.pyc
 .env
 *.dump
-app/algorithms/api_ex/model/my_survival_forest_model_quxi.joblib
 .vscode/
+app/algorithms/health/model/my_survival_forest_model_quxi.joblib

AGENTS.md

@@ -0,0 +1,73 @@
+# Repository Guidelines
+
+## Project Purpose
+
+This repository is the customer-delivery edition of the TJWater backend. Treat it as a deployable delivery package, not as the primary internal development repository. Changes should be limited to customer-facing fixes, deployment compatibility, configuration templates, packaging, and delivery documentation.
+
+Do not introduce internal-only experiments, debug utilities, local data, or source material that is not required for customer operation.
+
+## Source Encapsulation Requirement
+
+Core backend source code must be encapsulated before delivery. The sensitive implementation areas include business services, native integrations, hydraulic/network algorithms, and EPANET-related logic, especially:
+
+- `app/services`
+- `app/native`
+- `app/algorithms`
+- `app/infra/epanet`
+
+Use the existing Cython packaging flow in `scripts/compile.py` for these areas. Do not ship uncompiled core `.py` files in the final customer package when compiled extension modules are expected. Keep public entry points, configuration loading, route wiring, and minimal package files readable only where required for runtime and operations.
+
+Before removing source files with `--delete-source`, verify the build from a clean working tree or disposable copy. The delete mode is destructive by design.
+
+## Workspace Structure
+
+- `app/main.py` is the FastAPI entry point.
+- `app/api` contains HTTP route handlers.
+- `app/services` contains core business orchestration and must be protected in delivery builds.
+- `app/native`, `app/algorithms`, and `app/infra/epanet` contain specialized computation and integration code that must be protected in delivery builds.
+- `infra/` and `Dockerfile` contain deployment assets.
+- `scripts/` contains operational and packaging helpers.
+- `tests/` contains backend tests.
+
+## Common Commands
+
+Run commands from this repository root:
+
+```bash
+conda run -n server python -m pytest tests -q
+conda run -n server python scripts/run_server.py
+conda run -n server python scripts/compile.py
+```
+
+Clean compiled extensions when needed:
+
+```bash
+conda run -n server python scripts/compile.py --clean
+```
+
+Only use source deletion in a prepared delivery copy:
+
+```bash
+conda run -n server python scripts/compile.py --delete-source
+```
+
+## Change Policy
+
+Keep changes scoped and conservative. Prefer compatibility patches, configuration adjustments, packaging fixes, and customer deployment hardening. If a change requires substantial business logic updates, make it first in the internal backend repository and then port the reviewed result here.
+
+Do not weaken the encapsulation process to make debugging easier. If debugging requires readable source, do it in the internal repository or a non-delivery branch/copy.
+
+## Testing Guidelines
+
+Run the narrowest useful test command for the affected area. For delivery packaging changes, verify both:
+
+- tests still pass before packaging;
+- the packaged/compiled runtime can import and start the FastAPI app.
+
+Do not add tests that depend on untracked customer data, local database dumps, or machine-specific files.
+
+## Security & Delivery Rules
+
+Never commit `.env`, production credentials, customer data, logs, generated caches, `node_modules/`, database dumps, or temporary delivery archives. Use `.env.example` or deployment documentation for required configuration.
+
+Review Docker and deployment files carefully before delivery. Customer packages should contain only the files needed to run, operate, and diagnose the deployed service.

AUTHENTICATION_AND_USER_MANAGEMENT.md

@@ -0,0 +1,90 @@
+# TJWater Authentication and Metadata Management
+
+## Ownership
+
+Keycloak owns login identity, credentials, token issuance, and token expiry.
+TJWater metadata stores only business snapshots and authorization data:
+
+- `users.keycloak_id` is the stable identity binding.
+- `users.username`, `users.email`, and `users.last_login_at` are Keycloak claim caches.
+- `users.role`, `users.is_active`, and `users.is_superuser` control TJWater system access.
+- `user_project_membership.project_role` controls project access.
+
+The backend does not accept passwords, does not issue local JWTs, and does not
+trust frontend-supplied user IDs.
+
+## Login Snapshot Refresh
+
+Every authenticated metadata-user resolution validates the Keycloak access token
+and reads `sub`, `preferred_username` or `username`, and `email` claims. The
+backend finds `users` by `keycloak_id = sub`, rejects inactive or missing users,
+then refreshes `username`, `email`, and `last_login_at`.
+
+This keeps local display data current without changing the identity binding.
+There is no Keycloak webhook requirement; second-level user or permission sync is
+out of scope unless explicitly requested later.
+
+## Admin APIs
+
+All admin APIs require metadata admin access: `users.is_superuser = true` or
+`users.role = 'admin'`.
+
+User and membership management:
+
+- `GET /api/v1/admin/me`
+- `POST /api/v1/admin/users/sync`
+- `POST /api/v1/admin/users/sync/batch`
+- `GET /api/v1/admin/users`
+- `GET /api/v1/admin/users/{user_id}`
+- `PATCH /api/v1/admin/users/{user_id}`
+- `GET /api/v1/admin/projects/{project_id}/members`
+- `POST /api/v1/admin/projects/{project_id}/members`
+- `PATCH /api/v1/admin/projects/{project_id}/members/{user_id}`
+- `DELETE /api/v1/admin/projects/{project_id}/members/{user_id}`
+
+Project configuration:
+
+- `GET /api/v1/admin/projects`
+- `POST /api/v1/admin/projects`
+- `PATCH /api/v1/admin/projects/{project_id}`
+- `GET /api/v1/admin/projects/{project_id}/databases`
+- `PUT /api/v1/admin/projects/{project_id}/databases`
+- `DELETE /api/v1/admin/projects/{project_id}/databases/{db_role}`
+- `POST /api/v1/admin/projects/{project_id}/databases/{db_role}/health`
+
+## Secret Handling
+
+Admins submit plaintext DSNs only through HTTPS admin APIs. Operators should not
+write encrypted columns manually.
+
+- `project_databases.dsn_encrypted` is encrypted with `DATABASE_ENCRYPTION_KEY`.
+- Admin responses return only `has_dsn`.
+- Audit logs record whether a secret was updated, but never store plaintext DSNs
+  or other secrets.
+
+Generate the database encryption key with:
+
+```bash
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+Keep keys stable for the lifetime of encrypted metadata. Rotating a key requires
+decrypting with the old key and re-encrypting with the new key.
+
+## Metadata Schema Patches
+
+Apply metadata patches in order:
+
+1. `resources/sql/004_metadata_auth_management.sql`
+2. `resources/sql/005_metadata_project_configuration.sql`
+
+`004` creates Keycloak-backed metadata users and project memberships. `005`
+creates project and project database routing tables with uniqueness, role/type,
+and pool-size constraints.
+
+## Frontend System Management
+
+`/system-admin` is shown only after `GET /api/v1/admin/me` confirms metadata
+admin access. The page lets admins maintain metadata users, project members,
+projects, project database routing for `biz_data` and `iot_data`, connection
+health checks. This replaces direct SQL editing for normal project onboarding.

BACKEND_NAMING_AUDIT.md

@@ -0,0 +1,80 @@
+# Backend Naming Audit
+
+DOC-003 audit for the customer-delivery `TJWaterServerCustomer` backend.
+
+## Scope
+
+Reviewed FastAPI route decorators under `app/api/v1/endpoints`, router prefixes in `app/api/v1/router.py`, and public request/response schema fields in `app/api` and `app/domain`.
+
+The backend is mounted only under `/api/v1` from `app/main.py`; the old no-prefix router include remains commented out.
+
+## Current Good Surface
+
+These newer routes already follow the naming rule for public HTTP paths:
+
+- Audit: `/api/v1/audit/logs`, `/api/v1/audit/logs/count`
+- Metadata: `/api/v1/meta/project`, `/api/v1/meta/projects`, `/api/v1/meta/db/health`
+- Business APIs: `/api/v1/burst-detection/detect`, `/api/v1/burst-location/locate`, `/api/v1/leakage/identify`
+- Time-series APIs: `/api/v1/scada/by-ids-time-range`, `/api/v1/scada/by-ids-field-time-range`, `/api/v1/composite/clean-scada`
+- Project data APIs: `/api/v1/scada-info`, `/api/v1/scheme-list`, `/api/v1/burst-locate-result`
+- Web integrations: `/api/v1/web-search`, `/api/v1/geocode`
+
+Path template parameters such as `{user_id}`, `{device_id}`, `{scheme_name}`, and `{link_id}` intentionally remain `snake_case`.
+
+## Legacy URL Categories
+
+### Keep With Compatibility
+
+These now have `kebab-case` aliases. The frontend has been migrated to the replacement paths; keep the old paths as deprecated compatibility aliases for Agent planning, tests, customer scripts, or external callers:
+
+| Current URL | Suggested replacement |
+| --- | --- |
+| `/api/v1/openproject/` | `/api/v1/projects/open` |
+| `/api/v1/project_info/` | `/api/v1/project-info` |
+| `/api/v1/getallschemes/` | `/api/v1/schemes` |
+| `/api/v1/getallsensorplacements/` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/sensorplacementscheme/create` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/burst_analysis/` | `/api/v1/burst-analysis` |
+| `/api/v1/valve_isolation_analysis/` | `/api/v1/valve-isolation-analysis` |
+| `/api/v1/flushing_analysis/` | `/api/v1/flushing-analysis` |
+| `/api/v1/contaminant_simulation/` | `/api/v1/contaminant-simulation` |
+| `/api/v1/runsimulationmanuallybydate/` | `/api/v1/simulations/run-by-date` |
+
+### Broad Legacy Surface
+
+These route groups expose many command-style concatenated paths. They should not be copied into new work; replace only when a caller migration is planned:
+
+- Project lifecycle: `listprojects`, `createproject`, `deleteproject`, `isprojectopen`, `closeproject`, `copyproject`, `importinp`, `exportinp`, `readinp`, `dumpinp`, `lockproject`, `unlockproject`
+- Network object CRUD: `addjunction`, `getjunctionelevation`, `setpipediameter`, `getvalvesetting`, and similar junction/pipe/pump/tank/reservoir/valve routes
+- Region/DMA/VD commands: `calculatedistrictmeteringareaforregion`, `getdistrictmeteringarea`, `generatevirtualdistrict`, and related routes
+- SCADA native CRUD: `getscadadevice`, `setscadadevicedata`, `cleanscadaelement`, and related routes
+- Snapshot/cache utilities: `takesnapshotforoperation`, `syncwithserver`, `clearrediskey`, `queryredis`
+- Advanced simulation endpoints with underscore paths: `pressure_regulation`, `daily_scheduling_analysis`, `network_update`, `pressure_sensor_placement_kmeans`
+
+### Direct Cleanup Candidates
+
+These are likely safe only after confirming no caller uses them:
+
+- `/api/v1/test_dict/`: development/test utility in `misc.py`.
+- `/api/v1/takenapshotforcurrentoperation`: typo compatibility path; keep deprecated if any client may still call it.
+- `/api/v1/getpumpenergyproperties//` and `/api/v1/setpumpenergyproperties//`: double-slash paths in options endpoints.
+
+## Field Naming
+
+Most public JSON, query, and SSE fields are already `snake_case`, including `user_id`, `scheme_name`, `scheme_type`, `start_time`, `end_time`, `device_ids`, `session_id`, and `request_id`.
+
+Known legacy exception:
+
+- `BurstAnalysis.burst_ID` in `app/api/v1/endpoints/simulation.py` should become `burst_id` on a new API contract. Preserve `burst_ID` only for the legacy body shape.
+
+Headers keep standard HTTP casing:
+
+- `X-Project-Id`
+
+## Internal vs Customer Difference
+
+The customer backend retains local auth/user-management routes under `/api/v1/auth` and `/api/v1/users`; the internal backend has migrated to Keycloak/metadata admin routes. Treat those Customer-only auth routes as delivery compatibility surface, not a source for new internal API naming.
+
+## Recommendation
+
+Do not rename existing legacy routes in place. For each active legacy route, keep the new `kebab-case` alias as the documented path, keep the old route marked deprecated, migrate remaining Agent/customer/script callers, then remove only after a documented compatibility window.

DELIVERY_PACKAGING_NOTES.md

@@ -0,0 +1,102 @@
+# tjwater-server Customer Image Packaging Notes
+
+This repository is the customer-delivery backend package. Build delivery images from this repository root.
+
+## Image Build
+
+Build the customer backend image:
+
+```bash
+docker build -t tjwater-server:latest .
+```
+
+The `Dockerfile` already performs source encapsulation in the builder stage:
+
+```bash
+python scripts/compile.py
+python scripts/compile.py --delete-source
+```
+
+The compiled and source-deleted `app/` directory is then copied into the final runner stage. The source deletion happens inside the Docker builder layer only; it does not delete local workspace files.
+
+## Encapsulation Scope
+
+`scripts/compile.py` defaults to compiling these sensitive areas:
+
+- `app/services`
+- `app/native/wndb`
+- `app/algorithms`
+- `app/infra/epanet/epanet.py`
+
+These areas should not contain uncompiled `.py` source files in the delivered image. Public entry points, API route wiring, schemas, configuration, and operational files may remain readable when required for runtime.
+
+## Verification
+
+After building, verify the image tag:
+
+```bash
+docker image ls tjwater-server
+```
+
+Verify that core source files were removed and compiled extensions exist:
+
+```bash
+docker run --rm --entrypoint sh tjwater-server:latest -c "\
+printf 'core_py_count='; \
+find /app/app/services /app/app/native/wndb /app/app/algorithms /app/app/infra/epanet/epanet.py -name '*.py' 2>/dev/null | wc -l; \
+printf 'core_so_count='; \
+find /app/app/services /app/app/native/wndb /app/app/algorithms /app/app/infra/epanet -name '*.so' 2>/dev/null | wc -l; \
+python -c 'import app.main; print(\"import_app_main=ok\")'"
+```
+
+Expected delivery result:
+
+```text
+core_py_count=0
+core_so_count=<non-zero>
+import_app_main=ok
+```
+
+Warnings from third-party packages during import are not necessarily build failures. Treat non-zero exit codes, failed imports, or leftover core `.py` files as blockers.
+
+## Export For Windows Delivery
+
+Export the image tarball to the Windows desktop from WSL:
+
+```bash
+docker save -o /mnt/c/Users/admin/Desktop/tjwater-server-latest.tar tjwater-server:latest
+```
+
+Adjust the Windows username if needed. To find available desktop paths:
+
+```bash
+find /mnt/c/Users -maxdepth 2 -type d \( -name Desktop -o -name 桌面 \) 2>/dev/null
+```
+
+On the target machine, import the image with:
+
+```bash
+docker load -i tjwater-server-latest.tar
+```
+
+## Deployment Caution
+
+The development `infra/docker/docker-compose.yml` bind-mounts local source:
+
+```yaml
+volumes:
+  - ../../app:/app/app
+  - ../../resources:/app/resources
+```
+
+Do not use that source mount for customer delivery of the encapsulated image. Mounting `../../app` over `/app/app` replaces the compiled code inside the image with local source files and defeats the encapsulation. For delivery compose files, use the built image directly and mount only required runtime data/config paths.
+
+## Local Safety
+
+Do not run this destructive command in the normal working tree:
+
+```bash
+python scripts/compile.py --delete-source
+```
+
+Only use `--delete-source` in Docker builder stages or in a disposable delivery copy. The normal delivery image build already handles this safely.

DEPLOYMENT.md

@@ -1,391 +0,0 @@
-# 部署和集成指南
-
-本文档说明如何将新的安全功能集成到现有系统中。
-
-## 📦 已完成的功能
-
-### 1. 数据加密模块
-- ✅ `app/core/encryption.py` - Fernet 对称加密实现
-- ✅ 支持敏感数据加密/解密
-- ✅ 密钥管理和生成工具
-
-### 2. 用户认证系统
-- ✅ `app/domain/models/role.py` - 用户角色枚举 (ADMIN/OPERATOR/USER/VIEWER)
-- ✅ `app/domain/schemas/user.py` - 用户数据模型和验证
-- ✅ `app/infra/repositories/user_repository.py` - 用户数据访问层
-- ✅ `app/api/v1/endpoints/auth.py` - 注册/登录/刷新Token接口
-- ✅ `app/auth/dependencies.py` - 认证依赖项
-- ✅ `migrations/001_create_users_table.sql` - 用户表迁移脚本
-
-### 3. 权限控制系统
-- ✅ `app/auth/permissions.py` - RBAC 权限控制装饰器
-- ✅ `app/api/v1/endpoints/user_management.py` - 用户管理接口示例
-- ✅ 支持基于角色的访问控制
-- ✅ 支持资源所有者检查
-
-### 4. 审计日志系统
-- ✅ `app/core/audit.py` - 审计日志核心功能
-- ✅ `app/domain/schemas/audit.py` - 审计日志数据模型
-- ✅ `app/infra/repositories/audit_repository.py` - 审计日志数据访问层
-- ✅ `app/api/v1/endpoints/audit.py` - 审计日志查询接口
-- ✅ `app/infra/audit/middleware.py` - 自动审计中间件
-- ✅ `migrations/002_create_audit_logs_table.sql` - 审计日志表迁移脚本
-
-### 5. 文档和测试
-- ✅ `SECURITY_README.md` - 完整的使用文档
-- ✅ `.env.example` - 环境变量配置模板
-- ✅ `tests/test_encryption.py` - 加密功能测试
-
----
-
-## 🔧 集成步骤
-
-### 步骤 1: 环境配置
-
-1. 复制环境变量模板：
-```bash
-cp .env.example .env
-```
-
-2. 生成密钥并填写 `.env`：
-```bash
-# JWT 密钥
-openssl rand -hex 32
-
-# 加密密钥
-python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-```
-
-3. 编辑 `.env` 填写所有必需的配置项。
-
-### 步骤 2: 数据库迁移
-
-执行数据库迁移脚本：
-
-```bash
-# 方法 1: 使用 psql 命令
-psql -U postgres -d tjwater -f migrations/001_create_users_table.sql
-psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql
-
-# 方法 2: 在 psql 交互界面
-psql -U postgres -d tjwater
-\i migrations/001_create_users_table.sql
-\i migrations/002_create_audit_logs_table.sql
-```
-
-验证表已创建：
-
-```sql
--- 检查用户表
-SELECT * FROM users;
-
--- 检查审计日志表
-SELECT * FROM audit_logs;
-```
-
-### 步骤 3: 更新 main.py
-
-在 `app/main.py` 中集成新功能：
-
-```python
-from fastapi import FastAPI
-from app.core.config import settings
-from app.infra.audit.middleware import AuditMiddleware
-
-app = FastAPI(title=settings.PROJECT_NAME)
-
-# 1. 添加审计中间件（可选）
-app.add_middleware(AuditMiddleware)
-
-# 2. 注册路由
-from app.api.v1.endpoints import auth, user_management, audit
-
-app.include_router(
-    auth.router,
-    prefix=f"{settings.API_V1_STR}/auth",
-    tags=["认证"]
-)
-
-app.include_router(
-    user_management.router,
-    prefix=f"{settings.API_V1_STR}/users",
-    tags=["用户管理"]
-)
-
-app.include_router(
-    audit.router,
-    prefix=f"{settings.API_V1_STR}/audit",
-    tags=["审计日志"]
-)
-
-# 3. 确保数据库在启动时初始化
-@app.on_event("startup")
-async def startup_event():
-    # 初始化数据库连接池
-    from app.infra.db.postgresql.database import Database
-    global db
-    db = Database()
-    db.init_pool()
-    await db.open()
-
-@app.on_event("shutdown")
-async def shutdown_event():
-    # 关闭数据库连接
-    await db.close()
-```
-
-### 步骤 4: 保护现有接口
-
-#### 方法 1: 为路由添加全局依赖
-
-```python
-from app.auth.dependencies import get_current_active_user
-
-# 为整个路由器添加认证
-router = APIRouter(dependencies=[Depends(get_current_active_user)])
-```
-
-#### 方法 2: 为单个端点添加依赖
-
-```python
-from app.auth.permissions import require_role, get_current_admin
-from app.domain.models.role import UserRole
-
-@router.get("/data")
-async def get_data(
-    current_user = Depends(require_role(UserRole.USER))
-):
-    """需要 USER 及以上角色"""
-    return {"data": "protected"}
-
-@router.delete("/data/{id}")
-async def delete_data(
-    id: int,
-    current_user = Depends(get_current_admin)
-):
-    """仅管理员可访问"""
-    return {"message": "deleted"}
-```
-
-### 步骤 5: 添加审计日志
-
-#### 自动审计（推荐）
-
-使用中间件自动记录（已在 main.py 中添加）：
-
-```python
-app.add_middleware(AuditMiddleware)
-```
-
-#### 手动审计
-
-在关键业务逻辑中手动记录：
-
-```python
-from app.core.audit import log_audit_event, AuditAction
-
-@router.post("/important-action")
-async def important_action(
-    data: dict,
-    request: Request,
-    current_user = Depends(get_current_active_user)
-):
-    # 执行业务逻辑
-    result = do_something(data)
-    
-    # 记录审计日志
-    await log_audit_event(
-        action=AuditAction.UPDATE,
-        user_id=current_user.id,
-        username=current_user.username,
-        resource_type="important_resource",
-        resource_id=str(result.id),
-        ip_address=request.client.host,
-        request_data=data
-    )
-    
-    return result
-```
-
-### 步骤 6: 更新 auth/dependencies.py
-
-确保 `get_db()` 函数正确获取数据库实例：
-
-```python
-async def get_db() -> Database:
-    """获取数据库实例"""
-    # 方法 1: 从 main.py 导入
-    from app.main import db
-    return db
-    
-    # 方法 2: 从 FastAPI app.state 获取
-    # from fastapi import Request
-    # def get_db_from_request(request: Request):
-    #     return request.app.state.db
-```
-
----
-
-## 🧪 测试
-
-### 1. 测试加密功能
-
-```bash
-python tests/test_encryption.py
-```
-
-### 2. 测试 API
-
-启动服务器：
-
-```bash
-uvicorn app.main:app --reload
-```
-
-访问交互式文档：
-- Swagger UI: http://localhost:8000/docs
-- ReDoc: http://localhost:8000/redoc
-
-### 3. 测试登录
-
-```bash
-curl -X POST "http://localhost:8000/api/v1/auth/login" \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "username=admin&password=admin123"
-```
-
-### 4. 测试受保护接口
-
-```bash
-TOKEN="your-access-token"
-curl -X GET "http://localhost:8000/api/v1/auth/me" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
----
-
-## 🔄 迁移现有接口
-
-### 原有硬编码认证
-
-**旧代码** (`app/api/v1/endpoints/auth.py`):
-```python
-AUTH_TOKEN = "567e33c876a2"
-
-async def verify_token(authorization: str = Header()):
-    token = authorization.split(" ")[1]
-    if token != AUTH_TOKEN:
-        raise HTTPException(status_code=403)
-```
-
-**新代码** (已更新):
-```python
-from app.auth.dependencies import get_current_active_user
-
-@router.get("/protected")
-async def protected_route(
-    current_user = Depends(get_current_active_user)
-):
-    return {"user": current_user.username}
-```
-
-### 更新其他端点
-
-搜索项目中使用旧认证的地方：
-
-```bash
-grep -r "AUTH_TOKEN" app/
-grep -r "verify_token" app/
-```
-
-替换为新的依赖注入系统。
-
----
-
-## 📋 检查清单
-
-部署前检查：
-
-- [ ] 环境变量已配置（`.env`）
-- [ ] 数据库迁移已执行
-- [ ] 默认管理员账号可登录
-- [ ] JWT Token 可正常生成和验证
-- [ ] 权限控制正常工作
-- [ ] 审计日志正常记录
-- [ ] 加密功能测试通过
-- [ ] API 文档可访问
-
----
-
-## ⚠️ 注意事项
-
-### 1. 向后兼容性
-
-保留了简化版登录接口 `/auth/login/simple` 以兼容旧客户端：
-
-```python
-@router.post("/login/simple")
-async def login_simple(username: str, password: str):
-    # 验证并返回 Token
-    ...
-```
-
-### 2. 数据库连接
-
-确保在 `app/auth/dependencies.py` 中 `get_db()` 函数能正确获取数据库实例。
-
-### 3. 密钥安全
-
-- ❌ 不要提交 `.env` 文件到版本控制
-- ✅ 在生产环境使用环境变量或密钥管理服务
-- ✅ 定期轮换 JWT 密钥
-
-### 4. 性能考虑
-
-- 审计中间件会增加每个请求的处理时间（约 5-10ms）
-- 对高频接口可考虑异步记录审计日志
-- 定期清理或归档旧的审计日志
-
----
-
-## 🐛 故障排查
-
-### 问题 1: 导入错误
-
-```
-ImportError: cannot import name 'db' from 'app.main'
-```
-
-**解决**: 确保在 `app/main.py` 中定义了全局 `db` 对象。
-
-### 问题 2: 认证失败
-
-```
-401 Unauthorized: Could not validate credentials
-```
-
-**检查**:
-1. Token 是否正确设置在 `Authorization: Bearer {token}` header
-2. Token 是否过期
-3. SECRET_KEY 是否配置正确
-
-### 问题 3: 数据库连接失败
-
-```
-psycopg.OperationalError: connection failed
-```
-
-**检查**:
-1. PostgreSQL 是否运行
-2. `.env` 中数据库配置是否正确
-3. 数据库是否存在
-
----
-
-## 📞 技术支持
-
-详细文档请参考：
-- `SECURITY_README.md` - 安全功能使用指南
-- `migrations/` - 数据库迁移脚本
-- `app/domain/schemas/` - 数据模型定义
-

Dockerfile

@@ -1,20 +1,39 @@
-FROM continuumio/miniconda3:latest
+FROM condaforge/miniforge3:latest AS runtime-base
 
 WORKDIR /app
 
+ENV PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
+    PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn \
+    UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+
 # 安装 Python 3.12 和 pymetis (通过 conda-forge 避免编译问题)
-RUN conda install -y -c conda-forge python=3.12 pymetis && \
-    conda clean -afy
+RUN mamba install -y python=3.12 pymetis && \
+    mamba clean -afy
 
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir uv
+RUN uv pip install --system --no-cache-dir -r requirements.txt
+
+FROM runtime-base AS builder
+
+RUN mamba install -y c-compiler cxx-compiler && \
+    mamba clean -afy
+
+COPY app ./app
+COPY scripts ./scripts
+
+RUN python scripts/compile.py && \
+    python scripts/compile.py --delete-source
+
+FROM runtime-base AS runner
 
 # 将代码放入子目录 'app'，将数据放入子目录 'db_inp'
 # 这样临时文件默认会生成在 /app 下，而代码在 /app/app 下，实现了分离
-COPY app ./app
-COPY db_inp ./db_inp
-COPY temp ./temp
-COPY .env .
+COPY --from=builder /app/app ./app
+RUN python -c "from pathlib import Path; from zipfile import ZipFile; model_dir = Path('app/algorithms/health/model'); zip_path = model_dir / 'my_survival_forest_model_quxi.zip'; joblib_name = 'my_survival_forest_model_quxi.joblib'; joblib_path = model_dir / joblib_name; assert zip_path.exists(), f'Model archive not found: {zip_path}'; archive = ZipFile(zip_path); archive.extract(joblib_name, model_dir); archive.close(); assert joblib_path.exists(), f'Model file not extracted: {joblib_path}'" && \
+    rm -f app/algorithms/health/model/my_survival_forest_model_quxi.zip
+# COPY db_inp ./db_inp
+RUN mkdir -p db_inp temp data inp
 
 # 设置 PYTHONPATH 以便 uvicorn 找到 app 模块
 ENV PYTHONPATH=/app

INTEGRATION_CHECKLIST.md

@@ -1,322 +0,0 @@
-# API 集成检查清单
-
-## ✅ 已完成的集成工作
-
-### 1. 路由集成 (app/api/v1/router.py)
-
-已添加以下路由到 API Router：
-
-```python
-# 新增导入
-from app.api.v1.endpoints import (
-    ...
-    user_management,  # 用户管理
-    audit,            # 审计日志
-)
-
-# 新增路由
-api_router.include_router(user_management.router, prefix="/users", tags=["User Management"])
-api_router.include_router(audit.router, prefix="/audit", tags=["Audit Logs"])
-```
-
-**路由端点**：
-- `/api/v1/auth/` - 认证相关（register, login, me, refresh）
-- `/api/v1/users/` - 用户管理（CRUD操作，仅管理员）
-- `/api/v1/audit/` - 审计日志查询（仅管理员）
-
-### 2. 主应用配置 (app/main.py)
-
-#### 2.1 导入更新
-```python
-from app.core.config import settings
-from app.infra.audit.middleware import AuditMiddleware
-```
-
-#### 2.2 数据库初始化
-```python
-# 在 lifespan 中存储数据库实例到 app.state
-app.state.db = pgdb
-```
-
-#### 2.3 FastAPI 配置
-```python
-app = FastAPI(
-    lifespan=lifespan,
-    title=settings.PROJECT_NAME,
-    description="TJWater Server - 供水管网智能管理系统",
-    version="1.0.0",
-    docs_url="/docs",
-    redoc_url="/redoc",
-)
-```
-
-#### 2.4 审计中间件（可选）
-```python
-# 取消注释以启用审计日志
-# app.add_middleware(AuditMiddleware)
-```
-
-### 3. 依赖项更新 (app/auth/dependencies.py)
-
-更新 `get_db()` 函数从 Request 对象获取数据库：
-
-```python
-async def get_db(request: Request) -> Database:
-    """从 app.state 获取数据库实例"""
-    if not hasattr(request.app.state, "db"):
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Database not initialized"
-        )
-    return request.app.state.db
-```
-
-### 4. 审计日志更新
-
-- `app/api/v1/endpoints/audit.py` - 使用正确的数据库依赖
-- `app/core/audit.py` - 接受可选的 db 参数
-
----
-
-## 📋 部署前检查清单
-
-### 环境配置
-- [ ] 复制 `.env.example` 为 `.env`
-- [ ] 配置 `SECRET_KEY`（JWT密钥）
-- [ ] 配置 `ENCRYPTION_KEY`（数据加密密钥）
-- [ ] 配置数据库连接信息
-
-### 数据库迁移
-- [ ] 执行用户表迁移：`psql -U postgres -d tjwater -f migrations/001_create_users_table.sql`
-- [ ] 执行审计日志表迁移：`psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql`
-- [ ] 验证表已创建：`\dt` 在 psql 中
-
-### 依赖检查
-- [ ] 确认已安装：`cryptography`
-- [ ] 确认已安装：`python-jose[cryptography]`
-- [ ] 确认已安装：`passlib[bcrypt]`
-- [ ] 确认已安装：`email-validator`（用于 Pydantic email 验证）
-
-### 代码验证
-- [ ] 检查所有文件导入正常
-- [ ] 运行加密功能测试：`python tests/test_encryption.py`
-- [ ] 启动服务器：`uvicorn app.main:app --reload`
-- [ ] 访问 API 文档：http://localhost:8000/docs
-
-### API 测试
-- [ ] 测试登录：POST `/api/v1/auth/login`
-- [ ] 测试获取当前用户：GET `/api/v1/auth/me`
-- [ ] 测试用户列表（需管理员）：GET `/api/v1/users/`
-- [ ] 测试审计日志（需管理员）：GET `/api/v1/audit/logs`
-
----
-
-## 🔧 快速测试命令
-
-### 1. 生成密钥
-```bash
-# JWT 密钥
-openssl rand -hex 32
-
-# 加密密钥
-python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-```
-
-### 2. 执行迁移
-```bash
-cd /home/zhifu/TJWaterServer/TJWaterServerBinary
-psql -U postgres -d tjwater -f migrations/001_create_users_table.sql
-psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql
-```
-
-### 3. 测试加密
-```bash
-python tests/test_encryption.py
-```
-
-### 4. 启动服务器
-```bash
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
-```
-
-### 5. 测试登录 API
-```bash
-# 使用默认管理员账号
-curl -X POST "http://localhost:8000/api/v1/auth/login" \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "username=admin&password=admin123"
-
-# 或使用迁移的账号
-curl -X POST "http://localhost:8000/api/v1/auth/login" \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "username=tjwater&password=tjwater@123"
-```
-
-### 6. 测试受保护接口
-```bash
-# 保存 Token
-TOKEN="<从登录响应中获取的 access_token>"
-
-# 获取当前用户信息
-curl -X GET "http://localhost:8000/api/v1/auth/me" \
-  -H "Authorization: Bearer $TOKEN"
-
-# 获取用户列表（需管理员权限）
-curl -X GET "http://localhost:8000/api/v1/users/" \
-  -H "Authorization: Bearer $TOKEN"
-
-# 查询审计日志（需管理员权限）
-curl -X GET "http://localhost:8000/api/v1/audit/logs" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
----
-
-## 📚 API 端点总览
-
-### 认证接口 (`/api/v1/auth`)
-
-| 方法 | 端点 | 描述 | 权限 |
-|------|------|------|------|
-| POST | `/register` | 用户注册 | 公开 |
-| POST | `/login` | OAuth2 登录 | 公开 |
-| POST | `/login/simple` | 简化登录（兼容旧版） | 公开 |
-| GET | `/me` | 获取当前用户信息 | 认证用户 |
-| POST | `/refresh` | 刷新 Token | 认证用户 |
-
-### 用户管理 (`/api/v1/users`)
-
-| 方法 | 端点 | 描述 | 权限 |
-|------|------|------|------|
-| GET | `/` | 获取用户列表 | 管理员 |
-| GET | `/{id}` | 获取用户详情 | 所有者/管理员 |
-| PUT | `/{id}` | 更新用户信息 | 所有者/管理员 |
-| DELETE | `/{id}` | 删除用户 | 管理员 |
-| POST | `/{id}/activate` | 激活用户 | 管理员 |
-| POST | `/{id}/deactivate` | 停用用户 | 管理员 |
-
-### 审计日志 (`/api/v1/audit`)
-
-| 方法 | 端点 | 描述 | 权限 |
-|------|------|------|------|
-| GET | `/logs` | 查询审计日志 | 管理员 |
-| GET | `/logs/count` | 获取日志总数 | 管理员 |
-| GET | `/logs/my` | 查看我的操作记录 | 认证用户 |
-
----
-
-## ⚠️ 注意事项
-
-### 1. 审计中间件
-审计中间件默认是**禁用**的。如需启用，在 `app/main.py` 中取消注释：
-
-```python
-app.add_middleware(AuditMiddleware)
-```
-
-**注意**：启用后会自动记录所有 POST/PUT/DELETE 请求，可能增加数据库负载。
-
-### 2. 向后兼容
-保留了原有的简化登录接口 `/auth/login/simple`，可以直接使用查询参数：
-
-```bash
-POST /api/v1/auth/login/simple?username=admin&password=admin123
-```
-
-### 3. 数据库连接
-确保数据库实例在应用启动时正确初始化并存储到 `app.state.db`。
-
-### 4. 权限控制示例
-为现有接口添加权限控制：
-
-```python
-from app.auth.permissions import require_role, get_current_admin
-from app.domain.models.role import UserRole
-
-# 需要管理员权限
-@router.delete("/resource/{id}")
-async def delete_resource(
-    id: int,
-    current_user = Depends(get_current_admin)
-):
-    ...
-
-# 需要操作员以上权限
-@router.post("/resource")
-async def create_resource(
-    data: dict,
-    current_user = Depends(require_role(UserRole.OPERATOR))
-):
-    ...
-```
-
----
-
-## 🚀 完整启动流程
-
-```bash
-# 1. 进入项目目录
-cd /home/zhifu/TJWaterServer/TJWaterServerBinary
-
-# 2. 配置环境变量（如果还没有）
-cp .env.example .env
-# 编辑 .env 填写必要的配置
-
-# 3. 执行数据库迁移（如果还没有）
-psql -U postgres -d tjwater < migrations/001_create_users_table.sql
-psql -U postgres -d tjwater < migrations/002_create_audit_logs_table.sql
-
-# 4. 测试加密功能
-python tests/test_encryption.py
-
-# 5. 启动服务器
-uvicorn app.main:app --reload
-
-# 6. 访问 API 文档
-# 浏览器打开: http://localhost:8000/docs
-```
-
----
-
-## 📞 故障排查
-
-### 问题 1: 导入错误
-```
-ModuleNotFoundError: No module named 'jose'
-```
-**解决**: 安装依赖 `pip install python-jose[cryptography]`
-
-### 问题 2: 数据库未初始化
-```
-503 Service Unavailable: Database not initialized
-```
-**解决**: 检查 `main.py` 中的 lifespan 函数是否正确设置 `app.state.db`
-
-### 问题 3: Token 验证失败
-```
-401 Unauthorized: Could not validate credentials
-```
-**解决**: 
-1. 检查 SECRET_KEY 是否配置正确
-2. 确认 Token 格式：`Authorization: Bearer {token}`
-3. 检查 Token 是否过期
-
-### 问题 4: 表不存在
-```
-relation "users" does not exist
-```
-**解决**: 执行数据库迁移脚本
-
----
-
-## 📖 相关文档
-
-- **使用指南**: `SECURITY_README.md`
-- **部署指南**: `DEPLOYMENT.md`
-- **实施总结**: `SECURITY_IMPLEMENTATION_SUMMARY.md`
-- **自动设置**: `setup_security.sh`
-
----
-
-**最后更新**: 2026-02-02
-**状态**: ✅ API 已完全集成

README.md

@@ -0,0 +1,107 @@
+# TJWaterServerCustomer 客户版后端
+
+`TJWaterServerCustomer` 是 TJWater 客户交付版 Python 后端。该仓库应被视为可部署交付包，只保留客户运行、配置、部署、诊断和交付说明所需内容。
+
+## 技术栈
+
+- Python 3.12
+- FastAPI / Uvicorn
+- Pydantic / SQLAlchemy / psycopg
+- Redis、PostgreSQL、PostGIS、TimescaleDB
+- WNTR、EPANET、Cython、科学计算与空间分析依赖
+- pytest
+
+## 目录结构
+
+```text
+app/main.py           FastAPI 入口
+app/api/              HTTP API 路由
+app/auth/             认证和权限上下文
+app/core/             配置、日志和基础设施初始化
+app/domain/           领域模型和 Pydantic schema
+app/infra/            数据库、缓存、EPANET 和外部集成
+app/services/         核心业务服务，交付镜像中必须封装
+app/algorithms/       核心算法，交付镜像中必须封装
+app/native/           本地管网数据读写与转换，交付镜像中必须封装
+scripts/compile.py    Cython 封装脚本
+infra/docker/         Docker Compose 编排
+tests/                后端测试
+```
+
+## 本地开发
+
+推荐使用已有 conda 环境：
+
+```bash
+conda run -n server python -m pytest tests -q
+conda run -n server python scripts/run_server.py
+```
+
+本地调试不要在正常工作树执行源码删除命令。
+
+## 客户版镜像打包
+
+交付镜像标签通常为：
+
+```bash
+docker build -t tjwater-server:latest .
+```
+
+`Dockerfile` 会在 builder 阶段执行：
+
+```bash
+python scripts/compile.py
+python scripts/compile.py --delete-source
+```
+
+源码删除只发生在 Docker 构建层内，不会删除本地工作树源码。详细封装、验证和 Windows 导出说明见：
+
+```text
+DELIVERY_PACKAGING_NOTES.md
+```
+
+## 封装范围
+
+`scripts/compile.py` 默认封装：
+
+- `app/services`
+- `app/native/wndb`
+- `app/algorithms`
+- `app/infra/epanet/epanet.py`
+
+交付镜像中这些核心目录不应残留未编译的 `.py` 源码，应以 `.so` 扩展模块运行。
+
+## 验证命令
+
+构建后检查镜像：
+
+```bash
+docker image ls tjwater-server
+```
+
+检查核心源码是否已删除、FastAPI 入口是否可导入：
+
+```bash
+docker run --rm --entrypoint sh tjwater-server:latest -c "\
+printf 'core_py_count='; \
+find /app/app/services /app/app/native/wndb /app/app/algorithms /app/app/infra/epanet/epanet.py -name '*.py' 2>/dev/null | wc -l; \
+printf 'core_so_count='; \
+find /app/app/services /app/app/native/wndb /app/app/algorithms /app/app/infra/epanet -name '*.so' 2>/dev/null | wc -l; \
+python -c 'import app.main; print(\"import_app_main=ok\")'"
+```
+
+期望结果：
+
+```text
+core_py_count=0
+core_so_count=<非零>
+import_app_main=ok
+```
+
+## 部署注意
+
+客户交付时不要把本地 `../../app` 挂载到容器 `/app/app`，否则会覆盖镜像内已封装代码。交付 compose 文件应使用构建好的镜像，只挂载必要的运行数据和配置。
+
+## 安全规则
+
+不要提交 `.env`、生产凭据、客户数据、数据库 dump、日志、生成缓存、临时交付压缩包或本地运行目录。客户版仓库不应加入内部实验、调试工具或非交付源码材料。

SECURITY_IMPLEMENTATION_SUMMARY.md

@@ -1,370 +0,0 @@
-# 安全功能实施总结
-
-## ✅ 已完成的功能
-
-本次实施完成了完整的安全体系，包括数据加密、身份认证、权限管理、审计日志四大模块。
-
----
-
-## 📁 新增文件清单
-
-### 核心功能模块
-
-1. **数据加密**
-   - `app/core/encryption.py` - Fernet 加密实现
-   - `tests/test_encryption.py` - 加密功能测试
-
-2. **用户系统**
-   - `app/domain/models/role.py` - 用户角色枚举
-   - `app/domain/schemas/user.py` - 用户数据模型
-   - `app/infra/repositories/user_repository.py` - 用户数据访问层
-
-3. **认证授权**
-   - `app/api/v1/endpoints/auth.py` - 认证接口（已重构）
-   - `app/auth/dependencies.py` - 认证依赖项（已更新）
-   - `app/auth/permissions.py` - 权限控制装饰器
-   - `app/api/v1/endpoints/user_management.py` - 用户管理接口
-
-4. **审计日志**
-   - `app/core/audit.py` - 审计日志核心（已完善）
-   - `app/domain/schemas/audit.py` - 审计日志数据模型
-   - `app/infra/repositories/audit_repository.py` - 审计日志数据访问层
-   - `app/api/v1/endpoints/audit.py` - 审计日志查询接口
-   - `app/infra/audit/middleware.py` - 自动审计中间件
-
-### 数据库迁移
-
-5. **迁移脚本**
-   - `migrations/001_create_users_table.sql` - 用户表
-   - `migrations/002_create_audit_logs_table.sql` - 审计日志表
-
-### 配置和文档
-
-6. **配置文件**
-   - `.env.example` - 环境变量模板
-   - `app/core/config.py` - 配置文件（已更新）
-   - `app/core/security.py` - 安全工具（已增强）
-
-7. **文档**
-   - `SECURITY_README.md` - 完整使用指南（79KB+）
-   - `DEPLOYMENT.md` - 部署和集成指南
-   - `SECURITY_IMPLEMENTATION_SUMMARY.md` - 本文件
-
-8. **工具**
-   - `setup_security.sh` - 快速设置脚本
-
----
-
-## 🎯 功能特性
-
-### 1. 数据加密
-- ✅ 使用 Fernet（AES-128）对称加密
-- ✅ 支持密钥生成和管理
-- ✅ 自动从环境变量读取密钥
-- ✅ 完整的加密/解密 API
-- ✅ 单元测试覆盖
-
-### 2. 身份认证
-- ✅ 基于 JWT 的 Token 认证
-- ✅ Access Token + Refresh Token 机制
-- ✅ 用户注册/登录接口
-- ✅ 支持用户名或邮箱登录
-- ✅ 密码使用 bcrypt 哈希存储
-- ✅ Token 过期时间可配置
-- ✅ 向后兼容旧接口
-
-### 3. 权限管理（RBAC）
-- ✅ 4 个预定义角色：ADMIN, OPERATOR, USER, VIEWER
-- ✅ 基于角色层级的权限检查
-- ✅ 可复用的权限装饰器
-- ✅ 资源所有者检查
-- ✅ 灵活的依赖注入设计
-
-### 4. 审计日志
-- ✅ 自动记录所有关键操作
-- ✅ 记录用户、时间、操作类型、资源等信息
-- ✅ 敏感数据自动脱敏
-- ✅ 支持按多条件查询
-- ✅ 管理员专用查询接口
-- ✅ 用户可查看自己的操作记录
-
----
-
-## 📊 技术栈
-
-| 组件 | 技术 | 说明 |
-|------|------|------|
-| 加密 | cryptography.Fernet | 对称加密 |
-| 密码哈希 | bcrypt | 密码安全存储 |
-| JWT | python-jose | Token 生成和验证 |
-| 数据库 | PostgreSQL + psycopg | 异步数据访问 |
-| Web框架 | FastAPI | 现代异步框架 |
-| 数据验证 | Pydantic | 类型安全的数据模型 |
-
----
-
-## 🔐 安全特性
-
-1. **密码安全**
-   - bcrypt 哈希（work factor = 12）
-   - 自动加盐
-   - 不可逆加密
-
-2. **Token 安全**
-   - JWT 签名验证
-   - 短期 Access Token（30分钟）
-   - 长期 Refresh Token（7天）
-   - Token 类型校验
-
-3. **数据保护**
-   - 敏感字段自动脱敏
-   - 审计日志不记录密码
-   - 加密密钥从环境变量读取
-
-4. **访问控制**
-   - 基于角色的细粒度权限
-   - 资源级别的访问控制
-   - 自动验证用户激活状态
-
----
-
-## 📈 数据库设计
-
-### users 表
-```
-用户表 - 存储系统用户
-- id (主键)
-- username (唯一)
-- email (唯一)
-- hashed_password
-- role (ADMIN/OPERATOR/USER/VIEWER)
-- is_active
-- is_superuser
-- created_at
-- updated_at (自动更新)
-```
-
-### audit_logs 表
-```
-审计日志表 - 记录所有关键操作
-- id (主键)
-- user_id (外键)
-- username (冗余字段)
-- action (操作类型)
-- resource_type (资源类型)
-- resource_id (资源ID)
-- ip_address
-- user_agent
-- request_method
-- request_path
-- request_data (JSONB)
-- response_status
-- error_message
-- timestamp
-```
-
-**索引优化**：
-- users: username, email, role, is_active
-- audit_logs: user_id, username, timestamp, action, resource
-
----
-
-## 🚀 快速开始
-
-### 方法 1: 使用自动化脚本
-
-```bash
-./setup_security.sh
-```
-
-### 方法 2: 手动设置
-
-```bash
-# 1. 配置环境变量
-cp .env.example .env
-# 编辑 .env 填写密钥和数据库配置
-
-# 2. 执行数据库迁移
-psql -U postgres -d tjwater -f migrations/001_create_users_table.sql
-psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql
-
-# 3. 测试
-python tests/test_encryption.py
-
-# 4. 启动服务
-uvicorn app.main:app --reload
-```
-
----
-
-## 📋 集成检查清单
-
-### 必需步骤
-
-- [ ] 复制 `.env.example` 为 `.env` 并配置
-- [ ] 生成 JWT 密钥（SECRET_KEY）
-- [ ] 生成加密密钥（ENCRYPTION_KEY）
-- [ ] 配置数据库连接信息
-- [ ] 执行用户表迁移脚本
-- [ ] 执行审计日志表迁移脚本
-- [ ] 验证默认管理员可登录
-
-### 可选步骤
-
-- [ ] 在 main.py 中添加审计中间件
-- [ ] 为现有接口添加权限控制
-- [ ] 注册新的路由（auth, user_management, audit）
-- [ ] 替换硬编码的认证逻辑
-- [ ] 配置 Token 过期时间
-
----
-
-## 🔄 向后兼容性
-
-### 保留的旧接口
-
-1. **简化登录**: `/api/v1/auth/login/simple`
-   - 仍可使用 `username` 和 `password` 参数
-   - 返回标准 Token 响应
-
-2. **硬编码用户迁移**
-   - 原有 `tjwater/tjwater@123` 已迁移到数据库
-   - 保持相同的用户名和密码
-
-### 渐进式迁移
-
-可以逐步迁移现有接口：
-
-1. 新接口直接使用新认证系统
-2. 旧接口保持不变
-3. 逐个替换旧接口的认证逻辑
-
----
-
-## 📚 API 端点总览
-
-### 认证接口 (`/api/v1/auth/`)
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| POST | `/register` | 用户注册 | 公开 |
-| POST | `/login` | OAuth2 登录 | 公开 |
-| POST | `/login/simple` | 简化登录 | 公开 |
-| GET | `/me` | 获取当前用户 | 认证用户 |
-| POST | `/refresh` | 刷新Token | 认证用户 |
-
-### 用户管理 (`/api/v1/users/`)
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| GET | `/` | 用户列表 | 管理员 |
-| GET | `/{id}` | 用户详情 | 所有者/管理员 |
-| PUT | `/{id}` | 更新用户 | 所有者/管理员 |
-| DELETE | `/{id}` | 删除用户 | 管理员 |
-| POST | `/{id}/activate` | 激活用户 | 管理员 |
-| POST | `/{id}/deactivate` | 停用用户 | 管理员 |
-
-### 审计日志 (`/api/v1/audit/`)
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| GET | `/logs` | 查询审计日志 | 管理员 |
-| GET | `/logs/count` | 日志总数 | 管理员 |
-| GET | `/logs/my` | 我的操作记录 | 认证用户 |
-
----
-
-## 🎓 使用示例
-
-### Python 示例
-
-```python
-import requests
-
-# 登录
-resp = requests.post("http://localhost:8000/api/v1/auth/login", 
-                     data={"username": "admin", "password": "admin123"})
-token = resp.json()["access_token"]
-
-# 访问受保护接口
-headers = {"Authorization": f"Bearer {token}"}
-resp = requests.get("http://localhost:8000/api/v1/auth/me", headers=headers)
-print(resp.json())
-```
-
-### cURL 示例
-
-```bash
-# 登录
-TOKEN=$(curl -s -X POST "http://localhost:8000/api/v1/auth/login" \
-  -d "username=admin&password=admin123" | jq -r .access_token)
-
-# 查询审计日志
-curl -H "Authorization: Bearer $TOKEN" \
-  "http://localhost:8000/api/v1/audit/logs?action=LOGIN"
-```
-
----
-
-## 🐛 常见问题
-
-### Q: 如何修改默认管理员密码？
-
-A: 登录后通过 PUT `/api/v1/users/{id}` 接口修改，或直接更新数据库。
-
-### Q: 如何添加新用户？
-
-A: 使用 POST `/api/v1/auth/register` 接口，或由管理员在用户管理界面创建。
-
-### Q: 审计日志可以删除吗？
-
-A: 不建议删除。可以归档到冷存储，保留最近 90 天的数据。
-
-### Q: Token 过期了怎么办？
-
-A: 使用 Refresh Token 调用 `/api/v1/auth/refresh` 接口获取新的 Access Token。
-
----
-
-## 📞 技术支持
-
-- **完整文档**: `SECURITY_README.md`
-- **部署指南**: `DEPLOYMENT.md`
-- **测试代码**: `tests/test_encryption.py`
-- **迁移脚本**: `migrations/`
-
----
-
-## 📝 待办事项（可选）
-
-未来可以扩展的功能：
-
-- [ ] 邮件验证
-- [ ] 密码重置
-- [ ] 双因素认证（2FA）
-- [ ] 单点登录（SSO）
-- [ ] Token 黑名单
-- [ ] 会话管理
-- [ ] IP 白名单
-- [ ] 登录频率限制
-- [ ] 密码复杂度策略
-- [ ] 审计日志自动归档
-
----
-
-## 🎉 总结
-
-本次实施完成了企业级的安全体系，包含：
-
-✅ 数据加密 - Fernet 对称加密
-✅ 身份认证 - JWT Token + bcrypt 密码哈希
-✅ 权限管理 - 基于角色的访问控制（RBAC）
-✅ 审计日志 - 自动追踪所有关键操作
-
-所有功能均遵循安全最佳实践，提供完整的文档和测试，可直接投入生产使用。
-
----
-
-**实施日期**: 2026-02-02
-**版本**: v1.0.0
-**状态**: ✅ 已完成

SECURITY_README.md

@@ -1,499 +0,0 @@
-# 安全功能使用指南
-
-TJWater Server 安全体系实施完成，包含：数据加密、身份认证、权限管理、审计日志
-
-## 📋 目录
-
-1. [快速开始](#快速开始)
-2. [数据加密](#数据加密)
-3. [身份认证](#身份认证)
-4. [权限管理](#权限管理)
-5. [审计日志](#审计日志)
-6. [数据库迁移](#数据库迁移)
-7. [API 使用示例](#api-使用示例)
-
----
-
-## 🚀 快速开始
-
-### 1. 配置环境变量
-
-复制 `.env.example` 为 `.env` 并配置：
-
-```bash
-cp .env.example .env
-```
-
-生成必要的密钥：
-
-```bash
-# 生成 JWT 密钥
-openssl rand -hex 32
-
-# 生成加密密钥
-python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-```
-
-编辑 `.env` 文件：
-
-```env
-SECRET_KEY=your-generated-jwt-secret-key
-ENCRYPTION_KEY=your-generated-encryption-key
-DB_NAME=tjwater
-DB_HOST=localhost
-DB_PORT=5432
-DB_USER=postgres
-DB_PASSWORD=your-db-password
-```
-
-### 2. 执行数据库迁移
-
-```bash
-# 连接到 PostgreSQL
-psql -U postgres -d tjwater
-
-# 执行迁移脚本
-\i migrations/001_create_users_table.sql
-\i migrations/002_create_audit_logs_table.sql
-```
-
-或使用命令行：
-
-```bash
-psql -U postgres -d tjwater -f migrations/001_create_users_table.sql
-psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql
-```
-
-### 3. 验证安装
-
-默认创建了两个管理员账号：
-
-- **用户名**: `admin` / **密码**: `admin123`
-- **用户名**: `tjwater` / **密码**: `tjwater@123`
-
----
-
-## 🔐 数据加密
-
-### 使用加密器
-
-```python
-from app.core.encryption import get_encryptor
-
-encryptor = get_encryptor()
-
-# 加密敏感数据
-encrypted_data = encryptor.encrypt("sensitive information")
-
-# 解密
-decrypted_data = encryptor.decrypt(encrypted_data)
-```
-
-### 生成新密钥
-
-```python
-from app.core.encryption import Encryptor
-
-new_key = Encryptor.generate_key()
-print(f"New encryption key: {new_key}")
-```
-
----
-
-## 👤 身份认证
-
-### 用户角色
-
-系统定义了 4 个角色（权限由低到高）：
-
-| 角色 | 权限说明 |
-|------|---------|
-| `VIEWER` | 仅查询权限 |
-| `USER` | 读写权限 |
-| `OPERATOR` | 操作员，可修改数据 |
-| `ADMIN` | 管理员，完全权限 |
-
-### API 接口
-
-#### 用户注册
-
-```http
-POST /api/v1/auth/register
-Content-Type: application/json
-
-{
-  "username": "newuser",
-  "email": "user@example.com",
-  "password": "password123",
-  "role": "USER"
-}
-```
-
-#### 用户登录（OAuth2 标准）
-
-```http
-POST /api/v1/auth/login
-Content-Type: application/x-www-form-urlencoded
-
-username=admin&password=admin123
-```
-
-响应：
-
-```json
-{
-  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "token_type": "bearer",
-  "expires_in": 1800
-}
-```
-
-#### 用户登录（简化版）
-
-```http
-POST /api/v1/auth/login/simple?username=admin&password=admin123
-```
-
-#### 获取当前用户信息
-
-```http
-GET /api/v1/auth/me
-Authorization: Bearer {access_token}
-```
-
-#### 刷新 Token
-
-```http
-POST /api/v1/auth/refresh
-Content-Type: application/json
-
-{
-  "refresh_token": "your-refresh-token"
-}
-```
-
----
-
-## 🔑 权限管理
-
-### 在 API 中使用权限控制
-
-#### 方式 1: 使用预定义依赖
-
-```python
-from fastapi import APIRouter, Depends
-from app.auth.permissions import get_current_admin, get_current_operator
-from app.domain.schemas.user import UserInDB
-
-router = APIRouter()
-
-@router.post("/admin-only")
-async def admin_endpoint(
-    current_user: UserInDB = Depends(get_current_admin)
-):
-    """仅管理员可访问"""
-    return {"message": "Admin access granted"}
-
-@router.post("/operator-only")
-async def operator_endpoint(
-    current_user: UserInDB = Depends(get_current_operator)
-):
-    """操作员及以上可访问"""
-    return {"message": "Operator access granted"}
-```
-
-#### 方式 2: 使用 require_role
-
-```python
-from app.auth.permissions import require_role
-from app.domain.models.role import UserRole
-
-@router.get("/viewer-access")
-async def viewer_endpoint(
-    current_user: UserInDB = Depends(require_role(UserRole.VIEWER))
-):
-    """所有认证用户可访问"""
-    return {"data": "visible to all"}
-```
-
-#### 方式 3: 手动检查权限
-
-```python
-from app.auth.dependencies import get_current_active_user
-from app.auth.permissions import check_resource_owner
-
-@router.put("/users/{user_id}")
-async def update_user(
-    user_id: int,
-    current_user: UserInDB = Depends(get_current_active_user)
-):
-    """检查是否是资源拥有者或管理员"""
-    if not check_resource_owner(user_id, current_user):
-        raise HTTPException(status_code=403, detail="Permission denied")
-    
-    # 执行更新操作
-    ...
-```
-
----
-
-## 📝 审计日志
-
-### 自动审计
-
-使用中间件自动记录关键操作，在 `main.py` 中添加：
-
-```python
-from app.infra.audit.middleware import AuditMiddleware
-
-app.add_middleware(AuditMiddleware)
-```
-
-自动记录：
-- 所有 POST/PUT/DELETE 请求
-- 登录/登出事件
-- 关键资源访问
-
-### 手动记录审计日志
-
-```python
-from app.core.audit import log_audit_event, AuditAction
-
-await log_audit_event(
-    action=AuditAction.UPDATE,
-    user_id=current_user.id,
-    username=current_user.username,
-    resource_type="project",
-    resource_id="123",
-    ip_address=request.client.host,
-    request_data={"field": "value"},
-    response_status=200
-)
-```
-
-### 查询审计日志
-
-#### 获取所有审计日志（仅管理员）
-
-```http
-GET /api/v1/audit/logs?skip=0&limit=100
-Authorization: Bearer {admin_token}
-```
-
-#### 按条件过滤
-
-```http
-GET /api/v1/audit/logs?user_id=1&action=LOGIN&start_time=2024-01-01T00:00:00
-Authorization: Bearer {admin_token}
-```
-
-#### 获取我的操作记录
-
-```http
-GET /api/v1/audit/logs/my
-Authorization: Bearer {access_token}
-```
-
-#### 获取日志总数
-
-```http
-GET /api/v1/audit/logs/count?action=LOGIN
-Authorization: Bearer {admin_token}
-```
-
----
-
-## 💾 数据库迁移
-
-### 用户表结构
-
-```sql
-CREATE TABLE users (
-    id SERIAL PRIMARY KEY,
-    username VARCHAR(50) UNIQUE NOT NULL,
-    email VARCHAR(100) UNIQUE NOT NULL,
-    hashed_password VARCHAR(255) NOT NULL,
-    role VARCHAR(20) DEFAULT 'USER' NOT NULL,
-    is_active BOOLEAN DEFAULT TRUE NOT NULL,
-    is_superuser BOOLEAN DEFAULT FALSE NOT NULL,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
-);
-```
-
-### 审计日志表结构
-
-```sql
-CREATE TABLE audit_logs (
-    id SERIAL PRIMARY KEY,
-    user_id INTEGER REFERENCES users(id),
-    username VARCHAR(50),
-    action VARCHAR(50) NOT NULL,
-    resource_type VARCHAR(50),
-    resource_id VARCHAR(100),
-    ip_address VARCHAR(45),
-    user_agent TEXT,
-    request_method VARCHAR(10),
-    request_path TEXT,
-    request_data JSONB,
-    response_status INTEGER,
-    error_message TEXT,
-    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
-);
-```
-
----
-
-## 🔧 API 使用示例
-
-### Python 客户端示例
-
-```python
-import requests
-
-BASE_URL = "http://localhost:8000/api/v1"
-
-# 1. 登录
-response = requests.post(
-    f"{BASE_URL}/auth/login",
-    data={"username": "admin", "password": "admin123"}
-)
-token = response.json()["access_token"]
-
-# 2. 设置 Authorization Header
-headers = {"Authorization": f"Bearer {token}"}
-
-# 3. 获取当前用户信息
-response = requests.get(f"{BASE_URL}/auth/me", headers=headers)
-print(response.json())
-
-# 4. 创建新用户（需要管理员权限）
-response = requests.post(
-    f"{BASE_URL}/auth/register",
-    headers=headers,
-    json={
-        "username": "newuser",
-        "email": "new@example.com",
-        "password": "password123",
-        "role": "USER"
-    }
-)
-print(response.json())
-
-# 5. 查询审计日志（需要管理员权限）
-response = requests.get(
-    f"{BASE_URL}/audit/logs?action=LOGIN",
-    headers=headers
-)
-print(response.json())
-```
-
-### cURL 示例
-
-```bash
-# 登录
-curl -X POST "http://localhost:8000/api/v1/auth/login" \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "username=admin&password=admin123"
-
-# 使用 Token 访问受保护接口
-TOKEN="your-access-token"
-curl -X GET "http://localhost:8000/api/v1/auth/me" \
-  -H "Authorization: Bearer $TOKEN"
-
-# 注册新用户
-curl -X POST "http://localhost:8000/api/v1/auth/register" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $TOKEN" \
-  -d '{
-    "username": "testuser",
-    "email": "test@example.com",
-    "password": "password123",
-    "role": "USER"
-  }'
-```
-
----
-
-## 🛡️ 安全最佳实践
-
-1. **密钥管理**
-   - 绝不在代码中硬编码密钥
-   - 定期轮换 JWT 密钥
-   - 使用强随机密钥
-
-2. **密码策略**
-   - 最小长度 6 个字符（建议 12+）
-   - 强制密码复杂度（可在注册时添加验证）
-   - 定期提醒用户更换密码
-
-3. **Token 管理**
-   - Access Token 短期有效（默认 30 分钟）
-   - Refresh Token 长期有效（默认 7 天）
-   - 实施 Token 黑名单（可选）
-
-4. **审计日志**
-   - 审计日志不可删除
-   - 定期归档旧日志
-   - 监控异常登录行为
-
-5. **权限控制**
-   - 遵循最小权限原则
-   - 定期审查用户权限
-   - 记录所有权限变更
-
----
-
-## 📚 相关文件
-
-- **配置**: `app/core/config.py`
-- **加密**: `app/core/encryption.py`
-- **安全**: `app/core/security.py`
-- **审计**: `app/core/audit.py`
-- **认证**: `app/api/v1/endpoints/auth.py`
-- **权限**: `app/auth/permissions.py`
-- **用户管理**: `app/api/v1/endpoints/user_management.py`
-- **审计日志**: `app/api/v1/endpoints/audit.py`
-- **迁移脚本**: `migrations/`
-
----
-
-## ❓ 常见问题
-
-### Q: 忘记密码怎么办？
-
-A: 目前需要管理员通过数据库重置。未来可添加邮件重置功能。
-
-```sql
--- 重置密码为 "newpassword123"
-UPDATE users 
-SET hashed_password = '$2b$12$...' -- 使用 bcrypt 生成哈希
-WHERE username = 'targetuser';
-```
-
-### Q: 如何添加新角色？
-
-A: 编辑 `app/domain/models/role.py` 中的 `UserRole` 枚举，并更新数据库约束。
-
-### Q: 审计日志占用太多空间？
-
-A: 建议定期归档旧日志到冷存储：
-
-```sql
--- 归档 90 天前的日志
-CREATE TABLE audit_logs_archive AS
-SELECT * FROM audit_logs WHERE timestamp < NOW() - INTERVAL '90 days';
-
-DELETE FROM audit_logs WHERE timestamp < NOW() - INTERVAL '90 days';
-```
-
----
-
-## 📞 技术支持
-
-如有问题，请查看：
-- 日志文件: `logs/`
-- 数据库表结构: `migrations/`
-- 单元测试: `tests/`
-

app/algorithms/__init__.py

@@ -1,30 +1,45 @@
-from app.algorithms.data_cleaning import flow_data_clean, pressure_data_clean
-from app.algorithms.sensors import (
-    pressure_sensor_placement_sensitivity,
-    pressure_sensor_placement_kmeans,
-)
-from app.algorithms.valve_isolation import valve_isolation_analysis
-from app.algorithms.simulations import (
-    convert_to_local_unit,
-    burst_analysis,
-    valve_close_analysis,
-    flushing_analysis,
-    contaminant_simulation,
-    age_analysis,
-    pressure_regulation,
-)
+"""Algorithm package with side-effect-free, lazy compatibility exports."""
 
-__all__ = [
-    "flow_data_clean",
-    "pressure_data_clean",
-    "pressure_sensor_placement_sensitivity",
-    "pressure_sensor_placement_kmeans",
-    "convert_to_local_unit",
-    "burst_analysis",
-    "valve_close_analysis",
-    "flushing_analysis",
-    "contaminant_simulation",
-    "age_analysis",
-    "pressure_regulation",
-    "valve_isolation_analysis",
-]
+from importlib import import_module
+from typing import Any
+
+
+_EXPORT_MODULES = {
+    "flow_data_clean": "app.algorithms.cleaning",
+    "pressure_data_clean": "app.algorithms.cleaning",
+    "pressure_sensor_placement_sensitivity": "app.algorithms.sensor",
+    "pressure_sensor_placement_kmeans": "app.algorithms.sensor",
+    "valve_isolation_analysis": "app.algorithms.isolation.valve",
+    "LeakageIdentifier": "app.algorithms.leakage",
+    "PipelineHealthAnalyzer": "app.algorithms.health",
+    "run_burst_location": "app.algorithms.burst_location",
+    **{
+        name: "app.algorithms.simulation.scenarios"
+        for name in (
+            "convert_to_local_unit",
+            "burst_analysis",
+            "valve_close_analysis",
+            "flushing_analysis",
+            "contaminant_simulation",
+            "age_analysis",
+            "pressure_regulation",
+        )
+    },
+}
+
+__all__ = list(_EXPORT_MODULES)
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_name = _EXPORT_MODULES[name]
+    except KeyError as exc:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__})

app/algorithms/_utils.py

@@ -0,0 +1,88 @@
+import os
+
+import pandas as pd
+
+
+def fill_time_gaps(
+    data: pd.DataFrame,
+    time_col: str = "time",
+    freq: str = "1min",
+    short_gap_threshold: int = 10,
+) -> pd.DataFrame:
+    """
+    补齐缺失时间戳并填补数据缺口。
+
+    Args:
+        data: 包含时间列的 DataFrame
+        time_col: 时间列名（默认 'time'）
+        freq: 重采样频率（默认 '1min'）
+        short_gap_threshold: 短缺口阈值（分钟），<=此值用线性插值，>此值用前向填充
+
+    Returns:
+        补齐时间后的 DataFrame（保留原时间列格式）
+    """
+    if time_col not in data.columns:
+        raise ValueError(f"时间列 '{time_col}' 不存在于数据中")
+
+    # 解析时间列并设为索引
+    data = data.copy()
+    data[time_col] = pd.to_datetime(data[time_col], utc=True)
+    data_indexed = data.set_index(time_col)
+
+    # 生成完整时间范围
+    full_range = pd.date_range(
+        start=data_indexed.index.min(), end=data_indexed.index.max(), freq=freq
+    )
+
+    # 重索引以补齐缺失时间点，同时保留原始时间戳
+    combined_index = data_indexed.index.union(full_range).sort_values().unique()
+    data_reindexed = data_indexed.reindex(combined_index)
+
+    # 按列处理缺口
+    for col in data_reindexed.columns:
+        # 识别缺失值位置
+        is_missing = data_reindexed[col].isna()
+
+        # 计算连续缺失的长度
+        missing_groups = (is_missing != is_missing.shift()).cumsum()
+        gap_lengths = is_missing.groupby(missing_groups).transform("sum")
+
+        # 短缺口：时间插值
+        short_gap_mask = is_missing & (gap_lengths <= short_gap_threshold)
+        if short_gap_mask.any():
+            data_reindexed.loc[short_gap_mask, col] = (
+                data_reindexed[col]
+                .interpolate(method="time", limit_area="inside")
+                .loc[short_gap_mask]
+            )
+
+        # 长缺口：前向填充
+        long_gap_mask = is_missing & (gap_lengths > short_gap_threshold)
+        if long_gap_mask.any():
+            data_reindexed.loc[long_gap_mask, col] = (
+                data_reindexed[col].ffill().loc[long_gap_mask]
+            )
+
+    # 重置索引并恢复时间列（保留原格式）
+    data_result = data_reindexed.reset_index()
+    data_result.rename(columns={"index": time_col}, inplace=True)
+
+    # 保留时区信息
+    data_result[time_col] = data_result[time_col].dt.strftime("%Y-%m-%dT%H:%M:%S%z")
+    # 修正时区格式（Python的%z输出为+0000，需转为+00:00）
+    data_result[time_col] = data_result[time_col].str.replace(
+        r"(\+\d{2})(\d{2})$", r"\1:\2", regex=True
+    )
+
+    return data_result
+
+
+def _cleanup_temp_files(prefix: str) -> None:
+    """清理 EPANET 仿真产生的临时文件。"""
+    for ext in [".inp", ".rpt", ".bin", ".out"]:
+        temp_file = prefix + ext
+        if os.path.exists(temp_file):
+            try:
+                os.remove(temp_file)
+            except OSError:
+                pass

app/algorithms/api_ex/__init__.py

@@ -1,3 +0,0 @@
-from .flow_data_clean import *
-from .pressure_data_clean import *
-from .pipeline_health_analyzer import *

app/algorithms/api_ex/pressure_data_clean.py

@@ -1,355 +0,0 @@
-import pandas as pd
-import numpy as np
-import matplotlib.pyplot as plt
-from sklearn.cluster import KMeans
-from sklearn.impute import SimpleImputer
-import os
-
-
-def fill_time_gaps(
-    data: pd.DataFrame,
-    time_col: str = "time",
-    freq: str = "1min",
-    short_gap_threshold: int = 10,
-) -> pd.DataFrame:
-    """
-    补齐缺失时间戳并填补数据缺口。
-
-    Args:
-        data: 包含时间列的 DataFrame
-        time_col: 时间列名（默认 'time'）
-        freq: 重采样频率（默认 '1min'）
-        short_gap_threshold: 短缺口阈值（分钟），<=此值用线性插值，>此值用前向填充
-
-    Returns:
-        补齐时间后的 DataFrame（保留原时间列格式）
-    """
-    if time_col not in data.columns:
-        raise ValueError(f"时间列 '{time_col}' 不存在于数据中")
-
-    # 解析时间列并设为索引
-    data = data.copy()
-    data[time_col] = pd.to_datetime(data[time_col], utc=True)
-    data_indexed = data.set_index(time_col)
-
-    # 生成完整时间范围
-    full_range = pd.date_range(
-        start=data_indexed.index.min(), end=data_indexed.index.max(), freq=freq
-    )
-
-    # 重索引以补齐缺失时间点，同时保留原始时间戳
-    combined_index = data_indexed.index.union(full_range).sort_values().unique()
-    data_reindexed = data_indexed.reindex(combined_index)
-
-    # 按列处理缺口
-    for col in data_reindexed.columns:
-        # 识别缺失值位置
-        is_missing = data_reindexed[col].isna()
-
-        # 计算连续缺失的长度
-        missing_groups = (is_missing != is_missing.shift()).cumsum()
-        gap_lengths = is_missing.groupby(missing_groups).transform("sum")
-
-        # 短缺口：时间插值
-        short_gap_mask = is_missing & (gap_lengths <= short_gap_threshold)
-        if short_gap_mask.any():
-            data_reindexed.loc[short_gap_mask, col] = (
-                data_reindexed[col]
-                .interpolate(method="time", limit_area="inside")
-                .loc[short_gap_mask]
-            )
-
-        # 长缺口：前向填充
-        long_gap_mask = is_missing & (gap_lengths > short_gap_threshold)
-        if long_gap_mask.any():
-            data_reindexed.loc[long_gap_mask, col] = (
-                data_reindexed[col].ffill().loc[long_gap_mask]
-            )
-
-    # 重置索引并恢复时间列（保留原格式）
-    data_result = data_reindexed.reset_index()
-    data_result.rename(columns={"index": time_col}, inplace=True)
-
-    # 保留时区信息
-    data_result[time_col] = data_result[time_col].dt.strftime("%Y-%m-%dT%H:%M:%S%z")
-    # 修正时区格式（Python的%z输出为+0000，需转为+00:00）
-    data_result[time_col] = data_result[time_col].str.replace(
-        r"(\+\d{2})(\d{2})$", r"\1:\2", regex=True
-    )
-
-    return data_result
-
-
-def clean_pressure_data_km(
-    input_csv_path: str, show_plot: bool = False, fill_gaps: bool = True
-) -> str:
-    """
-    读取输入 CSV，基于 KMeans 检测异常并用滚动平均修复。输出为 <input_basename>_cleaned.xlsx（同目录）。
-    原始数据在 sheet 'raw_pressure_data'，处理后数据在 sheet 'cleaned_pressusre_data'。
-    返回输出文件的绝对路径。
-
-    Args:
-        input_csv_path: CSV 文件路径
-        show_plot: 是否显示可视化
-        fill_gaps: 是否先补齐时间缺口（默认 True）
-    """
-    # 读取 CSV
-    input_csv_path = os.path.abspath(input_csv_path)
-    data = pd.read_csv(input_csv_path, header=0, index_col=None, encoding="utf-8")
-
-    # 补齐时间缺口（如果数据包含 time 列）
-    if fill_gaps and "time" in data.columns:
-        data = fill_time_gaps(
-            data, time_col="time", freq="1min", short_gap_threshold=10
-        )
-
-    # 分离时间列和数值列
-    time_col_data = None
-    if "time" in data.columns:
-        time_col_data = data["time"]
-        data = data.drop(columns=["time"])
-    # 标准化
-    data_norm = (data - data.mean()) / data.std()
-
-    # 聚类与异常检测
-    k = 3
-    kmeans = KMeans(n_clusters=k, init="k-means++", n_init=50, random_state=42)
-    clusters = kmeans.fit_predict(data_norm)
-    centers = kmeans.cluster_centers_
-
-    distances = np.linalg.norm(data_norm.values - centers[clusters], axis=1)
-    threshold = distances.mean() + 3 * distances.std()
-
-    anomaly_pos = np.where(distances > threshold)[0]
-    anomaly_indices = data.index[anomaly_pos]
-
-    anomaly_details = {}
-    for pos in anomaly_pos:
-        row_norm = data_norm.iloc[pos]
-        cluster_idx = clusters[pos]
-        center = centers[cluster_idx]
-        diff = abs(row_norm - center)
-        main_sensor = diff.idxmax()
-        anomaly_details[data.index[pos]] = main_sensor
-
-    # 修复：滚动平均（窗口可调）
-    data_rolled = data.rolling(window=13, center=True, min_periods=1).mean()
-    data_repaired = data.copy()
-    for pos in anomaly_pos:
-        label = data.index[pos]
-        sensor = anomaly_details[label]
-        data_repaired.loc[label, sensor] = data_rolled.loc[label, sensor]
-
-    # 可选可视化（使用位置作为 x 轴）
-    plt.rcParams["font.sans-serif"] = ["SimHei"]
-    plt.rcParams["axes.unicode_minus"] = False
-
-    if show_plot and len(data.columns) > 0:
-        n = len(data)
-        time = np.arange(n)
-        plt.figure(figsize=(12, 8))
-        for col in data.columns:
-            plt.plot(time, data[col].values, marker="o", markersize=3, label=col)
-        for pos in anomaly_pos:
-            sensor = anomaly_details[data.index[pos]]
-            plt.plot(pos, data.iloc[pos][sensor], "ro", markersize=8)
-        plt.xlabel("时间点（序号）")
-        plt.ylabel("压力监测值")
-        plt.title("各传感器折线图（红色标记主要异常点）")
-        plt.legend()
-        plt.show()
-
-        plt.figure(figsize=(12, 8))
-        for col in data_repaired.columns:
-            plt.plot(
-                time, data_repaired[col].values, marker="o", markersize=3, label=col
-            )
-        for pos in anomaly_pos:
-            sensor = anomaly_details[data.index[pos]]
-            plt.plot(pos, data_repaired.iloc[pos][sensor], "go", markersize=8)
-        plt.xlabel("时间点（序号）")
-        plt.ylabel("修复后压力监测值")
-        plt.title("修复后各传感器折线图（绿色标记修复值）")
-        plt.legend()
-        plt.show()
-
-    # 保存到 Excel：两个 sheet
-    input_dir = os.path.dirname(os.path.abspath(input_csv_path))
-    input_base = os.path.splitext(os.path.basename(input_csv_path))[0]
-    output_filename = f"{input_base}_cleaned.xlsx"
-    output_path = os.path.join(input_dir, output_filename)
-
-    # 如果原始数据包含时间列，将其添加回结果
-    data_for_save = data.copy()
-    data_repaired_for_save = data_repaired.copy()
-    if time_col_data is not None:
-        data_for_save.insert(0, "time", time_col_data)
-        data_repaired_for_save.insert(0, "time", time_col_data)
-
-    if os.path.exists(output_path):
-        os.remove(output_path)  # 覆盖同名文件
-    with pd.ExcelWriter(output_path, engine="openpyxl") as writer:
-        data_for_save.to_excel(writer, sheet_name="raw_pressure_data", index=False)
-        data_repaired_for_save.to_excel(
-            writer, sheet_name="cleaned_pressusre_data", index=False
-        )
-
-    # 返回输出文件的绝对路径
-    return os.path.abspath(output_path)
-
-
-def clean_pressure_data_df_km(data: pd.DataFrame, show_plot: bool = False) -> dict:
-    """
-    接收一个 DataFrame 数据结构，使用KMeans聚类检测异常并用滚动平均修复。
-    返回清洗后的字典数据结构。
-
-    Args:
-        data: 输入 DataFrame（可包含 time 列）
-        show_plot: 是否显示可视化
-    """
-    # 使用传入的 DataFrame
-    data = data.copy()
-
-    # 补齐时间缺口（如果启用且数据包含 time 列）
-    data_filled = fill_time_gaps(
-        data, time_col="time", freq="1min", short_gap_threshold=10
-    )
-
-    # 保存 time 列用于最后合并
-    time_col_series = None
-    if "time" in data_filled.columns:
-        time_col_series = data_filled["time"]
-
-    # 移除 time 列用于后续清洗
-    data_filled = data_filled.drop(columns=["time"])
-
-    # 标准化（使用填充后的数据）
-    data_norm = (data_filled - data_filled.mean()) / data_filled.std()
-
-    # 添加：处理标准化后的 NaN（例如，标准差为0的列），防止异常数据，时间段内所有数据都相同导致计算结果为 NaN
-    imputer = SimpleImputer(
-        strategy="constant", fill_value=0, keep_empty_features=True
-    )  # 用 0 填充 NaN，包括全 NaN，并保留空特征
-    data_norm = pd.DataFrame(
-        imputer.fit_transform(data_norm),
-        columns=data_norm.columns,
-        index=data_norm.index,
-    )
-
-    # 聚类与异常检测
-    k = 3
-    kmeans = KMeans(n_clusters=k, init="k-means++", n_init=50, random_state=42)
-    clusters = kmeans.fit_predict(data_norm)
-    centers = kmeans.cluster_centers_
-
-    distances = np.linalg.norm(data_norm.values - centers[clusters], axis=1)
-    threshold = distances.mean() + 3 * distances.std()
-
-    anomaly_pos = np.where(distances > threshold)[0]
-    anomaly_indices = data_filled.index[anomaly_pos]
-
-    anomaly_details = {}
-    for pos in anomaly_pos:
-        row_norm = data_norm.iloc[pos]
-        cluster_idx = clusters[pos]
-        center = centers[cluster_idx]
-        diff = abs(row_norm - center)
-        main_sensor = diff.idxmax()
-        anomaly_details[data_filled.index[pos]] = main_sensor
-
-    # 修复：滚动平均（窗口可调）
-    data_rolled = data_filled.rolling(window=13, center=True, min_periods=1).mean()
-    data_repaired = data_filled.copy()
-    for pos in anomaly_pos:
-        label = data_filled.index[pos]
-        sensor = anomaly_details[label]
-        data_repaired.loc[label, sensor] = data_rolled.loc[label, sensor]
-
-    # 可选可视化（使用位置作为 x 轴）
-    plt.rcParams["font.sans-serif"] = ["SimHei"]
-    plt.rcParams["axes.unicode_minus"] = False
-
-    if show_plot and len(data.columns) > 0:
-        n = len(data)
-        time = np.arange(n)
-        n_filled = len(data_filled)
-        time_filled = np.arange(n_filled)
-        plt.figure(figsize=(12, 8))
-        for col in data.columns:
-            plt.plot(
-                time, data[col].values, marker="o", markersize=3, label=col, alpha=0.5
-            )
-        for col in data_filled.columns:
-            plt.plot(
-                time_filled,
-                data_filled[col].values,
-                marker="x",
-                markersize=3,
-                label=f"{col}_filled",
-                linestyle="--",
-            )
-        for pos in anomaly_pos:
-            sensor = anomaly_details[data_filled.index[pos]]
-            plt.plot(pos, data_filled.iloc[pos][sensor], "ro", markersize=8)
-        plt.xlabel("时间点（序号）")
-        plt.ylabel("压力监测值")
-        plt.title("各传感器折线图（红色标记主要异常点，虚线为0值填充后）")
-        plt.legend()
-        plt.show()
-
-        plt.figure(figsize=(12, 8))
-        for col in data_repaired.columns:
-            plt.plot(
-                time_filled, data_repaired[col].values, marker="o", markersize=3, label=col
-            )
-        for pos in anomaly_pos:
-            sensor = anomaly_details[data_filled.index[pos]]
-            plt.plot(pos, data_repaired.iloc[pos][sensor], "go", markersize=8)
-        plt.xlabel("时间点（序号）")
-        plt.ylabel("修复后压力监测值")
-        plt.title("修复后各传感器折线图（绿色标记修复值）")
-        plt.legend()
-        plt.show()
-
-    # 将 time 列添加回结果
-    if time_col_series is not None:
-        data_repaired.insert(0, "time", time_col_series)
-
-    # 返回清洗后的字典
-    return data_repaired
-
-
-# 测试
-# if __name__ == "__main__":
-#     # 默认使用脚本目录下的 pressure_raw_data.csv
-#     script_dir = os.path.dirname(os.path.abspath(__file__))
-#     default_csv = os.path.join(script_dir, "pressure_raw_data.csv")
-#     out_path = clean_pressure_data_km(default_csv, show_plot=False)
-#     print("保存路径：", out_path)
-
-# 测试 clean_pressure_data_dict_km 函数
-if __name__ == "__main__":
-    import random
-
-    # 读取 szh_pressure_scada.csv 文件
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    csv_path = os.path.join(script_dir, "szh_pressure_scada.csv")
-    data = pd.read_csv(csv_path, header=0, index_col=None, encoding="utf-8")
-
-    # 排除 Time 列，随机选择 5 列
-    columns_to_exclude = ["Time"]
-    available_columns = [col for col in data.columns if col not in columns_to_exclude]
-    selected_columns = random.sample(available_columns, 5)
-
-    # 将选中的列转换为字典
-    data_dict = {col: data[col].tolist() for col in selected_columns}
-
-    print("选中的列:", selected_columns)
-    print("原始数据长度:", len(data_dict[selected_columns[0]]))
-
-    # 调用函数进行清洗
-    cleaned_dict = clean_pressure_data_df_km(data_dict, show_plot=True)
-
-    print("清洗后的字典键:", list(cleaned_dict.keys()))
-    print("清洗后的数据长度:", len(cleaned_dict[selected_columns[0]]))
-    print("测试完成：函数运行正常")

app/algorithms/api_ex/sensor_placement.py

@@ -1,557 +0,0 @@
-# 改进灵敏度法
-import networkx
-import numpy as np
-import pandas
-import wntr
-import pandas as pd
-import copy
-import matplotlib.pyplot as plt
-import networkx as nx
-from sklearn.cluster import KMeans
-from wntr.epanet.toolkit import EpanetException
-from numpy.linalg import slogdet
-import random
-from app.services.tjnetwork import *
-import app.services.project_info as project_info
-
-# 2025/03/12
-# Step1: 获取节点坐标
-def getCoor(wn: wntr.network.WaterNetworkModel) -> pandas.DataFrame:
-    """
-    获取管网模型的节点坐标
-    :param wn: 由wntr生成的模型
-    :return: 节点坐标
-    """
-    # site: pandas.Series
-    #   index：节点名称（wn.node_name_list）
-    #   values：每个节点的坐标，格式为 tuple（如 (x, y) 或 (x, y, z)）
-    site = wn.query_node_attribute('coordinates')
-    # Coor: pandas.Series
-    #   index：与site相同（节点名称）。
-    #   values：坐标转换为numpy.ndarray（如array([10.5, 20.3])）
-    Coor = site.apply(lambda x: np.array(x))  # 将节点坐标转换为numpy数组
-    # x, y: list[float]
-    x = []  # 存储所有节点的 x 坐标
-    y = []  # 存储所有节点的 y 坐标
-    for i in range(0, len(Coor)):
-        x.append(Coor.values[i][0])  # 将 x 坐标存入 x 列表。
-        y.append(Coor.values[i][1])  # 将 y 坐标存入 y 列表
-    # xy: dict[str, list], x、y 坐标的字典
-    xy = {'x': x, 'y': y}
-    # Coor_node: pandas.DataFrame, 存储节点 x, y 坐标的 DataFrame
-    Coor_node = pd.DataFrame(xy, index=wn.node_name_list, columns=['x', 'y'])
-    return Coor_node
-
-
-# 2025/03/12
-# Step2: KMeans 聚类
-# 将节点用kmeans根据坐标分为k组，存入字典g
-def kgroup(coor: pandas.DataFrame, knum: int) -> dict[int, list[str]]:
-    """
-    使用KMeans聚类，将节点坐标分组
-    :param coor: 存储所有节点的坐标数据
-    :param knum: 需要分成的聚类数
-    :return: 聚类结果字典
-    """
-    g = {}
-    # estimator: sklearn.cluster.KMeans,KMeans 聚类模型
-    estimator = KMeans(n_clusters=knum)
-    estimator.fit(coor)
-    # label_pred: numpy.ndarray（int）,每个点的类别标签
-    label_pred = estimator.labels_
-    for i in range(0, knum):
-        g[i] = coor[label_pred == i].index.tolist()
-    return g
-
-
-# 2025/03/12
-# Step3: wn_func类，水力计算
-# wn_func 主要用于计算：
-#     水力距离（hydraulic length）：即节点之间的水力阻力。
-#     灵敏度分析（sensitivity analysis）：用于优化测压点的布置。
-# 一些与水力相关的函数，包括 CtoS：求水力距离,stafun：求状态函数F
-# # diff：求F对P的导数，返回灵敏度矩阵A
-# # sensitivity：返回灵敏度和总灵敏度
-class wn_func(object):
-
-    # Step3.1: 初始化
-    def __init__(self, wn: wntr.network.WaterNetworkModel):
-        """
-        获取管网模型信息
-        :param wn: 由wntr生成的模型
-        """
-        # self.results: wntr.sim.results.SimulationResults,仿真结果，包含压力、流量、水头等数据
-        self.results = wntr.sim.EpanetSimulator(wn).run_sim()  # 存储运行结果
-        self.wn = wn
-        # self.q：pandas.DataFrame,管道流量，索引为时间步长，列为管道名称
-        self.q = self.results.link['flowrate']
-        # ReservoirIndex / Tankindex: list[str],水库 / 水箱节点名称列表
-        ReservoirIndex = wn.reservoir_name_list
-        Tankindex = wn.tank_name_list
-        # 删除水库节点，删除与直接水库相连的虚拟管道
-        # self.pipes: list[str],所有管道的名称
-        self.pipes = wn.pipe_name_list
-        # self.nodes: list[str],所有节点的名称
-        self.nodes = wn.node_name_list
-        # self.coordinates：pandas.Series,节点坐标，索引为节点名，值为 (x, y) 坐标的 tuple
-        self.coordinates = wn.query_node_attribute('coordinates')
-        # allpumps / allvalves: list[str],所有泵/阀门名称列表
-        allpumps = wn.pump_name_list
-        allvalves = wn.valve_name_list
-        # pumpstnode / pumpednode / valvestnode / valveednode: list[str],存储泵和阀门 起终点节点的名称
-        pumpstnode = []
-        pumpednode = []
-        valvestnode = []
-        valveednode = []
-        # Reservoirpipe / Reservoirednode: list[str],记录与水库相关的管道和节点
-        Reservoirpipe = []
-        Reservoirednode = []
-        for pump in allpumps:
-            pumpstnode.append(wn.links[pump].start_node.name)
-            pumpednode.append(wn.links[pump].end_node.name)
-        for valve in allvalves:
-            valvestnode.append(wn.links[valve].start_node.name)
-            valveednode.append(wn.links[valve].end_node.name)
-        for pipe in self.pipes:
-            if wn.links[pipe].start_node.name in ReservoirIndex:
-                Reservoirpipe.append(pipe)
-                Reservoirednode.append(wn.links[pipe].end_node.name)
-            if wn.links[pipe].start_node.name in Tankindex:
-                Reservoirpipe.append(pipe)
-                Reservoirednode.append(wn.links[pipe].end_node.name)
-            if wn.links[pipe].end_node.name in Tankindex:
-                Reservoirpipe.append(pipe)
-                Reservoirednode.append(wn.links[pipe].start_node.name)
-        # 泵的起终点、tank、reservoir
-        # self.delnodes: list[str],需要删除的节点（包括水库、泵、阀门连接的节点）
-        self.delnodes = list(
-            set(ReservoirIndex).union(Tankindex, pumpstnode, pumpednode, valvestnode, valveednode, Reservoirednode))
-        # 泵、起终点为tank、reservoir的管道
-        # self.delpipes: list[str],需要删除的管道（包括水库、泵、阀门连接的管道）
-        self.delpipes = list(set(wn.pump_name_list).union(wn.valve_name_list).union(Reservoirpipe))
-        self.pipes = [pipe for pipe in wn.pipe_name_list if pipe not in self.delpipes]
-        # self.L: list[float],所有管道的长度（以米为单位）
-        self.L = wn.query_link_attribute('length')[self.pipes].tolist()
-        self.n = len(self.nodes)
-        self.m = len(self.pipes)
-        # self.unit_headloss: list[float],单位水头损失（headloss 数据的第一行，单位：米/km）
-        self.unit_headloss = self.results.link['headloss'].iloc[0, :].tolist()
-        ##
-        self.delnodes1 = list(set(ReservoirIndex).union(Tankindex))
-
-    # Step3.2: 计算水力距离
-    def CtoS(self):
-        """
-        计算水力距离矩阵
-        :return:
-        """
-        # 水力距离：当行索引对应的节点为控制点时，列索引对应的节点距离控制点的（路径*水头损失）的最小值
-        # nodes：list[str]（节点名称）
-        nodes = copy.deepcopy(self.nodes)
-        # pipes：list[str]（管道名称）
-        pipes = self.pipes
-        wn = self.wn
-        # n / m：int（节点数 / 管道数）
-        n = self.n
-        m = self.m
-        s1 = [0] * m
-        q = self.q
-        L = self.L
-        # H1：pandas.DataFrame,水头数据，索引为时间步长，列为节点名
-        H1 = self.results.node['head'].T
-        # hh：list[float],计算管道两端水头之差
-        hh = []
-        # 水头损失
-        for p in pipes:
-            h1 = self.wn.links[p].start_node.name
-            h1 = H1.loc[str(h1)]
-            h2 = self.wn.links[p].end_node.name
-            h2 = H1.loc[str(h2)]
-            hh.append(abs(h1 - h2))
-        hh = np.array(hh)
-        # headloss：pandas.DataFrame,管道水头损失矩阵
-        headloss = pd.DataFrame(hh, index=pipes).T
-        # s1:管道阻力系数，s2：将管道阻力系数与管道的起始节点和终止节点对应
-        hf = pd.DataFrame(np.array([0] * (n ** 2)).reshape(n, n), index=nodes, columns=nodes, dtype=float)
-        weightL = pd.DataFrame(np.array([0] * (n ** 2)).reshape(n, n), index=nodes, columns=nodes, dtype=float)
-        # s2为对应管道起始节点与终止节点的粗糙度系数矩阵，index代表起始节点，columns代表终止节点
-        G = nx.DiGraph()
-        for i in range(0, m):
-            pipe = pipes[i]
-            a = wn.links[pipe].start_node.name
-            b = wn.links[pipe].end_node.name
-            if q.loc[0, pipe] > 0:
-                hf.loc[a, b] = headloss.loc[0, pipe]
-                weightL.loc[a, b] = headloss.loc[0, pipe] * L[i]
-                G.add_weighted_edges_from([(a, b, weightL.loc[a, b])])
-
-            else:
-                hf.loc[b, a] = headloss.loc[0, pipe]
-                weightL.loc[b, a] = headloss.loc[0, pipe] * L[i]
-                G.add_weighted_edges_from([(b, a, weightL.loc[b, a])])
-
-        hydraulicL = pd.DataFrame(np.array([0] * (n ** 2)).reshape(n, n), index=nodes, columns=nodes, dtype=float)
-
-        for a in nodes:
-            if a in G.nodes:
-                d = nx.shortest_path_length(G, source=a, weight='weight')
-                for b in list(d.keys()):
-                    hydraulicL.loc[a, b] = d[b]
-
-        hydraulicL = hydraulicL.drop(self.delnodes)
-        hydraulicL = hydraulicL.drop(self.delnodes, axis=1)
-
-        # 求加权水力距离
-        return hydraulicL, G
-
-    # Step3.3: 计算灵敏度矩阵
-    # 获取关系矩阵
-    def get_Conn(self):
-        """
-        计算管网连接关系矩阵
-        :return:
-        """
-        m = self.wn.num_links
-        n = self.wn.num_nodes
-        p = self.wn.num_pumps
-        v = self.wn.num_valves
-
-        self.nonjunc_index = []
-        self.non_link_index = []
-        for r in self.wn.reservoirs():
-            self.nonjunc_index.append(r[0])
-        for t in self.wn.tanks():
-            self.nonjunc_index.append(t[0])
-        # Conn：numpy.matrix，节点-管道连接矩阵，起点 -1，终点 1
-        Conn = np.mat(np.zeros([n, m - p - v]))  # 节点和管道的关系矩阵，行为节点，列为管道，起点为-1，终点为1
-        # NConn：numpy.matrix，节点-节点连接矩阵，有管道相连的地方设为 1
-        NConn = np.mat(np.zeros([n, n]))  # 节点之间的关系，之间有管道为1，反之为0
-        # pipes：list[str]，去除泵和阀门的管道列表
-        pipes = [pipe for pipe in self.wn.pipes() if pipe not in self.wn.pumps() and pipe not in self.wn.valves()]
-        for pipe_name, pipe in pipes:
-            start = self.wn.node_name_list.index(pipe.start_node_name)
-            end = self.wn.node_name_list.index(pipe.end_node_name)
-            p_index = self.wn.link_name_list.index(pipe_name)
-            Conn[start, p_index] = -1
-            Conn[end, p_index] = 1
-            NConn[start, end] = 1
-            NConn[end, start] = 1
-        self.A = Conn
-        link_name_list = [link for link in self.wn.link_name_list if
-                          link not in self.wn.pump_name_list and link not in self.wn.valve_name_list]
-        self.A2 = pd.DataFrame(self.A, index=self.wn.node_name_list, columns=link_name_list)
-        self.A2 = self.A2.drop(self.delnodes)
-        for pipe in self.delpipes:
-            if pipe not in self.wn.pump_name_list and pipe not in self.wn.valve_name_list:
-                self.A2 = self.A2.drop(columns=pipe)
-        self.junc_list = self.A2.index
-        self.A2 = np.mat(self.A2)  # 节点管道关系
-        self.A3 = NConn
-
-    def Jaco(self, hL: pandas.DataFrame):
-        """
-        计算灵敏度矩阵（节点压力对粗糙度变化的响应）
-        :param hL: 水力距离矩阵
-        :return:
-        """
-        # global result
-        # A：numpy.matrix, 节点-管道关系矩阵
-        A = self.A2
-        wn = self.wn
-
-        try:
-            result = wntr.sim.EpanetSimulator(wn).run_sim()
-        except EpanetException:
-            pass
-        finally:
-            h = result.link['headloss'][self.pipes].values[0]
-            q = result.link['flowrate'][self.pipes].values[0]
-            l = self.wn.query_link_attribute('length')[self.pipes]
-            C = self.wn.query_link_attribute('roughness')[self.pipes]
-            # headloss：numpy.ndarray,水头损失数组
-            headloss = np.array(h)
-            # 调整流量方向
-            for i in range(0, len(q)):
-                if q[i] < 0:
-                    A[:, i] = -A[:, i]
-            # q：numpy.ndarray,流量数组
-            q = np.abs(q)
-            # 两个灵敏度矩阵
-            # B / S：numpy.matrix,灵敏度计算的中间矩阵
-            B = np.mat(np.diag(q / ((1.852 * headloss) + 1e-10)))
-            S = np.mat(np.diag(q / C))
-            # X：numpy.matrix, 灵敏度矩阵
-            X = A * B * A.T
-            try:
-                det = np.linalg.det(X)
-            except RuntimeError as e:
-                sign, logdet = slogdet(X)   # 防止溢出
-                det = sign * np.exp(logdet)
-            if det != 0:
-                J_H_Cw = X.I * A * S
-                # J_H_Q = -X.I
-                J_q_Cw = S - B * A.T * X.I * A * S  # 去掉了delnodes和delpipes
-                # J_q_Q = B * A.T * X.I
-            else:  # 当X不可逆
-                J_H_Cw = np.linalg.pinv(X) @ A @ S
-                # J_H_Q = -np.linalg.pinv(X)
-                J_q_Cw = S - B * A.T * np.linalg.pinv(X) * A * S
-                # J_q_Q = B * A.T * np.linalg.pinv(X)
-
-            Sen_pressure = []
-            S_pressure = np.abs(J_H_Cw).sum(axis=1).tolist()  # 修改为绝对值
-            for ss in S_pressure:
-                Sen_pressure.append(ss[0])
-            # 求总灵敏度
-            SS_pressure = copy.deepcopy(hL)
-            for i in range(0, len(Sen_pressure)):
-                SS_pressure.iloc[i, :] = SS_pressure.iloc[i, :] * Sen_pressure[i]
-            SS = copy.deepcopy(hL)
-            for i in range(0, len(Sen_pressure)):
-                SS.iloc[i, :] = SS.iloc[i, :] * Sen_pressure[i]
-            # SS[i,j]:节点nodes[i]的灵敏度*该节点到nodes[j]的水力距离
-            return SS
-
-
-# 2025/03/12
-# Step4: 传感器布置优化
-# Sensorplacement
-# weight：分配权重
-# sensor：传感器布置的位置
-class Sensorplacement(wn_func):
-    """
-    Sensorplacement 类继承了 wn_func 类，并且用于计算和优化传感器布置的位置。
-    """
-    def __init__(self, wn: wntr.network.WaterNetworkModel, sensornum: int):
-        """
-
-        :param wn: 由wntr生成的模型
-        :param sensornum: 传感器的数量
-        """
-        wn_func.__init__(self, wn)
-        self.sensornum = sensornum
-
-    # 1.某个节点到所有节点的加权距离之和
-    # 2.某个节点到该组内所有节点的加权距离之和
-    def sensor(self, SS: pandas.DataFrame, G: networkx.Graph, group: dict[int, list[str]]):
-        """
-        sensor 方法是用来根据灵敏度矩阵 SS 和加权图 G 来确定传感器布置位置的
-        :param SS: 灵敏度矩阵，每个节点的行和列代表不同节点，矩阵元素表示节点间的灵敏度。SS.iloc[i, :] 表示第 i 行对应节点 i 到所有其他节点的灵敏度
-        :param G: 加权图，表示管网的拓扑结构，每个节点通过管道连接。图的边的权重通常是根据水力距离或者流量等计算的
-        :param group: 节点分组，字典的键是分组编号，值是该组的节点名称列表
-        :return:
-        """
-        # 传感器布置个数以及位置
-        # W = self.weight()
-        n = self.n - len(self.delnodes)
-        nodes = copy.deepcopy(self.nodes)
-        for node in self.delnodes:
-            nodes.remove(node)
-        # sumSS：list[float],每个节点到其他节点的灵敏度之和。SS.iloc[i, :] 返回第 i 个节点与所有其他节点的灵敏度值，sum(SS.iloc[i, :]) 计算这些灵敏度值的总和。
-        sumSS = []
-        for i in range(0, n):
-            sumSS.append(sum(SS.iloc[i, :]))
-        # 一个整数范围，表示每个节点的索引，用作sumSS_ DataFrame的索引
-        indices = range(0, n)
-        # sumSS_：pandas.DataFrame,将 sumSS 转换成 DataFrame 格式，并且将节点的总灵敏度保存到 CSV 文件 sumSS_data.csv 中
-        sumSS_ = pd.DataFrame(np.array(sumSS), index=indices)
-        sumSS_.to_csv('sumSS_data.csv')  # 存储节点总灵敏度
-        # sumSS：pandas.DataFrame,sumSS 被转换为 DataFrame 类型，并且按总灵敏度（即灵敏度之和）降序排列。此时，sumSS 是按节点的灵敏度之和排序的 DataFrame
-        sumSS = pd.DataFrame(np.array(sumSS), index=nodes)
-        sumSS = sumSS.sort_values(by=[0], ascending=[False])
-        # sensorindex：list[str],用于存储根据灵敏度排序选出的传感器位置的节点名称,存储根据总灵敏度排序的节点列表，用于传感器布置
-        sensorindex = []
-        # sensorindex_2：list[str],用于存储每组内根据灵敏度排序选出的传感器位置的节点名称,存储每个组内根据灵敏度排序选择的传感器节点
-        sensorindex_2 = []
-        # group_S：dict[int, pandas.DataFrame],存储每个组内的灵敏度矩阵
-        group_S = {}
-        # group_sumSS：dict[int, list[float]],存储每个组内节点的总灵敏度，值为每个组内节点灵敏度之和的列表
-        group_sumSS = {}
-        for i in range(0, len(group)):
-            for node in self.delnodes:
-                # 这里的group[i]是每个组的节点列表，代码首先去除已经被标记为删除的节点self.delnodes
-                if node in group[i]:
-                    group[i].remove(node)
-            group_S[i] = SS.loc[group[i], group[i]]
-            # 对每个组内的节点，计算组内节点的总灵敏度（group_sumSS[i]）。它将每个组内节点的灵敏度值相加，并且按灵敏度降序排序
-            group_sumSS[i] = []
-            for j in range(0, len(group[i])):
-                group_sumSS[i].append(sum(group_S[i].iloc[j, :]))
-            group_sumSS[i] = pd.DataFrame(np.array(group_sumSS[i]), index=group[i])
-            group_sumSS[i] = group_sumSS[i].sort_values(by=[0], ascending=[False])
-        pass
-
-        # 1.选sumSS最大的节点，然后把这个节点所在的那个组删掉，就可以不再从这个组选点。再重新排序选sumSS最大的;
-        # 2.在每组内选group_sumSS最大的节点
-        # 在这个循环中，首先选择灵敏度最高的节点Smaxnode并添加到sensorindex。然后根据灵敏度排序，删除已选的节点并继续选择下一个灵敏度最大的节点。这个过程用于选择传感器的位置
-        sensornum = self.sensornum
-        for i in range(0, sensornum):
-            # Smaxnode：str,最大灵敏度节点，sumSS.index[0] 表示灵敏度最高的节点
-            Smaxnode = sumSS.index[0]
-            sensorindex.append(Smaxnode)
-            sensorindex_2.append(group_sumSS[i].index[0])
-
-            for key, value in group.items():
-                if Smaxnode in value:
-                    sumSS = sumSS.drop(index=group[key])
-                    continue
-
-            sumSS = sumSS.sort_values(by=[0], ascending=[False])
-
-        return sensorindex, sensorindex_2
-
-
-# 2025/03/13
-def get_sensor_coord(name: str, sensor_num: int) -> dict[str, float]:
-    """
-    获取布置测压点的坐标,初始测压点布置根据灵敏度来布置，计算初始情况下的校准过程的error
-    :param name: 数据库名称
-    :param sensor_num: 测压点数目
-    :return: 测压点坐标字典
-    """
-    # inp_file_real：str,输入文件名，表示原始水力模型文件的路径,该文件格式为 EPANET 输入文件（.inp），包含管网的结构信息、节点、管道、泵等数据
-    inp_file_real = f'./db_inp/{name}.db.inp'
-    # sensornum：int,需要布置的传感器数量
-    # sensornum = sensor_num
-    # wn_real：wntr.network.WaterNetworkModel,加载 EPANET 水力模型
-    wn_real = wntr.network.WaterNetworkModel(inp_file_real)  # 真实粗糙度的原始管网
-    # sim_real：wntr.sim.EpanetSimulator,创建一个水力仿真器对象
-    sim_real = wntr.sim.EpanetSimulator(wn_real)
-    # results_real：wntr.sim.results.SimulationResults,运行仿真并返回结果
-    results_real = sim_real.run_sim()
-
-    # real_C：list[float]，包含所有管道粗糙度的列表
-    real_C = wn_real.query_link_attribute('roughness').tolist()
-    # wn_fun1：wn_func（继承自 object），创建 wn_func 类的实例，传入 wn_real 水力模型对象。wn_func 用于计算管网相关的水力属性，比如水力距离、灵敏度等
-    wn_fun1 = wn_func(wn_real)
-    # nodes：list[str]，管网的节点名称列表
-    nodes = wn_fun1.nodes
-    # delnodes：list[str]，被删除的节点（如水库、泵、阀门连接的节点等）
-    delnodes = wn_fun1.delnodes
-    # Coor_node：pandas.DataFrame
-    Coor_node = getCoor(wn_real)
-    Coor_node = Coor_node.drop(wn_fun1.delnodes)
-    nodes = [node for node in wn_fun1.nodes if node not in delnodes]
-    # coordinates：pandas.Series，存储所有节点的坐标，类型为 Series，索引为节点名称，值为 (x, y) 坐标对
-    coordinates = wn_fun1.coordinates
-
-    # 随机产生监测点
-    # junctionnum：int，nodes 的长度，表示节点的数量
-    junctionnum = len(nodes)
-    # random_numbers：list[int]，使用 random.sample 随机选择 sensornum（20）个节点的编号。它返回一个不重复的随机编号列表
-    # random_numbers = random.sample(range(junctionnum), sensor_num)
-    # for i in range(sensor_num):
-    #     # print(random_numbers[i])
-
-    wn_fun1.get_Conn()
-    # hL：pandas.DataFrame，水力距离矩阵，表示每个节点到其他节点的水力阻力
-    # G：networkx.DiGraph，加权有向图，表示管网的拓扑结构，节点之间的边带有权重
-    hL, G = wn_fun1.CtoS()
-    # SS：pandas.DataFrame，灵敏度矩阵，表示每个节点对管网变化（如粗糙度、流量等）的响应
-    SS = wn_fun1.Jaco(hL)
-    # group：dict[int, list[str]]，使用 kgroup 函数将节点按坐标分成若干组，每组包含的节点数不一定相同。group 是一个字典，键为分组编号，值为节点名列表
-    group = kgroup(Coor_node, sensor_num)
-    # wn_fun：Sensorplacement（继承自wn_func）
-    # 创建Sensorplacement类的实例，传入水力网络模型wn_real和传感器数量sensornum。Sensorplacement用于计算和布置传感器
-    wn_fun = Sensorplacement(wn_real, sensor_num)
-    wn_fun.__dict__.update(wn_fun1.__dict__)
-    # sensorindex：list[str]，初始传感器布置位置的节点名称
-    # sensorindex_2：list[str]，根据分组选择的传感器位置
-    sensorindex, sensorindex_2 = wn_fun.sensor(SS, G, group)  # 初始的sensorindex
-    # print(str(sensor_num), "个测压点，测压点位置：", sensorindex)
-    sensor_coord = {}
-    # 重新打开数据库
-    if is_project_open(name=name):
-        close_project(name=name)
-    open_project(name=name)
-    for node_id in sensorindex:
-        sensor_coord[node_id] = get_node_coord(name=name, node_id=node_id)
-    close_project(name=name)
-    # print(sensor_coord)
-    return sensor_coord
-
-
-if __name__ == '__main__':
-    sensor_coord = get_sensor_coord(name=project_info.name, sensor_num=20)
-    print(sensor_coord)
-    # '''
-    # 初始测压点布置根据灵敏度来布置，计算初始情况下的校准过程的error
-    # '''
-    #
-    # # inp_file_real：str,输入文件名，表示原始水力模型文件的路径,该文件格式为 EPANET 输入文件（.inp），包含管网的结构信息、节点、管道、泵等数据
-    # inp_file_real = './db_inp/bb.db.inp'
-    # # sensornum：int,需要布置的传感器数量
-    # sensornum = 20
-    # # wn_real：wntr.network.WaterNetworkModel,加载 EPANET 水力模型
-    # wn_real = wntr.network.WaterNetworkModel(inp_file_real)  # 真实粗糙度的原始管网
-    # # sim_real：wntr.sim.EpanetSimulator,创建一个水力仿真器对象
-    # sim_real = wntr.sim.EpanetSimulator(wn_real)
-    # # results_real：wntr.sim.results.SimulationResults,运行仿真并返回结果
-    # results_real = sim_real.run_sim()
-    #
-    # # real_C：list[float]，包含所有管道粗糙度的列表
-    # real_C = wn_real.query_link_attribute('roughness').tolist()
-    # # wn_fun1：wn_func（继承自 object），创建 wn_func 类的实例，传入 wn_real 水力模型对象。wn_func 用于计算管网相关的水力属性，比如水力距离、灵敏度等
-    # wn_fun1 = wn_func(wn_real)
-    # # nodes：list[str]，管网的节点名称列表
-    # nodes = wn_fun1.nodes
-    # # delnodes：list[str]，被删除的节点（如水库、泵、阀门连接的节点等）
-    # delnodes = wn_fun1.delnodes
-    # # Coor_node：pandas.DataFrame
-    # Coor_node = getCoor(wn_real)
-    # Coor_node = Coor_node.drop(wn_fun1.delnodes)
-    # nodes = [node for node in wn_fun1.nodes if node not in delnodes]
-    # # coordinates：pandas.Series，存储所有节点的坐标，类型为 Series，索引为节点名称，值为 (x, y) 坐标对
-    # coordinates = wn_fun1.coordinates
-    #
-    # # 随机产生监测点
-    # # junctionnum：int，nodes 的长度，表示节点的数量
-    # junctionnum = len(nodes)
-    # # random_numbers：list[int]，使用 random.sample 随机选择 sensornum（20）个节点的编号。它返回一个不重复的随机编号列表
-    # random_numbers = random.sample(range(junctionnum), sensornum)
-    # for i in range(sensornum):
-    #     print(random_numbers[i])
-    #
-    # wn_fun1.get_Conn()
-    # # hL：pandas.DataFrame，水力距离矩阵，表示每个节点到其他节点的水力阻力
-    # # G：networkx.DiGraph，加权有向图，表示管网的拓扑结构，节点之间的边带有权重
-    # hL, G = wn_fun1.CtoS()
-    # # SS：pandas.DataFrame，灵敏度矩阵，表示每个节点对管网变化（如粗糙度、流量等）的响应
-    # SS = wn_fun1.Jaco(hL)
-    # # group：dict[int, list[str]]，使用 kgroup 函数将节点按坐标分成若干组，每组包含的节点数不一定相同。group 是一个字典，键为分组编号，值为节点名列表
-    # group = kgroup(Coor_node, sensornum)
-    # # wn_fun：Sensorplacement（继承自wn_func）
-    # # 创建Sensorplacement类的实例，传入水力网络模型wn_real和传感器数量sensornum。Sensorplacement用于计算和布置传感器
-    # wn_fun = Sensorplacement(wn_real, sensornum)
-    # wn_fun.__dict__.update(wn_fun1.__dict__)
-    # # sensorindex：list[str]，初始传感器布置位置的节点名称
-    # # sensorindex_2：list[str]，根据分组选择的传感器位置
-    # sensorindex, sensorindex_2 = wn_fun.sensor(SS, G, group)  # 初始的sensorindex
-    # print(str(sensornum), "个测压点，测压点位置：", sensorindex)
-
-    # # 分区画图
-    # colorlist = ['lightpink', 'coral', 'rosybrown', 'olive', 'powderblue', 'lightskyblue', 'steelblue', 'peachpuff','brown','silver','indigo','lime','gold','violet','maroon','navy','teal','magenta','cyan',
-    #              'burlywood', 'tan', 'slategrey', 'thistle', 'lightseagreen', 'lightgreen', 'red','blue','yellow','orange','purple','grey','green','pink','lightblue','beige','chartreuse','turquoise','lavender','fuchsia','coral']
-    # G = wn_real.to_graph()
-    # G = G.to_undirected()  # 变为无向图
-    # pos = nx.get_node_attributes(G, 'pos')
-    # pass
-    # for i in range(0, sensornum):
-    #     ax = plt.gca()
-    #     ax.set_title(inp_file_real + str(sensornum))
-    #     nodes = nx.draw_networkx_nodes(G, pos, nodelist=group[i], node_color=colorlist[i], node_size=20)
-    # nodes = nx.draw_networkx_nodes(G, pos,
-    #                                nodelist=sensorindex_2, node_color='black', node_size=70, node_shape='*'
-    #                                )
-    # edges = nx.draw_networkx_edges(G, pos)
-    # ax.spines['top'].set_visible(False)
-    # ax.spines['right'].set_visible(False)
-    # ax.spines['bottom'].set_visible(False)
-    # ax.spines['left'].set_visible(False)
-    # plt.savefig(inp_file_real + str(sensornum) + ".png")
-    # plt.show()
-    #
-    # wntr.graphics.plot_network(wn_real, node_attribute=sensorindex_2, node_size=50, node_labels=False,
-    #                            title=inp_file_real + '_Projetion' + str(sensornum))
-    # plt.savefig(inp_file_real + '_S' + str(sensornum) + ".png")
-    # plt.show()

app/algorithms/burst_detection/__init__.py

@@ -0,0 +1,3 @@
+from app.algorithms.burst_detection.burst_detector import BurstDetector
+
+__all__ = ["BurstDetector"]

app/algorithms/burst_detection/burst_detector.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from scipy.fft import fft, ifft
+from sklearn.ensemble import IsolationForest
+
+PressureDataInput = (
+    pd.DataFrame
+    | dict[str, list[Any]]
+    | list[dict[str, Any]]
+    | list[list[Any]]
+    | np.ndarray
+)
+IGNORED_OBSERVATION_COLUMNS = {"time", "timestamp", "datetime", "date"}
+
+
+class BurstDetector:
+    """FFT + IsolationForest based burst detection for daily aligned pressure data."""
+
+    def __init__(
+        self,
+        *,
+        mu: int = 100,
+        points_per_day: int = 1440,
+        iforest_params: dict[str, Any] | None = None,
+    ) -> None:
+        if points_per_day <= 0:
+            raise ValueError("points_per_day 必须大于 0。")
+        if mu <= 0:
+            raise ValueError("mu 必须大于 0。")
+
+        self.mu = int(mu)
+        self.points_per_day = int(points_per_day)
+        self.iforest_params = {
+            "n_estimators": 50,
+            "random_state": 42,
+            "contamination": "auto",
+        }
+        if iforest_params:
+            self.iforest_params.update(iforest_params)
+
+        self.data: np.ndarray | None = None
+        self.sensor_names: list[str] = []
+        self.high_freq_features: np.ndarray | None = None
+
+    def load_data(
+        self,
+        data_source: PressureDataInput,
+        *,
+        sensor_nodes: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """
+        标准化输入观测数据为 DataFrame。
+
+        支持的 `data_source` 格式：
+        - `pd.DataFrame`
+          每一列代表一个传感器，每一行代表一个时间点。
+        - `dict[str, list[Any]]`
+          键为传感器 ID，值为该传感器按时间顺序排列的压力序列。
+          例如：`{"J1": [101.2, 101.0], "J2": [99.8, 99.7]}`。
+        - `list[dict[str, Any]]`
+          每个字典代表一个时间点，键为传感器 ID，值为该时刻压力。
+          例如：`[{"J1": 101.2, "J2": 99.8}, {"J1": 101.0, "J2": 99.7}]`。
+        - `list[list[Any]]`
+          二维列表，格式为 `(时间点数, 传感器数)`。
+          例如：`[[101.2, 99.8], [101.0, 99.7]]`。
+        - `np.ndarray`
+          二维数组，形状必须为 `(时间点数, 传感器数)`。
+
+        参数：
+        - `sensor_nodes`:
+          可选的传感器列筛选列表。传入后，数据中必须包含这些列名。
+
+        返回：
+        - 标准化后的 `pd.DataFrame`，列为传感器，行为时间点。
+        """
+        if isinstance(data_source, np.ndarray):
+            observation_df = pd.DataFrame(data_source)
+        elif isinstance(data_source, pd.DataFrame):
+            observation_df = data_source.copy()
+        else:
+            observation_df = pd.DataFrame(data_source)
+
+        return self._normalize_observation_frame(
+            observation_df=observation_df, sensor_nodes=sensor_nodes
+        )
+
+    def process(
+        self,
+        observed_pressure_data: PressureDataInput,
+        *,
+        sensor_nodes: list[str] | None = None,
+    ) -> np.ndarray:
+        """
+        对输入压力序列按天切片，并提取每天末时刻的高频特征。
+
+        `observed_pressure_data` 的格式与 `load_data()` 一致，统一要求：
+        - 数据必须表示为“行=时间点、列=传感器”。
+        - 总行数必须是 `points_per_day` 的整数倍。
+        - 至少需要 2 天数据，即总行数 `>= 2 * points_per_day`。
+
+        例如：
+        - 当 `points_per_day=1440` 时，15 天数据的形状通常为 `(21600, 传感器数)`。
+        - 若传入 `sensor_nodes=["J1", "J2"]`，则输入中必须存在 `J1/J2` 两列。
+
+        返回：
+        - `np.ndarray`，形状为 `(天数, 传感器数)`，
+          每个值表示对应传感器在当天末时刻提取出的高频分量。
+        """
+        observation_df = self.load_data(
+            observed_pressure_data,
+            sensor_nodes=sensor_nodes,
+        )
+        matrix = observation_df.to_numpy(dtype=float)
+        total_points, sensor_count = matrix.shape
+        if sensor_count == 0:
+            raise ValueError("压力观测数据中未找到可用传感器列。")
+        if total_points < self.points_per_day * 2:
+            raise ValueError("至少需要 2 天的观测数据才能执行爆管侦测。")
+        if total_points % self.points_per_day != 0:
+            raise ValueError("观测数据长度必须能被每日采样点数整除，以便按天切分。")
+
+        day_count = total_points // self.points_per_day
+        high_freq_features = np.zeros((day_count, sensor_count), dtype=float)
+
+        for sensor_idx in range(sensor_count):
+            sensor_series = matrix[:, sensor_idx]
+            for day_idx in range(day_count):
+                start = day_idx * self.points_per_day
+                end = (day_idx + 1) * self.points_per_day
+                day_data = sensor_series[start:end]
+                mirrored_data = np.concatenate([day_data, day_data[::-1]])
+                transformed = fft(mirrored_data)
+                transformed[self.mu : len(mirrored_data) - self.mu + 1] = 0
+                low_freq = ifft(transformed).real
+                high_freq = day_data - low_freq[: self.points_per_day]
+                high_freq_features[day_idx, sensor_idx] = float(high_freq[-1])
+
+        self.data = matrix
+        self.sensor_names = [str(column) for column in observation_df.columns]
+        self.high_freq_features = high_freq_features
+        return high_freq_features
+
+    def detect(self) -> pd.DataFrame:
+        if self.high_freq_features is None:
+            raise ValueError("特征未提取。请先调用 process()。")
+
+        day_count = self.high_freq_features.shape[0]
+        if day_count < 2:
+            raise ValueError("孤立森林至少需要 2 天特征数据。")
+
+        clf = IsolationForest(
+            n_estimators=self.iforest_params.get("n_estimators", 50),
+            max_samples=day_count,
+            random_state=self.iforest_params.get("random_state", 42),
+            contamination=self.iforest_params.get("contamination", "auto"),
+            **{
+                key: value
+                for key, value in self.iforest_params.items()
+                if key not in {"n_estimators", "random_state", "contamination"}
+            },
+        )
+        clf.fit(self.high_freq_features)
+
+        scores = clf.decision_function(self.high_freq_features)
+        predictions = clf.predict(self.high_freq_features)
+        result_df = pd.DataFrame(
+            {
+                "Day": range(1, day_count + 1),
+                "Score": scores.astype(float),
+                "Prediction": predictions.astype(int),
+            }
+        )
+        result_df["IsBurst"] = result_df["Prediction"].eq(-1)
+        result_df.attrs["sensor_nodes"] = self.sensor_names.copy()
+        result_df.attrs["high_freq_features"] = self.high_freq_features.copy()
+        result_df.attrs["day_count"] = day_count
+        result_df.attrs["points_per_day"] = self.points_per_day
+        result_df.attrs["sample_count"] = (
+            int(self.data.shape[0]) if self.data is not None else 0
+        )
+        return result_df
+
+    def run_detection(
+        self,
+        observed_pressure_data: PressureDataInput,
+        *,
+        sensor_nodes: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """
+        执行完整爆管侦测流程。
+
+        输入格式与 `process()` 相同：
+        - `DataFrame` / `dict[str, list[Any]]` / `list[dict[str, Any]]` / `list[list[Any]]` / `np.ndarray`
+        - 行表示时间点，列表示传感器
+        - 总行数必须能被 `points_per_day` 整除
+
+        返回结果包含列：
+        - `Day`: 第几天（从 1 开始）
+        - `Score`: IsolationForest 异常分数，越小越异常
+        - `Prediction`: `-1` 表示异常，`1` 表示正常
+        - `IsBurst`: 是否判定为异常日
+        """
+        self.process(observed_pressure_data, sensor_nodes=sensor_nodes)
+        return self.detect()
+
+    @staticmethod
+    def _normalize_observation_frame(
+        *,
+        observation_df: pd.DataFrame,
+        sensor_nodes: list[str] | None,
+    ) -> pd.DataFrame:
+        if observation_df.empty:
+            raise ValueError("压力观测数据为空。")
+
+        normalized_df = observation_df.copy()
+        normalized_df.columns = [str(column) for column in normalized_df.columns]
+        normalized_df = normalized_df.drop(
+            columns=[
+                column
+                for column in normalized_df.columns
+                if column.lower() in IGNORED_OBSERVATION_COLUMNS
+                or column.lower().startswith("unnamed:")
+            ],
+            errors="ignore",
+        )
+
+        if sensor_nodes:
+            selected_columns = [str(node) for node in sensor_nodes]
+            missing_columns = [
+                column
+                for column in selected_columns
+                if column not in normalized_df.columns
+            ]
+            if missing_columns:
+                preview = ", ".join(missing_columns[:10])
+                raise ValueError(f"观测数据缺少传感器列: {preview}")
+            normalized_df = normalized_df.loc[:, selected_columns]
+        else:
+            candidate_df = normalized_df.apply(pd.to_numeric, errors="coerce")
+            normalized_df = candidate_df.loc[:, candidate_df.notna().any(axis=0)]
+
+        if normalized_df.empty:
+            raise ValueError("未识别到可用的数值型压力观测列。")
+
+        normalized_df = normalized_df.apply(pd.to_numeric, errors="coerce")
+        invalid_columns = [
+            column
+            for column in normalized_df.columns
+            if normalized_df[column].isna().any()
+        ]
+        if invalid_columns:
+            preview = ", ".join(invalid_columns[:10])
+            raise ValueError(f"压力观测数据包含非数值或缺失值: {preview}")
+
+        return normalized_df.reset_index(drop=True)

app/algorithms/burst_location/__init__.py

@@ -0,0 +1,3 @@
+from .burst_location import run_burst_location
+
+__all__ = ["run_burst_location"]

app/algorithms/burst_location/burst_location.py

@@ -0,0 +1,342 @@
+import argparse
+import json
+import logging
+from multiprocessing import cpu_count
+from pathlib import Path
+from typing import Any, Iterable
+
+import pandas as pd
+
+from app.algorithms.burst_location import leak_simulator
+
+from .burst_locator import (
+    DN_search_multi_simple_add_flow_count_new,
+)
+from .network_model import (
+    _build_node_pipe_maps,
+    cal_node_coordinate,
+    construct_graph,
+    load_inp,
+    read_inf_inp,
+    read_inf_inp_other,
+)
+
+DEFAULT_N_WORKERS = max(1, min(cpu_count() - 1, 4))
+# DEFAULT_N_WORKERS = max(1, cpu_count() - 1)
+logger = logging.getLogger(__name__)
+
+
+def _read_id_list_json(path):
+    if path is None:
+        return None
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(data, list):
+        return [str(item) for item in data]
+    if isinstance(data, dict):
+        if "ids" in data and isinstance(data["ids"], list):
+            return [str(item) for item in data["ids"]]
+        raise ValueError(f"ID JSON must be list or dict with key 'ids': {path}")
+    raise ValueError(f"Unsupported ID JSON format: {path}")
+
+
+def _read_series_csv(path):
+    if path is None:
+        return None
+    df = pd.read_csv(path)
+    if df.shape[1] < 2:
+        raise ValueError(f"CSV must contain at least two columns (id,value): {path}")
+    if {"id", "value"}.issubset(df.columns):
+        id_col, value_col = "id", "value"
+    else:
+        id_col, value_col = df.columns[0], df.columns[1]
+    series = pd.Series(
+        df[value_col].values, index=df[id_col].astype(str).values, dtype=float
+    )
+    return series
+
+
+def _align_scada_series(
+    series: pd.Series, ids: Iterable[str], series_name: str
+) -> pd.Series:
+    ids = [str(item) for item in ids]
+    aligned = series.copy()
+    aligned.index = aligned.index.map(str)
+    missing_ids = [item for item in ids if item not in aligned.index]
+    if missing_ids:
+        preview = ", ".join(missing_ids[:10])
+        raise ValueError(f"{series_name} missing IDs: {preview}")
+    aligned = pd.to_numeric(aligned.loc[ids], errors="coerce")
+    invalid_ids = aligned[aligned.isna()].index.tolist()
+    if invalid_ids:
+        preview = ", ".join(invalid_ids[:10])
+        raise ValueError(
+            f"{series_name} contains non-numeric values for IDs: {preview}"
+        )
+    return aligned
+
+
+def _validate_flow_inputs(
+    flow_scada_ids: list[str] | None,
+    burst_flow: pd.Series | None,
+    normal_flow: pd.Series | None,
+) -> tuple[bool, list[str]]:
+    has_any_flow = any(
+        value is not None for value in [flow_scada_ids, burst_flow, normal_flow]
+    )
+    has_all_flow = all(
+        value is not None for value in [flow_scada_ids, burst_flow, normal_flow]
+    )
+    if has_any_flow and not has_all_flow:
+        raise ValueError(
+            "flow_scada_ids, burst_flow, and normal_flow must be provided together."
+        )
+
+    if not has_all_flow:
+        return False, []
+
+    flow_ids = [str(item) for item in (flow_scada_ids or [])]
+    if len(flow_ids) == 0:
+        raise ValueError("flow_scada_ids cannot be empty when flow data is provided.")
+    return True, flow_ids
+
+
+def _build_top_candidates(similarity_series: pd.Series) -> list[dict[str, Any]]:
+    top_series = similarity_series.iloc[:10]
+    return [
+        {"pipe_id": str(pipe_id), "similarity": float(score)}
+        for pipe_id, score in top_series.items()
+    ]
+
+
+def run_burst_location(
+    wn_inp_path: str,
+    pressure_scada_ids: list[str],
+    burst_pressure: pd.Series,
+    normal_pressure: pd.Series,
+    burst_leakage: float,
+    flow_scada_ids: list[str] | None = None,
+    burst_flow: pd.Series | None = None,
+    normal_flow: pd.Series | None = None,
+    min_dpressure: float = 2.0,
+    basic_pressure: float = 10.0,
+    n_workers: int = DEFAULT_N_WORKERS,
+    partition_on_full_graph: bool = True,
+    visualize_partition: bool = False,
+    visualize_pause_seconds: float = 0.3,
+    final_candidates_csv_path: (
+        str | None
+    ) = "temp/burst_location/final_round_candidates.csv",
+) -> dict[str, Any]:
+    if pressure_scada_ids is None or len(pressure_scada_ids) == 0:
+        raise ValueError("pressure_scada_ids cannot be empty.")
+    if burst_pressure is None or normal_pressure is None:
+        raise ValueError("burst_pressure and normal_pressure are required.")
+
+    has_all_flow, flow_ids = _validate_flow_inputs(
+        flow_scada_ids=flow_scada_ids,
+        burst_flow=burst_flow,
+        normal_flow=normal_flow,
+    )
+
+    inp_path = Path(wn_inp_path)
+    wn = load_inp(
+        inp_name=inp_path.name,
+        inp_location=str(inp_path.parent) + "/",
+        inp_time=0,
+        driven_mode="PDD",
+        require_p=float(basic_pressure),
+        minimum_p=0.0,
+    )
+
+    (
+        all_node,
+        _,
+        node_coordinates,
+        all_pipe,
+        _,
+        _,
+        pipe_length,
+        pipe_diameter,
+    ) = read_inf_inp(wn)
+
+    candidate_pipe, _ = leak_simulator.cal_possible_pipe(
+        burst_leakage, all_pipe, pipe_diameter
+    )
+
+    _, pipe_start_node_all, pipe_end_node_all = read_inf_inp_other(wn)
+    node_x, node_y = cal_node_coordinate(all_node, node_coordinates)
+    G0 = construct_graph(wn)
+    node_pipe_dic, couple_node_length = _build_node_pipe_maps(
+        all_node,
+        all_pipe,
+        pipe_start_node_all,
+        pipe_end_node_all,
+        pipe_length,
+    )
+    all_node_series = pd.Series(range(len(all_node)), index=all_node)
+
+    pressure_ids = [str(item) for item in pressure_scada_ids]
+    normal_pressure_aligned = _align_scada_series(
+        normal_pressure, pressure_ids, "normal_pressure"
+    )
+    burst_pressure_aligned = _align_scada_series(
+        burst_pressure, pressure_ids, "burst_pressure"
+    )
+    pressure_normal = normal_pressure_aligned.to_frame().T
+    pressure_monitor = burst_pressure_aligned.to_frame().T
+    pressure_predict = pressure_normal.copy()
+    timestep_list = list(pressure_normal.index)
+
+    if has_all_flow:
+        normal_flow_aligned = _align_scada_series(normal_flow, flow_ids, "normal_flow")
+        burst_flow_aligned = _align_scada_series(burst_flow, flow_ids, "burst_flow")
+        flow_normal = normal_flow_aligned.to_frame().T
+        flow_monitor = burst_flow_aligned.to_frame().T
+        flow_predict = flow_normal.copy()
+        similarity_mode = "CDF"
+        max_flow = flow_normal.iloc[0, :].abs()
+    else:
+        flow_normal = pd.DataFrame(index=timestep_list)
+        flow_monitor = pd.DataFrame(index=timestep_list)
+        flow_predict = pd.DataFrame(index=timestep_list)
+        similarity_mode = "CAD_new_gy"
+        max_flow = pd.Series(dtype=float)
+
+    stage_timing: dict[str, Any] = {}
+    try:
+        (
+            located_pipe,
+            elapsed_seconds,
+            simulation_times,
+            _,
+            similarity_series,
+            exit_condition,
+            final_candidates_csv,
+        ) = DN_search_multi_simple_add_flow_count_new(
+            wn=wn,
+            wn_inp_path=str(inp_path),
+            G0=G0,
+            all_node=all_node,
+            node_x=node_x,
+            node_y=node_y,
+            pipe_start_node_all=pipe_start_node_all,
+            pipe_end_node_all=pipe_end_node_all,
+            pipe_diameter=pipe_diameter,
+            couple_node_length=couple_node_length,
+            node_pipe_dic=node_pipe_dic,
+            all_node_series=all_node_series,
+            top_group_ratio=0.3,
+            top_pipe_num_max=80,
+            top_pipe_num_min=10,
+            candidate_pipe_input_initial=candidate_pipe,
+            similarity_mode=similarity_mode,
+            pressure_monitor=pressure_monitor,
+            pressure_predict=pressure_predict,
+            pressure_normal=pressure_normal,
+            pressure_leak_all=None,
+            flow_monitor=flow_monitor,
+            flow_predict=flow_predict,
+            flow_normal=flow_normal,
+            flow_leak_all=None,
+            timestep_list=timestep_list,
+            max_flow=max_flow,
+            group_basic_num=30,
+            Top_sensor_num=min(5, len(pressure_ids)),
+            if_gy=0,
+            pressure_threshold=float(min_dpressure),
+            leak_mag=float(burst_leakage),
+            n_workers=max(1, int(n_workers)),
+            stage_timing=stage_timing,
+            partition_on_full_graph=partition_on_full_graph,
+            visualize_partition=visualize_partition,
+            visualize_pause_seconds=visualize_pause_seconds,
+            final_candidates_csv_path=final_candidates_csv_path,
+        )
+    except Exception as exc:
+        logger.exception("Burst location algorithm execution failed.")
+        raise RuntimeError(f"Failed to run burst location algorithm: {exc}") from exc
+
+    return {
+        "located_pipe": located_pipe,
+        "burst_leakage": float(burst_leakage),
+        "elapsed_seconds": elapsed_seconds,
+        "simulation_times": int(simulation_times),
+        "top_candidates": _build_top_candidates(similarity_series),
+        "similarity_mode": similarity_mode,
+        "exit_condition": exit_condition,
+        "final_candidates_csv": final_candidates_csv,
+        "stage_timing_seconds": stage_timing,
+    }
+
+
+def _parse_args():
+    parser = argparse.ArgumentParser(description="爆管定位主函数入口")
+    parser.add_argument("--wn-inp", required=True, help="EPANET inp 文件路径")
+    parser.add_argument(
+        "--pressure-ids-json", required=True, help="压力SCADA ID列表 JSON 文件"
+    )
+    parser.add_argument(
+        "--flow-ids-json", default=None, help="（可选）流量SCADA ID列表 JSON 文件"
+    )
+    parser.add_argument(
+        "--burst-pressure-csv", required=True, help="爆管时压力 CSV（id,value）"
+    )
+    parser.add_argument(
+        "--normal-pressure-csv", required=True, help="正常时压力 CSV（id,value）"
+    )
+    parser.add_argument(
+        "--burst-flow-csv", default=None, help="（可选）爆管时流量 CSV（id,value）"
+    )
+    parser.add_argument(
+        "--normal-flow-csv", default=None, help="（可选）正常时流量 CSV（id,value）"
+    )
+    parser.add_argument(
+        "--burst-leakage", type=float, required=True, help="爆管漏损流量"
+    )
+    parser.add_argument(
+        "--min-dpressure",
+        type=float,
+        default=2.0,
+        help="（可选）最小压降阈值，默认 2.0",
+    )
+    parser.add_argument(
+        "--basic-pressure",
+        type=float,
+        default=10.0,
+        help="（可选）基础服务压力，默认 10.0",
+    )
+    parser.add_argument(
+        "--n-workers",
+        type=int,
+        default=DEFAULT_N_WORKERS,
+        help="（可选）特征中心模拟进程数，默认 max(1, min(cpu_count()-1, 4))",
+    )
+    parser.add_argument(
+        "--final-candidates-csv-path",
+        default="temp/burst_location/final_round_candidates.csv",
+        help="（可选）最后一轮候选管道明细 CSV 输出路径",
+    )
+    return parser.parse_args()
+
+
+def main():
+    args = _parse_args()
+    result = run_burst_location(
+        wn_inp_path=args.wn_inp,
+        pressure_scada_ids=_read_id_list_json(args.pressure_ids_json),
+        burst_pressure=_read_series_csv(args.burst_pressure_csv),
+        normal_pressure=_read_series_csv(args.normal_pressure_csv),
+        burst_leakage=args.burst_leakage,
+        flow_scada_ids=_read_id_list_json(args.flow_ids_json),
+        burst_flow=_read_series_csv(args.burst_flow_csv),
+        normal_flow=_read_series_csv(args.normal_flow_csv),
+        min_dpressure=args.min_dpressure,
+        basic_pressure=args.basic_pressure,
+        n_workers=args.n_workers,
+        final_candidates_csv_path=args.final_candidates_csv_path,
+    )
+    print(json.dumps(result, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

app/algorithms/burst_location/burst_locator.py

@@ -0,0 +1,772 @@
+"""爆管定位主模块。"""
+
+import copy
+import math
+import os
+import sys
+from datetime import datetime
+from time import perf_counter
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+from .leak_simulator import cal_signature_pipe_multi_pf
+from .network_partitioner import (
+    cal_group_num,
+    metis_grouping_pipe_weight,
+    visualize_metis_partition,
+)
+from .similarity_calculator import (
+    adjust_ratio,
+    cal_similarity_all_multi_new_sq_improve_double_lzr,
+    decode_mode,
+    extra_judge,
+    update_similarity,
+)
+
+
+def _ensure_signatures_for_centers(
+    wn,
+    wn_inp_path,
+    center_list,  # 本轮要用到的中心（list[str]）
+    pressure_leak_all,
+    flow_leak_all,  # 全量缓存（可为空 DF）
+    timestep_list,  # 你现有的时序列表
+    pressure_monitor,
+    flow_monitor,  # 用来推断传感器列名
+    leak_mag,
+    n_workers=1,
+):
+    """
+    只为缺失的中心补算 SLF（调用你现有的 cal_signature_pipe_multi_pf），
+    并把补算结果并回缓存。返回：
+      pressure_leak_subset, flow_leak_subset, pressure_leak_all_new, flow_leak_all_new
+    其中 subset 只包含 center_list 的行（顺序与 center_list 保持一致）。
+    """
+
+    center_list = _dedupe_preserve_order(center_list)
+
+    # 1) 推断传感器列名（与现有数据保持一致）
+    sensor_name_all = list(pressure_monitor.columns)
+    sensor_f_name_all = (
+        list(flow_monitor.columns)
+        if (flow_monitor is not None and hasattr(flow_monitor, "columns"))
+        else []
+    )
+
+    # 2) 取出缓存里已经有的中心（考虑 MultiIndex 的第 0 层为 pipe）
+    def _existing_pipes(df):
+        if df is None or len(df) == 0:
+            return set()
+        idx = df.index
+        if isinstance(idx, pd.MultiIndex):
+            return set(idx.get_level_values(0))
+        else:
+            return set(idx)
+
+    exist_p = _existing_pipes(pressure_leak_all)
+    need = [p for p in center_list if p not in exist_p]
+
+    # 3) 若有缺失中心，仅为这些中心补算一次
+    if len(need) > 0:
+        p_new, _ = cal_signature_pipe_multi_pf(
+            wn,
+            leak_mag,
+            need,
+            timestep_list,
+            sensor_name_all,
+            n_workers=n_workers,
+            wn_inp_path=wn_inp_path,
+        )
+        # 初始化空缓存时，做一次“同构化”
+        if pressure_leak_all is None or len(pressure_leak_all) == 0:
+            pressure_leak_all = p_new
+        else:
+            pressure_leak_all = pd.concat([pressure_leak_all, p_new], axis=0)
+        # if (flow_leak_all is None or len(flow_leak_all) == 0) and f_new is not None:
+        #     flow_leak_all = f_new
+        # elif f_new is not None:
+        #     flow_leak_all = pd.concat([flow_leak_all, f_new], axis=0)
+
+        # 去重（如果既有缓存里不小心有重复中心）
+        if isinstance(pressure_leak_all.index, pd.MultiIndex):
+            pressure_leak_all = pressure_leak_all[
+                ~pressure_leak_all.index.duplicated(keep="last")
+            ]
+            if flow_leak_all is not None and len(flow_leak_all) > 0:
+                flow_leak_all = flow_leak_all[
+                    ~flow_leak_all.index.duplicated(keep="last")
+                ]
+        else:
+            pressure_leak_all = pressure_leak_all[
+                ~pressure_leak_all.index.duplicated(keep="last")
+            ]
+            if flow_leak_all is not None and len(flow_leak_all) > 0:
+                flow_leak_all = flow_leak_all[
+                    ~flow_leak_all.index.duplicated(keep="last")
+                ]
+
+    # 4) 从更新后的缓存里，取出这轮需要的中心子集（顺序与 center_list 一致）
+    if isinstance(pressure_leak_all.index, pd.MultiIndex):
+        pressure_subset = pressure_leak_all.loc[center_list]
+        flow_subset = (
+            flow_leak_all.loc[center_list]
+            if (flow_leak_all is not None and len(flow_leak_all) > 0)
+            else None
+        )
+    else:
+        pressure_subset = pressure_leak_all.loc[center_list, :]
+        flow_subset = (
+            flow_leak_all.loc[center_list, :]
+            if (flow_leak_all is not None and len(flow_leak_all) > 0)
+            else None
+        )
+
+    return pressure_subset, flow_subset, pressure_leak_all, flow_leak_all
+
+
+def area_output_num_ki_improve(
+    candidate_center,
+    candidate_group,
+    similarity,
+    new_all_node,
+    top_group_ratio,
+    top_pipe_num_max,
+    top_pipe_num_min,
+    cut_ratio,
+):
+    final_area = []
+    final_center = []
+    all_node_iter = []
+    if similarity.index.is_unique == False:
+        total_center_num = len(set(similarity.index))
+    else:
+        total_center_num = len(similarity.index)
+
+    next_group_num = min(
+        total_center_num, math.ceil(total_center_num / cut_ratio * top_group_ratio)
+    )
+
+    for i in range(next_group_num):
+        top_center = similarity.index[i]
+        top_center_index = find_list_repeat(candidate_center, top_center)
+        for j in range(len(top_center_index)):
+            final_area = final_area + candidate_group[top_center_index[j]]
+            all_node_iter = all_node_iter + list(new_all_node[top_center_index[j]])
+        final_center.append(top_center)
+        final_area = sorted(set(final_area))
+
+    if len(final_area) > top_pipe_num_max:
+        if_end = 0
+    elif len(final_area) > top_pipe_num_min:
+        if_end = 1
+    elif total_center_num == next_group_num:
+        if_end = 1
+    else:
+        if_end = 1
+        for i in np.arange(next_group_num, total_center_num, 1):
+
+            before_list = copy.deepcopy(final_area)
+            top_center = similarity.index[i]
+            top_center_index = candidate_center.index(top_center)
+            temp_group = final_area + candidate_group[top_center_index]
+            temp_area = sorted(set(temp_group))
+
+            if len(temp_area) < top_pipe_num_min:
+
+                final_center.append(top_center)
+                all_node_iter = all_node_iter + list(new_all_node[top_center_index])
+                final_area = temp_area
+
+            elif len(temp_area) < top_pipe_num_max:
+                final_center.append(top_center)
+                all_node_iter = all_node_iter + list(new_all_node[top_center_index])
+                final_area = temp_area
+                break
+            else:
+                a = len(temp_area) - top_pipe_num_max
+                b = top_pipe_num_min - len(before_list)
+
+                if a >= b:
+                    final_area = before_list
+                else:
+                    final_center.append(top_center)
+                    all_node_iter = all_node_iter + list(new_all_node[top_center_index])
+                    final_area = temp_area
+                break
+
+    final_center = sorted(set(final_center))
+    all_node_iter = sorted(set(all_node_iter))
+    return final_area, final_center, all_node_iter, if_end
+
+
+def find_list_repeat(candidate_center, target):
+    repeated_list = []
+    for index, nums in enumerate(candidate_center):
+        if nums == target:
+            repeated_list.append(index)
+    return repeated_list
+
+
+def _dedupe_preserve_order(items):
+    seen = set()
+    output = []
+    for item in items:
+        if item in seen:
+            continue
+        seen.add(item)
+        output.append(item)
+    return output
+
+
+def _accumulate_stage(stage_timing, stage_name, started_at):
+    stage_timing[stage_name] = stage_timing.get(stage_name, 0.0) + (
+        perf_counter() - started_at
+    )
+
+
+def _write_last_round_candidates_csv(
+    csv_path,
+    exit_condition,
+    iteration_count,
+    similarity_mode,
+    candidate_details,
+    fallback_similarity,
+):
+    if not csv_path:
+        return None
+    timestamp_suffix = datetime.now().strftime("%Y%m%d_%H%M%S")
+    base_path, ext = os.path.splitext(csv_path)
+    ext = ext or ".csv"
+    output_path = f"{base_path}_{timestamp_suffix}{ext}"
+    if candidate_details is not None and len(candidate_details) > 0:
+        export_df = candidate_details.copy()
+        if export_df.index.name == "pipe_id":
+            export_df = export_df.reset_index()
+    else:
+        export_df = pd.DataFrame(
+            {
+                "pipe_id": [str(pipe_id) for pipe_id in fallback_similarity.index],
+                "final_similarity": [float(value) for value in fallback_similarity.values],
+            }
+        )
+    export_df["exit_condition"] = exit_condition
+    export_df["iterations"] = int(iteration_count)
+    export_df["similarity_mode"] = similarity_mode
+    parent_dir = os.path.dirname(output_path)
+    if parent_dir:
+        os.makedirs(parent_dir, exist_ok=True)
+    export_df.to_csv(output_path, index=False, encoding="utf-8-sig")
+    return output_path
+
+
+def cal_DtoTop1(
+    G0, pipe_leak, located_pipe, pipe_start_node_all, pipe_end_node_all, pipe_length
+):
+    if pipe_leak == located_pipe:
+        result_DtoTop1 = 0
+        result_DtoTop1_num = 0
+    else:
+        pipe_leak_start_node = pipe_start_node_all[pipe_leak]
+        pipe_leak_end_node = pipe_end_node_all[pipe_leak]
+        located_pipe_start_node = pipe_start_node_all[located_pipe]
+        located_pipe_end_node = pipe_end_node_all[located_pipe]
+        DtoTop1_series = pd.Series(dtype=object)
+        DtoTop1_num_series = pd.Series(dtype=object)
+        DtoTop1_series["ss"] = nx.shortest_path_length(
+            G0, pipe_leak_start_node, located_pipe_start_node, weight="weight"
+        )
+        DtoTop1_series["se"] = nx.shortest_path_length(
+            G0, pipe_leak_start_node, located_pipe_end_node, weight="weight"
+        )
+        DtoTop1_series["es"] = nx.shortest_path_length(
+            G0, pipe_leak_end_node, located_pipe_start_node, weight="weight"
+        )
+        DtoTop1_series["ee"] = nx.shortest_path_length(
+            G0, pipe_leak_end_node, located_pipe_end_node, weight="weight"
+        )
+        DtoTop1_num_series["ss"] = nx.shortest_path_length(
+            G0, pipe_leak_start_node, located_pipe_start_node
+        )
+        DtoTop1_num_series["se"] = nx.shortest_path_length(
+            G0, pipe_leak_start_node, located_pipe_end_node
+        )
+        DtoTop1_num_series["es"] = nx.shortest_path_length(
+            G0, pipe_leak_end_node, located_pipe_start_node
+        )
+        DtoTop1_num_series["ee"] = nx.shortest_path_length(
+            G0, pipe_leak_end_node, located_pipe_end_node
+        )
+
+        if DtoTop1_num_series.min() == 0:
+            result_DtoTop1_num = 1
+            result_DtoTop1 = DtoTop1_series.max() / 2
+        else:
+            result_DtoTop1_num = DtoTop1_num_series.min() + 1
+            DtoTop1_type = DtoTop1_series.argmin()
+            result_DtoTop1 = (
+                DtoTop1_series[DtoTop1_type]
+                + (pipe_length[pipe_leak] + pipe_length[located_pipe]) / 2
+            )
+    return result_DtoTop1, result_DtoTop1_num
+
+
+def cal_RR(located_pipe, similarity_sp):
+    if located_pipe in similarity_sp.index:
+        rank = similarity_sp.index.get_loc(located_pipe)
+        RR = rank / len(similarity_sp.index)
+    else:
+        RR = 1.1
+    return RR
+
+
+def cal_cover(similarity, leak_pipe):
+    if leak_pipe in list(similarity.index):
+        cover = 1
+    else:
+        cover = 0
+    return cover
+
+
+def cal_SD(located_pipe, real_pipe, pipe_x, pipe_y):
+    dx = pipe_x[located_pipe] - pipe_x[real_pipe]
+    dy = pipe_y[located_pipe] - pipe_y[real_pipe]
+    SD = math.sqrt(dx * dx + dy * dy)
+    return SD
+
+
+def DN_search_multi_simple_add_flow_count_new(
+    wn,
+    wn_inp_path,
+    G0,
+    all_node,
+    node_x,
+    node_y,
+    pipe_start_node_all,
+    pipe_end_node_all,
+    pipe_diameter,
+    couple_node_length,
+    node_pipe_dic,
+    all_node_series,
+    top_group_ratio,
+    top_pipe_num_max,
+    top_pipe_num_min,
+    candidate_pipe_input_initial,
+    similarity_mode,
+    pressure_monitor,
+    pressure_predict,
+    pressure_normal,
+    pressure_leak_all,
+    flow_monitor,
+    flow_predict,
+    flow_normal,
+    flow_leak_all,
+    timestep_list,
+    max_flow,
+    group_basic_num,
+    Top_sensor_num,
+    if_gy,
+    pressure_threshold,
+    leak_mag,
+    n_workers=1,
+    stage_timing=None,
+    partition_on_full_graph=True,
+    visualize_partition=False,
+    visualize_pause_seconds=0.3,
+    final_candidates_csv_path=None,
+):
+    if stage_timing is None:
+        stage_timing = {}
+    exit_condition = "unknown"
+    final_candidates_csv = None
+    iter_count = 0
+    all_node_iter = copy.deepcopy(all_node)
+    candidate_pipe_input = copy.deepcopy(candidate_pipe_input_initial)  # 可能漏损管段
+    t1 = datetime.now()
+    if_flow, if_only_cos, if_only_flow = decode_mode(similarity_mode)  # 定位方法
+    # threshold
+    if if_only_flow == 1:
+        dpressure = (flow_predict - flow_monitor).mean()
+        dpressure = dpressure.abs()
+        effective_sensor = list(dpressure.index)
+
+    else:
+        dpressure = (pressure_predict - pressure_monitor).mean()
+        dpressure = dpressure.abs()
+        dpressure = dpressure[dpressure > pressure_threshold]
+        effective_sensor = list(dpressure.index)
+    simulation_times = 0  # 模拟次数
+    if len(dpressure) > 0:
+        break_flag = 0
+        last_round_candidate_details = None
+
+        cos_h = 0
+        dis_h = 0
+        dis_f_h = 0
+        if_compalsive = 0
+        record_center_dataset = []
+        record_center_set = set()
+        # iter
+        while 1:
+            final_area = []
+            final_center = []
+            group_num = cal_group_num(candidate_pipe_input, group_basic_num)
+            partition_nodes = all_node if partition_on_full_graph else all_node_iter
+
+            # group 分组，得出候选漏损中心
+            stage_start = perf_counter()
+            (
+                candidate_center_list,
+                candidate_group_list,
+                new_all_node,
+                candidate_center_candidates,
+            ) = (
+                metis_grouping_pipe_weight(
+                    G0,
+                    wn,
+                    partition_nodes,
+                    candidate_pipe_input,
+                    group_num,
+                    node_x,
+                    node_y,
+                    pipe_start_node_all,
+                    pipe_end_node_all,
+                    node_pipe_dic,
+                    all_node_series,
+                    couple_node_length,
+                    pipe_diameter,
+                )
+            )
+            _accumulate_stage(stage_timing, "group_partitioning", stage_start)
+            if visualize_partition:
+                visualize_metis_partition(
+                    G0,
+                    candidate_center_list,
+                    candidate_group_list,
+                    node_x,
+                    node_y,
+                    pipe_start_node_all,
+                    pipe_end_node_all,
+                    title=(
+                        f"METIS Partition Iteration {iter_count + 1} | "
+                        f"candidate pipes={len(candidate_pipe_input)} "
+                        f"groups={len(candidate_group_list)}"
+                    ),
+                    block=False,
+                    pause_seconds=visualize_pause_seconds,
+                )
+            simulation_times = simulation_times + len(candidate_center_list)
+            # pick_pressure_leak
+            # pressure_leak = pressure_leak_all.loc[candidate_center_list].loc[:, :]
+            # flow_leak = flow_leak_all.loc[candidate_center_list].loc[:, :]
+            # —— 新增泄漏量（保持你现在的一致，或从外部传入）——
+            # —— 只为缺失中心补算，然后取本轮需要的中心子集 ——
+            stage_start = perf_counter()
+            pressure_leak, flow_leak, pressure_leak_all, flow_leak_all = (
+                _ensure_signatures_for_centers(
+                    wn=wn,
+                    wn_inp_path=wn_inp_path,
+                    center_list=candidate_center_list,
+                    pressure_leak_all=pressure_leak_all,
+                    flow_leak_all=flow_leak_all,
+                    timestep_list=timestep_list,
+                    pressure_monitor=pressure_monitor,
+                    flow_monitor=flow_monitor,
+                    leak_mag=leak_mag,
+                    n_workers=n_workers,
+                )
+            )
+            _accumulate_stage(stage_timing, "signature_for_candidates", stage_start)
+
+            # pressure_leak_f= pressure_leak.swaplevel()
+
+            # --------------------------------------------------------
+
+            add_center = []
+            leak_center_dict = dict()
+            for i in range(len(candidate_center_list)):
+                primary_center = candidate_center_list[i]
+                houxuan_center = [
+                    center
+                    for center in candidate_center_candidates[i]
+                    if center != primary_center
+                ]
+                candidate_group_set = set(candidate_group_list[i])
+                for each_center in record_center_dataset:
+                    if (
+                        each_center in candidate_group_set
+                        and each_center != primary_center
+                    ):
+                        houxuan_center.append(each_center)
+                add_center = add_center + houxuan_center
+                leak_center_dict[primary_center] = _dedupe_preserve_order(
+                    houxuan_center + [primary_center]
+                )
+            add_center = _dedupe_preserve_order(add_center)
+            for each_group_centers in candidate_center_candidates:
+                for each_center in each_group_centers:
+                    if each_center not in record_center_set:
+                        record_center_dataset.append(each_center)
+                        record_center_set.add(each_center)
+            for each_center in add_center:
+                if each_center not in record_center_set:
+                    record_center_dataset.append(each_center)
+                    record_center_set.add(each_center)
+
+            # --------------------------------------------------------
+            # --------------------------------------------------------
+            # if len(add_center) > 0:
+            #     s3 = pressure_leak_all.loc[add_center]
+            #     pressure_leak = pd.concat([pressure_leak, s3])
+            #     s4 = flow_leak_all.loc[add_center]
+            #     flow_leak = pd.concat([flow_leak, s4])
+            # --------------------------------------------------------
+            # 只为 add_center 里还没算过的中心补算，并与本轮中心合并
+            if len(add_center) > 0:
+                stage_start = perf_counter()
+                pressure_add, flow_add, pressure_leak_all, flow_leak_all = (
+                    _ensure_signatures_for_centers(
+                        wn=wn,
+                        wn_inp_path=wn_inp_path,
+                        center_list=add_center,
+                        pressure_leak_all=pressure_leak_all,
+                        flow_leak_all=flow_leak_all,
+                        timestep_list=timestep_list,
+                        pressure_monitor=pressure_monitor,
+                        flow_monitor=flow_monitor,
+                        leak_mag=leak_mag,  # 与上面一致
+                        n_workers=n_workers,
+                    )
+                )
+                _accumulate_stage(
+                    stage_timing, "signature_for_extra_centers", stage_start
+                )
+                pressure_leak = pd.concat([pressure_leak, pressure_add], axis=0)
+                if (flow_leak is not None) and (flow_add is not None):
+                    flow_leak = pd.concat([flow_leak, flow_add], axis=0)
+            # --------------------------------------------------------
+            #
+            if len(candidate_pipe_input) < 1.2 * top_pipe_num_max / top_group_ratio:
+                if_compalsive = 1
+            cos_h, dis_h, dis_f_h = adjust_ratio(similarity_mode, cos_h, dis_h, dis_f_h)
+            candidate_center_list_sup = _dedupe_preserve_order(
+                candidate_center_list + add_center
+            )
+            stage_start = perf_counter()
+            similarity, cos_h, dis_h, dis_f_h, break_flag, similarity_details = (
+                cal_similarity_all_multi_new_sq_improve_double_lzr(
+                    candidate_center_list_sup,
+                    similarity_mode,
+                    pressure_leak,
+                    pressure_monitor,
+                    pressure_predict,
+                    pressure_normal,
+                    if_flow,
+                    if_only_cos,
+                    if_only_flow,
+                    flow_leak,
+                    flow_monitor,
+                    flow_predict,
+                    flow_normal,
+                    timestep_list,
+                    Top_sensor_num,
+                    if_gy,
+                    effective_sensor,
+                    cos_h,
+                    dis_h,
+                    dis_f_h,
+                    if_compalsive,
+                    max_flow,
+                )
+            )
+            last_round_candidate_details = similarity_details
+            _accumulate_stage(stage_timing, "similarity_ranking", stage_start)
+            if break_flag == 1:
+                exit_condition = "similarity_break_flag"
+                break
+
+            new_similarity = update_similarity(
+                candidate_center_list, similarity, leak_center_dict
+            )
+            if len(candidate_pipe_input) > top_pipe_num_max / top_group_ratio:
+                cut_ratio, new_similarity = extra_judge(new_similarity)
+            else:
+                cut_ratio = 1
+            stage_start = perf_counter()
+            final_area_t, final_center_t, all_node_new_1, if_end = (
+                area_output_num_ki_improve(
+                    candidate_center_list,
+                    candidate_group_list,
+                    new_similarity,
+                    new_all_node,
+                    top_group_ratio,
+                    top_pipe_num_max,
+                    top_pipe_num_min,
+                    cut_ratio,
+                )
+            )
+            _accumulate_stage(stage_timing, "candidate_area_selection", stage_start)
+            final_area = final_area + final_area_t
+            final_center = final_center + final_center_t
+
+            final_area = sorted(set(final_area))
+            final_center = sorted(set(final_center))
+            if if_end == 1:
+                exit_condition = "candidate_area_if_end"
+                break
+            elif len(candidate_pipe_input) == len(final_area):
+                exit_condition = "candidate_size_no_change"
+                break
+            else:
+                candidate_pipe_input = final_area
+                if not partition_on_full_graph:
+                    all_node_iter = all_node_new_1
+                iter_count += 1
+                sys.stdout.write(
+                    "\r"
+                    + "已经完成"
+                    + str(iter_count)
+                    + "次迭代计算"
+                    + "候选节点"
+                    + str(len(final_area))
+                    + "个"
+                )
+        # if break_flag == 0:
+        #     final_area_pipe = copy.deepcopy(final_area)
+        #     simulation_times = simulation_times + len(final_area)
+        #     pressure_leak_sp = pressure_leak_all.loc[final_area_pipe].loc[:, :]
+        #     flow_leak_sp = flow_leak_all.loc[final_area_pipe].loc[:, :]
+        #     similarity_sp, cos_h, dis_h, dis_f_h, break_flag = cal_similarity_all_multi_new_sq_improve_double_lzr(
+        #         final_area_pipe, similarity_mode, pressure_leak_sp,
+        #         pressure_monitor, pressure_predict, pressure_normal, if_flow,
+        #         if_only_cos, if_only_flow,
+        #         flow_leak_sp, flow_monitor, flow_predict, flow_normal,
+        #         timestep_list, Top_sensor_num, if_gy, effective_sensor, cos_h, dis_h, dis_f_h, if_compalsive, max_flow)
+        if break_flag == 0:
+            final_area_pipe = list(final_area)  # 确保是 list
+
+            # 只为还没算过的管段补齐 SLF（按需计算）
+            stage_start = perf_counter()
+            pressure_leak_sp, flow_leak_sp, pressure_leak_all, flow_leak_all = (
+                _ensure_signatures_for_centers(
+                    wn=wn,
+                    wn_inp_path=wn_inp_path,
+                    center_list=final_area_pipe,  # 这次要用的“最终区域里的所有管段”
+                    pressure_leak_all=pressure_leak_all,  # 累积缓存（会被更新）
+                    flow_leak_all=flow_leak_all,
+                    timestep_list=timestep_list,
+                    pressure_monitor=pressure_monitor,
+                    flow_monitor=flow_monitor,
+                    leak_mag=leak_mag,
+                    n_workers=n_workers,
+                )
+            )
+            _accumulate_stage(stage_timing, "signature_for_final_area", stage_start)
+
+            # 如果你要精确统计模拟次数，这里可以加上“本次新补的数量”，
+            # 做法：让 _ensure_signatures_for_centers 额外返回 need_cnt，再 simulation_times += need_cnt
+
+            stage_start = perf_counter()
+            (
+                similarity_sp,
+                cos_h,
+                dis_h,
+                dis_f_h,
+                break_flag,
+                similarity_details,
+            ) = (
+                cal_similarity_all_multi_new_sq_improve_double_lzr(
+                    final_area_pipe,
+                    similarity_mode,
+                    pressure_leak_sp,
+                    pressure_monitor,
+                    pressure_predict,
+                    pressure_normal,
+                    if_flow,
+                    if_only_cos,
+                    if_only_flow,
+                    flow_leak_sp,
+                    flow_monitor,
+                    flow_predict,
+                    flow_normal,
+                    timestep_list,
+                    Top_sensor_num,
+                    if_gy,
+                    effective_sensor,
+                    cos_h,
+                    dis_h,
+                    dis_f_h,
+                    if_compalsive,
+                    max_flow,
+                )
+            )
+            last_round_candidate_details = similarity_details
+            _accumulate_stage(stage_timing, "similarity_final", stage_start)
+
+        else:
+            dpressure = (pressure_predict - pressure_monitor).mean()
+            dpressure = dpressure.abs()
+            simulation_times = simulation_times + len(dpressure.index)
+            similarity_sp = pd.Series(dtype=float)
+            for each_node in dpressure.index:
+                pipe = node_pipe_dic[each_node][0]
+                similarity_sp.loc[pipe] = dpressure.loc[each_node]
+            similarity_sp = similarity_sp.sort_values(ascending=False, kind="mergesort")
+            t2 = datetime.now()
+            final_area_pipe = []
+
+        sys.stdout.write(
+            "\r"
+            + "已经完成"
+            + str(iter_count + 1)
+            + "次迭代计算"
+            + "候选节点"
+            + str(len(final_area_pipe))
+            + "个"
+        )
+        t2 = datetime.now()
+        dt = (t2 - t1).seconds
+        final_candidates_csv = _write_last_round_candidates_csv(
+            csv_path=final_candidates_csv_path,
+            exit_condition=exit_condition,
+            iteration_count=iter_count + 1,
+            similarity_mode=similarity_mode,
+            candidate_details=last_round_candidate_details,
+            fallback_similarity=similarity_sp,
+        )
+    else:
+        exit_condition = "no_effective_sensor_after_threshold"
+        dpressure = (pressure_predict - pressure_monitor).mean()
+        dpressure = dpressure.abs()
+
+        similarity_sp = pd.Series(dtype=float)
+        for each_node in dpressure.index:
+            pipe = node_pipe_dic[each_node][0]
+            similarity_sp.loc[pipe] = dpressure.loc[each_node]
+        similarity_sp = similarity_sp.sort_values(ascending=False, kind="mergesort")
+        t2 = datetime.now()
+        dt = (t2 - t1).seconds
+        final_candidates_csv = _write_last_round_candidates_csv(
+            csv_path=final_candidates_csv_path,
+            exit_condition=exit_condition,
+            iteration_count=0,
+            similarity_mode=similarity_mode,
+            candidate_details=None,
+            fallback_similarity=similarity_sp,
+        )
+    stage_timing["iterations"] = iter_count + 1 if len(dpressure) > 0 else 0
+    stage_timing["total_elapsed_seconds"] = float(dt)
+    stage_timing["exit_condition"] = exit_condition
+    stage_timing["final_candidates_csv"] = final_candidates_csv
+    return (
+        similarity_sp.index[0],
+        dt,
+        simulation_times,
+        wn,
+        similarity_sp,
+        exit_condition,
+        final_candidates_csv,
+    )
+
+

app/algorithms/burst_location/leak_simulator.py

@@ -0,0 +1,563 @@
+"""漏损模拟模块。"""
+
+import math
+import multiprocessing as mp
+import os
+import sys
+
+import pandas as pd
+import wntr
+
+from app.algorithms._utils import _cleanup_temp_files
+
+_PIPE2LEAKNODE = None
+_SIGNATURE_WORKER_DATA = {}
+
+
+def _make_temp_prefix(tag):
+    temp_dir = os.path.abspath(os.path.join("temp", "burst_location"))
+    os.makedirs(temp_dir, exist_ok=True)
+    safe_tag = str(tag).replace(os.sep, "_").replace(" ", "_")
+    return os.path.join(temp_dir, f"{safe_tag}_{os.getpid()}")
+
+
+def _snapshot_hydraulic_options(wn):
+    options = wn.options
+    return {
+        "demand_model": options.hydraulic.demand_model,
+        "duration": float(options.time.duration),
+        "hydraulic_timestep": float(options.time.hydraulic_timestep),
+        "pattern_timestep": float(options.time.pattern_timestep),
+        "report_timestep": float(options.time.report_timestep),
+        "required_pressure": float(options.hydraulic.required_pressure),
+        "minimum_pressure": float(options.hydraulic.minimum_pressure),
+    }
+
+
+def _apply_hydraulic_options(wn, option_values):
+    options = wn.options
+    options.hydraulic.demand_model = option_values["demand_model"]
+    options.time.duration = option_values["duration"]
+    options.time.hydraulic_timestep = option_values["hydraulic_timestep"]
+    options.time.pattern_timestep = option_values["pattern_timestep"]
+    options.time.report_timestep = option_values["report_timestep"]
+    options.hydraulic.required_pressure = option_values["required_pressure"]
+    options.hydraulic.minimum_pressure = option_values["minimum_pressure"]
+
+
+def simple_add_leak(wn, leak_mag, leak_pipe):
+    whole_inf = dict()
+    leak_pipe_self = wn.get_link(leak_pipe)
+    pipe_diameter = leak_pipe_self.diameter
+    pipe_length = leak_pipe_self.length
+    pipe_roughness = leak_pipe_self.roughness
+    pipe_minor_loss = leak_pipe_self.minor_loss
+    # pipe_status = leak_pipe_self.status
+    # pipe_check_valve = leak_pipe_self.check_valve
+    pipe_start_node = leak_pipe_self.start_node_name
+    pipe_end_node = leak_pipe_self.end_node_name
+
+    # close the pipe
+    # leak_pipe_self.status = 'Closed'
+    wn.remove_link(leak_pipe)
+    # add the pipe
+    add_pipe1 = leak_pipe + "A"
+    add_pipe2 = leak_pipe + "B"
+    add_node = leak_pipe + "_"
+
+    start_n = wn.get_node(pipe_start_node)
+    end_n = wn.get_node(pipe_end_node)
+    if start_n.node_type == "Reservoir":
+        end_n_elevation = end_n.elevation
+        start_n_elevation = end_n_elevation
+    elif end_n.node_type == "Reservoir":
+        start_n_elevation = start_n.elevation
+        end_n_elevation = start_n_elevation
+    else:
+        end_n_elevation = end_n.elevation
+        start_n_elevation = start_n.elevation
+    elevation_self = (start_n_elevation + end_n_elevation) / 2
+    coordinates_self = (
+        (start_n.coordinates[0] + end_n.coordinates[0]) / 2,
+        (start_n.coordinates[1] + end_n.coordinates[1]),
+    )
+
+    wn.add_junction(
+        add_node, base_demand=0, elevation=elevation_self, coordinates=coordinates_self
+    )
+    leak_node = wn.get_node(add_node)
+    wn.add_pipe(
+        add_pipe1,
+        start_node_name=pipe_start_node,
+        end_node_name=add_node,
+        length=pipe_length / 2,
+        diameter=pipe_diameter,
+        roughness=pipe_roughness,
+        minor_loss=pipe_minor_loss,
+    )
+    wn.add_pipe(
+        add_pipe2,
+        start_node_name=pipe_end_node,
+        end_node_name=add_node,
+        length=pipe_length / 2,
+        diameter=pipe_diameter,
+        roughness=pipe_roughness,
+        minor_loss=pipe_minor_loss,
+    )
+
+    # simulation
+    leak_node.add_demand(base=leak_mag, pattern_name="add_leak")
+
+    whole_inf["leak_node_name"] = add_node
+    whole_inf["add_pipe1"] = add_pipe1
+    whole_inf["add_pipe2"] = add_pipe2
+    whole_inf["leak_pipe"] = leak_pipe
+    whole_inf["pipe_start_node"] = pipe_start_node
+    whole_inf["pipe_end_node"] = pipe_end_node
+    whole_inf["pipe_length"] = pipe_length
+    whole_inf["pipe_diameter"] = pipe_diameter
+    whole_inf["pipe_roughness"] = pipe_roughness
+    whole_inf["pipe_minor_loss"] = pipe_diameter
+    return wn, whole_inf, add_pipe1
+
+
+def simple_recover_wn(wn, whole_inf):
+    leak_node = wn.get_node(whole_inf["leak_node_name"])
+
+    del leak_node.demand_timeseries_list[-1]
+    # update
+    wn.remove_link(whole_inf["add_pipe1"])
+    wn.remove_link(whole_inf["add_pipe2"])
+    wn.remove_node(whole_inf["leak_node_name"])
+    # open the pipe
+    # leak_pipe_self.status = 'Open'
+    wn.add_pipe(
+        whole_inf["leak_pipe"],
+        start_node_name=whole_inf["pipe_start_node"],
+        end_node_name=whole_inf["pipe_end_node"],
+        length=whole_inf["pipe_length"],
+        diameter=whole_inf["pipe_diameter"],
+        roughness=whole_inf["pipe_roughness"],
+        minor_loss=whole_inf["pipe_minor_loss"],
+    )
+
+    return wn
+
+
+def disable_all_controls_temporarily(wn):
+    """返回(控制名, 控制对象)的列表，之后可用 restore_controls 还原。"""
+    removed = []
+    # WNTR 的控制都在 wn.control_name_list / wn.get_control / wn.remove_control
+    for cname in list(wn.control_name_list):
+        ctrl = wn.get_control(cname)
+        removed.append((cname, ctrl))
+        wn.remove_control(cname)
+    return removed
+
+
+def restore_controls(wn, removed):
+    """把先前禁用的控制全部加回去。"""
+    for cname, ctrl in removed:
+        wn.add_control(cname, ctrl)
+
+
+def set_pipe2leaknode_mapping(mapping):
+    global _PIPE2LEAKNODE
+    _PIPE2LEAKNODE = mapping
+
+
+def _get_or_create_leak_demand_ts(leak_node):
+    """
+    返回：泄漏专用 demand 的下标 idx。
+    若不存在，以 category='leak' 新建一条 base=0.0 的 demand。
+    """
+    # 先尝试找到已有的 'leak' 分类
+    for i, ts in enumerate(leak_node.demand_timeseries_list):
+        # WNTR 的 Demand object 存在 category 属性
+        if getattr(ts, "category", None) == "leak":
+            return i
+    # 没有则新建（base=0.0，后续临时改 base_value）
+    leak_node.add_demand(base=0.0, pattern_name=None, category="leak")
+    return len(leak_node.demand_timeseries_list) - 1
+
+
+def ensure_mid_node(wn, leak_pipe):
+    add_pipe1 = f"{leak_pipe}A"
+    add_pipe2 = f"{leak_pipe}B"
+    add_node = f"{leak_pipe}__mid"
+
+    if add_node in wn.node_name_list:
+        return add_node
+
+    if leak_pipe in wn.link_name_list:
+        leak_pipe_self = wn.get_link(leak_pipe)
+        pipe_diameter = leak_pipe_self.diameter
+        pipe_length = leak_pipe_self.length
+        pipe_roughness = leak_pipe_self.roughness
+        pipe_minor_loss = leak_pipe_self.minor_loss
+        pipe_start_node = leak_pipe_self.start_node_name
+        pipe_end_node = leak_pipe_self.end_node_name
+
+        start_n = wn.get_node(pipe_start_node)
+        end_n = wn.get_node(pipe_end_node)
+        if start_n.node_type == "Reservoir":
+            end_elev = end_n.elevation
+            start_elev = end_elev
+        elif end_n.node_type == "Reservoir":
+            start_elev = start_n.elevation
+            end_elev = start_elev
+        else:
+            end_elev = end_n.elevation
+            start_elev = start_n.elevation
+        elev_mid = (start_elev + end_elev) / 2.0
+        x_mid = (start_n.coordinates[0] + end_n.coordinates[0]) / 2.0
+        y_mid = (start_n.coordinates[1] + end_n.coordinates[1]) / 2.0
+
+        wn.remove_link(leak_pipe)
+        wn.add_junction(
+            add_node, base_demand=0.0, elevation=elev_mid, coordinates=(x_mid, y_mid)
+        )
+        wn.add_pipe(
+            add_pipe1,
+            start_node_name=pipe_start_node,
+            end_node_name=add_node,
+            length=pipe_length / 2.0,
+            diameter=pipe_diameter,
+            roughness=pipe_roughness,
+            minor_loss=pipe_minor_loss,
+        )
+        wn.add_pipe(
+            add_pipe2,
+            start_node_name=add_node,
+            end_node_name=pipe_end_node,
+            length=pipe_length / 2.0,
+            diameter=pipe_diameter,
+            roughness=pipe_roughness,
+            minor_loss=pipe_minor_loss,
+        )
+        return add_node
+
+    # 若 A/B 已存在但中点不在，建议确认网络一致性
+    raise KeyError(f"Cannot ensure mid node for pipe '{leak_pipe}'.")
+
+
+def leak_simulation_pipe_dd_multi_pf(
+    wn, leak_mag, leak_pipe, sensor_name, file_prefix=None
+):
+    """
+    优化版：
+    - 不再 remove/add link/node
+    - 直接在预插入的中点泄漏节点上设置 base_demand = leak_mag；仿真后设回 0
+    """
+    wn.options.hydraulic.demand_model = "DD"
+
+    # 确保中点节点存在
+    leak_node_name = ensure_mid_node(wn, leak_pipe)
+    leak_node = wn.get_node(leak_node_name)
+
+    # 拿到泄漏专用的 demand time-series 下标
+    leak_idx = _get_or_create_leak_demand_ts(leak_node)
+    ts_obj = leak_node.demand_timeseries_list[leak_idx]
+
+    # 记录原值（通常是 0.0）
+    orig_base = ts_obj.base_value
+    try:
+        # 打开泄漏：只改 base_value，不碰 base_demand（只读）
+        ts_obj.base_value = float(leak_mag)
+
+        # 仿真
+        sim = wntr.sim.EpanetSimulator(wn)
+        if file_prefix is None:
+            results = sim.run_sim()
+        else:
+            results = sim.run_sim(file_prefix=file_prefix)
+
+        # 输出（保持列顺序）
+        pressure_output = results.node["pressure"].loc[:, sensor_name]
+        # flow_output = results.link['flowrate'].loc[:, sensor_f_name]
+        return wn, pressure_output
+    finally:
+        # 关闭泄漏：还原 base_value
+        ts_obj.base_value = orig_base
+        if file_prefix is not None:
+            _cleanup_temp_files(file_prefix)
+
+
+def prepare_leak_infrastructure(wn, candidate_pipes):
+    """
+    把 candidate_pipes 每条管段切成两段，并在中点插入一个泄漏节点（base_demand=0）。
+    返回一个映射：pipe_id -> leak_node_name
+    注意：只做一次；后续仿真通过在该节点设置 base_demand 实现“打开泄漏”，结束后恢复为 0。
+    """
+    pipe2leaknode = {}
+    for leak_pipe in candidate_pipes:
+        if leak_pipe in pipe2leaknode:
+            continue
+
+        leak_pipe_self = wn.get_link(leak_pipe)
+        pipe_diameter = leak_pipe_self.diameter
+        pipe_length = leak_pipe_self.length
+        pipe_roughness = leak_pipe_self.roughness
+        pipe_minor_loss = leak_pipe_self.minor_loss
+        pipe_start_node = leak_pipe_self.start_node_name
+        pipe_end_node = leak_pipe_self.end_node_name
+
+        # 计算中点高程/坐标（与原逻辑一致）
+        start_n = wn.get_node(pipe_start_node)
+        end_n = wn.get_node(pipe_end_node)
+        if start_n.node_type == "Reservoir":
+            end_elev = end_n.elevation
+            start_elev = end_elev
+        elif end_n.node_type == "Reservoir":
+            start_elev = start_n.elevation
+            end_elev = start_elev
+        else:
+            end_elev = end_n.elevation
+            start_elev = start_n.elevation
+        elev_mid = (start_elev + end_elev) / 2.0
+        x_mid = (start_n.coordinates[0] + end_n.coordinates[0]) / 2.0
+        y_mid = (start_n.coordinates[1] + end_n.coordinates[1]) / 2.0
+
+        # 先删原管，再加中点与两段半长管（只做一次）
+        wn.remove_link(leak_pipe)
+
+        add_pipe1 = f"{leak_pipe}A"
+        add_pipe2 = f"{leak_pipe}B"
+        add_node = f"{leak_pipe}__mid"  # 唯一命名，后面直接用它当泄漏节点
+
+        wn.add_junction(
+            add_node, base_demand=0.0, elevation=elev_mid, coordinates=(x_mid, y_mid)
+        )
+        wn.add_pipe(
+            add_pipe1,
+            start_node_name=pipe_start_node,
+            end_node_name=add_node,
+            length=pipe_length / 2.0,
+            diameter=pipe_diameter,
+            roughness=pipe_roughness,
+            minor_loss=pipe_minor_loss,
+        )
+        wn.add_pipe(
+            add_pipe2,
+            start_node_name=add_node,
+            end_node_name=pipe_end_node,
+            length=pipe_length / 2.0,
+            diameter=pipe_diameter,
+            roughness=pipe_roughness,
+            minor_loss=pipe_minor_loss,
+        )
+
+        pipe2leaknode[leak_pipe] = add_node
+
+    return pipe2leaknode
+
+
+def normal_simulation_pf(
+    wn, drive_mode, sensor_name, sensor_f_name, inp_time, require_p, minimum_p
+):
+    # inp_time = 0
+    if drive_mode == "PDD":  # 需水量根据节点压力动态调整
+        wn.options.hydraulic.demand_model = "PDD"
+        wn.options.hydraulic.required_pressure = require_p
+        wn.options.hydraulic.minimum_pressure = minimum_p
+    elif drive_mode == "DD":  # 需水量固定，与压力无关
+        wn.options.hydraulic.demand_model = "DD"
+    sim = wntr.sim.EpanetSimulator(wn)
+    results = sim.run_sim()
+    pressure_all = results.node["pressure"][sensor_name]
+    pressure = pressure_all.iloc[inp_time]
+    demand_all = results.node["demand"]
+    demand = demand_all.iloc[inp_time]
+    sum_demand = cal_sum_demand(demand)
+    flow_all = results.link["flowrate"][sensor_f_name]
+    flow = flow_all.iloc[inp_time]
+
+    top_sensor = pressure.idxmin()
+    basic_p = results.node["pressure"]
+    basic_p = basic_p.iloc[inp_time]
+    return pressure, flow, basic_p, top_sensor, sum_demand
+
+
+def normal_simulation_multi_pf(
+    wn, drive_mode, sensor_name, sensor_f_name, require_p, minimum_p
+):
+    # inp_time = 0
+    if drive_mode == "PDD":
+        wn.options.hydraulic.demand_model = "PDD"
+        wn.options.hydraulic.required_pressure = require_p
+        wn.options.hydraulic.minimum_pressure = minimum_p
+    elif drive_mode == "DD":
+        wn.options.hydraulic.demand_model = "DD"
+    sim = wntr.sim.EpanetSimulator(wn)
+    results = sim.run_sim()
+    pressure_all = results.node["pressure"][sensor_name]
+    pressure = pressure_all
+    demand_all = results.node["demand"]
+    demand = demand_all
+    flow = results.link["flowrate"][sensor_f_name]
+    sum_demand = pd.Series(dtype=object)
+    for i in range(len(demand.index)):
+        sum_demand[str(demand.index[i])] = cal_sum_demand(demand.iloc[i])
+    if type(pressure) == pd.core.series.Series:
+        top_sensor = pressure.idxmin()
+    else:
+        mean_pressure = pressure.mean()
+        top_sensor = mean_pressure.idxmin()
+    basic_p = results.node["pressure"]
+    return pressure, flow, basic_p, top_sensor, sum_demand
+
+
+def simple_simulation_pf(wn, sensor_name, sensor_f_name, leak_pipe, add_pipe1):
+    sim = wntr.sim.EpanetSimulator(wn)
+    results = sim.run_sim()
+    pressure_all = results.node["pressure"][sensor_name]
+    if len(leak_pipe) > 0 and leak_pipe in sensor_f_name:
+
+        f_sensor_name = [add_pipe1 if i == leak_pipe else i for i in sensor_f_name]
+        flow_all = results.link["flowrate"][f_sensor_name]
+        flow_all.columns = sensor_f_name
+    else:
+        flow_all = results.link["flowrate"][sensor_f_name]
+    return pressure_all, flow_all
+
+
+def cal_sum_demand(demand):
+    sum_demand = 0
+    for i in range(len(demand)):
+        if demand.iloc[i] > 0:
+            sum_demand += demand.iloc[i]
+    return sum_demand
+
+
+def cal_signature_pipe_multi_pf(
+    wn,
+    leak_mag,
+    candidate_center,
+    timestep_list,
+    sensor_name,
+    n_workers=1,
+    wn_inp_path=None,
+):
+    candidate_center_num = len(candidate_center)
+    pressure_leak = pd.DataFrame(
+        index=pd.MultiIndex.from_product([candidate_center, timestep_list]),
+        columns=sensor_name,
+    )
+    # flow_leak = pd.DataFrame(index=pd.MultiIndex.from_product([candidate_center, timestep_list]),
+    #                          columns=sensor_f_name)
+    pressure_leak = pressure_leak.sort_index()
+    # flow_leak = flow_leak.sort_index()
+    can_parallel = (
+        n_workers > 1
+        and candidate_center_num > 1
+        and wn_inp_path is not None
+        and len(str(wn_inp_path)) > 0
+    )
+    if can_parallel:
+        option_values = _snapshot_hydraulic_options(wn)
+        worker_count = min(n_workers, candidate_center_num)
+        start_methods = mp.get_all_start_methods()
+        context_name = "spawn" if "spawn" in start_methods else start_methods[0]
+        with mp.get_context(context_name).Pool(
+            processes=worker_count,
+            initializer=_signature_worker_init,
+            initargs=(
+                str(wn_inp_path),
+                float(leak_mag),
+                list(sensor_name),
+                option_values,
+                list(candidate_center),
+            ),
+        ) as pool:
+            for i, (center_name, pressure_array) in enumerate(
+                pool.imap(_signature_worker_run_center, candidate_center)
+            ):
+                pressure_leak.loc[(center_name, slice(None)), :] = pressure_array
+                sys.stdout.write("\r" + "已经完成计算" + str(i + 1) + "个特征中心")
+    else:
+        # Pre-insert all mid-nodes so every simulation sees the same topology
+        for center in candidate_center:
+            ensure_mid_node(wn, center)
+        for i in range(candidate_center_num):
+            temp_prefix = _make_temp_prefix(f"sig_{i}")
+            wn, pressure_output = leak_simulation_pipe_dd_multi_pf(
+                wn,
+                leak_mag,
+                candidate_center[i],
+                sensor_name,
+                file_prefix=temp_prefix,
+            )
+            # leak_or_not_list.append(leak_or_not)
+            pressure_leak.loc[(candidate_center[i], slice(None)), :] = (
+                pressure_output.to_numpy()
+            )
+            # flow_leak.loc[candidate_center[i]].loc[:, :] = flow_output
+            sys.stdout.write("\r" + "已经完成计算" + str(i + 1) + "个特征中心")
+    return pressure_leak, candidate_center
+
+
+def _signature_worker_init(
+    inp_path, leak_mag, sensor_name, option_values, candidate_centers=None
+):
+    global _SIGNATURE_WORKER_DATA
+    wn = wntr.network.WaterNetworkModel(inp_path)
+    _apply_hydraulic_options(wn, option_values)
+    # Pre-insert ALL mid-nodes so every simulation runs on the same topology,
+    # regardless of which worker handles which task.
+    if candidate_centers is not None:
+        for center in candidate_centers:
+            ensure_mid_node(wn, center)
+    _SIGNATURE_WORKER_DATA = {
+        "wn": wn,
+        "leak_mag": leak_mag,
+        "sensor_name": sensor_name,
+    }
+
+
+def _signature_worker_run_center(center_name):
+    data = _SIGNATURE_WORKER_DATA
+    temp_prefix = _make_temp_prefix(f"sig_worker_{center_name}")
+    _, pressure_output = leak_simulation_pipe_dd_multi_pf(
+        data["wn"],
+        data["leak_mag"],
+        center_name,
+        data["sensor_name"],
+        file_prefix=temp_prefix,
+    )
+    return center_name, pressure_output.to_numpy()
+
+
+def pick_pipe(all_pipes, pipe_diameter, limited_diameter):
+    candidate_pipe = []
+    for each_pipe in all_pipes:
+        if pipe_diameter[each_pipe] >= limited_diameter:
+            candidate_pipe.append(each_pipe)
+    return candidate_pipe
+
+
+def cal_possible_pipe(leak_flow, all_pipe, pipe_diameter):
+    basic_pressure = 10  # 基础压力
+    discharge_coeff = 0.6  # 经验系数
+    break_area_ratio = 1  # 爆管面积比 0.5  1.25
+    break_area = leak_flow / (
+        discharge_coeff * math.sqrt(2 * basic_pressure * 9.81)
+    )  # 爆管面积 m3/h
+    """break_area_diameter = math.sqrt(4 * break_area / math.pi)
+    min_diameter = (math.ceil(1000 * break_area_diameter / break_area_ratio)) / 1000"""
+    break_area_diameter = math.sqrt(
+        4 * break_area / math.pi / break_area_ratio
+    )  # 爆管直径
+    min_diameter = (math.ceil(1000 * break_area_diameter)) / 1000  # 向上取整
+    new_all_pipe = pick_pipe(all_pipe, pipe_diameter, min_diameter)
+    return new_all_pipe, min_diameter
+
+
+def extract_links(data, link_types, direction):
+    return [
+        link
+        for res_data in data.values()
+        for link_type in link_types
+        for link in res_data[link_type][direction]
+    ]
+
+

app/algorithms/burst_location/network_model.py

@@ -0,0 +1,137 @@
+"""管网模型读取与图构建模块。"""
+
+import copy
+
+import numpy as np
+import networkx as nx
+import pandas as pd
+import wntr
+
+
+def load_inp(inp_name, inp_location, inp_time, driven_mode, require_p, minimum_p):
+    inp_file = inp_location + inp_name
+    wn = wntr.network.WaterNetworkModel(inp_file)
+    if driven_mode == "PDD":
+        wn.options.hydraulic.demand_model = "PDD"
+        wn.options.hydraulic.required_pressure = require_p
+        wn.options.hydraulic.minimum_pressure = minimum_p
+    else:
+        wn.options.hydraulic.demand_model = "DD"
+    return wn
+
+
+def read_inf_inp(wn):
+    all_node = wn.node_name_list
+    node_elevation = wn.query_node_attribute("elevation")
+    node_coordinates = wn.query_node_attribute("coordinates")
+
+    all_pipe = wn.pipe_name_list
+    # 改_wz__________________________________
+    n_pipe = []
+    for p in all_pipe:
+        pipe = wn.get_link(p)
+        if pipe.initial_status == 0:  # 状态为'Closed'
+            n_pipe.append(p)
+    candidate_pipe_init = sorted(set(all_pipe) - set(n_pipe))
+    pipe_start_node = wn.query_link_attribute(
+        "start_node_name", link_type=wntr.network.model.Pipe
+    )
+    pipe_end_node = wn.query_link_attribute(
+        "end_node_name", link_type=wntr.network.model.Pipe
+    )
+    pipe_length = wn.query_link_attribute("length")
+    pipe_diameter = wn.query_link_attribute("diameter")
+
+    return (
+        all_node,
+        node_elevation,
+        node_coordinates,
+        candidate_pipe_init,
+        pipe_start_node,
+        pipe_end_node,
+        pipe_length,
+        pipe_diameter,
+    )
+
+
+def read_inf_inp_other(wn):
+    all_link = wn.link_name_list
+    pipe_start_node_all = wn.query_link_attribute("start_node_name")
+    pipe_end_node_all = wn.query_link_attribute("end_node_name")
+
+    return all_link, pipe_start_node_all, pipe_end_node_all
+
+
+def construct_graph(wn):
+    length = wn.query_link_attribute("length")
+    G = wn.get_graph(wn, link_weight=length)
+    # 转为无向图
+    G0 = G.to_undirected()
+    # A0 = np.array(nx.adjacency_graph(G0).todense())
+    return G0  # , A0
+
+
+def cal_pipe_coordinate(all_pipe, pipe_start_node, pipe_end_node, node_coordinates):
+    pipe_num = len(all_pipe)
+    pipe_coordinates = np.zeros([pipe_num, 2])
+    pipe_x = copy.deepcopy(pipe_start_node)
+    pipe_y = copy.deepcopy(pipe_start_node)
+    for i in range(pipe_num):
+        temp_pipe = all_pipe[i]
+        pipe_x[temp_pipe] = (
+            node_coordinates[pipe_start_node[temp_pipe]][0]
+            + node_coordinates[pipe_end_node[temp_pipe]][0]
+        ) / 2
+        pipe_y[temp_pipe] = (
+            node_coordinates[pipe_start_node[temp_pipe]][1]
+            + node_coordinates[pipe_end_node[temp_pipe]][1]
+        ) / 2
+    return pipe_x, pipe_y
+
+
+def cal_node_coordinate(all_node, node_coordinates):
+    node_x = copy.deepcopy(node_coordinates)
+    node_y = copy.deepcopy(node_coordinates)
+    for i in range(len(node_x)):
+        temp_node = all_node[i]
+        node_x[temp_node] = node_coordinates[temp_node][0]
+        node_y[temp_node] = node_coordinates[temp_node][1]
+    return node_x, node_y
+
+
+def produce_pattern_value(wn, all_node):
+    wn_o = copy.deepcopy(wn)
+    # 改_wz_____________________________
+    # sample_node = wn_o.get_node(all_node[0])
+    # num_categories = len(sample_node.demand_timeseries_list)
+    num_categories = 1
+    columns = [f"D{i}" for i in range(num_categories)]
+    basic_demand_pd = pd.DataFrame(index=all_node, columns=columns)
+    for each in all_node:
+        node = wn_o.get_node(each)
+        for i in range(num_categories):
+            basic_demand_pd.loc[each, columns[i]] = node.demand_timeseries_list[
+                i
+            ].base_value
+
+    return basic_demand_pd
+
+
+def _build_node_pipe_maps(
+    all_nodes, candidate_pipes, pipe_start_node, pipe_end_node, pipe_length
+):
+    node_pipe_dic = {node: [] for node in all_nodes}
+    couple_node_length = {}
+    for pipe in candidate_pipes:
+        start_node = pipe_start_node[pipe]
+        end_node = pipe_end_node[pipe]
+        if start_node in node_pipe_dic:
+            node_pipe_dic[start_node].append(pipe)
+        if end_node in node_pipe_dic:
+            node_pipe_dic[end_node].append(pipe)
+        length = float(pipe_length[pipe])
+        couple_node_length[f"{start_node},{end_node}"] = length
+        couple_node_length[f"{end_node},{start_node}"] = length
+    return node_pipe_dic, couple_node_length
+
+

app/algorithms/burst_location/network_partitioner.py

@@ -0,0 +1,456 @@
+"""管网分区模块。"""
+
+import math
+
+import matplotlib.pyplot as plt
+import networkx as nx
+import networkx as networkx
+import numpy as np
+import pandas as pd
+import pymetis
+from scipy.sparse import coo_matrix, csr_matrix
+from scipy.sparse.csgraph import connected_components
+
+
+def _to_metis_edge_weight(edge_weight):
+    weight = float(edge_weight)
+    if not math.isfinite(weight):
+        raise ValueError(f"Invalid non-finite METIS edge weight: {edge_weight}")
+    # pymetis expects integer edge weights.
+    return max(1, int(round(weight)))
+
+
+def _dedupe_preserve_order(items):
+    seen = set()
+    output = []
+    for item in items:
+        if item in seen:
+            continue
+        seen.add(item)
+        output.append(item)
+    return output
+
+
+def pick_center_pipe(node_x, node_y, candidate_pipe, pipe_start_node, pipe_end_node):
+    candidate_pipe_list = list(candidate_pipe)
+    start_nodes = pipe_start_node[candidate_pipe_list]
+    end_nodes = pipe_end_node[candidate_pipe_list]
+
+    x_vals = (node_x[start_nodes].to_numpy() + node_x[end_nodes].to_numpy()) / 2.0
+    y_vals = (node_y[start_nodes].to_numpy() + node_y[end_nodes].to_numpy()) / 2.0
+    mean_x = float(np.mean(x_vals))
+    mean_y = float(np.mean(y_vals))
+    distance = np.abs(x_vals - mean_x) + np.abs(y_vals - mean_y)
+    center_idx = int(np.argmin(distance))
+    return candidate_pipe_list[center_idx]
+
+
+def pick_max_diameter_pipe(candidate_pipe, pipe_diameter):
+    candidate_pipe_list = list(candidate_pipe)
+    diameters = pd.to_numeric(
+        pipe_diameter.reindex(candidate_pipe_list), errors="coerce"
+    ).dropna()
+    if len(diameters) != len(candidate_pipe_list):
+        missing = sorted(set(candidate_pipe_list) - set(diameters.index))
+        preview = ", ".join(map(str, missing[:10]))
+        raise ValueError(f"Missing or invalid diameter for pipes: {preview}")
+
+    max_diameter = float(diameters.max())
+    max_diameter_pipes = sorted(
+        [pipe for pipe, diameter in diameters.items() if float(diameter) == max_diameter],
+        key=str,
+    )
+    return max_diameter_pipes[0]
+
+
+def pick_dual_center_pipes(
+    node_x, node_y, candidate_pipe, pipe_start_node, pipe_end_node, pipe_diameter
+):
+    geometric_center = pick_center_pipe(
+        node_x, node_y, candidate_pipe, pipe_start_node, pipe_end_node
+    )
+    diameter_center = pick_max_diameter_pipe(candidate_pipe, pipe_diameter)
+    return _dedupe_preserve_order([geometric_center, diameter_center])
+
+
+def find_new_center_pipe(
+    node_x,
+    node_y,
+    candidate_pipe,
+    pipe_start_node,
+    pipe_end_node,
+    pipe_diameter,
+    record_center,
+):
+    new_candidate_pipe = sorted(set(candidate_pipe) - set(record_center))
+    if new_candidate_pipe == []:
+        new_candidate_pipe = candidate_pipe
+    center_t = pick_center_pipe(
+        node_x,
+        node_y,
+        new_candidate_pipe,
+        pipe_start_node,
+        pipe_end_node,
+    )
+    return center_t
+
+
+def cal_area_node_linked_pipe(nodeset, node_pipe_dic):
+    pipeset = []
+    for temp_node in nodeset:
+        pipeset.extend(node_pipe_dic[temp_node])
+    return pipeset
+
+
+def metis_grouping_pipe_weight(
+    G0,
+    wn,
+    all_node_iter,
+    candidate_pipe_input,
+    group_num,
+    node_x,
+    node_y,
+    pipe_start_node_all,
+    pipe_end_node_all,
+    node_pipe_dic,
+    all_node_series,
+    couple_node_length,
+    pipe_diameter,
+):
+    all_node_iter_series_new = all_node_series[all_node_iter]
+    all_node_iter_series_new = all_node_iter_series_new.sort_values(ascending=True)
+    all_node_iter_new = list(all_node_iter_series_new.index)
+
+    G1 = G0.subgraph(all_node_iter_new)
+    delimiter = " "
+    adjacency_list = []
+    node_dict = {}
+    c_new = 0
+    for each_node in all_node_iter_new:
+        node_dict[each_node] = c_new
+        c_new = c_new + 1
+    correspond_dic = {}
+    count_node = 0
+    w = []
+    for node_name in all_node_iter_new:
+        neighbors = G1[node_name]
+        w_temp = []
+        n_t = [node_dict[node_name]]
+        for neighbor_name in sorted(neighbors.keys()):
+            edge_data = neighbors[neighbor_name]
+            edge_key = f"{node_name},{neighbor_name}"
+            reverse_edge_key = f"{neighbor_name},{node_name}"
+            if edge_key in couple_node_length:
+                edge_weight = couple_node_length[edge_key]
+            elif reverse_edge_key in couple_node_length:
+                edge_weight = couple_node_length[reverse_edge_key]
+            elif edge_data.get("weight") is not None:
+                edge_weight = float(edge_data["weight"])
+            else:
+                # Ignore graph edges that are outside candidate pipes and have no usable
+                # partition weight (e.g. some non-pipe links in mixed network graphs).
+                continue
+            w_temp.append(_to_metis_edge_weight(edge_weight))
+            n_t.append(node_dict[neighbor_name])
+        w.append(w_temp)
+        correspond_dic[n_t[0]] = count_node
+        count_node = count_node + 1
+        # del n_t[0]
+        adjacency_list.append(n_t)
+    adjacency_list_new = [[] * 1 for i in range(len(adjacency_list))]
+    w_new = [[] * 1 for i in range(len(adjacency_list))]
+    for i in range(len(adjacency_list)):
+        adjacency_list_new[int(adjacency_list[i][0])] = adjacency_list[i]
+        w_new[int(adjacency_list[i][0])] = w[i]
+
+    for i in range(len(adjacency_list)):
+        del adjacency_list_new[i][0]
+    xadj = [0]
+    w_f = []
+    final_adjacency_list = []
+    for i in range(len(adjacency_list_new)):
+        final_adjacency_list = final_adjacency_list + adjacency_list_new[i]
+        xadj.append(len(final_adjacency_list))
+        w_f = w_f + w_new[i]
+
+    # (edgecuts, parts) = pymetis.part_graph(nparts=group_num, adjacency=adjacency_list_new)
+    metis_options = pymetis.Options()
+    metis_options.seed = 42
+    (edgecuts, parts) = pymetis.part_graph(
+        nparts=group_num,
+        adjncy=final_adjacency_list,
+        xadj=xadj,
+        eweights=w_f,
+        options=metis_options,
+    )
+    # (edgecuts, parts) = pymetis.part_graph(nparts=group_num, adjacency=adjacency_list_new)
+    candidate_group_list = [[] * 1 for i in range(group_num)]
+    for i in range(len(all_node_iter_new)):
+        candidate_group_list[parts[i]].append(all_node_iter_new[i])
+
+    """parts_new = np.zeros(len(candidate_node_input), dtype=int)
+    for i in range(len(candidate_group_list)):
+        temp_group = candidate_group_list[i]
+        for each_node in temp_group:
+            parts_new[node_dict[each_node]] = i
+    parts_new = list(parts_new)"""
+
+    new_center = []
+    new_group = []
+    new_center_candidates = []
+    new_all_node = []
+    candidate_pipe_set = set(candidate_pipe_input)
+    all_grouped_pipe = []
+    for i in range(group_num):
+        # 构建子图
+        G_sub = G0.subgraph(candidate_group_list[i])
+
+        # 计算联通子图
+        sub_graphs = networkx.connected_components(G_sub)
+        if networkx.number_connected_components(G_sub) == 1:
+            # 求交集
+            nodeset = G_sub.nodes()
+            pipeset_set = set(cal_area_node_linked_pipe(nodeset, node_pipe_dic))
+            candidate_pipe = sorted(pipeset_set.intersection(candidate_pipe_set))
+
+            # 判断集合是否保留
+            if len(candidate_pipe) > 0:
+                # 保留 计算中心
+                center_t = pick_center_pipe(
+                    node_x,
+                    node_y,
+                    candidate_pipe,
+                    pipe_start_node_all,
+                    pipe_end_node_all,
+                )
+                center_candidates_t = pick_dual_center_pipes(
+                    node_x,
+                    node_y,
+                    candidate_pipe,
+                    pipe_start_node_all,
+                    pipe_end_node_all,
+                    pipe_diameter,
+                )
+
+                # 更新
+                new_center.append(center_t)
+                new_center_candidates.append(center_candidates_t)
+                new_group.append(candidate_pipe)
+                new_all_node.append(nodeset)
+                all_grouped_pipe = all_grouped_pipe + candidate_pipe
+        else:
+            for c in sorted(sub_graphs, key=lambda c: min(c)):
+                G_temp = G0.subgraph(c)
+                nodeset = G_temp.nodes()
+                pipeset = cal_area_node_linked_pipe(nodeset, node_pipe_dic)
+                pipeset_set = set(pipeset)
+
+                # 求交集
+                candidate_pipe = sorted(pipeset_set.intersection(candidate_pipe_set))
+                # print(len(candidate_node))
+                # 判断集合是否保留
+                if len(candidate_pipe) > 0:
+                    # 保留 计算中心
+                    center_t = pick_center_pipe(
+                        node_x,
+                        node_y,
+                        candidate_pipe,
+                        pipe_start_node_all,
+                        pipe_end_node_all,
+                    )
+                    center_candidates_t = pick_dual_center_pipes(
+                        node_x,
+                        node_y,
+                        candidate_pipe,
+                        pipe_start_node_all,
+                        pipe_end_node_all,
+                        pipe_diameter,
+                    )
+                    # 更新
+                    new_center.append(center_t)
+                    new_center_candidates.append(center_candidates_t)
+                    new_group.append(candidate_pipe)
+                    new_all_node.append(nodeset)
+                    all_grouped_pipe = all_grouped_pipe + candidate_pipe
+    record_center = []
+    c_g = 0
+    for each_group in new_group:
+        if len(each_group) < 3:
+            record_center.append(new_center[c_g])
+        c_g += 1
+    c_g = 0
+    for each_group in new_group:
+        if len(each_group) >= 3:
+            if new_center[c_g] in record_center:
+                new_center[c_g] = find_new_center_pipe(
+                    node_x,
+                    node_y,
+                    each_group,
+                    pipe_start_node_all,
+                    pipe_end_node_all,
+                    pipe_diameter,
+                    record_center,
+                )
+                new_center_candidates[c_g] = _dedupe_preserve_order(
+                    [new_center[c_g]] + list(new_center_candidates[c_g])
+                )
+            record_center.append(new_center[c_g])
+        c_g += 1
+
+    # visualize_metis_partition(
+    #     G0, new_center, new_group,
+    #     node_x, node_y,
+    #     pipe_start_node_all, pipe_end_node_all
+    # )
+    return new_center, new_group, new_all_node, new_center_candidates
+
+
+def visualize_metis_partition(
+    G,
+    center_pipes,
+    pipe_groups,
+    node_x,
+    node_y,
+    pipe_start_node_all,
+    pipe_end_node_all,
+    title: str | None = None,
+    block: bool = True,
+    pause_seconds: float | None = None,
+):
+    """
+    可视化METIS分区结果（单图模式）
+    参数：
+        G: 原始管网图(nx.Graph)
+        center_pipes: 中心管道列表(list)
+        pipe_groups: 分组管道列表(list of lists)
+        node_x: 节点X坐标字典(dict)
+        node_y: 节点Y坐标字典(dict)
+        pipe_start_node_all: 管道起点字典(dict)
+        pipe_end_node_all: 管道终点字典(dict)
+    """
+    fig = plt.figure("metis_partition_convergence", figsize=(22.51, 12.48))
+    fig.clf()
+    ax = fig.add_subplot(111)
+    if not block:
+        plt.ion()
+
+    # 生成颜色映射（自动扩展颜色数量）
+    colors = plt.cm.tab20(np.linspace(0, 1, len(pipe_groups)))
+
+    # --- 绘制背景管网（灰色半透明） ---
+    for edge in G.edges():
+        start_node, end_node = edge
+        ax.plot(
+            [node_x[start_node], node_x[end_node]],
+            [node_y[start_node], node_y[end_node]],
+            color="lightgray",
+            linewidth=0.5,
+            alpha=0.3,
+            zorder=1,  # 确保背景在底层
+        )
+
+    # --- 绘制各分区管道（彩色）---
+    legend_handles = []  # 用于图例的句柄
+    for i, (group, center) in enumerate(zip(pipe_groups, center_pipes)):
+        color = colors[i % len(colors)]  # 循环使用颜色
+
+        # 绘制分组管道
+        for pipe in group:
+            start = pipe_start_node_all[pipe]
+            end = pipe_end_node_all[pipe]
+            line = ax.plot(
+                [node_x[start], node_x[end]],
+                [node_y[start], node_y[end]],
+                color=color,
+                linewidth=2.5,
+                alpha=0.8,
+                zorder=2,
+            )
+            # 只为每个分组的第一个管道添加图例句柄
+            if pipe == group[0]:
+                legend_handles.append(line[0])
+
+        # 高亮中心管道（红色虚线）
+        if center in pipe_start_node_all and center in pipe_end_node_all:
+            start = pipe_start_node_all[center]
+            end = pipe_end_node_all[center]
+            ax.plot(
+                [node_x[start], node_x[end]],
+                [node_y[start], node_y[end]],
+                color="red",
+                linewidth=4,
+                linestyle="--",
+                dash_capstyle="round",
+                zorder=3,  # 确保中心管道在最顶层
+            )
+
+    # --- 添加图例和标注 ---
+    # 分组图例
+    if legend_handles:
+        group_labels = [f"Group {i + 1}" for i in range(len(pipe_groups))]
+        ax.legend(
+            legend_handles,
+            group_labels,
+            loc="upper right",
+            title="Partitions",
+            fontsize=8,
+            title_fontsize=10,
+        )
+
+    # 中心管道标注（可选）
+    for i, center in enumerate(center_pipes):
+        if center in pipe_start_node_all:
+            x = (
+                node_x[pipe_start_node_all[center]] + node_x[pipe_end_node_all[center]]
+            ) / 2
+            y = (
+                node_y[pipe_start_node_all[center]] + node_y[pipe_end_node_all[center]]
+            ) / 2
+            ax.text(
+                x,
+                y,
+                f"C{i + 1}",
+                color="red",
+                fontsize=10,
+                ha="center",
+                va="center",
+                bbox=dict(facecolor="white", alpha=0.8, edgecolor="none"),
+            )
+
+    # --- 图形美化 ---
+    ax.set_title(title or "Water Network Partitioning Overview", fontsize=14, pad=20)
+    ax.set_xlabel("X Coordinate", fontsize=10)
+    ax.set_ylabel("Y Coordinate", fontsize=10)
+    ax.grid(True, alpha=0.2, linestyle=":")
+    fig.tight_layout()
+
+    # 显示图形并强制刷新，避免迭代显示滞后一轮。
+    plt.show(block=block)
+    if not block:
+        fig.canvas.draw_idle()
+        fig.canvas.flush_events()
+        pause_value = 0.001 if pause_seconds is None else max(0.0, float(pause_seconds))
+        plt.pause(max(0.001, pause_value))
+    elif pause_seconds is not None:
+        plt.pause(max(0.0, float(pause_seconds)))
+    return fig
+
+
+def generate_adjlist_with_all_edges(G, delimiter):
+    for s, nbrs in G.adjacency():
+        line = str(s) + delimiter
+        for t, data in nbrs.items():
+            line += str(t) + delimiter
+        yield line[: -len(delimiter)]
+
+
+def cal_group_num(candidate_node_input, cal_group_num):
+    candidate_node_num = len(candidate_node_input)
+    if candidate_node_num > 100:
+        group_num_input = cal_group_num  # 30
+    else:
+        group_num_input = 10
+
+    return group_num_input
+
+

app/algorithms/burst_location/noise_generator.py

@@ -0,0 +1,198 @@
+"""噪声生成模块。"""
+
+import copy
+import random
+
+import numpy as np
+import pandas as pd
+
+from .leak_simulator import simple_add_leak, simple_recover_wn, simple_simulation_pf
+
+
+def add_noise_pd(data, noise_type, noise_para):
+    output_data = copy.deepcopy(data)
+    if type(output_data) == pd.core.frame.Series:
+        if noise_type == "uni":
+            for x in output_data.index:
+                noise = (np.random.random() - 0.5) * 2
+                output_data[x] = output_data[x] + noise * noise_para
+
+        elif noise_type == "gauss":
+            noise = np.random.normal(loc=0, scale=noise_para, size=output_data.shape)
+            output_data = output_data + noise
+    elif type(output_data) == pd.core.frame.DataFrame:
+        if noise_type == "uni":
+            noise = (np.random.random(size=output_data.shape) - 0.5) * 2
+            output_data = output_data + noise * noise_para
+
+        elif noise_type == "gauss":
+            noise = np.random.normal(loc=0, scale=noise_para, size=output_data.shape)
+            output_data = output_data + noise
+    return output_data
+
+
+def add_noise_number(data, noise_type, noise_para):
+    output_data = copy.deepcopy(data)
+    if noise_type == "uni":
+        noise = (np.random.random() - 0.5) * 2
+        output_data = output_data + noise * noise_para
+
+    elif noise_type == "gauss":
+        noise = random.gauss(0, noise_para)
+        output_data = output_data + noise
+    return output_data
+
+
+def add_noise_number_flow(data, noise_para_mean, noise_para_std1, noise_para_std2):
+    output_data = copy.deepcopy(data)
+    noise_flag1 = np.random.random() - 0.5
+    if noise_flag1 < 0:
+        noise = noise_para_mean - abs(np.random.normal(loc=0, scale=noise_para_std1))
+    else:
+        noise = noise_para_mean + abs(np.random.normal(loc=0, scale=noise_para_std2))
+    noise_flag2 = np.random.random() - 0.5
+    if noise_flag2 < 0:
+        noise_f = noise * (-1)
+    else:
+        noise_f = noise
+    output_data = output_data + noise_f
+    return output_data
+
+
+def produce_noise_number(noise_type, noise_para):
+    if noise_type == "uni":
+        noise = (np.random.random() - 0.5) * 2
+        noise = noise * noise_para
+    elif noise_type == "gauss":
+        noise = random.gauss(0, noise_para)
+    else:
+        noise = 0
+    return noise
+
+
+def add_noise_percentage_pd(data, noise_type, noise_para):
+    output_data = copy.deepcopy(data)
+
+    if type(output_data) == pd.core.frame.Series:
+        if noise_type == "uni":
+            for x in output_data.index:
+                noise = (np.random.random() - 0.5) * 2
+                output_data[x] = output_data[x] * (1 + noise * noise_para / 100)
+
+        elif noise_type == "gauss":
+            for x in output_data.index:
+                noise = np.random.gauss(0, noise_para)
+                output_data[x] = output_data[x] * (1 + noise / 100)
+        # std_noise = noise.std()
+    elif type(output_data) == pd.core.frame.DataFrame:
+        if noise_type == "uni":
+            noise = (np.random.random(size=output_data.shape) - 0.5) * 2
+            output_data = output_data * (1 + noise * noise_para / 100)
+
+        elif noise_type == "gauss":
+            noise = np.random.normal(loc=0, scale=noise_para, size=output_data.shape)
+            output_data = output_data * (1 + noise / 100)
+        # std_noise = noise.std().mean()
+    return output_data
+
+
+def add_noise_in_wn_pf(
+    wn,
+    pipe_c_noise,
+    timestep_list,
+    pipe_coefficient,
+    sensor_name,
+    sensor_f_name,
+    all_node,
+    basic_demand_pd,
+    noise_type,
+    noise_para,
+    leak_pipe,
+    leak_flow,
+):
+
+    wn.options.time.duration = 0
+    pipe_roughness_change = add_noise_pd(pipe_coefficient, noise_type, pipe_c_noise)
+    wn = change_para_of_wn(wn, pipe_roughness_change)
+    record_pressure = pd.DataFrame(index=timestep_list, columns=sensor_name)
+    record_flow = pd.DataFrame(index=timestep_list, columns=sensor_f_name)
+    record_noise_all = pd.DataFrame(
+        index=pd.MultiIndex.from_product([timestep_list, all_node]),
+        columns=basic_demand_pd.columns,
+    )
+    record_noise_all = record_noise_all.sort_index()
+
+    # normal 获取添加噪声后的监测点数据
+    for i in range(len(timestep_list)):
+        wn, record_noise = change_node_demand(
+            wn, basic_demand_pd, all_node, noise_type, noise_para
+        )
+        record_noise_all.loc[timestep_list[i]].loc[:, :] = record_noise
+        pressure_temp, flow_temp = simple_simulation_pf(
+            wn, sensor_name, sensor_f_name, [], []
+        )
+        record_pressure.iloc[i, :] = pressure_temp
+        record_flow.iloc[i, :] = flow_temp
+
+    # leak_simulation 获取添加漏损后的监测点数据
+    record_pressure_leak = pd.DataFrame(index=timestep_list, columns=sensor_name)
+    record_flow_leak = pd.DataFrame(index=timestep_list, columns=sensor_f_name)
+    # 改_wz_________________________________________
+    # add leak
+    wn, whole_inf, add_pipe1 = simple_add_leak(wn, leak_flow, leak_pipe)
+    # simulation
+    for i in range(len(timestep_list)):
+        record_noise = record_noise_all.loc[timestep_list[i]]
+        wn = change_node_demand_leak(wn, record_noise, all_node)
+        pressure_temp, flow_temp = simple_simulation_pf(
+            wn, sensor_name, sensor_f_name, leak_pipe, add_pipe1
+        )
+        record_pressure_leak.iloc[i, :] = pressure_temp
+        record_flow_leak.iloc[i, :] = flow_temp
+    # delete leak
+    wn = simple_recover_wn(wn, whole_inf)
+    return wn, record_pressure, record_flow, record_pressure_leak, record_flow_leak
+
+
+def change_node_demand(wn, basic_demand_pd, all_node, noise_type, noise_para):
+    # 改_wz_____________________________________
+    record_noise = pd.DataFrame(index=all_node, columns=basic_demand_pd.columns)
+    for each_node in all_node:
+        node = wn.get_node(each_node)
+        num_columns = len(basic_demand_pd.columns)
+        # 处理前N-1列（如果有）
+        for i in range(num_columns - 1):
+            # 获取原始值并添加噪声
+            record_noise.loc[each_node].iloc[i] = (
+                1 + produce_noise_number(noise_type, noise_para)
+            ) * basic_demand_pd.loc[each_node].iloc[i]
+            node.demand_timeseries_list[i].base_value = record_noise.loc[
+                each_node
+            ].iloc[i]
+        # 处理最后一列（当列数>=1时）
+        if num_columns >= 1:
+            last_col = basic_demand_pd.columns[-1]
+            original_last = basic_demand_pd.loc[each_node, last_col]
+            record_noise.loc[each_node, last_col] = original_last
+            node.demand_timeseries_list[-1].base_value = original_last
+
+    return wn, record_noise
+
+
+def change_node_demand_leak(wn, record_noise, all_node):
+    sample_node = wn.get_node(all_node[0])
+    # num_categories = len(sample_node.demand_timeseries_list)
+    num_categories = 1
+    for each in all_node:
+        node = wn.get_node(each)
+        for i in range(num_categories):
+            node.demand_timeseries_list[i].base_value = record_noise.loc[each].iloc[i]
+    return wn
+
+
+def change_para_of_wn(wn, pipe_roughness_change):
+    for pipe_name, pipe in wn.pipes():
+        pipe.roughness = pipe_roughness_change[pipe_name]
+    return wn
+
+

app/algorithms/burst_location/similarity_calculator.py

@@ -0,0 +1,858 @@
+"""相似性计算模块。"""
+
+import math
+
+import numpy as np
+import pandas as pd
+
+
+def cal_similarity_simple_return_dd(
+    similarity_mode,
+    monitor_p,
+    predict_p,
+    normal_p,
+    leak_p,
+    monitor_p_all,
+    predict_p_all,
+    normal_p_all,
+    leak_p_all,
+    important_sensor,
+    mean_dpressure,
+    dpressure_std,
+    dpressure_std_all,
+    if_gy=0,
+    cos_or_flow=1,
+):
+    # cos_or_flow 用于 CAF
+    dpressure_s = normal_p - leak_p
+    dpressure = predict_p - monitor_p
+    act_dpressure = pd.Series(dtype=object)
+    for i in range(len(leak_p.index)):
+        if dpressure_std.iloc[i] > -200:  # 0.001:
+            if if_gy == 1:
+                act_dpressure[leak_p.index[i]] = (
+                    leak_p.iloc[i] - monitor_p.iloc[i]
+                ) / dpressure_std.iloc[i]
+            else:
+                act_dpressure[leak_p.index[i]] = leak_p.iloc[i] - monitor_p.iloc[i]
+
+    if similarity_mode == "COS" or (similarity_mode == "CAF" and cos_or_flow == 1):
+
+        """if leak_p.min()<0:
+            none_flag = 1
+            similarity_cos = 0
+            similarity_dis = 0
+        else:"""
+        none_flag = 0
+        sensor_for_cos = sorted(
+            set(dpressure_s.index).intersection(set(act_dpressure.index))
+        )
+        """if len(dpressure_s) ==0 or len(dpressure) ==0:
+            jj=9
+        else:"""
+        try:
+            s1 = np.dot(
+                np.transpose(dpressure_s.loc[sensor_for_cos]),
+                dpressure.loc[sensor_for_cos],
+            )
+            s2 = np.linalg.norm(dpressure_s.loc[sensor_for_cos]) * np.linalg.norm(
+                dpressure.loc[sensor_for_cos]
+            )
+            if s2 == 0:
+                s2 = s2 + 0.0001
+            similarity_cos = s1 / s2
+            similarity_dis = 0
+        except Exception as e:
+            print(dpressure_s)
+            print(sensor_for_cos)
+            print(act_dpressure)
+            print(dpressure_std)
+            print(dpressure)
+
+    elif similarity_mode == "DIS" or (similarity_mode == "CAF" and cos_or_flow == 2):
+        """if leak_p.min()<0:
+            none_flag = 1
+        else:"""
+        none_flag = 0
+        important_sensor = sorted(
+            set(important_sensor).intersection(set(act_dpressure.index))
+        )
+        part_dpressure = dpressure_s[important_sensor] - dpressure[important_sensor]
+        similarity_pre_DIS = np.linalg.norm(part_dpressure)
+        # similarity_pre_DIS_later = 1 / (1 + similarity_pre_DIS)
+        similarity_dis = similarity_pre_DIS
+        similarity_cos = 0
+
+    elif similarity_mode == "CAD_new":
+        act_dpressure = leak_p - monitor_p
+        """if leak_p.min() < 0:
+            none_flag = 1
+            similarity_cos = 0
+            similarity_dis =0
+        else:"""
+        none_flag = 0
+        # cos
+        s1 = np.dot(np.transpose(dpressure_s), dpressure)
+        s2 = np.linalg.norm(dpressure_s) * np.linalg.norm(dpressure)
+
+        if s2 == 0:
+            s2 = s2 + 0.0001
+        similarity_cos = s1 / s2
+
+        # DIS
+        part_dpressure = act_dpressure.loc[important_sensor]
+        similarity_pre_DIS = np.linalg.norm(part_dpressure)
+        similarity_pre_DIS_later = 1 / (1 + similarity_pre_DIS)
+        similarity_dis = similarity_pre_DIS
+
+    elif similarity_mode == "CAD_new_gy" or similarity_mode == "CDF":
+        # cos
+        sensor_for_cos = sorted(
+            set(dpressure_s.index).intersection(set(act_dpressure.index))
+        )
+        if len(sensor_for_cos) == 0 and len(dpressure_s) == 0:
+            similarity_cos = 0
+        elif len(sensor_for_cos) == 0 and len(dpressure_s) > 0:
+            sensor_for_cos = list(dpressure_s.index)
+            none_flag = 0
+            s1 = np.dot(
+                np.transpose(dpressure_s.loc[sensor_for_cos]),
+                dpressure.loc[sensor_for_cos],
+            )
+            s2 = np.linalg.norm(dpressure_s.loc[sensor_for_cos]) * np.linalg.norm(
+                dpressure.loc[sensor_for_cos]
+            )
+
+            if s2 == 0:
+                s2 = s2 + 0.0001
+            similarity_cos = s1 / s2
+        else:
+            none_flag = 0
+            s1 = np.dot(
+                np.transpose(dpressure_s.loc[sensor_for_cos]),
+                dpressure.loc[sensor_for_cos],
+            )
+            s2 = np.linalg.norm(dpressure_s.loc[sensor_for_cos]) * np.linalg.norm(
+                dpressure.loc[sensor_for_cos]
+            )
+
+            if s2 == 0:
+                s2 = s2 + 0.0001
+            similarity_cos = s1 / s2
+
+        # DIS
+        important_sensor_new = sorted(
+            set(important_sensor).intersection(set(act_dpressure.index))
+        )
+        if len(important_sensor_new) == 0:
+            important_sensor_new = important_sensor
+            act_dpressure = pd.Series(dtype=object)
+            for i in range(len(leak_p_all.index)):
+                # if dpressure_std.iloc [i] > -200:  # 0.001:
+                if if_gy == 1:
+                    act_dpressure[leak_p_all.index[i]] = (
+                        leak_p_all.iloc[i] - monitor_p_all.iloc[i]
+                    ) / dpressure_std_all.iloc[i]
+                else:
+                    act_dpressure[leak_p_all.index[i]] = (
+                        leak_p_all.iloc[i] - monitor_p_all.iloc[i]
+                    )
+        # part_dpressure = act_dpressure.loc[important_sensor_new]
+
+        part_dpressure = (
+            dpressure.loc[important_sensor_new] - dpressure_s.loc[important_sensor_new]
+        )
+        similarity_pre_DIS = np.linalg.norm(part_dpressure)  ## chang test
+        # part_dpressure = dpressure_s.loc[important_sensor]-dpressure.loc[important_sensor]
+        # similarity_pre_DIS = np.linalg.norm(part_dpressure)
+        # similarity_pre_DIS_later = 1 / (1 + similarity_pre_DIS)
+        similarity_dis = similarity_pre_DIS
+    elif similarity_mode == "OF":
+        # cos
+        similarity_cos = 0
+        none_flag = 0
+        # DIS
+        important_sensor_new = sorted(
+            set(important_sensor).intersection(set(act_dpressure.index))
+        )
+        if len(important_sensor_new) == 0:
+            important_sensor_new = important_sensor
+            act_dpressure = pd.Series(dtype=object)
+            for i in range(len(leak_p_all.index)):
+                # if dpressure_std.iloc [i] > -200:  # 0.001:
+                if if_gy == 1:
+                    act_dpressure[leak_p_all.index[i]] = (
+                        leak_p_all.iloc[i] - monitor_p_all.iloc[i]
+                    ) / dpressure_std_all.iloc[i]
+                else:
+                    act_dpressure[leak_p_all.index[i]] = (
+                        leak_p_all.iloc[i] - monitor_p_all.iloc[i]
+                    )
+        # part_dpressure = act_dpressure.loc[important_sensor_new]
+
+        part_dpressure = (
+            dpressure.loc[important_sensor_new] - dpressure_s.loc[important_sensor_new]
+        )
+        similarity_pre_DIS = np.linalg.norm(part_dpressure)  ## chang test
+        # part_dpressure = dpressure_s.loc[important_sensor]-dpressure.loc[important_sensor]
+        # similarity_pre_DIS = np.linalg.norm(part_dpressure)
+        # similarity_pre_DIS_later = 1 / (1 + similarity_pre_DIS)
+        similarity_dis = similarity_pre_DIS
+
+    return similarity_cos, similarity_dis, none_flag
+
+
+def adjust(
+    similarity_cos,
+    similarity_dis,
+    record_success_candidate,
+    record_success_no_candidate,
+):
+    if len(record_success_no_candidate) > 0:
+        for each in record_success_no_candidate:
+            similarity_cos[each] = similarity_cos[record_success_candidate].min() * 0.9
+            similarity_dis[each] = similarity_dis[record_success_candidate].max() * 1.1
+    return similarity_cos, similarity_dis
+
+
+def cal_sq_all_multi(
+    similarity_cos,
+    similarity_dis,
+    similarity_f,
+    candidate_pipe,
+    timestep_list_spc,
+    if_flow,
+    if_only_cos,
+    if_only_flow,
+    cos_h_input,
+    dis_h_input,
+    dis_f_h_input,
+    if_compalsive,
+    cos_sensor_num,
+    flow_sensor_num,
+):
+    """融合多种相似性并输出按时刻与候选管段组织的综合相似度。
+
+    该函数会根据模式开关（是否仅流量、是否仅 COS、是否包含流量）对
+    `similarity_cos`、`similarity_dis`、`similarity_f` 做标准化，并计算
+    权重 `sq_cos/sq_dis/sq_f` 后进行加权融合。
+
+    Args:
+        similarity_cos: 压力余弦相似性（DataFrame/Series，通常为时刻 x 候选管段）。
+        similarity_dis: 压力距离相似性（DataFrame/Series，通常为时刻 x 候选管段）。
+        similarity_f: 流量距离相似性（DataFrame/Series，通常为时刻 x 候选管段）。
+        candidate_pipe: 候选管段列表，用于输出列索引。
+        timestep_list_spc: 时刻列表，用于输出行索引。
+        if_flow: 是否启用流量相似性（1 启用，0 禁用）。
+        if_only_cos: 相似性模式标识（0: COS+DIS；1: COS；其他值按分支定义处理）。
+        if_only_flow: 是否仅使用流量相似性（1 是，0 否）。
+        cos_h_input: 外部给定的 COS 权重（强制权重模式下使用）。
+        dis_h_input: 外部给定的 DIS 权重（强制权重模式下使用）。
+        dis_f_h_input: 外部给定的流量权重（强制权重模式下使用）。
+        if_compalsive: 是否使用外部强制权重（1 使用输入权重，0 自动计算权重）。
+        cos_sensor_num: 压力传感器数量，用于权重调整。
+        flow_sensor_num: 流量传感器数量，用于权重调整。
+
+    Returns:
+        tuple[pd.DataFrame | pd.Series, float, float, float]:
+            - output_similarity_pd: 综合相似性结果。
+            - sq_cos: 最终 COS 权重。
+            - sq_dis: 最终 DIS 权重。
+            - sq_f: 最终流量权重。
+    """
+    if if_only_flow == 1:
+        similarity_f, h_f = cal_sq_single_array(
+            similarity_f.values.reshape((-1, 1)), if_direct=2
+        )
+        sq_cos = 0
+        sq_dis = 0
+        sq_f = 1
+        similarity_all = similarity_f * sq_f
+        output_similarity = similarity_all.reshape((-1, len(candidate_pipe)))
+        output_similarity_pd = pd.DataFrame(
+            output_similarity, index=timestep_list_spc, columns=candidate_pipe
+        )
+    else:
+        if if_only_cos == 0:
+            if if_flow == 1:
+                # standerdize
+                similarity_cos, h_cos = cal_sq_single_array(
+                    similarity_cos.values.reshape((-1, 1)), if_direct=1
+                )
+                similarity_dis, h_dis = cal_sq_single_array(
+                    similarity_dis.values.reshape((-1, 1)), if_direct=2
+                )
+                similarity_f, h_f = cal_sq_single_array(
+                    similarity_f.values.reshape((-1, 1)), if_direct=2
+                )
+                if if_compalsive == 1:
+                    sq_cos = cos_h_input
+                    sq_dis = dis_h_input
+                    sq_f = dis_f_h_input
+                else:
+                    """sq_cos = h_cos/(h_cos +h_dis +h_f )
+                    sq_dis = h_dis/(h_cos +h_dis +h_f )
+                    sq_f = h_f/(h_cos +h_dis +h_f )"""
+                    sq_cos, sq_dis, sq_f = add_weight_for_SQ(
+                        h_cos, h_dis, h_f, cos_sensor_num, flow_sensor_num
+                    )
+
+                    """if cos_sensor_num == 2 and sq_cos>0.2:
+                        sq_cos = 0.2
+                        sq_dis = 0.8*h_dis / (h_dis + h_f)
+                        sq_f = 0.8*h_f / (h_dis + h_f)
+                    if cos_sensor_num == 1 and sq_dis > 0.3:
+                        sq_cos = 0.1
+                        sq_dis = 0.3
+                        sq_f = 0.6"""
+                    sq_cos, sq_dis, sq_f = adjust_ratio("CDF", sq_cos, sq_dis, sq_f)
+                    if cos_sensor_num <= 1:
+                        sq_cos = 0
+                # similarity
+
+                similarity_all = (
+                    similarity_cos * sq_cos
+                    + similarity_dis * sq_dis
+                    + similarity_f * sq_f
+                )
+                output_similarity = similarity_all.reshape((-1, len(candidate_pipe)))
+                output_similarity_pd = pd.DataFrame(
+                    output_similarity, index=timestep_list_spc, columns=candidate_pipe
+                )
+            else:
+                # standerdize
+                similarity_cos, h_cos = cal_sq_single_array(
+                    similarity_cos.values.reshape((-1, 1)), if_direct=1
+                )
+                similarity_dis, h_dis = cal_sq_single_array(
+                    similarity_dis.values.reshape((-1, 1)), if_direct=2
+                )
+                if if_compalsive == 1:
+                    sq_cos = cos_h_input
+                    sq_dis = dis_h_input
+                else:
+                    sq_cos = h_cos / (h_cos + h_dis)
+                    sq_dis = h_dis / (h_cos + h_dis)
+                    if cos_sensor_num == 2 and sq_cos > 0.5:
+                        sq_cos = 0.5
+                        sq_dis = 0.5
+                    sq_cos, sq_dis, sq_f = adjust_ratio("CAD_new_gy", sq_cos, sq_dis, 0)
+                sq_f = 0
+                # similarity
+                similarity_all = similarity_cos * sq_cos + similarity_dis * sq_dis
+                output_similarity = similarity_all.reshape((-1, len(candidate_pipe)))
+                output_similarity_pd = pd.DataFrame(
+                    output_similarity, index=timestep_list_spc, columns=candidate_pipe
+                )
+        elif if_only_cos == 1:
+            if if_flow == 1:
+                # standerdize
+                similarity_cos, h_cos = cal_sq_single_array(
+                    similarity_cos.values.reshape((-1, 1)), if_direct=1
+                )
+                similarity_f, h_f = cal_sq_single_array(
+                    similarity_f.values.reshape((-1, 1)), if_direct=2
+                )
+                if if_compalsive == 1:
+                    sq_cos = cos_h_input
+                    sq_f = dis_f_h_input
+                else:
+                    sq_cos = h_cos / (h_cos + h_f)
+                    sq_f = h_f / (h_cos + h_f)
+                    sq_cos, sq_dis, sq_f = adjust_ratio("CAF", sq_cos, 0, sq_f)
+                sq_dis = 0
+                # similarity
+                similarity_all = similarity_cos * sq_cos + similarity_f * sq_f
+                output_similarity = similarity_all.reshape((-1, len(candidate_pipe)))
+                output_similarity_pd = pd.DataFrame(
+                    output_similarity, index=timestep_list_spc, columns=candidate_pipe
+                )
+
+            else:
+                sq_cos = cos_h_input
+                sq_dis = dis_h_input
+                sq_f = dis_f_h_input
+                output_similarity_pd = similarity_cos
+        else:
+            sq_cos = cos_h_input
+            sq_dis = dis_h_input
+            sq_f = dis_f_h_input
+            output_similarity_pd = 1 / (similarity_dis + 1)
+    return output_similarity_pd, sq_cos, sq_dis, sq_f
+
+
+def add_weight_for_SQ(h_cos, h_dis, h_f, sensor_cos_num, sensor_f_num):
+    h_f_new = h_f * sensor_f_num
+    if sensor_cos_num <= 1:
+        h_cos_new = 0
+        h_dis_new = h_dis * sensor_cos_num
+    else:
+        h_cos_new = h_cos * sensor_cos_num  # / 2
+        h_dis_new = h_dis * sensor_cos_num  # / 2
+    cos_sq = h_cos_new / (h_cos_new + h_dis_new + h_f_new)
+    dis_sq = h_dis_new / (h_cos_new + h_dis_new + h_f_new)
+    f_sq = h_f_new / (h_cos_new + h_dis_new + h_f_new)
+
+    if sensor_cos_num == 2 and cos_sq > 0.2:
+        cos_sq = 0.2
+        dis_sq = 0.8 * h_dis_new / (h_dis_new + h_f_new)
+        f_sq = 0.8 * h_f_new / (h_dis_new + h_f_new)
+    """if sensor_cos_num == 1:
+        if dis_sq / f_sq > sensor_cos_num/sensor_f_num:
+            dis_sq = sensor_cos_num/sensor_f_num
+            f_sq=1-dis_sq"""
+    # if h_dis_new/h_f_new > sensor_cos_num/sensor_f_num
+    return cos_sq, dis_sq, f_sq
+
+
+def cal_sq_single_array(similarity_pre, if_direct):
+    if similarity_pre.max() - similarity_pre.min() == 0:
+        similarity_pre = np.ones(similarity_pre.shape)
+    else:
+        if if_direct == 1:
+            similarity_pre = (
+                0.998
+                * (similarity_pre - similarity_pre.min())
+                / (similarity_pre.max() - similarity_pre.min())
+                + 0.002
+            )
+        else:
+            similarity_pre = (
+                0.998
+                * (similarity_pre.max() - similarity_pre)
+                / (similarity_pre.max() - similarity_pre.min())
+                + 0.002
+            )
+    # calculate pij
+    similarity_p = similarity_pre / similarity_pre.sum()
+    # cal xinxishang
+    similarity_lnp = np.zeros((len(similarity_pre), 1))
+    for j in range(len(similarity_p)):
+        similarity_lnp[j] = -similarity_p[j] * math.log(similarity_p[j], math.e)
+    h = 1 - 1 / math.log(len(similarity_pre), math.e) * similarity_lnp.sum()
+    return similarity_pre, h
+
+
+def cal_similarity_all_multi_new_sq_improve_double_lzr(
+    candidate_pipe,
+    similarity_mode,
+    pressure_leak,
+    monitor_p,
+    predict_p,
+    normal_p,
+    if_flow,
+    if_only_cos,
+    if_only_flow,
+    flow_leak,
+    monitor_f,
+    predict_f,
+    normal_f,
+    timestep_list,
+    Top_sensor_num,
+    if_gy,
+    effective_sensor,
+    cos_h,
+    dis_h,
+    dis_f_h,
+    if_compalsive,
+    max_flow,
+):
+    similarity = pd.Series(dtype=float, index=candidate_pipe)
+    similarity_detail: pd.DataFrame | None = None
+    important_p_sensor = cal_top_sensors(monitor_p, predict_p, Top_sensor_num)
+    # important_f_sensor, basic_f = cal_top_f_sensor(normal_f)
+    important_f_sensor = monitor_f.columns
+    if (
+        len(important_p_sensor) > 0 or len(important_f_sensor) > 0
+    ):  # if len(important_p_sensor) > 0
+        break_flag = 0
+        pressure_leak_new = pressure_leak.swaplevel()
+        # flow_leak_new = flow_leak.swaplevel()
+        if isinstance(flow_leak, pd.DataFrame) and len(flow_leak) > 0:
+            flow_leak_new = flow_leak.swaplevel()
+        else:
+            flow_leak_new = None
+        total_similarity_cos = pd.DataFrame(index=timestep_list, columns=candidate_pipe)
+        total_similarity_dis = pd.DataFrame(index=timestep_list, columns=candidate_pipe)
+        total_similarity_dis_f = pd.DataFrame(
+            index=timestep_list, columns=candidate_pipe
+        )
+
+        for timestep in timestep_list:
+            # cal p_cos, p_dis, f_dis
+            if if_only_flow != 1:
+                pressure_leak_temp = pressure_leak_new.loc[timestep].loc[
+                    :, effective_sensor
+                ]
+                monitor_p_temp = monitor_p.loc[timestep, effective_sensor]
+                predict_p_temp = predict_p.loc[timestep, effective_sensor]
+                normal_p_temp = normal_p.loc[timestep, effective_sensor]
+
+                (
+                    total_similarity_cos.loc[timestep, :],
+                    total_similarity_dis.loc[timestep, :],
+                ) = cal_similarity_all_cos_dis(
+                    candidate_pipe,
+                    pressure_leak_temp,
+                    similarity_mode,
+                    monitor_p_temp,
+                    predict_p_temp,
+                    normal_p_temp,
+                    pressure_leak_new.loc[timestep].loc[:, monitor_p.columns],
+                    monitor_p.loc[timestep, :],
+                    predict_p.loc[timestep, :],
+                    normal_p.loc[timestep, :],
+                    important_p_sensor,
+                    if_gy,
+                    cos_or_flow=1,
+                )
+
+            if if_flow == 1:
+                if len(timestep_list) == 1:
+                    leak_f_temp = flow_leak_new.loc[timestep].loc[:, important_f_sensor]
+                    monitor_f_temp = monitor_f.loc[timestep, important_f_sensor]
+                    predict_f_temp = predict_f.loc[timestep, important_f_sensor]
+                    normal_f_temp = normal_f.loc[timestep, important_f_sensor]
+                    basic_normal_f_temp = abs(max_flow.loc[important_f_sensor])
+
+                    leak_f_temp = leak_f_temp / basic_normal_f_temp
+                    monitor_f_temp = monitor_f_temp / basic_normal_f_temp
+                    predict_f_temp = predict_f_temp / basic_normal_f_temp
+                    normal_f_temp = normal_f_temp / basic_normal_f_temp
+
+                else:
+                    basic_f = abs(max_flow.loc[important_f_sensor])
+                    leak_f_temp = (
+                        flow_leak_new.loc[timestep].loc[:, important_f_sensor] / basic_f
+                    )
+                    monitor_f_temp = (
+                        monitor_f.loc[timestep, important_f_sensor] / basic_f
+                    )
+                    predict_f_temp = (
+                        predict_f.loc[timestep, important_f_sensor] / basic_f
+                    )
+                    normal_f_temp = normal_f.loc[timestep, important_f_sensor] / basic_f
+                _, total_similarity_dis_f.loc[timestep, :] = cal_similarity_all_cos_dis(
+                    candidate_pipe,
+                    leak_f_temp,
+                    similarity_mode,
+                    monitor_f_temp,
+                    predict_f_temp,
+                    normal_f_temp,
+                    flow_leak_new.loc[timestep].loc[:, monitor_f.columns],
+                    monitor_f.loc[timestep, :],
+                    predict_f.loc[timestep, :],
+                    normal_f.loc[timestep, :],
+                    important_f_sensor,
+                    if_gy,
+                    cos_or_flow=2,
+                )
+            else:
+                total_similarity_dis_f = []
+        similarity_all, cos_h, dis_h, dis_f_h = cal_sq_all_multi(
+            total_similarity_cos,
+            total_similarity_dis,
+            total_similarity_dis_f,
+            candidate_pipe,
+            timestep_list,
+            if_flow,
+            if_only_cos,
+            if_only_flow,
+            cos_h,
+            dis_h,
+            dis_f_h,
+            if_compalsive,
+            len(important_p_sensor),
+            len(important_f_sensor),
+        )
+        if len(timestep_list) == 1:
+            similarity = similarity_all.iloc[0]
+        elif len(timestep_list) > 3:
+            for each_candidate in candidate_pipe:
+                similarity[each_candidate] = remove_3_sigma(
+                    similarity_all.loc[:, each_candidate]
+                )
+        else:
+            for each_candidate in candidate_pipe:
+                similarity[each_candidate] = similarity_all.loc[
+                    :, each_candidate
+                ].mean()
+        similarity = similarity.sort_values(ascending=False, kind="mergesort")
+        detail_index = [str(pipe) for pipe in candidate_pipe]
+        similarity_detail = pd.DataFrame(index=detail_index)
+        similarity_detail.index.name = "pipe_id"
+        if isinstance(total_similarity_cos, pd.DataFrame) and len(total_similarity_cos) > 0:
+            pressure_cos_mean = (
+                total_similarity_cos.mean(axis=0)
+                .reindex(candidate_pipe)
+                .to_numpy(dtype=float)
+            )
+        else:
+            pressure_cos_mean = np.full(len(candidate_pipe), np.nan)
+        if isinstance(total_similarity_dis, pd.DataFrame) and len(total_similarity_dis) > 0:
+            pressure_dis_mean = (
+                total_similarity_dis.mean(axis=0)
+                .reindex(candidate_pipe)
+                .to_numpy(dtype=float)
+            )
+        else:
+            pressure_dis_mean = np.full(len(candidate_pipe), np.nan)
+        if isinstance(total_similarity_dis_f, pd.DataFrame) and len(total_similarity_dis_f) > 0:
+            flow_dis_mean = (
+                total_similarity_dis_f.mean(axis=0)
+                .reindex(candidate_pipe)
+                .to_numpy(dtype=float)
+            )
+        else:
+            flow_dis_mean = np.full(len(candidate_pipe), np.nan)
+        similarity_detail["pressure_cos_mean"] = pressure_cos_mean
+        similarity_detail["pressure_dis_mean"] = pressure_dis_mean
+        similarity_detail["flow_dis_mean"] = flow_dis_mean
+        similarity_detail["weight_cos"] = float(cos_h)
+        similarity_detail["weight_dis"] = float(dis_h)
+        similarity_detail["weight_flow"] = float(dis_f_h)
+        similarity_detail["final_similarity"] = (
+            similarity.reindex(candidate_pipe).to_numpy(dtype=float)
+        )
+        similarity_detail["similarity_rank"] = (
+            similarity_detail["final_similarity"].rank(method="dense", ascending=False)
+        ).astype(int)
+        similarity_detail["pressure_sensor_count"] = int(len(important_p_sensor))
+        similarity_detail["flow_sensor_count"] = int(len(important_f_sensor))
+        similarity_detail = similarity_detail.sort_values(
+            by="final_similarity", ascending=False, kind="mergesort"
+        )
+    else:
+        break_flag = 1
+        similarity = 0
+        cos_h = 0
+        dis_h = 0
+        dis_f_h = 0
+    return similarity, cos_h, dis_h, dis_f_h, break_flag, similarity_detail
+
+
+def cal_similarity_all_cos_dis(
+    candidate_pipe,
+    pressure_leak,
+    similarity_mode,
+    monitor_p,
+    predict_p,
+    normal_p,
+    pressure_leak_all,
+    monitor_p_all,
+    predict_p_all,
+    normal_p_all,
+    important_sensor,
+    if_gy,
+    cos_or_flow,
+):
+    similarity_cos = pd.Series(dtype=float, index=candidate_pipe)
+    similarity_dis = pd.Series(dtype=float, index=candidate_pipe)
+    dpressure = normal_p - pressure_leak
+
+    # 无用 ----------------------------------------------
+    mean_dpressure = dpressure.mean()
+
+    monitor_new = pd.DataFrame(index=["monitor"], columns=monitor_p.index)
+    monitor_new.iloc[0] = monitor_p
+    add_m_leak_pressure = [pressure_leak, monitor_p]
+    add_m_leak_pressure = pd.concat(add_m_leak_pressure)
+    pressure_leak_std = add_m_leak_pressure.std(axis=0, ddof=1)
+    pressure_leak_std = pd.Series(pressure_leak_std, index=pressure_leak.columns)
+
+    add_m_leak_pressure_all = [pressure_leak_all, monitor_p_all]
+    add_m_leak_pressure_all = pd.concat(add_m_leak_pressure_all)
+    pressure_leak_std_all = add_m_leak_pressure_all.std(axis=0, ddof=1)
+    pressure_leak_std_all = pd.Series(
+        pressure_leak_std_all, index=pressure_leak.columns
+    )
+    # 无用 ----------------------------------------------
+
+    monitor_p_temp = monitor_p
+    predict_p_temp = predict_p
+    normal_p_temp = normal_p
+    monitor_p_temp_all = monitor_p_all
+    predict_p_temp_all = predict_p_all
+    normal_p_temp_all = normal_p_all
+    record_success_candidate = []
+    record_success_no_candidate = []
+    for i in range(len(candidate_pipe)):
+        leak_p = pressure_leak.iloc[i, :]
+        leak_p_all = pressure_leak_all.iloc[i, :]
+        similarity_cos.iloc[i], similarity_dis.iloc[i], none_flag = (
+            cal_similarity_simple_return_dd(
+                similarity_mode,
+                monitor_p_temp,
+                predict_p_temp,
+                normal_p_temp,
+                leak_p,
+                monitor_p_temp_all,
+                predict_p_temp_all,
+                normal_p_temp_all,
+                leak_p_all,
+                important_sensor,
+                mean_dpressure,
+                pressure_leak_std,
+                pressure_leak_std_all,
+                if_gy,
+                cos_or_flow,
+            )
+        )
+        if none_flag == 0:
+            record_success_candidate.append(candidate_pipe[i])
+        else:
+            record_success_no_candidate.append(candidate_pipe[i])
+    similarity_cos, similarity_dis = adjust(
+        similarity_cos,
+        similarity_dis,
+        record_success_candidate,
+        record_success_no_candidate,
+    )
+    return similarity_cos, similarity_dis
+
+
+def cal_top_f_sensor(normal_f):
+    if type(normal_f) == pd.core.frame.DataFrame:
+        mean_f = normal_f.mean()
+    else:
+        mean_f = normal_f
+    output_sensor = []
+    output_normal_f = pd.Series(dtype=object)
+    for i in range(len(mean_f.index)):
+        if abs(mean_f.iloc[i]) > 0.01 / 3600:
+            output_sensor.append(mean_f.index[i])
+            output_normal_f[mean_f.index[i]] = mean_f.iloc[i]
+    return output_sensor, output_normal_f
+
+
+def cal_top_sensors(monitor_p, predict_p, Top_sensor_num):
+    dpressure = abs(predict_p - monitor_p)
+    if type(dpressure) == pd.core.frame.DataFrame:
+        dpressure = dpressure.mean()
+    dpressure_rank = dpressure.sort_values(ascending=False, kind="mergesort")
+    return list(dpressure_rank.index[:Top_sensor_num])
+
+
+def remove_3_sigma(similarity_t):
+    all_sample = len(similarity_t.index)
+    apart_sample = math.ceil(all_sample * 0.6)
+    similarity = similarity_t.astype("float")
+    mean_t = similarity.mean()
+    std_t = similarity.std()
+    new_similarity = similarity[
+        (similarity <= mean_t + 3 * std_t) & (similarity >= mean_t - 3 * std_t)
+    ]
+    mean_t_new = new_similarity.mean()
+    return mean_t_new
+
+
+def update_similarity(leak_candidate_center, similarity, leak_center_dict):
+    similarity_new = pd.Series(dtype=float)
+    for each_center in leak_candidate_center:
+        houxuan_center = leak_center_dict[each_center]
+        if len(houxuan_center) > 1:
+            temp_similarity = similarity[houxuan_center]
+            similarity_new[each_center] = temp_similarity.max()
+        else:
+            if type(similarity[each_center]) == pd.core.series.Series:
+                similarity_new[each_center] = similarity[each_center].mean()
+            else:
+                similarity_new[each_center] = similarity[each_center]
+    similarity_new = similarity_new.sort_values(ascending=False, kind="mergesort")
+    return similarity_new
+
+
+def extra_judge(
+    similarity, min_candidates_to_prune: int = 200, std_relax_factor: float = 0.5
+):
+    if len(similarity.index) == 0:
+        return 1.0, similarity
+    if len(similarity.index) < int(min_candidates_to_prune):
+        return 1.0, similarity
+
+    mean_similarity = float(similarity.mean())
+    std_similarity = float(similarity.std())
+    if not math.isfinite(std_similarity):
+        std_similarity = 0.0
+
+    threshold = mean_similarity - float(std_relax_factor) * std_similarity
+    out_put_similarity = similarity[similarity >= threshold - 1e-10]
+    if len(out_put_similarity.index) == 0:
+        out_put_similarity = similarity.iloc[:1]
+
+    cut_ratio = len(out_put_similarity.index) / len(similarity.index)
+    return cut_ratio, out_put_similarity
+
+
+def adjust_ratio(similarity_mode, cos_h, dis_h, dis_f_h, low_limit=0.1):
+    if similarity_mode == "CAF":
+        if cos_h < low_limit:
+            cos_h = low_limit
+            dis_f_h = 1 - cos_h
+        elif dis_f_h < low_limit:
+            dis_f_h = low_limit
+            cos_h = 1 - dis_f_h
+    elif similarity_mode == "CAD_new_gy":
+        if dis_h < low_limit:
+            dis_h = low_limit
+            cos_h = 1 - dis_h
+        elif cos_h < low_limit:
+            cos_h = low_limit
+            dis_h = 1 - cos_h
+    elif similarity_mode == "CDF":
+        normal_index = [0, 1, 2]
+        h_list = [cos_h, dis_h, dis_f_h]
+        if cos_h < low_limit:
+            h_list[0] = low_limit
+            normal_index.remove(0)
+        if dis_h < low_limit:
+            h_list[1] = low_limit
+            normal_index.remove(1)
+        if dis_f_h < low_limit:
+            h_list[2] = low_limit
+            normal_index.remove(2)
+
+        if len(normal_index) == 1:
+            h_list[normal_index[0]] = h_list[normal_index[0]] - (sum(h_list) - 1)
+        elif len(normal_index) == 2:
+            sum_list = sum(h_list)
+            multiper = 1 - (sum_list - 1) / (
+                h_list[normal_index[0]] + h_list[normal_index[1]]
+            )
+            h_list[normal_index[0]] = h_list[normal_index[0]] * multiper
+            h_list[normal_index[1]] = h_list[normal_index[1]] * multiper
+
+        cos_h, dis_h, dis_f_h = h_list[0], h_list[1], h_list[2]
+
+    return cos_h, dis_h, dis_f_h
+
+
+# 返回相似性计算的模式（不同权重），是否计算流量相似性，是否只计算cos相似性，是否只计算流量相似性。
+def decode_mode(similarity_mode):
+    if similarity_mode == "COS":
+        if_flow = 0
+        if_only_cos = 1
+        if_only_flow = 0
+    elif similarity_mode == "CAD_new_gy":
+        if_flow = 0
+        if_only_cos = 0
+        if_only_flow = 0
+    elif similarity_mode == "CDF":
+        if_flow = 1
+        if_only_cos = 0
+        if_only_flow = 0
+    elif similarity_mode == "CAF":
+        if_flow = 1
+        if_only_cos = 1
+        if_only_flow = 0
+    elif similarity_mode == "DIS":
+        if_flow = 1
+        if_only_cos = 2
+        if_only_flow = 0
+    elif similarity_mode == "OF":
+        if_flow = 1
+        if_only_cos = 0
+        if_only_flow = 1
+    return if_flow, if_only_cos, if_only_flow
+
+

app/algorithms/cleaning/__init__.py

@@ -1,7 +1,7 @@
 import os
 
-import app.algorithms.api_ex.flow_data_clean as flow_data_clean
-import app.algorithms.api_ex.pressure_data_clean as pressure_data_clean
+from app.algorithms.cleaning import flow as _flow_module
+from app.algorithms.cleaning import pressure as _pressure_module
 
 
 ############################################################
@@ -19,14 +19,15 @@ def flow_data_clean(input_csv_file: str) -> str:
     """
 
     # 提供的 input_csv_path 绝对路径，以下为 默认脚本目录下同名 CSV 文件，构建绝对路径，可根据情况修改
-    script_dir = os.path.dirname(os.path.abspath(__file__))
+    # 使用 algorithms 根目录保持与原 data_cleaning.py 一致的行为
+    script_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     input_csv_path = os.path.join(script_dir, input_csv_file)
 
     # 检查文件是否存在
     if not os.path.exists(input_csv_path):
         raise FileNotFoundError(f"指定的文件不存在: {input_csv_path}")
-    # 调用 Fdataclean.clean_flow_data_kf 函数进行数据清洗
-    out_xlsx_path = flow_data_clean.clean_flow_data_kf(input_csv_path)
+    # 调用 clean_flow_data_kf 函数进行数据清洗
+    out_xlsx_path = _flow_module.clean_flow_data_kf(input_csv_path)
     print("清洗后的数据已保存到:", out_xlsx_path)
 
 
@@ -46,12 +47,13 @@ def pressure_data_clean(input_csv_file: str) -> str:
     """
 
     # 提供的 input_csv_path 绝对路径，以下为 默认脚本目录下同名 CSV 文件，构建绝对路径，可根据情况修改
-    script_dir = os.path.dirname(os.path.abspath(__file__))
+    # 使用 algorithms 根目录保持与原 data_cleaning.py 一致的行为
+    script_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     input_csv_path = os.path.join(script_dir, input_csv_file)
 
     # 检查文件是否存在
     if not os.path.exists(input_csv_path):
         raise FileNotFoundError(f"指定的文件不存在: {input_csv_path}")
-    # 调用 Fdataclean.clean_flow_data_kf 函数进行数据清洗
-    out_xlsx_path = pressure_data_clean.clean_pressure_data_km(input_csv_path)
+    # 调用 clean_pressure_data_km 函数进行数据清洗
+    out_xlsx_path = _pressure_module.clean_pressure_data_km(input_csv_path)
     print("清洗后的数据已保存到:", out_xlsx_path)

app/algorithms/cleaning/flow.py

@@ -1,83 +1,10 @@
-# ...existing code...
 import pandas as pd
 import numpy as np
 import matplotlib.pyplot as plt
 from pykalman import KalmanFilter
 import os
 
-
-def fill_time_gaps(
-    data: pd.DataFrame,
-    time_col: str = "time",
-    freq: str = "1min",
-    short_gap_threshold: int = 10,
-) -> pd.DataFrame:
-    """
-    补齐缺失时间戳并填补数据缺口。
-
-    Args:
-        data: 包含时间列的 DataFrame
-        time_col: 时间列名（默认 'time'）
-        freq: 重采样频率（默认 '1min'）
-        short_gap_threshold: 短缺口阈值（分钟），<=此值用线性插值，>此值用前向填充
-
-    Returns:
-        补齐时间后的 DataFrame（保留原时间列格式）
-    """
-    if time_col not in data.columns:
-        raise ValueError(f"时间列 '{time_col}' 不存在于数据中")
-
-    # 解析时间列并设为索引
-    data = data.copy()
-    data[time_col] = pd.to_datetime(data[time_col], utc=True)
-    data_indexed = data.set_index(time_col)
-
-    # 生成完整时间范围
-    full_range = pd.date_range(
-        start=data_indexed.index.min(), end=data_indexed.index.max(), freq=freq
-    )
-
-    # 重索引以补齐缺失时间点，同时保留原始时间戳
-    combined_index = data_indexed.index.union(full_range).sort_values().unique()
-    data_reindexed = data_indexed.reindex(combined_index)
-
-    # 按列处理缺口
-    for col in data_reindexed.columns:
-        # 识别缺失值位置
-        is_missing = data_reindexed[col].isna()
-
-        # 计算连续缺失的长度
-        missing_groups = (is_missing != is_missing.shift()).cumsum()
-        gap_lengths = is_missing.groupby(missing_groups).transform("sum")
-
-        # 短缺口：时间插值
-        short_gap_mask = is_missing & (gap_lengths <= short_gap_threshold)
-        if short_gap_mask.any():
-            data_reindexed.loc[short_gap_mask, col] = (
-                data_reindexed[col]
-                .interpolate(method="time", limit_area="inside")
-                .loc[short_gap_mask]
-            )
-
-        # 长缺口：前向填充
-        long_gap_mask = is_missing & (gap_lengths > short_gap_threshold)
-        if long_gap_mask.any():
-            data_reindexed.loc[long_gap_mask, col] = (
-                data_reindexed[col].ffill().loc[long_gap_mask]
-            )
-
-    # 重置索引并恢复时间列（保留原格式）
-    data_result = data_reindexed.reset_index()
-    data_result.rename(columns={"index": time_col}, inplace=True)
-
-    # 保留时区信息
-    data_result[time_col] = data_result[time_col].dt.strftime("%Y-%m-%dT%H:%M:%S%z")
-    # 修正时区格式（Python的%z输出为+0000，需转为+00:00）
-    data_result[time_col] = data_result[time_col].str.replace(
-        r"(\+\d{2})(\d{2})$", r"\1:\2", regex=True
-    )
-
-    return data_result
+from app.algorithms._utils import fill_time_gaps
 
 
 def clean_flow_data_kf(

app/algorithms/cleaning/pressure.py

@@ -0,0 +1,579 @@
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import os
+
+ID_LIKE_COLUMNS = {
+    "id",
+    "device_id",
+    "node_id",
+    "sensor_id",
+    "monitor_id",
+    "junction_id",
+}
+
+
+def _normalize_time_frame(data: pd.DataFrame) -> pd.DataFrame:
+    """返回按时间排序的副本，并尽量将 time 列解析为时间类型。"""
+    data = data.copy()
+    if "time" in data.columns:
+        data["time"] = pd.to_datetime(data["time"], errors="coerce")
+        data = data.sort_values(["time"]).reset_index(drop=True)
+    return data
+
+
+def _select_pressure_columns(data: pd.DataFrame) -> tuple[list[str], list[str]]:
+    """区分需要清洗的数值列与需要原样保留的列。"""
+    value_cols: list[str] = []
+    keep_cols: list[str] = []
+    for col in data.columns:
+        if col == "time":
+            continue
+        col_key = col.lower()
+        if col_key in ID_LIKE_COLUMNS or col_key.endswith("_id"):
+            keep_cols.append(col)
+            continue
+        numeric = pd.to_numeric(data[col], errors="coerce")
+        if numeric.notna().sum() == 0 or numeric.nunique(dropna=True) <= 1:
+            keep_cols.append(col)
+        else:
+            value_cols.append(col)
+    return value_cols, keep_cols
+
+
+def _robust_scale(values: pd.Series) -> float:
+    """基于 MAD 计算稳健尺度。"""
+    series = pd.to_numeric(values, errors="coerce").dropna()
+    if series.empty:
+        return 1.0
+    median = series.median()
+    mad = (series - median).abs().median()
+    if pd.notna(mad) and mad > 0:
+        return float(1.4826 * mad)
+    iqr = series.quantile(0.75) - series.quantile(0.25)
+    if pd.notna(iqr) and iqr > 0:
+        return float(iqr / 1.349)
+    std = series.std()
+    if pd.notna(std) and std > 0:
+        return float(std)
+    return 1.0
+
+
+def _shrink_toward_baseline(observed: float, baseline: float, scale: float) -> float:
+    """把观测值向基线值收缩，scale 越小，修复越强。"""
+    if pd.isna(observed):
+        return baseline
+    if pd.isna(baseline):
+        return observed
+    diff = observed - baseline
+    weight = scale / (abs(diff) + scale)
+    return float(baseline + diff * weight)
+
+
+def _infer_time_frequency(time_values: pd.Series | pd.Index) -> pd.Timedelta:
+    """从时间序列中推断采样频率，失败时默认 15 分钟。"""
+    parsed = pd.to_datetime(pd.Series(time_values), errors="coerce").dropna().sort_values()
+    if len(parsed) < 2:
+        return pd.Timedelta(minutes=15)
+
+    diffs = parsed.diff().dropna()
+    diffs = diffs[diffs > pd.Timedelta(0)]
+    if diffs.empty:
+        return pd.Timedelta(minutes=15)
+
+    mode = diffs.mode()
+    return mode.iloc[0] if not mode.empty else diffs.median()
+
+
+def _build_local_pressure_baseline(series: pd.Series) -> pd.Series:
+    """基于局部插值与中值滤波构造平滑基线。"""
+    baseline = _safe_time_interpolate(series)
+    baseline = baseline.rolling(window=5, center=True, min_periods=1).median()
+    baseline = _safe_time_interpolate(baseline)
+    return baseline.ffill().bfill()
+
+
+def _build_seasonal_pressure_baseline(series: pd.Series) -> pd.Series:
+    """按一天内的同一时刻构造季节性基线，适合日周期压力数据。"""
+    if not isinstance(series.index, pd.DatetimeIndex):
+        return pd.Series(np.nan, index=series.index, dtype=float)
+
+    slot_labels = pd.Series(series.index.strftime("%H:%M:%S"), index=series.index)
+    return series.groupby(slot_labels).transform("median")
+
+
+def _detect_pressure_spikes(series: pd.Series, local_baseline: pd.Series) -> pd.Series:
+    """识别单点异常上升/下降尖峰，避免过度修正正常波动。"""
+    residual = series - local_baseline
+    neighbor_center = (series.shift(1) + series.shift(-1)) / 2
+    curvature = series - neighbor_center
+
+    residual_scale = max(_robust_scale(residual), 1e-6)
+    curvature_scale = max(_robust_scale(curvature), 1e-6)
+    direction_flip = ((series - series.shift(1)) * (series.shift(-1) - series) < 0).fillna(False)
+
+    return (
+        residual.abs() > 3.5 * residual_scale
+    ) & (
+        curvature.abs() > 3.0 * curvature_scale
+    ) & direction_flip
+
+
+def _fill_pressure_gaps(
+    original: pd.Series,
+    repaired: pd.Series,
+    local_baseline: pd.Series,
+    seasonal_baseline: pd.Series,
+) -> pd.Series:
+    """短缺口用局部插值，长缺口优先使用同一时刻的季节性轨迹。"""
+    missing_mask = original.isna()
+    if not missing_mask.any():
+        return repaired
+
+    gap_groups = (missing_mask != missing_mask.shift(fill_value=False)).cumsum()
+    gap_lengths = missing_mask.groupby(gap_groups).transform("sum").where(missing_mask, 0)
+
+    filled = repaired.copy()
+    short_gap_mask = missing_mask & (gap_lengths < 4)
+    long_gap_mask = missing_mask & ~short_gap_mask
+
+    filled[short_gap_mask] = local_baseline[short_gap_mask]
+    long_gap_fill = seasonal_baseline.where(seasonal_baseline.notna(), local_baseline)
+    filled[long_gap_mask] = long_gap_fill[long_gap_mask]
+    return filled
+
+
+def _clean_pressure_series(series: pd.Series) -> pd.Series:
+    """清洗单个压力时间序列。"""
+    series = pd.to_numeric(series, errors="coerce").astype(float)
+    local_baseline = _build_local_pressure_baseline(series)
+    spike_mask = _detect_pressure_spikes(series, local_baseline)
+
+    repaired = series.copy()
+    repaired[spike_mask] = local_baseline[spike_mask]
+
+    seasonal_baseline = _build_seasonal_pressure_baseline(repaired)
+    repaired = _fill_pressure_gaps(series, repaired, local_baseline, seasonal_baseline)
+
+    if repaired.isna().any():
+        repaired = repaired.where(repaired.notna(), local_baseline)
+    return repaired.ffill().bfill()
+
+
+def _format_time_column(data: pd.DataFrame) -> pd.DataFrame:
+    """统一输出时间格式，方便下游直接按 ISO 字符串解析。"""
+    if "time" not in data.columns:
+        return data
+
+    formatted = data.copy()
+    time_values = pd.to_datetime(formatted["time"], errors="coerce")
+    if time_values.isna().all():
+        return formatted
+
+    if time_values.dt.tz is not None:
+        time_strings = time_values.dt.strftime("%Y-%m-%dT%H:%M:%S%z")
+        time_strings = time_strings.str.replace(
+            r"([+-]\d{2})(\d{2})$",
+            r"\1:\2",
+            regex=True,
+        )
+    else:
+        time_strings = time_values.dt.strftime("%Y-%m-%dT%H:%M:%S")
+
+    formatted["time"] = time_strings.where(time_values.notna(), formatted["time"])
+    return formatted
+
+
+def _expand_snapshot_time_grid(data: pd.DataFrame, freq: pd.Timedelta) -> pd.DataFrame:
+    """仅补齐时间轴，不提前填充值，避免长缺口丢失原始形状特征。"""
+    expanded = data.copy()
+    expanded["time"] = pd.to_datetime(expanded["time"], errors="coerce")
+    expanded = expanded.dropna(subset=["time"]).sort_values("time")
+    if expanded.empty:
+        return data
+
+    indexed = expanded.set_index("time")
+    full_index = pd.date_range(indexed.index.min(), indexed.index.max(), freq=freq)
+    indexed = indexed.reindex(full_index)
+    indexed.index.name = "time"
+    return indexed.reset_index()
+
+
+def _safe_datetime_index(values: pd.Series | pd.Index | list[object]) -> pd.DatetimeIndex | None:
+    """尽量把时间值标准化为 DatetimeIndex；失败则返回 None。"""
+    parsed = pd.to_datetime(values, errors="coerce")
+    try:
+        datetime_index = pd.DatetimeIndex(parsed)
+    except (TypeError, ValueError):
+        return None
+
+    if datetime_index.isna().all():
+        return None
+    return datetime_index
+
+
+def _safe_time_interpolate(series: pd.Series) -> pd.Series:
+    """仅在索引确实是 DatetimeIndex 时使用 time interpolation。"""
+    if isinstance(series.index, pd.DatetimeIndex):
+        return series.interpolate(method="time", limit_direction="both")
+    return series.interpolate(limit_direction="both")
+
+
+def _detect_long_form_identifier(data: pd.DataFrame, value_cols: list[str], keep_cols: list[str]) -> str | None:
+    """识别 time/id/value 长表结构。"""
+    if "time" not in data.columns or len(value_cols) != 1:
+        return None
+
+    identifier_candidates = [
+        col
+        for col in keep_cols
+        if col.lower() in ID_LIKE_COLUMNS or col.lower().endswith("_id")
+    ]
+    if len(identifier_candidates) != 1:
+        return None
+    if not data["time"].duplicated().any():
+        return None
+    return identifier_candidates[0]
+
+
+def _clean_long_form_pressure(
+    data: pd.DataFrame,
+    value_col: str,
+    identifier_col: str,
+    keep_cols: list[str],
+    fill_gaps: bool,
+) -> pd.DataFrame:
+    """按测点拆分 long-form 压力数据，再逐列清洗后恢复原结构。"""
+    data = _normalize_time_frame(data)
+    wide_df = (
+        data[[identifier_col, "time", value_col]]
+        .pivot(index="time", columns=identifier_col, values=value_col)
+        .reset_index()
+    )
+
+    sensor_cols = [col for col in wide_df.columns if col != "time"]
+    cleaned_wide = _clean_snapshot_pressure(wide_df, sensor_cols, keep_cols=[], fill_gaps=fill_gaps)
+
+    cleaned_long = cleaned_wide.melt(
+        id_vars="time",
+        var_name=identifier_col,
+        value_name=value_col,
+    )
+
+    passthrough_cols = [col for col in keep_cols if col != identifier_col]
+    if passthrough_cols:
+        metadata = data[[identifier_col] + passthrough_cols].drop_duplicates(subset=[identifier_col])
+        cleaned_long = cleaned_long.merge(metadata, on=identifier_col, how="left")
+
+    try:
+        cleaned_long[identifier_col] = cleaned_long[identifier_col].astype(data[identifier_col].dtype)
+    except (TypeError, ValueError):
+        pass
+
+    cleaned_long = cleaned_long.sort_values(["time", identifier_col]).reset_index(drop=True)
+    ordered_cols = ["time", identifier_col] + passthrough_cols + [value_col]
+    cleaned_long = cleaned_long[[col for col in ordered_cols if col in cleaned_long.columns]]
+    return cleaned_long
+
+
+def _build_time_slot_frame(
+    data: pd.DataFrame, value_col: str, expected_slots: int
+) -> pd.DataFrame:
+    """把重复时间点整理成 time x slot 的矩阵。"""
+    grouped = data.groupby("time", sort=True)
+    times = list(grouped.groups.keys())
+    slot_frame = pd.DataFrame(index=pd.Index(times, name="time"), columns=range(expected_slots), dtype=float)
+
+    for time_value, group in grouped:
+        values = pd.to_numeric(group[value_col], errors="coerce").tolist()
+        for slot_idx, value in enumerate(values[:expected_slots]):
+            slot_frame.loc[time_value, slot_idx] = value
+    return slot_frame
+
+
+def _slot_baseline(slot_frame: pd.DataFrame) -> pd.DataFrame:
+    """对每个槽位做时间插值和平滑，得到基线轨迹。"""
+    baseline = pd.DataFrame(index=slot_frame.index, columns=slot_frame.columns, dtype=float)
+    for col in slot_frame.columns:
+        series = slot_frame[col].astype(float)
+        series = _safe_time_interpolate(series)
+        series = series.rolling(window=5, center=True, min_periods=1).median()
+        series = _safe_time_interpolate(series).ffill().bfill()
+        baseline[col] = series
+    return baseline
+
+
+def _choose_insertion_position(
+    observed: list[float], baseline_row: pd.Series, expected_slots: int
+) -> int:
+    """为少一个观测值的时间组选择最合理的插入位置。"""
+    missing_count = expected_slots - len(observed)
+    if missing_count <= 0:
+        return 0
+
+    best_pos = 0
+    best_cost = float("inf")
+    for insert_pos in range(expected_slots):
+        cost = 0.0
+        obs_idx = 0
+        for slot_idx in range(expected_slots):
+            if slot_idx == insert_pos:
+                continue
+            obs_value = observed[obs_idx]
+            base_value = float(baseline_row.iloc[slot_idx])
+            if pd.notna(obs_value) and pd.notna(base_value):
+                cost += abs(obs_value - base_value)
+            obs_idx += 1
+        if cost < best_cost:
+            best_cost = cost
+            best_pos = insert_pos
+    return best_pos
+
+
+def _clean_repeated_timestamp_pressure(
+    data: pd.DataFrame, value_col: str, keep_cols: list[str]
+) -> pd.DataFrame:
+    """针对同一时间点重复采样的压力数据进行修复。"""
+    data = _normalize_time_frame(data)
+    grouped_sizes = data.groupby("time").size()
+    if grouped_sizes.empty:
+        return data
+
+    expected_slots = int(grouped_sizes.mode().iloc[0]) if not grouped_sizes.mode().empty else int(grouped_sizes.max())
+    expected_slots = max(expected_slots, int(grouped_sizes.max()))
+    slot_frame = _build_time_slot_frame(data, value_col, expected_slots)
+    baseline_frame = _slot_baseline(slot_frame)
+
+    residuals = slot_frame - baseline_frame
+    slot_scales = {
+        col: max(_robust_scale(residuals[col]), 1e-6) for col in residuals.columns
+    }
+
+    cleaned_rows: list[dict[str, object]] = []
+    grouped = data.groupby("time", sort=True)
+    for time_value, group in grouped:
+        observed_values = pd.to_numeric(group[value_col], errors="coerce").tolist()
+        baseline_row = baseline_frame.loc[time_value]
+        insert_pos = _choose_insertion_position(observed_values, baseline_row, expected_slots)
+
+        cleaned_values: list[float] = []
+        obs_idx = 0
+        for slot_idx in range(expected_slots):
+            if slot_idx == insert_pos and len(observed_values) < expected_slots:
+                cleaned_values.append(float(baseline_row.iloc[slot_idx]))
+                continue
+
+            if obs_idx >= len(observed_values):
+                cleaned_values.append(float(baseline_row.iloc[slot_idx]))
+                continue
+
+            observed = observed_values[obs_idx]
+            baseline = float(baseline_row.iloc[slot_idx])
+            cleaned_values.append(
+                _shrink_toward_baseline(observed, baseline, slot_scales.get(slot_idx, 1.0))
+            )
+            obs_idx += 1
+
+        # 其余字段原样保留；常量列（如 id）直接复制第一条记录即可
+        template_row = group.iloc[0].to_dict()
+        for slot_idx, cleaned_value in enumerate(cleaned_values):
+            row = dict(template_row)
+            row["time"] = time_value
+            row[value_col] = cleaned_value
+            cleaned_rows.append(row)
+
+    cleaned_df = pd.DataFrame(cleaned_rows)
+    cleaned_df = cleaned_df.sort_values(["time"]).reset_index(drop=True)
+    ordered_cols = ["time"] + keep_cols + [value_col]
+    ordered_cols = [col for col in ordered_cols if col in cleaned_df.columns]
+    remaining_cols = [col for col in cleaned_df.columns if col not in ordered_cols]
+    cleaned_df = cleaned_df[ordered_cols + remaining_cols]
+    return _format_time_column(cleaned_df)
+
+
+def _clean_snapshot_pressure(
+    data: pd.DataFrame, value_cols: list[str], keep_cols: list[str], fill_gaps: bool
+) -> pd.DataFrame:
+    """针对单条时间序列或多列快照数据进行稳健修复。"""
+    data = _normalize_time_frame(data)
+    if fill_gaps and "time" in data.columns:
+        freq = _infer_time_frequency(data["time"])
+        data = _expand_snapshot_time_grid(data, freq)
+        data["time"] = pd.to_datetime(data["time"], errors="coerce")
+        data = data.sort_values(["time"]).reset_index(drop=True)
+
+    cleaned_df = data.copy()
+    time_index = (
+        _safe_datetime_index(cleaned_df["time"])
+        if "time" in cleaned_df.columns
+        else None
+    )
+    if time_index is None:
+        time_index = pd.RangeIndex(start=0, stop=len(cleaned_df))
+    for col in value_cols:
+        series = pd.Series(
+            pd.to_numeric(cleaned_df[col], errors="coerce").to_numpy(),
+            index=time_index,
+            dtype=float,
+        )
+        cleaned_df[col] = _clean_pressure_series(series).to_numpy()
+
+    ordered_cols = ["time"] + keep_cols + value_cols
+    ordered_cols = [col for col in ordered_cols if col in cleaned_df.columns]
+    remaining_cols = [col for col in cleaned_df.columns if col not in ordered_cols]
+    cleaned_df = cleaned_df[ordered_cols + remaining_cols]
+    return _format_time_column(cleaned_df)
+
+
+def clean_pressure_data_km(
+    input_csv_path: str, show_plot: bool = False, fill_gaps: bool = True
+) -> str:
+    """
+    读取输入 CSV，基于时间结构进行稳健修复。输出为 <input_basename>_cleaned.xlsx（同目录）。
+    原始数据在 sheet 'raw_pressure_data'，处理后数据在 sheet 'cleaned_pressusre_data'。
+    返回输出文件的绝对路径。
+
+    Args:
+        input_csv_path: CSV 文件路径
+        show_plot: 是否显示可视化
+        fill_gaps: 是否先补齐时间缺口（默认 True）
+    """
+    # 读取 CSV
+    input_csv_path = os.path.abspath(input_csv_path)
+    data = pd.read_csv(input_csv_path, header=0, index_col=None, encoding="utf-8")
+    data = _normalize_time_frame(data)
+    value_cols, keep_cols = _select_pressure_columns(data)
+    has_repeated_time = "time" in data.columns and data["time"].duplicated().any()
+    identifier_col = _detect_long_form_identifier(data, value_cols, keep_cols)
+
+    if identifier_col is not None:
+        data_repaired = _clean_long_form_pressure(
+            data,
+            value_cols[0],
+            identifier_col,
+            keep_cols,
+            fill_gaps,
+        )
+    elif has_repeated_time and len(value_cols) == 1:
+        data_repaired = _clean_repeated_timestamp_pressure(data, value_cols[0], keep_cols)
+    else:
+        data_repaired = _clean_snapshot_pressure(data, value_cols, keep_cols, fill_gaps)
+
+    # 可选可视化（只展示首个数值列）
+    plt.rcParams["font.sans-serif"] = ["SimHei"]
+    plt.rcParams["axes.unicode_minus"] = False
+    if show_plot and value_cols:
+        plot_col = value_cols[0]
+        if "time" in data_repaired.columns:
+            x = pd.to_datetime(data_repaired["time"], errors="coerce")
+        else:
+            x = np.arange(len(data_repaired))
+        plt.figure(figsize=(12, 6))
+        plt.plot(x, pd.to_numeric(data_repaired[plot_col], errors="coerce"), label="cleaned")
+        plt.xlabel("时间" if "time" in data_repaired.columns else "序号")
+        plt.ylabel("压力监测值")
+        plt.title(f"{plot_col} 清洗结果")
+        plt.legend()
+        plt.show()
+
+    # 保存到 Excel：两个 sheet
+    input_dir = os.path.dirname(os.path.abspath(input_csv_path))
+    input_base = os.path.splitext(os.path.basename(input_csv_path))[0]
+    output_filename = f"{input_base}_cleaned.xlsx"
+    output_path = os.path.join(input_dir, output_filename)
+
+    # 如果原始数据包含时间列，将其添加回结果
+    data_for_save = data.copy()
+    data_repaired_for_save = data_repaired.copy()
+
+    if os.path.exists(output_path):
+        os.remove(output_path)  # 覆盖同名文件
+    with pd.ExcelWriter(output_path, engine="openpyxl") as writer:
+        data_for_save.to_excel(writer, sheet_name="raw_pressure_data", index=False)
+        data_repaired_for_save.to_excel(
+            writer, sheet_name="cleaned_pressusre_data", index=False
+        )
+
+    # 返回输出文件的绝对路径
+    return os.path.abspath(output_path)
+
+
+def clean_pressure_data_df_km(data: pd.DataFrame, show_plot: bool = False) -> pd.DataFrame:
+    """
+    接收一个 DataFrame 数据结构，使用时间感知的稳健修复方法清洗压力数据。
+    返回清洗后的 DataFrame。
+
+    Args:
+        data: 输入 DataFrame（可包含 time 列）
+        show_plot: 是否显示可视化
+    """
+    # 使用传入的 DataFrame
+    data = data.copy()
+    data = _normalize_time_frame(data)
+    value_cols, keep_cols = _select_pressure_columns(data)
+    has_repeated_time = "time" in data.columns and data["time"].duplicated().any()
+    identifier_col = _detect_long_form_identifier(data, value_cols, keep_cols)
+
+    if identifier_col is not None:
+        data_repaired = _clean_long_form_pressure(
+            data,
+            value_cols[0],
+            identifier_col,
+            keep_cols,
+            fill_gaps=True,
+        )
+    elif has_repeated_time and len(value_cols) == 1:
+        data_repaired = _clean_repeated_timestamp_pressure(data, value_cols[0], keep_cols)
+    else:
+        data_repaired = _clean_snapshot_pressure(data, value_cols, keep_cols, fill_gaps=True)
+
+    if show_plot and value_cols:
+        plt.rcParams["font.sans-serif"] = ["SimHei"]
+        plt.rcParams["axes.unicode_minus"] = False
+        plot_col = value_cols[0]
+        x = pd.to_datetime(data_repaired["time"], errors="coerce") if "time" in data_repaired.columns else np.arange(len(data_repaired))
+        plt.figure(figsize=(12, 6))
+        plt.plot(x, pd.to_numeric(data_repaired[plot_col], errors="coerce"), label="cleaned")
+        plt.xlabel("时间" if "time" in data_repaired.columns else "序号")
+        plt.ylabel("压力监测值")
+        plt.title(f"{plot_col} 清洗结果")
+        plt.legend()
+        plt.show()
+
+    return data_repaired
+
+
+# 测试
+# if __name__ == "__main__":
+#     # 默认使用脚本目录下的 pressure_raw_data.csv
+#     script_dir = os.path.dirname(os.path.abspath(__file__))
+#     default_csv = os.path.join(script_dir, "pressure_raw_data.csv")
+#     out_path = clean_pressure_data_km(default_csv, show_plot=False)
+#     print("保存路径：", out_path)
+
+# 测试 clean_pressure_data_dict_km 函数
+if __name__ == "__main__":
+    import random
+
+    # 读取 szh_pressure_scada.csv 文件
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    csv_path = os.path.join(script_dir, "szh_pressure_scada.csv")
+    data = pd.read_csv(csv_path, header=0, index_col=None, encoding="utf-8")
+
+    # 排除 Time 列，随机选择 5 列
+    columns_to_exclude = ["Time"]
+    available_columns = [col for col in data.columns if col not in columns_to_exclude]
+    selected_columns = random.sample(available_columns, 5)
+
+    # 将选中的列转换为字典
+    data_dict = {col: data[col].tolist() for col in selected_columns}
+
+    print("选中的列:", selected_columns)
+    print("原始数据长度:", len(data_dict[selected_columns[0]]))
+
+    # 调用函数进行清洗
+    cleaned_dict = clean_pressure_data_df_km(data_dict, show_plot=True)
+
+    print("清洗后的字典键:", list(cleaned_dict.keys()))
+    print("清洗后的数据长度:", len(cleaned_dict[selected_columns[0]]))
+    print("测试完成：函数运行正常")

app/algorithms/health/__init__.py

@@ -0,0 +1,3 @@
+from app.algorithms.health.analyzer import PipelineHealthAnalyzer
+
+__all__ = ["PipelineHealthAnalyzer"]

app/algorithms/isolation/__init__.py

@@ -0,0 +1,3 @@
+from app.algorithms.isolation.valve import valve_isolation_analysis
+
+__all__ = ["valve_isolation_analysis"]

app/algorithms/leakage/__init__.py

@@ -0,0 +1,3 @@
+from app.algorithms.leakage.identifier import LeakageIdentifier
+
+__all__ = ["LeakageIdentifier"]

app/algorithms/leakage/identifier.py

@@ -0,0 +1,655 @@
+import wntr
+import numpy as np
+import pandas as pd
+import os
+import time
+import argparse
+from multiprocessing import Pool, cpu_count
+from typing import Any, List, Dict, Union
+
+from pymoo.core.problem import Problem
+from pymoo.core.callback import Callback
+from pymoo.algorithms.soo.nonconvex.ga import GA
+from pymoo.operators.crossover.sbx import SBX
+from pymoo.operators.mutation.pm import PM
+from pymoo.optimize import minimize as pymoo_minimize
+from pymoo.termination.default import DefaultSingleObjectiveTermination
+
+
+from app.algorithms._utils import _cleanup_temp_files
+
+_worker_data: dict[str, Any] = {}
+DEFAULT_N_WORKERS = max(1, min(cpu_count() - 1, 4))
+
+
+def _worker_init(
+    inp_path: str,
+    sensor_nodes: list[str],
+    area_ids: list[str],
+    nodes_by_area: dict[str, list[str]],
+    obs_matrix: np.ndarray,
+    q_sum: float,
+    duration_sec: float,
+    timestep_sec: float,
+) -> None:
+    global _worker_data
+    wn = wntr.network.WaterNetworkModel(inp_path)
+    wn.options.hydraulic.demand_model = "DD"
+    wn.options.time.duration = duration_sec
+    wn.options.time.hydraulic_timestep = timestep_sec
+    wn.options.time.pattern_timestep = timestep_sec
+    wn.options.time.report_timestep = timestep_sec
+
+    demand_objs_by_area = {}
+    allocatable_counts = {}
+    for area_id in area_ids:
+        demand_objs = []
+        for node_name in nodes_by_area.get(area_id, []):
+            if node_name not in wn.node_name_list:
+                continue
+            node = wn.get_node(node_name)
+            if (
+                hasattr(node, "demand_timeseries_list")
+                and len(node.demand_timeseries_list) > 0
+            ):
+                demand_objs.append(node.demand_timeseries_list[0])
+        demand_objs_by_area[area_id] = demand_objs
+        allocatable_counts[area_id] = len(demand_objs)
+
+    _worker_data = {
+        "wn": wn,
+        "sensor_nodes": sensor_nodes,
+        "area_ids": area_ids,
+        "nodes_by_area": nodes_by_area,
+        "demand_objs_by_area": demand_objs_by_area,
+        "allocatable_counts": allocatable_counts,
+        "obs_matrix": obs_matrix,
+        "q_sum": q_sum,
+    }
+
+
+def _worker_evaluate(raw_ratios: np.ndarray) -> float:
+    d = _worker_data
+    effective_ratio_map = LeakageIdentifier._effective_area_ratios(
+        raw_ratios,
+        d["area_ids"],
+        d["nodes_by_area"],
+        allocatable_counts=d["allocatable_counts"],
+    )
+
+    modifications = []
+    for area_id in d["area_ids"]:
+        ratio = effective_ratio_map.get(area_id, 0.0)
+        if ratio <= 0:
+            continue
+
+        demand_objs = d["demand_objs_by_area"].get(area_id, [])
+        if not demand_objs:
+            continue
+
+        per_node_leak = d["q_sum"] * ratio / len(demand_objs)
+        for demand_obj in demand_objs:
+            original_val = demand_obj.base_value
+            demand_obj.base_value = original_val + per_node_leak
+            modifications.append((demand_obj, original_val))
+
+    temp_dir = os.path.abspath(os.path.join("temp", "leakage"))
+    os.makedirs(temp_dir, exist_ok=True)
+    prefix = os.path.join(temp_dir, f"temp_{os.getpid()}")
+
+    try:
+        sim = wntr.sim.EpanetSimulator(d["wn"])
+        results = sim.run_sim(file_prefix=prefix)
+        sim_pressure = results.node["pressure"].loc[:, d["sensor_nodes"]]
+
+        n_steps = min(sim_pressure.shape[0], d["obs_matrix"].shape[0])
+        sim_vals = sim_pressure.values[:n_steps, :]
+        obs_vals = d["obs_matrix"][:n_steps, :]
+        diff = sim_vals - obs_vals
+
+        row_max = np.max(np.abs(diff), axis=1, keepdims=True)
+        row_max[row_max == 0] = 1.0
+        normalized_diff = diff / row_max
+        return float(np.linalg.norm(normalized_diff))
+
+    except Exception:
+        return 1e9
+
+    finally:
+        for demand_obj, original_val in modifications:
+            demand_obj.base_value = original_val
+        _cleanup_temp_files(prefix)
+
+
+class LeakageIdentifier:
+    FLOW_UNIT_TO_M3S = {
+        "m3/s": 1.0,
+        "m³/s": 1.0,
+        "m3/h": 1.0 / 3600.0,
+        "m³/h": 1.0 / 3600.0,
+        "L/s": 1.0 / 1000.0,
+        "L/min": 1.0 / 60000.0,
+    }
+
+    @classmethod
+    def _flow_to_m3s(cls, value: float, unit: str) -> float:
+        if unit not in cls.FLOW_UNIT_TO_M3S:
+            raise ValueError(f"不支持的流量单位: {unit}")
+        return float(value) * cls.FLOW_UNIT_TO_M3S[unit]
+
+    @classmethod
+    def _flow_from_m3s(cls, value_m3s: float, unit: str) -> float:
+        if unit not in cls.FLOW_UNIT_TO_M3S:
+            raise ValueError(f"不支持的流量单位: {unit}")
+        return float(value_m3s) / cls.FLOW_UNIT_TO_M3S[unit]
+
+    @staticmethod
+    def _effective_area_ratios(
+        raw_ratios: Union["np.ndarray", Dict[str, float]],
+        area_ids: List[str],
+        nodes_by_area: Dict[str, List[str]],
+        allocatable_counts: Union[Dict[str, int], None] = None,
+    ) -> Dict[str, float]:
+        """将输入比例转换为有效区域比例，确保有效区域比例和为 1。"""
+        area_count = len(area_ids)
+        if area_count == 0:
+            return {}
+
+        if isinstance(raw_ratios, dict):
+            ratios = np.array(
+                [float(raw_ratios.get(area_id, 0.0)) for area_id in area_ids],
+                dtype=float,
+            )
+        else:
+            arr = np.asarray(raw_ratios, dtype=float).reshape(-1)
+            ratios = np.zeros(area_count, dtype=float)
+            fill_len = min(area_count, arr.shape[0])
+            if fill_len > 0:
+                ratios[:fill_len] = arr[:fill_len]
+
+        # 仅保留非负比例，负值按 0 处理
+        ratios = np.clip(ratios, a_min=0.0, a_max=None)
+
+        # 仅在有效区域（存在可分配节点）内归一化
+        if allocatable_counts is not None:
+            valid_mask = np.array(
+                [int(allocatable_counts.get(area_id, 0)) > 0 for area_id in area_ids],
+                dtype=bool,
+            )
+        else:
+            valid_mask = np.array(
+                [len(nodes_by_area.get(area_id, [])) > 0 for area_id in area_ids],
+                dtype=bool,
+            )
+        if not np.any(valid_mask):
+            raise ValueError("没有可分配漏损的有效分区，无法满足漏损总量约束。")
+
+        effective = np.zeros(area_count, dtype=float)
+        valid_sum = float(np.sum(ratios[valid_mask]))
+
+        if valid_sum > 0:
+            effective[valid_mask] = ratios[valid_mask] / valid_sum
+        else:
+            # 若输入全为 0，则在有效区域内均分，保证总和仍为 1
+            valid_count = int(np.sum(valid_mask))
+            effective[valid_mask] = 1.0 / valid_count
+
+        return {area_id: float(effective[idx]) for idx, area_id in enumerate(area_ids)}
+
+    @staticmethod
+    def _normalize_area_map_df(df: pd.DataFrame) -> pd.DataFrame:
+        """标准化区域映射列名为 ID 和 Area。"""
+        if "ID" in df.columns and "Area" in df.columns:
+            return df
+
+        if "ID" in df.columns and "now" in df.columns:
+            df = df.rename(columns={"now": "Area"})
+            return df
+
+        df = df.copy()
+        df.columns = ["ID", "Area"] + list(df.columns[2:])
+        return df
+
+    def __init__(
+        self,
+        inp_path: str,
+        sensor_nodes: List[str],
+        area_map: Union[str, Dict[str, str]],
+        start_time: float = 0,
+        duration: float = 24,
+        timestep: float = 5,
+        q_sum: float = 0.2,
+    ):
+        """
+        初始化漏损识别器。
+
+        参数:
+            inp_path: EPANET .inp 文件路径。
+            sensor_nodes: 用作压力传感器的节点 ID 列表。
+            area_map: 节点到区域的映射。可以是 CSV 文件路径（列：ID, Area），也可以是字典 {NodeID: AreaID}。
+            start_time: 模拟开始时间（小时）。
+            duration: 模拟持续时间（小时）。
+            timestep: 模拟时间步长（分钟）。
+            q_sum: 假设的总漏损流量 (m3/s)。
+        """
+        self.inp_path = inp_path
+        self.sensor_nodes = sensor_nodes
+        self.start_time = start_time
+        self.duration = duration
+        self.timestep = timestep
+        self.q_sum = q_sum
+
+        # 加载管网模型（仅一次）
+        self.wn = wntr.network.WaterNetworkModel(self.inp_path)
+
+        # 优化 WNTR 设置以提高速度
+        self.wn.options.hydraulic.demand_model = "DD"
+        self.wn.options.time.duration = float(self.duration) * 3600
+        self.wn.options.time.hydraulic_timestep = float(self.timestep) * 60
+        self.wn.options.time.pattern_timestep = float(self.timestep) * 60
+        self.wn.options.time.report_timestep = float(self.timestep) * 60
+
+        # 加载区域映射
+        if isinstance(area_map, str):
+            self.area_map_df = self._load_area_map(area_map)
+        elif isinstance(area_map, dict):
+            self.area_map_df = self._normalize_area_map_df(
+                pd.DataFrame(list(area_map.items()), columns=["ID", "Area"])
+            )
+        else:
+            raise ValueError("area_map 必须是 CSV 文件路径或字典。")
+
+        self.area_ids = sorted(self.area_map_df["Area"].unique())
+        self.num_areas = len(self.area_ids)
+
+        # 按区域对节点进行预分类，以便更快查找
+        self.nodes_by_area = {
+            area: self.area_map_df[self.area_map_df["Area"] == area]["ID"].tolist()
+            for area in self.area_ids
+        }
+
+    def _load_area_map(self, path: str) -> pd.DataFrame:
+        """加载并验证节点-区域映射文件。"""
+        df = pd.read_csv(path, dtype={"ID": str, "Area": str})
+        return self._normalize_area_map_df(df)
+
+    def run_identification(
+        self,
+        observed_pressure_data: Union[
+            str, pd.DataFrame, Dict[str, List[Any]], List[Dict[str, Any]]
+        ],
+        output_dir: str = "Results",
+        pop_size: int = 50,
+        max_gen: int = 100,
+        output_flow_unit: str = "m3/s",
+        save_result: bool = True,
+        ftol: float = 1e-3,
+        ftol_period: int = 15,
+        n_workers: int = DEFAULT_N_WORKERS,
+    ):
+        """
+        运行遗传算法以识别漏损分布。
+
+        参数:
+            observed_pressure_data: 包含 SCADA 压力数据的 CSV 文件路径或 DataFrame/字典列表数据。
+            output_dir: 结果保存目录。
+            pop_size: GA 的种群大小。
+            max_gen: GA 的最大代数。
+            output_flow_unit: 输出漏损流量的单位。
+            save_result: 是否保存识别结果到本地 CSV。
+            ftol: 目标值收敛容差（连续 ftol_period 代改善 < ftol 则停止）。
+            ftol_period: 收敛检测的窗口代数。
+            n_workers: 并行工作进程数（1=串行，>1=并行评估）。
+        """
+        if save_result:
+            os.makedirs(output_dir, exist_ok=True)
+
+        # 加载观测数据
+        if isinstance(observed_pressure_data, str):
+            obs_df = pd.read_csv(observed_pressure_data)
+            observed_name = os.path.basename(observed_pressure_data)
+        elif isinstance(observed_pressure_data, pd.DataFrame):
+            obs_df = observed_pressure_data.copy()
+            observed_name = "observed_pressure.csv"
+        else:
+            obs_df = pd.DataFrame(observed_pressure_data)
+            observed_name = "observed_pressure.csv"
+
+        # 准备 pymoo 问题实例
+        problem = LeakageProblem(
+            self.wn,
+            self.nodes_by_area,
+            self.area_ids,
+            self.sensor_nodes,
+            obs_df,
+            q_sum=self.q_sum,
+            n_workers=n_workers,
+            inp_path=os.path.abspath(self.inp_path),
+        )
+
+        # 配置 pymoo GA 算法
+        n_var = self.num_areas
+        algorithm = GA(
+            pop_size=pop_size,
+            crossover=SBX(prob=0.9, eta=15),
+            mutation=PM(prob=1.0 / max(1, n_var), eta=20),
+            eliminate_duplicates=False,
+        )
+
+        # 终止条件：收敛检测 + 最大代数
+        termination = DefaultSingleObjectiveTermination(
+            ftol=ftol,
+            period=ftol_period,
+            n_max_gen=max_gen,
+        )
+
+        # 回调：记录每代信息
+        callback = _ProgressCallback()
+
+        t0 = time.time()
+        try:
+            res = pymoo_minimize(
+                problem,
+                algorithm,
+                termination,
+                seed=42,
+                verbose=True,
+                callback=callback,
+            )
+        finally:
+            problem.close()
+        elapsed = time.time() - t0
+
+        # 提取最优解
+        best_ind = res.X  # 最优个体（漏损比例原始值）
+        best_obj = float(res.F[0])
+
+        # 输出终止信息
+        print(f"\n优化完成。耗时: {elapsed:.1f}s")
+        print(f"总代数: {res.algorithm.n_gen}, 总评估次数: {problem._eval_count}")
+        print(f"最佳目标值: {best_obj:.6f}")
+
+        # 保存到文件
+        effective_ratio_map = self._effective_area_ratios(
+            best_ind,
+            self.area_ids,
+            self.nodes_by_area,
+            allocatable_counts=problem.allocatable_counts,
+        )
+        normalized_ratios = [
+            effective_ratio_map.get(area_id, 0.0) for area_id in self.area_ids
+        ]
+        leakage_flow_m3s = [ratio * self.q_sum for ratio in normalized_ratios]
+        leakage_flow_output = [
+            self._flow_from_m3s(value_m3s, output_flow_unit)
+            for value_m3s in leakage_flow_m3s
+        ]
+
+        result_df = pd.DataFrame(
+            {
+                "Area": self.area_ids,
+                "LeakageRatioRaw": best_ind,
+                "LeakageRatio": normalized_ratios,
+                "LeakageFlow_m3_per_s": leakage_flow_m3s,
+                f"LeakageFlow_{output_flow_unit.replace('/', '_per_')}": leakage_flow_output,
+            }
+        )
+        result_path = None
+        if save_result:
+            result_path = os.path.join(
+                output_dir, f"identified_leakage_{observed_name}"
+            )
+            result_df.to_csv(result_path, index=False)
+            print(f"结果已保存至 {result_path}")
+        result_df.attrs["result_path"] = result_path
+        return result_df
+
+
+class _ProgressCallback(Callback):
+    """每代回调：记录进度。"""
+
+    def __init__(self):
+        super().__init__()
+        self.gen_times = []
+        self._t_last = None
+
+    def notify(self, algorithm):
+        now = time.time()
+        if self._t_last is not None:
+            self.gen_times.append(now - self._t_last)
+        self._t_last = now
+
+
+class LeakageProblem(Problem):
+    """pymoo 批量评估问题定义。
+
+    搜索空间：n 维 [0, 1] 实数 -> 通过 _effective_area_ratios 归一化到单纯形。
+    目标：模拟压力与观测压力之间的归一化误差范数。
+    无显式约束（sum=1 由归一化自动保证）。
+    """
+
+    def __init__(
+        self,
+        wn,
+        nodes_by_area,
+        area_ids,
+        sensor_nodes,
+        observed_data,
+        q_sum: float = 0.2,
+        n_workers: int = DEFAULT_N_WORKERS,
+        inp_path: str | None = None,
+    ):
+        n_var = len(area_ids)
+
+        super().__init__(
+            n_var=n_var,
+            n_obj=1,
+            n_ieq_constr=0,
+            xl=np.zeros(n_var),
+            xu=np.ones(n_var),
+        )
+
+        self.wn = wn
+        self.nodes_by_area = nodes_by_area
+        self.area_ids = area_ids
+        self.sensor_nodes = sensor_nodes
+        self.q_sum = q_sum
+        self.n_workers = max(1, int(n_workers))
+        self.inp_path = inp_path
+
+        # 预处理观测数据以匹配模拟格式
+        try:
+            missing_sensors = [
+                s for s in self.sensor_nodes if s not in observed_data.columns
+            ]
+            if not missing_sensors:
+                self.obs_matrix = observed_data[self.sensor_nodes].values
+            else:
+                self.obs_matrix = observed_data.values[:, : len(self.sensor_nodes)]
+        except Exception:
+            self.obs_matrix = observed_data.values[:, : len(self.sensor_nodes)]
+
+        duration_sec = float(self.wn.options.time.duration)
+        step_sec = float(self.wn.options.time.hydraulic_timestep)
+        if step_sec > 0:
+            max_steps = int(duration_sec / step_sec) + 1
+            self.obs_matrix = self.obs_matrix[:max_steps, :]
+
+        # 预先缓存每个区域的需水对象，减少每次适应度计算的节点查找
+        self.demand_objs_by_area = {}
+        for area_id in self.area_ids:
+            demand_objs = []
+            for node_name in self.nodes_by_area.get(area_id, []):
+                if node_name not in self.wn.node_name_list:
+                    continue
+                node = self.wn.get_node(node_name)
+                if (
+                    hasattr(node, "demand_timeseries_list")
+                    and len(node.demand_timeseries_list) > 0
+                ):
+                    demand_objs.append(node.demand_timeseries_list[0])
+            self.demand_objs_by_area[area_id] = demand_objs
+
+        self.allocatable_counts = {
+            area_id: len(self.demand_objs_by_area.get(area_id, []))
+            for area_id in self.area_ids
+        }
+        if not any(count > 0 for count in self.allocatable_counts.values()):
+            raise ValueError("没有可分配漏损的有效分区，无法满足漏损总量约束。")
+
+        # 评估计数器（诊断用）
+        self._eval_count = 0
+        self._pool = None
+        if self.n_workers > 1:
+            if not self.inp_path:
+                raise ValueError("并行评估需要提供 inp_path。")
+            duration_sec = float(self.wn.options.time.duration)
+            timestep_sec = float(self.wn.options.time.hydraulic_timestep)
+            self._pool = Pool(
+                processes=self.n_workers,
+                initializer=_worker_init,
+                initargs=(
+                    self.inp_path,
+                    list(self.sensor_nodes),
+                    list(self.area_ids),
+                    {k: list(v) for k, v in self.nodes_by_area.items()},
+                    self.obs_matrix.copy(),
+                    self.q_sum,
+                    duration_sec,
+                    timestep_sec,
+                ),
+            )
+
+    def _evaluate(self, X, out, *args, **kwargs):
+        """批量评估种群。
+
+        X: 形状 (pop_size, n_var) 的决策变量矩阵。
+        """
+        n_pop = X.shape[0]
+        self._eval_count += n_pop
+
+        if self._pool is not None:
+            results = self._pool.map(_worker_evaluate, [X[i] for i in range(n_pop)])
+            out["F"] = np.array(results, dtype=float).reshape(-1, 1)
+            return
+
+        F = np.zeros((n_pop, 1))
+        for i in range(n_pop):
+            F[i, 0] = self._evaluate_single(X[i])
+        out["F"] = F
+
+    def _evaluate_single(self, x):
+        """评估单个个体，返回归一化误差范数。"""
+        leak_ratios = x
+
+        # 将漏损分布归一化
+        effective_ratio_map = LeakageIdentifier._effective_area_ratios(
+            leak_ratios,
+            self.area_ids,
+            self.nodes_by_area,
+            allocatable_counts=self.allocatable_counts,
+        )
+
+        # 跟踪修改以便稍后恢复
+        modifications = []
+
+        for j, area_id in enumerate(self.area_ids):
+            ratio = effective_ratio_map.get(area_id, 0.0)
+            if ratio <= 0:
+                continue
+
+            demand_objs = self.demand_objs_by_area.get(area_id, [])
+            if not demand_objs:
+                continue
+
+            per_node_leak = self.q_sum * ratio / len(demand_objs)
+
+            for demand_obj in demand_objs:
+                original_val = demand_obj.base_value
+                demand_obj.base_value = original_val + per_node_leak
+                modifications.append((demand_obj, original_val))
+
+        # 结果保存在根目录的temp/leakage文件夹中
+        temp_dir = os.path.abspath(os.path.join("temp", "leakage"))
+        os.makedirs(temp_dir, exist_ok=True)
+        prefix = os.path.join(temp_dir, f"temp_{os.getpid()}")
+
+        try:
+            sim = wntr.sim.EpanetSimulator(self.wn)
+            results = sim.run_sim(file_prefix=prefix)
+            sim_pressure = results.node["pressure"].loc[:, self.sensor_nodes]
+
+            n_steps = min(sim_pressure.shape[0], self.obs_matrix.shape[0])
+            sim_vals = sim_pressure.values[:n_steps, :]
+            obs_vals = self.obs_matrix[:n_steps, :]
+
+            diff = sim_vals - obs_vals
+
+            # 按行最大值归一化
+            row_max = np.max(np.abs(diff), axis=1, keepdims=True)
+            row_max[row_max == 0] = 1.0  # 防止除以零
+
+            normalized_diff = diff / row_max
+
+            # 目标：归一化差值矩阵的 2-范数
+            return float(np.linalg.norm(normalized_diff))
+
+        except Exception:
+            return 1e9
+
+        finally:
+            for demand_obj, original_val in modifications:
+                demand_obj.base_value = original_val
+
+            _cleanup_temp_files(prefix)
+
+    def close(self) -> None:
+        if self._pool is not None:
+            self._pool.close()
+            self._pool.join()
+            self._pool = None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="漏损区域识别")
+    parser.add_argument("--inp", required=True, help=".inp 文件路径")
+    parser.add_argument("--map", help="节点-区域映射 CSV 路径")
+    parser.add_argument("--scada", help="SCADA 压力 CSV 路径 (观测数据)")
+    parser.add_argument("--sensors", help="传感器节点 ID 列表 (逗号分隔)")
+    parser.add_argument("--output", default="Results", help="输出目录")
+
+    parser.add_argument("--pop_size", type=int, default=50, help="种群大小")
+    parser.add_argument("--max_gen", type=int, default=100, help="最大代数")
+    parser.add_argument("--duration", type=float, default=24, help="模拟时长(小时)")
+    parser.add_argument("--q_sum", type=float, default=0.241, help="总漏损流量")
+    parser.add_argument(
+        "--q_sum_unit",
+        default="m3/s",
+        choices=list(LeakageIdentifier.FLOW_UNIT_TO_M3S.keys()),
+        help="q_sum 输入单位（建议与现场习惯一致，内部统一换算为 m3/s）",
+    )
+
+    args = parser.parse_args()
+
+    if not args.map or not args.scada or not args.sensors:
+        parser.error("--map、--scada、--sensors 为必填")
+
+    q_sum_m3s = LeakageIdentifier._flow_to_m3s(args.q_sum, args.q_sum_unit)
+
+    sensors = [sensor.strip() for sensor in args.sensors.split(",") if sensor.strip()]
+    identifier = LeakageIdentifier(
+        args.inp, sensors, args.map, duration=args.duration, q_sum=q_sum_m3s
+    )
+
+    identifier.run_identification(
+        args.scada,
+        args.output,
+        pop_size=args.pop_size,
+        max_gen=args.max_gen,
+        output_flow_unit=args.q_sum_unit,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

app/algorithms/sensor/__init__.py

@@ -1,8 +1,8 @@
 import psycopg
 
-import app.algorithms.api_ex.kmeans_sensor as kmeans_sensor
-import app.algorithms.api_ex.sensitivity as sensitivity
-from app.native.api.postgresql_info import get_pgconn_string
+from app.algorithms.sensor import kmeans as kmeans_sensor
+from app.algorithms.sensor import sensitivity
+from app.core.config import get_pgconn_string
 from app.services.tjnetwork import dump_inp
 
 

app/algorithms/sensor/kmeans.py

@@ -6,104 +6,66 @@ import sklearn.cluster
 import os
 
 
-
 class QD_KMeans(object):
     def __init__(self, wn, num_monitors):
         # self.inp = inp
-        self.cluster_num = num_monitors # 聚类中心个数，也即测压点个数
-        self.wn=wn
+        self.cluster_num = num_monitors  # 聚类中心个数，也即测压点个数
+        self.wn = wn
         self.monitor_nodes = []
         self.coords = []
         self.junction_nodes = {}  # Added missing initialization
 
-
     def get_junctions_coordinates(self):
-       
-        for junction_name in self.wn.junction_name_list: 
+
+        for junction_name in self.wn.junction_name_list:
             junction = self.wn.get_node(junction_name)
             self.junction_nodes[junction_name] = junction.coordinates
-            self.coords.append(junction.coordinates )
+            self.coords.append(junction.coordinates)
 
-        # print(f"Total junctions: {self.junction_coordinates}")   
+        # print(f"Total junctions: {self.junction_coordinates}")
 
     def select_monitoring_points(self):
         if not self.coords:  # Add check if coordinates are collected
             self.get_junctions_coordinates()
         coords = np.array(self.coords)
-        coords_normalized = (coords - coords.min(axis=0)) / (coords.max(axis=0) - coords.min(axis=0))
-        kmeans = sklearn.cluster.KMeans(n_clusters= self.cluster_num, random_state=42)
-        kmeans.fit(coords_normalized) 
+        coords_normalized = (coords - coords.min(axis=0)) / (
+            coords.max(axis=0) - coords.min(axis=0)
+        )
+        kmeans = sklearn.cluster.KMeans(n_clusters=self.cluster_num, random_state=42)
+        kmeans.fit(coords_normalized)
 
         for center in kmeans.cluster_centers_:
             distances = np.sum((coords_normalized - center) ** 2, axis=1)
             nearest_node = self.wn.junction_name_list[np.argmin(distances)]
-            self.monitor_nodes.append(nearest_node)  
+            self.monitor_nodes.append(nearest_node)
 
         return self.monitor_nodes
-    
 
     def visualize_network(self):
         """Visualize network with monitoring points"""
-        ax=wntr.graphics.plot_network(self.wn,   
-                               node_attribute=self.monitor_nodes,  
-                               node_size=30,  
-                               title='Optimal sensor') 
-        plt.show() 
+        ax = wntr.graphics.plot_network(
+            self.wn,
+            node_attribute=self.monitor_nodes,
+            node_size=30,
+            title="Optimal sensor",
+        )
+        plt.show()
 
 
-    
-    
 def kmeans_sensor_placement(name: str, sensor_num: int, min_diameter: int) -> list:
-    inp_name = f'./db_inp/{name}.db.inp'
-    wn= wntr.network.WaterNetworkModel(inp_name)
-    wn_cluster=QD_KMeans(wn, sensor_num)
+    inp_name = f"./db_inp/{name}.db.inp"
+    wn = wntr.network.WaterNetworkModel(inp_name)
+    wn_cluster = QD_KMeans(wn, sensor_num)
 
     # Select monitoring pointse
-    sensor_ids= wn_cluster.select_monitoring_points()
+    sensor_ids = wn_cluster.select_monitoring_points()
 
     # wn_cluster.visualize_network()
 
     return sensor_ids
 
 
-     
 if __name__ == "__main__":
-    #sensorindex = get_ID(name='suzhouhe_2024_cloud_0817', sensor_num=30, min_diameter=500)
-    sensorindex = kmeans_sensor_placement(name='szh', sensor_num=50, min_diameter=300)
+    # sensorindex = get_ID(name='suzhouhe_2024_cloud_0817', sensor_num=30, min_diameter=500)
+    sensorindex = kmeans_sensor_placement(name="szh", sensor_num=50, min_diameter=300)
     print(sensorindex)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

app/algorithms/sensor/sensitivity.py

@@ -11,7 +11,6 @@ from sklearn.cluster import KMeans
 from wntr.epanet.toolkit import EpanetException
 from numpy.linalg import slogdet
 import random
-from app.services.tjnetwork import *
 from matplotlib.lines import Line2D
 from sklearn.cluster import SpectralClustering
 import libpysal as ps
@@ -21,6 +20,7 @@ import geopandas as gpd
 from sklearn.metrics import pairwise_distances
 import app.services.project_info as project_info
 
+
 # 2025/03/12
 # Step1: 获取节点坐标
 def getCoor(wn: wntr.network.WaterNetworkModel) -> pandas.DataFrame:
@@ -32,7 +32,7 @@ def getCoor(wn: wntr.network.WaterNetworkModel) -> pandas.DataFrame:
     # site: pandas.Series
     #   index：节点名称（wn.node_name_list）
     #   values：每个节点的坐标，格式为 tuple（如 (x, y) 或 (x, y, z)）
-    site = wn.query_node_attribute('coordinates')
+    site = wn.query_node_attribute("coordinates")
     # Coor: pandas.Series
     #   index：与site相同（节点名称）。
     #   values：坐标转换为numpy.ndarray（如array([10.5, 20.3])）
@@ -44,9 +44,9 @@ def getCoor(wn: wntr.network.WaterNetworkModel) -> pandas.DataFrame:
         x.append(Coor.values[i][0])  # 将 x 坐标存入 x 列表。
         y.append(Coor.values[i][1])  # 将 y 坐标存入 y 列表
     # xy: dict[str, list], x、y 坐标的字典
-    xy = {'x': x, 'y': y}
+    xy = {"x": x, "y": y}
     # Coor_node: pandas.DataFrame, 存储节点 x, y 坐标的 DataFrame
-    Coor_node = pd.DataFrame(xy, index=wn.node_name_list, columns=['x', 'y'])
+    Coor_node = pd.DataFrame(xy, index=wn.node_name_list, columns=["x", "y"])
     return Coor_node
 
 
@@ -88,23 +88,23 @@ def skater_partition(G, n_clusters):
             字典形式的聚类结果，键为区域编号，值为该区域内的节点列表。
     """
     # 1. 获取所有节点坐标，假设每个节点都有 'pos' 属性
-    pos = nx.get_node_attributes(G, 'pos')
+    pos = nx.get_node_attributes(G, "pos")
     nodes = list(G.nodes())
     # 构造坐标数组：每行为 [x, y]
     coords = np.array([pos[node] for node in nodes])
 
     # 2. 构造 GeoDataFrame：创建 DataFrame 并生成 geometry 列
-    df = pd.DataFrame(coords, columns=['x', 'y'], index=nodes)
+    df = pd.DataFrame(coords, columns=["x", "y"], index=nodes)
     # 利用 shapely 的 Point 构造空间位置
-    df['geometry'] = df.apply(lambda row: Point(row['x'], row['y']), axis=1)
-    gdf = gpd.GeoDataFrame(df, geometry='geometry')
+    df["geometry"] = df.apply(lambda row: Point(row["x"], row["y"]), axis=1)
+    gdf = gpd.GeoDataFrame(df, geometry="geometry")
 
     # 3. 构造空间权重矩阵，使用 4 近邻方法（k=4，可根据实际情况调整）
     w = ps.weights.KNN.from_array(coords, k=4)
-    w.transform = 'R'
+    w.transform = "R"
 
     # 4. 调用 SKATER：新版本 API 要求传入 gdf, w 以及 attrs_name（这里使用 'x' 和 'y' 作为属性）
-    skater = Skater(gdf, w, attrs_name=['x', 'y'], n_clusters=n_clusters)
+    skater = Skater(gdf, w, attrs_name=["x", "y"], n_clusters=n_clusters)
     skater.solve()
 
     # 5. 获取聚类标签，构造成字典格式
@@ -134,24 +134,24 @@ def spectral_partition(G, n_clusters):
             键为聚类标签，值为该聚类对应的节点列表。
     """
     # 1. 获取节点空间坐标，注意保证每个节点都有 'pos' 属性
-    pos_dict = nx.get_node_attributes(G, 'pos')
+    pos_dict = nx.get_node_attributes(G, "pos")
     nodes = list(G.nodes())
     coords = np.array([pos_dict[node] for node in nodes])
 
     # 2. 计算节点之间的欧氏距离矩阵
-    D = pairwise_distances(coords, metric='euclidean')
+    D = pairwise_distances(coords, metric="euclidean")
 
     # 3. 计算 sigma 值：这里取所有距离的均值，当然也可以根据实际情况调整
     sigma = np.mean(D)
 
     # 4. 构造相似度矩阵：使用高斯核函数
     #    A(i, j) = exp( -d(i,j)^2 / (2*sigma^2) )
-    A = np.exp(- (D ** 2) / (2 * sigma ** 2))
+    A = np.exp(-(D**2) / (2 * sigma**2))
 
     # 5. 使用谱聚类进行图分区
-    clustering = SpectralClustering(n_clusters=n_clusters,
-                                    affinity='precomputed',
-                                    random_state=0)
+    clustering = SpectralClustering(
+        n_clusters=n_clusters, affinity="precomputed", random_state=0
+    )
     labels = clustering.fit_predict(A)
 
     # 6. 构造字典形式的分区结果
@@ -161,6 +161,7 @@ def spectral_partition(G, n_clusters):
 
     return groups
 
+
 # 2025/03/12
 # Step3: wn_func类，水力计算
 # wn_func 主要用于计算：
@@ -182,7 +183,7 @@ class wn_func(object):
         self.results = wntr.sim.EpanetSimulator(wn).run_sim()  # 存储运行结果
         self.wn = wn
         # self.q：pandas.DataFrame,管道流量，索引为时间步长，列为管道名称
-        self.q = self.results.link['flowrate']
+        self.q = self.results.link["flowrate"]
         # ReservoirIndex / Tankindex: list[str],水库 / 水箱节点名称列表
         ReservoirIndex = wn.reservoir_name_list
         Tankindex = wn.tank_name_list
@@ -192,7 +193,7 @@ class wn_func(object):
         # self.nodes: list[str],所有节点的名称
         self.nodes = wn.node_name_list
         # self.coordinates：pandas.Series,节点坐标，索引为节点名，值为 (x, y) 坐标的 tuple
-        self.coordinates = wn.query_node_attribute('coordinates')
+        self.coordinates = wn.query_node_attribute("coordinates")
         # allpumps / allvalves: list[str],所有泵/阀门名称列表
         allpumps = wn.pump_name_list
         allvalves = wn.valve_name_list
@@ -223,17 +224,27 @@ class wn_func(object):
         # 泵的起终点、tank、reservoir
         # self.delnodes: list[str],需要删除的节点（包括水库、泵、阀门连接的节点）
         self.delnodes = list(
-            set(ReservoirIndex).union(Tankindex, pumpstnode, pumpednode, valvestnode, valveednode, Reservoirednode))
+            set(ReservoirIndex).union(
+                Tankindex,
+                pumpstnode,
+                pumpednode,
+                valvestnode,
+                valveednode,
+                Reservoirednode,
+            )
+        )
         # 泵、起终点为tank、reservoir的管道
         # self.delpipes: list[str],需要删除的管道（包括水库、泵、阀门连接的管道）
-        self.delpipes = list(set(wn.pump_name_list).union(wn.valve_name_list).union(Reservoirpipe))
+        self.delpipes = list(
+            set(wn.pump_name_list).union(wn.valve_name_list).union(Reservoirpipe)
+        )
         self.pipes = [pipe for pipe in wn.pipe_name_list if pipe not in self.delpipes]
         # self.L: list[float],所有管道的长度（以米为单位）
-        self.L = wn.query_link_attribute('length')[self.pipes].tolist()
+        self.L = wn.query_link_attribute("length")[self.pipes].tolist()
         self.n = len(self.nodes)
         self.m = len(self.pipes)
         # self.unit_headloss: list[float],单位水头损失（headloss 数据的第一行，单位：米/km）
-        self.unit_headloss = self.results.link['headloss'].iloc[0, :].tolist()
+        self.unit_headloss = self.results.link["headloss"].iloc[0, :].tolist()
         ##
         self.delnodes1 = list(set(ReservoirIndex).union(Tankindex))
 
@@ -246,7 +257,9 @@ class wn_func(object):
                 end_node = wn.links[pipe].end_node.name
                 self.less_than_min_diameter_junction_list.extend([start_node, end_node])
         # 去重
-        self.less_than_min_diameter_junction_list = list(set(self.less_than_min_diameter_junction_list))
+        self.less_than_min_diameter_junction_list = list(
+            set(self.less_than_min_diameter_junction_list)
+        )
 
     # Step3.2: 计算水力距离
     def CtoS(self):
@@ -267,7 +280,7 @@ class wn_func(object):
         q = self.q
         L = self.L
         # H1：pandas.DataFrame,水头数据，索引为时间步长，列为节点名
-        H1 = self.results.node['head'].T
+        H1 = self.results.node["head"].T
         # hh：list[float],计算管道两端水头之差
         hh = []
         # 水头损失
@@ -281,8 +294,18 @@ class wn_func(object):
         # headloss：pandas.DataFrame,管道水头损失矩阵
         headloss = pd.DataFrame(hh, index=pipes).T
         # s1:管道阻力系数，s2：将管道阻力系数与管道的起始节点和终止节点对应
-        hf = pd.DataFrame(np.array([0] * (n ** 2)).reshape(n, n), index=nodes, columns=nodes, dtype=float)
-        weightL = pd.DataFrame(np.array([0] * (n ** 2)).reshape(n, n), index=nodes, columns=nodes, dtype=float)
+        hf = pd.DataFrame(
+            np.array([0] * (n**2)).reshape(n, n),
+            index=nodes,
+            columns=nodes,
+            dtype=float,
+        )
+        weightL = pd.DataFrame(
+            np.array([0] * (n**2)).reshape(n, n),
+            index=nodes,
+            columns=nodes,
+            dtype=float,
+        )
         # s2为对应管道起始节点与终止节点的粗糙度系数矩阵，index代表起始节点，columns代表终止节点
         G = nx.DiGraph()
         for i in range(0, m):
@@ -299,11 +322,16 @@ class wn_func(object):
                 weightL.loc[b, a] = headloss.loc[0, pipe] * L[i]
                 G.add_weighted_edges_from([(b, a, weightL.loc[b, a])])
 
-        hydraulicL = pd.DataFrame(np.array([0] * (n ** 2)).reshape(n, n), index=nodes, columns=nodes, dtype=float)
+        hydraulicL = pd.DataFrame(
+            np.array([0] * (n**2)).reshape(n, n),
+            index=nodes,
+            columns=nodes,
+            dtype=float,
+        )
 
         for a in nodes:
             if a in G.nodes:
-                d = nx.shortest_path_length(G, source=a, weight='weight')
+                d = nx.shortest_path_length(G, source=a, weight="weight")
                 for b in list(d.keys()):
                     hydraulicL.loc[a, b] = d[b]
 
@@ -332,11 +360,17 @@ class wn_func(object):
         for t in self.wn.tanks():
             self.nonjunc_index.append(t[0])
         # Conn：numpy.matrix，节点-管道连接矩阵，起点 -1，终点 1
-        Conn = np.mat(np.zeros([n, m - p - v]))  # 节点和管道的关系矩阵，行为节点，列为管道，起点为-1，终点为1
+        Conn = np.mat(
+            np.zeros([n, m - p - v])
+        )  # 节点和管道的关系矩阵，行为节点，列为管道，起点为-1，终点为1
         # NConn：numpy.matrix，节点-节点连接矩阵，有管道相连的地方设为 1
         NConn = np.mat(np.zeros([n, n]))  # 节点之间的关系，之间有管道为1，反之为0
         # pipes：list[str]，去除泵和阀门的管道列表
-        pipes = [pipe for pipe in self.wn.pipes() if pipe not in self.wn.pumps() and pipe not in self.wn.valves()]
+        pipes = [
+            pipe
+            for pipe in self.wn.pipes()
+            if pipe not in self.wn.pumps() and pipe not in self.wn.valves()
+        ]
         for pipe_name, pipe in pipes:
             start = self.wn.node_name_list.index(pipe.start_node_name)
             end = self.wn.node_name_list.index(pipe.end_node_name)
@@ -346,12 +380,21 @@ class wn_func(object):
             NConn[start, end] = 1
             NConn[end, start] = 1
         self.A = Conn
-        link_name_list = [link for link in self.wn.link_name_list if
-                          link not in self.wn.pump_name_list and link not in self.wn.valve_name_list]
-        self.A2 = pd.DataFrame(self.A, index=self.wn.node_name_list, columns=link_name_list)
+        link_name_list = [
+            link
+            for link in self.wn.link_name_list
+            if link not in self.wn.pump_name_list
+            and link not in self.wn.valve_name_list
+        ]
+        self.A2 = pd.DataFrame(
+            self.A, index=self.wn.node_name_list, columns=link_name_list
+        )
         self.A2 = self.A2.drop(self.delnodes)
         for pipe in self.delpipes:
-            if pipe not in self.wn.pump_name_list and pipe not in self.wn.valve_name_list:
+            if (
+                pipe not in self.wn.pump_name_list
+                and pipe not in self.wn.valve_name_list
+            ):
                 self.A2 = self.A2.drop(columns=pipe)
         self.junc_list = self.A2.index
         self.A2 = np.mat(self.A2)  # 节点管道关系
@@ -373,10 +416,10 @@ class wn_func(object):
         except EpanetException:
             pass
         finally:
-            h = result.link['headloss'][self.pipes].values[0]
-            q = result.link['flowrate'][self.pipes].values[0]
-            l = self.wn.query_link_attribute('length')[self.pipes]
-            C = self.wn.query_link_attribute('roughness')[self.pipes]
+            h = result.link["headloss"][self.pipes].values[0]
+            q = result.link["flowrate"][self.pipes].values[0]
+            l = self.wn.query_link_attribute("length")[self.pipes]
+            C = self.wn.query_link_attribute("roughness")[self.pipes]
             # headloss：numpy.ndarray,水头损失数组
             headloss = np.array(h)
             # 调整流量方向
@@ -394,7 +437,7 @@ class wn_func(object):
             try:
                 det = np.linalg.det(X)
             except RuntimeError as e:
-                sign, logdet = slogdet(X)   # 防止溢出
+                sign, logdet = slogdet(X)  # 防止溢出
                 det = sign * np.exp(logdet)
             if det != 0:
                 J_H_Cw = X.I * A * S
@@ -431,7 +474,10 @@ class Sensorplacement(wn_func):
     """
     Sensorplacement 类继承了 wn_func 类，并且用于计算和优化传感器布置的位置。
     """
-    def __init__(self, wn: wntr.network.WaterNetworkModel, sensornum: int, min_diameter: int):
+
+    def __init__(
+        self, wn: wntr.network.WaterNetworkModel, sensornum: int, min_diameter: int
+    ):
         """
 
         :param wn: 由wntr生成的模型
@@ -443,7 +489,9 @@ class Sensorplacement(wn_func):
 
     # 1.某个节点到所有节点的加权距离之和
     # 2.某个节点到该组内所有节点的加权距离之和
-    def sensor(self, SS: pandas.DataFrame, G: networkx.Graph, group: dict[int, list[str]]):
+    def sensor(
+        self, SS: pandas.DataFrame, G: networkx.Graph, group: dict[int, list[str]]
+    ):
         """
         sensor 方法是用来根据灵敏度矩阵 SS 和加权图 G 来确定传感器布置位置的
         :param SS: 灵敏度矩阵，每个节点的行和列代表不同节点，矩阵元素表示节点间的灵敏度。SS.iloc[i, :] 表示第 i 行对应节点 i 到所有其他节点的灵敏度
@@ -528,7 +576,7 @@ def get_ID(name: str, sensor_num: int, min_diameter: int) -> list[str]:
     :return: 测压点节点ID
     """
     # inp_file_real：str,输入文件名，表示原始水力模型文件的路径,该文件格式为 EPANET 输入文件（.inp），包含管网的结构信息、节点、管道、泵等数据
-    inp_file_real = f'./db_inp/{name}.db.inp'
+    inp_file_real = f"./db_inp/{name}.db.inp"
     # sensornum：int,需要布置的传感器数量
     # sensornum = sensor_num
     # wn_real：wntr.network.WaterNetworkModel,加载 EPANET 水力模型
@@ -539,7 +587,7 @@ def get_ID(name: str, sensor_num: int, min_diameter: int) -> list[str]:
     results_real = sim_real.run_sim()
 
     # real_C：list[float]，包含所有管道粗糙度的列表
-    real_C = wn_real.query_link_attribute('roughness').tolist()
+    real_C = wn_real.query_link_attribute("roughness").tolist()
     # wn_fun1：wn_func（继承自 object），创建 wn_func 类的实例，传入 wn_real 水力模型对象。wn_func 用于计算管网相关的水力属性，比如水力距离、灵敏度等
     wn_fun1 = wn_func(wn_real, min_diameter=min_diameter)
     # nodes：list[str]，管网的节点名称列表
@@ -599,7 +647,6 @@ def get_ID(name: str, sensor_num: int, min_diameter: int) -> list[str]:
     sensorindex, sensorindex_2 = wn_fun.sensor(SS, G, group)  # 初始的sensorindex
     # print(str(sensor_num), "个测压点，测压点位置：", sensorindex)
 
-
     # 重新打开数据库
     # if is_project_open(name=name):
     #     close_project(name=name)
@@ -638,7 +685,7 @@ def get_ID(name: str, sensor_num: int, min_diameter: int) -> list[str]:
     return sensorindex
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     sensorindex = get_ID(name=project_info.name, sensor_num=20, min_diameter=300)
 
     print(sensorindex)

app/algorithms/simulation/__init__.py

@@ -0,0 +1,19 @@
+from app.algorithms.simulation.scenarios import (
+    convert_to_local_unit,
+    burst_analysis,
+    valve_close_analysis,
+    flushing_analysis,
+    contaminant_simulation,
+    age_analysis,
+    pressure_regulation,
+)
+
+__all__ = [
+    "convert_to_local_unit",
+    "burst_analysis",
+    "valve_close_analysis",
+    "flushing_analysis",
+    "contaminant_simulation",
+    "age_analysis",
+    "pressure_regulation",
+]

app/algorithms/simulation/runner.py

@@ -1,6 +1,26 @@
 import numpy as np
-from app.services.tjnetwork import *
-from api.s36_wda_cal import *
+from app.services.tjnetwork import (
+    ChangeSet,
+    close_project,
+    copy_project,
+    delete_project,
+    get_pattern,
+    get_patterns,
+    get_pump,
+    get_reservoir,
+    get_status,
+    get_tank,
+    get_time,
+    have_project,
+    is_project_open,
+    open_project,
+    read_all,
+    run_project,
+    set_pattern,
+    set_status,
+    set_tank,
+    set_time,
+)
 # from get_real_status import *
 from datetime import datetime,timedelta
 from math import modf
@@ -9,6 +29,7 @@ import pytz
 import requests
 import time
 import app.services.project_info as project_info
+from app.services.time_api import parse_clock_duration_seconds
 
 url_path = 'http://10.101.15.16:9000/loong'  # 内网
 # url_path = 'http://183.64.62.100:9057/loong'  # 外网
@@ -531,21 +552,11 @@ def from_clock_to_seconds (clock: str)->int:
     return hr*3600+mnt*60+seconds
 
 def from_clock_to_seconds_2 (clock: str)->int:
-    str_format="%H:%M:%S"
-    dt=datetime.strptime(clock,str_format)
-    hr=dt.hour
-    mnt=dt.minute
-    seconds=dt.second
-    return hr*3600+mnt*60+seconds
+    return parse_clock_duration_seconds(clock)
 
 
 def from_clock_to_seconds_3 (clock: str)->int:
-    str_format = "%H:%M" # 更新时间格式以适应 "小时:分钟" 格式
-    dt = datetime.strptime(clock,str_format)
-    hr = dt.hour
-    mnt = dt.minute
-    seconds = dt.second
-    return hr * 3600 + mnt * 60
+    return parse_clock_duration_seconds(clock)
 
 
 ###convert datetimestring 

app/algorithms/simulation/scenarios.py

@@ -5,14 +5,39 @@ from math import pi, sqrt
 import pytz
 
 import app.services.simulation as simulation
-from app.algorithms.api_ex.run_simulation import (
+from app.algorithms.simulation.runner import (
     run_simulation_ex,
     from_clock_to_seconds_2,
 )
-from app.native.api.project import copy_project
-from app.services.epanet.epanet import Output
 from app.services.scheme_management import store_scheme_info
-from app.services.tjnetwork import *
+from app.services.tjnetwork import (
+    ChangeSet,
+    OPTION_DEMAND_MODEL_PDA,
+    OPTION_QUALITY_CHEMICAL,
+    SOURCE_TYPE_SETPOINT,
+    add_pattern,
+    add_source,
+    close_project,
+    copy_project,
+    delete_project,
+    get_demand,
+    get_emitter,
+    get_node_links,
+    get_option,
+    get_pattern,
+    get_pipe,
+    get_source,
+    get_time,
+    have_project,
+    is_junction,
+    is_project_open,
+    open_project,
+    set_demand,
+    set_emitter,
+    set_option,
+    set_source,
+    set_time,
+)
 
 
 ############################################################
@@ -47,6 +72,7 @@ def burst_analysis(
     modify_variable_pump_pattern: dict[str, list] = None,
     modify_valve_opening: dict[str, float] = None,
     scheme_name: str = None,
+    username: str | None = None,
 ) -> None:
     """
     爆管模拟
@@ -61,6 +87,9 @@ def burst_analysis(
     :param scheme_name: 方案名称
     :return:
     """
+    if not username:
+        raise ValueError("username is required when storing burst analysis scheme")
+
     scheme_detail: dict = {
         "burst_ID": burst_ID,
         "burst_size": burst_size,
@@ -186,7 +215,7 @@ def burst_analysis(
         name=name,
         scheme_name=scheme_name,
         scheme_type="burst_analysis",
-        username="admin",
+        username=username,
         scheme_start_time=modify_pattern_start_time,
         scheme_detail=scheme_detail,
     )
@@ -286,6 +315,7 @@ def flushing_analysis(
     drainage_node_ID: str = None,
     flushing_flow: float = 0,
     scheme_name: str = None,
+    username: str | None = None,
 ) -> None:
     """
     管道冲洗模拟
@@ -298,6 +328,9 @@ def flushing_analysis(
     :param scheme_name: 方案名称
     :return:
     """
+    if not username:
+        raise ValueError("username is required when storing flushing analysis scheme")
+
     scheme_detail: dict = {
         "duration": modify_total_duration,
         "valve_opening": modify_valve_opening,
@@ -430,7 +463,7 @@ def flushing_analysis(
         name=name,
         scheme_name=scheme_name,
         scheme_type="flushing_analysis",
-        username="admin",
+        username=username,
         scheme_start_time=modify_pattern_start_time,
         scheme_detail=scheme_detail,
     )
@@ -448,6 +481,7 @@ def contaminant_simulation(
     concentration: float,  # 污染源浓度，单位mg/L
     scheme_name: str = None,
     source_pattern: str = None,  # 污染源时间变化模式名称
+    username: str | None = None,
 ) -> None:
     """
     污染模拟
@@ -461,6 +495,9 @@ def contaminant_simulation(
     :param scheme_name: 方案名称
     :return:
     """
+    if not username:
+        raise ValueError("username is required when storing contaminant analysis scheme")
+
     scheme_detail: dict = {
         "source": source,
         "concentration": concentration,
@@ -583,7 +620,7 @@ def contaminant_simulation(
         name=name,
         scheme_name=scheme_name,
         scheme_type="contaminant_analysis",
-        username="admin",
+        username=username,
         scheme_start_time=modify_pattern_start_time,
         scheme_detail=scheme_detail,
     )
@@ -637,24 +674,24 @@ def age_analysis(
         new_name,
         "realtime",
         modify_pattern_start_time,
-        modify_total_duration,
+        duration=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/admin_metadata.py

@@ -0,0 +1,695 @@
+from typing import List
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Query, Response, status
+from sqlalchemy import text
+from sqlalchemy.engine.url import make_url
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.auth.metadata_dependencies import (
+    get_current_metadata_admin,
+    get_metadata_repository,
+)
+from app.core.audit import AuditAction, log_audit_event
+from app.domain.schemas.admin_metadata import (
+    AdminProjectCreateRequest,
+    AdminProjectResponse,
+    AdminProjectUpdateRequest,
+    MetadataUsersBatchSyncRequest,
+    MetadataUserResponse,
+    MetadataUserSyncRequest,
+    MetadataUserSyncResult,
+    MetadataUserUpdateRequest,
+    ProjectDatabaseHealthResponse,
+    ProjectDatabaseHealthRequest,
+    ProjectDatabaseResponse,
+    ProjectDatabaseUpsertRequest,
+    ProjectDbRole,
+    ProjectMemberCreateRequest,
+    ProjectMemberResponse,
+    ProjectMemberUpdateRequest,
+)
+from app.infra.db.metadb import models
+from app.infra.db.metadb.repositories.metadata_repository import (
+    MetadataRepository,
+    ProjectDbRouting,
+)
+
+router = APIRouter()
+
+
+def _project_response(project: models.Project) -> AdminProjectResponse:
+    return AdminProjectResponse(
+        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,
+        created_at=project.created_at,
+        updated_at=project.updated_at,
+    )
+
+
+def _project_database_response(
+    record: models.ProjectDatabase,
+) -> ProjectDatabaseResponse:
+    return ProjectDatabaseResponse(
+        id=record.id,
+        project_id=record.project_id,
+        db_role=record.db_role,
+        db_type=record.db_type,
+        pool_min_size=record.pool_min_size,
+        pool_max_size=record.pool_max_size,
+        has_dsn=bool(record.dsn_encrypted),
+    )
+
+
+def _database_audit_payload(payload: ProjectDatabaseUpsertRequest) -> dict:
+    return {
+        "db_role": payload.db_role,
+        "db_type": _db_type_for_role(payload.db_role),
+        "pool_min_size": payload.pool_min_size,
+        "pool_max_size": payload.pool_max_size,
+        "dsn_updated": payload.dsn is not None,
+    }
+
+
+def _to_async_sqlalchemy_url(dsn: str) -> str:
+    parsed = make_url(dsn)
+    if parsed.drivername in {"postgresql", "postgres"}:
+        parsed = parsed.set(drivername="postgresql+psycopg")
+    return parsed.render_as_string(hide_password=False)
+
+
+def _db_type_for_role(db_role: str) -> str:
+    if db_role == "iot_data":
+        return "timescaledb"
+    return "postgresql"
+
+
+def _status_for_config_value_error(exc: ValueError) -> int:
+    if "DATABASE_ENCRYPTION_KEY" in str(exc):
+        return status.HTTP_503_SERVICE_UNAVAILABLE
+    return status.HTTP_400_BAD_REQUEST
+
+
+async def _check_database_connection(routing: ProjectDbRouting) -> None:
+    engine = create_async_engine(
+        _to_async_sqlalchemy_url(routing.dsn),
+        pool_size=1,
+        max_overflow=0,
+        pool_pre_ping=True,
+    )
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+    finally:
+        await engine.dispose()
+
+
+def _database_health_error_detail(exc: Exception) -> str:
+    message = str(exc)
+    lower_message = message.lower()
+    if "password authentication failed" in lower_message:
+        return "连通性测试失败：用户名或密码错误，请检查 DSN 中的账号密码。"
+    if "connection refused" in lower_message:
+        return "连通性测试失败：目标主机或端口拒绝连接，请检查地址、端口和服务状态。"
+    if "timeout" in lower_message or "timed out" in lower_message:
+        return "连通性测试失败：连接超时，请检查网络、防火墙和数据库服务状态。"
+    if "could not translate host name" in lower_message or "name or service not known" in lower_message:
+        return "连通性测试失败：数据库主机名无法解析，请检查 DSN 中的主机地址。"
+    first_line = message.splitlines()[0] if message else exc.__class__.__name__
+    return f"连通性测试失败：{first_line}"
+
+
+async def _upsert_and_audit_metadata_user(
+    payload: MetadataUserSyncRequest,
+    *,
+    current_user,
+    metadata_repo: MetadataRepository,
+    response_status: int,
+) -> MetadataUserResponse:
+    user = await metadata_repo.upsert_user_from_keycloak(
+        keycloak_id=payload.keycloak_id,
+        username=payload.username,
+        email=str(payload.email),
+        role=payload.role,
+        is_active=payload.is_active,
+    )
+    await log_audit_event(
+        action=AuditAction.UPDATE,
+        user_id=current_user.id,
+        resource_type="metadata_user",
+        resource_id=str(user.id),
+        request_data=payload.model_dump(mode="json"),
+        response_status=response_status,
+        session=metadata_repo.session,
+    )
+    return MetadataUserResponse.model_validate(user)
+
+
+@router.get("/me", response_model=MetadataUserResponse)
+async def get_metadata_admin_me(
+    current_user=Depends(get_current_metadata_admin),
+) -> MetadataUserResponse:
+    return MetadataUserResponse.model_validate(current_user)
+
+
+@router.post("/users/sync", response_model=MetadataUserResponse)
+async def sync_metadata_user(
+    payload: MetadataUserSyncRequest,
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> MetadataUserResponse:
+    try:
+        return await _upsert_and_audit_metadata_user(
+            payload,
+            current_user=current_user,
+            metadata_repo=metadata_repo,
+            response_status=status.HTTP_200_OK,
+        )
+    except IntegrityError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="User keycloak_id, username, or email conflicts with an existing user",
+        ) from exc
+    except SQLAlchemyError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Metadata database error: {exc}",
+        ) from exc
+
+
+
+@router.post("/users/sync/batch", response_model=List[MetadataUserSyncResult])
+async def sync_metadata_users_batch(
+    payload: MetadataUsersBatchSyncRequest,
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> List[MetadataUserSyncResult]:
+    results: list[MetadataUserSyncResult] = []
+    for item in payload.users:
+        try:
+            user = await _upsert_and_audit_metadata_user(
+                item,
+                current_user=current_user,
+                metadata_repo=metadata_repo,
+                response_status=status.HTTP_200_OK,
+            )
+        except IntegrityError as exc:
+            results.append(
+                MetadataUserSyncResult(
+                    keycloak_id=item.keycloak_id,
+                    success=False,
+                    error="User keycloak_id, username, or email conflicts with an existing user",
+                )
+            )
+            await metadata_repo.session.rollback()
+        except SQLAlchemyError as exc:
+            results.append(
+                MetadataUserSyncResult(
+                    keycloak_id=item.keycloak_id,
+                    success=False,
+                    error=f"Metadata database error: {exc}",
+                )
+            )
+            await metadata_repo.session.rollback()
+        else:
+            results.append(
+                MetadataUserSyncResult(
+                    keycloak_id=item.keycloak_id,
+                    success=True,
+                    user=user,
+                )
+            )
+    return results
+
+
+@router.get("/users", response_model=List[MetadataUserResponse])
+async def list_metadata_users(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=1000),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> List[MetadataUserResponse]:
+    users = await metadata_repo.list_users(skip=skip, limit=limit)
+    return [MetadataUserResponse.model_validate(user) for user in users]
+
+
+@router.get("/projects", response_model=List[AdminProjectResponse])
+async def list_admin_projects(
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> List[AdminProjectResponse]:
+    projects = await metadata_repo.list_project_records()
+    return [_project_response(project) for project in projects]
+
+
+@router.post(
+    "/projects",
+    response_model=AdminProjectResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_admin_project(
+    payload: AdminProjectCreateRequest,
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> AdminProjectResponse:
+    try:
+        project = await metadata_repo.create_project(
+            name=payload.name,
+            code=payload.code,
+            description=payload.description,
+            gs_workspace=payload.gs_workspace,
+            map_extent=payload.map_extent,
+            status=payload.status,
+        )
+    except IntegrityError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Project code or workspace conflicts with an existing project",
+        ) from exc
+    except SQLAlchemyError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Metadata database error: {exc}",
+        ) from exc
+
+    await log_audit_event(
+        action=AuditAction.CREATE,
+        user_id=current_user.id,
+        project_id=project.id,
+        resource_type="project",
+        resource_id=str(project.id),
+        request_data=payload.model_dump(mode="json"),
+        response_status=status.HTTP_201_CREATED,
+        session=metadata_repo.session,
+    )
+    return _project_response(project)
+
+
+@router.patch(
+    "/projects/{project_id}",
+    response_model=AdminProjectResponse,
+)
+async def update_admin_project(
+    payload: AdminProjectUpdateRequest,
+    project_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> AdminProjectResponse:
+    updates = payload.model_dump(mode="json", exclude_unset=True)
+    try:
+        project = await metadata_repo.update_project(project_id, updates=updates)
+    except IntegrityError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Project code or workspace conflicts with an existing project",
+        ) from exc
+    except SQLAlchemyError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Metadata database error: {exc}",
+        ) from exc
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+
+    await log_audit_event(
+        action=AuditAction.UPDATE,
+        user_id=current_user.id,
+        project_id=project.id,
+        resource_type="project",
+        resource_id=str(project.id),
+        request_data=updates,
+        response_status=status.HTTP_200_OK,
+        session=metadata_repo.session,
+    )
+    return _project_response(project)
+
+
+@router.get(
+    "/projects/{project_id}/databases",
+    response_model=List[ProjectDatabaseResponse],
+)
+async def list_project_databases(
+    project_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> List[ProjectDatabaseResponse]:
+    project = await metadata_repo.get_project_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    records = await metadata_repo.list_project_databases(project_id)
+    return [_project_database_response(record) for record in records]
+
+
+@router.put(
+    "/projects/{project_id}/databases",
+    response_model=ProjectDatabaseResponse,
+)
+async def upsert_project_database(
+    payload: ProjectDatabaseUpsertRequest,
+    project_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> ProjectDatabaseResponse:
+    project = await metadata_repo.get_project_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    try:
+        routing = (
+            ProjectDbRouting(
+                project_id=project_id,
+                db_role=payload.db_role,
+                db_type=_db_type_for_role(payload.db_role),
+                dsn=payload.dsn,
+                pool_min_size=payload.pool_min_size,
+                pool_max_size=payload.pool_max_size,
+            )
+            if payload.dsn
+            else await metadata_repo.get_project_db_routing(project_id, payload.db_role)
+        )
+        if routing is None:
+            raise ValueError("dsn is required when creating project database config")
+        await _check_database_connection(routing)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=_status_for_config_value_error(exc),
+            detail=str(exc),
+        ) from exc
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=_database_health_error_detail(exc),
+        ) from exc
+
+    try:
+        record = await metadata_repo.upsert_project_database_config(
+            project_id,
+            db_role=payload.db_role,
+            db_type=_db_type_for_role(payload.db_role),
+            dsn=payload.dsn,
+            pool_min_size=payload.pool_min_size,
+            pool_max_size=payload.pool_max_size,
+        )
+    except IntegrityError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Project database role conflicts with an existing config",
+        ) from exc
+    except SQLAlchemyError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Metadata database error: {exc}",
+        ) from exc
+
+    await log_audit_event(
+        action=AuditAction.CONFIG_CHANGE,
+        user_id=current_user.id,
+        project_id=project_id,
+        resource_type="project_database",
+        resource_id=payload.db_role,
+        request_data=_database_audit_payload(payload),
+        response_status=status.HTTP_200_OK,
+        session=metadata_repo.session,
+    )
+    return _project_database_response(record)
+
+
+@router.delete(
+    "/projects/{project_id}/databases/{db_role}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_project_database(
+    project_id: UUID = Path(...),
+    db_role: ProjectDbRole = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> None:
+    removed = await metadata_repo.delete_project_database_config(project_id, db_role)
+    if not removed:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Project database config not found",
+        )
+    await log_audit_event(
+        action=AuditAction.CONFIG_CHANGE,
+        user_id=current_user.id,
+        project_id=project_id,
+        resource_type="project_database",
+        resource_id=db_role,
+        request_data={"deleted": True},
+        response_status=status.HTTP_204_NO_CONTENT,
+        session=metadata_repo.session,
+    )
+
+
+@router.post(
+    "/projects/{project_id}/databases/{db_role}/health",
+    response_model=ProjectDatabaseHealthResponse,
+)
+async def check_project_database_health(
+    response: Response,
+    project_id: UUID = Path(...),
+    db_role: ProjectDbRole = Path(...),
+    payload: ProjectDatabaseHealthRequest | None = None,
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> ProjectDatabaseHealthResponse:
+    dsn_to_test = payload.dsn if payload and payload.dsn else None
+    if dsn_to_test:
+        routing = ProjectDbRouting(
+            project_id=project_id,
+            db_role=db_role,
+            db_type=_db_type_for_role(db_role),
+            dsn=dsn_to_test,
+            pool_min_size=1,
+            pool_max_size=1,
+        )
+    else:
+        try:
+            routing = await metadata_repo.get_project_db_routing(project_id, db_role)
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=f"Project database routing DSN is invalid: {exc}",
+            ) from exc
+        if routing is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Project database config not found",
+            )
+
+    try:
+        await _check_database_connection(routing)
+    except Exception as exc:  # health endpoint should return diagnostic status
+        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        return ProjectDatabaseHealthResponse(
+            project_id=project_id,
+            db_role=db_role,
+            db_type=routing.db_type,
+            ok=False,
+            detail=_database_health_error_detail(exc),
+        )
+    return ProjectDatabaseHealthResponse(
+        project_id=project_id,
+        db_role=db_role,
+        db_type=routing.db_type,
+        ok=True,
+        detail="连通性测试通过",
+    )
+
+
+@router.get("/users/{user_id}", response_model=MetadataUserResponse)
+async def get_metadata_user(
+    user_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> MetadataUserResponse:
+    user = await metadata_repo.get_user_by_id(user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    return MetadataUserResponse.model_validate(user)
+
+
+@router.patch("/users/{user_id}", response_model=MetadataUserResponse)
+async def update_metadata_user(
+    payload: MetadataUserUpdateRequest,
+    user_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> MetadataUserResponse:
+    updates = payload.model_dump(mode="json", exclude_unset=True)
+    if user_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Users cannot modify themselves",
+        )
+    user = await metadata_repo.update_user_admin(
+        user_id,
+        updates=updates,
+    )
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    await log_audit_event(
+        action=AuditAction.UPDATE,
+        user_id=current_user.id,
+        resource_type="metadata_user",
+        resource_id=str(user.id),
+        request_data=updates,
+        response_status=status.HTTP_200_OK,
+        session=metadata_repo.session,
+    )
+    return MetadataUserResponse.model_validate(user)
+
+
+@router.get(
+    "/projects/{project_id}/members",
+    response_model=List[ProjectMemberResponse],
+)
+async def list_project_members(
+    project_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> List[ProjectMemberResponse]:
+    project = await metadata_repo.get_project_by_id(project_id)
+    if project is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Project not found"
+        )
+    members = await metadata_repo.list_project_members(project_id)
+    return [ProjectMemberResponse(**member.__dict__) for member in members]
+
+
+@router.post(
+    "/projects/{project_id}/members",
+    response_model=ProjectMemberResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def add_project_member(
+    payload: ProjectMemberCreateRequest,
+    project_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> ProjectMemberResponse:
+    if payload.user_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Users cannot modify their own project membership",
+        )
+    project = await metadata_repo.get_project_by_id(project_id)
+    if project is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Project not found"
+        )
+    user = await metadata_repo.get_user_by_id(payload.user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    existing = await metadata_repo.get_project_membership(project_id, payload.user_id)
+    if existing is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="User is already a project member",
+        )
+
+    membership = await metadata_repo.add_project_member(
+        project_id, payload.user_id, payload.project_role
+    )
+    await log_audit_event(
+        action=AuditAction.PERMISSION_CHANGE,
+        user_id=current_user.id,
+        project_id=project_id,
+        resource_type="project_member",
+        resource_id=str(payload.user_id),
+        request_data=payload.model_dump(mode="json"),
+        response_status=status.HTTP_201_CREATED,
+        session=metadata_repo.session,
+    )
+    return ProjectMemberResponse(
+        id=membership.id,
+        user_id=membership.user_id,
+        project_id=membership.project_id,
+        project_role=membership.project_role,
+        username=user.username,
+        email=user.email,
+        is_active=user.is_active,
+    )
+
+
+@router.patch(
+    "/projects/{project_id}/members/{user_id}",
+    response_model=ProjectMemberResponse,
+)
+async def update_project_member(
+    payload: ProjectMemberUpdateRequest,
+    project_id: UUID = Path(...),
+    user_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> ProjectMemberResponse:
+    if user_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Users cannot modify their own project membership",
+        )
+    user = await metadata_repo.get_user_by_id(user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    membership = await metadata_repo.update_project_member_role(
+        project_id, user_id, payload.project_role
+    )
+    if membership is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Project member not found"
+        )
+    await log_audit_event(
+        action=AuditAction.PERMISSION_CHANGE,
+        user_id=current_user.id,
+        project_id=project_id,
+        resource_type="project_member",
+        resource_id=str(user_id),
+        request_data=payload.model_dump(mode="json"),
+        response_status=status.HTTP_200_OK,
+        session=metadata_repo.session,
+    )
+    return ProjectMemberResponse(
+        id=membership.id,
+        user_id=membership.user_id,
+        project_id=membership.project_id,
+        project_role=membership.project_role,
+        username=user.username,
+        email=user.email,
+        is_active=user.is_active,
+    )
+
+
+@router.delete("/projects/{project_id}/members/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_project_member(
+    project_id: UUID = Path(...),
+    user_id: UUID = Path(...),
+    current_user=Depends(get_current_metadata_admin),
+    metadata_repo: MetadataRepository = Depends(get_metadata_repository),
+) -> None:
+    if user_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Users cannot modify their own project membership",
+        )
+    removed = await metadata_repo.remove_project_member(project_id, user_id)
+    if not removed:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Project member not found"
+        )
+    await log_audit_event(
+        action=AuditAction.PERMISSION_CHANGE,
+        user_id=current_user.id,
+        project_id=project_id,
+        resource_type="project_member",
+        resource_id=str(user_id),
+        response_status=status.HTTP_204_NO_CONTENT,
+        session=metadata_repo.session,
+    )

app/api/v1/endpoints/agent_auth.py

@@ -0,0 +1,50 @@
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from app.auth.keycloak_dependencies import get_current_keycloak_payload
+from app.auth.metadata_dependencies import get_current_metadata_user
+from app.auth.project_dependencies import (
+    ProjectContext,
+    get_project_context,
+)
+
+router = APIRouter()
+
+
+class AgentAuthContextResponse(BaseModel):
+    user_id: str
+    keycloak_sub: str
+    username: str
+    role: str
+    is_superuser: bool
+    project_id: str
+    network: str
+    project_role: str
+    token_expires_at: str | None = None
+
+
+@router.get("/agent/auth/context", response_model=AgentAuthContextResponse)
+async def get_agent_auth_context(
+    ctx: ProjectContext = Depends(get_project_context),
+    current_user=Depends(get_current_metadata_user),
+    keycloak_payload: dict = Depends(get_current_keycloak_payload),
+) -> AgentAuthContextResponse:
+    exp = keycloak_payload.get("exp")
+    token_expires_at = (
+        datetime.fromtimestamp(exp, tz=timezone.utc).isoformat()
+        if isinstance(exp, int)
+        else None
+    )
+    return AgentAuthContextResponse(
+        user_id=str(current_user.id),
+        keycloak_sub=str(current_user.keycloak_id),
+        username=current_user.username,
+        role=current_user.role,
+        is_superuser=current_user.is_superuser,
+        project_id=str(ctx.project_id),
+        network=ctx.project_code,
+        project_role=ctx.project_role,
+        token_expires_at=token_expires_at,
+    )

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

@@ -1,186 +0,0 @@
-from typing import Annotated
-from datetime import timedelta
-from fastapi import APIRouter, Depends, HTTPException, status
-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.auth.dependencies import get_user_repository, get_current_active_user
-from app.domain.schemas.user import UserInDB
-import logging
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-@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)
-) -> UserResponse:
-    """
-    用户注册
-    
-    创建新用户账号
-    """
-    # 检查用户名和邮箱是否已存在
-    if await user_repo.user_exists(username=user_data.username):
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            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"
-        )
-    
-    # 创建用户
-    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"
-            )
-        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"
-        )
-
-@router.post("/login", response_model=Token)
-async def login(
-    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
-    user_repo: UserRepository = Depends(get_user_repository)
-) -> Token:
-    """
-    用户登录（OAuth2 标准格式）
-    
-    返回 JWT Access Token 和 Refresh Token
-    """
-    # 验证用户（支持用户名或邮箱登录）
-    user = await user_repo.get_user_by_username(form_data.username)
-    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"
-        )
-    
-    # 生成 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
-    )
-
-@router.post("/login/simple", response_model=Token)
-async def login_simple(
-    username: str,
-    password: str,
-    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"
-        )
-    
-    if not user.is_active:
-        raise HTTPException(
-            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
-    )
-
-@router.get("/me", response_model=UserResponse)
-async def get_current_user_info(
-    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)
-) -> 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])
-        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
-    )

app/api/v1/endpoints/burst_detection.py

@@ -0,0 +1,131 @@
+from datetime import datetime
+from typing import Any
+
+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_detection import (
+    get_burst_detection_scheme_detail,
+    list_burst_detection_schemes,
+    run_burst_detection,
+)
+
+router = APIRouter()
+
+
+class BurstDetectionRequest(BaseModel):
+    """爆管检测请求模型"""
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    observed_pressure_data: (
+        dict[str, list[Any]] | list[dict[str, Any]] | list[list[Any]] | None
+    ) = Field(
+        default=None,
+        description=(
+            "压力观测数据。支持列式字典 {sensor_id: [values,...]}、"
+            "逐时刻对象数组 [{sensor_id: value,...}, ...]、"
+            "或二维数组 [[t1_s1, t1_s2], [t2_s1, t2_s2], ...]。"
+        ),
+    )
+    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/",
+    summary="执行爆管检测",
+    description="基于压力观测数据和其他参数执行爆管检测分析"
+)
+async def detect_burst(
+    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/",
+    summary="查询爆管检测方案列表",
+    description="获取指定网络的所有爆管检测方案"
+)
+async def query_burst_detection_schemes(
+    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}",
+    summary="获取爆管检测方案详情",
+    description="获取指定爆管检测方案的详细信息"
+)
+async def query_burst_detection_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_detection_scheme_detail(network=network, scheme_name=scheme_name)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

app/api/v1/endpoints/burst_location.py

@@ -0,0 +1,131 @@
+from typing import Any
+from datetime import datetime
+
+from typing import Literal
+
+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 (
+    get_burst_location_scheme_detail,
+    list_burst_location_schemes,
+    run_burst_location_by_network,
+)
+
+router = APIRouter()
+
+
+class BurstLocationRequest(BaseModel):
+    """爆管定位请求模型"""
+    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_burst_end: datetime | None = Field(None, description="爆管/模拟方案结束时间")
+    scada_normal_start: datetime | None = Field(None, description="监测数据正常工况开始时间")
+    scada_normal_end: datetime | None = Field(None, description="监测数据正常工况结束时间")
+    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/",
+    summary="执行爆管定位",
+    description="基于压力和流量数据定位管网中的爆管位置"
+)
+async def locate_burst(
+    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/",
+    summary="查询爆管定位方案列表",
+    description="获取指定网络的所有爆管定位方案"
+)
+async def query_burst_schemes(
+    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}",
+    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:
+        raise HTTPException(status_code=400, detail=str(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,31 +1,70 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    get_control,
+    get_control_schema,
+    get_rule,
+    get_rule_schema,
+    set_control,
+    set_rule,
+)
 
 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,42 +1,95 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_curve,
+    delete_curve,
+    get_curve,
+    get_curve_schema,
+    get_curves,
+    is_curve,
+    set_curve,
+)
 
 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,60 +1,137 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    get_energy,
+    get_energy_schema,
+    get_option_v3,
+    get_option_v3_schema,
+    get_pump_energy,
+    get_pump_energy_schema,
+    get_time,
+    get_time_schema,
+    set_energy,
+    set_option_v3,
+    set_pump_energy,
+    set_time,
+)
 
 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,42 +1,95 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_pattern,
+    delete_pattern,
+    get_pattern,
+    get_pattern_schema,
+    get_patterns,
+    is_pattern,
+    set_pattern,
+)
 
 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,119 +1,297 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_mixing,
+    add_source,
+    api,
+    delete_mixing,
+    delete_source,
+    get_emitter,
+    get_emitter_schema,
+    get_mixing,
+    get_mixing_schema,
+    get_pipe_reaction,
+    get_pipe_reaction_schema,
+    get_quality,
+    get_quality_schema,
+    get_reaction,
+    get_reaction_schema,
+    get_source,
+    get_source_schema,
+    get_tank_reaction,
+    get_tank_reaction_schema,
+    set_emitter,
+    set_pipe_reaction,
+    set_quality,
+    set_reaction,
+    set_source,
+    set_tank_reaction,
+)
 
 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,76 +1,180 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_label,
+    add_vertex,
+    delete_label,
+    delete_vertex,
+    get_all_vertex_links,
+    get_all_vertices,
+    get_backdrop,
+    get_backdrop_schema,
+    get_label,
+    get_label_schema,
+    get_vertex,
+    get_vertex_schema,
+    set_backdrop,
+    set_label,
+    set_vertex,
+)
 from fastapi.responses import PlainTextResponse
 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/data_query.py

@@ -1,388 +0,0 @@
-from typing import Any, List, Dict, Optional
-import logging
-from datetime import datetime, timedelta, timezone, time as dt_time
-import msgpack
-from fastapi import APIRouter
-from pydantic import BaseModel
-from py_linq import Enumerable
-
-import app.infra.db.influxdb.api as influxdb_api
-import app.services.time_api as time_api
-from app.infra.cache.redis_client import redis_client, encode_datetime, decode_datetime
-
-router = APIRouter()
-logger = logging.getLogger(__name__)
-
-# Basic Node/Link Latest Record Queries
-
-@router.get("/querynodelatestrecordbyid/")
-async def fastapi_query_node_latest_record_by_id(id: str) -> Any:
-    return influxdb_api.query_latest_record_by_ID(id, type="node")
-
-@router.get("/querylinklatestrecordbyid/")
-async def fastapi_query_link_latest_record_by_id(id: str) -> Any:
-    return influxdb_api.query_latest_record_by_ID(id, type="link")
-
-@router.get("/queryscadalatestrecordbyid/")
-async def fastapi_query_scada_latest_record_by_id(id: str) -> Any:
-    return influxdb_api.query_latest_record_by_ID(id, type="scada")
-
-# Time-based Queries
-
-@router.get("/queryallrecordsbytime/")
-async def fastapi_query_all_records_by_time(querytime: str) -> dict[str, list]:
-    results: tuple = influxdb_api.query_all_records_by_time(query_time=querytime)
-    return {"nodes": results[0], "links": results[1]}
-
-@router.get("/queryallrecordsbytimeproperty/")
-async def fastapi_query_all_record_by_time_property(
-    querytime: str, type: str, property: str, bucket: str = "realtime_simulation_result"
-) -> dict[str, list]:
-    results: tuple = influxdb_api.query_all_record_by_time_property(
-        query_time=querytime, type=type, property=property, bucket=bucket
-    )
-    return {"results": results}
-
-@router.get("/queryallschemerecordsbytimeproperty/")
-async def fastapi_query_all_scheme_record_by_time_property(
-    querytime: str,
-    type: str,
-    property: str,
-    schemename: str,
-    bucket: str = "scheme_simulation_result",
-) -> dict[str, list]:
-    """
-    查询指定方案某一时刻的所有记录,查询 'node' 或 'link' 的某一属性值
-    """
-    results: list = influxdb_api.query_all_scheme_record_by_time_property(
-        query_time=querytime,
-        type=type,
-        property=property,
-        scheme_name=schemename,
-        bucket=bucket,
-    )
-    return {"results": results}
-
-@router.get("/querysimulationrecordsbyidtime/")
-async def fastapi_query_simulation_record_by_ids_time(
-    id: str, querytime: str, type: str, bucket: str = "realtime_simulation_result"
-) -> dict[str, list]:
-    results: tuple = influxdb_api.query_simulation_result_by_ID_time(
-        ID=id, type=type, query_time=querytime, bucket=bucket
-    )
-    return {"results": results}
-
-@router.get("/queryschemesimulationrecordsbyidtime/")
-async def fastapi_query_scheme_simulation_record_by_ids_time(
-    scheme_name: str,
-    id: str,
-    querytime: str,
-    type: str,
-    bucket: str = "scheme_simulation_result",
-) -> dict[str, list]:
-    results: tuple = influxdb_api.query_scheme_simulation_result_by_ID_time(
-        scheme_name=scheme_name, ID=id, type=type, query_time=querytime, bucket=bucket
-    )
-    return {"results": results}
-
-# Date-based Queries with Caching
-
-@router.get("/queryallrecordsbydate/")
-async def fastapi_query_all_records_by_date(querydate: str) -> dict:
-    is_today_or_future = time_api.is_today_or_future(querydate)
-    logger.info(f"isToday or future: {is_today_or_future}")
-
-    cache_key = f"queryallrecordsbydate_{querydate}"
-    
-    if not is_today_or_future:
-        data = redis_client.get(cache_key)
-        if data:
-            results = msgpack.unpackb(data, object_hook=decode_datetime)
-            logger.info("return from cache redis")
-            return results
-
-    logger.info("query from influxdb")
-    nodes_links: tuple = influxdb_api.query_all_records_by_date(query_date=querydate)
-    results = {"nodes": nodes_links[0], "links": nodes_links[1]}
-
-    if not is_today_or_future:
-        logger.info("save to cache redis")
-        redis_client.set(cache_key, msgpack.packb(results, default=encode_datetime))
-
-    logger.info("return results")
-    return results
-
-@router.get("/queryallrecordsbytimerange/")
-async def fastapi_query_all_records_by_time_range(
-    starttime: str, endtime: str
-) -> dict[str, list]:
-    cache_key = f"queryallrecordsbytimerange_{starttime}_{endtime}"
-    
-    if not time_api.is_today_or_future(starttime):
-        data = redis_client.get(cache_key)
-        if data:
-            loaded_dict = msgpack.unpackb(data, object_hook=decode_datetime)
-            return loaded_dict
-
-    nodes_links: tuple = influxdb_api.query_all_records_by_time_range(
-        starttime=starttime, endtime=endtime
-    )
-    results = {"nodes": nodes_links[0], "links": nodes_links[1]}
-
-    if not time_api.is_today_or_future(starttime):
-        redis_client.set(cache_key, msgpack.packb(results, default=encode_datetime))
-
-    return results
-
-@router.get("/queryallrecordsbydatewithtype/")
-async def fastapi_query_all_records_by_date_with_type(
-    querydate: str, querytype: str
-) -> list:
-    cache_key = f"queryallrecordsbydatewithtype_{querydate}_{querytype}"
-    data = redis_client.get(cache_key)
-    if data:
-        loaded_dict = msgpack.unpackb(data, object_hook=decode_datetime)
-        return loaded_dict
-
-    results = influxdb_api.query_all_records_by_date_with_type(
-        query_date=querydate, query_type=querytype
-    )
-
-    packed = msgpack.packb(results, default=encode_datetime)
-    redis_client.set(cache_key, packed)
-
-    return results
-
-@router.get("/queryallrecordsbyidsdatetype/")
-async def fastapi_query_all_records_by_ids_date_type(
-    ids: str, querydate: str, querytype: str
-) -> list:
-    cache_key = f"queryallrecordsbydatewithtype_{querydate}_{querytype}"
-    data = redis_client.get(cache_key)
-    
-    results = []
-    if data:
-        results = msgpack.unpackb(data, object_hook=decode_datetime)
-    else:
-        results = influxdb_api.query_all_records_by_date_with_type(
-            query_date=querydate, query_type=querytype
-        )
-        packed = msgpack.packb(results, default=encode_datetime)
-        redis_client.set(cache_key, packed)
-
-    query_ids = ids.split(",")
-    # Using Enumerable from py_linq as in original code
-    e_results = Enumerable(results)
-    lst_results = e_results.where(lambda x: x["ID"] in query_ids).to_list()
-
-    return lst_results
-
-@router.get("/queryallrecordsbydateproperty/")
-async def fastapi_query_all_records_by_date_property(
-    querydate: str, querytype: str, property: str
-) -> list[dict]:
-    cache_key = f"queryallrecordsbydateproperty_{querydate}_{querytype}_{property}"
-    data = redis_client.get(cache_key)
-    if data:
-        loaded_dict = msgpack.unpackb(data, object_hook=decode_datetime)
-        return loaded_dict
-
-    result_dict = influxdb_api.query_all_record_by_date_property(
-        query_date=querydate, type=querytype, property=property
-    )
-    packed = msgpack.packb(result_dict, default=encode_datetime)
-    redis_client.set(cache_key, packed)
-
-    return result_dict
-
-# Curve Queries
-
-@router.get("/querynodecurvebyidpropertydaterange/")
-async def fastapi_query_node_curve_by_id_property_daterange(
-    id: str, prop: str, startdate: str, enddate: str
-):
-    return influxdb_api.query_curve_by_ID_property_daterange(
-        id, type="node", property=prop, start_date=startdate, end_date=enddate
-    )
-
-@router.get("/querylinkcurvebyidpropertydaterange/")
-async def fastapi_query_link_curve_by_id_property_daterange(
-    id: str, prop: str, startdate: str, enddate: str
-):
-    return influxdb_api.query_curve_by_ID_property_daterange(
-        id, type="link", property=prop, start_date=startdate, end_date=enddate
-    )
-
-# SCADA Data Queries
-
-@router.get("/queryscadadatabydeviceidandtime/")
-async def fastapi_query_scada_data_by_device_id_and_time(ids: str, querytime: str):
-    query_ids = ids.split(",")
-    logger.info(querytime)
-    return influxdb_api.query_SCADA_data_by_device_ID_and_time(
-        query_ids_list=query_ids, query_time=querytime
-    )
-
-@router.get("/queryscadadatabydeviceidandtimerange/")
-async def fastapi_query_scada_data_by_device_id_and_time_range(
-    ids: str, starttime: str, endtime: str
-):
-    print(f"query_ids: {ids}, starttime: {starttime}, endtime: {endtime}")
-    query_ids = ids.split(",")
-    return influxdb_api.query_SCADA_data_by_device_ID_and_timerange(
-        query_ids_list=query_ids, start_time=starttime, end_time=endtime
-    )
-
-@router.get("/queryfillingscadadatabydeviceidandtimerange/")
-async def fastapi_query_filling_scada_data_by_device_id_and_time_range(
-    ids: str, starttime: str, endtime: str
-):
-    print(f"query_ids: {ids}, starttime: {starttime}, endtime: {endtime}")
-    query_ids = ids.split(",")
-    return influxdb_api.query_filling_SCADA_data_by_device_ID_and_timerange(
-        query_ids_list=query_ids, start_time=starttime, end_time=endtime
-    )
-
-@router.get("/querycleaningscadadatabydeviceidandtimerange/")
-async def fastapi_query_cleaning_scada_data_by_device_id_and_time_range(
-    ids: str, starttime: str, endtime: str
-):
-    print(f"query_ids: {ids}, starttime: {starttime}, endtime: {endtime}")
-    query_ids = ids.split(",")
-    return influxdb_api.query_cleaning_SCADA_data_by_device_ID_and_timerange(
-        query_ids_list=query_ids, start_time=starttime, end_time=endtime
-    )
-
-@router.get("/querysimulationscadadatabydeviceidandtimerange/")
-async def fastapi_query_simulation_scada_data_by_device_id_and_time_range(
-    ids: str, starttime: str, endtime: str
-):
-    print(f"query_ids: {ids}, starttime: {starttime}, endtime: {endtime}")
-    query_ids = ids.split(",")
-    return influxdb_api.query_simulation_SCADA_data_by_device_ID_and_timerange(
-        query_ids_list=query_ids, start_time=starttime, end_time=endtime
-    )
-
-@router.get("/querycleanedscadadatabydeviceidandtimerange/")
-async def fastapi_query_cleaned_scada_data_by_device_id_and_time_range(
-    ids: str, starttime: str, endtime: str
-):
-    print(f"query_ids: {ids}, starttime: {starttime}, endtime: {endtime}")
-    query_ids = ids.split(",")
-    return influxdb_api.query_cleaned_SCADA_data_by_device_ID_and_timerange(
-        query_ids_list=query_ids, start_time=starttime, end_time=endtime
-    )
-
-@router.get("/queryscadadatabydeviceidanddate/")
-async def fastapi_query_scada_data_by_device_id_and_date(ids: str, querydate: str):
-    query_ids = ids.split(",")
-    return influxdb_api.query_SCADA_data_by_device_ID_and_date(
-        query_ids_list=query_ids, query_date=querydate
-    )
-
-@router.get("/queryallscadarecordsbydate/")
-async def fastapi_query_all_scada_records_by_date(querydate: str):
-    is_today_or_future = time_api.is_today_or_future(querydate)
-    logger.info(f"isToday or future: {is_today_or_future}")
-
-    cache_key = f"queryallscadarecordsbydate_{querydate}"
-    
-    if not is_today_or_future:
-        data = redis_client.get(cache_key)
-        if data:
-            loaded_dict = msgpack.unpackb(data, object_hook=decode_datetime)
-            logger.info("return from cache redis")
-            return loaded_dict
-
-    logger.info("query from influxdb")
-    result_dict = influxdb_api.query_all_SCADA_records_by_date(query_date=querydate)
-
-    if not is_today_or_future:
-        logger.info("save to cache redis")
-        packed = msgpack.packb(result_dict, default=encode_datetime)
-        redis_client.set(cache_key, packed)
-
-    logger.info("return results")
-    return result_dict
-
-@router.get("/queryallschemeallrecords/")
-async def fastapi_query_all_scheme_all_records(
-    schemetype: str, schemename: str, querydate: str
-) -> tuple:
-    cache_key = f"queryallschemeallrecords_{schemetype}_{schemename}_{querydate}"
-    data = redis_client.get(cache_key)
-    if data:
-        loaded_dict = msgpack.unpackb(data, object_hook=decode_datetime)
-        return loaded_dict
-
-    results = influxdb_api.query_scheme_all_record(
-        scheme_type=schemetype, scheme_name=schemename, query_date=querydate
-    )
-    packed = msgpack.packb(results, default=encode_datetime)
-    redis_client.set(cache_key, packed)
-
-    return results
-
-@router.get("/queryschemeallrecordsproperty/")
-async def fastapi_query_all_scheme_all_records_property(
-    schemetype: str, schemename: str, querydate: str, querytype: str, queryproperty: str
-) -> Optional[List]:
-    cache_key = f"queryallschemeallrecords_{schemetype}_{schemename}_{querydate}"
-    data = redis_client.get(cache_key)
-    all_results = None
-    if data:
-        all_results = msgpack.unpackb(data, object_hook=decode_datetime)
-    else:
-        all_results = influxdb_api.query_scheme_all_record(
-            scheme_type=schemetype, scheme_name=schemename, query_date=querydate
-        )
-        packed = msgpack.packb(all_results, default=encode_datetime)
-        redis_client.set(cache_key, packed)
-
-    results = None
-    if querytype == "node":
-        results = all_results[0]
-    elif querytype == "link":
-        results = all_results[1]
-
-    return results
-
-@router.get("/queryinfluxdbbuckets/")
-async def fastapi_query_influxdb_buckets():
-    return influxdb_api.query_buckets()
-
-@router.get("/queryinfluxdbbucketmeasurements/")
-async def fastapi_query_influxdb_bucket_measurements(bucket: str):
-    return influxdb_api.query_measurements(bucket=bucket)
-
-############################################################
-# download history data
-############################################################
-
-class Download_History_Data_Manually(BaseModel):
-    """
-    download_date：样式如 datetime(2025, 5, 4)
-    """
-
-    download_date: datetime
-
-
-@router.post("/download_history_data_manually/")
-async def fastapi_download_history_data_manually(
-    data: Download_History_Data_Manually,
-) -> None:
-    item = data.dict()
-    tz = timezone(timedelta(hours=8))
-    begin_dt = datetime.combine(item.get("download_date").date(), dt_time.min).replace(
-        tzinfo=tz
-    )
-    end_dt = datetime.combine(item.get("download_date").date(), dt_time(23, 59, 59)).replace(
-        tzinfo=tz
-    )
-
-    begin_time = begin_dt.isoformat()
-    end_time = end_dt.isoformat()
-
-    influxdb_api.download_history_data_manually(
-        begin_time=begin_time, end_time=end_time
-    )

app/api/v1/endpoints/extension.py

@@ -1,7 +1,7 @@
 from typing import List, Any
-from fastapi import APIRouter, Request, HTTPException
-from app.native.api import ChangeSet
+from fastapi import APIRouter, Request, HTTPException, Query, Body
 from app.services.tjnetwork import (
+    ChangeSet,
     get_all_extension_data_keys,
     get_all_extension_data,
     get_extension_data,
@@ -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/geocoding.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.services.geocoding import (
+    TiandituGeocodeRequest,
+    TiandituGeocodingAPIError,
+    TiandituGeocodingConfigError,
+    geocode_tianditu,
+)
+
+router = APIRouter()
+
+
+@router.post(
+    "/tianditu/geocode",
+    summary="Tianditu Geocoding",
+    description="调用天地图地理编码服务，将结构化地址转换为经纬度",
+)
+async def tianditu_geocode(request: TiandituGeocodeRequest) -> dict[str, Any]:
+    try:
+        return await geocode_tianditu(request)
+    except TiandituGeocodingConfigError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=str(exc),
+        ) from exc
+    except TiandituGeocodingAPIError as exc:
+        raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc

app/api/v1/endpoints/leakage.py

@@ -0,0 +1,133 @@
+import os
+from typing import Any
+from datetime import datetime
+
+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 (
+    get_leakage_identify_scheme_detail,
+    list_leakage_identify_schemes,
+    run_leakage_identification,
+)
+
+router = APIRouter()
+DEFAULT_N_WORKERS = max(1, min((os.cpu_count() or 1) - 1, 4))
+
+
+class LeakageIdentifyRequest(BaseModel):
+    """漏损识别请求模型"""
+    network: str = Field(..., description="管网名称（或数据库名称）")
+    observed_pressure_data: str | dict[str, list[Any]] | list[dict[str, Any]] | None = Field(
+        None, description="观测的压力数据"
+    )
+    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/",
+    summary="执行漏损识别",
+    description="基于压力观测数据和遗传算法识别管网中的漏损位置和大小"
+)
+async def identify_leakage(
+    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/",
+    summary="查询漏损识别方案列表",
+    description="获取指定网络的所有漏损识别方案"
+)
+async def query_leakage_schemes(
+    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}",
+    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
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

app/api/v1/endpoints/meta.py

@@ -1,5 +1,6 @@
 import logging
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Path
+import psycopg
 from psycopg import AsyncConnection
 from sqlalchemy import text
 from sqlalchemy.exc import SQLAlchemyError
@@ -15,55 +16,52 @@ from app.auth.project_dependencies import (
 from app.auth.metadata_dependencies import get_current_metadata_user
 from app.core.config import settings
 from app.domain.schemas.metadata import (
-    GeoServerConfigResponse,
     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),
 ):
+    """
+    获取项目元数据
+    
+    返回当前项目的完整元数据
+    """
     project = await metadata_repo.get_project_by_id(ctx.project_id)
     if not project:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND, detail="Project not found"
         )
-    geoserver = await metadata_repo.get_geoserver_config(ctx.project_id)
-    geoserver_payload = (
-        GeoServerConfigResponse(
-            gs_base_url=geoserver.gs_base_url,
-            gs_admin_user=geoserver.gs_admin_user,
-            gs_datastore_name=geoserver.gs_datastore_name,
-            default_extent=geoserver.default_extent,
-            srid=geoserver.srid,
-        )
-        if geoserver
-        else None
-    )
     return ProjectMetaResponse(
         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,
         project_role=ctx.project_role,
-        geoserver=geoserver_payload,
     )
 
 
-@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,12 +88,33 @@ 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),
 ):
-    await pg_session.execute(text("SELECT 1"))
-    async with ts_conn.cursor() as cur:
-        await cur.execute("SELECT 1")
+    """
+    检查数据库健康状态
+    
+    检查PostgreSQL和TimescaleDB数据库的连接状态
+    """
+    try:
+        await pg_session.execute(text("SELECT 1"))
+    except SQLAlchemyError as exc:
+        logger.error("Project PostgreSQL health check failed", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Project PostgreSQL health check failed: {exc}",
+        ) from exc
+
+    try:
+        async with ts_conn.cursor() as cur:
+            await cur.execute("SELECT 1")
+    except psycopg.Error as exc:
+        logger.error("Project TimescaleDB health check failed", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Project TimescaleDB health check failed: {exc}",
+        ) from exc
+
     return {"postgres": "ok", "timescale": "ok"}

app/api/v1/endpoints/misc.py

@@ -1,6 +1,5 @@
 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 +11,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 +28,38 @@ async def fastapi_get_json():
     )
 
 
-@router.get("/getallsensorplacements/")
-async def fastapi_get_all_sensor_placements(network: str) -> list[dict[Any, Any]]:
+@router.get("/sensor-placement-schemes", summary="获取所有传感器位置", description="获取网络中所有传感器的放置位置信息")
+@router.get("/getallsensorplacements/", summary="获取所有传感器位置（旧路径）", description="获取网络中所有传感器的放置位置信息", deprecated=True)
+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/")
-async def fastapi_get_realtimedata():
-    data = [random.randint(0, 100) for _ in range(100)]
-    return data
-
-
-@router.get("/getsimulationresult/")
-async def fastapi_get_simulationresult():
-    data = [random.randint(0, 100) for _ in range(100)]
-    return data

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

@@ -1,6 +1,15 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    calculate_demand_to_network,
+    calculate_demand_to_nodes,
+    calculate_demand_to_region,
+    get_demand,
+    get_demand_schema,
+    set_demand,
+)
 
 router = APIRouter()
 
@@ -8,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))
@@ -30,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,6 +1,42 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    delete_junction,
+    delete_pipe,
+    delete_pump,
+    delete_reservoir,
+    delete_tank,
+    delete_valve,
+    get_all_scada_info,
+    get_element_properties,
+    get_element_properties_with_type,
+    get_element_type,
+    get_element_type_value,
+    get_link_properties,
+    get_link_type,
+    get_links,
+    get_node_links,
+    get_node_properties,
+    get_node_type,
+    get_nodes,
+    get_scada_info,
+    get_status,
+    get_status_schema,
+    get_title,
+    get_title_schema,
+    is_junction,
+    is_link,
+    is_node,
+    is_pipe,
+    is_pump,
+    is_reservoir,
+    is_tank,
+    is_valve,
+    set_status,
+    set_title,
+)
 
 router = APIRouter()
 
@@ -8,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))
 
@@ -119,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))
@@ -139,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))
@@ -150,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,7 +1,16 @@
-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 *
-from app.auth.dependencies import get_current_user as verify_token
+from app.services.tjnetwork import (
+    Any,
+    get_all_scada_info,
+    get_major_node_coords,
+    get_major_pipe_nodes,
+    get_network_in_extent,
+    get_network_link_nodes,
+    get_network_node_coords,
+    get_node_coord,
+)
+from app.auth.metadata_dependencies import get_current_metadata_user
 from app.infra.cache.redis_client import redis_client, encode_datetime, decode_datetime
 import msgpack
 
@@ -25,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(get_current_metadata_user)],
+    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:
@@ -55,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,111 +1,361 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_junction,
+    delete_junction,
+    get_all_junctions,
+    get_junction,
+    get_junction_schema,
+    set_junction,
+)
 
 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,25 +1,63 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    PIPE_STATUS_OPEN,
+    add_pipe,
+    delete_pipe,
+    get_all_pipes,
+    get_pipe,
+    get_pipe_schema,
+    set_pipe,
+)
 
 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,
@@ -32,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,60 +1,203 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_pump,
+    delete_pump,
+    get_all_pumps,
+    get_pump,
+    get_pump_schema,
+    set_pump,
+)
 
 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,6 +1,42 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_district_metering_area,
+    add_region,
+    add_service_area,
+    add_virtual_district,
+    calculate_district_metering_area_for_network,
+    calculate_district_metering_area_for_nodes,
+    calculate_district_metering_area_for_region,
+    calculate_service_area,
+    calculate_virtual_district,
+    delete_district_metering_area,
+    delete_region,
+    delete_service_area,
+    delete_virtual_district,
+    generate_district_metering_area,
+    generate_service_area,
+    generate_sub_district_metering_area,
+    generate_virtual_district,
+    get_all_district_metering_area_ids,
+    get_all_district_metering_areas,
+    get_all_service_areas,
+    get_all_virtual_districts,
+    get_district_metering_area,
+    get_district_metering_area_schema,
+    get_region,
+    get_region_schema,
+    get_service_area,
+    get_service_area_schema,
+    get_virtual_district,
+    get_virtual_district_schema,
+    set_district_metering_area,
+    set_region,
+    set_service_area,
+    set_virtual_district,
+)
 
 router = APIRouter()
 
@@ -8,64 +44,95 @@ router = APIRouter()
 # region 32
 ############################################################
 
-@router.get("/calculateregion/")
-async def fastapi_calculate_region(network: str, time_index: int) -> 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]]:
-    return get_all_regions(network)
-
-@router.post("/generateregion/", response_model=None)
-async def fastapi_generate_region(
-    network: str, inflate_delta: float
-) -> ChangeSet:
-    return generate_region(network, inflate_delta)
-
 
 ############################################################
 # district_metering_area 33
 ############################################################
 
-@router.get("/calculatedistrictmeteringarea/")
-async def fastapi_calculate_district_metering_area(
-    network: str, req: Request
-) -> list[list[str]]:
-    props = await req.json()
-    nodes = props["nodes"]
-    part_count = props["part_count"]
-    part_type = props["part_type"]
-    return 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"]
@@ -74,32 +141,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", [])
@@ -110,33 +222,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
     )
@@ -146,43 +298,104 @@ 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
-) -> dict[str, Any]:
-    return calculate_service_area(network, time_index)
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+) -> list[dict[str, list[str]]]:
+    """计算服务区分区，返回全部时间步结果。"""
+    return calculate_service_area(network)
 
-@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)
 
 
@@ -190,52 +403,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,105 +1,422 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_reservoir,
+    delete_reservoir,
+    get_all_reservoirs,
+    get_reservoir,
+    get_reservoir_schema,
+    set_reservoir,
+)
 
 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,6 +1,13 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    get_tag,
+    get_tag_schema,
+    get_tags,
+    set_tag,
+)
 
 router = APIRouter()
 
@@ -8,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,26 +1,62 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    add_tank,
+    delete_tank,
+    get_all_tanks,
+    get_tank,
+    get_tank_schema,
+    set_tank,
+)
 
 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,
@@ -34,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,24 +1,55 @@
-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 *
+from app.services.tjnetwork import (
+    Any,
+    ChangeSet,
+    VALVES_TYPE_PRV,
+    add_valve,
+    delete_valve,
+    get_all_valves,
+    get_valve,
+    get_valve_schema,
+    set_valve,
+)
 
 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,
@@ -31,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,12 +1,15 @@
 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
 import app.services.project_info as project_info
-from app.native.api import ChangeSet
 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
 from app.services.tjnetwork import (
+    ChangeSet,
     list_project,
     have_project,
     create_project,
@@ -39,30 +42,97 @@ 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)
+@router.get("/project_info/", summary="获取项目信息（旧路径）", description="从数据库获取项目的详细信息，包括地图范围等。", response_model=ProjectMetaResponse, deprecated=True)
+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")
+
+    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",
+    )
+
+@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("/projects/open", summary="打开项目", description="将指定项目加载到内存中，并初始化数据库连接池。")
+@router.post("/openproject/", summary="打开项目（旧路径）", description="将指定项目加载到内存中，并初始化数据库连接池。", deprecated=True)
+async def open_project_endpoint(
+    network: str = Query(..., description="管网名称（或数据库名称）")
+):
+    """
+    打开项目
+
+    - **network**: 管网名称（或数据库名称）
+    """
     open_project(network)
     
     # 尝试连接指定数据库
@@ -88,18 +158,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 +202,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 +235,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 +314,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 +333,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 +352,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 +372,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,30 +1,31 @@
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
 from psycopg import AsyncConnection
 
-from .scada_info import ScadaRepository
-from .scheme import SchemeRepository
+from app.infra.db.postgresql.scada import ScadaInfoRepository
+from app.infra.db.postgresql.scheme import SchemeRepository
 from app.auth.project_dependencies import get_project_pg_connection
 
 router = APIRouter()
 
 
-# 动态项目 PostgreSQL 连接依赖
 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:
-        # 使用ScadaRepository查询SCADA信息
-        scada_data = await ScadaRepository.get_scadas(conn)
+        scada_data = await ScadaInfoRepository.get_scadas(conn)
         return {"success": True, "data": scada_data, "count": len(scada_data)}
     except Exception as e:
         raise HTTPException(
@@ -32,30 +33,32 @@ 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:
-        # 使用SchemeRepository查询方案信息
         scheme_data = await SchemeRepository.get_schemes(conn)
         return {"success": True, "data": scheme_data, "count": len(scheme_data)}
     except Exception as e:
         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:
-        # 使用SchemeRepository查询爆管定位结果
         burst_data = await SchemeRepository.get_burst_locate_results(conn)
         return {"success": True, "data": burst_data, "count": len(burst_data)}
     except Exception as e:
@@ -64,16 +67,18 @@ 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:
-        # 使用SchemeRepository查询爆管定位结果
         return await SchemeRepository.get_burst_locate_result_by_incident(
             conn, burst_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,7 +1,7 @@
 from typing import Any
-from fastapi import APIRouter, Request
-from app.native.api import ChangeSet
+from fastapi import APIRouter, Request, Query
 from app.services.tjnetwork import (
+    ChangeSet,
     get_scada_info,
     get_all_scada_info,
     get_scada_device_schema,
@@ -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,33 @@
-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("/schemes", summary="获取所有方案", description="获取指定网络的所有方案信息")
+@router.get("/getallschemes/", summary="获取所有方案（旧路径）", description="获取指定网络的所有方案信息", deprecated=True)
+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,20 +4,18 @@ import json
 import os
 import shutil
 import threading
-import pandas as pd
-from fastapi import APIRouter, HTTPException, File, UploadFile, Query
+from fastapi import APIRouter, Depends, HTTPException, File, UploadFile, Query, Path, Body
 from fastapi.responses import PlainTextResponse
-import app.infra.db.influxdb.api as influxdb_api
+from app.auth.keycloak_dependencies import get_current_keycloak_username
 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,
     run_inp,
     dump_output,
 )
-from app.algorithms.simulations import (
+from app.algorithms.simulation.scenarios import (
     burst_analysis,
     valve_close_analysis,
     flushing_analysis,
@@ -26,12 +24,11 @@ from app.algorithms.simulations import (
     # scheduling_analysis,
     pressure_regulation,
 )
-from app.algorithms.sensors import (
+from app.algorithms.sensor import (
     pressure_sensor_placement_sensitivity,
     pressure_sensor_placement_kmeans,
 )
-import app.algorithms.api_ex.flow_data_clean as flow_data_clean
-import app.algorithms.api_ex.pressure_data_clean as pressure_data_clean
+
 from app.services.network_import import network_update
 from app.services.simulation_ops import (
     project_management,
@@ -39,176 +36,194 @@ from app.services.simulation_ops import (
     daily_scheduling_simulation,
 )
 from app.services.valve_isolation import analyze_valve_isolation
-from pydantic import BaseModel
+from app.services.time_api import (
+    parse_aware_time,
+    parse_clock_duration_seconds,
+    parse_utc_time,
+)
+from pydantic import BaseModel, Field, field_validator
 
 router = APIRouter()
 
 
 class RunSimulationManuallyByDate(BaseModel):
-    name: str
-    simulation_date: str
-    start_time: str
-    duration: int
+    name: str = Field(..., description="管网名称（或数据库名称）")
+    start_time: str = Field(..., description="开始时间 (ISO 8601 / RFC3339，必须显式带时区)")
+    duration: int = Field(..., gt=0, description="持续时间 (分钟)")
+
+    @field_validator("start_time")
+    @classmethod
+    def validate_start_time_timezone(cls, value: str) -> str:
+        parse_aware_time(value, field_name="start_time")
+        return value
 
 
 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(
-    network_name: str, base_date: datetime, start_time: str, duration: int
+    network_name: str, start_time: datetime, duration: int
 ) -> None:
-    time_parts = list(map(int, start_time.split(":")))
-    if len(time_parts) == 2:
-        start_hour, start_minute = time_parts
-        start_second = 0
-    elif len(time_parts) == 3:
-        start_hour, start_minute, start_second = time_parts
-    else:
-        raise ValueError("Invalid start_time format. Use HH:MM or HH:MM:SS")
-
-    start_datetime = base_date.replace(
-        hour=start_hour, minute=start_minute, second=start_second
+    end_datetime = start_time + timedelta(minutes=duration)
+    time_properties = simulation.get_time(network_name)
+    hydraulic_step_seconds = parse_clock_duration_seconds(
+        time_properties["HYDRAULIC TIMESTEP"],
+        field_name="HYDRAULIC TIMESTEP",
     )
-    end_datetime = start_datetime + timedelta(minutes=duration)
-    current_time = start_datetime
+    if hydraulic_step_seconds <= 0:
+        raise ValueError("HYDRAULIC TIMESTEP must be greater than 0.")
+    hydraulic_step = timedelta(seconds=hydraulic_step_seconds)
+    current_time = start_time
     while current_time < end_datetime:
-        iso_time = current_time.strftime("%Y-%m-%dT%H:%M:%S") + "+08:00"
         simulation.run_simulation(
             name=network_name,
             simulation_type="realtime",
-            modify_pattern_start_time=iso_time,
+            modify_pattern_start_time=current_time.isoformat(timespec="seconds"),
         )
-        current_time += timedelta(minutes=15)
+        current_time += hydraulic_step
 
 
 # 必须用这个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/")
-async def burst_analysis_endpoint(
-    network: str, pipe_id: str, start_time: str, end_time: str, burst_flow: float
-):
-    return burst_analysis(network, pipe_id, start_time, end_time, burst_flow)
-
-
-@router.get("/burst_analysis/")
+@router.get("/burst-analysis", summary="爆管分析（高级）", description="高级版本的爆管分析，支持在指定时间点修改泵控制模式和阀门开度，以分析这些改变对爆管影响的作用。支持固定泵和变速泵的独立控制。")
+@router.get("/burst_analysis/", summary="爆管分析（高级，旧路径）", description="高级版本的爆管分析，支持在指定时间点修改泵控制模式和阀门开度，以分析这些改变对爆管影响的作用。支持固定泵和变速泵的独立控制。", deprecated=True)
 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="分析方案名称"),
+    username: str = Depends(get_current_keycloak_username),
 ) -> 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,
@@ -216,78 +231,108 @@ async def fastapi_burst_analysis(
         burst_size=burst_size,
         modify_total_duration=modify_total_duration,
         scheme_name=scheme_name,
+        username=username,
     )
     return "success"
 
 
-@router.get("/valvecloseanalysis/")
-async def valve_close_analysis_endpoint(
-    network: str, valve_id: str, start_time: str, end_time: str
-):
-    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秒"),
+    scheme_name: str = Query(..., description="阀门关闭方案名称"),
 ) -> str:
+    """
+    阀门关闭分析（高级版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 阀门关闭开始时间
+    - **valves**: 要关闭的阀门ID列表
+    - **duration**: 模拟持续时间（秒，可选，默认900）
+    - **scheme_name**: 阀门关闭方案名称
+    
+    支持同时关闭多个阀门进行分析。
+    """
     result = valve_close_analysis(
         name=network,
         modify_pattern_start_time=start_time,
         modify_total_duration=duration or 900,
         modify_valve_opening={valve_id: 0.0 for valve_id in valves},
+        scheme_name=scheme_name,
     )
     return result or "success"
 
 
-@router.get("/valve_isolation_analysis/")
+@router.get("/valve-isolation-analysis", summary="阀门隔离分析", description="分析当发生突发事件时，通过关闭指定阀门进行隔离，确定哪些阀门必须关闭、哪些可选关闭，以及隔离的可行性。")
+@router.get("/valve_isolation_analysis/", summary="阀门隔离分析（旧路径）", description="分析当发生突发事件时，通过关闭指定阀门进行隔离，确定哪些阀门必须关闭、哪些可选关闭，以及隔离的可行性。", deprecated=True)
 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列表（可选）"),
 ):
-    result = {
-        "accident_element": "P461309",
-        "accident_elements": ["P461309"],
-        "affected_nodes": [
-            "J316629_A",
-            "J317037_B",
-            "J317060_B",
-            "J408189_B",
-            "J499996",
-            "J524940",
-            "J535933",
-            "J58841",
-        ],
-        "isolatable": True,
-        "must_close_valves": ["210521658", "V12974", "V12986", "V12993"],
-        "optional_valves": [],
-    }
+    """
+    阀门隔离分析
+    
+    - **network**: 管网名称（或数据库名称）
+    - **accident_element**: 发生事故的管段/节点ID列表
+    - **disabled_valves**: 已故障的阀门ID列表（可选）
+    
+    返回隔离方案，包括：
+    - must_close_valves: 必须关闭的阀门列表
+    - optional_valves: 可选关闭的阀门列表
+    - affected_nodes: 受影响的节点列表
+    - isolatable: 是否可以有效隔离
+    """
+    # result = {
+    #     "accident_element": "P461309",
+    #     "accident_elements": ["P461309"],
+    #     "affected_nodes": [
+    #         "J316629_A",
+    #         "J317037_B",
+    #         "J317060_B",
+    #         "J408189_B",
+    #         "J499996",
+    #         "J524940",
+    #         "J535933",
+    #         "J58841",
+    #     ],
+    #     "isolatable": True,
+    #     "must_close_valves": ["210521658", "V12974", "V12986", "V12993"],
+    #     "optional_valves": [],
+    # }
     result = analyze_valve_isolation(network, accident_element, disabled_valves)
     return result
 
 
-@router.get("/flushinganalysis/")
-async def flushing_analysis_endpoint(
-    network: str, pipe_id: str, start_time: str, duration: float, flow: float
-):
-    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="高级版本的冲洗分析，支持同时开启多个阀门进行冲洗，指定排污节点，并设置固定的冲洗流量。返回纯文本格式的分析结果。")
+@router.get("/flushing_analysis/", response_class=PlainTextResponse, summary="冲洗分析（高级，旧路径）", description="高级版本的冲洗分析，支持同时开启多个阀门进行冲洗，指定排污节点，并设置固定的冲洗流量。返回纯文本格式的分析结果。", deprecated=True)
 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 = Query(..., description="冲洗方案名称"),
+    username: str = Depends(get_current_keycloak_username),
 ) -> 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)
     }
@@ -299,20 +344,36 @@ async def fastapi_flushing_analysis(
         drainage_node_ID=drainage_node_ID,
         flushing_flow=flush_flow,
         scheme_name=scheme_name,
+        username=username,
     )
     return result or "success"
 
 
-@router.get("/contaminant_simulation/", response_class=PlainTextResponse)
+@router.get("/contaminant-simulation", response_class=PlainTextResponse, summary="污染物模拟", description="对管网中的污染物扩散进行模拟，评估污染源对管网的影响范围和浓度分布。支持指定污染源位置、污染浓度和扩散模式。")
+@router.get("/contaminant_simulation/", response_class=PlainTextResponse, summary="污染物模拟（旧路径）", description="对管网中的污染物扩散进行模拟，评估污染源对管网的影响范围和浓度分布。支持指定污染源位置、污染浓度和扩散模式。", deprecated=True)
 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 = Query(..., description="模拟方案名称"),
+    pattern: str | None = Query(None, description="污染源模式ID（可选）"),
+    username: str = Depends(get_current_keycloak_username),
 ) -> 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,
@@ -321,19 +382,26 @@ async def fastapi_contaminant_simulation(
         source=source,
         concentration=concentration,
         source_pattern=pattern,
+        username=username,
     )
     return result or "success"
 
 
-@router.get("/ageanalysis/")
-async def age_analysis_endpoint(network: str):
-    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格式）"),
+    duration: int = Query(..., description="模拟持续时间（秒）"),
 ) -> str:
+    """
+    水龄分析（高级版本）
+    
+    - **network**: 管网名称（或数据库名称）
+    - **start_time**: 分析开始时间
+    - **duration**: 模拟持续时间（秒）
+    
+    分析指定时间段内管网中各节点的水体停留时间。
+    """
     result = age_analysis(network, start_time, duration)
     return result or "success"
 
@@ -343,15 +411,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 +467,20 @@ async def fastapi_pressure_regulation(data: PressureRegulation) -> str:
     return "success"
 
 
-@router.get("/projectmanagement/")
-async def project_management_endpoint(network: str):
-    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 +496,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 +522,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 +549,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 +568,15 @@ 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):
-    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 +594,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 +638,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 +688,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 +738,32 @@ async def fastapi_pressure_sensor_placement_kmeans(
     )
 
 
-@router.post("/sensorplacementscheme/create")
+@router.post("/sensor-placement-schemes", summary="传感器放置方案创建", description="创建新的传感器放置方案，支持灵敏度分析和KMeans聚类两种方法。根据指定的方法自动计算最优的传感器放置位置。")
+@router.post("/sensorplacementscheme/create", summary="传感器放置方案创建（旧路径）", description="创建新的传感器放置方案，支持灵敏度分析和KMeans聚类两种方法。根据指定的方法自动计算最优的传感器放置位置。", deprecated=True)
 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,68 +787,23 @@ 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("/simulations/run-by-date", summary="手动运行日期指定模拟", description="根据指定的开始时间和持续时间，手动运行水力模拟。开始时间必须是显式带时区的 ISO 8601 / RFC3339 时间。")
+@router.post("/runsimulationmanuallybydate/", summary="手动运行日期指定模拟（旧路径）", description="根据指定的开始时间和持续时间，手动运行水力模拟。开始时间必须是显式带时区的 ISO 8601 / RFC3339 时间。", deprecated=True)
 async def fastapi_run_simulation_manually_by_date(
-    data: RunSimulationManuallyByDate,
+    data: RunSimulationManuallyByDate = Body(..., description="模拟运行参数"),
 ) -> dict[str, str]:
-    item = data.dict()
+    """
+    手动运行日期指定模拟
+    
+    请求体参数：
+    - **name**: 管网名称（或数据库名称）
+    - **start_time**: 开始时间（ISO 8601 / RFC3339，必须显式带时区）
+    - **duration**: 模拟持续时间（分钟）
+    
+    系统将从指定时间开始，按15分钟间隔多次运行模拟。
+    每次模拟间隔15分钟，直至达到指定的总持续时间。
+    """
+    item = data.model_dump()
     try:
         simulation.query_corresponding_element_id_and_query_id(item["name"])
         simulation.query_corresponding_pattern_id_and_query_id(item["name"])
@@ -661,10 +830,10 @@ async def fastapi_run_simulation_manually_by_date(
             globals.source_outflow_region_id,
             globals.realtime_region_pipe_flow_and_demand_id,
         )
-        base_date = datetime.strptime(item["simulation_date"], "%Y-%m-%d")
+        start_time = parse_utc_time(item["start_time"], field_name="start_time")
         run_simulation_manually_by_date(
-            item["name"], base_date, item["start_time"], item["duration"]
+            item["name"], start_time, item["duration"]
         )
         return {"status": "success"}
     except Exception as exc:
-        return {"status": "error", "message": str(exc)}
+        raise HTTPException(status_code=500, detail=str(exc)) from exc

app/api/v1/endpoints/snapshots.py

@@ -1,6 +1,6 @@
-from fastapi import APIRouter, Request
-from app.native.api import ChangeSet
+from fastapi import APIRouter, Request, Query
 from app.services.tjnetwork import (
+    ChangeSet,
     get_current_operation,
     execute_undo,
     execute_redo,
@@ -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

@@ -0,0 +1,263 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from datetime import datetime
+from psycopg import AsyncConnection
+
+from app.infra.db.timescaledb.composite_queries import CompositeQueries
+from .dependencies import get_timescale_connection, get_postgres_connection
+
+router = APIRouter()
+
+
+@router.get("/composite/scada-simulation", summary="获取SCADA关联的模拟数据")
+async def get_scada_associated_simulation_data(
+    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 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 = (
+            [id.strip() for id in device_ids.split(",") if id.strip()]
+            if device_ids
+            else []
+        )
+
+        if scheme_type and scheme_name:
+            result = await CompositeQueries.get_scada_associated_scheme_simulation_data(
+                timescale_conn,
+                postgres_conn,
+                device_ids_list,
+                start_time,
+                end_time,
+                scheme_type,
+                scheme_name,
+            )
+        else:
+            result = (
+                await CompositeQueries.get_scada_associated_realtime_simulation_data(
+                    timescale_conn,
+                    postgres_conn,
+                    device_ids_list,
+                    start_time,
+                    end_time,
+                )
+            )
+        if result is None:
+            raise HTTPException(status_code=404, detail="No simulation data found")
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/composite/element-simulation", summary="获取管网元素的模拟数据")
+async def get_feature_simulation_data(
+    start_time: datetime = Query(..., description="查询开始时间"),
+    end_time: datetime = Query(..., description="查询结束时间"),
+    feature_infos: str = Query(
+        ..., description="特征信息，格式: id1:type1,id2:type2，type为pipe（管道）或junction（节点）"
+    ),
+    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，查询对应的模拟数据。支持查询实时或方案数据。
+
+    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 = []
+        if feature_infos:
+            for item in feature_infos.split(","):
+                item = item.strip()
+                if ":" in item:
+                    element_id, element_type = item.split(":", 1)
+                    feature_infos_list.append(
+                        (element_id.strip(), element_type.strip())
+                    )
+
+        if not feature_infos_list:
+            raise HTTPException(status_code=400, detail="feature_infos cannot be empty")
+
+        if scheme_type and scheme_name:
+            result = await CompositeQueries.get_scheme_simulation_data(
+                timescale_conn,
+                feature_infos_list,
+                start_time,
+                end_time,
+                scheme_type,
+                scheme_name,
+            )
+        else:
+            result = await CompositeQueries.get_realtime_simulation_data(
+                timescale_conn,
+                feature_infos_list,
+                start_time,
+                end_time,
+            )
+
+        if result is None:
+            raise HTTPException(status_code=404, detail="No simulation data found")
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/composite/element-scada", summary="获取管网元素关联的SCADA监测数据")
+async def get_element_associated_scada_data(
+    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 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(
+            timescale_conn, postgres_conn, element_id, start_time, end_time, use_cleaned
+        )
+        if result is None:
+            raise HTTPException(
+                status_code=404, detail="No associated SCADA data found"
+            )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/composite/clean-scada", summary="清洗SCADA监测数据")
+async def clean_scada_data(
+    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监测数据
+    
+    根据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":
+            device_ids_list = []
+        else:
+            device_ids_list = (
+                [id.strip() for id in device_ids.split(",") if id.strip()]
+                if device_ids
+                else []
+            )
+        return await CompositeQueries.clean_scada_data(
+            timescale_conn, postgres_conn, device_ids_list, start_time, end_time
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/composite/pipeline-health-prediction", summary="预测管道健康状况")
+async def predict_pipeline_health(
+    query_time: datetime = Query(..., description="查询时间"),
+    network_name: str = Query(..., description="管网名称（或数据库名称）"),
+    timescale_conn: AsyncConnection = Depends(get_timescale_connection),
+):
+    """
+    预测管道健康状况
+    
+    根据管网名称和当前时间，查询管道信息和实时数据，
+    使用随机生存森林模型预测管道的生存概率。
+
+    Args:
+        query_time: 查询时间
+        network_name: 管网名称（或数据库名称）
+        timescale_conn: TimescaleDB连接
+
+    Returns:
+        预测结果列表，每个元素包含 link_id 和对应的生存函数
+
+    Raises:
+        HTTPException: 当模型文件不存在返回404错误，其他错误返回400或500错误
+    """
+    try:
+        return await CompositeQueries.predict_pipeline_health(
+            timescale_conn, network_name, query_time
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"内部服务器错误: {str(e)}")

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

@@ -0,0 +1,19 @@
+from fastapi import Depends
+from psycopg import AsyncConnection
+
+from app.auth.project_dependencies import (
+    get_project_pg_connection,
+    get_project_timescale_connection,
+)
+
+
+async def get_timescale_connection(
+    conn: AsyncConnection = Depends(get_project_timescale_connection),
+):
+    yield conn
+
+
+async def get_postgres_connection(
+    conn: AsyncConnection = Depends(get_project_pg_connection),
+):
+    yield conn

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

@@ -0,0 +1,289 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
+from typing import List
+from datetime import datetime
+from psycopg import AsyncConnection
+
+from app.infra.db.timescaledb.repositories.realtime import RealtimeRepository
+from .dependencies import get_timescale_connection
+
+router = APIRouter()
+
+TIME_WITH_TZ_DESC = "ISO 8601 / RFC 3339 时间，必须显式带时区；可直接传 UTC+8，服务端会先转换为 UTC 再处理。"
+TIME_RANGE_START_DESC = f"时间范围开始时间。{TIME_WITH_TZ_DESC}"
+TIME_RANGE_END_DESC = f"时间范围结束时间。{TIME_WITH_TZ_DESC}"
+
+
+@router.post("/realtime/links/batch", status_code=201, summary="批量插入实时管道数据")
+async def insert_realtime_links(
+    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",
+    summary="查询实时管道数据",
+    description="按时间范围查询实时管道数据。start_time 和 end_time 必须显式带时区；允许传 UTC+8，服务端会先归一化为 UTC 再执行查询。",
+)
+async def get_realtime_links(
+    start_time: datetime = Query(..., description=TIME_RANGE_START_DESC),
+    end_time: datetime = Query(..., description=TIME_RANGE_END_DESC),
+    conn: AsyncConnection = Depends(get_timescale_connection),
+):
+    """
+    查询指定时间范围内的实时管道数据
+    
+    根据时间范围查询所有实时管道的监测值。传入时间必须显式包含时区，
+    可以直接使用 UTC+8，服务端会先统一转换为 UTC 再参与数据库查询。
+    
+    Args:
+        start_time: 查询开始时间
+        end_time: 查询结束时间
+        
+    Returns:
+        实时管道数据列表
+    """
+    return await RealtimeRepository.get_links_by_time_range(conn, start_time, end_time)
+
+
+@router.delete(
+    "/realtime/links",
+    summary="删除实时管道数据",
+    description="按时间范围删除实时管道数据。start_time 和 end_time 必须显式带时区；允许传 UTC+8，服务端按请求中的绝对时间删除对应 UTC 数据。",
+)
+async def delete_realtime_links(
+    start_time: datetime = Query(..., description=TIME_RANGE_START_DESC),
+    end_time: datetime = Query(..., description=TIME_RANGE_END_DESC),
+    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", summary="更新实时管道字段")
+async def update_realtime_link_field(
+    link_id: str = Path(..., description="管道ID"),
+    time: datetime = Query(..., description=f"要更新记录的时间戳。{TIME_WITH_TZ_DESC}"),
+    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"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/realtime/nodes/batch", status_code=201, summary="批量插入实时节点数据")
+async def insert_realtime_nodes(
+    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",
+    summary="查询实时节点数据",
+    description="按时间范围查询实时节点数据。start_time 和 end_time 必须显式带时区；允许传 UTC+8，服务端会先归一化为 UTC 再执行查询。",
+)
+async def get_realtime_nodes(
+    start_time: datetime = Query(..., description=TIME_RANGE_START_DESC),
+    end_time: datetime = Query(..., description=TIME_RANGE_END_DESC),
+    conn: AsyncConnection = Depends(get_timescale_connection),
+):
+    """
+    查询指定时间范围内的实时节点数据
+    
+    根据时间范围查询所有实时节点的监测值。传入时间必须显式包含时区，
+    可以直接使用 UTC+8，服务端会先统一转换为 UTC 再参与数据库查询。
+    
+    Args:
+        start_time: 查询开始时间
+        end_time: 查询结束时间
+        
+    Returns:
+        实时节点数据列表
+    """
+    return await RealtimeRepository.get_nodes_by_time_range(conn, start_time, end_time)
+
+
+@router.delete(
+    "/realtime/nodes",
+    summary="删除实时节点数据",
+    description="按时间范围删除实时节点数据。start_time 和 end_time 必须显式带时区；允许传 UTC+8，服务端按请求中的绝对时间删除对应 UTC 数据。",
+)
+async def delete_realtime_nodes(
+    start_time: datetime = Query(..., description=TIME_RANGE_START_DESC),
+    end_time: datetime = Query(..., description=TIME_RANGE_END_DESC),
+    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, summary="存储实时模拟结果")
+async def store_realtime_simulation_result(
+    node_result_list: List[dict] = Body(..., description="节点模拟结果列表"),
+    link_result_list: List[dict] = Body(..., description="管道模拟结果列表"),
+    result_start_time: str = Query(..., description=f"模拟结果开始时间。{TIME_WITH_TZ_DESC}"),
+    conn: AsyncConnection = Depends(get_timescale_connection),
+):
+    """
+    存储实时模拟结果到时间序列数据库
+    
+    将节点和管道的实时模拟计算结果批量存储到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",
+    summary="按时间和属性查询实时数据",
+    description="查询指定时间点的实时属性值。query_time 必须显式带时区；允许传 UTC+8，服务端会先归一化为 UTC 再执行查询。",
+)
+async def query_realtime_records_by_time_property(
+    query_time: str = Query(..., description=f"查询时间。{TIME_WITH_TZ_DESC}"),
+    type: str = Query(..., description="数据类型，pipe（管道）或 junction（节点）"),
+    property: str = Query(..., description="要查询的属性名称"),
+    conn: AsyncConnection = Depends(get_timescale_connection),
+):
+    """
+    按指定时间和属性查询所有实时监测数据
+    
+    查询在特定时间点，所有指定类型元素的特定属性值。
+    
+    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
+        )
+        return {"results": results}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get(
+    "/realtime/query/by-id-time",
+    summary="按ID和时间查询实时模拟数据",
+    description="查询指定元素在某一时间点的实时模拟结果。query_time 必须显式带时区；允许传 UTC+8，服务端会先归一化为 UTC 再执行查询。",
+)
+async def query_realtime_simulation_by_id_time(
+    id: str = Query(..., description="元素ID（管道ID或节点ID）"),
+    type: str = Query(..., description="元素类型，pipe（管道）或 junction（节点）"),
+    query_time: str = Query(..., description=f"查询时间。{TIME_WITH_TZ_DESC}"),
+    conn: AsyncConnection = Depends(get_timescale_connection),
+):
+    """
+    按指定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
+        )
+        return {"result": results}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))

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

@@ -0,0 +1,159 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
+from typing import List
+from datetime import datetime
+from psycopg import AsyncConnection
+
+from app.infra.db.timescaledb.repositories.scada import ScadaRepository
+from .dependencies import get_timescale_connection
+
+router = APIRouter()
+
+
+@router.post("/scada/batch", status_code=201, summary="批量插入SCADA监测数据")
+async def insert_scada_data(
+    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", summary="按设备ID和时间范围查询SCADA数据")
+async def get_scada_by_ids_time_range(
+    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 []
+    )
+    return await ScadaRepository.get_scada_by_ids_time_range(
+        conn, device_ids_list, start_time, end_time
+    )
+
+
+@router.get(
+    "/scada/by-ids-field-time-range", summary="按设备ID、字段和时间范围查询SCADA数据"
+)
+async def get_scada_field_by_ids_time_range(
+    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()]
+            if device_ids
+            else []
+        )
+        return await ScadaRepository.get_scada_field_by_id_time_range(
+            conn, device_ids_list, start_time, end_time, field
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.patch("/scada/{device_id}/field", summary="更新SCADA设备字段")
+async def update_scada_field(
+    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"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/scada/by-id-time-range", summary="按设备ID和时间范围删除SCADA数据")
+async def delete_scada_data(
+    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
+    )
+    return {"message": "Deleted successfully"}

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

@@ -0,0 +1,391 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
+from typing import List
+from datetime import datetime
+from psycopg import AsyncConnection
+
+from app.infra.db.timescaledb.repositories.scheme import SchemeRepository
+from .dependencies import get_timescale_connection
+
+router = APIRouter()
+
+
+@router.post("/scheme/links/batch", status_code=201, summary="批量插入方案管道数据")
+async def insert_scheme_links(
+    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", summary="查询方案管道数据")
+async def get_scheme_links(
+    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", summary="查询方案管道字段数据")
+async def get_scheme_link_field(
+    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
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.patch("/scheme/links/{link_id}/field", summary="更新方案管道字段")
+async def update_scheme_link_field(
+    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
+        )
+        return {"message": "Updated successfully"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/scheme/links", summary="删除方案管道数据")
+async def delete_scheme_links(
+    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, summary="批量插入方案节点数据")
+async def insert_scheme_nodes(
+    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", summary="查询方案节点字段数据")
+async def get_scheme_node_field(
+    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
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.patch("/scheme/nodes/{node_id}/field", summary="更新方案节点字段")
+async def update_scheme_node_field(
+    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
+        )
+        return {"message": "Updated successfully"}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/scheme/nodes", summary="删除方案节点数据")
+async def delete_scheme_nodes(
+    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, summary="存储方案模拟结果")
+async def store_scheme_simulation_result(
+    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),
+):
+    """
+    存储方案模拟结果到时间序列数据库
+
+    将特定方案的节点和管道模拟计算结果批量存储到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,
+        scheme_name,
+        node_result_list,
+        link_result_list,
+        result_start_time,
+    )
+    return {"message": "Scheme simulation results stored successfully"}
+
+
+@router.get(
+    "/scheme/query/by-scheme-time-property", summary="按方案、时间和属性查询数据"
+)
+async def query_scheme_records_by_scheme_time_property(
+    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),
+):
+    """
+    按指定方案、时间和属性查询所有方案数据
+
+    查询在特定方案和时间点，所有指定类型元素的特定属性值。
+
+    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
+        )
+        return {"results": results}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/scheme/query/by-id-time", summary="按ID和时间查询方案模拟数据")
+async def query_scheme_simulation_by_id_time(
+    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),
+):
+    """
+    按指定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
+        )
+        return {"result": result}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))

app/api/v1/endpoints/user_management.py

@@ -1,180 +0,0 @@
-"""
-用户管理 API 接口
-
-演示权限控制的使用
-"""
-from typing import List
-from fastapi import APIRouter, Depends, HTTPException, status
-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.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])
-async def list_users(
-    skip: int = 0,
-    limit: int = 100,
-    current_user: UserInDB = Depends(require_role(UserRole.ADMIN)),
-    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)
-async def get_user(
-    user_id: int,
-    current_user: UserInDB = Depends(get_current_active_user),
-    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"
-        )
-    
-    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"
-        )
-    
-    return UserResponse.model_validate(user)
-
-@router.put("/{user_id}", response_model=UserResponse)
-async def update_user(
-    user_id: int,
-    user_update: UserUpdate,
-    current_user: UserInDB = Depends(get_current_active_user),
-    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"
-        )
-    
-    # 权限检查
-    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"
-        )
-    
-    # 非管理员不能修改角色和激活状态
-    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"
-            )
-        if user_update.is_active is not None:
-            raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
-                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"
-        )
-    
-    return UserResponse.model_validate(updated_user)
-
-@router.delete("/{user_id}")
-async def delete_user(
-    user_id: int,
-    current_user: UserInDB = Depends(get_current_admin),
-    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"
-        )
-    
-    success = await user_repo.delete_user(user_id)
-    if not success:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="User not found"
-        )
-    
-    return {"message": "User deleted successfully"}
-
-@router.post("/{user_id}/activate")
-async def activate_user(
-    user_id: int,
-    current_user: UserInDB = Depends(get_current_admin),
-    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"
-        )
-    
-    return UserResponse.model_validate(updated_user)
-
-@router.post("/{user_id}/deactivate")
-async def deactivate_user(
-    user_id: int,
-    current_user: UserInDB = Depends(get_current_admin),
-    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"
-        )
-    
-    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"
-        )
-    
-    return UserResponse.model_validate(updated_user)

app/api/v1/endpoints/users.py

@@ -1,6 +1,6 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query
 from typing import Any, List, Dict, Union
-from app.services.tjnetwork import *
+from app.services.tjnetwork import Any, get_all_users, get_user, get_user_schema
 
 router = APIRouter()
 
@@ -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/api/v1/endpoints/web_search.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.services.web_search import (
+    BochaSearchAPIError,
+    BochaSearchConfigError,
+    WebSearchRequest,
+    search_bocha_web,
+)
+
+router = APIRouter()
+
+
+@router.post(
+    "/web-search",
+    summary="Web Search",
+    description="调用 Bocha Web Search API 获取实时网页搜索结果",
+)
+async def web_search(request: WebSearchRequest) -> dict[str, Any]:
+    try:
+        return await search_bocha_web(request)
+    except BochaSearchConfigError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=str(exc),
+        ) from exc
+    except BochaSearchAPIError as exc:
+        raise HTTPException(status_code=exc.status_code, detail=exc.detail) from exc

app/api/v1/router.py

@@ -1,20 +1,24 @@
 from fastapi import APIRouter
 from app.api.v1.endpoints import (
-    auth,
+    admin_metadata,
+    agent_auth,
     project,
     simulation,
     scada,
     extension,
     snapshots,
-    data_query,
     users,
     schemes,
     misc,
     risk,
     cache,
-    user_management,  # 新增：用户管理
+    leakage,
+    burst_detection,
+    burst_location,
     audit,  # 新增：审计日志
     meta,
+    web_search,
+    geocoding,
 )
 from app.api.v1.endpoints.network import (
     general,
@@ -38,14 +42,21 @@ from app.api.v1.endpoints.components import (
     visuals,
 )
 
-from app.infra.db.postgresql import router as postgresql_router
-from app.infra.db.timescaledb import router as timescaledb_router
+from app.api.v1.endpoints import project_data
+from app.api.v1.endpoints.timeseries import (
+    realtime as ts_realtime,
+    scheme as ts_scheme,
+    scada as ts_scada,
+    composite as ts_composite,
+)
 
 api_router = APIRouter()
 
 # Core Services
-api_router.include_router(auth.router, prefix="/auth", tags=["Auth"])
-api_router.include_router(user_management.router, prefix="/users", tags=["User Management"])  # 新增
+api_router.include_router(agent_auth.router, tags=["Agent Auth"])
+api_router.include_router(
+    admin_metadata.router, prefix="/admin", tags=["Metadata Admin"]
+)
 api_router.include_router(audit.router, prefix="/audit", tags=["Audit Logs"])  # 新增
 api_router.include_router(meta.router, tags=["Metadata"])
 api_router.include_router(project.router, tags=["Project"])
@@ -75,18 +86,31 @@ api_router.include_router(visuals.router, tags=["Visuals"])
 
 # Simulation & Data
 api_router.include_router(simulation.router, tags=["Simulation Control"])
-api_router.include_router(data_query.router, tags=["Data Query & InfluxDB"])
-api_router.include_router(scada.router, tags=["SCADA"])
+api_router.include_router(scada.router)
 api_router.include_router(snapshots.router, tags=["Snapshots"])
 api_router.include_router(users.router, tags=["Users"])
 api_router.include_router(schemes.router, tags=["Schemes"])
 api_router.include_router(misc.router, tags=["Misc"])
 api_router.include_router(risk.router, tags=["Risk"])
 api_router.include_router(cache.router, tags=["Cache"])
+api_router.include_router(web_search.router, tags=["Web Search"])
+api_router.include_router(geocoding.router, tags=["Geocoding"])
+api_router.include_router(leakage.router, prefix="/leakage", tags=["Leakage"])
+api_router.include_router(
+    burst_detection.router, prefix="/burst-detection", tags=["Burst Detection"]
+)
+api_router.include_router(
+    burst_location.router, prefix="/burst-location", tags=["Burst Location"]
+)
 
-# Database Routers
-api_router.include_router(timescaledb_router, tags=["TimescaleDB"])
-api_router.include_router(postgresql_router, tags=["PostgreSQL"])
+# TimescaleDB Data Access
+api_router.include_router(ts_realtime.router, tags=["TimescaleDB - Realtime"])
+api_router.include_router(ts_scheme.router, tags=["TimescaleDB - Scheme"])
+api_router.include_router(ts_scada.router, tags=["TimescaleDB - SCADA"])
+api_router.include_router(ts_composite.router, tags=["TimescaleDB - Composite"])
+
+# Project Data (PostgreSQL)
+api_router.include_router(project_data.router, tags=["Project Data"])
 
 # Extension
 api_router.include_router(extension.router, tags=["Extension"])

app/audit/__init__.py

@@ -0,0 +1,9 @@
+"""
+This module is reserved for future implementation of audit logging and compliance features.
+
+Current implementation of audit logging can be found in `app.core.audit`.
+Future expansion may include:
+- Comprehensive audit trails for all system actions
+- Compliance reporting (e.g., for industrial control systems)
+- Anomaly detection in user behavior
+"""

app/auth/dependencies.py

@@ -1,100 +0,0 @@
-from typing import Annotated, Optional
-from fastapi import Depends, HTTPException, status, Request
-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.postgresql.database import Database
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.API_V1_STR}/auth/login")
-
-
-# 数据库依赖
-async def get_db(request: Request) -> Database:
-    """
-    获取数据库实例
-
-    从 FastAPI app.state 中获取在启动时初始化的数据库连接
-    """
-    if not hasattr(request.app.state, "db"):
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Database not initialized",
-        )
-    return request.app.state.db
-
-
-async def get_user_repository(db: Database = Depends(get_db)) -> UserRepository:
-    """获取用户仓储实例"""
-    return UserRepository(db)
-
-
-async def get_current_user(
-    token: str = Depends(oauth2_scheme),
-    user_repo: UserRepository = Depends(get_user_repository),
-) -> UserInDB:
-    """
-    获取当前登录用户
-
-    从 JWT Token 中解析用户信息，并从数据库验证
-    """
-    credentials_exception = HTTPException(
-        status_code=status.HTTP_401_UNAUTHORIZED,
-        detail="Could not validate credentials",
-        headers={"WWW-Authenticate": "Bearer"},
-    )
-
-    try:
-        payload = jwt.decode(
-            token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM]
-        )
-        username: str = payload.get("sub")
-        token_type: str = payload.get("type", "access")
-
-        if username is None:
-            raise credentials_exception
-
-        if token_type != "access":
-            raise HTTPException(
-                status_code=status.HTTP_401_UNAUTHORIZED,
-                detail="Invalid token type. Access token required.",
-                headers={"WWW-Authenticate": "Bearer"},
-            )
-
-    except JWTError:
-        raise credentials_exception
-
-    # 从数据库获取用户
-    user = await user_repo.get_user_by_username(username)
-    if user is None:
-        raise credentials_exception
-
-    return user
-
-
-async def get_current_active_user(
-    current_user: UserInDB = Depends(get_current_user),
-) -> UserInDB:
-    """
-    获取当前活跃用户（必须是激活状态）
-    """
-    if not current_user.is_active:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user"
-        )
-    return current_user
-
-
-async def get_current_superuser(
-    current_user: UserInDB = Depends(get_current_user),
-) -> UserInDB:
-    """
-    获取当前超级管理员用户
-    """
-    if not current_user.is_superuser:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Not enough privileges. Superuser access required.",
-        )
-    return current_user

app/auth/keycloak_dependencies.py

@@ -8,35 +8,41 @@ from jose import JWTError, jwt
 from app.core.config import settings
 
 oauth2_optional = OAuth2PasswordBearer(
-    tokenUrl=f"{settings.API_V1_STR}/auth/login", auto_error=False
+    tokenUrl="keycloak", auto_error=False
 )
 
 # logger = logging.getLogger(__name__)
 
 
-async def get_current_keycloak_sub(
+def _decode_keycloak_token(token: str) -> dict:
+    if not settings.KEYCLOAK_PUBLIC_KEY:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Keycloak public key is not configured",
+        )
+
+    key = settings.KEYCLOAK_PUBLIC_KEY.replace("\\n", "\n")
+
+    return jwt.decode(
+        token,
+        key,
+        algorithms=[settings.KEYCLOAK_ALGORITHM],
+        audience=settings.KEYCLOAK_AUDIENCE or None,
+    )
+
+
+async def get_current_keycloak_payload(
     token: str | None = Depends(oauth2_optional),
-) -> UUID:
+) -> dict:
     if not token:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Not authenticated",
             headers={"WWW-Authenticate": "Bearer"},
         )
-    if settings.KEYCLOAK_PUBLIC_KEY:
-        key = settings.KEYCLOAK_PUBLIC_KEY.replace("\\n", "\n")
-        algorithms = [settings.KEYCLOAK_ALGORITHM]
-    else:
-        key = settings.SECRET_KEY
-        algorithms = [settings.ALGORITHM]
 
     try:
-        payload = jwt.decode(
-            token,
-            key,
-            algorithms=algorithms,
-            audience=settings.KEYCLOAK_AUDIENCE or None,
-        )
+        return _decode_keycloak_token(token)
     except JWTError as exc:
         # logger.warning("Keycloak token validation failed: %s", exc)
         raise HTTPException(
@@ -45,6 +51,10 @@ async def get_current_keycloak_sub(
             headers={"WWW-Authenticate": "Bearer"},
         ) from exc
 
+
+async def get_current_keycloak_sub(
+    payload: dict = Depends(get_current_keycloak_payload),
+) -> UUID:
     sub = payload.get("sub")
     if not sub:
         raise HTTPException(
@@ -61,3 +71,16 @@ async def get_current_keycloak_sub(
             detail="Invalid subject claim",
             headers={"WWW-Authenticate": "Bearer"},
         ) from exc
+
+
+async def get_current_keycloak_username(
+    payload: dict = Depends(get_current_keycloak_payload),
+) -> str:
+    username = payload.get("preferred_username") or payload.get("username")
+    if not username:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing username claim",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return str(username)

app/auth/metadata_dependencies.py

@@ -6,10 +6,9 @@ from fastapi import Depends, HTTPException, status
 from sqlalchemy.exc import SQLAlchemyError
 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.auth.keycloak_dependencies import get_current_keycloak_payload
+from app.infra.db.metadb.database import get_metadata_session
+from app.infra.db.metadb.repositories.metadata_repository import MetadataRepository
 
 logger = logging.getLogger(__name__)
 
@@ -20,10 +19,40 @@ async def get_metadata_repository(
     return MetadataRepository(session)
 
 
+def _keycloak_sub_from_payload(payload: dict) -> UUID:
+    sub = payload.get("sub")
+    if not sub:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing subject claim",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    try:
+        return UUID(str(sub))
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid subject claim",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from exc
+
+
+def _username_from_payload(payload: dict) -> str | None:
+    username = payload.get("preferred_username") or payload.get("username")
+    return str(username) if username else None
+
+
+def _email_from_payload(payload: dict) -> str | None:
+    email = payload.get("email")
+    return str(email) if email else None
+
+
 async def get_current_metadata_user(
-    keycloak_sub: UUID = Depends(get_current_keycloak_sub),
+    keycloak_payload: dict = Depends(get_current_keycloak_payload),
     metadata_repo: MetadataRepository = Depends(get_metadata_repository),
 ):
+    keycloak_sub = _keycloak_sub_from_payload(keycloak_payload)
     try:
         user = await metadata_repo.get_user_by_keycloak_id(keycloak_sub)
     except SQLAlchemyError as exc:
@@ -39,6 +68,21 @@ async def get_current_metadata_user(
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user"
         )
+    try:
+        user = await metadata_repo.refresh_user_keycloak_snapshot(
+            user,
+            username=_username_from_payload(keycloak_payload),
+            email=_email_from_payload(keycloak_payload),
+        )
+    except SQLAlchemyError as exc:
+        logger.error(
+            "Metadata DB error while refreshing current user snapshot",
+            exc_info=True,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Metadata database error: {exc}",
+        ) from exc
     return user
 
 

app/auth/permissions.py

@@ -1,106 +0,0 @@
-"""
-权限控制依赖项和装饰器
-
-基于角色的访问控制（RBAC）
-"""
-from typing import Callable
-from fastapi import Depends, HTTPException, status
-from app.domain.models.role import UserRole
-from app.domain.schemas.user import UserInDB
-from app.auth.dependencies import get_current_active_user
-
-def require_role(required_role: UserRole):
-    """
-    要求特定角色或更高权限
-    
-    用法:
-        @router.get("/admin-only")
-        async def admin_endpoint(user: UserInDB = Depends(require_role(UserRole.ADMIN))):
-            ...
-    
-    Args:
-        required_role: 需要的最低角色
-        
-    Returns:
-        依赖函数
-    """
-    async def role_checker(
-        current_user: UserInDB = Depends(get_current_active_user)
-    ) -> UserInDB:
-        user_role = UserRole(current_user.role)
-        
-        if not user_role.has_permission(required_role):
-            raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
-                detail=f"Insufficient permissions. Required role: {required_role.value}, "
-                       f"Your role: {user_role.value}"
-            )
-        
-        return current_user
-    
-    return role_checker
-
-# 预定义的权限检查依赖
-require_admin = require_role(UserRole.ADMIN)
-require_operator = require_role(UserRole.OPERATOR)
-require_user = require_role(UserRole.USER)
-
-def get_current_admin(
-    current_user: UserInDB = Depends(require_admin)
-) -> UserInDB:
-    """
-    获取当前管理员用户
-    
-    等同于 Depends(require_role(UserRole.ADMIN))
-    """
-    return current_user
-
-def get_current_operator(
-    current_user: UserInDB = Depends(require_operator)
-) -> UserInDB:
-    """
-    获取当前操作员用户（或更高权限）
-    
-    等同于 Depends(require_role(UserRole.OPERATOR))
-    """
-    return current_user
-
-def check_resource_owner(user_id: int, current_user: UserInDB) -> bool:
-    """
-    检查是否是资源拥有者或管理员
-    
-    Args:
-        user_id: 资源拥有者ID
-        current_user: 当前用户
-        
-    Returns:
-        是否有权限
-    """
-    # 管理员可以访问所有资源
-    if UserRole(current_user.role).has_permission(UserRole.ADMIN):
-        return True
-    
-    # 检查是否是资源拥有者
-    return current_user.id == user_id
-
-def require_owner_or_admin(user_id: int):
-    """
-    要求是资源拥有者或管理员
-    
-    Args:
-        user_id: 资源拥有者ID
-        
-    Returns:
-        依赖函数
-    """
-    async def owner_or_admin_checker(
-        current_user: UserInDB = Depends(get_current_active_user)
-    ) -> UserInDB:
-        if not check_resource_owner(user_id, current_user):
-            raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
-                detail="You don't have permission to access this resource"
-            )
-        return current_user
-    
-    return owner_or_admin_checker

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"
@@ -25,6 +25,7 @@ logger = logging.getLogger(__name__)
 @dataclass(frozen=True)
 class ProjectContext:
     project_id: UUID
+    project_code: str
     user_id: UUID
     project_role: str
 
@@ -85,6 +86,7 @@ async def get_project_context(
 
     return ProjectContext(
         project_id=project.id,
+        project_code=project.code,
         user_id=user.id,
         project_role=membership_role,
     )

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)