# 数据源与字段映射

## CLI 命令清单

### ① 管道静态属性

```bash
tjwater-cli network get-all-pipes-properties
```

返回字段：

| 字段 | 类型 | 说明 | 分析用途 |
|------|------|------|----------|
| id | string | 管段 ID | 主键，关联水力数据 |
| node1 | string | 起始节点 ID | 拓扑，定位压力 |
| node2 | string | 终止节点 ID | 拓扑，定位压力 |
| length | float | 管长 (m) | 短管高水损检测 |
| diameter | int | 管径 (mm) | 管径分级，扩容建议 |
| roughness | int | 粗糙系数 | 内衬修复判定 |
| minor_loss | float | 局部水头损失系数 | 暂未使用 |
| status | string | OPEN/CLOSED | 管道状态 |

### ② 管道实时水力

```bash
tjwater-cli data timeseries realtime links --start-time <T> --end-time <T+15min>
```

返回字段：

| 字段 | 类型 | 说明 | 分析用途 |
|------|------|------|----------|
| time | string | 时间戳 ISO8601 | 筛选目标时刻 |
| id | string | 管段 ID | 关联静态属性 |
| flow | float | 流量 | 辅助参考 |
| velocity | float | 流速 (m/s) | **核心评分指标** |
| headloss | float | 水头损失 (m) | **核心评分指标** |
| setting | float | ⚠️ 无效值 | 时序 API 返回的 setting 为无效值，不可用于判定 |
| friction | float | 摩擦系数 | 暂未使用 |
| quality | float | 水质 | 暂未使用 |
| reaction | float | 反应速率 | 暂未使用 |
| status | string | OPEN/CLOSED | 管道状态 |

### ③ 节点实时压力

```bash
tjwater-cli data timeseries realtime nodes --start-time <T> --end-time <T+15min>
```

返回字段：

| 字段 | 类型 | 说明 | 分析用途 |
|------|------|------|----------|
| time | string | 时间戳 ISO8601 | 筛选目标时刻 |
| id | string | 节点 ID | 关联管段端点 |
| pressure | float | 压力 (m) | **低压判定** |
| total_head | float | 总水头 (m) | 含高程信息 |
| actual_demand | float | 实际需水量 | 暂未使用 |
| quality | float | 水质 | 暂未使用 |

## 数据合并逻辑

```
管道属性 (pipe_map[id])  ←─id─→  实时水力 (rt[time==TT])
                                       │
                                  node1, node2
                                       │
                                       ↓
                              节点压力 (node_pressure[id])
```

合并时以**实时水力数据为主表**，左联管道属性，再通过 node1/node2 查找两端压力。

## 时间处理

- 模拟步长：15 分钟
- 查询窗口建议：T 到 T+15min（覆盖 1-2 步）
- 脚本内精确筛选：`r.get('time') == TT` 严格匹配字符串
- 若目标时刻（如 08:00）无数据，需先触发 `simulation run --start-time T --duration 15`