---
name: tjwater-workflow-bottleneck-analysis
description: workflow 下 bottleneck-analysis（水力瓶颈分析）工作流技能。
version: 1.1.0
---

# bottleneck-analysis Workflow Skill

## 简介
负责 `analytics/simulation-analysis` 场景下的水力瓶颈综合分析，通过结合管道属性与水力模拟结果，识别管网中超负荷、高流速、高水头损失的瓶颈管道，并给出分级改造建议。

## 前置依赖
本工作流依赖以下两个数据源，需按顺序并行或串行获取：

### 依赖 1：管道属性数据
- 接口：`GET /api/v1/getallpipeproperties/`
- 参数：`network`（query，如 `tjwater`）
- 用途：获取全部管道的 id、管径(diameter)、长度(length)、粗糙度(roughness)、起端(node1)、终端(node2) 等属性
- 注意：结果可能很大（数万条），需使用 `fetch_result_ref` 分批或全量获取

### 依赖 2：水力模拟结果
- 接口：`GET /api/v1/runprojectreturndict/`
- 参数：`network`（query，如 `tjwater`）
- 用途：运行管网水力模拟，返回各管段的 flow(LPS)、velocity(m/s)、headloss(m)、status，以及各节点的 demand、head、pressure(KPA)
- 注意：结果可达 30MB+，需用 Python 脚本批量处理或使用 `fetch_result_ref` 回读

## 工作流步骤

### 第 1 步：并行获取管道属性和运行水力模拟
同时调用 `getallpipeproperties` 和 `runprojectreturndict`，network 参数使用项目名称（如 `tjwater`）。

### 第 2 步：合并数据
用 Python 脚本将管道属性的 pipe_id 与模拟结果的 link_id 进行关联，构建含以下字段的合并数据集：

| 字段 | 来源 | 说明 |
|------|------|------|
| id | 两者关联键 | 管道/链路 ID |
| flow | 模拟 link_results | 流量 (LPS) |
| velocity | 模拟 link_results | 流速 (m/s) |
| headloss | 模拟 link_results | 水头损失 (m) |
| diameter | 管道属性 | 管径 (mm) |
| length | 管道属性 | 长度 (m) |
| roughness | 管道属性 | 粗糙度系数 |
| node1 / node2 | 管道属性 | 起端/终端节点 ID |
| unit_headloss | 计算 | headloss / length (m/m) |
| capacity_ratio | 计算 | |flow| / (π×(d/2000)²×1000)，即实际流量与 1m/s 设计流量的比值 |

同时从模拟 node_results 提取各节点 pressure，关联到管段两端。

### 第 3 步：多维度瓶颈识别
按以下 5 个维度分别排序筛选，交叉印证：

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

排除极短管道（length < 0.5m）以减少噪声。

### 第 4 步：综合评分
对有效管道计算综合瓶颈分数：

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

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

### 第 5 步：前端可视化
- 使用 `show_chart` 展示流速分布柱状图
- 使用 `locate_features` 在地图上定位 TOP 瓶颈管道（feature_type=pipe）
- 可选：使用 `view_history` 查看瓶颈管道的历史运行数据
- 前端工具仅用于展示，分析结论必须来自 `dynamic_http_call` / `fetch_result_ref` 获得的数据

### 第 6 步：给出分级改造建议
按严重程度分为三级：

- **🚨 紧急**：综合评分 > 0.3，立即安排管径升级
- **⚡ 重点**：综合评分 0.15~0.3，纳入近期改造计划
- **📋 关注**：综合评分 0.05~0.15 或单维度超标，持续监测

每条建议含：当前管径 → 建议管径（基于目标流速 1.0~1.5 m/s 反推），并附改造理由。

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

## 证据约束

- 如果关键数据仍处于 preview 状态，不得直接输出最终瓶颈结论
- 如果模拟结果不完整或接口失败，应明确说明当前仅能做初步筛查
- 改造建议必须区分“数据直接支持的结论”和“工程经验推断”

## 推荐输出结构

1. 分析范围与数据来源
2. 主要瓶颈管段 Top N
3. 分级建议（紧急 / 重点 / 关注）
4. 假设与局限
5. 是否建议地图定位或图表展示

## 参考
- 管道属性操作：`../business/network-assets/pipes/SKILL.md`
- 模拟操作：`./simulation/SKILL.md`
- 节点属性操作：`../business/network-assets/junctions/SKILL.md`

## Learned Patterns
- 先按“属性数据获取 → 模拟结果获取 → 本地关联 → 多指标筛选 → 分级建议”拆解工作流，再组织展示步骤，避免把一次分析过程写成会话流水账。
- 结果集较大时，优先使用 `fetch_result_ref` 或本地脚本批处理；只要数据仍是 preview、截断或未完整回读，就不能直接输出 Top N 瓶颈结论。
- 关联前先统一关键字段和单位：`pipe_id/link_id`、`diameter(mm)`、`length(m)`、`flow(LPS)`、`pressure(KPA)`；字段未对齐时，后续 ranking 和建议都会失真。
- `unit_headloss`、`capacity_ratio` 等衍生指标应在过滤异常数据（如 `length < 0.5m` 的短管）后再计算，否则容易被极端值放大。
- 阈值和评分权重应视为可调启发式，而不是唯一真理；输出时要区分“数据直接支持的结论”和“工程经验推断的建议”。
- 地图定位、图表展示属于证据呈现层，不能替代分析层；瓶颈判定必须基于后端原始结果或完整回读数据。
- 常见坑点：短管导致单位水头损失虚高、节点或链路映射缺失导致误判、模拟结果不完整时误把局部结果当全量结论。