5.2 KiB
外围子系统合成样本
仅供演示，所有数据标为 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。
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、计算规范化摘要。已有同编号记录时只允许核对相同摘要，不覆盖；改变种子或生成器应使用新版本/新编号并另行调整读取配置。样本本身永久保存，读取不会重新生成或写入。
经明确授权需要为某个开发项目填充外围样板时，可运行：
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-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 来源、现场反馈或业务审批。 已审核反馈现在可经人工确认导入独立新证据，再另行确认建立人工复核草稿修订。专业重分析不在本次已确认的样板反馈范围内；生成器不会自动导入或修订成果。