feat(timeseries): unify element history queries
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# TJWater 数据库改造说明与当前结构
|
||||
|
||||
> 本文记录截至 2026-09-10 的数据库实际状态。结构、约束、行数、TimescaleDB chunk 和策略均直接读取数据库，不以仓库中的 SQL 脚本为依据。文中不包含主机、端口、账号、密码或 DSN。
|
||||
> 本文记录截至 2026-09-14 的数据库实际状态。结构、约束、行数、TimescaleDB chunk 和策略均直接读取数据库，不以仓库中的 SQL 脚本为依据。文中不包含主机、端口、账号、密码或 DSN。
|
||||
|
||||
## 改造范围与当前状态
|
||||
|
||||
@@ -20,10 +20,11 @@
|
||||
- `system_hub.public` 补充了项目数据库外键、数据库路由约束、连接池约束、必要的非空约束，以及 5 张表和 44 个字段的中文数据库注释。
|
||||
- 用户角色和项目角色仍是可扩展字符串，没有增加枚举检查约束。
|
||||
- `audit_logs.user_id` 和 `audit_logs.project_id` 仍为逻辑关联，没有增加外键。
|
||||
- 业务库 48 个表或物化视图、192 个字段，以及时序库 7 张表、47 个字段均已写入中文数据库注释。
|
||||
- 业务库 48 个表或物化视图、194 个字段，以及时序库 7 张表、47 个字段均已写入中文数据库注释。
|
||||
- 后端已对接新 schema。WNDB、PostgreSQL 管理连接和同步 TimescaleDB 访问均使用有界连接池，闲置项目按最近使用顺序回收；动态异步池采用代际切换，配置更新不会中断旧借用或阻塞新请求。
|
||||
- 后端批量元素查询读取 GIS 物化视图，模型增删改和 INP 导入提交后执行并发刷新；批量事务只刷新一次。
|
||||
- `pattern_values`、`pattern_flow_samples`、`curve_points`、`demands` 和 `link_vertices` 的顺序号按所属父对象编号，主键已改为父对象 ID 与 `sequence_no` 的复合键。
|
||||
- 5 个活跃业务库、5 个对应管网模板库和 `tjwater_v2_schema_template` 均已增加 `asset.scada_devices.measurement_unit`；压力设备回填为 `m`，流量设备回填为 `m3/h`，`gis.scada_devices` 物化视图同步暴露该字段。
|
||||
|
||||
逻辑项目 `tjwater_v2` 当前为 `active`。
|
||||
|
||||
@@ -359,15 +360,27 @@ TimescaleDB 的空结构模板为 `tjwater_v2_timescale_template`，普通连接
|
||||
|
||||
方案查询统一读取 `/api/v1/analysis/runs`，详情和时序结果按 UUID `run_id` 关联。时间轴读取 `/api/v1/timeseries/analysis/runs/{run_id}/values`，爆管定位的模拟数据源也传递 `simulation_run_id`。监测点优化使用 `/api/v1/sensor-placement-runs`。前端不再调用旧的 `/schemes`、`/timeseries/schemes` 和 `/sensor-placement-schemes` 接口。
|
||||
|
||||
管网元素历史查询统一使用 `POST /api/v1/timeseries/views/element-history/query`。单次请求批量返回元素关联的原始/清洗 SCADA、实时模拟或指定分析运行时序，并显式返回 `source_unit`、`display_unit` 和 `unit_inferred`。点值仍使用 `source_unit`，前端由共享单位模块统一换算为流量 `m³/h`、压力 `m` 和流速 `m/s`。旧的 `element-simulations`、`element-scada-readings` 和 `scada-simulations` 组合接口已移除。
|
||||
|
||||
当前业务库 `network.simulation_settings` 中的模型结果源单位如下。`LPS` 表示 L/s，`MLD` 表示百万升/日；公制模型的流速源单位为 m/s。前端不得再假定所有项目都是 `LPS`，而应读取项目设置并通过共享单位模块换算。
|
||||
|
||||
| 业务库 | 流量源单位 | 压力源单位 | 前端显示单位 |
|
||||
| --- | --- | --- | --- |
|
||||
| `fengyang_v2` | `LPS` | `METERS` | m³/h、m、m/s |
|
||||
| `md_v2` | `LPS` | `METERS` | m³/h、m、m/s |
|
||||
| `szh_v2` | `MLD` | `METERS` | m³/h、m、m/s |
|
||||
| `tjwater_v2` | `LPS` | `METERS` | m³/h、m、m/s |
|
||||
| `zjb` | `LPS` | `METERS` | m³/h、m、m/s |
|
||||
|
||||
模型修改提交后，后端先调用 `gis.refresh_all_materialized_views(boolean)` 刷新数据库查询层。GeoWebCache 不会感知 PostgreSQL 物化视图刷新，因此 7 个新图层配置了 300 秒的服务端和客户端缓存有效期，前端最迟在 5 分钟后读到新瓦片。部署或批量迁移完成后仍可执行一次图层缓存清空，避免等待已有瓦片自然过期。
|
||||
|
||||
### asset：SCADA 设备配置
|
||||
|
||||
`asset.scada_devices` 保存设备类型、采集接口标识、传输模式、频率、可靠性和可选几何。每台设备必须关联一个节点或一条连接，不能同时关联两者。设备的历史测量值不放在业务库，保存在时序库 `scada.measurements`。
|
||||
`asset.scada_devices` 保存设备类型、采集接口标识、传输模式、频率、可靠性、测量源单位 `measurement_unit` 和可选几何。单位字段非空且不允许空字符串。每台设备必须关联一个节点或一条连接，不能同时关联两者。设备的历史测量值不放在业务库，保存在时序库 `scada.measurements`。
|
||||
|
||||
### analysis：分析运行和非时序结果
|
||||
|
||||
`analysis.runs` 表示一次实际执行，保存运行名称、类型、创建人、开始时间、状态和参数。当前没有单独的 `scenarios` 模板表。
|
||||
`analysis.runs` 表示一次实际执行，保存运行名称、类型、创建人、开始时间、状态和参数。新执行会在 `parameters.result_units` 中保存 EPANET 输出的流量和压力源单位，避免日后调整模型设置时误读历史值。旧运行没有该元数据时，API 使用当前模型单位并返回 `unit_inferred=true`。当前没有单独的 `scenarios` 模板表。
|
||||
|
||||
每次执行都会创建新的 `run_id`，名称和业务时间相同也不会覆盖旧结果。扩展仿真开始写结果前，业务库先记录 `running`；时序库写入完成后更新为 `completed`，写入失败则保留为 `failed`。业务库和时序库据此共用同一个执行标识。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user