feat: mount peripheral API in main server

README.md

@@ -72,7 +72,7 @@ conda activate server
 
 ## 常用命令
 
-外围接入样板是独立进程，复用 PostgreSQL，不自动建表；启动、授权边界和契约见 [外围样板说明](docs/peripheral-sample.md)。
+外围接入样板作为 `/peripheral` 子应用随主 API 进程启动，复用 PostgreSQL 且不自动建表；授权边界和契约见 [外围样板说明](docs/peripheral-sample.md)。
 外围样板提供 synthetic 测试工单和测试数据的版本化 CRUD；工单经同步器投影为 `workbench.operational_tasks` 中的外围来源任务。固定演示时窗和造数方式见 [合成样本说明](docs/peripheral-generated-data.md)，运行态读取边界见 [工作台运行态说明](docs/workbench-runtime.md)。这些数据不代表现场事实，也不会触发设备控制。
 
 ```bash

app/main.py

@@ -14,6 +14,7 @@ from app.infra.db.metadb.database import close_metadata_engine
 from app.infra.db.timescaledb.sync_pool import close_all_timescale_pools
 from app.native.wndb.core.connection import close_all_project_pools
 from app.core.config import settings
+from samples.peripheral.api import create_app as create_peripheral_app
 
 # 导入审计中间件
 from app.infra.audit.middleware import AuditMiddleware
@@ -80,6 +81,7 @@ install_problem_details_handlers(app)
 from app.api.v1.endpoints.mcp_queries import router as mcp_context_router
 app.state.mcp_runtime = mcp_runtime
 app.include_router(mcp_context_router, prefix="/api/v1")
+app.mount("/peripheral", create_peripheral_app(), name="peripheral")
 # Legacy routers without version prefix
 # app.include_router(api_router)
 

docs/operational-task-workers.md

@@ -72,8 +72,8 @@ OPERATIONAL_WORKER_AGENT_URL=http://127.0.0.1:8787
 OPERATIONAL_WORKER_TOKEN_URL=https://<identity-host>/realms/<realm>/protocol/openid-connect/token
 OPERATIONAL_WORKER_CLIENT_ID=<dedicated-service-client>
 OPERATIONAL_WORKER_CLIENT_SECRET=<inject-securely>
-OPERATIONAL_ACTION_PERIPHERAL_URL=http://127.0.0.1:8011
-OPERATIONAL_DATA_PERIPHERAL_URL=http://127.0.0.1:8011
+OPERATIONAL_ACTION_PERIPHERAL_URL=http://127.0.0.1:8000/peripheral
+OPERATIONAL_DATA_PERIPHERAL_URL=http://127.0.0.1:8000/peripheral
 ```
 
 选择 OAuth 时不要同时配置 `OPERATIONAL_WORKER_BEARER`，否则固定 Bearer 优先。不要配置设备命令网关进行本次合成联调。

docs/peripheral-sample.md

@@ -1,6 +1,6 @@
 # 外围样板服务
 
-该独立 FastAPI 服务提供历史监测回放、固定合成数据，以及 synthetic 测试工单和测试数据的版本化 CRUD。管理入口位于供水工作台“外围样板”。它不控制设备，也不修改正式业务资产。
+该 FastAPI 子应用提供历史监测回放、固定合成数据，以及 synthetic 测试工单和测试数据的版本化 CRUD。生产环境挂载在主 Server 的 `/peripheral`，随 `next-backend` 单容器发布；源码仍可独立启动用于本地隔离调试。管理入口位于供水工作台“外围样板”。它不控制设备，也不修改正式业务资产。
 
 浏览器通过 `TJWATER_PERIPHERAL_SAMPLE_API_BASE_URL` 连接样板服务。服务复用主系统的 Bearer 身份和 `X-Project-Id`，读取需要 `simulation.view`，写入需要 `simulation.run`。
 
@@ -10,17 +10,16 @@ Custom Location：
 
 | 配置项 | 值 |
 | --- | --- |
-| Location | `/peripheral/`，必须保留末尾斜杠 |
+| Location | `/peripheral`，不添加末尾斜杠 |
 | Scheme | `http` |
-| Forward Hostname / IP | NPMplus 能访问的应用机地址，通常与现有前端上游相同 |
-| Forward Port | `8011` |
+| Forward Hostname / IP | `192.168.1.114`，不追加路径或末尾斜杠 |
+| Forward Port | `8000` |
 | Forward Path | 留空 |
 
-NPMplus 会去掉 `/peripheral/` 前缀，因此浏览器请求
-`/peripheral/api/sample/v1/context` 时，上游收到 `/api/sample/v1/context`。不要在 Forward
-Hostname 后再追加 `/api/sample/v1`。外围服务应只向 NPMplus 所在网络开放 `8011`，不要直接开放公网。
-本机开发和预览模式也提供等价的 `/peripheral` 代理，可通过
-`TJWATER_PERIPHERAL_SAMPLE_UPSTREAM` 覆盖默认上游 `http://127.0.0.1:8011`。
+该配置保留 `/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 不自动创建表或复制演示数据。
 

scripts/provision_operational_worker_identity.py

@@ -309,8 +309,8 @@ def _update_worker_environment(
         "OPERATIONAL_WORKER_SERVER_URL": "http://127.0.0.1:8000",
         "OPERATIONAL_WORKER_AGENT_URL": "http://127.0.0.1:18787",
         "OPERATIONAL_WORKER_TOKEN_REFRESH_SECONDS": "300",
-        "OPERATIONAL_ACTION_PERIPHERAL_URL": "http://127.0.0.1:8011",
-        "OPERATIONAL_DATA_PERIPHERAL_URL": "http://127.0.0.1:8011",
+        "OPERATIONAL_ACTION_PERIPHERAL_URL": "http://127.0.0.1:8000/peripheral",
+        "OPERATIONAL_DATA_PERIPHERAL_URL": "http://127.0.0.1:8000/peripheral",
         "OPERATIONAL_DATA_SERVER_URL": "http://127.0.0.1:8000",
     }
     for key, value in values.items():

tests/api/test_peripheral_mount.py

@@ -0,0 +1,23 @@
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+def test_main_server_mounts_peripheral_health_endpoint():
+    response = TestClient(app).get("/peripheral/health")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "service": "peripheral-sample",
+        "origin": "synthetic",
+        "storage": "postgresql",
+        "status": "up",
+        "storage_verified": False,
+    }
+
+
+def test_mounted_peripheral_api_preserves_its_authentication_boundary():
+    response = TestClient(app).get("/peripheral/api/sample/v1/context")
+
+    assert response.status_code == 401
+    assert response.json()["code"] == "AUTHENTICATION_REQUIRED"