优化 CLI 命令,增加获取所有节点和管道属性的功能

This commit is contained in:
2026-06-03 17:31:49 +08:00
parent 233960d8db
commit b7872f29a9
12 changed files with 823 additions and 433 deletions
+6 -85
View File
@@ -7,7 +7,6 @@
首批 CLI 采用 **少量顶层入口 + 业务域二级分组 + 只读/分析优先** 的设计。
```text
tjwater-cli project
tjwater-cli network
tjwater-cli component
tjwater-cli simulation
@@ -39,7 +38,6 @@ tjwater-cli help
| 顶层命令 | 二级范围 | 说明 |
|---|---|---|
| `project` | `list``info``db-health``export-inp``data` | 项目发现和只读项目数据 |
| `network` | `get-node-properties``get-link-properties` | 管网节点/管线属性查询,只读 |
| `component` | `option` | EPANET 选项设置,只读 |
| `simulation` | `run` | 模拟运行 |
@@ -92,85 +90,6 @@ tjwater-cli help
## 首批 CLI 范围
### Project
来源:
```text
app/api/v1/endpoints/auth.py
app/api/v1/endpoints/meta.py
app/api/v1/endpoints/project.py
app/api/v1/endpoints/project_data.py
TJWaterFrontend_Refine/src/lib/requestHeaders.ts
TJWaterFrontend_Refine/src/lib/api.ts
TJWaterFrontend_Refine/src/lib/apiFetch.ts
```
认证模式:
- **Non-interactive / Agent**
- 面向 agent、脚本、多用户多 agent 并发调用。
- 必须显式传入认证上下文。
- 不得隐式回退到本机默认状态。
Agent 调用认证上下文:
- 当前前端调用链会自动附加以下请求头:
- `Authorization: Bearer <access_token>`
- `X-Project-Id: <projectId>`
- `X-User-Id: <userId>`
- 其中 `Authorization` 来自访问令牌,`X-Project-Id` 来自当前项目上下文,`X-User-Id` 来自当前登录用户。
- 因此前端触发的 agent 调用,应默认支持直接消费这三个字段;不再设计额外的本地 `login` 流程。
- CLI 侧建议提供两类显式注入方式:
- `--auth-context PATH`
- 环境变量 / 调用方 header 映射
认证解析优先级建议固定为:
1. 命令行显式参数(如 `--auth-context`
2. 调用方显式注入的环境变量 / header 映射
约束:
- Agent 模式下,若未显式提供认证上下文,应返回明确错误,而不是尝试复用默认登录态。
- `X-Project-Id` 是当前 project scope 的默认来源;CLI 命令默认直接使用该上下文,不要求重复传参。
- `X-User-Id` 主要用于审计、结果归属和多用户隔离,不应用来替代 access token 做认证。
| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater-cli project list` | `GET /meta/projects` | 项目列表 |
| `tjwater-cli project info` | `GET /meta/project` | 当前 project 信息 |
| `tjwater-cli project db-health` | `GET /meta/db/health` | 当前 project 数据库健康 |
| `tjwater-cli project export-inp --output PATH` | `GET /exportinp/``GET /dumpinp/``GET /downloadinp/` | 导出当前 project 的 INP 到本地文件 |
| `tjwater-cli project data --kind scada-info\|scheme-list\|burst-locate-result` | `GET /scada-info``GET /scheme-list``GET /burst-locate-result*` | 当前 project 的业务数据 |
暂不暴露:
```text
POST /auth/register
POST /auth/login
POST /auth/login/simple
GET /auth/me
POST /auth/refresh
GET /listprojects/
GET /project_info/
GET /haveproject/
GET /isprojectopen/
GET /isprojectlocked/
GET /isprojectlockedbyme/
POST /createproject/
POST /deleteproject/
POST /openproject/
POST /closeproject/
POST /copyproject/
POST /importinp/
POST /readinp/
POST /lockproject/
POST /unlockproject/
POST /uploadinp/
GET /convertv3tov2/
```
### Network
来源:
@@ -183,6 +102,8 @@ app/api/v1/endpoints/network/*.py
|---|---|---|
| `tjwater-cli network get-node-properties --node NODE` | `GET /getnodeproperties/` | 读取当前 project 中指定节点的属性 |
| `tjwater-cli network get-link-properties --link LINK` | `GET /getlinkproperties/` | 读取当前 project 中指定管线的属性 |
| `tjwater-cli network get-all-junction-properties` | `GET /getalljunctionproperties/` | 读取当前 project 中所有节点属性 |
| `tjwater-cli network get-all-pipe-properties` | `GET /getallpipeproperties/` | 读取当前 project 中所有管道属性 |
暂不暴露:
@@ -275,10 +196,10 @@ app/api/v1/endpoints/risk.py
|---|---|---|
| `tjwater-cli simulation run --start-time RFC3339 --duration MINUTES` | `POST /runsimulationmanuallybydate/` | 按指定绝对开始时间触发当前 project 的实时模拟;`start-time` 必须显式带时区,结果写入服务端时序库,后续通过 `tjwater-cli data timeseries realtime *` 查询 |
| `tjwater-cli analysis burst --start-time TIME --duration SEC --scheme SCHEME --burst-file FILE` | `GET /burst_analysis/` | 爆管分析;`FILE` 提供爆管点与流量列表,CLI 负责转换为 `burst_ID[]` / `burst_size[]` |
| `tjwater-cli analysis valve --mode close\|isolation --start-time TIME --valve VALVE` | `GET /valve_close_analysis/``GET /valve_isolation_analysis/` | 阀门分析,`--valve` 可重复 |
| `tjwater-cli analysis flushing --start-time TIME --valve-setting-file FILE --drainage-node NODE --flow FLOW [--duration SEC] [--scheme SCHEME]` | `GET /flushing_analysis/` | 冲洗分析;`FILE` 提供阀门与开度列表,CLI 负责转换为 `valves[]` / `valves_k[]` |
| `tjwater-cli analysis valve --mode close\|isolation --start-time TIME --valve VALVE [--scheme SCHEME]` | `GET /valve_close_analysis/``GET /valve_isolation_analysis/` | 阀门分析close 模式需要 `--scheme``--valve` 可重复 |
| `tjwater-cli analysis flushing --start-time TIME --valve-setting-file FILE --drainage-node NODE --flow FLOW --scheme SCHEME [--duration SEC]` | `GET /flushing_analysis/` | 冲洗分析;`FILE` 提供阀门与开度列表,CLI 负责转换为 `valves[]` / `valves_k[]` |
| `tjwater-cli analysis age --start-time TIME --duration SEC` | `GET /age_analysis/` | 水龄分析 |
| `tjwater-cli analysis contaminant --start-time TIME --duration SEC --source-node NODE --concentration VALUE [--pattern PATTERN] [--scheme SCHEME]` | `GET /contaminant_simulation/` | 污染物模拟 |
| `tjwater-cli analysis contaminant --start-time TIME --duration SEC --source-node NODE --concentration VALUE --scheme SCHEME [--pattern PATTERN]` | `GET /contaminant_simulation/` | 污染物模拟 |
| `tjwater-cli analysis sensor-placement kmeans --count N` | `GET /pressuresensorplacementkmeans/` | 基于 kmeans 的传感器放置分析;不包含创建方案 |
| `tjwater-cli analysis leakage identify --scheme SCHEME --start-time TIME --end-time TIME` | `POST /leakage/identify/` | 漏损识别 |
| `tjwater-cli analysis leakage schemes list\|get` | `GET /leakage/schemes/``GET /leakage/schemes/{scheme_name}` | 漏损方案查询 |
@@ -440,7 +361,7 @@ POST /users/{user_id}/deactivate
输出补充约束:
- 首批 CLI 不再设计通用 `result_ref` / `--out-ref` 机制。
- 若某业务命令确实需要落本地文件,应由所属命令显式提供 `--output PATH`,例如 `project export-inp --output PATH`
- 若某业务命令确实需要落本地文件,应由所属命令显式提供 `--output PATH`
- 若后续出现超大结果集、必须脱离 stdout 传输时,再单独设计结果引用机制,而不是在首批 CLI 中预埋未闭环能力。
## 输出规范