feat(workbench): add runtime GIS and sample integrations
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# 外围子系统合成样本
|
||||
|
||||
仅供演示，所有数据标为 `synthetic`，所有对象使用 `DEMO-` 前缀。它们不映射真实资产，不写入 `asset/network/scada`，不生成正式工单，不控制设备。
|
||||
|
||||
## 内容与复现
|
||||
|
||||
纯函数 `samples/peripheral/demo_data.py::build_demo_content` 接收种子和带时区的固定起点，返回结构化数据。相同生成器版本、种子、归一化后的 UTC 起点产生相同记录、UUID 和 JCS SHA-256；不依赖当前时间、进程随机状态或数据库内容。生成器升级必须换版本，不能原地悄改 v1 的行为。
|
||||
|
||||
默认版本 `water-demo@2`，种子 `tjwater-peripheral-demo-20260917`；北京时间 2026-09-17 08:00 至 20:00，15 分钟一条，共 48 个时点。
|
||||
|
||||
| 内容 | 数量及情节 |
|
||||
| --- | --- |
|
||||
| 测点 | 3 个压力点、1 个流量点、1 个液位点 |
|
||||
| 读数 | 240 条；含 4 条缺测 null、4 条真实零值，保留各自质量标记 |
|
||||
| 设备状态 | 9 条变化；通信离线与恢复、泵运行/停止、阀门开/关 |
|
||||
| 告警 | 2 个预置事件，含发生与解除时间；不是从真实数据推断出的故障 |
|
||||
| 运行记录 | 4 条泵阀历史事件；不是可执行命令或真实设备回执 |
|
||||
|
||||
目录 `status=unknown` 不代表设备当前在线。历史状态必须按 `device_states.observed_at` 解读，不能将固定演示时点当成当前现场状态。
|
||||
|
||||
本数据压力单位为 m，不自动转换或送入专业分析。
|
||||
|
||||
## 独立 PG 存储
|
||||
|
||||
用户已授权外围样板使用独立 schema。仅在业务端 `tjwater_v2` 的已有 `peripheral_sample` 中新增一张表，不改其他表。由外部供给流程在事务中执行一次；应用没有建表或生成接口，也没有自动 seed。
|
||||
|
||||
```sql
|
||||
CREATE TABLE peripheral_sample.demo_datasets (
|
||||
project_id uuid NOT NULL,
|
||||
dataset_id text NOT NULL,
|
||||
digest text NOT NULL CHECK (digest ~ '^sha256:[0-9a-f]{64}$'),
|
||||
document jsonb NOT NULL,
|
||||
PRIMARY KEY (project_id,dataset_id),
|
||||
CHECK ((jsonb_typeof(document) = 'object' AND document->>'origin' = 'synthetic'
|
||||
AND document->>'generator_version' = 'water-demo@2') IS TRUE)
|
||||
);
|
||||
```
|
||||
|
||||
登记 `dataset_id=water-demo-v1` 时，先生成并验证 DemoContent、计算规范化摘要。已有同编号记录时只允许核对相同摘要，不覆盖；改变种子或生成器应使用新版本/新编号并另行调整读取配置。样本本身永久保存，读取不会重新生成或写入。
|
||||
|
||||
经明确授权需要为某个开发项目填充外围样板时，可运行：
|
||||
|
||||
```bash
|
||||
conda run -n server python scripts/seed_peripheral_sample.py --project-id <project-uuid>
|
||||
```
|
||||
|
||||
脚本使用固定 UUIDv5 请求号和专用 synthetic actor，重复执行会读取原幂等回执，不重复创建。它核验或补充 `water-demo-v1`，并创建 3 张测试工单和 12 条带 `DEMO-` 前缀的可编辑测试数据；不创建缺少合法 Action 来源的外围核查任务，不写正式工单、资产或监测表。
|
||||
|
||||
## 演示历史窗口配置
|
||||
|
||||
外围面板的“历史监测回放”读取现有项目历史监测源，与上述 `water-demo-v1` 合成数据集是两个独立区域。前端可通过 `TJWATER_PERIPHERAL_SAMPLE_TIME_MODE=demo` 默认使用已知有数据的固定窗口，并用 `TJWATER_PERIPHERAL_SAMPLE_DEMO_START`、`TJWATER_PERIPHERAL_SAMPLE_DEMO_END` 配置开始和结束时间；切到 `recent` 时按 `TJWATER_PERIPHERAL_SAMPLE_RECENT_HOURS` 查询最近时段。界面仍允许在运行时切换演示、最近和自定义窗口。
|
||||
|
||||
本地默认演示窗口为 UTC 2026-04-30 08:00 至 16:00。它只控制历史监测查询，不改变 `water-demo-v1` 自身的 UTC 2026-09-17 00:00 至 12:00 固定内容。
|
||||
|
||||
## 接口与页面
|
||||
|
||||
`GET /api/sample/v1/demo-data` 复用 Next 项目身份和读取权限，按项目查 PG 后核验摘要与模型，返回 project_id、source_id、source_revision、固定时间窗和样本。无记录返回 SOURCE_NOT_CONFIGURED，不回退到浏览器造数据；服务不可用演练仍按既有场景拒绝读取。
|
||||
|
||||
原历史监测接口不变，真实告警源仍然是 `not_configured`；合成告警只出现在单独的合成样本区域，不能宣称真实告警接口已经接通。
|
||||
|
||||
前端在“外围样板”中单独读取合成样本，展示版本、种子和摘要，以及读数、设备状态、告警和运行历史。加载失败不会清空或阻止既有核查任务及历史回放。
|
||||
|
||||
核查任务、反馈仍需用户依据已保存来源显式提交。生成器不会伪造 Next 来源、现场反馈或业务审批。
|
||||
已审核反馈现在可经人工确认[导入独立新证据](field-feedback-import.md)，再另行确认建立[人工复核草稿修订](feedback-review-revisions.md)。专业重分析不在本次已确认的样板反馈范围内；生成器不会自动导入或修订成果。
|
||||
@@ -0,0 +1,15 @@
|
||||
# 外围样板服务
|
||||
|
||||
该独立 FastAPI 服务提供历史监测回放、固定合成数据，以及 synthetic 测试工单和测试数据的版本化 CRUD。管理入口位于供水工作台“外围样板”。它不控制设备，也不修改正式业务资产。
|
||||
|
||||
浏览器通过 `TJWATER_PERIPHERAL_SAMPLE_API_BASE_URL` 连接样板服务。服务复用主系统的 Bearer 身份和 `X-Project-Id`，读取需要 `simulation.view`，写入需要 `simulation.run`。
|
||||
|
||||
主要接口包括：
|
||||
|
||||
- `/api/sample/v1/context` 与 `/scenario`
|
||||
- `/api/sample/v1/work-orders`
|
||||
- `/api/sample/v1/test-data`
|
||||
- `/api/sample/v1/monitoring/points`、`observations`、`alerts`
|
||||
- `/api/sample/v1/demo-data`
|
||||
|
||||
演示数据通过 `scripts/seed_peripheral_sample.py` 写入 `tjwater_v2` 的 `peripheral_sample` schema。当前固定窗口为 2026-09-17，所有记录标记为 `synthetic`，并使用 `DEMO-` 前缀。
|
||||
@@ -0,0 +1,20 @@
|
||||
# 工作台工单与告警存储契约
|
||||
|
||||
工作台只聚合预约工单与任务主动推送的告警。浏览器不推导告警，也不写正式工单。
|
||||
|
||||
## 任务告警
|
||||
|
||||
DDL 位于 `resources/sql/008_workbench_alert_events.sql`。任务通过 `POST /api/v1/workbench/task-alert-events` 推送 `raised`、`acknowledged` 或 `resolved` 事件。来源包含 `task_type`、`task_id` 和 `run_id`，生产者由认证项目身份绑定。`event_id` 在项目和生产者范围内幂等，告警事实在首次 raised 后不可改写。
|
||||
|
||||
## 预约工单
|
||||
|
||||
`workbench.work_orders` 的 DDL 位于 `resources/sql/011_workbench_work_orders.sql`。每行保存一个只读工单投影，文档必须满足 `WorkbenchRuntimeWorkOrder`：
|
||||
|
||||
- 一张主工单包含一个或多个 `subtasks`。
|
||||
- 每个子任务保存自己的位置、班组、时间窗和复令要求。
|
||||
- 每个子任务包含一个或多个有序 `stages`，`sequence` 从 1 连续递增，阶段编号在子任务内唯一，最多只有一个 `current` 阶段。
|
||||
- 阶段名称不写死为固定枚举。演示数据使用派发、执行、复令，正式工单适配器可以按业务定义其他阶段。
|
||||
|
||||
演示数据可以先运行 `scripts/seed_peripheral_sample.py`，再运行 `scripts/seed_workbench_work_orders.py` 投影。工作台会显示一张主工单，三项外围核查分别作为子任务展示。
|
||||
|
||||
工作台运行账号对工单表只需 `SELECT`，同步账号使用独立受控写权限；对告警事件表需要 `SELECT, INSERT`，对告警状态表需要 `SELECT, INSERT, UPDATE`。
|
||||
@@ -0,0 +1,10 @@
|
||||
# 工作台运行态
|
||||
|
||||
`GET /api/v1/workbench/runtime` 按当前项目读取 BizDB 中的分析成果、预约工单和任务告警。工况任务继续由前端演示数据提供，不从后端运行记录或分析结果生成。
|
||||
|
||||
- `analysis.runs/results` 只用于分析成果、历史成果和兼容场景字段。
|
||||
- `workbench.work_orders` 是预约工单的后端持久化投影。主工单包含多个子任务，每个子任务包含自己的有序阶段。表存在时，空列表同样是权威结果，不回退到 mock 工单。
|
||||
- `workbench.alert_events` 保存任务显式推送的事件，`workbench.alerts` 保存当前状态。分析结果、测点值和缺测状态不会自动变成告警。
|
||||
- 每个可选分区独立读取并返回 `ready`、`not_configured` 或 `degraded`，一个分区失败不会污染其他分区。
|
||||
|
||||
演示工单由 `scripts/seed_peripheral_sample.py` 写入 `peripheral_sample`，再由 `scripts/seed_workbench_work_orders.py` 将三项外围核查组合成一张主工单和三个子任务，写入 `workbench.work_orders`。当前固定演示日期为 2026-09-17。
|
||||
Reference in New Issue
Block a user