plc_control/docs/api-ops.md

运转系统 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 完成。