# 外围子系统合成样本

仅供演示，所有数据标为 `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-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)。专业重分析不在本次已确认的样板反馈范围内；生成器不会自动导入或修订成果。