# 外围样板服务

该 FastAPI 子应用提供历史监测回放、固定合成数据，以及 synthetic 测试工单和测试数据的版本化 CRUD。生产环境挂载在主 Server 的 `/peripheral`，随 `next-backend` 单容器发布；源码仍可独立启动用于本地隔离调试。管理入口位于供水工作台“外围样板”。它不控制设备，也不修改正式业务资产。

浏览器通过 `TJWATER_PERIPHERAL_SAMPLE_API_BASE_URL` 连接样板服务。服务复用主系统的 Bearer 身份和 `X-Project-Id`，读取需要 `simulation.view`，写入需要 `simulation.run`。

生产环境不需要为外围服务新增域名。前端设置
`TJWATER_PERIPHERAL_SAMPLE_API_BASE_URL=/peripheral`，在现有前端 NPMplus Proxy Host 中增加以下
Custom Location：

| 配置项 | 值 |
| --- | --- |
| Location | `/peripheral`，不添加末尾斜杠 |
| Scheme | 与 `next-api.waternetwork.cn` 现有 Proxy Host 的上游一致 |
| Forward Hostname / IP | 复制 `next-api.waternetwork.cn` 现有 Proxy Host 的 Forward Hostname / IP，不追加路径或末尾斜杠 |
| Forward Port | 复制 `next-api.waternetwork.cn` 现有 Proxy Host 的 Forward Port |
| Forward Path | 留空 |

不要根据容器内的 `8000` 端口猜测宿主机映射；生产发布端口以
`next-api.waternetwork.cn` 的现有 NPMplus 上游配置为准。该配置保留 `/peripheral` 前缀，因此浏览器请求
`/peripheral/api/sample/v1/context` 时，主 Server 收到相同路径并交给挂载的子应用。不要在
Forward Hostname 后追加 `/api/sample/v1`。本机开发和预览模式也将 `/peripheral` 代理到
`TJWATER_SERVER_API_BASE_URL`，默认是 `http://127.0.0.1:8000`。

外围 API 支持已授权项目切换。每次请求先由主系统验证项目成员身份和权限，再从 Metadata DB 解析该项目的 `biz_data` 路由；历史观测另解析 `iot_data` 路由。逻辑项目代码、业务物理库名和时序物理库名可以不同，连接沿用各自完整 DSN。路由缺失返回 `503 PROJECT_STORAGE_NOT_CONFIGURED`，不会回退到其他项目数据库。未配置存储表的项目仍需单独完成结构部署；API 不自动创建表或复制演示数据。

`PERIPHERAL_SAMPLE_PROJECT_CODE` 和 `PERIPHERAL_SAMPLE_DB_NAME` 仅供显式运行的种子、导出等脚本选择默认库，不再限制 HTTP 请求。工单变更在当前项目已有 `workbench.domain_event_log` 时于同一事务发布事件；未配置事件表时不自动建表，实时同步仍需项目工作台事件结构。

后台同步器和调查 worker 支持 `OPERATIONAL_WORKER_PROJECT_IDS`（项目 UUID，逗号分隔），每个项目维护独立凭据、事件游标和会话状态；未配置时继续使用原 `OPERATIONAL_WORKER_PROJECT_ID`。多项目配置只选择运行范围，不新增项目成员权限，服务身份必须已获各项目授权。修改后需重启两个常驻进程，参见 [工作进程配置](operational-task-workers.md)。

主要接口包括：

- `/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，因此浏览器关闭后流程仍可继续。