feat: add project-scoped operations

docs/peripheral-sample.md

@@ -4,6 +4,30 @@
 
 浏览器通过 `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 | NPMplus 能访问的应用机地址，通常与现有前端上游相同 |
+| Forward Port | `8011` |
+| 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`。
+
+外围 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`