后端服务将通过tjwater-cli形式访问

2026-06-02 15:31:21 +08:00
parent 20329bb771
commit 5b285ad7a5
65 changed files with 1288 additions and 2286 deletions
@@ -0,0 +1,113 @@
+---
+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 首次访问归属策略隐含"距离最近水源"语义