22 lines
1.6 KiB
Markdown
22 lines
1.6 KiB
Markdown
# 外围样板服务
|
|
|
|
该独立 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-` 前缀。
|
|
|
|
## 水质投诉 Agent 演示
|
|
|
|
`POST /api/sample/v1/work-orders` 可创建 `work_order_type=water_quality_complaint` 的合成投诉事件，或 `work_order_type=burst_report` 的合成爆管上报。二者由外围同步器转换为统一事件调查任务，再由后端 worker 可靠交给 Agent；浏览器不再负责启动调查。事件和执行请求 ID 均由稳定业务身份确定，回执恢复或重试不会重复创建任务。
|
|
|
|
样板服务只保存工单，不直接调用 Agent。`scripts/sync_peripheral_work_orders.py` 使用受认证的后台身份同步外部版本并创建调查任务，`scripts/run_operational_worker.py` 再将持久化的待执行任务交给 Agent，因此浏览器关闭后流程仍可继续。
|