4.7 KiB
外围系统接入服务
该 FastAPI 子应用接入真实业务工单，提供版本化 CRUD、处理反馈和事件调查入口，同时保留独立的历史监测回放与演练数据接口。生产环境挂载在主 Server 的 /peripheral，随 next-backend 单容器发布；源码仍可独立启动用于本地隔离调试。管理入口位于供水工作台“外围系统”。
外围工单的 origin 固定为 system_data，前端录入、同步器、任务快照、执行回执和工单查询均使用该来源，不再提供演练来源分支。业务录入代表系统中的上报，不代表投诉内容或故障原因已核实，Agent 仍需查询实际证据。
此次变更不修改表结构；部署时需在每个项目业务库执行 resources/sql/029_peripheral_work_orders_system_data.sql，统一修正源工单、修订记录、任务快照和外围反馈证据。API 路径、配置键中的 sample 为兼容名称，不代表工单是模拟数据。更新需发布 Server、同步器、Agent 与前端对应版本。
浏览器通过 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 | http |
| Forward Hostname / IP | 192.168.1.114，不追加路径或末尾斜杠 |
| Forward Port | 8001 |
| Forward Path | 留空 |
容器内部仍监听 8000，生产发布在宿主机映射为 8001，避免与已有服务冲突。该配置保留 /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。多项目配置只选择运行范围，不新增项目成员权限，服务身份必须已获各项目授权。修改后需重启两个常驻进程，参见 工作进程配置。
主要接口包括：
/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- 前缀。
工单事件调查
POST /api/sample/v1/work-orders 可创建 work_order_type=water_quality_complaint 的水质投诉事件，或 work_order_type=burst_report 的爆管上报，均默认使用业务来源。二者由外围同步器转换为统一事件调查任务，再由后端 worker 可靠交给 Agent；浏览器不再负责启动调查。事件和执行请求 ID 均由稳定业务身份确定，回执恢复或重试不会重复创建任务。普通业务录入无需绑定演练场景码，也不会向 Agent 注入预设监测结果或邻区投诉情况。
外围服务只保存工单，不直接调用 Agent。scripts/sync_peripheral_work_orders.py 使用受认证的后台身份同步外部版本并创建调查任务，scripts/run_operational_worker.py 再将持久化的待执行任务交给 Agent，因此浏览器关闭后流程仍可继续。