next-tjwater-server/docs/peripheral-sample.md

外围样板服务

该独立 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- 前缀。