---
name: tjwater-workflow-source-service-area-analysis
description: 水源服务范围分区分析工作流。
version: 2.0.0
---

# Source Service Area Analysis Workflow Skill

## 简介
基于水力模拟结果的流向数据构建有向图，通过下游遍历确定每个节点的供水水源归属，生成分区渲染数据并在地图上以不同颜色展示各水源的服务范围。

## 前置依赖

### 依赖 1：水库（水源）列表
从模拟结果的 node_results 中识别 type=reservoir 的节点，或逐条查询已知水库节点。

### 依赖 2：管道拓扑数据
```
tjwater_cli:
  command: "network get-link-properties --link P1"
```
逐条获取管道 ID 的 node1（起端）、node2（终端），构建管网拓扑。

### 依赖 3：水力模拟结果
```
tjwater_cli:
  command: "data timeseries realtime links --start-time TIME --end-time TIME"
  timeout: 300
```
获取各管段的 `flow`(LPS) 和 `status`，确定水流方向。
- `flow > 0` → node1 → node2
- `flow < 0` → node2 → node1
- `flow ≈ 0` 或 `status != "Open"` → 忽略

---

## 工作流步骤

### 第 1 步：获取三大数据源
并行调用 CLI 命令获取模拟结果、管道拓扑和水库信息，写入本地临时 JSON 文件。

### 第 2 步：构建有向图并计算服务范围

```bash
python scripts/compute_service_areas.py \
  /tmp/opencode/sim_result.json \
  /tmp/opencode/pipes.json \
  /tmp/opencode/reservoirs.json \
  --output /tmp/opencode/service_area_result.json
```

脚本核心逻辑：
1. **构建无向拓扑图**：从管道属性提取 `(node1, node2)`，构建邻接表
2. **确定流向**：从模拟结果读取 flow 和 status
   - flow > 0 → node1 → node2
   - flow < 0 → node2 → node1
   - flow ≈ 0 或 status != "Open" → 忽略
3. **获取水源集合**：从水库列表提取所有水库 ID 作为 source nodes
4. **多源 BFS 下游遍历**：从所有水源节点同时出发，首次访问归属策略
5. **统计输出**：各水源服务节点数、占比、未分配节点数
6. **生成渲染数据**：`node_area_map: { node_id: area_id }`，每个水源分配唯一颜色

### 第 3 步：结果验证
- **服务覆盖率**：正常管网应 > 80%
- **水源孤立**：某水源服务节点数为 0，检查出口管道是否 Closed
- **大区未分配**：检查区域与水源之间管道是否 Closed

### 第 4 步：前端可视化
1. `store_render_ref` 将 `node_area_map` 迁移为受控 `render_ref`
2. `render_junctions` 地图着色
3. `locate_features` 高亮水源位置
4. `show_chart` 各水源服务节点数柱状图（可选）

### 第 5 步：报告输出

```
---
## 水源服务范围分析报告

### 一、管网概况
- 总节点数 / 总管段数 / 水源数 / 覆盖率

### 二、各水源服务范围
| 水源 ID | 服务节点数 | 占比 | 颜色 |

### 三、未分配节点分析
- 数量、可能原因

### 四、假设与局限
- 流向基于稳态模拟，不代表所有工况
- 有向图忽略零流量管段
```

---

## 颜色调色板
脚本内置 20 色：
```
#1f77b4, #ff7f0e, #2ca02c, #d62728, #9467bd, #8c564b, #e377c2,
#7f7f7f, #bcbd22, #17becf, #aec7e8, #ffbb78, #98df8a, #ff9896,
#c5b0d5, #c49c94, #f7b6d2, #c7c7c7, #dbdb8d, #9edae5
```

## 证据约束
- 计算脚本的输出是唯一数据真相源
- 未完成数据回读时不得执行分析
- 零流量管段视为断连，需在报告中说明

## Learned Patterns
- 核心数据流：模拟结果(流向) + 管道属性(拓扑) + 水库列表(起点) → 有向图 BFS → 分区渲染
- 有向图遍历前务必过滤 Closed 和零流量管段
- 渲染数据必须通过 `store_render_ref` 迁移再传给 `render_junctions`
- 多水源 BFS 首次访问归属策略隐含"距离最近水源"语义