jiang
b853b61a0b
Accumulate investigation paths and preserve failed attempts across rounds. Keep graph annotations separate from execution state, synchronize the API contract, and consolidate documentation.
66 lines
5.3 KiB
Markdown
66 lines
5.3 KiB
Markdown
# 外围子系统合成样本
|
||
|
||
仅供演示，所有数据标为 `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`，并创建 12 条带 `DEMO-` 前缀的可编辑测试数据；不再创建早期用于检查通信、压力和零流量展示的三张测试工单，也不创建缺少合法 Action 来源的外围核查任务，不写正式工单、资产或监测表。
|
||
|
||
通过工单接口新建的预约工单不再包含子任务和固定阶段。创建请求可直接填写 `feedback_requirements`；修改请求可填写 `progress_note`，它只追加一条有时间、操作者和正文的活动记录，不作为工单顶层字段保存。旧工单读取时去掉 `subtasks`，历史修订仍保留原样。
|
||
|
||
## 演示历史窗口配置
|
||
|
||
外围面板的“历史监测回放”读取现有项目历史监测源，与上述 `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-09-17 00:00 至 12:00，可由运行时配置覆盖，见 [前端配置定义](../../next-tjwater-frontend/src/shared/config/env.ts)。它只控制历史监测查询，不改变 `water-demo-v1` 自身的固定内容；部署环境的实际配置与数据覆盖需现场核对。
|
||
|
||
## 接口与页面
|
||
|
||
`GET /api/sample/v1/demo-data` 复用 Next 项目身份和读取权限，按项目查 PG 后核验摘要与模型，返回 project_id、source_id、source_revision、固定时间窗和样本。无记录返回 SOURCE_NOT_CONFIGURED，不回退到浏览器造数据；服务不可用演练仍按既有场景拒绝读取。
|
||
|
||
原历史监测接口不变，真实告警源仍然是 `not_configured`；合成告警只出现在单独的合成样本区域，不能宣称真实告警接口已经接通。
|
||
|
||
前端在“外围样板”中单独读取合成样本，展示版本、种子和摘要，以及读数、设备状态、告警和运行历史。加载失败不会清空或阻止既有核查任务及历史回放。
|
||
|
||
外围业务工单及现场反馈使用 `system_data` 来源，合成生成器不伪造业务上报、人工证据或审批。旧的“反馈导入后建立人工复核草稿”不再作为当前流程；人工事实、外部反馈与调查新轮次的边界见 [工况任务](operational-tasks.md#调查轮次与协作边界)，工单来源与事件同步见 [外围服务](peripheral-sample.md)。
|