OrgTJWater/TJWaterServerBinary
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

拆分代码；约束cli命令

Browse Source
This commit is contained in:
Jiang
2026-06-02 14:54:08 +08:00
parent 9b8a517092
commit 40e699e173
17 changed files with 395 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli/tjwater_cli_endpoint_scope.md
+63 -63
View File
@@ -7,13 +7,13 @@
首批 CLI 采用 **少量顶层入口 + 业务域二级分组 + 只读/分析优先** 的设计。
```text
tjwater project
tjwater network
tjwater component
tjwater simulation
tjwater analysis
tjwater data
tjwater help
tjwater-cli project
tjwater-cli network
tjwater-cli component
tjwater-cli simulation
tjwater-cli analysis
tjwater-cli data
tjwater-cli help
```
首批默认不暴露：
@@ -45,12 +45,12 @@ tjwater help
| `simulation` | `run` | 模拟运行 |
| `analysis` | `burst`、`valve`、`flushing`、`age`、`contaminant`、`sensor-placement`、`leakage`、`burst-detection`、`burst-location`、`risk` | 任务级分析 |
| `data` | `timeseries`、`scada`、`scheme`、`extension`、`misc` | 数据查询 |
| `help` | `--json`、`COMMAND --json` | Agent 能力发现和命令说明 |
| `help` | `COMMAND` | Agent 能力发现和命令说明 |
命令深度建议：
- 常规命令不超过 3 层：`tjwater component option get`
- 时序数据允许 4 层：`tjwater data timeseries realtime links`
- 常规命令不超过 3 层：`tjwater-cli component option get`
- 时序数据允许 4 层：`tjwater-cli data timeseries realtime links`
- `risk` 归入 `analysis risk`
- `scada`、`scheme`、`extension` 归入 `data`
@@ -88,7 +88,7 @@ tjwater help
- 用户输入的业务时间默认按 **UTC+8** 理解；若命令直接接收完整时间戳，应使用 ISO 8601 / RFC 3339 并显式包含时区。CLI 可直接传 `+08:00`，也可传其他时区的绝对时间，由服务端统一归一化。
- 范围参数优先拆成 `--start-time` / `--end-time`，不再引入模糊的 `--time-range ...` 写法。
- 复合输入优先使用可重复显式选项或 `--input FILE`，避免把多个语义字段压进 `ID:SIZE`、`NODE:VALUE`、`VALVE:OPENING` 这类 shell 内联 DSL。
- 若必须传大批量复合参数，优先支持 `--input FILE`，文件格式由 `help --json` 给出 schema。
- 若必须传大批量复合参数，优先支持 `--input FILE`，文件格式由 `help` 给出 schema。
## 首批 CLI 范围
@@ -138,11 +138,11 @@ Agent 调用认证上下文：
| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater project list` | `GET /meta/projects` | 项目列表 |
| `tjwater project info` | `GET /meta/project` | 当前 project 信息 |
| `tjwater project db-health` | `GET /meta/db/health` | 当前 project 数据库健康 |
| `tjwater project export-inp --output PATH` | `GET /exportinp/`、`GET /dumpinp/`、`GET /downloadinp/` | 导出当前 project 的 INP 到本地文件 |
| `tjwater project data --kind scada-info\|scheme-list\|burst-locate-result` | `GET /scada-info`、`GET /scheme-list`、`GET /burst-locate-result*` | 当前 project 的业务数据 |
| `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 的业务数据 |
暂不暴露：
@@ -181,8 +181,8 @@ app/api/v1/endpoints/network/*.py
| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater network get-node-properties --node NODE` | `GET /getnodeproperties/` | 读取当前 project 中指定节点的属性 |
| `tjwater network get-link-properties --link LINK` | `GET /getlinkproperties/` | 读取当前 project 中指定管线的属性 |
| `tjwater-cli network get-node-properties --node NODE` | `GET /getnodeproperties/` | 读取当前 project 中指定节点的属性 |
| `tjwater-cli network get-link-properties --link LINK` | `GET /getlinkproperties/` | 读取当前 project 中指定管线的属性 |
暂不暴露：
@@ -209,14 +209,14 @@ app/api/v1/endpoints/components/*.py
| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater component option schema --kind time` | `GET /gettimeschema` | 时间选项 schema |
| `tjwater component option get --kind time` | `GET /gettimeproperties/` | 时间选项属性 |
| `tjwater component option schema --kind energy` | `GET /getenergyschema/` | 全局能耗选项 schema |
| `tjwater component option get --kind energy` | `GET /getenergyproperties/` | 全局能耗选项属性 |
| `tjwater component option schema --kind pump-energy` | `GET /getpumpenergyschema/` | 泵能耗选项 schema |
| `tjwater component option get --kind pump-energy --pump PUMP` | `GET /getpumpenergyproperties//` | 指定泵的能耗选项属性 |
| `tjwater component option schema --kind network` | `GET /getoptionschema/` | 管网选项 schema |
| `tjwater component option get --kind network` | `GET /getoptionproperties/` | 管网选项属性 |
| `tjwater-cli component option schema --kind time` | `GET /gettimeschema` | 时间选项 schema |
| `tjwater-cli component option get --kind time` | `GET /gettimeproperties/` | 时间选项属性 |
| `tjwater-cli component option schema --kind energy` | `GET /getenergyschema/` | 全局能耗选项 schema |
| `tjwater-cli component option get --kind energy` | `GET /getenergyproperties/` | 全局能耗选项属性 |
| `tjwater-cli component option schema --kind pump-energy` | `GET /getpumpenergyschema/` | 泵能耗选项 schema |
| `tjwater-cli component option get --kind pump-energy --pump PUMP` | `GET /getpumpenergyproperties//` | 指定泵的能耗选项属性 |
| `tjwater-cli component option schema --kind network` | `GET /getoptionschema/` | 管网选项 schema |
| `tjwater-cli component option get --kind network` | `GET /getoptionproperties/` | 管网选项属性 |
暂不暴露：
@@ -273,22 +273,22 @@ app/api/v1/endpoints/risk.py
| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater simulation run --start-time RFC3339 --duration MINUTES` | `POST /runsimulationmanuallybydate/` | 按指定绝对开始时间触发当前 project 的实时模拟；`start-time` 必须显式带时区，结果写入服务端时序库，后续通过 `tjwater data timeseries realtime *` 查询 |
| `tjwater analysis burst --start-time TIME --duration SEC --scheme SCHEME --burst-file FILE` | `GET /burst_analysis/` | 爆管分析；`FILE` 提供爆管点与流量列表，CLI 负责转换为 `burst_ID[]` / `burst_size[]` |
| `tjwater analysis valve --mode close\|isolation --start-time TIME --valve VALVE` | `GET /valve_close_analysis/`、`GET /valve_isolation_analysis/` | 阀门分析，`--valve` 可重复 |
| `tjwater 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 analysis age --start-time TIME --duration SEC` | `GET /age_analysis/` | 水龄分析 |
| `tjwater analysis contaminant --start-time TIME --duration SEC --source-node NODE --concentration VALUE [--pattern PATTERN] [--scheme SCHEME]` | `GET /contaminant_simulation/` | 污染物模拟 |
| `tjwater analysis sensor-placement kmeans --count N` | `GET /pressuresensorplacementkmeans/` | 基于 kmeans 的传感器放置分析；不包含创建方案 |
| `tjwater analysis leakage identify --scheme SCHEME --start-time TIME --end-time TIME` | `POST /leakage/identify/` | 漏损识别 |
| `tjwater analysis leakage schemes list\|get` | `GET /leakage/schemes/`、`GET /leakage/schemes/{scheme_name}` | 漏损方案查询 |
| `tjwater analysis burst-detection detect --scheme SCHEME --start-time TIME --end-time TIME` | `POST /burst-detection/detect/` | 爆管检测 |
| `tjwater analysis burst-detection schemes list\|get` | `GET /burst-detection/schemes/`、`GET /burst-detection/schemes/{scheme_name}` | 爆管检测方案查询 |
| `tjwater analysis burst-location locate --scheme SCHEME --start-time TIME --end-time TIME` | `POST /burst-location/locate/` | 爆管定位 |
| `tjwater analysis burst-location schemes list\|get` | `GET /burst-location/schemes/`、`GET /burst-location/schemes/{scheme_name}` | 爆管定位方案查询 |
| `tjwater analysis risk pipe-now --pipe PIPE` | `GET /getpiperiskprobabilitynow/` | 单条管道当前风险 |
| `tjwater analysis risk pipe-history --pipe PIPE` | `GET /getpiperiskprobability/` | 单条管道历史风险 |
| `tjwater analysis risk network` | `GET /getnetworkpiperiskprobabilitynow/`、`GET /getpiperiskprobabilitygeometries/` | 当前 project 全网风险 |
| `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 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 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}` | 漏损方案查询 |
| `tjwater-cli analysis burst-detection detect --scheme SCHEME --start-time TIME --end-time TIME` | `POST /burst-detection/detect/` | 爆管检测 |
| `tjwater-cli analysis burst-detection schemes list\|get` | `GET /burst-detection/schemes/`、`GET /burst-detection/schemes/{scheme_name}` | 爆管检测方案查询 |
| `tjwater-cli analysis burst-location locate --scheme SCHEME --start-time TIME --end-time TIME` | `POST /burst-location/locate/` | 爆管定位 |
| `tjwater-cli analysis burst-location schemes list\|get` | `GET /burst-location/schemes/`、`GET /burst-location/schemes/{scheme_name}` | 爆管定位方案查询 |
| `tjwater-cli analysis risk pipe-now --pipe PIPE` | `GET /getpiperiskprobabilitynow/` | 单条管道当前风险 |
| `tjwater-cli analysis risk pipe-history --pipe PIPE` | `GET /getpiperiskprobability/` | 单条管道历史风险 |
| `tjwater-cli analysis risk network` | `GET /getnetworkpiperiskprobabilitynow/`、`GET /getpiperiskprobabilitygeometries/` | 当前 project 全网风险 |
暂缓或暂不暴露：
@@ -310,7 +310,7 @@ POST /daily_scheduling_analysis/
- `simulation run` 不直接回传全量模拟结果；它负责触发服务端模拟，并返回执行摘要、时间窗口和后续查询提示。
- 当前 `runsimulationmanuallybydate` 接口会从 `start_time` 指定的绝对时间开始，按 15 分钟步长运行直到达到 `duration`，结果持久化到服务端时序存储。
- `start_time` 必须显式带时区；CLI 推荐直接传 **UTC+8** 时间，服务端统一转换后执行和落库。CLI 文档与帮助信息需要把这条规则写成显式契约，不能把数据库存储时间直接暴露成用户输入语义。
- 模拟结果读取统一走 `tjwater data timeseries realtime *`，而不是再单独设计 `simulation output`。
- 模拟结果读取统一走 `tjwater-cli data timeseries realtime *`，而不是再单独设计 `simulation output`。
- `analysis` 相关命令首批也按同步请求处理；若后续服务端真的引入任务队列，再单独设计 `job` 类基础设施能力。
### Data
@@ -328,22 +328,22 @@ app/api/v1/endpoints/project_data.py
| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater data timeseries realtime links --start-time TIME --end-time TIME` | `GET /realtime/links` | 查询指定时间范围内的实时/模拟管道数据 |
| `tjwater data timeseries realtime nodes --start-time TIME --end-time TIME` | `GET /realtime/nodes` | 查询指定时间范围内的实时/模拟节点数据 |
| `tjwater data timeseries realtime simulation-by-id-time --id ID --type pipe\|junction --time TIME` | `GET /realtime/query/by-id-time` | 查询指定元素在指定时间点的模拟结果 |
| `tjwater data timeseries realtime simulation-by-time-property --type pipe\|junction --time TIME --property PROPERTY` | `GET /realtime/query/by-time-property` | 查询指定时间点某类元素某属性的聚合模拟结果 |
| `tjwater data timeseries scheme links --scheme SCHEME --start-time TIME --end-time TIME` | `GET /scheme/links`、`GET /scheme/links/{link_id}/field` | 方案管道数据 |
| `tjwater data timeseries scheme node-field --node NODE --field FIELD` | `GET /scheme/nodes/{node_id}/field` | 方案节点字段 |
| `tjwater data timeseries scheme simulation --query by-id-time\|by-scheme-time-property --scheme SCHEME --id ID --time TIME --property PROPERTY` | `GET /scheme/query/*` | 方案模拟查询 |
| `tjwater data timeseries scada query --device-id ID --start-time TIME --end-time TIME [--device-id ID ...] [--field FIELD]` | `GET /scada/by-ids-time-range`、`GET /scada/by-ids-field-time-range` | SCADA 时序；CLI 把重复 `--device-id` 转换为后端逗号分隔参数 |
| `tjwater data timeseries composite --kind scada-simulation\|element-simulation\|element-scada --feature FEATURE --start-time TIME --end-time TIME` | `GET /composite/*` | 复合查询，`--feature` 可重复 |
| `tjwater data timeseries composite pipeline-health --pipe PIPE --start-time TIME --end-time TIME` | `GET /composite/pipeline-health-prediction` | 管道健康预测 |
| `tjwater data scada schema --kind device\|device-data\|element\|info` | `GET /getscada*schema/` | `SCADA` 元数据 `schema` |
| `tjwater data scada get\|list --kind device\|device-data\|element\|info` | `scada.py` 下 `GET` 查询接口 | `SCADA` 元数据 |
| `tjwater data scheme schema\|get\|list` | `schemes.py` 下 `GET` 接口 | 当前 project 方案查询 |
| `tjwater data extension keys\|get\|list` | `extension.py` 下 `GET` 查询接口 | 当前 project 扩展数据查询 |
| `tjwater data misc sensor-placements` | `GET /getallsensorplacements/` | 当前 project 传感器位置 |
| `tjwater data misc burst-location-results` | `GET /getallburstlocateresults/` | 当前 project 爆管定位结果 |
| `tjwater-cli data timeseries realtime links --start-time TIME --end-time TIME` | `GET /realtime/links` | 查询指定时间范围内的实时/模拟管道数据 |
| `tjwater-cli data timeseries realtime nodes --start-time TIME --end-time TIME` | `GET /realtime/nodes` | 查询指定时间范围内的实时/模拟节点数据 |
| `tjwater-cli data timeseries realtime simulation-by-id-time --id ID --type pipe\|junction --time TIME` | `GET /realtime/query/by-id-time` | 查询指定元素在指定时间点的模拟结果 |
| `tjwater-cli data timeseries realtime simulation-by-time-property --type pipe\|junction --time TIME --property PROPERTY` | `GET /realtime/query/by-time-property` | 查询指定时间点某类元素某属性的聚合模拟结果 |
| `tjwater-cli data timeseries scheme links --scheme SCHEME --start-time TIME --end-time TIME` | `GET /scheme/links`、`GET /scheme/links/{link_id}/field` | 方案管道数据 |
| `tjwater-cli data timeseries scheme node-field --node NODE --field FIELD` | `GET /scheme/nodes/{node_id}/field` | 方案节点字段 |
| `tjwater-cli data timeseries scheme simulation --query by-id-time\|by-scheme-time-property --scheme SCHEME --id ID --time TIME --property PROPERTY` | `GET /scheme/query/*` | 方案模拟查询 |
| `tjwater-cli data timeseries scada query --device-id ID --start-time TIME --end-time TIME [--device-id ID ...] [--field FIELD]` | `GET /scada/by-ids-time-range`、`GET /scada/by-ids-field-time-range` | SCADA 时序；CLI 把重复 `--device-id` 转换为后端逗号分隔参数 |
| `tjwater-cli data timeseries composite --kind scada-simulation\|element-simulation\|element-scada --feature FEATURE --start-time TIME --end-time TIME` | `GET /composite/*` | 复合查询，`--feature` 可重复 |
| `tjwater-cli data timeseries composite pipeline-health --pipe PIPE --start-time TIME --end-time TIME` | `GET /composite/pipeline-health-prediction` | 管道健康预测 |
| `tjwater-cli data scada schema --kind device\|device-data\|element\|info` | `GET /getscada*schema/` | `SCADA` 元数据 `schema` |
| `tjwater-cli data scada get\|list --kind device\|device-data\|element\|info` | `scada.py` 下 `GET` 查询接口 | `SCADA` 元数据 |
| `tjwater-cli data scheme schema\|get\|list` | `schemes.py` 下 `GET` 接口 | 当前 project 方案查询 |
| `tjwater-cli data extension keys\|get\|list` | `extension.py` 下 `GET` 查询接口 | 当前 project 扩展数据查询 |
| `tjwater-cli data misc sensor-placements` | `GET /getallsensorplacements/` | 当前 project 传感器位置 |
| `tjwater-cli data misc burst-location-results` | `GET /getallburstlocateresults/` | 当前 project 爆管定位结果 |
- `realtime` 是首批 simulation 结果的主读取域；CLI 可以按任务语义组合 `links`、`nodes`、`simulation-by-id-time`、`simulation-by-time-property`，但底层数据源仍以 `realtime.py` 为准。
- `realtime`、`scheme`、`composite` 等时间查询命令面向用户时仍按 **UTC+8** 输入；CLI/服务端负责转换为后端使用的 **UTC0** 条件进行检索。若返回结果直接包含时间戳，必须显式带时区，避免把存储时间和展示时间混淆。
@@ -434,8 +434,8 @@ POST /users/{user_id}/deactivate
| 命令 | 说明 |
|---|---|
| `tjwater help --json` | 返回当前 CLI 能力清单，供 Agent 发现可用命令 |
| `tjwater help COMMAND --json` | 返回某个命令的参数、输出、示例和推荐后续命令 |
| `tjwater-cli help` | 返回当前 CLI 能力清单，供 Agent 发现可用命令 |
| `tjwater-cli help COMMAND` | 返回某个命令的参数、输出、示例和推荐后续命令 |
输出补充约束：
@@ -491,7 +491,7 @@ POST /users/{user_id}/deactivate
"data": null,
"metadata": {},
"next_commands": [
"tjwater <command> --auth-context /path/to/auth-context.json"
"tjwater-cli <command> --auth-context /path/to/auth-context.json"
]
}
```
@@ -500,7 +500,7 @@ POST /users/{user_id}/deactivate
- `metadata` 至少建议包含：`request_id`、`server`、`duration_ms`、`generated_at`。
- `next_commands` 是面向 agent 的推荐后续动作，不影响退出码和主结果语义。
- 所有 `help --json` 输出也应带 `schema_version`，便于 agent 做能力协商。
- 所有 `help` 输出也应带 `schema_version`，便于 agent 做能力协商。
## 后续开放条件