---
name: tjwater-workflow-bottleneck-analysis
description: 水力瓶颈分析工作流。
version: 2.0.0
---

# bottleneck-analysis Workflow Skill

## 简介
结合管道属性与水力模拟结果，识别管网中超负荷、高流速、高水头损失的瓶颈管道，计算综合评分并给出分级改造建议。

## 前置依赖

### 依赖 1：管道属性数据
```
tjwater_cli:
  command: "network get-link-properties --link P1"
```
逐条查询所需管道 ID 的属性（id、diameter、length、roughness、node1、node2）。
> 首批 CLI 仅支持按 ID 单项查询，需对目标管段逐个调用。

### 依赖 2：水力模拟结果
```
tjwater_cli:
  command: "data timeseries realtime links --start-time TIME --end-time TIME"
  timeout: 300
```
获取全部管段的 flow(LPS)、velocity(m/s)、headloss(m)、status 等。

---

## 工作流步骤

### 第 1 步：获取管道属性
从 `simulation-diagnosis` 输出的 TOP 问题管段 ID 列表出发，逐条调用 `network get-link-properties --link ID` 获取管径/长度/粗糙度。

### 第 2 步：获取模拟结果
调用 `data timeseries realtime links` 获取对应时间窗口的全部管道水力结果。

### 第 3 步：合并数据
Python 脚本将管道属性 `id` 与模拟结果的 `link_id` 关联，构建合并数据集：

| 字段 | 来源 | 说明 |
|------|------|------|
| id | 关联键 | 管道 ID |
| flow | 模拟 | 流量 (LPS) |
| velocity | 模拟 | 流速 (m/s) |
| headloss | 模拟 | 水头损失 (m) |
| diameter | 管道属性 | 管径 (mm) |
| length | 管道属性 | 长度 (m) |
| roughness | 管道属性 | 粗糙度系数 |
| node1 / node2 | 管道属性 | 起端/终端节点 |
| unit_headloss | 计算 | headloss / length (m/m) |
| capacity_ratio | 计算 | \|flow\| / (π×(d/2000)²×1000) |

### 第 4 步：多维度瓶颈识别

| 维度 | 筛选条件 | 指示含义 |
|------|---------|---------|
| 高流速 | velocity > 1.2 m/s | 管径不足 |
| 主干管高流量 | diameter ≥ 300mm 且 velocity > 0.5 m/s | 传输瓶颈 |
| 高水头损失 | headloss > 5m 且 0.3 < velocity < 1.5 | 能耗瓶颈 |
| 高单位水头损失 | unit_headloss > 1.0 m/m | 严重局部瓶颈 |
| 超负荷 | capacity_ratio > 1.0 | 超过设计能力 |

排除极短管道（length < 0.5m）。

### 第 5 步：综合评分

```
composite_score = (velocity / max_velocity) × 0.4
                + (headloss / max_headloss) × 0.3
                + (capacity_ratio / max_capacity_ratio) × 0.3
```

取 TOP 10~20 作为最严重瓶颈管道。

### 第 6 步：分级改造建议

| 级别 | 评分范围 | 行动 |
|------|---------|------|
| 🚨 紧急 | > 0.3 | 立即安排管径升级 |
| ⚡ 重点 | 0.15~0.3 | 纳入近期改造计划 |
| 📋 关注 | 0.05~0.15 | 持续监测 |

建议管径公式：
```
建议管径(mm) = 2 × 1000 × sqrt(|flow| / (π × target_velocity × 1000))
```
DN<300 目标流速 1.0 m/s，DN≥300 目标流速 1.2 m/s。

### 第 7 步：可视化
- `show_chart`：流速分布柱状图
- `locate_features`：地图定位 TOP 瓶颈管道

---

## 证据约束
- 关键数据不完整时不得输出最终瓶颈结论
- 改造建议必须区分"数据直接支持"和"工程经验推断"

## Learned Patterns
- 先按"属性数据获取 → 模拟结果获取 → 本地关联 → 多指标筛选 → 分级建议"拆解工作流。
- 关联前统一字段：`link_id`、`diameter(mm)`、`length(m)`、`flow(LPS)`、`pressure(KPA)`。
- `unit_headloss`、`capacity_ratio` 等衍生指标应在过滤异常数据后再计算。
- 常见坑点：短管导致单位水头损失虚高、节点链路映射缺失、模拟结果不完整误当全量结论。