# 运转系统 API

> 参考来源：`docs/superpowers/specs/2026-05-18-operation-system-engine-design.md`

## 健康检查

- `GET /api/health` — 返回应用名称和状态

## 日志

- `GET /api/logs` — 拉取日志内容
- `GET /api/logs/stream` — SSE 增量推送

## 文档

- `GET /api/docs/api-md` — 获取本 API 文档
- `GET /api/docs/readme-md` — 获取 README

## 平台基础接口

复用 `plc_platform_core::handler::platform_routes`：源 / 设备 / 点位 / 标签 / 页面。

## 工位配置（§9.1.1）

- `GET /api/station` — 列出工位（可选 `?line_code=`）
- `POST /api/station` — 新建工位
- `GET /api/station/{id}` — 工位详情含信号绑定
- `PUT /api/station/{id}` — 更新工位
- `DELETE /api/station/{id}`
- `POST /api/station/{id}/signal` — Upsert 工位信号绑定
- `DELETE /api/station/{id}/signal/{role}`

## 流程段配置（§9.1.1）

- `GET /api/segment`（可选 `?line_code=`）
- `POST /api/segment`
- `GET /api/segment/{id}`
- `GET /api/segment/{id}/detail` — 包含 step / interlock / resource
- `PUT /api/segment/{id}`
- `DELETE /api/segment/{id}`
- `GET /api/segment/{id}/step`
- `POST /api/segment/{id}/step`
- `PUT /api/segment/{id}/step/{step_no}`
- `DELETE /api/segment/{id}/step/{step_no}`
- `GET /api/segment/{id}/interlock`
- `POST /api/segment/{id}/interlock`
- `DELETE /api/segment/{id}/interlock/{interlock_id}`
- `GET /api/segment/{id}/resource`
- `PUT /api/segment/{id}/resource` — 用新的 `resource_keys` 数组整体替换

## 段运行控制（§9.2）

- `POST /api/control/segment/{id}/start-auto`
- `POST /api/control/segment/{id}/stop-auto`
- `POST /api/control/segment/{id}/ack-fault`
- `POST /api/control/segment/{id}/reset` — 仅在 Blocked / Faulted / ManualAckRequired 状态允许
- `POST /api/control/segment/batch-start-auto`
- `POST /api/control/segment/batch-stop-auto`

## 运行态查询（§9.3）

- `GET /api/runtime/overview` — 所有段 + 资源占用快照
- `GET /api/runtime/segment/{id}` — 单段配置 + runtime
- `GET /api/runtime/station/{id}` — 工位信号 + 最新点位监控值
- `GET /api/event` — 事件时间线，参数：
  - `event_type` — 精确匹配，例如 `ops.segment.fault_locked`
  - `event_type_prefix` — 前缀匹配，例如 `ops.` 拉取全部 ops 事件
  - `subject_type` / `subject_id` — 设计文档 §4.2.8 归因字段，可按段 / 工位 / 设备过滤
  - 分页参数 `page` / `page_size`

## WebSocket（§8.2）

- `GET /ws/public` — 推送
  - `point_new_value`（核心）
  - `event_created`（核心）
  - `app_event`：`{ app: "operation-system", event_type: "segment_runtime_changed", data: SegmentRuntime }`

## 环境变量

- `SIMULATE_PLC=1` — 调试模式，引擎发出命令后通过模拟器把确认信号写回监控缓存，使段流程可在无 PLC 现场时端到端运行。
- `OPS_SEED_TEMPLATES=1` — 应用启动时自动写入默认骨架：
  - 6 个干燥窑段（infeed / step / outfeed × 1 号 / 2 号）
  - 6 个公共段（前端码车 / 前端放车 / 前端摆渡 / 窑尾摆渡 / 卸砖 / 回车），并写入对应共享资源 key（`transfer_front` / `transfer_tail` / `unload_position` / `return_line` / `robot_arm`）
  - 关联工位（含 5 个公共工位）
  - 仅插入缺失的记录，不覆盖已有配置。设备与工位信号绑定仍需通过 CRUD API 完成。